undefine _DEFINE_LIST before redefining it; also rename it to have WX prefix

[wxWidgets.git] / docs / latex / wx / ctrlsub.tex

diff --git a/docs/latex/wx/ctrlsub.tex b/docs/latex/wx/ctrlsub.tex
index fe7dbbf5fe50e3f119ad9ece7c658df72c9eda60..deae9e7dca6225d40ab76e80d321ca2ff10dcc74 100644 (file)
--- a/docs/latex/wx/ctrlsub.tex
+++ b/docs/latex/wx/ctrlsub.tex
@@ -6,27 +6,27 @@
 %% Created:     01.01.03
 %% RCS-ID:      $Id$
 %% Copyright:   (c) 2003 Vadim Zeitlin
 %% Created:     01.01.03
 %% RCS-ID:      $Id$
 %% Copyright:   (c) 2003 Vadim Zeitlin

-%% License:     wxWidgets license
+%% License:     wxWindows license

 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxControlWithItems}}\label{wxcontrolwithitems}
 
 This class is an abstract base class for some wxWidgets controls which contain
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \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, 
+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.
 
 \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,
+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
 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 
+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
 \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


@@ -44,6 +44,10 @@ client data pointer) or \helpref{SetClientData}{wxcontrolwithitemssetclientdata}
 
 <wx/ctrlsub.h> but usually never included directly
 
 
 <wx/ctrlsub.h> but usually never included directly
 

+\wxheading{Library}
+
+\helpref{wxCore}{librarieslist}
+

 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxControlWithItems::Append}\label{wxcontrolwithitemsappend}
 \latexignore{\rtfignore{\wxheading{Members}}}
 
 \membersection{wxControlWithItems::Append}\label{wxcontrolwithitemsappend}


@@ -61,15 +65,27 @@ untyped, client data pointer with the item.
 
 \func{void}{Append}{\param{const wxArrayString\& }{strings}}
 
 
 \func{void}{Append}{\param{const wxArrayString\& }{strings}}
 

+\func{void}{Append}{\param{unsigned int }{n},\param{const wxString* }{strings}}
+
+\func{void}{Append}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{void **}{clientData}}
+
+\func{void}{Append}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{wxClientData **}{clientData}}
+

 Appends several items at once to the control. Notice that calling this method
 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
+is usually much faster than appending them one by one if you need to add a lot

 of items.
 
 \wxheading{Parameters}
 
 \docparam{item}{String to add.}
 
 of items.
 
 \wxheading{Parameters}
 
 \docparam{item}{String to add.}
 

-\docparam{clientData}{Client data to associate with the item.}
+\docparam{stringsArray}{Contains items to append to the control.}
+
+\docparam{strings}{Array of strings of size \arg{n}.}
+
+\docparam{n}{Number of items in the \arg{strings} array.}
+
+\docparam{clientData}{Array of client data pointers of size \arg{n} to associate with the new items.}

 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 


@@ -88,7 +104,7 @@ by the control.
 
 \membersection{wxControlWithItems::Delete}\label{wxcontrolwithitemsdelete}
 
 
 \membersection{wxControlWithItems::Delete}\label{wxcontrolwithitemsdelete}
 

-\func{void}{Delete}{\param{int}{ n}}
+\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.
 
 Deletes an item from the control. The client data associated with the item
 will be also deleted if it is owned by the control.


@@ -107,7 +123,7 @@ items in the control.
 
 \membersection{wxControlWithItems::FindString}\label{wxcontrolwithitemsfindstring}
 
 
 \membersection{wxControlWithItems::FindString}\label{wxcontrolwithitemsfindstring}
 

-\func{int}{FindString}{\param{const wxString\& }{string}}
+\func{int}{FindString}{\param{const wxString\& }{string}, \param{bool}{ caseSensitive = false}}

 
 Finds an item whose label matches the given string.
 
 
 Finds an item whose label matches the given string.
 


@@ -115,6 +131,8 @@ Finds an item whose label matches the given string.
 
 \docparam{string}{String to find.}
 
 
 \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
 \wxheading{Return value}
 
 The zero-based position of the item, or {\tt wxNOT\_FOUND} if the string was


