wxListBox(3erl)

🌈 NAME 🌈

wxListBox — literally the functions for the wxListBox class, bestie. This is the Erlang module definition page (3erl), and yes we're getting into it 💅

---

✨ DESCRIPTION ✨

Okay so picture this: a listbox is used to select one or more of a list of strings. That's the whole vibe 🎀

The strings are displayed in a scrolling box, with the selected string(s) marked in reverse video (iconic). A listbox can be single selection (if an item is selected, the previous selection is removed — one at a time, periodt) or multiple selection (clicking an item toggles the item on or off independently of other selections — chaos mode, love that for us).

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 — one that doesn't require you to add all the items to it at once — such as wxDataViewCtrl (not implemented in wx) or wxListCtrl with wxLC_VIRTUAL style, once more than a few hundreds items need to be displayed. Why? Because this control is not optimized, neither from performance nor from user interface point of view, for large number of items. Ngl, she's not built for that 💀

Notice that the list box doesn't support control characters other than TAB. That's the rule, no cap.

🦋 Styles 🦋

This class supports the following styles:

(...and then it just doesn't list any 😭 the manpage said "the following styles:" and dipped. Fr fr, that's what the source says — no styles listed here, so don't come for me.)

---

See: wxEditableListBox (not implemented in wx), wxChoice, wxComboBox, wxListCtrl, wxCommandEvent

This class is derived (and can use functions) from: wxControlWithItems wxControl wxWindow wxEvtHandler — it's giving main character with a whole ancestry 🌸

wxWidgets docs: wxListBox

---

🔥 EVENTS 🔥

Event types emitted from this class:

• command_listbox_selected
• command_listbox_doubleclicked

(that doubleclick one is lowkey the best one, iykyk)

---

💜 DATA TYPES 💜

wxListBox() = wx:wx_object()

---

👑 EXPORTS 👑

new() -> wxListBox()

Default constructor. The no-thoughts-just-vibes one ✨

new(Parent, Id) -> wxListBox()

Types:

Parent = wxWindow:wxWindow()
Id = integer()

new(Parent, Id, Options :: [Option]) -> wxListBox()

Types:

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). Same energy, different argument situation.

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

Destructor, destroying the list box. She's done, she's leaving, bye 💅

create(This, Parent, Id, Pos, Size, Choices) -> boolean()

Types:

This = wxListBox()
Parent = wxWindow:wxWindow()
Id = integer()
Pos = {X :: integer(), Y :: integer()}
Size = {W :: integer(), H :: integer()}
Choices = [unicode:chardata()]

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

Types:

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

Types:

This = wxListBox()
N = integer()

Deselects an item in the list box.

Remark: This applies to multiple selection listboxes only. Single-selection girlies, this one's not for you 🙈

getSelections(This) -> Result

Types:

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

(correction, verbatim from the source: Selections :: [integer] — okay moving on)

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

insertItems(This, Items, Pos) -> ok

Types:

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

Insert the given number of strings before the specified position. Sneaking them in, we love a strategic insert 🌸

isSelected(This, N) -> boolean()

Types:

This = wxListBox()
N = integer()

Determines whether an item is selected.

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

set(This, Items) -> ok

Types:

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. Performance queen behavior 💅✨

hitTest(This, Point) -> integer()

Types:

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()

Types:

This = wxListBox()
X = 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 function, different little outfit 🎀

setFirstItem(This, N) -> ok

setFirstItem(This, String) -> ok

Types:

This = wxListBox()
String = unicode:chardata()

Set the specified item to be the first visible item. Scroll queen, making sure the right thing is up top 👑

---

That's the whole page, bestie — every flag, every type, every remark, nothing skipped. Go build something cute with it 🦋

Shoutout to the wxWidgets team for writing this one, from wx 2.2.2.1 — mwah 💖