wxControlWithItems(3erl)

🎀 NAME 🎀

okay so this is the wxControlWithItems(3erl) manual page, Erlang module definition, and we are gonna make it make sense, bestie. It is Functions for wxControlWithItems class — that's the whole assignment, no cap. 💅

🌈 DESCRIPTION 🌈

This is a convenience class that derives from both wxControl and wxItemContainer (not implemented in wx). It's used as the basis for some wxWidgets controls (wxChoice and wxListBox). iconic behavior, honestly.

See: wxItemContainer (not implemented in wx), wxItemContainerImmutable (not implemented in wx).

This class is derived (and can use functions) from: wxControl, wxWindow, wxEvtHandler. the whole family tree is showing up to the function party.

wxWidgets docs: wxControlWithItems.

🧸 DATA TYPES 🧸

wxControlWithItems()

wxControlWithItems() = wx:wx_object()

That's the type tea: wxControlWithItems() is literally a wx:wx_object(). short, sweet, slaying. ✨

🚀 EXPORTS 🚀

append(This, Item) -> integer()

Types:

This = wxControlWithItems()
Item = unicode:chardata()

Appends item into the control.

Return: the index of the newly inserted item. Heads up, bestie: this may be different from the last one if the control is sorted (e.g. has wxLB_SORT or wxCB_SORT style). 💖

append(This, Item, ClientData) -> integer()

Types:

This = wxControlWithItems()
Item = unicode:chardata()
ClientData = term()

Appends item into the control, now with ClientData attached. fancy.

Return: the index of the newly inserted item. Again, this may be different from the last one if the control is sorted (e.g. has wxLB_SORT or wxCB_SORT style). 🎀

appendStrings(This, Items) -> integer()

Types:

This = wxControlWithItems()
Items = [unicode:chardata()]

Appends several items at once into the control.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items. batch mode ate, fr fr. 🔥

appendStrings(This, Items, ClientsData) -> integer()

Types:

This = wxControlWithItems()
Items = [unicode:chardata()]
ClientsData = [term()]

Appends several items at once into the control, with ClientsData for each one.

Notice that calling this method is usually much faster than appending them one by one if you need to add a lot of items. same speedy vibe, now with client data. 🦋

clear(This) -> ok

Types:

This = wxControlWithItems()

Removes all items from the control.

clear/1 also deletes the client data of the existing items if it is owned by the control. so like, it's not just clearing the vibe, it's cleaning up the client data too. 🧹

delete(This, N) -> ok

Types:

This = wxControlWithItems()
N = integer()

Deletes an item from the control.

The client data associated with the item will be also deleted if it is owned by the control.

Important caveat, bestie: it is an error (signalled by an assert failure in debug builds) to remove an item with the index negative or greater or equal than the number of items in the control.

If there is a currently selected item below the item being deleted, i.e. if getSelection/1 returns a valid index greater than or equal to n, the selection is invalidated when this function is called. However if the selected item appears before the item being deleted, the selection is preserved unchanged.

See: clear/1.

findString(This, String) -> integer()

Types:

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

Types only in the original, no cap. 🍓

findString(This, String, Options :: [Option]) -> integer()

Types:

This = wxControlWithItems()
String = unicode:chardata()
Option = {bCase, boolean()}

Finds an item whose label matches the given string.

Return: the zero-based position of the item, or wxNOT_FOUND if the string was not found. zero-based, because of course. 💅

getClientData(This, N) -> term()

Types:

This = wxControlWithItems()
N = integer()

Returns a pointer to the client data associated with the given item (if any).

Error tea: it is an error to call this function for a control which doesn't have typed client data at all, although it is OK to call it even if the given item doesn't have any client data associated with it (but other items do).

Notice that the returned pointer is still owned by the control and will be deleted by it — use DetachClientObject() (not implemented in wx) if you want to remove the pointer from the control.

Return: a pointer to the client data, or NULL if not present. NULL is giving "not present, bestie." 😭

setClientData(This, N, Data) -> ok

Types:

This = wxControlWithItems()
N = integer()
Data = term()

Associates the given typed client data pointer with the given item: the data object will be deleted when the item is deleted (either explicitly by using delete/2 or implicitly when the control itself is destroyed).

