com.smartgwt.client.widgets.form.fields

Class ShuttleItem

java.lang.Object

com.smartgwt.client.core.JsObject

com.smartgwt.client.core.DataClass

com.smartgwt.client.core.RefDataClass

com.smartgwt.client.data.Field

com.smartgwt.client.widgets.form.fields.FormItem

com.smartgwt.client.widgets.form.fields.CanvasItem

com.smartgwt.client.widgets.form.fields.ShuttleItem

All Implemented Interfaces:

com.google.gwt.event.shared.HasHandlers, HasBlurHandlers, HasCanEditChangedHandlers, HasChangedHandlers, HasChangeHandlers, HasClickHandlers, HasDoubleClickHandlers, HasEditorEnterHandlers, HasEditorExitHandlers, HasFocusHandlers, HasIconClickHandlers, HasIconKeyPressHandlers, HasItemHoverHandlers, HasKeyDownHandlers, HasKeyPressHandlers, HasKeyUpHandlers, HasPendingStatusChangedHandlers, HasPickerIconClickHandlers, HasReadOnlyDisplayChangedHandlers, HasShowContextMenuHandlers, HasShowValueHandlers, HasTitleClickHandlers, HasTitleDoubleClickHandlers, HasTitleHoverHandlers, HasValueHoverHandlers, HasValueIconClickHandlers

public class ShuttleItem
extends CanvasItem

Shuttle-based form item for choosing values from a list of options.

Options for the Shuttle should be derived from an optionDataSource.

Nested Class Summary

Nested classes/interfaces inherited from class com.smartgwt.client.widgets.form.fields.FormItem

FormItem.CustomStateGetter, FormItem.StateCustomizer

Field Summary

Fields inherited from class com.smartgwt.client.widgets.form.fields.FormItem

configOnly, scClassName, warnOnEditorTypeConversion, warnOnEditorTypeConversionDefault

Fields inherited from class com.smartgwt.client.core.RefDataClass

id

Fields inherited from class com.smartgwt.client.core.DataClass

factoryCreated, factoryProperties

Fields inherited from class com.smartgwt.client.core.JsObject

jsObj

Constructor Summary

Constructors

Constructor and Description
ShuttleItem()
ShuttleItem(com.google.gwt.core.client.JavaScriptObject jsObj)
ShuttleItem(java.lang.String name)

Method Summary

Modifier and Type	Method and Description
static void	changeAutoChildDefaults(java.lang.String autoChildName, Canvas defaults) Changes the defaults for Canvas AutoChildren named autoChildName.
static void	changeAutoChildDefaults(java.lang.String autoChildName, FormItem defaults) Changes the defaults for FormItem AutoChildren named autoChildName.
static void	changePickerIconDefaults(FormItemIcon defaults)
java.lang.String	getDisplayField() If set, this item will display a value from another field to the user instead of showing the underlying data value for the field name.
int	getHeight() Height of the FormItem.
java.lang.String	getHeightAsString() Height of the FormItem.
DataSource	getOptionDataSource() The optionDataSource for a shuttle item will be applied to the Shuttle as Shuttle.dataSource.
static ShuttleItem	getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)
Shuttle	getShuttle() The ShuttleItem generates a Shuttle com.smartgwt.client.types.AutoChild as its canvas.
ListGridField[]	getShuttleFields() Which Shuttle.fields should be displayed in the Shuttle.
java.lang.String	getValueField() The value field for a shuttle item will be applied to the Shuttle as Shuttle.valueField.
int	getWidth() Width of the FormItem.
java.lang.String	getWidthAsString() Width of the FormItem.
static void	setDefaultProperties(ShuttleItem shuttleItemProperties) Class level method to set the default properties of this class.
ShuttleItem	setDisplayField(java.lang.String displayField) If set, this item will display a value from another field to the user instead of showing the underlying data value for the field name.
ShuttleItem	setHeight(int height) Height of the FormItem.
ShuttleItem	setHeight(java.lang.String height) Height of the FormItem.
ShuttleItem	setOptionDataSource(DataSource optionDataSource) The optionDataSource for a shuttle item will be applied to the Shuttle as Shuttle.dataSource.
ShuttleItem	setShuttleFields(ListGridField... shuttleFields) Which Shuttle.fields should be displayed in the Shuttle.
ShuttleItem	setValueField(java.lang.String valueField) The value field for a shuttle item will be applied to the Shuttle as Shuttle.valueField.
ShuttleItem	setWidth(int width) Width of the FormItem.
ShuttleItem	setWidth(java.lang.String width) Width of the FormItem.

