wxListBox(3)

💖 wxListBox — the Erlang module, but make it cute 💖

okay bestie, come closer. This is wxListBox(3) from the Erlang module definitions, and yes the manual name is right there in the title because we keep it 💯.

---

✨ NAME ✨

wxListBox — a listbox is used to select one or more of a list of strings. that's it, that's the whole vibe 🎀

---

🌸 DESCRIPTION 🌸

So basically: the strings get displayed in a scrolling box, and whichever string(s) you selected are marked in reverse video (iconic highlighting behavior, no notes 💅). A listbox can be single selection — meaning if you pick an item, the previous selection gets yeeted — or multiple selection — meaning clicking an item toggles it on or off independently of all the other selections. choose your fighter 🫶

List box elements are numbered from zero, and while the maximal number of elements is unlimited, it is usually better to use a virtual control, not requiring you to add all the items to it at once — think wxDataViewCtrl (not implemented in wx) or wxListCtrl with wxLC_VIRTUAL style — once more than a few hundred items need to be displayed. why?? because this control is not optimized, neither from a performance nor from a user interface point of view, for large numbers of items. she's cute but she's not built for that many 🥲

not me reminding you: the list box doesn't support control characters other than TAB. periodt.

🦋 Styles 🦋

This class supports the following styles, and yes we're listing every single one:

• wxLB_SINGLE — Single-selection list.
• wxLB_MULTIPLE — Multiple-selection list: the user can toggle multiple items on and off. This is the same as wxLB_EXTENDED in wxGTK2 port.
• wxLB_EXTENDED — Extended-selection list: the user can extend the selection by using SHIFT or CTRL keys together with the cursor movement keys or the mouse.
• wxLB_HSCROLL — Create horizontal scrollbar if contents are too wide (Windows only).
• wxLB_ALWAYS_SB — Always show a vertical scrollbar.
• wxLB_NEEDED_SB — Only create a vertical scrollbar if needed.
• wxLB_NO_SB — Don't create vertical scrollbar (wxMSW and wxGTK only).
• wxLB_SORT — The listbox contents are sorted in alphabetical order. Note that wxLB_SINGLE, wxLB_MULTIPLE and wxLB_EXTENDED styles are mutually exclusive and you can specify at most one of them (single selection is the default). See also overview_windowstyles.

See:

• wxChoice
• wxComboBox
• wxListCtrl
• wxCommandEvent

This class is derived, and can use functions, from:

• wxControlWithItems
• wxControl
• wxWindow
• wxEvtHandler

wxWidgets docs: wxListBox — iykyk 🧚

🔥 Events 🔥

Event types emitted from this class:

• command_listbox_selected
• command_listbox_doubleclicked

---

💜 DATA TYPES 💜

wxListBox() :: wx:wx_object().

look at her. an object. main character energy fr fr 👑

---

⭐ FUNCTIONS ⭐

• create(This, Parent, Id, Pos, Size, Choices, [Option]) -> boolean()

create(This, Parent, Id, Pos, Size, Choices, [Option]) -> boolean()
    when
        This :: wxListBox(),
        Parent :: wxWindow:wxWindow(),
        Id :: integer(),
        Pos :: {X :: integer(), Y :: integer()},
        Size :: {W :: integer(), H :: integer()},
        Choices :: [unicode:chardata()],
        Option :: {style, integer()} | {validator, wx:wx_object()}.

• deselect(This, N) -> ok when This :: wxListBox(), N :: integer().

Deselects an item in the list box.

Remark: this applies to multiple selection listboxes only. don't come for me when it doesn't work on a single-selection one, the manual literally said so 😭

• destroy(This :: wxListBox()) -> ok.

Destroys the object. goodbye bestie, it's giving exit stage left 💀

• getSelections(This) -> Result when

Result :: {Res :: integer(), Selections :: [integer()]},
This :: wxListBox().

Fill an array of ints with the positions of the currently selected items.

Return: the number of selections.

Remark: use this with a multiple selection listbox.

See:

• wxControlWithItems:getSelection/1
• wxControlWithItems:getStringSelection/1
• wxControlWithItems:setSelection/2

• hitTest(This, Point) -> integer() when

This :: wxListBox(),
Point :: {X :: integer(), Y :: integer()}.

Returns the item located at point, or wxNOT_FOUND if there is no item located at point.

It is currently implemented for wxMSW, wxMac and wxGTK2 ports.

Return: item located at point, or wxNOT_FOUND if unimplemented or the item does not exist.

Since: 2.7.0

• hitTest(This, X, Y) -> integer() when

This :: wxListBox(), X :: integer(), Y :: integer().

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. same energy, different signature 🫶

• insertItems(This, Items, Pos) -> ok when

This :: wxListBox(),
Items :: [unicode:chardata()],
Pos :: integer().

Insert the given number of strings before the specified position. slide in, no cap 💅

• isSelected(This, N) -> boolean() when This :: wxListBox(), N :: integer().

Determines whether an item is selected.

Return: true if the given item is selected, false otherwise.

• new() -> wxListBox().

Default constructor. the blank canvas. the pre-glow-up era ✨

• new(Parent, Id, [Option]) -> wxListBox() when

Parent :: wxWindow:wxWindow(),
Id :: integer(),
Option :: {pos, {X :: integer(), Y :: integer()}} |
          {size, {W :: integer(), H :: integer()}} |
          {choices, [unicode:chardata()]} |
          {style, integer()} |
          {validator, wx:wx_object()}.

Constructor, creating and showing a list box.

See the other new/3 constructor; the only difference is that this overload takes a wxArrayString (not implemented in wx) instead of a pointer to an array of wxString (not implemented in wx).

• set(This, Items) -> ok when This :: wxListBox(), Items :: [unicode:chardata()].

Replaces the current control contents with the given items.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items. lowkey a speedrun strats situation 🔥

• setFirstItem(This, N) -> ok when This :: wxListBox(), N :: integer(); (This, String) -> ok when

This :: wxListBox(),
String :: unicode:chardata().

Set the specified item to be the first visible item.

---

⚠️ bestie heads up: wxLB_SINGLE, wxLB_MULTIPLE and wxLB_EXTENDED are mutually exclusive — pick at most one or the vibe check fails. and remember this control is not optimized for huge lists, so go virtual when it gets big. 💖

---

and that's the whole page, you're officially a wxListBox scholar now, I'm so proud 🥹🫶

this lil manual moment was brought to you by Ericsson AB for wx 2.6, dated with the classic wxListBox(3) — mwah 💋 stay slaying, and don't forget to destroy your objects 💜🌈