docs/latex/wx/list.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        list.tex
   3 %% Purpose:     wxList
   4 %% Author:      wxWidgets Team
   5 %% Modified by:
   6 %% Created:
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) wxWidgets Team
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxList<T>}}\label{wxlist}
  13
  14 The wxList<T> class provides linked list functionality. It has been written
  15 to be type safe and to provide the full API of the STL std::list container and
  16 should be used like it. The exception is that wxList<T> actually stores
  17 pointers and therefore its iterators return pointers and not references
  18 to the actual objets in the list (see example below). Unfortunately, the
  19 new wxList<T> class requires that you declare and define each wxList<T>
  20 class in your program. This is done with {\it WX\_DECLARE\_LIST} and
  21 {\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able
  22 to provide a proper template class providing both the STL std::list
  23 and the old wxList API in the future.
  24
  25 Please refer to the STL std::list documentation for further
  26 information on how to use the class. Below we documented the legacy
  27 API that originated from the old wxList class and which can still
  28 be used alternatively for the the same class.
  29
  30 Note that if you compile wxWidgets in STL mode (wxUSE_STL defined as 1)
  31 then wxList<T> will actually derive from std::list and just add a legacy
  32 compatibility layer for the old wxList class.
  33
  34 each list type (i.e. list of ints, of wxStrings or of MyObjects).
  35
  36 \wxheading{Example}
  37
  38 \begin{verbatim}
  39     // this part might be in a header or source (.cpp) file
  40     class MyListElement
  41     {
  42         ... // whatever
  43     };
  44
  45     // this macro declares and partly implements MyList class
  46     WX_DECLARE_LIST(MyListElement, MyList);
  47
  48     ...
  49
  50     // the only requirement for the rest is to be AFTER the full declaration of
  51     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
  52     // usually it will be found in the source file and not in the header
  53
  54     #include <wx/listimpl.cpp>
  55     WX_DEFINE_LIST(MyList);
  56
  57
  58
  59     MyList list;
  60     MyListElement element;
  61     list.Append(&element);     // ok
  62     list.Append(17);           // error: incorrect type
  63
  64     // let's iterate over the list in STL syntax
  65     MyList::iterator iter;
  66     for (iter = list.begin(); iter != list.end(); ++iter)
  67     {
  68         MyListElement *current = *iter;
  69
  70         ...process the current element...
  71     }
  72
  73     // the same with the legacy API from the old wxList class
  74     MyList::compatibility_iterator node = list.GetFirst();
  75     while (node)
  76     {
  77         MyListElement *current = node->GetData();
  78
  79         ...process the current element...
  80
  81         node = node->GetNext();
  82     }
  83
  84 \end{verbatim}
  85
  86 For compatibility with previous versions wxList and wxStringList classes are
  87 still defined, but their usage is deprecated and they will disappear in the
  88 future versions completely. The use of the latter is especially discouraged as
  89 it is not only unsafe but is also much less efficient than
  90 \helpref{wxArrayString}{wxarraystring} class.
  91
  92 \wxheading{Include files}
  93
  94 <wx/list.h>
  95
  96 \wxheading{See also}
  97
  98 \helpref{wxArray}{wxarray}
  99
 100 \latexignore{\rtfignore{\wxheading{Members}}}
 101
 102 \membersection{wxList<T>::wxList<T>}\label{wxlistctor}
 103
 104 \func{}{wxList<T>}{\void}
 105
 106 \func{}{wxList<T>}{\param{size_t}{ count}, \param{T *}{elements[]}}
 107
 108 Constructors.
 109
 110 \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}
 111
 112 \func{}{\destruct{wxList<T>}}{\void}
 113
 114 Destroys the list, but does not delete the objects stored in the list
 115 unless you called DeleteContents({\tt true} ).
 116
 117 \membersection{wxList<T>::Append}\label{wxlistappend}
 118
 119 \func{wxList<T>::compatibility_iterator }{Append}{\param{T *}{object}}
 120
 121 Appends the pointer to \rtfsp{\it object} to the list.
 122
 123 \membersection{wxList<T>::Clear}\label{wxlistclear}
 124
 125 \func{void}{Clear}{\void}
 126
 127 Clears the list, but does not delete the objects stored in the list
 128 unless you called DeleteContents({\tt true} ).
 129
 130 \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}
 131
 132 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 133
 134 If {\it destroy} is {\tt true}, instructs the list to call {\it delete}
 135 on objects stored in the list whenever they are removed.
 136 The default is {\tt false}.
 137
 138 \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}
 139
 140 \func{bool}{DeleteNode}{\param{const compatibility_iterator &}{iter}}
 141
 142 Deletes the given element refered to by {\tt iter} from the list,
 143 returning {\tt true} if successful.
 144
 145 \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}
 146
 147 \func{bool}{DeleteObject}{\param{T *}{object}}
 148
 149 Finds the given {\it object} and removes it from the list, returning
 150 {\tt true} if successful. The application must delete the actual object
 151 separately.
 152
 153 \membersection{wxList<T>::Erase}\label{wxlisterase}
 154
 155 \func{void}{Erase}{\param{const compatibility_iterator &}{iter}}
 156
 157 Removes element refered to be {\tt iter}.
 158
 159 \membersection{wxList<T>::Find}\label{wxlistfind}
 160
 161 \constfunc{wxList<T>::compatibility_iterator}{Find}{\param{T *}{ object}}
 162
 163 Returns the iterator refering to {\it object} or NULL if none found.
 164
 165 \membersection{wxList<T>::GetCount}\label{wxlistgetcount}
 166
 167 \constfunc{size\_t}{GetCount}{\void}
 168
 169 Returns the number of elements in the list.
 170
 171 \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}
 172
 173 \constfunc{wxList<T>::compatibility_iterator}{GetFirst}{\void}
 174
 175 Returns the first iterator in the list (NULL if the list is empty).
 176
 177 \membersection{wxList<T>::GetLast}\label{wxlistgetlast}
 178
 179 \constfunc{wxList<T>::compatibility_iterator}{GetLast}{\void}
 180
 181 Returns the last iterator in the list (NULL if the list is empty).
 182
 183 \membersection{wxList<T>::IndexOf}\label{wxlistindexof}
 184
 185 \constfunc{int}{IndexOf}{\param{T*}{ obj }}
 186
 187 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
 188 {\it obj} is not found in the list.
 189
 190 \membersection{wxList<T>::Insert}\label{wxlistinsert}
 191
 192 \func{wxList<T>::compatibility_iterator}{Insert}{\param{T *}{object}}
 193
 194 Insert object at the front of list.
 195
 196 \func{wxList<T>::compatibility_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
 197
 198 Insert object before {\it position}, i.e. the index of the new item in the
 199 list will be equal to {\it position}. {\it position} should be less than or
 200 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
 201 same as calling \helpref{Append}{wxlistappend}.
 202
 203 \func{wxList<T>::compatibility_iterator}{Insert}{\param{compatibility_iterator}{iter}, \param{T *}{object}}
 204
 205 Inserts the object before the object refered to be {\it iter}.
 206
 207 \membersection{wxList<T>::IsEmpty}\label{wxlistisempty}
 208
 209 \constfunc{bool}{IsEmpty}{\void}
 210
 211 Returns {\tt true} if the list is empty, {\tt false} otherwise.
 212
 213 % Use different label name to avoid clashing with wxListItem label
 214 \membersection{wxList<T>::Item}\label{wxlistitemfunc}
 215
 216 \constfunc{wxList<T>::compatibility_iterator}{Item}{\param{size\_t }{index}}
 217
 218 Returns the iterator refering to the object at the given
 219 {\tt index} in the list.
 220
 221 \membersection{wxList<T>::Member}\label{wxlistmember}
 222
 223 \constfunc{wxList<T>::compatibility_iterator}{Member}{\param{T *}{ object}}
 224
 225 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
 226
 227 \membersection{wxList<T>::Nth}\label{wxlistnth}
 228
 229 \constfunc{wxList<T>::compatibility_iterator}{Nth}{\param{int }{n}}
 230
 231 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
 232
 233 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 234 or the nth node could not be found).
 235
 236 \membersection{wxList<T>::Number}\label{wxlistnumber}
 237
 238 \constfunc{int}{Number}{\void}
 239
 240 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
 241
 242 Returns the number of elements in the list.
 243
 244 \membersection{wxList<T>::Sort}\label{wxlistsort}
 245
 246 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 247
 248 \begin{verbatim}
 249   // Type of compare function for list sort operation (as in 'qsort')
 250   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 251 \end{verbatim}
 252
 253 Allows the sorting of arbitrary lists by giving a function to compare
 254 two list elements. We use the system {\bf qsort} function for the actual
 255 sorting process.
 256