Methods inherited from class com.smartgwt.client.widgets.form.fields.CanvasItem

addCanEditChangedHandler, addReadOnlyDisplayChangedHandler, addShowValueHandler, createCanvas, getApplyPromptToCanvas, getAutoDestroy, getCanvas, getEditCriteriaInInnerForm, getMaxHeight, getMinHeight, getMultiple, getOverflow, getPrompt, getShouldSaveValue, hasAdvancedCriteria, isFocused, setApplyPromptToCanvas, setAutoDestroy, setCanEditCriterionPredicate, setCanvas, setCriterionGetter, setCriterionSetter, setDefaultProperties, setEditCriteriaInInnerForm, setMaxHeight, setMinHeight, setMultiple, setOverflow, setPrompt, setShouldDisableCanvasCustomizer, setShouldSaveValue, setupCanvasConstructor, storeValue, storeValue, storeValue, updateCanvasTabPosition

Methods inherited from class com.smartgwt.client.widgets.form.fields.FormItem

_getValue, addBlurHandler, addChangedHandler, addChangeHandler, addClickHandler, addDoubleClickHandler, addEditorEnterHandler, addEditorExitHandler, addFocusHandler, addIcon, addIcon, addIconClickHandler, addIconKeyPressHandler, addItemHoverHandler, addKeyDownHandler, addKeyPressHandler, addKeyUpHandler, addPendingStatusChangedHandler, addPickerIconClickHandler, addShowContextMenuHandler, addTitleClickHandler, addTitleDoubleClickHandler, addTitleHoverHandler, addValueHoverHandler, addValueIconClickHandler, applyFormula, asSGWTComponent, blurItem, canEditCriterion, checkFormItemType, clearErrors, clearValue, disable, disableIcon, enable, enableIcon, error, error, errorIfNotCreated, focusAfterItem, focusInItem, getAccessKey, getAlign, getAllowExpressions, getAlwaysFetchMissingValues, getAlwaysShowControlBox, getApplyAlignToText, getApplyHeightToTextBox, getAriaRole, getAttribute, getAttributeAsBoolean, getAttributeAsBoolean, getAttributeAsDate, getAttributeAsDouble, getAttributeAsFloat, getAttributeAsInt, getAttributeAsJavaScriptObject, getAttributeAsObject, getAttributeAsString, getAutoComplete, getAutoCompleteKeywords, getBrowserInputType, getBrowserSpellCheck, getCanEdit, getCanEditOpaqueValues, getCanFocus, getCanHover, getCanSelectText, getCanTabToIcons, getCanvasAutoChild, getCellHeight, getCellStyle, getChangeOnKeypress, getClassName, getClipStaticValue, getClipTitle, getConfig, getContainerWidget, getControlStyle, getCriteriaField, getCriterion, getCriterion, getCursorPosition, getCustomState, getDataPath, getDateFormatter, getDecimalPad, getDecimalPrecision, getDefaultIconSrc, getDefaultOperator, getDefaultValue, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEditProxyConstructor, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconProperties, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getEscapeHTML, getExportFormat, getFetchMissingValues, getFieldName, getFilterLocally, getForeignDisplayField, getForm, getFormat, getFormItemAutoChild, getFormula, getFullDataPath, getGlobalTabIndex, getGridColNum, getGridRowNum, getHidden, getHint, getHintStyle, getHoverAlign, getHoverDelay, getHoverFocusKey, getHoverHeight, getHoverHeightAsString, getHoverOpacity, getHoverPersist, getHoverStyle, getHoverVAlign, getHoverWidth, getHoverWidthAsString, getIcon, getIconBaseStyle, getIconHeight, getIconHSpace, getIconPageRect, getIconPrompt, getIconRect, getIcons, getIconTabPosition, getIconVAlign, getIconWidth, getID, getImageURLPrefix, getImageURLSuffix, getImplicitSave, getImplicitSaveOnBlur, getInputFormat, getLeft, getLinearColSpan, getLinearColSpanAsString, getLinearEndRow, getLinearEndRowAsString, getLinearStartRow, getLinearStartRowAsString, getLinearWidth, getLinearWidthAsString, getListGrid, getLoadingDisplayValue, getLocateItemBy, getMinHintWidth, getMultipleValueSeparator, getName, getNullOriginalValueText, getOperator, getOptionCriteria, getOptionDataSourceAsString, getOptionFilterContext, getOptionOperationId, getOptionTextMatchStyle, getOriginalValueMessage, getPageLeft, getPageRect, getPageTop, getPaletteDefaults, getPicker, getPickerIcon, getPickerIcon, getPickerIconHeight, getPickerIconName, getPickerIconPrompt, getPickerIconProperties, getPickerIconSrc, getPickerIconStyle, getPickerIconTabPosition, getPickerIconWidth, getPixelHeight, getPixelWidth, getPrintReadOnlyTextBoxStyle, getPrintTextBoxStyle, getPrintTitleStyle, getReadOnlyCanSelectText, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredWhen, getRowSpan, getSaveOnEnter, getScClassName, getSelectedRecord, getSelectOnClick, getSelectOnFocus, getShowClippedTitleOnHover, getShowClippedValueOnHover, getShowDeletions, getShowDisabled, getShowDisabledIconsOnFocus, getShowDisabledPickerIconOnFocus, getShowErrorIcon, getShowErrorIconInline, getShowErrorStyle, getShowErrorText, getShowFocused, getShowFocusedErrorState, getShowFocusedIcons, getShowFocusedPickerIcon, getShowHint, getShowIcons, getShowIconsOnFocus, getShowImageAsURL, getShowOldValueInHover, getShowOver, getShowOverIcons, getShowPending, getShowPickerIcon, getShowPickerIconOnFocus, getShowRTL, getShowTitle, getShowValueIconOnly, getStartRow, getStaticHeight, getStopOnError, getStoreDisplayValues, getSupportsCutPasteEvents, getSuppressValueIcon, getSynchronousValidation, getTabIndex, getTextAlign, getTextBoxStyle, getTextFormula, getTimeFormatter, getTitle, getTitleAlign, getTitleColSpan, getTitleOrientation, getTitleStyle, getTitleVAlign, getTooltip, getTop, getType, getUpdateControlOnOver, getUpdatePickerIconOnOver, getUpdateTextBoxOnOver, getUseAdvancedCriteria, getUseDisabledHintStyleForReadOnly, getUseLocalDisplayFieldValue, getValidateOnChange, getValidateOnExit, getValidOperators, getVAlign, getValue, getValueAsFloat, getValueAsInteger, getValueAsLong, getValueAsRecordList, getValueDeselectedCSSText, getValueFieldName, getValueIconHeight, getValueIconLeftPadding, getValueIconRightPadding, getValueIconSize, getValueIconWidth, getValueMap, getValueMapAsArray, getVisible, getVisibleHeight, getVisibleTitleWidth, getVisibleWhen, getVisibleWidth, getWarnOnEditorTypeConversion, getWarnOnEditorTypeConversionDefault, getWrapHintText, getWrapTitle, handleWarnOnEditorTypeConversion, hasErrors, hide, hideIcon, invalidateDisplayValueCache, isAssignableFrom, isConfigOnly, isCreated, isCutEvent, isDisabled, isDrawn, isInGrid, isPasteEvent, isVisible, linkToInstanceUponCreate, mapDisplayToValue, mapValueToDisplay, mapValueToDisplay, mapValueToDisplay, redraw, redraw, removeIcon, selectedRecordChanged, setAccessKey, setAlign, setAllowExpressions, setAlwaysFetchMissingValues, setAlwaysShowControlBox, setApplyAlignToText, setApplyHeightToTextBox, setAriaRole, setAriaState, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAttribute, setAutoChildConstructor, setAutoChildProperties, setAutoChildProperties, setAutoChildProperties, setAutoChildVisibility, setAutoComplete, setAutoCompleteKeywords, setBrowserInputType, setBrowserSpellCheck, setCanEdit, setCanEditOpaqueValues, setCanFocus, setCanHover, setCanSelectText, setCanTabToIcons, setCellHeight, setCellStyle, setChangeOnKeypress, setClipStaticValue, setClipTitle, setColSpan, setColSpan, setConfigOnly, setControlStyle, setCriteriaField, setCriterion, setCustomStateGetter, setDataPath, setDateFormatter, setDecimalPad, setDecimalPrecision, setDefaultIconSrc, setDefaultOperator, setDefaultProperties, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDefaultValue, setDisabled, setDisabledHover, setDisableIconsOnReadOnly, setDisplayFormat, setDisplayFormat, setEditorProperties, setEditorType, setEditorType, setEditorType, setEditorValueFormatter, setEditorValueParser, setEditPendingCSSText, setEditProxyConstructor, setEmptyDisplayValue, setEmptyValueIcon, setEndRow, setErrorFormatter, setErrorIconHeight, setErrorIconProperties, setErrorIconSrc, setErrorIconWidth, setErrorMessageWidth, setErrorOrientation, setErrors, setErrors, setEscapeHTML, setExportFormat, setFetchMissingValues, setFilterLocally, setForeignDisplayField, setFormat, setFormula, setGlobalTabIndex, setHidden, setHint, setHintStyle, setHoverAlign, setHoverDelay, setHoverFocusKey, setHoverHeight, setHoverHeight, setHoverOpacity, setHoverPersist, setHoverStyle, setHoverVAlign, setHoverWidth, setHoverWidth, setIconBaseStyle, setIconDisabled, setIconHeight, setIconHSpace, setIconPrompt, setIcons, setIconShowOnFocus, setIconVAlign, setIconWidth, setID, setImageURLPrefix, setImageURLSuffix, setImplicitSave, setImplicitSaveOnBlur, setInitHandler, setInputFormat, setInputTransformer, setItemHoverFormatter, setItemTitleHoverFormatter, setItemValueHoverFormatter, setJavaScriptObject, setLeft, setLinearColSpan, setLinearColSpan, setLinearEndRow, setLinearEndRow, setLinearStartRow, setLinearStartRow, setLinearWidth, setLinearWidth, setLoadingDisplayValue, setLocateItemBy, setMinHintWidth, setMultipleValueSeparator, setName, setNullOriginalValueText, setNullProperty, setOperator, setOptionCriteria, setOptionDataSource, setOptionFilterContext, setOptionOperationId, setOptionTextMatchStyle, setOriginalValueMessage, setPickerIconHeight, setPickerIconName, setPickerIconPrompt, setPickerIconProperties, setPickerIconSrc, setPickerIconStyle, setPickerIconWidth, setPrintReadOnlyTextBoxStyle, setPrintTextBoxStyle, setPrintTitleStyle, setProperty, setProperty, setProperty, setProperty, setProperty, setReadOnlyCanSelectText, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredWhen, setRowSpan, setSaveOnEnter, setScClassName, setSelectOnClick, setSelectOnFocus, setShowClippedTitleOnHover, setShowClippedValueOnHover, setShowDeletions, setShowDisabled, setShowDisabledIconsOnFocus, setShowDisabledPickerIconOnFocus, setShowErrorIcon, setShowErrorIconInline, setShowErrorStyle, setShowErrorText, setShowFocused, setShowFocusedErrorState, setShowFocusedIcons, setShowFocusedPickerIcon, setShowHint, setShowIcons, setShowIconsOnFocus, setShowIfCondition, setShowImageAsURL, setShowOldValueInHover, setShowOver, setShowOverIcons, setShowPending, setShowPickerIcon, setShowPickerIconOnFocus, setShowRTL, setShowTitle, setShowValueIconOnly, setStartRow, setStateCustomizer, setStaticHeight, setStopOnError, setStoreDisplayValues, setSupportsCutPasteEvents, setSuppressValueIcon, setSynchronousValidation, setTabIndex, setTextAlign, setTextBoxStyle, setTextFormula, setTimeFormatter, setTitle, setTitleAlign, setTitleColSpan, setTitleHoverFormatter, setTitleOrientation, setTitleStyle, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setUseObjectFactoryForTypeFallback, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueDeselectedCSSText, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWrapHintText, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, updateState, validate, valueClipped