Do not skip this note: it is an error to call this function if any untyped client data pointers had been associated with the control items before. vibe check your client data first, fr fr.

getCount(This) -> integer()

Types:

This = wxControlWithItems()

Returns the number of items in the control.

See: isEmpty/1. count check, then empty check — the duo. ✨

getSelection(This) -> integer()

Types:

This = wxControlWithItems()

Returns the index of the selected item or wxNOT_FOUND if no item is selected.

Return: the position of the current selection.

Remark: this method can be used with single selection list boxes only. You should use wxListBox:getSelections/1 for the list boxes with wxLB_MULTIPLE style.

See: setSelection/2, getStringSelection/1.

getString(This, N) -> unicode:charlist()

Types:

This = wxControlWithItems()
N = integer()

Returns the label of the item with the given index.

Return: the label of the item or an empty string if the position was invalid. invalid position gets the empty-string treatment, respectfully. 🎀

getStringSelection(This) -> unicode:charlist()

Types:

This = wxControlWithItems()

Returns the label of the selected item or an empty string if no item is selected.

See: getSelection/1.

insert(This, Item, Pos) -> integer()

Types:

This = wxControlWithItems()
Item = unicode:chardata()
Pos = integer()

Inserts item into the control at Pos.

Return: the index of the newly inserted item. If the insertion failed for some reason, -1 is returned. yes, -1 is the "it did not slay" signal. 💀

insert(This, Item, Pos, ClientData) -> integer()

Types:

This = wxControlWithItems()
Item = unicode:chardata()
Pos = integer()
ClientData = term()

Inserts item into the control at Pos, with ClientData attached.

Return: the index of the newly inserted item. If the insertion failed for some reason, -1 is returned. same -1 fail vibe. 🦋

insertStrings(This, Items, Pos) -> integer()

Types:

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

Inserts several items at once into the control.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items. bulk insert is the main character here. 👑

Return: the index of the last inserted item. If the insertion failed for some reason, -1 is returned. 🔥

insertStrings(This, Items, Pos, ClientsData) -> integer()

Types:

This = wxControlWithItems()
Items = [unicode:chardata()]
Pos = integer()
ClientsData = [term()]

Inserts several items at once into the control, with ClientsData for each one.

Notice that calling this method is usually much faster than inserting them one by one if you need to insert a lot of items. we love a bulk operation that doesn't waste our time. ✨

Return: the index of the last inserted item. If the insertion failed for some reason, -1 is returned.

isEmpty(This) -> boolean()

Types:

This = wxControlWithItems()

Returns true if the control is empty or false if it has some items.

See: getCount/1. empty or not empty — the simplest vibe check. 🫶

select(This, N) -> ok

Types:

This = wxControlWithItems()
N = integer()

This is the same as setSelection/2 and exists only because it is slightly more natural for controls which support multiple selection. it's giving "same function, different font." 💅

setSelection(This, N) -> ok

Types:

This = wxControlWithItems()
N = integer()

Sets the selection to the given item n or removes the selection entirely if n == wxNOT_FOUND.

Note that this does not cause any command events to be emitted nor does it deselect any other items in the controls which support multiple selections. important: no event spam, no surprise deselects.

See: setString/3, setStringSelection/2.

setString(This, N, String) -> ok

Types:

This = wxControlWithItems()
N = integer()
String = unicode:chardata()

Sets the label for the given item. short and iconic, honestly. 🎀

setStringSelection(This, String) -> boolean()

Types:

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

Selects the item with the specified string in the control.

This method doesn't cause any command events to be emitted.

Case-insensitive caveat, bestie: notice that this method is case-insensitive, i.e. the string is compared with all the elements of the control case-insensitively and the first matching entry is selected, even if it doesn't have exactly the same case as this string and there is an exact match afterwards. the first match ate, even if a later exact match is sitting there like 👀.

Return: true if the specified string has been selected, false if it wasn't found in the control.

---

okay bestie, that's the whole page 💖 huge shoutout to the wxWidgets team and version wx 2.2.2.1. The footer had no date line, so no fake date energy — just pure source/version slay. wxControlWithItems(3erl) out. periodt. 🫶✨