Package 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:
  `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
  Description
  `ShuttleItem()`
  `ShuttleItem(JavaScriptObject jsObj)`
  `ShuttleItem(String name)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static void`
  `changeAutoChildDefaults(String autoChildName, Canvas defaults)`
  Changes the defaults for Canvas AutoChildren named `autoChildName`.
  `static void`
  `changeAutoChildDefaults(String autoChildName, FormItem defaults)`
  Changes the defaults for FormItem AutoChildren named `autoChildName`.
  `static void`
  `changePickerIconDefaults(FormItemIcon defaults)`
  `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.
  `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(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`.
  `String`
  `getValueField()`
  The value field for a shuttle item will be applied to the `Shuttle` as `Shuttle.valueField`.
  `int`
  `getWidth()`
  Width of the FormItem.
  `String`
  `getWidthAsString()`
  Width of the FormItem.
  `static void`
  `setDefaultProperties(ShuttleItem shuttleItemProperties)`
  Class level method to set the default properties of this class.
  `ShuttleItem`
  `setDisplayField(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(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(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(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, getDeferActionConversion, getDestroyed, getDisabled, getDisabledHover, getDisableIconsOnReadOnly, getDisplayFieldName, getDisplayValue, getDisplayValue, getEditorTypeConfig, getEditPendingCSSText, getEditProxyConstructor, getEmptyDisplayValue, getEmptyValueIcon, getEndRow, getErrorIconHeight, getErrorIconProperties, getErrorIconSrc, getErrorIconWidth, getErrorMessageWidth, getErrors, getEscapeHTML, getExportFormat, getExtraControlTableCSS, getExtraTextBoxCSS, 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, getReadOnlyControlStyle, getReadOnlyDisplay, getReadOnlyHover, getReadOnlyTextBoxStyle, getReadOnlyWhen, getRect, getRedrawOnChange, getRejectInvalidValueOnChange, getRequired, getRequiredMessage, getRequiredRightTitlePrefix, getRequiredRightTitleSuffix, getRequiredTitlePrefix, getRequiredTitleSuffix, getRequiredWhen, getRightTitlePrefix, getRightTitleSuffix, 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, getTitlePrefix, getTitleStyle, getTitleSuffix, 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, getWrapStaticValue, 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, setDeferActionConversion, 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, setExtraControlTableCSS, setExtraTextBoxCSS, 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, setReadOnlyControlStyle, setReadOnlyDisplay, setReadOnlyHover, setReadOnlyTextBoxStyle, setReadOnlyWhen, setRedrawOnChange, setRejectInvalidValueOnChange, setRequired, setRequiredMessage, setRequiredRightTitlePrefix, setRequiredRightTitleSuffix, setRequiredTitlePrefix, setRequiredTitleSuffix, setRequiredWhen, setRightTitlePrefix, setRightTitleSuffix, 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, setTitlePrefix, setTitleStyle, setTitleSuffix, setTitleVAlign, setTooltip, setTop, setType, setUpdateControlOnOver, setUpdatePickerIconOnOver, setUpdateTextBoxOnOver, setUseAdvancedCriteria, setUseDisabledHintStyleForReadOnly, setUseLocalDisplayFieldValue, setUseObjectFactoryForTypeFallback, setValidateOnChange, setValidateOnExit, setValidators, setValidOperators, setVAlign, setValue, setValue, setValue, setValue, setValue, setValue, setValueByDisplayValue, setValueByDisplayValue, setValueDeselectedCSSText, setValueFormatter, setValueHoverFormatter, setValueIconHeight, setValueIconLeftPadding, setValueIconMapper, setValueIconRightPadding, setValueIcons, setValueIconSize, setValueIconWidth, setValueMap, setValueMap, setVisible, setVisibleWhen, setWarnOnEditorTypeConversion, setWarnOnEditorTypeConversionDefault, setWrapHintText, setWrapStaticValue, setWrapTitle, shouldApplyHeightToTextBox, shouldFetchMissingValue, shouldSaveOnEnter, shouldStopKeyPressBubbling, show, showIcon, showPicker, stopHover, storeValue, updateState, validate, valueClipped`

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

  `getCanExport, getExportTitle, getPrimaryKey, getSortByField, setCanExport, setExportTitle, setPrimaryKey, 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 Details

  - ### ShuttleItem

    public ShuttleItem()

  - ### ShuttleItem

    public ShuttleItem(JavaScriptObject jsObj)

  - ### ShuttleItem

    public ShuttleItem(String name)

- ## Method Details

  - ### getOrCreateRef

    public static ShuttleItem getOrCreateRef(JavaScriptObject jsObj)

  - ### changeAutoChildDefaults

    public static void changeAutoChildDefaults(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(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(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 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 `SpinnerItem`s, 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 `SpinnerItem`s, 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 `SpinnerItem`s, 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 `SpinnerItem`s, 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(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 `SpinnerItem`s, 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 `SpinnerItem`s, 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 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 `SpinnerItem`s, 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 `SpinnerItem`s, 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(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 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(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 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`