---
name: "Prima::ComboBox"
section: "3"
platform: "linux"
package: "libprima-perl"
version: "1.28-1.3+b3"
release: "Debian 8 (Jessie)"
platforms: ["linux"]
url: "https://new.carta.tech/Prima::ComboBox"
---

# Prima::ComboBox(3)

standard combo box widget

## NAME

Prima::ComboBox - standard combo box widget

## SYNOPSIS

```
        use Prima::ComboBox;
        my $combo = Prima::ComboBox-> create( style => cs::DropDown, items => [ 1 .. 10 ]);
        $combo-> style( cs::DropDownList );
        print $combo-> text;
```

## DESCRIPTION

Provides a combo box widget which consists of an input line, list box of possible selections and eventual drop-down button. The combo box can be either in form  with a drop-down selection list, that is shown by the command of the user, or in form when the selection list is always visible.

The combo box is a grouping widget, and contains neither painting nor user-input code. All such functionality is delegated into the children widgets: input line, list box and button. `"Prima::ComboBox"` exports a fixed list of methods and properties from namespaces of Prima::InputLine and Prima::ListBox. Since, however, it is possible to tweak the `"Prima::ComboBox"` ( using its editClass and listClass create-only properties ) so the input line and list box would be other classes, it is not necessarily that all default functionality would work. The list of exported names is stored in package variables `%listProps`, `%editProps` and `%listDynas`. These also described in "Exported names" section.

The module defines `"cs::"` package for the constants used by style property.

## API

### Properties

- buttonClass STRING

  Assigns a drop-down button class.

  Create-only property.

  Default value: `"Prima::Widget"`

- buttonDelegations ARRAY

  Assigns a drop-down button list of delegated notifications.

  Create-only property.

- buttonProfile HASH

  Assigns hash of properties, passed to the drop-down button during the creation.

  Create-only property.

- caseSensitive BOOLEAN

  Selects whether the user input is case-sensitive or not, when a value is picked from the selection list.

  Default value: 0

- editClass STRING

  Assigns an input line class.

  Create-only property.

  Default value: `"Prima::InputLine"`

- editProfile HASH

  Assigns hash of properties, passed to the input line during the creation.

  Create-only property.

- editDelegations ARRAY

  Assigns an input line list of delegated notifications.

  Create-only property.

- editHeight INTEGER

  Selects height of an input line.

- items ARRAY

  Mapped onto the list widget's `"items"` property. See Prima::Lists for details.

- listClass STRING

  Assigns a listbox class.

  Create-only property.

  Default value: `"Prima::ListBox"`

- listHeight INTEGER

  Selects height of the listbox widget.

  Default value: 100

- listVisible BOOLEAN

  Sets whether the listbox is visible or not. Not writable when style is `"cs::Simple"`.

- listProfile HASH

  Assigns hash of properties, passed to the listbox during the creation.

  Create-only property.

- listDelegations ARRAY

  Assigns a selection listbox list of delegated notifications.

  Create-only property.

- literal BOOLEAN

  Selects whether the combo box user input routine assume that  the listbox contains literal strings, that can be fetched via `"get_item_text"` ( see Prima::Lists ). As an example when this property is set to 0 is `"Prima::ColorComboBox"` from Prima::ComboBox package.

  Default value: 1

- style INTEGER

  Selected one of three styles:

  - cs::Simple

    The listbox is always visible, and the drop-down button is not.

  - cs::DropDown

    The listbox is not visible, but the drop-down button is. When the use presses the drop-down button, the listbox is shown; when the list-box is defocused, it gets hidden.

  - cs::DropDownList

    Same as `"cs::DropDown"`, but the user is restricted in the selection:  the input line can only accept user input that is contained in listbox. If literal set to 1, the auto completion feature is provided.

- text STRING

  Mapped onto the edit widget's `"text"` property.

### Exported names

- %editProps

  ```
          alignment      autoScroll  text         text
          charOffset     maxLen      insertMode   firstChar
          selection      selStart    selEnd       writeOnly
          copy           cut         delete       paste
          wordDelimiters readOnly    passwordChar focus
          select_all
  ```

- %listProps

  ```
          autoHeight     focusedItem    hScroll
          integralHeight items          itemHeight
          topItem        vScroll        gridColor
          multiColumn    offset
  ```

- %listDynas

  ```
          onDrawItem
          onSelectItem
  ```

## AUTHOR

Dmitry Karasik, \<dmitry@karasik.eu.org\>.

## SEE ALSO

Prima, Prima::InputLine, Prima::Lists, Prima::ColorDialog, Prima::FileDialog, *examples/listbox.pl*.