1 /**

     2  * Copyright (c) 2009-2010 Symbian Foundation and/or its subsidiary(-ies).

     3  * All rights reserved.

     4  * This component and the accompanying materials are made available

     5  * under the terms of the License "Eclipse Public License v1.0"

     6  * which accompanies this distribution, and is available

     7  * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8  *

     9  * Initial Contributors:

    10  * Nokia Corporation - initial contribution.

    11  * 

    12  * Contributors:

    13  * 

    14  * Description:

    15  * 

    16  */

    17 

    18 ///////////////////////////////////////////////////////////////////////////////

    19 // The SelectionControl class is an abstract base class for controls that lets

    20 // the user select one or more options from a list of options. Don't use

    21 // SelectionControl directly.

    22 

    23 // Constructor.

    24 function SelectionControl(id, caption, options, multipleSelection, selected) {

    25     if (id != UI_NO_INIT_ID) {

    26         this.init(id, caption, options, multipleSelection, selected);

    27     }

    28 }

    29 

    30 // SelectionControl inherits from Control.

    31 SelectionControl.prototype = new Control(UI_NO_INIT_ID);

    32 

    33 // List of options.

    34 SelectionControl.prototype.options = null;

    35 

    36 // The single selected option in single selection controls

    37 // or list of options in multi selection controls.

    38 SelectionControl.prototype.selected = null;

    39 

    40 // Single or multiple selection.

    41 SelectionControl.prototype.multipleSelection = false;

    42 

    43 // Initializer - called from constructor.

    44 SelectionControl.prototype.init = function(id, caption, options, multipleSelection, selected) {

    45     uiLogger.debug("SelectionControl.init(" + id + ", " + caption + ", " + options + ", " + multipleSelection + ", " + selected + ")");

    46     

    47     // call superclass initializer

    48     Control.prototype.init.call(this, id, caption);

    49     

    50     // set the multiple selection property

    51     this.multipleSelection = multipleSelection;

    52     

    53     // init options and selected (makes copies of the original arrays)

    54     this.options = (options != null) ? options.slice(0) : [];

    55     if (multipleSelection) {

    56         this.selected = (selected == null) ? [] : selected.slice(0);

    57     } else {

    58         this.selected = selected;

    59     }

    60     this.validateSelected();

    61 };

    62 

    63 // Returns true if the control is a multiple selection control; false if single.

    64 SelectionControl.prototype.isMultipleSelection = function() {

    65     return this.multipleSelection;

    66 };

    67 

    68 // Returns true if the specified option is selected; false if not.

    69 SelectionControl.prototype.isSelected = function(option) {

    70     if (this.multipleSelection) {

    71         // multiple selection

    72         // iterate through all selected options and look for the specified option

    73         for (var i = 0; i < this.selected.length; i++) {

    74             if (this.selected[i] == option) {

    75                 return true;

    76             }

    77         }

    78         return false;

    79     } else {

    80         // single selection

    81         return (this.selected == option);

    82     }

    83 };

    84 

    85 // Returns the currently selected option in a single selection control or

    86 // an array of selected options in a multiple selection control. If there are

    87 // no selected options a single selection control returns null and a multiple

    88 // selection control returns an empty array.

    89 SelectionControl.prototype.getSelected = function() {

    90     return this.multipleSelection ? this.selected.slice(0) : this.selected;

    91 };

    92 

    93 // Sets the currently selected options. Pass a single option in a single selection

    94 // control or an array of selected controls in a multiple selection control. To

    95 // deselect all options pass null in a single selection control and an empty array

    96 // in a multiple selection control.

    97 // Override in sublcasses to provide full implementation.

    98 SelectionControl.prototype.setSelected = function(selected) {

    99     this.selected = this.multipleSelection ? selected.slice(0) : selected;

   100     // make sure the selected option or options are legal

   101     this.validateSelected();

   102 };

   103 

   104 // Ensures that the selected option or options exist among the options in this control.

   105 SelectionControl.prototype.validateSelected = function() {

   106     if (this.multipleSelection) {

   107         // multiple selection

   108         // iterate through all selected options and ensure they exist among the options

   109         for (var i = 0; i < this.selected.length; i++) {

   110             // check that the selected option exists among the options

   111             var found = false;

   112             for (var j = 0; j < this.options.length; j++) {

   113                 if (this.options[j] == this.selected[i]) {

   114                     // found - stop looking for this option

   115                     found = true;

   116                     break;

   117                 }

   118             }

   119             // not found - remove this selected element

   120             if (!found) {

   121                 this.selected.splice(i, 1);

   122                 // since we removed an entry we must re-check this position

   123                 i--;

   124             }

   125         }

   126     } else {

   127         // single selection

   128         if (this.selected != null) {

   129             // check that the selected option exists among the options

   130             for (var i = 0; i < this.options.length; i++) {

   131                 if (this.options[i] == this.selected) {

   132                     // found - we're done

   133                     return;

   134                 }

   135             }

   136             // not found - remove the selection

   137             this.selected = null;

   138         }

   139     }

   140 };

   141 

   142 // Returns the options in the control as an array of option objects with

   143 // a value and text property.

   144 SelectionControl.prototype.getOptions = function() {

   145     return this.options;

   146 };

   147 

   148 // Sets the options in the control.

   149 // Override in sublcasses to provide full implementation.

   150 SelectionControl.prototype.setOptions = function(options) {

   151     this.options = options.slice(0);

   152     // make sure the selected option or options are legal

   153     this.validateSelected();

   154 };

   155 

   156 // Returns the option that has the specified value; null if none.

   157 SelectionControl.prototype.getOptionForValue = function(value) {

   158     // iterate through all options and look for a match

   159     for (var i = 0; i < this.options.length; i++) {

   160         if (this.options[i].value == value) {

   161             return this.options[i];

   162         }

   163     }

   164     return null;

   165 };