docs/latex/wx/vlbox.tex

   1 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
   2 %% Name:        vlbox.tex
   3 %% Purpose:     wxVListBox documentation
   4 %% Author:      Vadim Zeitlin
   5 %% Modified by:
   6 %% Created:     01.06.03
   7 %% RCS-ID:      $Id$
   8 %% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
   9 %% License:     wxWindows license
  10 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
  11
  12 \section{\class{wxVListBox}}\label{wxvlistbox}
  13
  14 wxVListBox is a listbox-like control with the following two main differences
  15 from a regular listbox: it can have an arbitrarily huge number of items because
  16 it doesn't store them itself but uses \helpref{OnDrawItem()}{wxvlistboxondrawitem}
  17 callback to draw them (so it is a {\Large V}irtual listbox) and its items can
  18 have variable height as determined by
  19 \helpref{OnMeasureItem()}{wxvlistboxonmeasureitem} (so it is also a listbox
  20 with the lines of {\Large V}ariable height).
  21
  22 Also, as a consequence of its virtual nature, it doesn't have any methods to
  23 append or insert items in it as it isn't necessary to do it: you just have to
  24 call \helpref{SetItemCount()}{wxvlistboxsetitemcount} to tell the control how
  25 many items it should display. Of course, this also means that you will never
  26 use this class directly because it has pure virtual functions, but will need to
  27 derive your own class, such as \helpref{wxHtmlListBox}{wxhtmllistbox}, from it.
  28
  29 However it emits the same events as \helpref{wxListBox}{wxlistbox} and the same
  30 event macros may be used with it.
  31
  32 \wxheading{Derived from}
  33
  34 \helpref{wxVScrolledWindow}{wxvscrolledwindow}
  35
  36 \wxheading{Include files}
  37
  38 <wx/vlbox.h>
  39
  40 \latexignore{\rtfignore{\wxheading{Members}}}
  41
  42
  43 \membersection{wxVListBox::wxVListBox}\label{wxvlistboxctor}
  44
  45 \func{}{wxVListBox}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{size\_t }{countItems = 0}, \param{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}}
  46
  47 Normal constructor which calls \helpref{Create()}{wxvlistboxcreate} internally.
  48
  49 \func{}{wxVListBox}{\void}
  50
  51 Default constructor, you must call \helpref{Create()}{wxvlistboxcreate} later.
  52
  53
  54 \membersection{wxVListBox::Clear}\label{wxvlistboxclear}
  55
  56 \func{void}{Clear}{\void}
  57
  58 Deletes all items from the control.
  59
  60
  61 \membersection{wxVListBox::Create}\label{wxvlistboxcreate}
  62
  63 \func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID }{id = wxID\_ANY}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize}, \param{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}}
  64
  65 Creates the control. To finish creating it you also should call
  66 \helpref{SetItemCount()}{wxvlistboxsetitemcount} to let it know about the
  67 number of items it contains.
  68
  69 The only special style which may be used with wxVListBox is {\tt wxLB\_MULTIPLE}
  70 which indicates that the listbox should support multiple selection.
  71
  72 Returns {\tt true} on success or {\tt false} if the control couldn't be created
  73
  74
  75 \membersection{wxVListBox::DeselectAll}\label{wxvlistboxdeselectall}
  76
  77 \func{bool}{DeselectAll}{\void}
  78
  79 Deselects all the items in the listbox.
  80
  81 Returns {\tt true} if any items were changed, i.e. if there had been any
  82 selected items before, or {\tt false} if all the items were already deselected.
  83
  84 This method is only valid for multi selection listboxes.
  85
  86 \wxheading{See also}
  87
  88 \helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
  89
  90
  91 \membersection{wxVListBox::GetFirstSelected}\label{wxvlistboxgetfirstselected}
  92
  93 \constfunc{int}{GetFirstSelected}{\param{unsigned long\& }{cookie}}
  94
  95 Returns the index of the first selected item in the listbox or
  96 {\tt wxNOT\_FOUND} if no items are currently selected.
  97
  98 {\it cookie} is an opaque parameter which should be passed to the subsequent
  99 calls to \helpref{GetNextSelected}{wxvlistboxgetnextselected}. It is needed in
 100 order to allow parallel iterations over the selected items.
 101
 102 Here is a typical example of using these functions:
 103 \begin{verbatim}
 104 unsigned long cookie;
 105 int item = hlbox->GetFirstSelected(cookie);
 106 while ( item != wxNOT_FOUND )
 107 {
 108     ... process item ...
 109     item = hlbox->GetNextSelected(cookie);
 110 }
 111 \end{verbatim}
 112
 113 This method is only valid for multi selection listboxes.
 114
 115
 116 \membersection{wxVListBox::GetItemCount}\label{wxvlistboxgetitemcount}
 117
 118 \constfunc{size\_t}{GetItemCount}{\void}
 119
 120 Get the number of items in the control.
 121
 122 \wxheading{See also}
 123
 124 \helpref{SetItemCount()}{wxvlistboxsetitemcount}
 125
 126
 127 \membersection{wxVListBox::GetMargins}\label{wxvlistboxgetmargins}
 128
 129 \constfunc{wxPoint}{GetMargins}{\void}
 130
 131 Returns the margins used by the control. The {\tt x} field of the returned
 132 point is the horizontal margine and the {\tt y} field is the vertical one.
 133
 134 \wxheading{See also}
 135
 136 \helpref{SetMargins}{wxvlistboxsetmargins}
 137
 138
 139 \membersection{wxVListBox::GetNextSelected}\label{wxvlistboxgetnextselected}
 140
 141 \constfunc{int}{GetNextSelected}{\param{unsigned long\& }{cookie}}
 142
 143 Returns the index of the next selected item or {\tt wxNOT\_FOUND} if there are
 144 no more.
 145
 146 This method is only valid for multi selection listboxes.
 147
 148 \wxheading{See also}
 149
 150 \helpref{GetFirstSelected}{wxvlistboxgetfirstselected}
 151
 152
 153 \membersection{wxVListBox::GetSelectedCount}\label{wxvlistboxgetselectedcount}
 154
 155 \constfunc{size\_t}{GetSelectedCount}{\void}
 156
 157 Returns the number of the items currently selected.
 158
 159 It is valid for both single and multi selection controls. In the former case it
 160 may only return $0$ or $1$ however.
 161
 162 \wxheading{See also}
 163
 164 \helpref{IsSelected}{wxvlistboxisselected},\\
 165 \helpref{GetFirstSelected}{wxvlistboxgetfirstselected},\\
 166 \helpref{GetNextSelected}{wxvlistboxgetnextselected}
 167
 168
 169 \membersection{wxVListBox::GetSelection}\label{wxvlistboxgetselection}
 170
 171 \constfunc{int}{GetSelection}{\void}
 172
 173 Get the currently selected item or $-1$ if there is no selection.
 174
 175
 176 \membersection{wxVListBox::HasMultipleSelection}\label{wxvlistboxishasmultipleselection}
 177
 178 \constfunc{bool}{HasMultipleSelection}{\void}
 179
 180 Returns {\tt true} if the listbox was created with {\tt wxLB\_MULTIPLE} style
 181 and so supports multiple selection or {\tt false} if it is a single selection
 182 listbox.
 183
 184
 185 \membersection{wxVListBox::IsCurrent}\label{wxvlistboxiscurrent}
 186
 187 \constfunc{bool}{IsCurrent}{\param{size\_t }{item}}
 188
 189 Returns {\tt true} if this item is the current one, {\tt false} otherwise.
 190
 191 Current item is always the same as selected one for the single selection
 192 listbox and in this case this method is equivalent to
 193 \helpref{IsSelected}{wxvlistboxisselected} but they are different for multi
 194 selection listboxes where many items may be selected but only one (at most) is
 195 current.
 196
 197
 198 \membersection{wxVListBox::IsSelected}\label{wxvlistboxisselected}
 199
 200 \constfunc{bool}{IsSelected}{\param{size\_t }{item}}
 201
 202 Returns {\tt true} if this item is selected, {\tt false} otherwise.
 203
 204
 205 \membersection{wxVListBox::OnDrawItem}\label{wxvlistboxondrawitem}
 206
 207 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 208
 209 The derived class must implement this function to actually draw the item
 210 with the given index on the provided DC.
 211
 212 \wxheading{Parameters}
 213
 214 \docparam{dc}{The device context to use for drawing}
 215
 216 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 217 region is set to this rectangle before calling this function)}
 218
 219 \docparam{n}{The index of the item to be drawn}
 220
 221
 222 \membersection{wxVListBox::OnDrawSeparator}\label{wxvlistboxondrawseparator}
 223
 224 \constfunc{void}{OnDrawSeparator}{\param{wxDC\& }{dc}, \param{wxRect\& }{rect}, \param{size\_t }{n}}
 225
 226 This method may be used to draw separators between the lines. The rectangle
 227 passed to it may be modified, typically to deflate it a bit before passing to
 228 \helpref{OnDrawItem()}{wxvlistboxondrawitem}.
 229
 230 The base class version of this method doesn't do anything.
 231
 232 \wxheading{Parameters}
 233
 234 \docparam{dc}{The device context to use for drawing}
 235
 236 \docparam{rect}{The bounding rectangle for the item}
 237
 238 \docparam{n}{The index of the item}
 239
 240
 241 \membersection{wxVListBox::OnMeasureItem}\label{wxvlistboxonmeasureitem}
 242
 243 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{n}}
 244
 245 The derived class must implement this method to return the height of the
 246 specified item (in pixels).
 247
 248
 249 \membersection{wxVListBox::Select}\label{wxvlistboxselect}
 250
 251 \func{bool}{Select}{\param{size\_t }{item}, \param{bool }{select = true}}
 252
 253 Selects or deselects the specified item which must be valid (i.e. not
 254 equal to {\tt wxNOT\_FOUND}).
 255
 256 Return {\tt true} if the items selection status has changed or {\tt false}
 257 otherwise.
 258
 259 This function is only valid for the multiple selection listboxes, use
 260 \helpref{SetSelection}{wxvlistboxsetselection} for the single selection ones.
 261
 262
 263 \membersection{wxVListBox::SelectAll}\label{wxvlistboxselectall}
 264
 265 \func{bool}{SelectAll}{\void}
 266
 267 Selects all the items in the listbox.
 268
 269 Returns {\tt true} if any items were changed, i.e. if there had been any
 270 unselected items before, or {\tt false} if all the items were already selected.
 271
 272 This method is only valid for multi selection listboxes.
 273
 274 \wxheading{See also}
 275
 276 \helpref{DeselectAll}{wxvlistboxdeselectall}, \helpref{Select}{wxvlistboxselect}
 277
 278
 279 \membersection{wxVListBox::SelectRange}\label{wxvlistboxselectrange}
 280
 281 \func{bool}{SelectRange}{\param{size\_t }{from}, \param{size\_t }{to}}
 282
 283 Selects all items in the specified range which may be given in any order.
 284
 285 Return {\tt true} if the items selection status has changed or {\tt false}
 286 otherwise.
 287
 288 This method is only valid for multi selection listboxes.
 289
 290 \wxheading{See also}
 291
 292 \helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
 293
 294
 295 \func{void}{SetItemCount}{\param{size\_t }{count}}
 296
 297 Set the number of items to be shown in the control.
 298
 299 This is just a synonym for
 300 \helpref{wxVScrolledWindow::SetLineCount()}{wxvscrolledwindowsetlinecount}.
 301
 302
 303 \membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins}
 304
 305 \func{void}{SetMargins}{\param{const wxPoint\& }{pt}}
 306
 307 \func{void}{SetMargins}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 308
 309 Set the margins: horizontal margin is the distance between the window
 310 border and the item contents while vertical margin is half of the
 311 distance between items.
 312
 313 By default both margins are $0$.
 314
 315
 316 \membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection}
 317
 318 \func{void}{SetSelection}{\param{int }{selection}}
 319
 320 Set the selection to the specified item, if it is $-1$ the selection is
 321 unset. The selected item will be automatically scrolled into view if it isn't
 322 currently visible.
 323
 324
 325 \membersection{wxVListBox::Toggle}\label{wxvlistboxtoggle}
 326
 327 \func{void}{Toggle}{\param{size\_t }{item}}
 328
 329 Toggles the state of the specified {\it item}, i.e. selects it if it was
 330 unselected and deselects it if it was selected.
 331
 332 This method is only valid for multi selection listboxes.
 333
 334 \wxheading{See also}
 335
 336 \helpref{Select}{wxvlistboxselect}
 337