Package com.orchestranetworks.ui.form.widget

# Interface UIComboBox

All Superinterfaces:
  `UIAtomicWidget`, `UIAtomicWithEnumeration`, `UIWidget`

public interface UIComboBox extends UIAtomicWithEnumeration
Combo box composed of a drop-down list and a text box to filter the list.

Regarding the `drop-down list`, this widget facilitates the selection in the list, especially for large enumerations. Another benefit is its low cost for data transfer between the end-user browser and the application server.

### JavaScript type

The JavaScript type for this widget is an `Object` with three fields: key, label and previewURL. The previewURL is optional and can be `undefined`. This `Object` represents the current selection. The fields key, label and previewURL are all of JavaScript type `String`.

If the selection is empty (that is, the item [not defined] is selected), the value will be `null`.

If an `afterValueChanged action` has been set on this widget, the JavaScript type of the value will be the same.

Since:
  5.3.0
See Also:
  - `UIFormWriter.newComboBox(com.orchestranetworks.schema.Path)`
  - `UIResponseContext.newComboBox(com.orchestranetworks.schema.Path)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `Integer`
  `getPageSize()`
  `String`
  `getViewForAdvancedSelection()`
  Returns the published view that will be used in the combo-box selection of the associated foreign key field.
  `Size`
  `getWidth()`
  `boolean`
  `isAdvancedSelectorDisplayable()`
  `boolean`
  `isCreateButtonDisplayable()`
  `boolean`
  `isPreviewButtonDisplayable()`
  `void`
  `setAdvancedSelectorDisplayable(boolean isDisplayable)`
  Defines whether the advanced selector should be displayed when the underlying node is a foreign key .
  `void`
  `setCreateButtonDisplayable(boolean isDisplayable)`
  Defines whether the create button should be displayed when the underlying node is a foreign key.
  `void`
  `setPageSize(int newPageSize)`
  Sets the number of entries on each page of the drop-down list.
  `void`
  `setPageSize(Integer newPageSize)`
  Sets the number of entries on each page of the drop-down list.
  `void`
  `setPreviewButtonDisplayable(boolean isDisplayable)`
  Defines whether the preview button should be displayed when the underlying node is a foreign key .
  `void`
  `setViewForAdvancedSelection(String aViewPublicationName)`
  Specifies the name of the published view that will be used in the combo-box selection of the associated foreign key field.
  `void`
  `setWidth(Size width)`
  Sets the width of the combo box.

  ### Methods inherited from interface com.orchestranetworks.ui.form.widget.UIAtomicWidget

  `getActionOnAfterValueChanged, isAjaxPrevalidationEnabled, isAjaxValueSynchEnabled, setActionOnAfterValueChanged, setAjaxPrevalidationEnabled, setAjaxValueSynchEnabled`

  ### Methods inherited from interface com.orchestranetworks.ui.form.widget.UIAtomicWithEnumeration

  `getSpecificNomenclature, setSpecificNomenclature`

  ### Methods inherited from interface com.orchestranetworks.ui.form.widget.UIWidget

  `isEditorDisabled, setEditorDisabled`

- ## Method Details

  - ### isCreateButtonDisplayable

    boolean isCreateButtonDisplayable()
    Returns:
      `true` if the create button is required, `false` if the create button must be hidden.
    See Also:
      - `setCreateButtonDisplayable(boolean)`

  - ### setCreateButtonDisplayable

    void setCreateButtonDisplayable(boolean isDisplayable)
    Defines whether the create button should be displayed when the underlying node is a foreign key.

    When the create button is enabled, it may or may not be displayed, depending on the user's permissions for creating a record in the target table.

    The create button can be hidden completely by setting `false`.

    The create button is placed below the list.

    Default value is `true`.

    Parameters:
      `isDisplayable` - `false` to hide the create button, `true` to reset to the default behavior.

  - ### isPreviewButtonDisplayable

    boolean isPreviewButtonDisplayable()
    Returns:
      `true` if the preview button is required, `false` if the preview button must be hidden.
    See Also:
      - `setPreviewButtonDisplayable(boolean)`

  - ### setPreviewButtonDisplayable

    void setPreviewButtonDisplayable(boolean isDisplayable)
    Defines whether the preview button should be displayed when the underlying node is a foreign key .

    When the preview button is enabled, it may or may not be displayed, depending on the user's permissions for reading the record in the target table.

    The preview button can be hidden by setting `false`.

    The preview button is placed on each entry in the list that refers to a table record.

    Default value is `true`.

    Parameters:
      `isDisplayable` - `false` to hide the preview button, `true` to reset to default behavior.

  - ### getPageSize

    Integer getPageSize()
    Returns:
      the page size of list of the combo box, or `null` if it has not been defined.
    See Also:
      - `setPageSize(Integer)`

  - ### setPageSize

    void setPageSize(int newPageSize)
    Sets the number of entries on each page of the drop-down list.
    Parameters:
      `newPageSize` - the number of entries on each page of the list in the combo box, must be greater than zero.
    See Also:
      - `setPageSize(Integer)`

  - ### setPageSize

    void setPageSize(Integer newPageSize)
    Sets the number of entries on each page of the drop-down list.

    When the list is displayed, the elements are not all displayed at once. Subsequent pages are loaded as the user reaches the end of the list.

    If the parameter is `null`, then the component will use its default page size.

    Default value: `null`.

    Parameters:
      `newPageSize` - the size of each page of the list of the combo box, must be either `null` or greater than zero.

  - ### getWidth

    Size getWidth()
    Returns:
      the width of the combo box, or `null` if it has not been defined.
    See Also:
      - `setWidth(Size)`

  - ### setWidth

    void setWidth(Size width)
    Sets the width of the combo box.

    If the width is `null`, it will use the standard width of inputs defined in the Administration section, topic Ergonomics and layout.

    Default value is `null`.

    Parameters:
      `width` - the width to set to the combo box, or `null` to reset to default.

  - ### isAdvancedSelectorDisplayable

    boolean isAdvancedSelectorDisplayable()
    Returns:
      `true` if the advanced selector is required, `false` if the advanced selector must be hidden.
    Since:
      5.6.0
    See Also:
      - `setAdvancedSelectorDisplayable(boolean)`

  - ### setAdvancedSelectorDisplayable

    void setAdvancedSelectorDisplayable(boolean isDisplayable)
    Defines whether the advanced selector should be displayed when the underlying node is a foreign key .

    The advanced selector is placed below the list.

    Default value is `true`.

    Parameters:
      `isDisplayable` - `false` to hide the advanced selector, `true` to reset to the default behavior.
    Since:
      5.6.0

  - ### getViewForAdvancedSelection

    String getViewForAdvancedSelection()
    Returns the published view that will be used in the combo-box selection of the associated foreign key field.
    Since:
      5.8.1
    See Also:
      - `setViewForAdvancedSelection(String)`

  - ### setViewForAdvancedSelection

    void setViewForAdvancedSelection(String aViewPublicationName)
    Specifies the name of the published view that will be used in the combo-box selection of the associated foreign key field. A selection button will be displayed at the bottom right corner of the drop-down list. When defining a foreign key, this feature allows accessing an advanced selection view through the 'Selector' button that opens the advanced selection view, from where sorting and searching options can be used.

    If the associated field is not a foreign key, or if the specified view does not exist in the repository, then the selection button will not be displayed in the combo-box.

    Since:
      5.8.1