A listbox is used to select one or more of a list of strings. The strings are displayed in a scrolling box, with the selected string(s) marked in reverse video. A listbox can be single selection (if an item is selected, the previous selection is removed) or multiple selection (clicking an item toggles the item on or off independently of other selections).
List box elements are numbered from zero.
A listbox callback gets an event wxEVENT_TYPE_LISTBOX_COMMAND for single clicks, and wxEVENT_TYPE_LISTBOX_DCLICK_COMMAND for double clicks. Another way of intercepting double clicks is to override wxPanel::OnDefaultAction.
Please note that under XView, the height of a listbox cannot be set accurately, since internally, the number of rows must be used to set the height. So it is unlikely that the value returned by GetSize will be the same as passed to SetSize.
See also wxChoice.
wxListBox::wxListBox
wxListBox::~wxListBox
wxListBox::Append
wxListBox::Clear
wxListBox::Create
wxListBox::Delete
wxListBox::Deselect
wxListBox::FindString
wxListBox::GetClientData
wxListBox::GetSelection
wxListBox::GetSelections
wxListBox::GetString
wxListBox::GetStringSelection
wxListBox::Number
wxListBox::Selected
wxListBox::Set
wxListBox::SetClientData
wxListBox::SetFirstItem
wxListBox::SetSelection
wxListBox::SetString
wxListBox::SetStringSelection
void wxListBox(void)
Constructor, for deriving classes.
void wxListBox(wxPanel *parent, wxFunction func, char *label,
Bool multiple_selection = wxSINGLE, int x = -1, int y = -1,
int width = -1, int height = -1, int n, char *choices[],
long style = 0, char *name = "listBox")
Constructor, creating and showing a list box.
func may be NULL; otherwise it is used as the callback for the list box. Note that the cast (wxFunction) must be used when passing your callback function name, or the compiler may complain that the function does not match the constructor declaration.
If label is non-NULL, it will be used as the listbox label.
The parameters x and y are used to specify an absolute position, or a position after the previous panel item if omitted or default.
If width or height are omitted (or are less than zero), an appropriate size will be used for the list box.
n is the number of possible choices, and choices is an array of strings of size n. wxWindows allocates its own memory for these strings so the calling program must deallocate the array itself.
multiple_selection is a bit list of some of the following:
wxSINGLE | Single-selection list. |
wxMULTIPLE | Multiple-selection list. |
wxEXTENDED | Extended-selection list (Motif and Windows). |
style is a bit list of some of the following. Note that style should now be used for all listbox styles, in preference to using the multiple_selection argument. However, the styles in multiple_selection still work for backward compatibility.
wxNEEDED_SB | Create scrollbars if needed. |
wxLB_NEEDED_SB | Same as wxNEEDED_SB. |
wxALWAYS_SB | Create scrollbars immediately. |
wxLB_ALWAYS_SB | Same as wxALWAYS_LB. |
wxLB_SINGLE | Single-selection list. |
wxLB_MULTIPLE | Multiple-selection list. |
wxLB_EXTENDED | Extended-selection list (Motif and Windows). |
wxHSCROLL | Create horizontal scrollbar if contents are too wide (Windows only). |
wxFIXED_LENGTH | Allows the values of a column of items to be left-aligned. Create an item with this style, and pad out your labels with spaces to the same length. The item labels will initially created with a string of identical characters, positioning all the values at the same x-position. Then the real label is restored. |
The name parameter is used to associate a name with the item, allowing the application user to set Motif resource values for individual listboxes.
void ~wxListBox(void)
Destructor, destroying the list box.
void Append(char * item)
Adds the item to the end of the list box. item must be deallocated by the calling program, i.e. wxWindows makes its own copy.
void Append(char * item, char *client_data)
Adds the item to the end of the list box, associating the given data with the item. item must be deallocated by the calling program.
void Clear(void)
Clears all strings from the list box.
Bool Create(wxPanel *parent, wxFunction func, char *label,
Bool multiple_selection = FALSE, int x = -1, int y = -1,
int width = -1, int height = -1, int n, char *choices[],
long style = 0, char *name = "listBox")
Creates the listbox for two-step construction. Derived classes should call or replace this function. See wxListBox::wxListBox for further details.
void Delete(int n)
Delete the nth element in the list box.
void Deselect(int n)
Deselects the given item in the list box.
int FindString(int char *s)
Finds a choice matching the given string, returning the position if found, or -1 if not found.
char * GetClientData(int n)
Returns a pointer to the client data associated with the given item (if any).
int GetSelection(void)
Gets the id (position) of the selected string - for single selection list boxes only.
int GetSelections(int **selections)
Gets an array containing the positions of the selected strings. The number of selections is returned. Pass a pointer to an integer array, and do not deallocate the returned array.
char * GetString(int n)
Returns a temporary pointer to the string at position n.
char * GetStringSelection(void)
Gets the selected string - for single selection list boxes only. This must be copied by the calling program if long term use is to be made of it.
int Number(void)
Returns the number of items in the listbox.
Bool Selected(int n)
Returns TRUE if the given item is selected, FALSE otherwise.
void Set(int n, char *choices[], char *clientData[] = NULL)
Clears the list box and adds the given strings. Deallocate the array from the calling program after this function has been called.
void SetClientData(int n, char *data)
Associates the given client data pointer with the given item.
void SetFirstItem(int n)
void SetFirstItem(char *item)
Set the specified item to be the first visible item (not XView).
void SetSelection(int n, Bool select = TRUE)
Selects or deselects the given item.
void SetString(int n, char * s)
Sets the value of the given string.
void SetStringSelection(char * s)
Sets the choice by passing the desired string.