wxComboBox(3)

📦
version 29.0.6 · 3 versions
, in ubuntu stonking

🌸 wxComboBox 🌸

okay so bestie, welcome to wxComboBox(3) — it's an Erlang Module Definition and it's honestly giving main character energy ✨ grab a snack, we're going through every single thing 💅

💖 NAME 💖

wxComboBox — a combobox is like a combination of an edit control and a listbox. two icons, one control, periodt 🫶

✨ DESCRIPTION ✨

So here's the vibe 🌈 it can be displayed as a static list with an editable or read-only text field; or as a drop-down list with a text field; or as a drop-down list without a text field — which one you get depends on the platform and on whether the wxCB_READONLY style is present or not. platform-dependent glow-up, we love that for it 💅

A combobox permits a single selection only. that's it. one. no multi-select shenanigans. and the combobox items are numbered from zero, zero-indexed as always 👑

If you need a customized combobox, go have a look at wxComboCtrl (not implemented in wx), wxOwnerDrawnComboBox (not implemented in wx), wxComboPopup (not implemented in wx) and the ready-to-use wxBitmapComboBox (not implemented in wx). those are the DIY besties 🧚

Please refer to wxTextEntry (not implemented in wx) documentation for the description of methods operating with the text entry part of the combobox, and to wxItemContainer (not implemented in wx) for the methods operating with the list of strings. that's where the lore lives 📚

important tea ☕ Notice that at least under MSW wxComboBox doesn't behave correctly if it contains strings differing in case only — so portable programs should avoid adding such strings to this control. like, "hello" and "Hello" in the same list? chaos. don't do it. no cap 😭

🎀 Styles 🎀

This class supports the following styles:

  • wxCB_SIMPLE — creates a combobox with a permanently displayed list. Windows only.
  • wxCB_DROPDOWN — creates a combobox with a drop-down list. MSW and Motif only.
  • wxCB_READONLY — a combobox with this style behaves like a wxChoice (and may look in the same way as well, although this is platform-dependent), i.e. it allows the user to choose from the list of options but doesn't allow to enter a value not present in the list. read-only queen, she only accepts what's on the menu 🎀
  • wxCB_SORT — sorts the entries in the list alphabetically. a-z, iconic, no notes ✨
  • wxTE_PROCESS_ENTER — the control will generate the event wxEVT_TEXT_ENTER that can be handled by the program. Otherwise — i.e. either if this style not specified at all, or it is used, but there is no event handler for this event, or the event handler called wxEvent:skip/2 to avoid overriding the default handling — pressing Enter key is either processed internally by the control or used to activate the default button of the dialog, if any. 🫶

👀 See: 👀

  • wxListBox
  • wxTextCtrl
  • wxChoice
  • wxCommandEvent

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

  • wxControlWithItems
  • wxControl
  • wxWindow
  • wxEvtHandler

family tree slay 🌳 wxWidgets docs: wxComboBox

🔥 Events 🔥

Event types emitted from this class:

  • command_combobox_selected
  • command_text_updated
  • command_text_enter
  • combobox_dropdown
  • combobox_closeup

🦋 DATA TYPES 🦋

wxComboBox() :: wx:wx_object().

💜 FUNCTIONS 💜

canCopy(This) -> boolean() when This :: wxComboBox().

Returns true if the selection can be copied to the clipboard. 📋✨

canCut(This) -> boolean() when This :: wxComboBox().

Returns true if the selection can be cut to the clipboard. ✂️

canPaste(This) -> boolean() when This :: wxComboBox().

Returns true if the contents of the clipboard can be pasted into the text control.

On some platforms (Motif, GTK) this is an approximation and returns true if the control is editable, false otherwise. so like, it's doing its best 🫠

canRedo(This) -> boolean() when This :: wxComboBox().

Returns true if there is a redo facility available and the last operation can be redone. ↪️

canUndo(This) -> boolean() when This :: wxComboBox().

Returns true if there is an undo facility available and the last operation can be undone. ↩️

copy(This) -> ok when This :: wxComboBox().

Copies the selected text to the clipboard. 📎

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

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

cut(This) -> ok when This :: wxComboBox().

Copies the selected text to the clipboard and removes it from the control. ✂️📋 two-for-one, efficient bestie

destroy(This :: wxComboBox()) -> ok.

Destroys the object. bye bestie, you were iconic 💀

getInsertionPoint(This) -> integer() when This :: wxComboBox().

Same as wxTextCtrl:getInsertionPoint/1.

Note: Under wxMSW, this function always returns 0 if the combobox doesn't have the focus. rude but true 🙈

getLastPosition(This) -> integer() when This :: wxComboBox().

Returns the zero based index of the last position in the text control, which is equal to the number of characters in the control. 📏

getValue(This) -> unicode:charlist() when This :: wxComboBox().

Gets the contents of the control.

Notice that for a multiline text control, the lines will be separated by (Unix-style) \n characters, even under Windows where they are separated by a \r\n sequence in the native control. yes, even there. it normalizes, it's that girl 💅

new() -> wxComboBox().

Default constructor. blank canvas, no thoughts, just vibes 🎀

new(Parent, Id, [Option]) -> wxComboBox()

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

Constructor, creating and showing a combobox. ✨

See: create/8

paste(This) -> ok when This :: wxComboBox().

Pastes text from the clipboard to the text item. 📥

redo(This) -> ok when This :: wxComboBox().

If there is a redo facility and the last operation can be redone, redoes the last operation.

Does nothing if there is no redo facility. it just… sits there. respectfully 🫶

remove(This, From, To) -> ok

remove(This, From, To) -> ok
                when
                    This :: wxComboBox(),
                    From :: integer(),
                    To :: integer().

Removes the text starting at the first given position up to (but not including) the character at the last position. yes, not including, the To char survives, that's the rule 📌

This function puts the current insertion point position at to as a side effect. sneaky little side quest 👀

replace(This, From, To, Value) -> ok

replace(This, From, To, Value) -> ok
                 when
                     This :: wxComboBox(),
                     From :: integer(),
                     To :: integer(),
                     Value :: unicode:chardata().

Replaces the text starting at the first position up to (but not including) the character at the last position with the given text. again — not including the last one 💅

This function puts the current insertion point position at to as a side effect. same side quest, same energy 👑

setInsertionPoint(This, Pos) -> ok

setInsertionPoint(This, Pos) -> ok
                           when This :: wxComboBox(), Pos :: integer().

Sets the insertion point at the given position. 🎯

setInsertionPointEnd(This) -> ok when This :: wxComboBox().

Sets the insertion point at the end of the text control.

This is equivalent to calling setInsertionPoint/2 with getLastPosition/1 argument. shortcut slay ✨

setSelection(This, N) -> ok

setSelection(This, N) -> ok
                      when This :: wxComboBox(), 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, no event drama 💀

See:

  • wxControlWithItems:setString/3
  • wxControlWithItems:setStringSelection/2

setSelection(This, From, To) -> ok

setSelection(This, From, To) -> ok
                      when
                          This :: wxComboBox(),
                          From :: integer(),
                          To :: integer().

Same as wxTextCtrl:setSelection/3.

setValue(This, Text) -> ok

setValue(This, Text) -> ok
                  when This :: wxComboBox(), Text :: unicode:chardata().

Sets the text for the combobox text field. ✍️

For normal, editable comboboxes with a text entry field calling this method will generate a wxEVT_TEXT event, consistently with wxTextCtrl:setValue/2 behaviour — use wxTextCtrl:changeValue/2 if this is undesirable. like, if you didn't want the event, that's the move bestie 🫶

For controls with wxCB_READONLY style the method behaves somewhat differently: the string must be in the combobox choices list (the check for this is case-insensitive) and wxEVT_TEXT is not generated in this case. read-only mode says "must be on the list, bestie, and no event for you" 📋

undo(This) -> ok when This :: wxComboBox().

If there is an undo facility and the last operation can be undone, undoes the last operation.

Does nothing if there is no undo facility. once again — no facility, no nothing. it's fine. it's fine 🙈

and that's the whole page, diva 💖 this lil doc came from Ericsson AB for wx 2.6, and yeah it's literally the wxComboBox(3) page — go forth and combobox responsibly, bestie 🦋✨🎀

📦 where this page comes from