+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+%% 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 wxWindows 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::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 wxWindows was compiled with
+{\tt WXWIN\_COMPATIBILITY\_2\_2} defined and will disappear completely in
+future versions.
+
+
+\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 choice by passing the desired string position. This does not cause
+any command events to get emitted.
+
+\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{void}{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{See also}
+
+\helpref{SetSelection}{wxcontrolwithitemssetselection}
+
+
projects / wxWidgets.git / commitdiff
