1%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 2%% Name: list.tex 3%% Purpose: wxList 4%% Author: wxWidgets Team 5%% Modified by: Robert Roebling 6%% Created: 7%% RCS-ID: $Id: list.tex 48887 2007-09-21 17:53:07Z JS $ 8%% Copyright: (c) wxWidgets Team 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxList<T>}}\label{wxlist} 13 14The wxList<T> class provides linked list functionality. It has been written 15to be type safe and to provide the full API of the STL std::list container and 16should be used like it. The exception is that wxList<T> actually stores 17pointers and therefore its iterators return pointers and not references 18to the actual objets in the list (see example below). In other words 19{\it value\_type} is defined as {\it T*}. 20 21 22Unfortunately, the 23new wxList<T> class requires that you declare and define each wxList<T> 24class in your program. This is done with {\it WX\_DECLARE\_LIST} and 25{\it WX\_DEFINE\_LIST} macros (see example). We hope that we'll be able 26to provide a proper template class providing both the STL std::list 27and the old wxList API in the future. 28 29Please refer to the STL std::list documentation for further 30information on how to use the class. Below we documented both 31the supported STL and the legacy API that originated from the 32old wxList class and which can still be used alternatively for 33the the same class. 34 35Note that if you compile wxWidgets in STL mode (wxUSE\_STL defined as 1) 36then wxList<T> will actually derive from std::list and just add a legacy 37compatibility layer for the old wxList class. 38 39\wxheading{Example} 40 41\begin{verbatim} 42 // this part might be in a header or source (.cpp) file 43 class MyListElement 44 { 45 ... // whatever 46 }; 47 48 // this macro declares and partly implements MyList class 49 WX_DECLARE_LIST(MyListElement, MyList); 50 51 ... 52 53 // the only requirement for the rest is to be AFTER the full declaration of 54 // MyListElement (for WX_DECLARE_LIST forward declaration is enough), but 55 // usually it will be found in the source file and not in the header 56 57 #include <wx/listimpl.cpp> 58 WX_DEFINE_LIST(MyList); 59 60 61 MyList list; 62 MyListElement element; 63 list.Append(&element); // ok 64 list.Append(17); // error: incorrect type 65 66 // let's iterate over the list in STL syntax 67 MyList::iterator iter; 68 for (iter = list.begin(); iter != list.end(); ++iter) 69 { 70 MyListElement *current = *iter; 71 72 ...process the current element... 73 } 74 75 // the same with the legacy API from the old wxList class 76 MyList::compatibility_iterator node = list.GetFirst(); 77 while (node) 78 { 79 MyListElement *current = node->GetData(); 80 81 ...process the current element... 82 83 node = node->GetNext(); 84 } 85 86\end{verbatim} 87 88For compatibility with previous versions wxList and wxStringList classes are 89still defined, but their usage is deprecated and they will disappear in the 90future versions completely. The use of the latter is especially discouraged as 91it is not only unsafe but is also much less efficient than 92\helpref{wxArrayString}{wxarraystring} class. 93 94\wxheading{Include files} 95 96<wx/list.h> 97 98\wxheading{Library} 99 100\helpref{wxBase}{librarieslist} 101 102\wxheading{See also} 103 104\helpref{wxArray}{wxarray} 105 106\latexignore{\rtfignore{\wxheading{Members}}} 107 108\membersection{wxList<T>::wxList<T>}\label{wxlistctor} 109 110\func{}{wxList<T>}{\void} 111 112\func{}{wxList<T>}{\param{size\_t}{ count}, \param{T *}{elements[]}} 113 114Constructors. 115 116\membersection{wxList<T>::\destruct{wxList<T>}}\label{wxlistdtor} 117 118\func{}{\destruct{wxList<T>}}{\void} 119 120Destroys the list, but does not delete the objects stored in the list 121unless you called DeleteContents({\tt true} ). 122 123\membersection{wxList<T>::Append}\label{wxlistappend} 124 125\func{wxList<T>::compatibility\_iterator }{Append}{\param{T *}{object}} 126 127Appends the pointer to \rtfsp{\it object} to the list. 128 129\membersection{wxList<T>::Clear}\label{wxlistclear1} 130 131\func{void}{Clear}{\void} 132 133Clears the list, but does not delete the objects stored in the list 134unless you called DeleteContents({\tt true} ). 135 136\membersection{wxList<T>::DeleteContents}\label{wxlistdeletecontents} 137 138\func{void}{DeleteContents}{\param{bool}{ destroy}} 139 140If {\it destroy} is {\tt true}, instructs the list to call {\it delete} 141on objects stored in the list whenever they are removed. 142The default is {\tt false}. 143 144\membersection{wxList<T>::DeleteNode}\label{wxlistdeletenode} 145 146\func{bool}{DeleteNode}{\param{const compatibility\_iterator &}{iter}} 147 148Deletes the given element refered to by {\tt iter} from the list, 149returning {\tt true} if successful. 150 151\membersection{wxList<T>::DeleteObject}\label{wxlistdeleteobject} 152 153\func{bool}{DeleteObject}{\param{T *}{object}} 154 155Finds the given {\it object} and removes it from the list, returning 156{\tt true} if successful. The application must delete the actual object 157separately. 158 159\membersection{wxList<T>::Erase}\label{wxlisterase} 160 161\func{void}{Erase}{\param{const compatibility\_iterator &}{iter}} 162 163Removes element refered to be {\tt iter}. 164 165\membersection{wxList<T>::Find}\label{wxlistfind} 166 167\constfunc{wxList<T>::compatibility\_iterator}{Find}{\param{T *}{ object}} 168 169Returns the iterator refering to {\it object} or NULL if none found. 170 171\membersection{wxList<T>::GetCount}\label{wxlistgetcount} 172 173\constfunc{size\_t}{GetCount}{\void} 174 175Returns the number of elements in the list. 176 177\membersection{wxList<T>::GetFirst}\label{wxlistgetfirst} 178 179\constfunc{wxList<T>::compatibility\_iterator}{GetFirst}{\void} 180 181Returns the first iterator in the list (NULL if the list is empty). 182 183\membersection{wxList<T>::GetLast}\label{wxlistgetlast} 184 185\constfunc{wxList<T>::compatibility\_iterator}{GetLast}{\void} 186 187Returns the last iterator in the list (NULL if the list is empty). 188 189\membersection{wxList<T>::IndexOf}\label{wxlistindexof} 190 191\constfunc{int}{IndexOf}{\param{T*}{ obj }} 192 193Returns the index of {\it obj} within the list or {\tt wxNOT\_FOUND} if 194{\it obj} is not found in the list. 195 196\membersection{wxList<T>::Insert}\label{wxlistinsert1} 197 198\func{wxList<T>::compatibility\_iterator}{Insert}{\param{T *}{object}} 199 200Insert object at the front of list. 201 202\func{wxList<T>::compatibility\_iterator}{Insert}{\param{size\_t }{position}, \param{T *}{object}} 203 204Insert object before {\it position}, i.e. the index of the new item in the 205list will be equal to {\it position}. {\it position} should be less than or 206equal to \helpref{GetCount}{wxlistgetcount}; if it is equal to it, this is the 207same as calling \helpref{Append}{wxlistappend}. 208 209\func{wxList<T>::compatibility\_iterator}{Insert}{\param{compatibility\_iterator}{iter}, \param{T *}{object}} 210 211Inserts the object before the object refered to be {\it iter}. 212 213\membersection{wxList<T>::IsEmpty}\label{wxlistisempty} 214 215\constfunc{bool}{IsEmpty}{\void} 216 217Returns {\tt true} if the list is empty, {\tt false} otherwise. 218 219% Use different label name to avoid clashing with wxListItem label 220\membersection{wxList<T>::Item}\label{wxlistitemfunc} 221 222\constfunc{wxList<T>::compatibility\_iterator}{Item}{\param{size\_t }{index}} 223 224Returns the iterator refering to the object at the given 225{\tt index} in the list. 226 227\membersection{wxList<T>::Member}\label{wxlistmember} 228 229\constfunc{wxList<T>::compatibility\_iterator}{Member}{\param{T *}{ object}} 230 231{\bf NB:} This function is deprecated, use \helpref{Find}{wxlistfind} instead. 232 233\membersection{wxList<T>::Nth}\label{wxlistnth} 234 235\constfunc{wxList<T>::compatibility\_iterator}{Nth}{\param{int }{n}} 236 237{\bf NB:} This function is deprecated, use \helpref{Item}{wxlistitemfunc} instead. 238 239Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty 240or the nth node could not be found). 241 242\membersection{wxList<T>::Number}\label{wxlistnumber} 243 244\constfunc{int}{Number}{\void} 245 246{\bf NB:} This function is deprecated, use \helpref{GetCount}{wxlistgetcount} instead. 247 248Returns the number of elements in the list. 249 250\membersection{wxList<T>::Sort}\label{wxlistsort} 251 252\func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}} 253 254\begin{verbatim} 255 // Type of compare function for list sort operation (as in 'qsort') 256 typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2); 257\end{verbatim} 258 259Allows the sorting of arbitrary lists by giving a function to compare 260two list elements. We use the system {\bf qsort} function for the actual 261sorting process. 262 263 264 265\membersection{wxList<T>::assign}\label{wxlistassign} 266 267\func{void}{assign}{\param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} 268 269 270\func{void}{assign}{\param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} 271 272 273\membersection{wxList<T>::back}\label{wxlistback} 274 275\func{reference}{back}{\void} 276 277\constfunc{const\_reference}{back}{\void} 278 279Returns the last item of the list. 280 281\membersection{wxList<T>::begin}\label{wxlistbegin} 282 283\func{iterator}{begin}{\void} 284 285\constfunc{const\_iterator}{begin}{\void} 286 287Returns a (const) iterator pointing to the beginning of the list. 288 289\membersection{wxList<T>::clear}\label{wxlistclear} 290 291\func{void}{clear}{\void} 292 293Removes all items from the list. 294 295\membersection{wxList<T>::empty}\label{wxlistempty} 296 297\constfunc{bool}{empty}{\void} 298 299Returns {\it true} if the list is empty. 300 301\membersection{wxList<T>::end}\label{wxlistend} 302 303\func{iterator}{end}{\void} 304 305\constfunc{const\_iterator}{end}{\void} 306 307Returns a (const) iterator pointing at the end of the list. 308 309\membersection{wxList<T>::erase}\label{wxlisterase2} 310 311\func{iterator}{erase}{\param{const iterator\& }{it}} 312 313Erases the item pointed to by {\it it}. 314 315\func{iterator}{erase}{\param{const iterator\& }{first}, \param{const iterator\& }{last}} 316 317Erases the items from {\it first} to {\it last}. 318 319\membersection{wxList<T>::front}\label{wxlistfront} 320 321\func{reference}{front}{\void} 322 323\constfunc{const\_reference}{front}{\void} 324 325Returns the first item in the list. 326 327\membersection{wxList<T>::insert}\label{wxlistinsert} 328 329\func{iterator}{insert}{\param{const iterator\& }{it}, \param{const\_reference }{v = value\_type()}} 330 331\func{void}{insert}{\param{const iterator\& }{it}, \param{size\_type }{n}, \param{const\_reference }{v = value\_type()}} 332 333\func{void}{insert}{\param{const iterator\& }{it}, \param{const\_iterator }{first}, \param{const const\_iterator\& }{last}} 334 335Inserts an item (or several) at the given position. 336 337\membersection{wxList<T>::max\_size}\label{wxlistmax\_size} 338 339\constfunc{size\_type}{max\_size}{\void} 340 341Returns the largest possible size of the list. 342 343\membersection{wxList<T>::pop\_back}\label{wxlistpopback} 344 345\func{void}{pop\_back}{\void} 346 347Removes the list item. 348 349\membersection{wxList<T>::pop\_front}\label{wxlistpopfront} 350 351\func{void}{pop\_front}{\void} 352 353Removes the first item. 354 355\membersection{wxList<T>::push\_back}\label{wxlistpushback} 356 357\func{void}{push\_back}{\param{const\_reference }{v = value\_type()}} 358 359Adds an item to end of the list. 360 361\membersection{wxList<T>::push\_front}\label{wxlistpushfront} 362 363\func{void}{push\_front}{\param{const\_reference }{v = value\_type()}} 364 365Adds an item to the front of the list. 366 367\membersection{wxList<T>::rbegin}\label{wxlistrbegin} 368 369\func{reverse\_iterator}{rbegin}{\void} 370 371\constfunc{const\_reverse\_iterator}{rbegin}{\void} 372 373Returns a (const) reverse iterator pointer to the beginning of the 374reversed list. 375 376\membersection{wxList<T>::remove}\label{wxlistremove} 377 378\func{void}{remove}{\param{const\_reference }{v}} 379 380Removes an item from the list. 381 382\membersection{wxList<T>::rend}\label{wxlistrend} 383 384\func{reverse\_iterator}{rend}{\void} 385 386\constfunc{const\_reverse\_iterator}{rend}{\void} 387 388Returns a (const) reverse iterator pointer to the end of the 389reversed list. 390 391\membersection{wxList<T>::resize}\label{wxlistresize} 392 393\func{void}{resize}{\param{size\_type }{n}, \param{value\_type }{v = value\_type()}} 394 395Resizes the list. If the the list is enlarges items with 396the value {\it v} are appended to the list. 397 398\membersection{wxList<T>::reverse}\label{wxlistreverse} 399 400\func{void}{reverse}{\void} 401 402Reverses the list. 403 404\membersection{wxList<T>::size}\label{wxlistsize} 405 406\constfunc{size\_type}{size}{\void} 407 408Returns the size of the list. 409 410\membersection{wxList<T>::splice}\label{wxlistsplice} 411 412\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}} 413 414\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}} 415 416\func{void}{splice}{\param{const iterator\& }{it}, \param{wxList<T>\& }{l}, \param{const iterator\& }{first}, \param{const iterator\& }{last}} 417 418Moves part of the list into another list, starting from {\it first} and 419ending at {\it last} if specified. 420 421