Methods inherited from class com.smartgwt.client.data.Field

getCanExport, getExportTitle, getSortByField, setCanExport, setExportTitle, setSortByField

Methods inherited from class com.smartgwt.client.core.RefDataClass

getRef, getRef, internalSetID

Methods inherited from class com.smartgwt.client.core.DataClass

applyFactoryProperties, doAddHandler, fireEvent, getAttributeAsDoubleArray, getAttributeAsElement, getAttributeAsIntArray, getAttributeAsLong, getAttributeAsMap, getAttributeAsObject, getAttributeAsRecord, getAttributeAsStringArray, getAttributes, getHandlerCount, isFactoryCreated, setAttribute, setAttribute, setAttribute, setAttributeAsJavaObject, setFactoryCreated

Methods inherited from class com.smartgwt.client.core.JsObject

equals, getJsObj, hashCode, setJsObj

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Constructor Detail

ShuttleItem

public ShuttleItem()

ShuttleItem

public ShuttleItem(com.google.gwt.core.client.JavaScriptObject jsObj)

ShuttleItem

public ShuttleItem(java.lang.String name)

Method Detail

getOrCreateRef

public static ShuttleItem getOrCreateRef(com.google.gwt.core.client.JavaScriptObject jsObj)

changeAutoChildDefaults

