NAME

Prima::ComboBox - standard combo box widget

SYNOPSIS

use Prima qw(Application ComboBox);

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

run Prima;

DESCRIPTION

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

The combo box is a grouping widget and contains neither painting nor user input code by itself. All such functionality is delegated to the children widgets: input line, list box, and drop button. Prima::ComboBox exports a fixed list of methods and properties from the namespaces of Prima::InputLine and Prima::ListBox. It is possible to tweak the Prima::ComboBox ( using its editClass and listClass create-only properties ) so the input line and list box widgets can be instantiated from other classes. The list of exported names is stored in package variables %listProps, %editProps, and %listDynas. These are also described in the "Exported names" section.

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

API

Properties

autoHeight BOOLEAN

If 1, adjusts the height of the widget automatically when its font changes. Only for styles not equal to cs::Simple.

Default value: 1

buttonClass STRING

Assigns the drop-down button class.

Create-only property.

Default value: Prima::Widget

buttonDelegations ARRAY

Assigns the list of delegated notifications to the drop-down button.

Create-only property.

buttonProfile HASH

Assigns a 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 the input line class.

Create-only property.

Default value: Prima::InputLine

editProfile HASH

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

Create-only property.

editDelegations ARRAY

Assigns the list of delegated notifications to the input line.

Create-only property.

editHeight INTEGER

Selects the height of the input line.

items ARRAY

Proxy of the list widget's items property. See Prima::Lists for details.

listClass STRING

Assigns the list box class.

Create-only property.

Default value: Prima::ListBox

listHeight INTEGER

Selects the height of the list box widget.

Default value: 100

listVisible BOOLEAN

Sets whether the list box is visible or not. Not writable when the style is cs::Simple.

listProfile HASH

Assigns a hash of properties passed to the list box during the creation.

Create-only property.

listDelegations ARRAY

Assigns the list of delegated notifications to the list box.

Create-only property.

literal BOOLEAN

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

Default value: 1

style INTEGER

Selects one of three styles of the combo box:

cs::Simple

The list box is always visible, but the drop-down button is not.

cs::DropDown

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

cs::DropDownList

Same as cs::DropDown but the user is restricted in selection: the input line can only accept user input that is present in the list box. If literal is set to 1, the auto-completion feature is provided.

text STRING

Alias of the input line's text property.

Events

Change

Triggered the 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).

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

	       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::Dialog::ColorDialog, Prima::Dialog::FileDialog, examples/listbox.pl.