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

    All Methods Static Methods Instance Methods Concrete Methods
    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, 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, 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, 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 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 `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(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 `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 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 `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(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`