public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                           Canvas defaults)

Changes the defaults for Canvas AutoChildren named autoChildName.

Parameters:

autoChildName - name of an AutoChild to customize the defaults for.

defaults - Canvas defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.

See Also:

AutoChildUsage

changeAutoChildDefaults

public static void changeAutoChildDefaults(java.lang.String autoChildName,
                                           FormItem defaults)

Changes the defaults for FormItem AutoChildren named autoChildName.

Parameters:

autoChildName - name of an AutoChild to customize the defaults for.

defaults - FormItem defaults to apply. These defaults override any existing properties without destroying or wiping out non-overridden properties. For usage tips on this param, see SGWTProperties.

See Also:

AutoChildUsage

changePickerIconDefaults

public static void changePickerIconDefaults(FormItemIcon defaults)

setDisplayField

public ShuttleItem setDisplayField(java.lang.String displayField)

If set, this item will display a value from another field to the user instead of showing the underlying data value for the field name.

This property is used in two ways:

The item will display the displayField value from the record currently being edited if FormItem.useLocalDisplayFieldValue is true, (or if unset and the conditions outlined in the documentation for that property are met).

If this field has an FormItem.optionDataSource, this property is used by default to identify which value to use as a display value in records from this related dataSource. In this usage the specified displayField must be explicitly defined in the optionDataSource to be used - see getDisplayFieldName() for more on this behavior.
If not using local display values, the display value for this item will be derived by performing a fetch against the option dataSource to find a record where the value field matches this item's value, and use the displayField value from that record.
In addition to this, PickList-based form items that provide a list of possible options such as the SelectItem or ComboBoxItem will show the displayField values to the user by default, allowing them to choose a new data value (see FormItem.valueField) from a list of user-friendly display values.

