X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/2edb0bdef6238c8c246b6978bc14828b7033d931..d3e78bab3ea46183c22a5f0484b931a99b897636:/docs/latex/wx/list.tex?ds=inline diff --git a/docs/latex/wx/list.tex b/docs/latex/wx/list.tex index f7a6cd830a..ba7fef8068 100644 --- a/docs/latex/wx/list.tex +++ b/docs/latex/wx/list.tex @@ -2,7 +2,8 @@ wxList classes provide linked list functionality for wxWindows, and for an application if it wishes. Depending on the form of constructor used, a list -can be keyed on integer or string keys to provide a primitive look-up ability. +can be keyed on integer or string keys to provide a primitive look-up ability, +but please note that this feature is {\bf deprecated}. See \helpref{wxHashMap}{wxhashmap}\rtfsp for a faster method of storage when random access is required. @@ -68,9 +69,11 @@ future versions completely. The use of the latter is especially discouraged as it is not only unsafe but is also much less efficient than \helpref{wxArrayString}{wxarraystring} class. -In the documentation of the list classes below, you should replace wxNode with -wxListName::Node and wxObject with the list element type (i.e. the first -parameter of WX\_DECLARE\_LIST) for the template lists. +In the documentation of the list classes below, the template notations are +used even though these classes are not really templates at all -- but it helps +to think about them as if they were. You should replace wxNode with +wxListName::Node and T itself with the list element type (i.e. the first +parameter of WX\_DECLARE\_LIST). \wxheading{Derived from} @@ -136,11 +139,13 @@ members for getting to the next or previous node. \func{}{wxList}{\void} -\func{}{wxList}{\param{unsigned int}{ key\_type}} +\func{}{wxList}{\param{int}{ n}, \param{T *}{objects[]}} + +\func{}{wxList}{\param{T *}{object}, ...} -\func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}} +{\bf Note}: keyed lists are deprecated and should not be used in new code. -\func{}{wxList}{\param{wxObject *}{object}, ...} +\func{}{wxList}{\param{unsigned int}{ key\_type}} Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING, and indicates what sort of keying is required (if any). @@ -159,15 +164,18 @@ client data held in the nodes. \membersection{wxList::Append}\label{wxlistappend} -\func{wxNode *}{Append}{\param{wxObject *}{object}} +\func{wxNode *}{Append}{\param{T *}{object}} -\func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}} +{\bf Note}: keyed lists are deprecated and should not be used in new code. -\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}} +\func{wxNode *}{Append}{\param{long}{ key}, \param{T *}{object}} -Appends a new {\bf wxNode} to the end of the list and puts a pointer to the -\rtfsp{\it object} in the node. The last two forms store a key with the object for -later retrieval using the key. The new node is returned in each case. +\func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{T *}{object}} + +Appends a new \helpref{wxNode}{wxnode} to the end of the list and puts a +pointer to the \rtfsp{\it object} in the node. The last two forms store a key +with the object for later retrieval using the key. The new node is returned in +each case. The key string is copied and stored by the list implementation. @@ -176,33 +184,39 @@ The key string is copied and stored by the list implementation. \func{void}{Clear}{\void} Clears the list (but does not delete the client data stored with each node -unless you called DeleteContents(TRUE), in which case it deletes data). +unless you called DeleteContents({\tt true}), in which case it deletes data). \membersection{wxList::DeleteContents}\label{wxlistdeletecontents} \func{void}{DeleteContents}{\param{bool}{ destroy}} -If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of -a node whenever the node is destroyed. The default is FALSE. +If {\it destroy} is {\tt true}, instructs the list to call {\it delete} on the client contents of +a node whenever the node is destroyed. The default is {\tt false}. \membersection{wxList::DeleteNode}\label{wxlistdeletenode} -\func{bool}{DeleteNode}{\param{wxNode *}{node}} +\func{bool}{DeleteNode}{\param{wxNode *}{node}} -Deletes the given node from the list, returning TRUE if successful. +Deletes the given node from the list, returning {\tt true} if successful. \membersection{wxList::DeleteObject}\label{wxlistdeleteobject} -\func{bool}{DeleteObject}{\param{wxObject *}{object}} +\func{bool}{DeleteObject}{\param{T *}{object}} Finds the given client {\it object} and deletes the appropriate node from the list, returning -TRUE if successful. The application must delete the actual object separately. +{\tt true} if successful. The application must delete the actual object separately. \membersection{wxList::Find}\label{wxlistfind} -\func{wxNode *}{Find}{\param{long}{ key}} +\func{wxNode *}{Find}{\param{T *}{ object}} + +Returns the node whose client date is {\it object} or NULL if none found. -\func{wxNode *}{Find}{\param{const wxString\& }{key}} +{\bf Note}: keyed lists are deprecated and should not be used in new code. + +\func{wxNode *}{Find}{\param{long}{ key}} + +\func{wxNode *}{Find}{\param{const wxString\& }{key}} Returns the node whose stored key matches {\it key}. Use on a keyed list only. @@ -214,49 +228,56 @@ Returns the number of elements in the list. \membersection{wxList::GetFirst}\label{wxlistgetfirst} -\func{wxNode *}{GetFirst}{\void} +\func{wxNode *}{GetFirst}{\void} Returns the first node in the list (NULL if the list is empty). \membersection{wxList::GetLast}\label{wxlistgetlast} -\func{wxNode *}{GetLast}{\void} +\func{wxNode *}{GetLast}{\void} Returns the last node in the list (NULL if the list is empty). \membersection{wxList::IndexOf}\label{wxlistindexof} -\func{int}{IndexOf}{\param{wxObject*}{ obj }} +\func{int}{IndexOf}{\param{T*}{ obj }} Returns the index of {\it obj} within the list or wxNOT\_FOUND if {\it obj} is not found in the list. \membersection{wxList::Insert}\label{wxlistinsert} -\func{wxNode *}{Insert}{\param{wxObject *}{object}} +\func{wxNode *}{Insert}{\param{T *}{object}} Insert object at front of list. -\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{wxObject *}{object}} +\func{wxNode *}{Insert}{\param{size\_t }{position}, \param{T *}{object}} Insert object before {\it position}, i.e. the index of the new item in the list will be equal to {\it position}. {\it position} should be less than or equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the same as calling \helpref{Append}{wxlistappend}. -\func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{wxObject *}{object}} +\func{wxNode *}{Insert}{\param{wxNode *}{node}, \param{T *}{object}} Inserts the object before the given {\it node}. -\membersection{wxList::Item}\label{wxlistitem} +\membersection{wxList::IsEmpty}\label{wxlistisempty} + +\constfunc{bool}{IsEmpty}{\void} + +Returns {\tt true} if the list is empty, {\tt false} otherwise. + +% Use different label name to avoid clashing with wxListItem label +\membersection{wxList::Item}\label{wxlistitemfunc} -\constfunc{wxNode *}{Item}{\param{size\_t }{index}} +\constfunc{wxNode *}{Item}{\param{size\_t }{index}} Returns the node at given position in the list. \membersection{wxList::Member}\label{wxlistmember} -\func{wxNode *}{Member}{\param{wxObject *}{object}} +\func{wxNode *}{Member}{\param{T *}{object}} {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. @@ -264,9 +285,9 @@ Returns the node associated with {\it object} if it is in the list, NULL otherwi \membersection{wxList::Nth}\label{wxlistnth} -\func{wxNode *}{Nth}{\param{int}{ n}} +\func{wxNode *}{Nth}{\param{int}{ n}} -{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitem} instead. +{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead. Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty or the nth node could not be found).