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.

  • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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 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:

    • 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 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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:

    • 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: