Prima::ComboBox(3)

💅 Prima::ComboBox(3)

ok so this page is straight outta the User Contributed Perl Documentation (yes, that's the manual name, we're fancy like that ✨), and it's all about Prima::ComboBox — the standard combo box widget. buckle up bestie, we're going in 🎀

🌸 SYNOPSIS

ok first, the vibe check — here's the whole thing in action:

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;

look at her go 😭💖

🦋 DESCRIPTION

so what even is this? it's a combo box widget — and no cap, it's literally three things glued together: an input line, a list box full of your possible selections, and an eventual drop-down button. she can show up in two whole forms: as a drop-down list that you pop open and hide again, or in a form where the selection list is just always visible. main character energy either way 👑

here's the tea though: the combo box is a grouping widget and contains neither painting nor user input code by itself. all of that functionality is delegated to the children widgets — the input line, the list box, and the drop button. Prima::ComboBox exports a fixed list of methods and properties from the namespaces of Prima::InputLine and Prima::ListBox. and yeah, it's 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 the package variables %listProps, %editProps, and %listDynas. these are also described in the "Exported names" section down below 🫶

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

---

✨ API ✨

💜 Properties

• autoHeight BOOLEAN — if it's 1, the widget adjusts its height automatically when its font changes. only for styles not equal to cs::Simple, bestie. 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 — picks 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 the details, iykyk.
• 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 — lowkey important, don't @ me.
• 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. periodt. 💅
• text STRING — alias of the input line's text property.

🎀 Events

• Change — triggered the value is changed. (yes, that's the wording, we're keeping it exactly fr fr)
• 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). ⚠️ watch out for that one. 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

(and yeah, text really does show up twice in %editProps — that's just how it is, we don't make the rules 🫠)

---

👑 AUTHOR

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

🧚 SEE ALSO

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

---

ok that's the whole page, you're officially a combo box expert now 🎓✨ this was perl v5.42.0, dated 2024-08-20 — and it's the Prima::ComboBox(3) page, so go forth and build something iconic 💖🦋🌸