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{See also}
  94
  95 \helpref{wxArray}{wxarray}
  96
  97 \latexignore{\rtfignore{\wxheading{Members}}}
  98
  99 \membersection{wxList<T>::wxList<T>}\label{wxlistctor}
 100
 101 \func{}{wxList<T>}{\void}
 102
 103 \func{}{wxList<T>}{\param{size_t}{ count}, \param{T *}{elements[]}}
 104
 105 Constructors.
 106
 107 \membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor}
 108
 109 \func{}{\destruct{wxList<T>}}{\void}
 110
 111 Destroys the list, but does not delete the objects stored in the list
 112 unless you called DeleteContents({\tt true} ).
 113
 114 \membersection{wxList<T>::Append}\label{wxlistappend}
 115
 116 \func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}}
 117
 118 Appends the pointer to \rtfsp{\it object} to the list.
 119
 120 \membersection{wxList<T>::Clear}\label{wxlistclear}
 121
 122 \func{void}{Clear}{\void}
 123
 124 Clears the list, but does not delete the objects stored in the list
 125 unless you called DeleteContents({\tt true} ).
 126
 127 \membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents}
 128
 129 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 130
 131 If {\it destroy} is {\tt true}, instructs the list to call {\it delete}
 132 on objects stored in the list whenever they are removed.
 133 The default is {\tt false}.
 134
 135 \membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode}
 136
 137 \func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}}
 138
 139 Deletes the given element refered to by {\tt iter} from the list,
 140 returning {\tt true} if successful.
 141
 142 \membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject}
 143
 144 \func{bool}{DeleteObject}{\param{T *}{object}}
 145
 146 Finds the given {\it object} and removes it from the list, returning
 147 {\tt true} if successful. The application must delete the actual object
 148 separately.
 149
 150 \membersection{wxList<T>::Erase}\label{wxlisterase}
 151
 152 \func{void}{Erase}{\param{const compatibility\_iterator &}{iter}}
 153
 154 Removes element refered to be {\tt iter}.
 155
 156 \membersection{wxList<T>::Find}\label{wxlistfind}
 157
 158 \constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}}
 159
 160 Returns the iterator refering to {\it object} or NULL if none found.
 161
 162 \membersection{wxList<T>::GetCount}\label{wxlistgetcount}
 163
 164 \constfunc{size\_t}{GetCount}{\void}
 165
 166 Returns the number of elements in the list.
 167
 168 \membersection{wxList<T>::GetFirst}\label{wxlistgetfirst}
 169
 170 \constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void}
 171
 172 Returns the first iterator in the list (NULL if the list is empty).
 173
 174 \membersection{wxList<T>::GetLast}\label{wxlistgetlast}
 175
 176 \constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void}
 177
 178 Returns the last iterator in the list (NULL if the list is empty).
 179
 180 \membersection{wxList<T>::IndexOf}\label{wxlistindexof}
 181
 182 \constfunc{int}{IndexOf}{\param{T*}{ obj }}
 183
 184 Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if
 185 {\it obj} is not found in the list.
 186
 187 \membersection{wxList<T>::Insert}\label{wxlistinsert}
 188
 189 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}}
 190
 191 Insert object at the front of list.
 192
 193 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}}
 194
 195 Insert object before {\it position}, i.e. the index of the new item in the
 196 list will be equal to {\it position}. {\it position} should be less than or
 197 equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the
 198 same as calling \helpref{Append}{wxlistappend}.
 199
 200 \func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}}
 201
 202 Inserts the object before the object refered to be {\it iter}.
 203
 204 \membersection{wxList<T>::IsEmpty}\label{wxlistisempty}
 205
 206 \constfunc{bool}{IsEmpty}{\void}
 207
 208 Returns {\tt true} if the list is empty, {\tt false} otherwise.
 209
 210 % Use different label name to avoid clashing with wxListItem label
 211 \membersection{wxList<T>::Item}\label{wxlistitemfunc}
 212
 213 \constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}}
 214
 215 Returns the iterator refering to the object at the given
 216 {\tt index} in the list.
 217
 218 \membersection{wxList<T>::Member}\label{wxlistmember}
 219
 220 \constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}}
 221
 222 {\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead.
 223
 224 \membersection{wxList<T>::Nth}\label{wxlistnth}
 225
 226 \constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}}
 227
 228 {\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead.
 229
 230 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 231 or the nth node could not be found).
 232
 233 \membersection{wxList<T>::Number}\label{wxlistnumber}
 234
 235 \constfunc{int}{Number}{\void}
 236
 237 {\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead.
 238
 239 Returns the number of elements in the list.
 240
 241 \membersection{wxList<T>::Sort}\label{wxlistsort}
 242
 243 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 244
 245 \begin{verbatim}
 246   // Type of compare function for list sort operation (as in 'qsort')
 247   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 248 \end{verbatim}
 249
 250 Allows the sorting of arbitrary lists by giving a function to compare
 251 two list elements. We use the system {\bf qsort} function for the actual
 252 sorting process.
 253