This essentially allows the specified optionDataSource to be used as a server based valueMap.

If local display values are being used and FormItem.storeDisplayValues is true, selecting a new value will update both the value for this field and the associated display-field value on the record being edited.

Note: Developers may specify the FormItem.foreignDisplayField property in addition to displayField. This is useful for cases where the display field name in the local dataSource differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField for more on this.
If a foreignDisplayField is specified, as with just displayField, if local display values are being used and FormItem.storeDisplayValues is true, when the user chooses a value the associated display-field value on the record being edited will be updated. In this case it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always expected to be set to the equivalent field in the related dataSources.
Developers looking to display some other arbitrary field(s) from the related dataSource during editing should consider using custom PickList.pickListFields instead of setting a foreignDisplayField.

Note that if optionDataSource is set and no valid display field is specified, FormItem.getDisplayFieldName() will return the dataSource title field by default.

If a displayField is specified for a freeform text based item (such as a ComboBoxItem), any user-entered value will be treated as a display value. In this scenario, items will derive the data value for the item from the first record where the displayField value matches the user-entered value. To avoid ambiguity, developers may wish to avoid this usage if display values are not unique.

Overrides:

setDisplayField in class FormItem

Parameters:

displayField - New displayField value. Default value is null

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

FormItem.getDisplayFieldName(), FormItem.invalidateDisplayValueCache(), DataBinding