@@ -123,7 +141,7 @@ not found.
 
 \membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
 
 
 \membersection{wxControlWithItems::GetClientData}\label{wxcontrolwithitemsgetclientdata}
 

-\constfunc{void *}{GetClientData}{\param{int}{ n}}
+\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
 
 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


@@ -141,7 +159,7 @@ A pointer to the client data, or {\tt NULL} if not present.
 
 \membersection{wxControlWithItems::GetClientObject}\label{wxcontrolwithitemsgetclientobject}
 
 
 \membersection{wxControlWithItems::GetClientObject}\label{wxcontrolwithitemsgetclientobject}
 

-\constfunc{wxClientData *}{GetClientObject}{\param{int}{ n}}
+\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
 
 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


@@ -159,7 +177,7 @@ A pointer to the client data, or {\tt NULL} if not present.
 
 \membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount}
 
 
 \membersection{wxControlWithItems::GetCount}\label{wxcontrolwithitemsgetcount}
 

-\constfunc{int}{GetCount}{\void}
+\constfunc{unsigned int}{GetCount}{\void}

 
 Returns the number of items in the control.
 
 
 Returns the number of items in the control.
 


@@ -181,7 +199,7 @@ The position of the current selection.
 
 \wxheading{Remarks}
 
 
 \wxheading{Remarks}
 

-This method can be used with single selection list boxes only, you should use 
+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.
 
 \helpref{wxListBox::GetSelections}{wxlistboxgetselections} for the list boxes
 with {\tt wxLB\_MULTIPLE} style.
 


@@ -193,7 +211,7 @@ with {\tt wxLB\_MULTIPLE} style.
 
 \membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}
 
 
 \membersection{wxControlWithItems::GetString}\label{wxcontrolwithitemsgetstring}
 

-\constfunc{wxString}{GetString}{\param{int}{ n}}
+\constfunc{wxString}{GetString}{\param{unsigned int}{ n}}

 
 Returns the label of the item with the given index.
 
 
 Returns the label of the item with the given index.
 


@@ -206,6 +224,13 @@ Returns the label of the item with the given index.
 The label of the item or an empty string if the position was invalid.
 
 
 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}
 \membersection{wxControlWithItems::GetStringSelection}\label{wxcontrolwithitemsgetstringselection}
 
 \constfunc{wxString}{GetStringSelection}{\void}


@@ -220,26 +245,47 @@ selected.
 
 \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
 
 
 \membersection{wxControlWithItems::Insert}\label{wxcontrolwithitemsinsert}
 

-\func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}}
+\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.
 
 
 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{unsigned int }{pos}, \param{void *}{clientData}}

 
 

-\func{int}{Insert}{\param{const wxString\& }{ item}, \param{int }{pos}, \param{wxClientData *}{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.
 
 
 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.
 

+\func{void}{Insert}{\param{const wxArrayString\& }{strings}, \param{unsigned int }{pos}}
+
+\func{void}{Insert}{\param{const wxArrayString\& }{strings}, \param{unsigned int }{pos}}
+
+\func{void}{Insert}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{unsigned int }{pos}}
+
+\func{void}{Insert}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{unsigned int }{pos}, \param{void **}{clientData}}
+
+\func{void}{Insert}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{unsigned int }{pos}, \param{wxClientData **}{clientData}}
+
+Inserts several items at once into the control. Notice that calling this method
+is usually much faster than inserting them one by one if you need to insert a lot
+of items.
+
+

 \wxheading{Parameters}
 
 \docparam{item}{String to add.}
 
 \docparam{pos}{Position to insert item before, zero based.}
 
 \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.}
+\docparam{stringsArray}{Contains items to insert into the control content}
+
+\docparam{strings}{Array of strings of size \arg{n}.}
+
+\docparam{n}{Number of items in the \arg{strings} array.}
+
+\docparam{clientData}{Array of client data pointers of size \arg{n} to associate with the new items.}

 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 


