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::Insert}
 148
 149 \func{wxNode *}{Insert}{\param{wxObject *}{object}}
 150
 151 Insert object at front of list.
 152
 153 \func{wxNode *}{Insert}{\param{wxNode *}{position}, \param{wxObject *}{object}}
 154
 155 Insert object before {\it position}.
 156
 157
 158 \membersection{wxList::Last}
 159
 160 \func{wxNode *}{Last}{\void}
 161
 162 Returns the last node in the list (NULL if the list is empty).
 163
 164 \membersection{wxList::Member}
 165
 166 \func{wxNode *}{Member}{\param{wxObject *}{object}}
 167
 168 Returns the node associated with {\it object} if it is in the list, NULL otherwise.
 169
 170 \membersection{wxList::Nth}
 171
 172 \func{wxNode *}{Nth}{\param{int}{ n}}
 173
 174 Returns the {\it nth} node in the list, indexing from zero (NULL if the list is empty
 175 or the nth node could not be found).
 176
 177 \membersection{wxList::Number}
 178
 179 \func{int}{Number}{\void}
 180
 181 Returns the number of elements in the list.
 182
 183 \membersection{wxList::Sort}
 184
 185 \func{void}{Sort}{\param{wxSortCompareFunction}{ compfunc}}
 186
 187 \begin{verbatim}
 188   // Type of compare function for list sort operation (as in 'qsort')
 189   typedef int (*wxSortCompareFunction)(const void *elem1, const void *elem2);
 190 \end{verbatim}
 191
 192 Allows the sorting of arbitrary lists by giving
 193 a function to compare two list elements. We use the system {\bf qsort} function
 194 for the actual sorting process. The sort function receives pointers to wxObject pointers (wxObject **),
 195 so be careful to dereference appropriately.
 196
 197 Example:
 198
 199 \begin{verbatim}
 200   int listcompare(const void *arg1, const void *arg2)
 201   {
 202     return(compare(**(wxString **)arg1,    // use the wxString 'compare'
 203                    **(wxString **)arg2));  // function
 204   }
 205
 206   void main()
 207   {
 208     wxList list;
 209
 210     list.Append(new wxString("DEF"));
 211     list.Append(new wxString("GHI"));
 212     list.Append(new wxString("ABC"));
 213     list.Sort(listcompare);
 214   }
 215 \end{verbatim}
 216
 217