%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%% Name:        ctrlsub.tex
%% Purpose:     wxControlWithItems documentation
%% Author:      Vadim Zeitlin
%% Modified by:
%% Created:     01.01.03
%% RCS-ID:      $Id$
%% Copyright:   (c) 2003 Vadim Zeitlin
%% License:     wxWindows license
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\section{\class{wxControlWithItems}}\label{wxcontrolwithitems}

This class is an abstract base class for some wxWidgets controls which contain
several items, such as \helpref{wxListBox}{wxlistbox} and 
\helpref{wxCheckListBox}{wxchecklistbox} derived from it, 
\helpref{wxChoice}{wxchoice} and \helpref{wxComboBox}{wxcombobox}.

It defines the methods for accessing the controls items and although each of
the derived classes implements them differently, they still all conform to the
same interface.

The items in a wxControlWithItems have (non empty) string labels and,
optionally, client data associated with them. Client data may be of two
different kinds: either simple untyped ({\tt void *}) pointers which are simply
stored by the control but not used in any way by it, or typed pointers
({\tt wxClientData *}) which are owned by the control meaning that the typed
client data (and only it) will be deleted when an item is 
\helpref{deleted}{wxcontrolwithitemsdelete} or the entire control is 
\helpref{cleared}{wxcontrolwithitemsclear} (which also happens when it is
destroyed). Finally note that in the same control all items must have client
data of the same type (typed or untyped), if any. This type is determined by
the first call to \helpref{Append}{wxcontrolwithitemsappend} (the version with
client data pointer) or \helpref{SetClientData}{wxcontrolwithitemssetclientdata}.

\wxheading{Derived from}

\helpref{wxControl}{wxcontrol}\\
\helpref{wxWindow}{wxwindow}\\
\helpref{wxEvtHandler}{wxevthandler}\\
\helpref{wxObject}{wxobject}

\wxheading{Include files}

<wx/ctrlsub.h> but usually never included directly

\latexignore{\rtfignore{\wxheading{Members}}}

\membersection{wxControlWithItems::Append}\label{wxcontrolwithitemsappend}

\func{int}{Append}{\param{const wxString\& }{ item}}

Adds the item to the end of the list box.

\func{int}{Append}{\param{const wxString\& }{ item}, \param{void *}{clientData}}

\func{int}{Append}{\param{const wxString\& }{ item}, \param{wxClientData *}{clientData}}

Adds the item to the end of the list box, associating the given, typed or
untyped, client data pointer with the item.

\func{void}{Append}{\param{const wxArrayString\& }{strings}}

Appends several items at once to the control. Notice that calling this method
may be much faster than appending the items one by one if you need to add a lot
of items.

\wxheading{Parameters}

\docparam{item}{String to add.}

\docparam{clientData}{Client data to associate with the item.}

\wxheading{Return value}

When appending a single item, the return value is the index of the newly added
item which may be different from the last one if the control is sorted (e.g.
has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style).

\membersection{wxControlWithItems::Clear}\label{wxcontrolwithitemsclear}

\func{void}{Clear}{\void}

Removes all items from the control.

{\it Clear()} also deletes the client data of the existing items if it is owned
by the control.

\membersection{wxControlWithItems::Delete}\label{wxcontrolwithitemsdelete}

\func{void}{Delete}{\param{int}{ n}}

Deletes an item from the control. The client data associated with the item
will be also deleted if it is owned by the control.

Note that it is an error (signalled by an assert failure in debug builds) to
remove an item with the index negative or greater or equal than the number of
items in the control.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\wxheading{See also}

\helpref{Clear}{wxcontrolwithitemsclear}

\membersection{wxControlWithItems::FindString}\label{wxcontrolwithitemsfindstring}

\func{int}{FindString}{\param{const wxString\& }{string}}

Finds an item whose label matches the given string.

\wxheading{Parameters}

\docparam{string}{String to find.}

\wxheading{Return value}

The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was
not found.


\membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}

\constfunc{void *}{GetClientData}{\param{int}{ n}}

Returns a pointer to the client data associated with the given item (if any).
It is an error to call this function for a control which doesn't have untyped
client data at all although it is ok to call it even if the given item doesn't
have any client data associated with it (but other items do).

\wxheading{Parameters}

\docparam{n}{The zero-based position of the item.}

\wxheading{Return value}

A pointer to the client data, or {\tt NULL} if not present.


\membersection{wxControlWithItems::GetClientObject}\label{wxcontrolwithitemsgetclientobject}

\constfunc{wxClientData *}{GetClientObject}{\param{int}{ n}}

Returns a pointer to the client data associated with the given item (if any).
It is an error to call this function for a control which doesn't have typed
client data at all although it is ok to call it even if the given item doesn't
have any client data associated with it (but other items do).

\wxheading{Parameters}

\docparam{n}{The zero-based position of the item.}

