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 \wxheading{Example}
  35
  36 \begin{verbatim}
  37     // this part might be in a header or source (.cpp) file
  38     class MyListElement
  39     {
  40         ... // whatever
  41     };
  42
  43     // this macro declares and partly implements MyList class
  44     WX_DECLARE_LIST(MyListElement, MyList);
  45
  46     ...
  47
  48     // the only requirement for the rest is to be AFTER the full declaration of
  49     // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but
  50     // usually it will be found in the source file and not in the header
  51
  52     #include <wx/listimpl.cpp>
  53     WX_DEFINE_LIST(MyList);
  54
  55
  56     MyList list;
  57     MyListElement element;
  58     list.Append(&element);     // ok
  59     list.Append(17);           // error: incorrect type
  60
  61     // let's iterate over the list in STL syntax
  62     MyList::iterator iter;
  63     for (iter = list.begin(); iter != list.end(); ++iter)
  64     {
  65         MyListElement *current = *iter;
  66
  67         ...process the current element...
  68     }
  69
  70     // the same with the legacy API from the old wxList class
  71     MyList::compatibility_iterator node = list.GetFirst();
  72     while (node)
  73     {
  74         MyListElement *current = node->GetData();
  75
  76         ...process the current element...
  77
  78         node = node->GetNext();
  79     }
  80
  81 \end{verbatim}
  82
  83 For compatibility with previous versions wxList and wxStringList classes are
  84 still defined, but their usage is deprecated and they will disappear in the
  85 future versions completely. The use of the latter is especially discouraged as
  86 it is not only unsafe but is also much less efficient than
  87 \helpref{wxArrayString}{wxarraystring} class.
  88
  89 \wxheading{Include files}
  90
  91 <wx/list.h>
  92
  93 \wxheading{Library}
  94
  95 \helpref{wxBase}{librarieslist}
  96
  97 \wxheading{See also}
  98
  99 \helpref{wxArray}{wxarray}
 100
 101 \latexignore{\rtfignore{\wxheading{Members}}}
 102
 103 \membersection{wxList<T>::wxList<T>}\label{wxlistctor}
 104
 105 \func{}{wxList<T>}{\void}
 106
 107 \func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}}
 108
 109 Constructors.
 110
 111 \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}
 112
 113 \func{}{\destruct{wxList<T>}}{\void}
 114
 115 Destroys the list, but does not delete the objects stored in the list
 116 unless you called DeleteContents({\tt true} ).
 117
 118 \membersection{wxList<T>::Append}\label{wxlistappend}
 119
 120 \func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}}
 121
 122 Appends the pointer to \rtfsp{\it object} to the list.
 123
 124 \membersection{wxList<T>::Clear}\label{wxlistclear}
 125
 126 \func{void}{Clear}{\void}
 127
 128 Clears the list, but does not delete the objects stored in the list
 129 unless you called DeleteContents({\tt true} ).
 130
 131 \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}
 132
 133 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 134
 135 If {\it destroy} is {\tt true}, instructs the list to call {\it delete}
 136 on objects stored in the list whenever they are removed.
 137 The default is {\tt false}.
 138
 139 \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}
 140
 141 \func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}}
 142
 143 Deletes the given element refered to by {\tt iter} from the list,
 144 returning {\tt true} if successful.
 145
 146 \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}
 147
 148 \func{bool}{DeleteObject}{\param{T *}{object}}
 149
 150 Finds the given {\it object} and removes it from the list, returning
 151 {\tt true} if successful. The application must delete the actual object
 152 separately.
 153
 154 \membersection{wxList<T>::Erase}\label{wxlisterase}
 155
 156 \func{void}{Erase}{\param{const compatibility\_iterator &}{iter}}
 157
 158 Removes element refered to be {\tt iter}.
 159
 160 \membersection{wxList<T>::Find}\label{wxlistfind}
 161
 162 \constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}}
 163
 164 Returns the iterator refering to {\it object} or NULL if none found.
 165
 166 \membersection{wxList<T>::GetCount}\label{wxlistgetcount}
 167
 168 \constfunc{size\_t}{GetCount}{\void}
 169
 170 Returns the number of elements in the list.
 171
 172 \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}
 173
 174 \constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void}
 175
 176 Returns the first iterator in the list (NULL if the list is empty).
 177
 178 \membersection{wxList<T>::GetLast}\label{wxlistgetlast}
 179
 180 \constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void}
 181
 182 Returns the last iterator in the list (NULL if the list is empty).
 183
 184 \membersection{wxList<T>::IndexOf}\label{wxlistindexof}
 185
 186 \constfunc{int}{IndexOf}{\param{T*}{ obj }}
 187
 188 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
 189 {\it obj} is not found in the list.
 190
 191 \membersection{wxList<T>::Insert}\label{wxlistinsert}
 192
 193 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}}
 194
 195 Insert object at the front of list.
 196
 197 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
 198
 199 Insert object before {\it position}, i.e. the index of the new item in the
 200 list will be equal to {\it position}. {\it position} should be less than or
 201 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
 202 same as calling \helpref{Append}{wxlistappend}.
 203
 204 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}}
 205
 206 Inserts the object before the object refered to be {\it iter}.
 207
 208 \membersection{wxList<T>::IsEmpty}\label{wxlistisempty}
 209
 210 \constfunc{bool}{IsEmpty}{\void}
 211
 212 Returns {\tt true} if the list is empty, {\tt false} otherwise.
 213
 214 % Use different label name to avoid clashing with wxListItem label
 215 \membersection{wxList<T>::Item}\label{wxlistitemfunc}
 216
 217 \constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}}
 218
 219 Returns the iterator refering to the object at the given
 220 {\tt index} in the list.
 221
 222 \membersection{wxList<T>::Member}\label{wxlistmember}
 223
 224 \constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}}
 225
 226 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
 227
 228 \membersection{wxList<T>::Nth}\label{wxlistnth}
 229
 230 \constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}}
 231
 232 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
 233
 234 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 235 or the nth node could not be found).
 236
 237 \membersection{wxList<T>::Number}\label{wxlistnumber}
 238
 239 \constfunc{int}{Number}{\void}
 240
 241 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
 242
 243 Returns the number of elements in the list.
 244
 245 \membersection{wxList<T>::Sort}\label{wxlistsort}
 246
 247 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 248
 249 \begin{verbatim}
 250   // Type of compare function for list sort operation (as in 'qsort')
 251   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 252 \end{verbatim}
 253
 254 Allows the sorting of arbitrary lists by giving a function to compare
 255 two list elements. We use the system {\bf qsort} function for the actual
 256 sorting process.
 257