Class MultiComboBoxItem

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 MultiComboBoxItem extends CanvasItem
A MultiComboBoxItem is a combo box that allows the user to select multiple options. Each selected option is represented as a button that can be clicked to deselect the option. The relative layout of the buttons to the combo box is specified with the layoutStyle attribute. The buttons will be kept in the order that they were added, with the most recently added button being adjacent to the combo box. MultiComboBoxItem uses the com.smartgwt.client.types.AutoChild pattern to construct the comboBox and the buttons so that they can be easily customized. For example, you can customize the criteria used to fetch by using ComboBoxItem.setPickListFilterCriteriaFunction() with setComboBoxProperties().
See Also:
  • Constructor Details

    • MultiComboBoxItem

      public MultiComboBoxItem()
    • MultiComboBoxItem

      public MultiComboBoxItem(JavaScriptObject jsObj)
    • MultiComboBoxItem

      public MultiComboBoxItem(String name)
    • MultiComboBoxItem

      public MultiComboBoxItem(String name, String title)
  • Method Details

    • getOrCreateRef

      public static MultiComboBoxItem 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)
    • setAddUnknownValues

      public MultiComboBoxItem setAddUnknownValues(Boolean addUnknownValues)
      Similar to ComboBoxItem.addUnknownValues, controls whether additional values can be added to the ComboBox or whether the user must choose from the available values in the picklist only.

      If this setting is changed after the MultiComboBoxItem has been created, the current value of the item is reset to null and all buttons for non-default values (values not in the FormItem.defaultValue array) are removed.

      Parameters:
      addUnknownValues - New addUnknownValues value. Default value is false
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getAddUnknownValues

      public Boolean getAddUnknownValues()
      Similar to ComboBoxItem.addUnknownValues, controls whether additional values can be added to the ComboBox or whether the user must choose from the available values in the picklist only.

      If this setting is changed after the MultiComboBoxItem has been created, the current value of the item is reset to null and all buttons for non-default values (values not in the FormItem.defaultValue array) are removed.

      Returns:
      Current addUnknownValues value. Default value is false
    • setAlwaysExitOnTab

      public MultiComboBoxItem setAlwaysExitOnTab(Boolean alwaysExitOnTab)
      If true, hitting tab always exits the field, and will also add a value to the list of selected values if there is match (and depending on the setting for addUnknownValues).

      If false, if the user has typed in a value and hits tab, focus remains in the field. If there is a match or if addUnknownValues is true, a value will be added. Otherwise, the input cursor remains at the end of the entered value.

      Parameters:
      alwaysExitOnTab - New alwaysExitOnTab value. Default value is true
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getAlwaysExitOnTab

      public Boolean getAlwaysExitOnTab()
      If true, hitting tab always exits the field, and will also add a value to the list of selected values if there is match (and depending on the setting for addUnknownValues).

      If false, if the user has typed in a value and hits tab, focus remains in the field. If there is a match or if addUnknownValues is true, a value will be added. Otherwise, the input cursor remains at the end of the entered value.

      Returns:
      Current alwaysExitOnTab value. Default value is true
    • setAutoFetchData

      public MultiComboBoxItem setAutoFetchData(Boolean autoFetchData)
      Should the MultiComboBoxItem fetch data from the data source immediately or wait until the user first opens the pickList.
      Parameters:
      autoFetchData - New autoFetchData value. Default value is false
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getAutoFetchData

      public Boolean getAutoFetchData()
      Should the MultiComboBoxItem fetch data from the data source immediately or wait until the user first opens the pickList.
      Returns:
      Current autoFetchData value. Default value is false
      See Also:
    • setAutoFitButtons

      public MultiComboBoxItem setAutoFitButtons(Boolean autoFitButtons)
      Specifies whether to autofit the buttons in the MultiComboBoxItem. The default value is true if layoutStyle is "flow", but false for a layoutStyle of "vertical" or "verticalReverse". If the layoutStyle is "horizontal" or "horizontalReverse" then the buttons will autofit regardless of the setting of this property.

      If this method is called after the component has been drawn/initialized: Sets the autoFitButtons property.
      Parameters:
      autoFitButtons - whether to autofit the buttons. Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getAutoFitButtons

      public Boolean getAutoFitButtons()
      Specifies whether to autofit the buttons in the MultiComboBoxItem. The default value is true if layoutStyle is "flow", but false for a layoutStyle of "vertical" or "verticalReverse". If the layoutStyle is "horizontal" or "horizontalReverse" then the buttons will autofit regardless of the setting of this property.
      Returns:
      Current autoFitButtons value. Default value is null
    • setAutoOpenTree

      public MultiComboBoxItem setAutoOpenTree(String autoOpenTree)
      When this item is showing a tree-based picker, which nodes should be opened automatically. Options are:
      • "none" - no nodes are opened automatically
      • "root" - opens the top-level node - in databound tree-pickers, this node is always hidden
      • "all" - when loading data on demand, opens the top-level node and all of it's direct descendants - otherwise, opens all loaded nodes
      Parameters:
      autoOpenTree - New autoOpenTree value. Default value is "none"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getAutoOpenTree

      public String getAutoOpenTree()
      When this item is showing a tree-based picker, which nodes should be opened automatically. Options are:
      • "none" - no nodes are opened automatically
      • "root" - opens the top-level node - in databound tree-pickers, this node is always hidden
      • "all" - when loading data on demand, opens the top-level node and all of it's direct descendants - otherwise, opens all loaded nodes
      Returns:
      Current autoOpenTree value. Default value is "none"
    • getButton

      public IButton getButton()
      Note : This API is non-functional (always returns null) and exists only to make you aware that this MultiAutoChild exists. See Using AutoChildren for details.

      An com.smartgwt.client.types.AutoChild attribute used to create the buttons in the MultiComboBoxItem.

      Returns:
      null
    • getComboBox

      public ComboBoxItem getComboBox()
      An com.smartgwt.client.types.AutoChild attribute to create the combo box in a MultiComboBoxItem.

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

      Returns:
      Current comboBox value. Default value is null
    • setComboBoxWidth

      public MultiComboBoxItem setComboBoxWidth(int comboBoxWidth)
      Specifies the size of the combo box field.

      Note that this attribute only has an effect in "flow", "horizontal", and "horizontalReverse" modes. In the other modes, the combo box is as wide as the overall MultiComboBoxItem.

      Parameters:
      comboBoxWidth - New comboBoxWidth value. Default value is 130
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getComboBoxWidth

      public int getComboBoxWidth()
      Specifies the size of the combo box field.

      Note that this attribute only has an effect in "flow", "horizontal", and "horizontalReverse" modes. In the other modes, the combo box is as wide as the overall MultiComboBoxItem.

      Returns:
      Current comboBoxWidth value. Default value is 130
    • getComboForm

      public DynamicForm getComboForm()
      The DynamicForm holding the comboBox.

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

      Returns:
      Current comboForm value. Default value is null
    • setDataSetType

      public MultiComboBoxItem setDataSetType(String dataSetType)
      Whether to show the picker as a flat list, or a collapsible tree.

      The default value, "list", will use an instance of the pickListConstructor as the picker - "tree" will show an instance of pickTreeConstructor.

      Parameters:
      dataSetType - New dataSetType value. Default value is "list"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getDataSetType

      public String getDataSetType()
      Whether to show the picker as a flat list, or a collapsible tree.

      The default value, "list", will use an instance of the pickListConstructor as the picker - "tree" will show an instance of pickTreeConstructor.

      Returns:
      Current dataSetType value. Default value is "list"
    • setDeselectedButtonStyle

      public MultiComboBoxItem setDeselectedButtonStyle(String deselectedButtonStyle)
      When showDeletions is true, the Button.baseStyle used on buttons for values that have been deleted (also called "deselected buttons").

      If unset, then the baseStyle of deselected buttons is not changed.

      NOTE: Deselected buttons are also disabled, so styling should be provided for the deselectedButtonStyle + "Disabled" style name.

      Parameters:
      deselectedButtonStyle - New deselectedButtonStyle value. Default value is "buttonDeselected"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getDeselectedButtonStyle

      public String getDeselectedButtonStyle()
      When showDeletions is true, the Button.baseStyle used on buttons for values that have been deleted (also called "deselected buttons").

      If unset, then the baseStyle of deselected buttons is not changed.

      NOTE: Deselected buttons are also disabled, so styling should be provided for the deselectedButtonStyle + "Disabled" style name.

      Returns:
      Current deselectedButtonStyle value. Default value is "buttonDeselected"
      See Also:
    • setDisplayField

      public MultiComboBoxItem setDisplayField(String displayField)
      The displayField of the combo box.

      Note : This is an advanced setting

      Overrides:
      setDisplayField in class FormItem
      Parameters:
      displayField - New displayField value. Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getDisplayField

      public String getDisplayField()
      The displayField of the combo box.
      Overrides:
      getDisplayField in class FormItem
      Returns:
      Current displayField value. Default value is null
      See Also:
    • setLayoutStyle

      public MultiComboBoxItem setLayoutStyle(MultiComboBoxLayoutStyle layoutStyle)
      Specifies the layout style of the combo box and the buttons in the MultiComboBoxItem. Available values are "flow" (the default), "horizontal", "horizontalReverse", "vertical", and "verticalReverse".
      • "flow":  The buttons appear to the left of the combo box. When there is no more room, the combo box and/or buttons flow onto a new line. The buttons autoFit by default.
      • "horizontal":  The combo box appears on right and buttons are horizontally stacked directly left of it. The buttons must autofit.
      • "horizontalReverse":  Like "horizontal" but the combo box appears on the left. The buttons must autofit.
      • "vertical":  The combo box appears on top and buttons are stacked beneath it. Buttons do not autofit by default.
      • "verticalReverse":  Like "vertical" but the combo box appears at bottom. The buttons do not autofit by default.
      Parameters:
      layoutStyle - the new layout style. Default value is "flow"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getLayoutStyle

      public MultiComboBoxLayoutStyle getLayoutStyle()
      Specifies the layout style of the combo box and the buttons in the MultiComboBoxItem. Available values are "flow" (the default), "horizontal", "horizontalReverse", "vertical", and "verticalReverse".
      • "flow":  The buttons appear to the left of the combo box. When there is no more room, the combo box and/or buttons flow onto a new line. The buttons autoFit by default.
      • "horizontal":  The combo box appears on right and buttons are horizontally stacked directly left of it. The buttons must autofit.
      • "horizontalReverse":  Like "horizontal" but the combo box appears on the left. The buttons must autofit.
      • "vertical":  The combo box appears on top and buttons are stacked beneath it. Buttons do not autofit by default.
      • "verticalReverse":  Like "vertical" but the combo box appears at bottom. The buttons do not autofit by default.
      Returns:
      Current layoutStyle value. Default value is "flow"
    • setOptionOperationId

      public MultiComboBoxItem setOptionOperationId(String optionOperationId)
      If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option dataSource to pick up display value mapping.
      Overrides:
      setOptionOperationId in class FormItem
      Parameters:
      optionOperationId - New optionOperationId value. Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getOptionOperationId

      public String getOptionOperationId()
      If this item has a specified optionDataSource, this attribute may be set to specify an explicit DSRequest.operationId when performing a fetch against the option dataSource to pick up display value mapping.
      Overrides:
      getOptionOperationId in class FormItem
      Returns:
      Current optionOperationId value. Default value is null
      See Also:
    • setPendingButtonStyle

      public MultiComboBoxItem setPendingButtonStyle(String pendingButtonStyle)
      When showPending is true, the Button.baseStyle used on buttons that are in the "Pending" visual state.

      If unset, then the baseStyle of pending buttons is not changed.

      Parameters:
      pendingButtonStyle - New pendingButtonStyle value. Default value is "buttonPending"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getPendingButtonStyle

      public String getPendingButtonStyle()
      When showPending is true, the Button.baseStyle used on buttons that are in the "Pending" visual state.

      If unset, then the baseStyle of pending buttons is not changed.

      Returns:
      Current pendingButtonStyle value. Default value is "buttonPending"
      See Also:
    • setPickListConstructor

      public MultiComboBoxItem setPickListConstructor(String pickListConstructor)
      The Class to use when creating a picker of type "list" for a FormItem. Must be a subclass of the builtin default, PickListMenu.
      Parameters:
      pickListConstructor - New pickListConstructor value. Default value is "PickListMenu"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getPickListConstructor

      public String getPickListConstructor()
      The Class to use when creating a picker of type "list" for a FormItem. Must be a subclass of the builtin default, PickListMenu.
      Returns:
      Current pickListConstructor value. Default value is "PickListMenu"
      See Also:
    • setPickTreeConstructor

      public MultiComboBoxItem setPickTreeConstructor(String pickTreeConstructor)
      The Class to use when creating a picker of type "tree" for a FormItem. Must be a subclass of the builtin default, PickTreeMenu.
      Parameters:
      pickTreeConstructor - New pickTreeConstructor value. Default value is "PickTreeMenu"
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getPickTreeConstructor

      public String getPickTreeConstructor()
      The Class to use when creating a picker of type "tree" for a FormItem. Must be a subclass of the builtin default, PickTreeMenu.
      Returns:
      Current pickTreeConstructor value. Default value is "PickTreeMenu"
      See Also:
    • setRootNodeId

      public MultiComboBoxItem setRootNodeId(String rootNodeId)
      When this item is showing a tree-based picker, this is the id of the record to use as the root node.
      Parameters:
      rootNodeId - New rootNodeId value. Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getRootNodeId

      public String getRootNodeId()
      When this item is showing a tree-based picker, this is the id of the record to use as the root node.
      Returns:
      Current rootNodeId value. Default value is null
    • setRootNodeId

      public MultiComboBoxItem setRootNodeId(Integer rootNodeId)
      When this item is showing a tree-based picker, this is the id of the record to use as the root node.
      Parameters:
      rootNodeId - New rootNodeId value. Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getRootNodeIdAsInt

      public Integer getRootNodeIdAsInt()
      When this item is showing a tree-based picker, this is the id of the record to use as the root node.
      Returns:
      Current rootNodeId value. Default value is null
    • setShouldSaveValue

      public MultiComboBoxItem setShouldSaveValue(Boolean shouldSaveValue)
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via FormItem.defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Overrides:
      setShouldSaveValue in class CanvasItem
      Parameters:
      shouldSaveValue - New shouldSaveValue value. Default value is true
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getShouldSaveValue

      public Boolean getShouldSaveValue()
      Should this item's value be saved in the form's values and hence returned from form.getValues()?

      shouldSaveValue:false is used to mark formItems which do not correspond to the underlying data model and should not save a value into the form's values. Example includes visual separators, password re-type fields, or checkboxes used to show/hide other form items.

      A shouldSaveValue:false item should be given a value either via FormItem.defaultValue or by calling form.setValue(item, value) or formItem.setValue(value). Providing a value via form.values or form.setValues() will automatically switch the item to shouldSaveValue:true.

      Note that

      • if an item is shouldSaveValue true, but has no name, a warning is logged, and shouldSaveValue will be set to false.
      Overrides:
      getShouldSaveValue in class CanvasItem
      Returns:
      Current shouldSaveValue value. Default value is true
    • setUseInsertionOrder

      public MultiComboBoxItem setUseInsertionOrder(Boolean useInsertionOrder)
      Specifies whether to arrange the buttons of the MultiComboBoxItem in the order that they were selected (the default), or to sort the buttons by displayField.
      Parameters:
      useInsertionOrder - New useInsertionOrder value. Default value is true
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
    • getUseInsertionOrder

      public Boolean getUseInsertionOrder()
      Specifies whether to arrange the buttons of the MultiComboBoxItem in the order that they were selected (the default), or to sort the buttons by displayField.
      Returns:
      Current useInsertionOrder value. Default value is true
    • setValueField

      public MultiComboBoxItem setValueField(String valueField)
      The valueField of the combo box.
      Overrides:
      setValueField in class FormItem
      Parameters:
      valueField - New valueField value. Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getValueField

      public String getValueField()
      The valueField of the combo box.
      Overrides:
      getValueField in class FormItem
      Returns:
      Current valueField value. Default value is null
      See Also:
    • getValueLayout

      public Layout getValueLayout()
      Note : This API is non-functional (always returns null) and exists only to make you aware that this MultiAutoChild exists. See Using AutoChildren for details.

      The layout used to arrange the comboForm and the buttons representing the values of the MultiComboBoxItem. Note that the constructor cannot be changed (setting a valueLayoutConstructor has no effect) because the exact layout class used depends on the current layout style.

      Returns:
      null
    • pendingStatusChanged

      public boolean pendingStatusChanged(DynamicForm form, FormItem item, boolean pendingStatus, Object newValue, Object value)
      Notification method called when showPending is enabled and this MultiComboBoxItem should either clear or show its pending visual state.

      The default behavior is that the titleStyle and cellStyle are updated to include/exclude the "Pending" suffix. In addition, when displayed in the pending state and a pendingButtonStyle is set, then:

      • If useInsertionOrder is false, buttons for any new values will have their baseStyle set to pendingButtonStyle; otherwise
      • (useInsertionOrder is true) buttons for values will have their baseStyle set to pendingButtonStyle if either the value is new or it is in a different place within the value array.
      Returning false will cancel this default behavior.
      Parameters:
      form - the managing DynamicForm instance.
      item - the form item itself (also available as "this").
      pendingStatus - true if the item should show its pending visual state; false otherwise.
      newValue - the current form item value.
      value - the value that would be restored by a call to DynamicForm.resetValues().
      Returns:
      false to cancel the default behavior.
    • showValue

      public void showValue(Object displayValue, Object dataValue, DynamicForm form, CanvasItem item)
      This method will be called whenever this FormItem's value is being set via a programmatic call to e.g: DynamicForm.setValues() or FormItem.setValue() and may be overridden by CanvasItems intended to support displaying data values to update the embedded Canvas to reflect the value passed in.

      The value of a MultiComboBoxItem to the form is an array of valueField values corresponding to the selected combo box options.

      Parameters:
      displayValue - new display value for the item. This is the value after applying any custom formatter or valueMap
      dataValue - underlying data value for the item
      form - the dynamicForm in which this item is contained
      item - the live form item instance
    • setDefaultProperties

      public static void setDefaultProperties(MultiComboBoxItem multiComboBoxItemProperties)
      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:
      multiComboBoxItemProperties - properties that should be used as new defaults when instances of this class are created
      See Also:
    • getButtonDefaults

      public IButton getButtonDefaults()
      Default properties to be used in creating each IButton.
      Returns:
      IButton
    • setButtonProperties

      public void setButtonProperties(IButton buttonProperties)
      Properties to be used in creating each option button.

      Note : This is an advanced setting

      Parameters:
      buttonProperties - buttonProperties
    • getButtonProperties

      public IButton getButtonProperties()
      Properties to be used in creating each option button.
      Returns:
      IButton
    • getComboBoxDefaults

      public ComboBoxItem getComboBoxDefaults()
      Default properties for the ComboBoxItem in a MultiComboBoxItem.
      Returns:
      ComboBoxItem
    • setComboBoxProperties

      public void setComboBoxProperties(ComboBoxItem comboBoxProperties)
      Properties to be used in creating a ComboBoxItem.

      Note : This is an advanced setting

      Parameters:
      comboBoxProperties - comboBoxProperties Default value is null
    • getComboBoxProperties

      public ComboBoxItem getComboBoxProperties()
      Properties to be used in creating a ComboBoxItem.
      Returns:
      ComboBoxItem
    • setOptionDataSource

      public MultiComboBoxItem setOptionDataSource(DataSource optionDataSource)
      The optionDataSource of the combo box.
      Overrides:
      setOptionDataSource in class FormItem
      Parameters:
      optionDataSource - optionDataSource Default value is null
      Returns:
      MultiComboBoxItem instance, for chaining setter calls
      See Also:
    • getOptionDataSource

      public DataSource getOptionDataSource()
      The optionDataSource of the combo box.
      Overrides:
      getOptionDataSource in class FormItem
      Returns:
      DataSource
      See Also:
    • getValues

      public final String[] getValues()
    • setValues

      public void setValues(Object... values)