Contents Up Previous Next

wxListBox: wxItem

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


wxListBox::wxListBox

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.


wxListBox::~wxListBox

void ~wxListBox(void)

Destructor, destroying the list box.


wxListBox::Append

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.


wxListBox::Clear

void Clear(void)

Clears all strings from the list box.


wxListBox::Create

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.


wxListBox::Delete

void Delete(int n)

Delete the nth element in the list box.


wxListBox::Deselect

void Deselect(int n)

Deselects the given item in the list box.


wxListBox::FindString

int FindString(int char *s)

Finds a choice matching the given string, returning the position if found, or -1 if not found.


wxListBox::GetClientData

char * GetClientData(int n)

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


wxListBox::GetSelection

int GetSelection(void)

Gets the id (position) of the selected string - for single selection list boxes only.


wxListBox::GetSelections

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.


wxListBox::GetString

char * GetString(int n)

Returns a temporary pointer to the string at position n.


wxListBox::GetStringSelection

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.


wxListBox::Number

int Number(void)

Returns the number of items in the listbox.


wxListBox::Selected

Bool Selected(int n)

Returns TRUE if the given item is selected, FALSE otherwise.


wxListBox::Set

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.


wxListBox::SetClientData

void SetClientData(int n, char *data)

Associates the given client data pointer with the given item.


wxListBox::SetFirstItem

void SetFirstItem(int n)

void SetFirstItem(char *item)

Set the specified item to be the first visible item (not XView).


wxListBox::SetSelection

void SetSelection(int n, Bool select = TRUE)

Selects or deselects the given item.


wxListBox::SetString

void SetString(int n, char * s)

Sets the value of the given string.


wxListBox::SetStringSelection

void SetStringSelection(char * s)

Sets the choice by passing the desired string.