wxListBox Class Reference
[Controls]

#include <wx/listbox.h>

Inheritance diagram for wxListBox:
Inheritance graph
[legend]

Detailed Description

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. Their number may be limited under some platforms.

A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECTED for single clicks, and wxEVT_COMMAND_LISTBOX_DOUBLECLICKED for double clicks.

Styles

This class supports the following styles:

Note that wxLB_SINGLE, wxLB_MULTIPLE and wxLB_EXTENDED styles are mutually exclusive and you can specify at most one of them (single selection is the default). See also Window Styles.

Events emitted by this class

The following event handler macros redirect the events to member function handlers 'func' with prototypes like:

void handlerFuncName(wxCommandEvent& event)

Event macros for events emitted by this class:

Library:  wxCore
Category:  Controls

Appearance:
wxMSW appearancewxGTK appearancewxMac appearance
wxMSW appearancewxGTK appearancewxMac appearance
See also:
wxEditableListBox, wxChoice, wxComboBox, wxListCtrl, wxCommandEvent

Public Member Functions

 wxListBox ()
 Default constructor.
 wxListBox (wxWindow *parent, wxWindowID id, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, int n=0, const wxString choices[]=NULL, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxListBoxNameStr)
 Constructor, creating and showing a list box.
 wxListBox (wxWindow *parent, wxWindowID id, const wxPoint &pos, const wxSize &size, const wxArrayString &choices, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxListBoxNameStr)
 Constructor, creating and showing a list box.
virtual ~wxListBox ()
 Destructor, destroying the list box.
void Deselect (int n)
 Deselects an item in the list box.
virtual int GetSelections (wxArrayInt &selections) const
 Fill an array of ints with the positions of the currently selected items.
int HitTest (const wxPoint &point) const
 Returns the item located at point, or wxNOT_FOUND if there is no item located at point.
int HitTest (int x, int y) const
 This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.
void InsertItems (unsigned int nItems, const wxString *items, unsigned int pos)
 Insert the given number of strings before the specified position.
void InsertItems (const wxArrayString &items, unsigned int pos)
 Insert the given number of strings before the specified position.
virtual bool IsSelected (int n) const
 Determines whether an item is selected.
void Set (unsigned int n, const wxString *choices, void *clientData)
 Clears the list box and adds the given strings to it.
void Set (const wxArrayString &choices, void *clientData)
 Clears the list box and adds the given strings to it.
void SetFirstItem (int n)
 Set the specified item to be the first visible item.
void SetFirstItem (const wxString &string)
 Set the specified item to be the first visible item.

bool Create (wxWindow *parent, wxWindowID id, const wxPoint &pos=wxDefaultPosition, const wxSize &size=wxDefaultSize, int n=0, const wxString choices[]=NULL, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxListBoxNameStr)
 Creates the listbox for two-step construction.
bool Create (wxWindow *parent, wxWindowID id, const wxPoint &pos, const wxSize &size, const wxArrayString &choices, long style=0, const wxValidator &validator=wxDefaultValidator, const wxString &name=wxListBoxNameStr)
 Creates the listbox for two-step construction.

List of all members.


Constructor & Destructor Documentation

wxListBox::wxListBox (  ) 

Default constructor.

wxListBox::wxListBox ( wxWindow parent,
wxWindowID  id,
const wxPoint pos = wxDefaultPosition,
const wxSize size = wxDefaultSize,
int  n = 0,
const wxString  choices[] = NULL,
long  style = 0,
const wxValidator validator = wxDefaultValidator,
const wxString name = wxListBoxNameStr 
)

Constructor, creating and showing a list box.

Parameters:
parent The parent window.
id The ID of this control. A value of wxID_ANY indicates a default value.
pos The initial position. If wxDefaultPosition is specified then a default position is chosen.
size The initial size. If wxDefaultSize is specified then the window is sized appropriately.
n Number of strings with which to initialise the control.
choices The strings to use to initialize the control.
style Window style. See wxListBox.
validator The validator for this control.
name The name of this class.

wxPerl Note: Not supported by wxPerl.

wxListBox::wxListBox ( wxWindow parent,
wxWindowID  id,
const wxPoint pos,
const wxSize size,
const wxArrayString choices,
long  style = 0,
const wxValidator validator = wxDefaultValidator,
const wxString name = wxListBoxNameStr 
)

Constructor, creating and showing a list box.

See the other wxListBox() constructor; the only difference is that this overload takes a wxArrayString instead of a pointer to an array of wxString.

wxPerl Note: Use an array reference for the choices parameter.

virtual wxListBox::~wxListBox (  )  [virtual]

Destructor, destroying the list box.


Member Function Documentation

bool wxListBox::Create ( wxWindow parent,
wxWindowID  id,
const wxPoint pos,
const wxSize size,
const wxArrayString choices,
long  style = 0,
const wxValidator validator = wxDefaultValidator,
const wxString name = wxListBoxNameStr 
)

Creates the listbox for two-step construction.

See wxListBox() for further details.

bool wxListBox::Create ( wxWindow parent,
wxWindowID  id,
const wxPoint pos = wxDefaultPosition,
const wxSize size = wxDefaultSize,
int  n = 0,
const wxString  choices[] = NULL,
long  style = 0,
const wxValidator validator = wxDefaultValidator,
const wxString name = wxListBoxNameStr 
)

Creates the listbox for two-step construction.

See wxListBox() for further details.

void wxListBox::Deselect ( int  n  ) 

Deselects an item in the list box.

Parameters:
n The zero-based item to deselect.
Remarks:
This applies to multiple selection listboxes only.
virtual int wxListBox::GetSelections ( wxArrayInt selections  )  const [virtual]

Fill an array of ints with the positions of the currently selected items.

Parameters:
selections A reference to an wxArrayInt instance that is used to store the result of the query.
Returns:
The number of selections.
Remarks:
Use this with a multiple selection listbox.

wxPerl Note: In wxPerl this method takes no parameters and return the selected items as a list.

See also:
wxControlWithItems::GetSelection, wxControlWithItems::GetStringSelection, wxControlWithItems::SetSelection
int wxListBox::HitTest ( int  x,
int  y 
) const

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.

int wxListBox::HitTest ( const wxPoint point  )  const

Returns the item located at point, or wxNOT_FOUND if there is no item located at point.

It is currently implemented for wxMSW, wxMac and wxGTK2 ports.

Parameters:
point Point of item (in client coordinates) to obtain
Returns:
Item located at point, or wxNOT_FOUND if unimplemented or the item does not exist.
Since:
2.7.0
void wxListBox::InsertItems ( const wxArrayString items,
unsigned int  pos 
)

Insert the given number of strings before the specified position.

Parameters:
items Labels of items to be inserted
pos Position before which to insert the items: if pos is 0 the items will be inserted in the beginning of the listbox

wxPerl Note: Use an array reference for the items parameter.

void wxListBox::InsertItems ( unsigned int  nItems,
const wxString items,
unsigned int  pos 
)

Insert the given number of strings before the specified position.

Parameters:
nItems Number of items in the array items
items Labels of items to be inserted
pos Position before which to insert the items: if pos is 0 the items will be inserted in the beginning of the listbox

wxPerl Note: Not supported by wxPerl.

virtual bool wxListBox::IsSelected ( int  n  )  const [virtual]

Determines whether an item is selected.

Parameters:
n The zero-based item index.
Returns:
true if the given item is selected, false otherwise.
void wxListBox::Set ( const wxArrayString choices,
void *  clientData 
)

Clears the list box and adds the given strings to it.

You may free the array from the calling program after this method has been called.

Parameters:
choices An array of strings to set.
clientData Options array of client data pointers
void wxListBox::Set ( unsigned int  n,
const wxString choices,
void *  clientData 
)

Clears the list box and adds the given strings to it.

Parameters:
n The number of strings to set.
choices An array of strings to set.
clientData Options array of client data pointers
void wxListBox::SetFirstItem ( const wxString string  ) 

Set the specified item to be the first visible item.

Parameters:
string The string that should be visible.
void wxListBox::SetFirstItem ( int  n  ) 

Set the specified item to be the first visible item.

Parameters:
n The zero-based item index that should be visible.
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Friends Defines



wxWidgets logo

[ top ]