Prima::ComboBox(3)

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.

  Events

Change
    Triggered with ComboBox value is changed.

List events
    ComboBox forwards "SelectItem" and "DrawItem" events from the list box, and these are executed in the List's context (therefore $self there is not ComboBox, but the ComboBox->List). If you use "SelectItem" you probably need "Change" instead.

    See more in Prima::Lists.

  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.