getDisplayField

public java.lang.String getDisplayField()

If set, this item will display a value from another field to the user instead of showing the underlying data value for the field name.

This property is used in two ways:

The item will display the displayField value from the record currently being edited if FormItem.useLocalDisplayFieldValue is true, (or if unset and the conditions outlined in the documentation for that property are met).

If this field has an FormItem.optionDataSource, this property is used by default to identify which value to use as a display value in records from this related dataSource. In this usage the specified displayField must be explicitly defined in the optionDataSource to be used - see getDisplayFieldName() for more on this behavior.
If not using local display values, the display value for this item will be derived by performing a fetch against the option dataSource to find a record where the value field matches this item's value, and use the displayField value from that record.
In addition to this, PickList-based form items that provide a list of possible options such as the SelectItem or ComboBoxItem will show the displayField values to the user by default, allowing them to choose a new data value (see FormItem.valueField) from a list of user-friendly display values.

This essentially allows the specified optionDataSource to be used as a server based valueMap.

If local display values are being used and FormItem.storeDisplayValues is true, selecting a new value will update both the value for this field and the associated display-field value on the record being edited.

Note: Developers may specify the FormItem.foreignDisplayField property in addition to displayField. This is useful for cases where the display field name in the local dataSource differs from the display field name in the optionDataSource. See the documentation for DataSourceField.foreignDisplayField for more on this.
If a foreignDisplayField is specified, as with just displayField, if local display values are being used and FormItem.storeDisplayValues is true, when the user chooses a value the associated display-field value on the record being edited will be updated. In this case it would be set to the foreignDisplayField value from the related record. This means foreignDisplayField is always expected to be set to the equivalent field in the related dataSources.
Developers looking to display some other arbitrary field(s) from the related dataSource during editing should consider using custom PickList.pickListFields instead of setting a foreignDisplayField.

Note that if optionDataSource is set and no valid display field is specified, FormItem.getDisplayFieldName() will return the dataSource title field by default.

If a displayField is specified for a freeform text based item (such as a ComboBoxItem), any user-entered value will be treated as a display value. In this scenario, items will derive the data value for the item from the first record where the displayField value matches the user-entered value. To avoid ambiguity, developers may wish to avoid this usage if display values are not unique.

Overrides:

getDisplayField in class FormItem

Returns:

Current displayField value. Default value is null

See Also:

FormItem.getDisplayFieldName(), FormItem.invalidateDisplayValueCache(), DataBinding

setHeight

public ShuttleItem setHeight(int height)

Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit FormItem.pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property FormItem.staticHeight is used instead.

Overrides:

setHeight in class CanvasItem

Parameters:

height - New height value. Default value is 400

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

FormItem.setWidth(int), DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType), Form Layout, Filling Example

getHeight

public int getHeight()

Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit FormItem.pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property FormItem.staticHeight is used instead.

Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

Overrides:

getHeight in class CanvasItem

Returns:

Current height value. Default value is 400

See Also:

FormItem.getWidth(), DynamicForm.getItemLayout(), Form Layout, Filling Example

