selectitem.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */


// ** Limitations when working with a databound pickList. **
// We support databinding the pickList by setting optionDataSource (implemented in the
// PickList interface - not available for NativeSelectItems).
// We currently DO NOT support 
//  - 'isSelectOther' behavior 
//  - 'addUnknownValues' behavior
//  - keyboard navigation while the pickList is not visible
// on select items with databound pickLists.



// Class will not work without the ListGrid
if (isc.ListGrid) {




//>	@class	SelectItem
// FormItem that allows picking between several mutually exclusive options via a select list.
// <P>
// Options may be derived from a <code>dataSource</code> or a <code>valueMap</code>
// <P>
// Note that to select the first option as a default value for the item,
// +link{SelectItem.defaultToFirstOption} may be set.
//
// @implements PickList
// @see PickList.optionDataSource
// @see formItem.valueMap
// @visibility external
// @example selectItem
//<
isc.ClassFactory.defineClass("SelectItem", "FormItem");

// When the developer specifies a form item as type 'select', depending on the form's 
// useNativeSelectItems property, we may give them a SelectItem, or a NativeSelectItem.
// The APIs and defaults for these classes match, but the implementations are completely
// different.
// Define 'select' type property defaults (to be applied to both classes) in a separate
// object to avoid duplication.

isc._SelectItemProperties = {

    // Have native and synthetic selects' text styling match
	textBoxStyle:"selectItemText",
    
    //>	@attr	SelectItem.height		(number : 19 : IRW)
	//  Default height for select items is 19px.
	// @group       appearance
    // @visibility   external
	//<
    height:19,
    width:150,

    // Override the 'dirtyOnKeyDown' property to avoid marking the form item as dirty on every
    // keyDown. We'll handle marking as dirty explicitly when the value should be updated, 
    // without being saved to the form or firing the change handler.
    dirtyOnKeyDown:false,
    // Similarly avoid firing 'updateValue' on every keypress - we will handle when to save the
    // value out.
    changeOnKeypress:false,
    
    // Override redrawOnShowIcon - we can to avoid redrawing the entire form when showing
    // or hiding icons for this item.
    redrawOnShowIcon:false,

    //>	@attr	SelectItem.addUnknownValues		(boolean : true : IRWA)
	// If we're setting the value of a select item and the value isn't a legal value in the
    // valueMap, whether we should allow the value (creating a new option for it) or reject it.
    // <P>
    // Exception: If the value is set to <code>null</code> but there is no null entry in the
    // valueMap for this item, setting <code>addUnknownValues</code> to true will not cause
    // a null option to show up at the top of the select item pickList. Whether an empty 
    // option is shown in the pickList is governed by +link{SelectItem.allowEmptyValue}
    // instead.
    //
    // @visibility external
    // @example formDependentSelects
	//<
    
	addUnknownValues:true,
    
    //> @attr SelectItem.defaultValue (boolean : null : IRW)
    // Static default value for this SelectItem. To default to the first option use
    // +link{SelectItem.defaultToFirstOption} instead.
    // @visibility external
    //<
    
    //> @method SelectItem.defaultDynamicValue() (A)
    // Expression evaluated to determine the +link{SelectItem.defaultValue} when no value is
    // provided for this item. To default to the first option use
    // +link{SelectItem.defaultToFirstOption} instead.
    // @visibility external
    //<
    
    //> @attr SelectItem.defaultToFirstOption (boolean : false : IRW) 
    // Select the first option as the default value for this SelectItem. If options are derived from
    // a dataSource, the first value returned by the server will be used, otherwise the first
    // value in the valueMap. If enabled, this setting overrides +link{SelectItem.defaultValue} and
    // +link{SelectItem.defaultDynamicValue}.
    // @visibility external
    //<
    
    autoSizePickList:true,
    
    // ---------------------------
    // SelectOther is a behavior implemented on select items 
    // This is doc'd as a separate form item type, and can be specified by creating a 
    // form item of type 'selectOther' (or setting the 'isSelectOther' flag on a select item)
    // ---------------------------
    
    
    // isSelectOther - flag to specify this as a special 'selectOther' type item.
    // may be set up by the FormItemFactory when the item is created
    //isSelectOther:false,

    //>	@class	SelectOtherItem
    //
    // FormItem that shows a list of options, plus an "Other..." option that allows them to enter
    // another value.
    //
    // @treeLocation Client Reference/Forms/Form Items
    // @visibility external
    //<
    
    //>	@attr	selectOtherItem.separatorValue		(string : "----" : IRW)
	//			value for the separator between normal items and the Other... value
	//		@group	appearance
	//<
	separatorValue:"----",

    //>	@attr	selectOtherItem.separatorTitle		(string : "--------------------" : IRW)
	//			title for the separator between normal items and the Other... value
	//		@group	appearance
    // @visibility external
	//<
	separatorTitle:"--------------------",

    //>	@attr	selectOtherItem.otherValue		(string : "***other***" : IRW)
	//			value for the Other... item
	//		@group	appearance
	//<
	otherValue:"***other***",

    //>	@attr	selectOtherItem.otherTitle		(string : "Other..." : IRW)
	//			title for the Other... item
	//		@group	appearance
    // @group i18nMessages
    // @visibility external
	//<
	otherTitle:"Other..."
};


// Include the shared select item properties
isc.SelectItem.addProperties(isc._SelectItemProperties);

// The following properties apply only to SelectItems (not NativeSelectItems)
isc.SelectItem.addProperties({
    
    
    //> @attr selectItem.showPickerIcon (boolean : true : [IRW])
    // Should we show a special 'picker' icon for this form item. Picker icons are customizeable
    // via +link{SelectItem.pickerIconProperties}. By default they will be rendered inside the 
    // Form Item's "control box" area, and will call +link{SelectItem.showPicker()} when clicked.
    //
    // @visibility external
    //<
    showPickerIcon:true,
    
    // override emptyDisplayValue to show a nonbreaking space so styling works correctly
    emptyDisplayValue:"&nbsp;",
    
    //>@method SelectItem.showPicker()
    // @include FormItem.showPicker()
    // @visibility external
    //<
    
    //>@attr SelectItem.textBoxStyle (FormItemBaseStyle : "selectItemText", [IRA])
    // @include FormItem.textBoxStyle
    // @visibility external
    // @group appearance
    //<
    // This is applied to the visible, selected value in the select item.
    

    //>@attr SelectItem.controlStyle (FormItemBaseStyle : "selectItemControl", [IRA])
    // @include FormItem.controlStyle
    // @group appearance
    // @visibility external
    //<
    controlStyle:"selectItemControl",
    
    //>@attr SelectItem.pickerIconStyle  (FormItemBaseStyle : "selectItemPickerIcon", [IRA])
    // @include FormItem.pickerIconStyle
    // @see SelectItem.controlStyle
    // @visibility external
    // @group appearance
    //<
    pickerIconStyle:"selectItemPickerIcon",
       
        

    // Select items can accept focus
    
    canFocus:true,
    
    //>@attr SelectItem.showFocused    (boolean : true, [IRWA])
    // @include FormItem.showFocused
    // @visibility external
    //<
    showFocused:true,
    
    //> @attr SelectItem.pickerIconWidth (number : null : [IRWA])
    // If +link{selectItem.showPickerIcon} is true for this item, this property governs the
    // size of the picker icon. If unset picker icon will be sized as a square to fit in the
    // avaliable height for the icon.
    // @group pickerIcon
    // @visibility external
    //<
        
    //> @attr SelectItem.pickerIconHeight (number : null : [IRWA])
    // If +link{selectItem.showPickerIcon} is true for this item, this property governs the
    // size of the picker icon. If unset picker icon will be sized as a square to fit in the
    // avaliable height for the icon.
    // @group pickerIcon
    // @visibility external
    //<
    
    //>@attr SelectItem.pickerIconSrc  (SCImgURL : "[SKIN]/DynamicForm/SelectItem_PickButton_icon.gif" : [IRWA])
    // If +link{selectItem.showPickerIcon} is true for this item, this property governs the
    // src of the picker icon image to be displayed.
    // @group pickerIcon    
    // @visibility external
    //<
    pickerIconSrc:"[SKIN]/DynamicForm/SelectItem_PickButton_icon.gif",
    
    // Override pickerIconDefaults
    // Don't make this pickerIcon independantly focusable - we only want the user to focus
    // once on the form item
    // Marked 'internal' - we don't want this property overridden - very likely to break
    // the selectItem functionality.
    pickerIconDefaults : {
        
        //imgOnly:true
        tabIndex:-1,
        click:function () {}
    },
    
    //>@attr SelectItem.pickerIconProperties (object : {...} :[IRA])
    // If +link{selectItem.showPickerIcon} is true for this item, this block of properties will
    // be applied to the pickerIcon. Allows for advanced customization of this icon.
    // @visibility external
    // @group pickerIcon
    //<

    // Clip the content.
    
    clipValue:true,
    
    // -----------------------
    // Deprecated:

    //>@attr SelectItem.hiliteOnFocus   (boolean : true : [IRWA])
    // Should this SelectItem show a hilite when it recieves keyboard focus?
    // @visibility external
    // @deprecated As of SmartClient version 5.5, use +link{SelectItem.showFocused} instead.
    //<
    
    //>@attr    SelectItem.hiliteColor (string : "#316AC5": IRWA)
    // Background color to apply to the select item's selected value when the SelectItem 
    // recieves focus, if <code>hiliteOnFocus</code> is true.
    // @visibility external
    // @deprecated As of SmartClient version 5.5, if +link{SelectItem.showFocused} is true,
    //  styling will be updated for this form item on focus. The hiliting effect can therefore
    //  be achieved via +link{SelectItem.textBoxStyle} and +link{SelectItem.controlStyle} 
    //  instead.
    //<
    
    //>@attr    SelectItem.hiliteTextColor (string : "white": IRWA)
    // Text color to apply to the select item's selected value when the SelectItem 
    // recieves focus, if <code>hiliteOnFocus</code> is true.
    // @visibility external
    // @deprecated As of SmartClient version 5.5, if +link{SelectItem.showFocused} is true,
    //  styling will be updated for this form item on focus. The hiliting effect can therefore
    //  be achieved via +link{SelectItem.textBoxStyle} and +link{SelectItem.controlStyle} 
    //  instead.
    //<

    //>@attr    SelectItem.pickButtonWidth  (number : null : IRWA)
    // How large should the pick button be rendered?
    // @visibility external
    // @deprecated As of SmartClient version 5.5, pickButtonWidth has been deprecated in 
    //  favor of +link{SelectItem.pickerIconWidth}.
    //<
    
    //>@attr    SelectItem.pickButtonHeight  (number : null : IRWA)
    // How large should the pick button be rendered?
    //
    // @visibility external    
    // @deprecated As of SmartClient version 5.5, pickButtonHeight has been deprecated in 
    //  favor of +link{SelectItem.pickerIconHeight}.
    //<
    
    //>@attr    SelectItem.pickButtonSrc  (string : null : IRWA)
    // Source for image to show for the pick button
    // @visibility external    
    // @deprecated As of SmartClient version 5.5, pickButtonSrc has been deprecated in 
    //  favor of +link{SelectItem.pickerIconSrc}.