@@ -258,20 +304,65 @@ Returns {\tt true} if the control is empty or {\tt false} if it has some items.
 \helpref{GetCount}{wxcontrolwithitemsgetcount}
 
 
 \helpref{GetCount}{wxcontrolwithitemsgetcount}
 
 

-\membersection{wxControlWithItems::Number}\label{wxcontrolwithitemsnumber}
+\membersection{wxControlWithItems::Select}\label{wxcontrolwithitemsselect}
+
+\func{void}{Select}{\param{int}{ n}}

 
 

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

 
 

-{\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::Set}\label{wxcontrolwithitemsset}
+
+\func{int}{Set}{\param{const wxString\& }{ item}}
+
+\func{int}{Set}{\param{const wxString\& }{ item}, \param{void *}{clientData}}
+
+\func{int}{Set}{\param{const wxString\& }{ item}, \param{wxClientData *}{clientData}}
+
+Replace control items with the (only) item specified, associating the typed or
+untyped client data pointer with it if given.
+
+\func{void}{Set}{\param{const wxArrayString\& }{stringsArray}}
+
+\func{void}{Set}{\param{unsigned int }{n},\param{const wxString* }{strings}}
+
+\func{void}{Set}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{void **}{clientData}}
+
+\func{void}{Set}{\param{unsigned int }{n},\param{const wxString* }{strings}, \param{wxClientData **}{clientData}}
+
+Replaces the current control contents with the given items. Notice that calling
+this method is much faster than appending the items one by one if you need to
+append a lot of them.
+
+\wxheading{Parameters}
+
+\docparam{item}{The single item to insert into the control.}
+
+\docparam{stringsArray}{Contains items to set as control content.}
+
+\docparam{strings}{Raw C++ array of strings. Only used in conjunction with 'n'.}
+
+\docparam{n}{Number of items passed in 'strings'. Only used in conjunction with 'strings'.}
+
+\docparam{clientData}{Client data to associate with the item(s).}
+
+\wxheading{Return value}
+
+When the control is sorted (e.g. has {\tt wxLB\_SORT} or {\tt wxCB\_SORT} style)
+the return value could be different from (GetCount() - 1).
+When setting a single item to the container, 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).
+
+By default this method subsequently calls \helpref{Clear}{wxcontrolwithitemsclear}
+and \helpref{Append}{wxcontrolwithitemsappend}.

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

-\func{void}{SetClientData}{\param{int}{ n}, \param{void *}{data}}
+\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
 
 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


@@ -286,9 +377,9 @@ associated with the control items before.
 
 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 
 
 \membersection{wxControlWithItems::SetClientObject}\label{wxcontrolwithitemssetclientobject}
 

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

 
 

-Associates the given typed client data pointer with the given item: the 
+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).
 {\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).


@@ -310,7 +401,8 @@ pointers had been associated with the control items before.
 Sets the selection to the given item \arg{n} or removes the selection entirely
 if \arg{n} $==$ {\tt wxNOT\_FOUND}.
 
 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.
+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}
 
 
 \wxheading{Parameters}
 


@@ -324,7 +416,7 @@ Note that this does not cause any command events to be emitted.
 
 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 
 
 \membersection{wxControlWithItems::SetString}\label{wxcontrolwithitemssetstring}
 

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

 
 Sets the label for the given item.
 
 
 Sets the label for the given item.
 


@@ -337,17 +429,21 @@ Sets the label for the given item.
 
 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 
 
 \membersection{wxControlWithItems::SetStringSelection}\label{wxcontrolwithitemssetstringselection}
 

-\func{void}{SetStringSelection}{\param{const wxString\& }{ string}}
+\func{bool}{SetStringSelection}{\param{const wxString\& }{ string}}

 
 Selects the item with the specified string in the control. This doesn't cause
 
 Selects the item with the specified string in the control. This doesn't cause

-any command events being emitted.
+any command events to be emitted.

 
 \wxheading{Parameters}
 
 \docparam{string}{The string to select.}
 
 
 \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}
 
 \wxheading{See also}
 
 \helpref{SetSelection}{wxcontrolwithitemssetselection}
 

-