added wxControlWithItems docs, updated the others to refer to it
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@18488 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
322
docs/latex/wx/ctrlsub.tex
Normal file
322
docs/latex/wx/ctrlsub.tex
Normal file
@@ -0,0 +1,322 @@
|
||||
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
||||
%% 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}
|
||||
|
||||
|
Reference in New Issue
Block a user