\wxheading{Return value}

A pointer to the client data, or {\tt NULL} if not present.


\membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount}

\constfunc{int}{GetCount}{\void}

Returns the number of items in the control.

\wxheading{See also}

\helpref{IsEmpty}{wxcontrolwithitemsisempty}


\membersection{wxControlWithItems::GetSelection}\label{wxcontrolwithitemsgetselection}

\constfunc{int}{GetSelection}{\void}

Returns the index of the selected item or {\tt wxNOT\_FOUND} if no item is
selected.

\wxheading{Return value}

The position of the current selection.

\wxheading{Remarks}

This method can be used with single selection list boxes only, you should use 
\helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
with {\tt wxLB\_MULTIPLE} style.

\wxheading{See also}

\helpref{SetSelection}{wxcontrolwithitemssetselection},\rtfsp
\helpref{GetStringSelection}{wxcontrolwithitemsgetstringselection}


\membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}

\constfunc{wxString}{GetString}{\param{int}{ n}}

Returns the label of the item with the given index.

\wxheading{Parameters}

\docparam{n}{The zero-based index.}

\wxheading{Return value}

The label of the item or an empty string if the position was invalid.


\membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}

\constfunc{wxString}{GetStringSelection}{\void}

Returns the label of the selected item or an empty string if no item is
selected.

\wxheading{See also}

\helpref{GetSelection}{wxcontrolwithitemsgetselection}


\membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}

\func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}}

Inserts the item into the list before pos.
Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.

\func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{void *}{clientData}}

\func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{wxClientData *}{clientData}}

Inserts the item into the list before pos, associating the given, typed or
untyped, client data pointer with the item.
Not valid for {\tt wxLB\_SORT} or {\tt wxCB\_SORT} styles, use Append instead.

\wxheading{Parameters}

\docparam{item}{String to add.}

\docparam{pos}{Position to insert item before, zero based.}

\docparam{clientData}{Client data to associate with the item.}

\wxheading{Return value}

The return value is the index of the newly inserted item. If the insertion failed
for some reason, -1 is returned.


\membersection{wxControlWithItems::IsEmpty}\label{wxcontrolwithitemsisempty}

\constfunc{bool}{IsEmpty}{\void}

Returns {\tt true} if the control is empty or {\tt false} if it has some items.

\wxheading{See also}

\helpref{GetCount}{wxcontrolwithitemsgetcount}


\membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}

\constfunc{int}{Number}{\void}

{\bf Obsolescence note:} This method is obsolete and was replaced with
\helpref{GetCount}{wxcontrolwithitemsgetcount}, please use the new method in
the new code. This method is only available if wxWidgets was compiled with 
{\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
future versions.


\membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}

\func{void}{Select}{\param{int}{ n}}

This is the same as \helpref{SetSelection}{wxcontrolwithitemssetselection} and
exists only because it is slightly more natural for controls which support
multiple selection.


\membersection{wxControlWithItems::SetClientData}\label{wxcontrolwithitemssetclientdata}

\func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}

Associates the given untyped client data pointer with the given item. Note that
it is an error to call this function if any typed client data pointers had been
associated with the control items before.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{data}{The client data to associate with the item.}


\membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}

\func{void}{SetClientObject}{\param{int}{ n}, \param{wxClientData *}{data}}

Associates the given typed client data pointer with the given item: the 
{\it data} object will be deleted when the item is deleted (either explicitly
by using \helpref{Deletes}{wxcontrolwithitemsdelete} or implicitly when the
control itself is destroyed).

Note that it is an error to call this function if any untyped client data
pointers had been associated with the control items before.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{data}{The client data to associate with the item.}


\membersection{wxControlWithItems::SetSelection}\label{wxcontrolwithitemssetselection}

\func{void}{SetSelection}{\param{int}{ n}}

Sets the selection to the given item \arg{n} or removes the selection entirely
if \arg{n} $==$ {\tt 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.

\wxheading{Parameters}

\docparam{n}{The string position to select, starting from zero.}

\wxheading{See also}

\helpref{SetString}{wxcontrolwithitemssetstring},\rtfsp
\helpref{SetStringSelection}{wxcontrolwithitemssetstringselection}


\membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}

\func{void}{SetString}{\param{int}{ n}, \param{const wxString\& }{ string}}

Sets the label for the given item.

\wxheading{Parameters}

\docparam{n}{The zero-based item index.}

\docparam{string}{The label to set.}


\membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}

\func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}

Selects the item with the specified string in the control. This doesn't cause
any command events being emitted.

\wxheading{Parameters}

\docparam{string}{The string to select.}

\wxheading{Return value}

\true if the specified string has been selected, \false if it wasn't found in
the control.

\wxheading{See also}

\helpref{SetSelection}{wxcontrolwithitemssetselection}