setHeight

public ShuttleItem setHeight(java.lang.String height)

Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit FormItem.pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property FormItem.staticHeight is used instead.

Overrides:

setHeight in class CanvasItem

Parameters:

height - New height value. Default value is 400

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

FormItem.setWidth(int), DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType), Form Layout, Filling Example

getHeightAsString

public java.lang.String getHeightAsString()

Height of the FormItem. Can be either a number indicating a fixed height in pixels, a percentage indicating a percentage of the overall form's height, or "*" indicating take whatever remaining space is available. See the FormLayout overview for details.

If height is specified as a String, getHeight() will return -1. Use getHeightAsString.() in this case.

For form items having a picker icon (e.g. SelectItem, ComboBoxItem) and SpinnerItems, if there is no explicit FormItem.pickerIconHeight, the pickerIcon will be sized to match the available space based on the specified item height.
Note that if spriting is being used, and the image to be displayed in these icons is specified using css properties such as background-image, background-size, changing this value may result in an unexpected appearance as the image will not scale.
Scaleable spriting can be achieved using the SCSpriteConfig format. See the section on spriting in the skinning overview for further information.
Alternatively, the pickerIconStyle could be changed to a custom CSS style name, and in the case of SpinnerItems, the baseStyle and src of the SpinnerItem.increaseIcon and SpinnerItem.decreaseIcon AutoChildren could be customized.

Note that when FormItem is rendered as read-only with readOnlyDisplay as "static" the property FormItem.staticHeight is used instead.

Overrides:

getHeightAsString in class CanvasItem

Returns:

Current height value. Default value is 400

See Also:

FormItem.getWidth(), DynamicForm.getItemLayout(), Form Layout, Filling Example

setOptionDataSource

public ShuttleItem setOptionDataSource(DataSource optionDataSource)

The optionDataSource for a shuttle item will be applied to the Shuttle as Shuttle.dataSource.

If no explicit optionDataSource was specified it may be automatically derived - see FormItem.getOptionDataSource() for details.

Overrides:

setOptionDataSource in class FormItem

Parameters:

optionDataSource - New optionDataSource value. Default value is null

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

FormItem.invalidateDisplayValueCache(), List - Combo Box Example

getOptionDataSource

public DataSource getOptionDataSource()

The optionDataSource for a shuttle item will be applied to the Shuttle as Shuttle.dataSource.

If no explicit optionDataSource was specified it may be automatically derived - see FormItem.getOptionDataSource() for details.

Overrides:

getOptionDataSource in class FormItem

Returns:

Current optionDataSource value. Default value is null

See Also:

FormItem.invalidateDisplayValueCache(), List - Combo Box Example

getShuttle

public Shuttle getShuttle()

The ShuttleItem generates a Shuttle com.smartgwt.client.types.AutoChild as its canvas.

This component is an AutoChild named "shuttle". For an overview of how to use and configure AutoChildren, see Using AutoChildren.

Returns:

Current shuttle value. Default value is null

setShuttleFields

public ShuttleItem setShuttleFields(ListGridField... shuttleFields)

Which Shuttle.fields should be displayed in the Shuttle.

If not specified, the grids within the shuttle will show a single field containing the displayField, if specified otherwise the valueField for the item

Parameters:

shuttleFields - New shuttleFields value. Default value is null

Returns:

ShuttleItem instance, for chaining setter calls

getShuttleFields

public ListGridField[] getShuttleFields()

Which Shuttle.fields should be displayed in the Shuttle.

If not specified, the grids within the shuttle will show a single field containing the displayField, if specified otherwise the valueField for the item

Returns:

Current shuttleFields value. Default value is null

setValueField

public ShuttleItem setValueField(java.lang.String valueField)

The value field for a shuttle item will be applied to the Shuttle as Shuttle.valueField.

If no explicit valueField was specified it may be automatically derived - see FormItem.getValueFieldName() for details.

Overrides:

setValueField in class FormItem

Parameters:

valueField - New valueField value. Default value is null

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

DataBinding

getValueField

public java.lang.String getValueField()

