docs/latex/wx/list.tex

   1 \section{\class{wxList}}\label{wxlist}
   2
   3 This class provides linked list functionality for wxWindows, and for an application
   4 if it wishes.  Depending on the form of constructor used, a list can be keyed on
   5 integer or string keys to provide a primitive look-up ability. See \helpref{wxHashTable}{wxhashtable}\rtfsp
   6 for a faster method of storage when random access is required.
   7
   8 \wxheading{Derived from}
   9
  10 \helpref{wxObject}{wxobject}
  11
  12 \wxheading{Example}
  13
  14 It is very common to iterate on a list as follows:
  15
  16 \begin{verbatim}
  17   ...
  18   wxPoint *point1 = new wxPoint(100, 100);
  19   wxPoint *point2 = new wxPoint(200, 200);
  20
  21   wxList SomeList;
  22   SomeList.Append(point1);
  23   SomeList.Append(point2);
  24
  25   ...
  26
  27   wxNode *node = SomeList.First();
  28   while (node)
  29   {
  30     wxPoint *point = (wxPoint *)node->Data();
  31     ...
  32     node = node->Next();
  33   }
  34 \end{verbatim}
  35
  36 To delete nodes in a list as the list is being traversed, replace
  37
  38 \begin{verbatim}
  39     ...
  40     node = node->Next();
  41     ...
  42 \end{verbatim}
  43
  44 with
  45
  46 \begin{verbatim}
  47     ...
  48     delete point;
  49     delete node;
  50     node = SomeList.First();
  51     ...
  52 \end{verbatim}
  53
  54 See \helpref{wxNode}{wxnode} for members that retrieve the data associated with a node, and
  55 members for getting to the next or previous node.
  56
  57 Note that a cast is required when retrieving the data from a node.  Although a
  58 node is defined to store objects of type {\bf wxObject} and derived types, other
  59 types (such as char*) may be used with appropriate casting.
  60
  61 \wxheading{See also}
  62
  63 \helpref{wxNode}{wxnode}, \helpref{wxStringList}{wxstringlist}
  64
  65 \latexignore{\rtfignore{\wxheading{Members}}}
  66
  67
  68 \membersection{wxList::wxList}
  69
  70 \func{}{wxList}{\void}
  71
  72 \func{}{wxList}{\param{unsigned int}{ key\_type}}
  73
  74 \func{}{wxList}{\param{int}{ n}, \param{wxObject *}{objects[]}}
  75
  76 \func{}{wxList}{\param{wxObject *}{object}, ...}
  77
  78 Constructors. {\it key\_type} is one of wxKEY\_NONE, wxKEY\_INTEGER, or wxKEY\_STRING,
  79 and indicates what sort of keying is required (if any).
  80
  81 {\it objects} is an array of {\it n} objects with which to initialize the list.
  82
  83 The variable-length argument list constructor must be supplied with a
  84 terminating NULL.
  85
  86 \membersection{wxList::\destruct{wxList}}
  87
  88 \func{}{\destruct{wxList}}{\void}
  89
  90 Destroys the list.  Also destroys any remaining nodes, but does not destroy
  91 client data held in the nodes.
  92
  93 \membersection{wxList::Append}
  94
  95 \func{wxNode *}{Append}{\param{wxObject *}{object}}
  96
  97 \func{wxNode *}{Append}{\param{long}{ key}, \param{wxObject *}{object}}
  98
  99 \func{wxNode *}{Append}{\param{const wxString\& }{key}, \param{wxObject *}{object}}
 100
 101 Appends a new {\bf wxNode} to the end of the list and puts a pointer to the
 102 \rtfsp{\it object} in the node.  The last two forms store a key with the object for
 103 later retrieval using the key. The new node is returned in each case.
 104
 105 The key string is copied and stored by the list implementation.
 106
 107 \membersection{wxList::Clear}
 108
 109 \func{void}{Clear}{\void}
 110
 111 Clears the list (but does not delete the client data stored with each node).
 112
 113 \membersection{wxList::DeleteContents}
 114
 115 \func{void}{DeleteContents}{\param{bool}{ destroy}}
 116
 117 If {\it destroy} is TRUE, instructs the list to call {\it delete} on the client contents of
 118 a node whenever the node is destroyed. The default is FALSE.
 119
 120 \membersection{wxList::DeleteNode}
 121
 122 \func{bool}{DeleteNode}{\param{wxNode *}{node}}
 123
 124 Deletes the given node from the list, returning TRUE if successful.
 125
 126 \membersection{wxList::DeleteObject}
 127
 128 \func{bool}{DeleteObject}{\param{wxObject *}{object}}
 129
 130 Finds the given client {\it object} and deletes the appropriate node from the list, returning
 131 TRUE if successful. The application must delete the actual object separately.
 132
 133 \membersection{wxList::Find}
 134
 135 \func{wxNode *}{Find}{\param{long}{ key}}
 136
 137 \func{wxNode *}{Find}{\param{const wxString\& }{key}}
 138
 139 Returns the node whose stored key matches {\it key}. Use on a keyed list only.
 140
 141 \membersection{wxList::First}
 142
 143 \func{wxNode *}{First}{\void}
 144
 145 Returns the first node in the list (NULL if the list is empty).
 146
 147 \membersection{wxList::IndexOf}
 148
 149 \func{int}{IndexOf}{\param{wxObject*}{ obj }}
 150
 151 Returns the index of {\it obj} within the list or NOT\_FOUND if {\it obj}
 152 is not found in the list.
 153
 154 \membersection{wxList::Insert}
 155
 156 \func{wxNode *}{Insert}{\param{wxObject *}{object}}
 157
 158 Insert object at front of list.
 159
 160 \func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
 161
 162 Insert object before {\it position}.
 163
 164
 165 \membersection{wxList::Last}
 166
 167 \func{wxNode *}{Last}{\void}
 168
 169 Returns the last node in the list (NULL if the list is empty).
 170
 171 \membersection{wxList::Member}
 172
 173 \func{wxNode *}{Member}{\param{wxObject *}{object}}
 174
 175 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 176
 177 \membersection{wxList::Nth}
 178
 179 \func{wxNode *}{Nth}{\param{int}{ n}}
 180
 181 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 182 or the nth node could not be found).
 183
 184 \membersection{wxList::Number}
 185
 186 \func{int}{Number}{\void}
 187
 188 Returns the number of elements in the list.
 189
 190 \membersection{wxList::Sort}
 191
 192 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 193
 194 \begin{verbatim}
 195   // Type of compare function for list sort operation (as in 'qsort')
 196   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 197 \end{verbatim}
 198
 199 Allows the sorting of arbitrary lists by giving
 200 a function to compare two list elements. We use the system {\bf qsort} function
 201 for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **),
 202 so be careful to dereference appropriately.
 203
 204 Example:
 205
 206 \begin{verbatim}
 207   int listcompare(const void *arg1, const void *arg2)
 208   {
 209     return(compare(**(wxString **)arg1,    // use the wxString 'compare'
 210                    **(wxString **)arg2));  // function
 211   }
 212
 213   void main()
 214   {
 215     wxList list;
 216
 217     list.Append(new wxString("DEF"));
 218     list.Append(new wxString("GHI"));
 219     list.Append(new wxString("ABC"));
 220     list.Sort(listcompare);
 221   }
 222 \end{verbatim}
 223
 224