b4a980f4f5
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@45395 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
366 lines
11 KiB
TeX
366 lines
11 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% 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{unsigned 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}, \param{bool}{ caseSensitive = false}}
|
|
|
|
Finds an item whose label matches the given string.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{string}{String to find.}
|
|
|
|
\docparam{caseSensitive}{Whether search is case sensitive (default is not).}
|
|
|
|
\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{unsigned 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{unsigned 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{unsigned 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{unsigned 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::GetStrings}\label{wxcontrolwithitemsgetstrings}
|
|
|
|
\constfunc{wxArrayString}{GetStrings}{\void}
|
|
|
|
Returns the array of the labels of all items in the control.
|
|
|
|
|
|
\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{unsigned 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{unsigned int }{pos}, \param{void *}{clientData}}
|
|
|
|
\func{int}{Insert}{\param{const wxString\& }{ item}, \param{unsigned 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::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{unsigned 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{unsigned 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{unsigned 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 to be 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}
|
|
|