The value field for a shuttle item will be applied to the Shuttle as Shuttle.valueField.

If no explicit valueField was specified it may be automatically derived - see FormItem.getValueFieldName() for details.

Overrides:

getValueField in class FormItem

Returns:

Current valueField value. Default value is null

See Also:

DataBinding

setWidth

public ShuttleItem setWidth(int width)

Width of the FormItem. Can be either a number indicating a fixed width in pixels, or "*" indicating the FormItem fills the space allocated to it's column (or columns, for a column spanning item). You may also use "100%" as a synonym for "*", but other percentages are not supported.

Note that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout for further details.

If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.

See the FormLayout overview for details.

Overrides:

setWidth in class FormItem

Parameters:

width - New width value. Default value is 400

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

FormItem.setLinearWidth(int), FormItem.setHeight(int), DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType), Form Layout, Spanning Example

getWidth

public int getWidth()

Width of the FormItem. Can be either a number indicating a fixed width in pixels, or "*" indicating the FormItem fills the space allocated to it's column (or columns, for a column spanning item). You may also use "100%" as a synonym for "*", but other percentages are not supported.

Note that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout for further details.

If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.

See the FormLayout overview for details.

Note : This method will return -1 if the underlying SmartClient JavaScript attribute value cannot be expressed as a(n) int. In that case, other getters, similarly-named but ending in AsString, AsCanvas, etc., may be provided.

Overrides:

getWidth in class FormItem

Returns:

Current width value. Default value is 400

See Also:

FormItem.getLinearWidth(), FormItem.getHeight(), DynamicForm.getItemLayout(), Form Layout, Spanning Example

setWidth

public ShuttleItem setWidth(java.lang.String width)

Width of the FormItem. Can be either a number indicating a fixed width in pixels, or "*" indicating the FormItem fills the space allocated to it's column (or columns, for a column spanning item). You may also use "100%" as a synonym for "*", but other percentages are not supported.

Note that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout for further details.

If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.

See the FormLayout overview for details.

Overrides:

setWidth in class FormItem

Parameters:

width - New width value. Default value is 400

Returns:

ShuttleItem instance, for chaining setter calls

See Also:

FormItem.setLinearWidth(int), FormItem.setHeight(int), DynamicForm.setItemLayout(com.smartgwt.client.types.FormLayoutType), Form Layout, Spanning Example

getWidthAsString

public java.lang.String getWidthAsString()

Width of the FormItem. Can be either a number indicating a fixed width in pixels, or "*" indicating the FormItem fills the space allocated to it's column (or columns, for a column spanning item). You may also use "100%" as a synonym for "*", but other percentages are not supported.

Note that for "absolute" item layout rather than the default "table" layout, the rules for specifying the width are slightly different. All percent sizes are allowed, but not "*". See DynamicForm.itemLayout for further details.

If width is specified as a String, getWidth() will return -1. Use getWidthAsString.() in this case.

See the FormLayout overview for details.

Overrides:

getWidthAsString in class FormItem

Returns:

Current width value. Default value is 400

See Also:

FormItem.getLinearWidth(), FormItem.getHeight(), DynamicForm.getItemLayout(), Form Layout, Spanning Example

setDefaultProperties

public static void setDefaultProperties(ShuttleItem shuttleItemProperties)

Class level method to set the default properties of this class. If set, then all existing and subsequently created instances of this class will automatically have default properties corresponding to the properties of the class instance passed to this function. This is a powerful feature that eliminates the need for users to create a separate hierarchy of subclasses that only alter the default properties of this class. Can also be used for skinning / styling purposes.

Note: This method is intended for setting default attributes only and will affect all instances of the underlying class (including those automatically generated in JavaScript). This method should not be used to apply standard EventHandlers or override methods for a class - use a custom subclass instead. Calling this method after instances have been created can result in undefined behavior, since it bypasses any setters and a class instance may have already examined a particular property and not be expecting any changes through this route.

Parameters:

shuttleItemProperties - properties that should be used as new defaults when instances of this class are created

See Also:

SGWTProperties