wxControlWithItems(3)

📦

version 29.0.6 · 3 versions

🎀 wxControlWithItems — the Erlang module definition 💅

okay bestie so this is wxControlWithItems(3) from the Erlang module definitions, and we're gonna get you so comfy with it, no cap ✨

✨ NAME ✨

wxControlWithItems — this is a convenience class that derives from both wxControl and wxItemContainer, and heads up: it's not implemented in wx. 🙈

🌸 DESCRIPTION 🌸

so like. it's the ✨blueprint✨ that some wxWidgets controls are built on top of — specifically wxChoice and wxListBox. main character energy, honestly.

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

wxControl
wxWindow
wxEvtHandler

wxWidgets docs: wxControlWithItems — iykyk 🫶

🦋 DATA TYPES 🦋

wxControlWithItems() :: wx:wx_object().

periodt. that's the whole type. 💅

💖 FUNCTIONS 💖

append/2

append(This, Item) -> integer()
                when
                    This :: wxControlWithItems(),
                    Item :: unicode:chardata().

Appends Item into the control. 🍓

Return: the return value is the index of the newly inserted item. ⚠️ but plot twist — this may be different from the last one if the control is sorted (e.g. it has wxLB_SORT or wxCB_SORT style). so don't just assume it lands at the end, bestie.

append/3

append(This, Item, ClientData) -> integer()
                when
                    This :: wxControlWithItems(),
                    Item :: unicode:chardata(),
                    ClientData :: term().

Appends Item into the control. same vibe, now with ClientData. 💜

Return: the return value is the index of the newly inserted item. ⚠️ again heads up — this may be different from the last one if the control is sorted (e.g. it has wxLB_SORT or wxCB_SORT style).

appendStrings/2

appendStrings(This, Items) -> integer()
                       when
                           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. bestie, batch it. it's giving efficiency.

appendStrings/3

appendStrings(This, Items, ClientsData) -> integer()
                       when
                           This :: wxControlWithItems(),
                           Items :: [unicode:chardata()],
                           ClientsData :: [term()].

Appends several items at once into the control. same slay, but with ClientsData. 🌈

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

clear/1

clear(This) -> ok when This :: wxControlWithItems().

Removes all items from the control. the ultimate spring cleaning 🧚

clear/1 also deletes the client data of the existing items if it is owned by the control.

delete/2

delete(This, N) -> ok
                when This :: wxControlWithItems(), N :: integer().

Deletes an item from the control.

The client data associated with the item will also be deleted if it is owned by the control. 🚨 note that 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. do not do this. it's not cute.

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/3

findString(This, String, [Option]) -> integer()
                    when
                        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.

getClientData/2

getClientData(This, N) -> term()
                       when This :: wxControlWithItems(), N :: integer().

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

It's 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.

getCount/1

getCount(This) -> integer() when This :: wxControlWithItems().

Returns the number of items in the control. 💯

See: isEmpty/1

getSelection/1

getSelection(This) -> integer() when 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/2

getString(This, N) -> unicode:charlist()
                   when 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.

getStringSelection/1

getStringSelection(This) -> unicode:charlist()
                            when This :: wxControlWithItems().

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

See: getSelection/1

insert/3

insert(This, Item, Pos) -> integer()
                when
                    This :: wxControlWithItems(),
                    Item :: unicode:chardata(),
                    Pos :: integer().

Inserts Item into the control. 🌸

Return: the return value is the index of the newly inserted item. If the insertion failed for some reason, -1 is returned. 😭

insert/4

insert(This, Item, Pos, ClientData) -> integer()
                when
                    This :: wxControlWithItems(),
                    Item :: unicode:chardata(),
                    Pos :: integer(),
                    ClientData :: term().

Inserts Item into the control. same but with ClientData 💜

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

insertStrings/3

insertStrings(This, Items, Pos) -> integer()
                       when
                           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.

Return: the return value is the index of the last inserted item. If the insertion failed for some reason, -1 is returned. (yes bestie, last — not first. read it twice.)

insertStrings/4

insertStrings(This, Items, Pos, ClientsData) -> integer()
                       when
                           This :: wxControlWithItems(),
                           Items :: [unicode:chardata()],
                           Pos :: integer(),
                           ClientsData :: [term()].

Inserts several items at once into the control. now with ClientsData 🌈

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

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

isEmpty/1

isEmpty(This) -> boolean() when This :: wxControlWithItems().

Returns true if the control is empty or false if it has some items. vibe check on your list 📋

See: getCount/1

select/2

select(This, N) -> ok
                when 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 literally the same function in a different outfit 💅

setClientData/3

setClientData(This, N, Data) -> ok
                       when
                           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).

🚨 Note that it is an error to call this function if any untyped client data pointers had been associated with the control items before. don't mix them, bestie, it will Not Go Well.

setSelection/2

setSelection(This, N) -> ok
                      when 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. silent but deadly ✨

See:

setString/3
setStringSelection/2

setString/3

setString(This, N, String) -> ok
                   when
                       This :: wxControlWithItems(),
                       N :: integer(),
                       String :: unicode:chardata().

Sets the label for the given item. ✏️

setStringSelection/2

setStringSelection(This, String) -> boolean()
                            when
                                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.

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. so yes bestie, the "wrong-case" one wins. that's just how it is. 😭

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

and that's the whole page, angel 💖 you now officially know wxControlWithItems better than 90% of the people who use it, fr fr. go forth and populate your list boxes responsibly 🦋✨

— brought to you by Ericsson AB 🌸 wx 2.6 — mwah 💋 slay, bye 👑

📦 where this page comes from

ubuntu stonking: erlang-doc 1:29.0.6+dfsg-1 · Apache-2.0
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms