File: wx128.htm

package info (click to toggle)
wxwin2-doc 2.01-1
links: PTS
area: main
in suites: potato
size: 6,540 kB
ctags: 5,968
sloc: cpp: 15,157; makefile: 434; sh: 6
file content (485 lines) | stat: -rw-r--r-- 15,582 bytes
<HTML>
<head><title>wxListBox</title></head>

<BODY BGCOLOR=#FFFFFF>
<A NAME="wxlistbox"></A><CENTER>
<A HREF="wx.htm"><img align=center src="contents.gif" BORDER=0 ALT="Contents"></A> <A HREF="wx22.htm#classref"><img align=center src="up.gif" BORDER=0 ALT="Up"></A> <A HREF="wx127.htm#wxlist"><img align=center src="back.gif" BORDER=0 ALT="Previous"></A> <A HREF="wx129.htm#wxlistctrl"><img align=center src="forward.gif" BORDER=0 ALT="Next"></A> </CENTER><HR>

<H2>wxListBox</H2>
<P>
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).<P>
List box elements are numbered from zero.<P>
A listbox callback gets an event wxEVT_COMMAND_LISTBOX_SELECT for single clicks, and
wxEVT_COMMAND_LISTBOX_DOUBLE_CLICKED for double clicks.<P>
<B><FONT COLOR="#FF0000">Derived from</FONT></B><P>
<A HREF="wx56.htm#wxcontrol">wxControl</A><BR>

<A HREF="wx260.htm#wxwindow">wxWindow</A><BR>

<A HREF="wx85.htm#wxevthandler">wxEvtHandler</A><BR>

<A HREF="wx158.htm#wxobject">wxObject</A><P>
<B><FONT COLOR="#FF0000">Include files</FONT></B><P>
&lt;wx/listbox.h&gt;<P>
<B><FONT COLOR="#FF0000">Window styles</FONT></B><P>

<TABLE>


<TR><TD VALIGN=TOP>
<B>wxLB_SINGLE</B>
</TD>

<TD VALIGN=TOP>
Single-selection list.
</TD></TR>


<TR><TD VALIGN=TOP>
<B>wxLB_MULTIPLE</B>
</TD>

<TD VALIGN=TOP>
Multiple-selection list: the user can toggle multiple
items on and off.
</TD></TR>


<TR><TD VALIGN=TOP>
<B>wxLB_EXTENDED</B>
</TD>

<TD VALIGN=TOP>
Extended-selection list: the user can
select multiple items using the SHIFT key and the mouse or special key combinations.
</TD></TR>


<TR><TD VALIGN=TOP>
<B>wxLB_HSCROLL</B>
</TD>

<TD VALIGN=TOP>
Create horizontal scrollbar if contents are too wide (Windows only).
</TD></TR>


<TR><TD VALIGN=TOP>
<B>wxLB_ALWAYS_SB</B>
</TD>

<TD VALIGN=TOP>
Always show a vertical scrollbar.
</TD></TR>


<TR><TD VALIGN=TOP>
<B>wxLB_NEEDED_SB</B>
</TD>

<TD VALIGN=TOP>
Only create a vertical scrollbar if needed.
</TD></TR>


<TR><TD VALIGN=TOP>
<B>wxLB_SORT</B>
</TD>

<TD VALIGN=TOP>
The listbox contents are sorted in alphabetical order.
</TD></TR>


</TABLE>
<P>
See also <A HREF="wx305.htm#windowstyles">window styles overview</A>.<P>
<B><FONT COLOR="#FF0000">Event handling</FONT></B><P>


<TABLE>


<TR><TD VALIGN=TOP>
<B>EVT_LISTBOX(id, func)</B>
</TD>

<TD VALIGN=TOP>
Process a wxEVT_COMMAND_LISTBOX_SELECTED event,
when an item on the list is selected.
</TD></TR>


<TR><TD VALIGN=TOP>
<B>EVT_LISTBOX_DCLICK(id, func)</B>
</TD>

<TD VALIGN=TOP>
Process a wxEVT_COMMAND_LISTBOX_DOUBLECLICKED event,
when the listbox is doubleclicked.
</TD></TR>


</TABLE>
<P>
<B><FONT COLOR="#FF0000">See also</FONT></B><P>
<A HREF="wx41.htm#wxchoice">wxChoice</A>, <A HREF="wx50.htm#wxcombobox">wxComboBox</A>, <A HREF="wx129.htm#wxlistctrl">wxListCtrl</A>,
<A HREF="wx52.htm#wxcommandevent">wxCommandEvent</A><P>
<B><FONT COLOR="#FF0000">Members</FONT></B><P>
<A HREF="#wxlistboxconstr">wxListBox::wxListBox</A><BR>
<A HREF="#topic537">wxListBox::~wxListBox</A><BR>
<A HREF="#wxlistboxappend">wxListBox::Append</A><BR>
<A HREF="#wxlistboxclear">wxListBox::Clear</A><BR>
<A HREF="#wxlistboxcreate">wxListBox::Create</A><BR>
<A HREF="#wxlistboxdelete">wxListBox::Delete</A><BR>
<A HREF="#wxlistboxdeselect">wxListBox::Deselect</A><BR>
<A HREF="#wxlistboxfindstring">wxListBox::FindString</A><BR>
<A HREF="#wxlistboxgetclientdata">wxListBox::GetClientData</A><BR>
<A HREF="#wxlistboxgetselection">wxListBox::GetSelection</A><BR>
<A HREF="#wxlistboxgetselections">wxListBox::GetSelections</A><BR>
<A HREF="#wxlistboxgetstring">wxListBox::GetString</A><BR>
<A HREF="#wxlistboxgetstringselection">wxListBox::GetStringSelection</A><BR>
<A HREF="#wxlistboxinsertitems">wxListBox::InsertItems</A><BR>
<A HREF="#wxlistboxnumber">wxListBox::Number</A><BR>
<A HREF="#wxlistboxselected">wxListBox::Selected</A><BR>
<A HREF="#wxlistboxset">wxListBox::Set</A><BR>
<A HREF="#wxlistboxsetclientdata">wxListBox::SetClientData</A><BR>
<A HREF="#wxlistboxsetfirstitem">wxListBox::SetFirstItem</A><BR>
<A HREF="#wxlistboxsetselection">wxListBox::SetSelection</A><BR>
<A HREF="#wxlistboxsetstring">wxListBox::SetString</A><BR>
<A HREF="#wxlistboxsetstringselection">wxListBox::SetStringSelection</A><BR>
<P>

<HR>
<A NAME="wxlistboxconstr"></A>
<H3>wxListBox::wxListBox</H3>
<P>
<B></B> <B>wxListBox</B>()<P>
Default constructor.<P>
<B></B> <B>wxListBox</B>(<B>wxWindow*</B><I> parent</I>, <B>wxWindowID</B><I> id</I>,
<B>const wxPoint&amp;</B><I> pos = wxDefaultPosition</I>, <B>const wxSize&amp;</B><I> size = wxDefaultSize</I>,
<B>int</B><I> n</I>, <B>const wxString </B><I>choices[] = NULL</I>,
<B>long</B><I> style = 0</I>, <B>const wxValidator&amp; </B><I>validator = wxDefaultValidator</I>, <B>const wxString&amp; </B><I>name = "listBox"</I>)<P>
Constructor, creating and showing a list box.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>parent</I><UL><UL>
Parent window. Must not be NULL.</UL></UL>
<P>
<I>id</I><UL><UL>
Window identifier. A value of -1 indicates a default value.</UL></UL>
<P>
<I>pos</I><UL><UL>
Window position.</UL></UL>
<P>
<I>size</I><UL><UL>
Window size. If the default size (-1, -1) is specified then the window is sized
appropriately.</UL></UL>
<P>
<I>n</I><UL><UL>
Number of strings with which to initialise the control.</UL></UL>
<P>
<I>choices</I><UL><UL>
An array of strings with which to initialise the control.</UL></UL>
<P>
<I>style</I><UL><UL>
Window style. See <A HREF="wx128.htm#wxlistbox">wxListBox</A>.</UL></UL>
<P>
<I>validator</I><UL><UL>
Window validator.</UL></UL>
<P>
<I>name</I><UL><UL>
Window name.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">See also</FONT></B><P>
<A HREF="wx128.htm#wxlistboxcreate">wxListBox::Create</A>, <A HREF="wx255.htm#wxvalidator">wxValidator</A><P>
<B><FONT COLOR="#0000C8">wxPython note:</FONT></B><BR>
 The wxListBox constructor in wxPython reduces the <TT>n</TT>
and <TT>choices</TT> arguments are to a single argument, which is
a list of strings.<P>
<P>

<HR>
<A NAME="topic537"></A>
<H3>wxListBox::~wxListBox</H3>
<P>
<B>void</B> <B>~wxListBox</B>()<P>
Destructor, destroying the list box.<P>

<HR>
<A NAME="wxlistboxappend"></A>
<H3>wxListBox::Append</H3>
<P>
<B>void</B> <B>Append</B>(<B>const wxString&amp; </B><I> item</I>)<P>
Adds the item to the end of the list box.<P>
<B>void</B> <B>Append</B>(<B>const wxString&amp; </B><I> item</I>, <B>char* </B><I>clientData</I>)<P>
Adds the item to the end of the list box, associating the given data
with the item.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>item</I><UL><UL>
String to add.</UL></UL>
<P>
<I>clientData</I><UL><UL>
Client data to associate with the item.</UL></UL>
<P>

<HR>
<A NAME="wxlistboxclear"></A>
<H3>wxListBox::Clear</H3>
<P>
<B>void</B> <B>Clear</B>()<P>
Clears all strings from the list box.<P>

<HR>
<A NAME="wxlistboxcreate"></A>
<H3>wxListBox::Create</H3>
<P>
<B>bool</B> <B>Create</B>(<B>wxWindow*</B><I> parent</I>, <B>wxWindowID</B><I> id</I>,
<B>const wxPoint&amp;</B><I> pos = wxDefaultPosition</I>, <B>const wxSize&amp;</B><I> size = wxDefaultSize</I>,
<B>int</B><I> n</I>, <B>const wxString </B><I>choices[] = NULL</I>,
<B>long</B><I> style = 0</I>, <B>const wxValidator&amp; </B><I>validator = wxDefaultValidator</I>, <B>const wxString&amp; </B><I>name = "listBox"</I>)<P>
Creates the listbox for two-step construction. See <A HREF="wx128.htm#wxlistboxconstr">wxListBox::wxListBox</A>
for further details.<P>

<HR>
<A NAME="wxlistboxdelete"></A>
<H3>wxListBox::Delete</H3>
<P>
<B>void</B> <B>Delete</B>(<B>int</B><I> n</I>)<P>
Deletes an item from the listbox.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item index.</UL></UL>
<P>

<HR>
<A NAME="wxlistboxdeselect"></A>
<H3>wxListBox::Deselect</H3>
<P>
<B>void</B> <B>Deselect</B>(<B>int</B><I> n</I>)<P>
Deselects an item in the list box.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item to deselect.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Remarks</FONT></B><P>
This applies to multiple selection listboxes only.<P>

<HR>
<A NAME="wxlistboxfindstring"></A>
<H3>wxListBox::FindString</H3>
<P>
<B>int</B> <B>FindString</B>(<B>const wxString&amp; </B><I>string</I>)<P>
Finds an item matching the given string.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>string</I><UL><UL>
String to find.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Return value</FONT></B><P>
The zero-based position of the item, or -1 if the string was not found.<P>

<HR>
<A NAME="wxlistboxgetclientdata"></A>
<H3>wxListBox::GetClientData</H3>
<P>
<B>char*</B> <B>GetClientData</B>(<B>int</B><I> n</I>) <B>const</B><P>
Returns a pointer to the client data associated with the given item (if any).<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based position of the item.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Return value</FONT></B><P>
A pointer to the client data, or NULL if not present.<P>

<HR>
<A NAME="wxlistboxgetselection"></A>
<H3>wxListBox::GetSelection</H3>
<P>
<B>int</B> <B>GetSelection</B>() <B>const</B><P>
Gets the position of the selected item.<P>
<B><FONT COLOR="#FF0000">Return value</FONT></B><P>
The position of the current selection.<P>
<B><FONT COLOR="#FF0000">Remarks</FONT></B><P>
Applicable to single selection list boxes only.<P>
<B><FONT COLOR="#FF0000">See also</FONT></B><P>
<A HREF="wx128.htm#wxlistboxsetselection">wxListBox::SetSelection</A>,
<A HREF="wx128.htm#wxlistboxgetstringselection">wxListBox::GetStringSelection</A>,
<A HREF="wx128.htm#wxlistboxgetselections">wxListBox::GetSelections</A><P>

<HR>
<A NAME="wxlistboxgetselections"></A>
<H3>wxListBox::GetSelections</H3>
<P>
<B>int</B> <B>GetSelections</B>(<B>int **</B><I>selections</I>) <B>const</B><P>
Gets an array containing the positions of the selected strings.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>selections</I><UL><UL>
A pointer to an integer array, which will be allocated by the function if
selects are present. Do not deallocate the returned array - it will be deallocated by the listbox.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Return value</FONT></B><P>
The number of selections.<P>
<B><FONT COLOR="#FF0000">Remarks</FONT></B><P>
Use this with a multiple selection listbox.<P>
<B><FONT COLOR="#FF0000">See also</FONT></B><P>
<A HREF="wx128.htm#wxlistboxgetselection">wxListBox::GetSelection</A>,
<A HREF="wx128.htm#wxlistboxgetstringselection">wxListBox::GetStringSelection</A>,
<A HREF="wx128.htm#wxlistboxsetselection">wxListBox::SetSelection</A><P>

<HR>
<A NAME="wxlistboxgetstring"></A>
<H3>wxListBox::GetString</H3>
<P>
<B>wxString</B> <B>GetString</B>(<B>int</B><I> n</I>) <B>const</B><P>
Returns the string at the given position.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based position.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Return value</FONT></B><P>
The string, or an empty string if the position was invalid.<P>

<HR>
<A NAME="wxlistboxgetstringselection"></A>
<H3>wxListBox::GetStringSelection</H3>
<P>
<B>wxString</B> <B>GetStringSelection</B>() <B>const</B><P>
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.<P>
<B><FONT COLOR="#FF0000">See also</FONT></B><P>
<A HREF="wx128.htm#wxlistboxgetselection">wxListBox::GetSelection</A>,
<A HREF="wx128.htm#wxlistboxgetselections">wxListBox::GetSelections</A>,
<A HREF="wx128.htm#wxlistboxsetselection">wxListBox::SetSelection</A><P>

<HR>
<A NAME="wxlistboxinsertitems"></A>
<H3>wxListBox::InsertItems</H3>
<P>
<B>void</B> <B>InsertItems</B>(<B>int</B><I> nItems</I>, <B>const wxString</B><I> items</I>, <B>int</B><I> pos</I>)<P>
Insert the given number of strings before the specified position.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>nItems</I><UL><UL>
Number of items in the array <I>items</I></UL></UL>
<P>
<I>items</I><UL><UL>
Labels of items to be inserted</UL></UL>
<P>
<I>pos</I><UL><UL>
Position before which to insert the items: for example, if <I>pos</I> is 0 the items
will be inserted in the beginning of the listbox</UL></UL>
<P>

<HR>
<A NAME="wxlistboxnumber"></A>
<H3>wxListBox::Number</H3>
<P>
<B>int</B> <B>Number</B>() <B>const</B><P>
Returns the number of items in the listbox.<P>

<HR>
<A NAME="wxlistboxselected"></A>
<H3>wxListBox::Selected</H3>
<P>
<B>bool</B> <B>Selected</B>(<B>int</B><I> n</I>) <B>const</B><P>
Determines whether an item is selected.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item index.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Return value</FONT></B><P>
TRUE if the given item is selected, FALSE otherwise.<P>

<HR>
<A NAME="wxlistboxset"></A>
<H3>wxListBox::Set</H3>
<P>
<B>void</B> <B>Set</B>(<B>int</B><I> n</I>, <B>const wxString*</B><I> choices</I>)<P>
Clears the list box and adds the given strings.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The number of strings to set.</UL></UL>
<P>
<I>choices</I><UL><UL>
An array of strings to set.</UL></UL>
<P>
<B><FONT COLOR="#FF0000">Remarks</FONT></B><P>
Deallocate the array from the calling program
after this function has been called.<P>

<HR>
<A NAME="wxlistboxsetclientdata"></A>
<H3>wxListBox::SetClientData</H3>
<P>
<B>void</B> <B>SetClientData</B>(<B>int</B><I> n</I>, <B>char* </B><I>data</I>)<P>
Associates the given client data pointer with the given item.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item index.</UL></UL>
<P>
<I>data</I><UL><UL>
The client data to associate with the item.</UL></UL>
<P>

<HR>
<A NAME="wxlistboxsetfirstitem"></A>
<H3>wxListBox::SetFirstItem</H3>
<P>
<B>void</B> <B>SetFirstItem</B>(<B>int</B><I> n</I>)<P>
<B>void</B> <B>SetFirstItem</B>(<B>const wxString&amp; </B><I>string</I>)<P>
Set the specified item to be the first visible item.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item index.</UL></UL>
<P>
<I>string</I><UL><UL>
The string that should be visible.</UL></UL>
<P>

<HR>
<A NAME="wxlistboxsetselection"></A>
<H3>wxListBox::SetSelection</H3>
<P>
<B>void</B> <B>SetSelection</B>(<B>int</B><I> n</I>, <B>const bool </B><I>select = TRUE</I>)<P>
Selects or deselects the given item.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item index.</UL></UL>
<P>
<I>select</I><UL><UL>
If TRUE, will select the item. If FALSE, will deselect it.</UL></UL>
<P>

<HR>
<A NAME="wxlistboxsetstring"></A>
<H3>wxListBox::SetString</H3>
<P>
<B>void</B> <B>SetString</B>(<B>int</B><I> n</I>, <B>const wxString&amp; </B><I> string</I>)<P>
Sets the string value of an item.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>n</I><UL><UL>
The zero-based item index.</UL></UL>
<P>
<I>string</I><UL><UL>
The string to set.</UL></UL>
<P>

<HR>
<A NAME="wxlistboxsetstringselection"></A>
<H3>wxListBox::SetStringSelection</H3>
<P>
<B>void</B> <B>SetStringSelection</B>(<B>const wxString&amp; </B><I> string</I>, <B>const bool</B><I> select = TRUE</I>)<P>
Sets the current selection.<P>
<B><FONT COLOR="#FF0000">Parameters</FONT></B><P>
<I>string</I><UL><UL>
The item to select.</UL></UL>
<P>
<I>select</I><UL><UL>
If TRUE, will select the item. If FALSE, will deselect it.</UL></UL>
<P>

</BODY></HTML>