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. Since wxVListBox does not store its items
  31 itself, the events will only contain the index, not any contents such as the
  32 string of an item.
  33
  34 \wxheading{Derived from}
  35
  36 \helpref{wxVScrolledWindow}{wxvscrolledwindow}\\
  37 \helpref{wxPanel}{wxpanel}\\
  38 \helpref{wxWindow}{wxwindow}\\
  39 \helpref{wxEvtHandler}{wxevthandler}\\
  40 \helpref{wxObject}{wxobject}
  41
  42 \wxheading{Include files}
  43
  44 <wx/vlbox.h>
  45
  46 \wxheading{Library}
  47
  48 \helpref{wxCore}{librarieslist}
  49
  50 \wxheading{See also}
  51
  52 \helpref{wxSimpleHtmlListBox}{wxsimplehtmllistbox}, \helpref{wxHtmlListBox}{wxhtmllistbox}
  53
  54 \latexignore{\rtfignore{\wxheading{Members}}}
  55
  56
  57 \membersection{wxVListBox::wxVListBox}\label{wxvlistboxctor}
  58
  59 \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}}
  60
  61 Normal constructor which calls \helpref{Create()}{wxvlistboxcreate} internally.
  62
  63 \func{}{wxVListBox}{\void}
  64
  65 Default constructor, you must call \helpref{Create()}{wxvlistboxcreate} later.
  66
  67
  68 \membersection{wxVListBox::Clear}\label{wxvlistboxclear}
  69
  70 \func{void}{Clear}{\void}
  71
  72 Deletes all items from the control.
  73
  74
  75 \membersection{wxVListBox::Create}\label{wxvlistboxcreate}
  76
  77 \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}}
  78
  79 Creates the control. To finish creating it you also should call
  80 \helpref{SetItemCount()}{wxvlistboxsetitemcount} to let it know about the
  81 number of items it contains.
  82
  83 The only special style which may be used with wxVListBox is {\tt wxLB\_MULTIPLE}
  84 which indicates that the listbox should support multiple selection.
  85
  86 Returns {\tt true} on success or {\tt false} if the control couldn't be created
  87
  88
  89 \membersection{wxVListBox::DeselectAll}\label{wxvlistboxdeselectall}
  90
  91 \func{bool}{DeselectAll}{\void}
  92
  93 Deselects all the items in the listbox.
  94
  95 Returns {\tt true} if any items were changed, i.e. if there had been any
  96 selected items before, or {\tt false} if all the items were already deselected.
  97
  98 This method is only valid for multi selection listboxes.
  99
 100 \wxheading{See also}
 101
 102 \helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
 103
 104
 105 \membersection{wxVListBox::GetFirstSelected}\label{wxvlistboxgetfirstselected}
 106
 107 \constfunc{int}{GetFirstSelected}{\param{unsigned long\& }{cookie}}
 108
 109 Returns the index of the first selected item in the listbox or
 110 {\tt wxNOT\_FOUND} if no items are currently selected.
 111
 112 \arg{cookie} is an opaque parameter which should be passed to the subsequent
 113 calls to \helpref{GetNextSelected}{wxvlistboxgetnextselected}. It is needed in
 114 order to allow parallel iterations over the selected items.
 115
 116 Here is a typical example of using these functions:
 117 \begin{verbatim}
 118 unsigned long cookie;
 119 int item = hlbox->GetFirstSelected(cookie);
 120 while ( item != wxNOT_FOUND )
 121 {
 122     ... process item ...
 123     item = hlbox->GetNextSelected(cookie);
 124 }
 125 \end{verbatim}
 126
 127 This method is only valid for multi selection listboxes.
 128
 129
 130 \membersection{wxVListBox::GetItemCount}\label{wxvlistboxgetitemcount}
 131
 132 \constfunc{size\_t}{GetItemCount}{\void}
 133
 134 Get the number of items in the control.
 135
 136 \wxheading{See also}
 137
 138 \helpref{SetItemCount()}{wxvlistboxsetitemcount}
 139
 140
 141 \membersection{wxVListBox::GetMargins}\label{wxvlistboxgetmargins}
 142
 143 \constfunc{wxPoint}{GetMargins}{\void}
 144
 145 Returns the margins used by the control. The {\tt x} field of the returned
 146 point is the horizontal margin and the {\tt y} field is the vertical one.
 147
 148 \wxheading{See also}
 149
 150 \helpref{SetMargins}{wxvlistboxsetmargins}
 151
 152
 153 \membersection{wxVListBox::GetNextSelected}\label{wxvlistboxgetnextselected}
 154
 155 \constfunc{int}{GetNextSelected}{\param{unsigned long\& }{cookie}}
 156
 157 Returns the index of the next selected item or {\tt wxNOT\_FOUND} if there are
 158 no more.
 159
 160 This method is only valid for multi selection listboxes.
 161
 162 \wxheading{See also}
 163
 164 \helpref{GetFirstSelected}{wxvlistboxgetfirstselected}
 165
 166
 167 \membersection{wxVListBox::GetSelectedCount}\label{wxvlistboxgetselectedcount}
 168
 169 \constfunc{size\_t}{GetSelectedCount}{\void}
 170
 171 Returns the number of the items currently selected.
 172
 173 It is valid for both single and multi selection controls. In the former case it
 174 may only return $0$ or $1$ however.
 175
 176 \wxheading{See also}
 177
 178 \helpref{IsSelected}{wxvlistboxisselected},\\
 179 \helpref{GetFirstSelected}{wxvlistboxgetfirstselected},\\
 180 \helpref{GetNextSelected}{wxvlistboxgetnextselected}
 181
 182
 183 \membersection{wxVListBox::GetSelection}\label{wxvlistboxgetselection}
 184
 185 \constfunc{int}{GetSelection}{\void}
 186
 187 Get the currently selected item or {\tt wxNOT\_FOUND} if there is no selection.
 188
 189
 190 \membersection{wxVListBox::GetSelectionBackground}\label{wxvlistboxgetselectionbackground}
 191
 192 \constfunc{const wxColour\&}{GetSelectionBackground}{\void}
 193
 194 Returns the background colour used for the selected cells. By default the
 195 standard system colour is used.
 196
 197 \wxheading{See also}
 198
 199 \helpref{wxSystemSettings::GetColour}{wxsystemsettingsgetcolour},\\
 200 \helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground}
 201
 202
 203 \membersection{wxVListBox::HasMultipleSelection}\label{wxvlistboxishasmultipleselection}
 204
 205 \constfunc{bool}{HasMultipleSelection}{\void}
 206
 207 Returns {\tt true} if the listbox was created with {\tt wxLB\_MULTIPLE} style
 208 and so supports multiple selection or {\tt false} if it is a single selection
 209 listbox.
 210
 211
 212 \membersection{wxVListBox::IsCurrent}\label{wxvlistboxiscurrent}
 213
 214 \constfunc{bool}{IsCurrent}{\param{size\_t }{item}}
 215
 216 Returns {\tt true} if this item is the current one, {\tt false} otherwise.
 217
 218 Current item is always the same as selected one for the single selection
 219 listbox and in this case this method is equivalent to
 220 \helpref{IsSelected}{wxvlistboxisselected} but they are different for multi
 221 selection listboxes where many items may be selected but only one (at most) is
 222 current.
 223
 224
 225 \membersection{wxVListBox::IsSelected}\label{wxvlistboxisselected}
 226
 227 \constfunc{bool}{IsSelected}{\param{size\_t }{item}}
 228
 229 Returns {\tt true} if this item is selected, {\tt false} otherwise.
 230
 231
 232 \membersection{wxVListBox::OnDrawBackground}\label{wxvlistboxondrawbackground}
 233
 234 \constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 235
 236 This method is used to draw the items background and, maybe, a border
 237 around it.
 238
 239 The base class version implements a reasonable default behaviour which
 240 consists in drawing the selected item with the standard background
 241 colour and drawing a border around the item if it is either selected or
 242 current.
 243
 244
 245 \membersection{wxVListBox::OnDrawItem}\label{wxvlistboxondrawitem}
 246
 247 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 248
 249 The derived class must implement this function to actually draw the item
 250 with the given index on the provided DC.
 251
 252 \wxheading{Parameters}
 253
 254 \docparam{dc}{The device context to use for drawing}
 255
 256 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 257 region is set to this rectangle before calling this function)}
 258
 259 \docparam{n}{The index of the item to be drawn}
 260
 261
 262 \membersection{wxVListBox::OnDrawSeparator}\label{wxvlistboxondrawseparator}
 263
 264 \constfunc{void}{OnDrawSeparator}{\param{wxDC\& }{dc}, \param{wxRect\& }{rect}, \param{size\_t }{n}}
 265
 266 This method may be used to draw separators between the lines. The rectangle
 267 passed to it may be modified, typically to deflate it a bit before passing to
 268 \helpref{OnDrawItem()}{wxvlistboxondrawitem}.
 269
 270 The base class version of this method doesn't do anything.
 271
 272 \wxheading{Parameters}
 273
 274 \docparam{dc}{The device context to use for drawing}
 275
 276 \docparam{rect}{The bounding rectangle for the item}
 277
 278 \docparam{n}{The index of the item}
 279
 280
 281 \membersection{wxVListBox::OnMeasureItem}\label{wxvlistboxonmeasureitem}
 282
 283 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{n}}
 284
 285 The derived class must implement this method to return the height of the
 286 specified item (in pixels).
 287
 288
 289 \membersection{wxVListBox::Select}\label{wxvlistboxselect}
 290
 291 \func{bool}{Select}{\param{size\_t }{item}, \param{bool }{select = true}}
 292
 293 Selects or deselects the specified item which must be valid (i.e. not
 294 equal to {\tt wxNOT\_FOUND}).
 295
 296 Return {\tt true} if the items selection status has changed or {\tt false}
 297 otherwise.
 298
 299 This function is only valid for the multiple selection listboxes, use
 300 \helpref{SetSelection}{wxvlistboxsetselection} for the single selection ones.
 301
 302
 303 \membersection{wxVListBox::SelectAll}\label{wxvlistboxselectall}
 304
 305 \func{bool}{SelectAll}{\void}
 306
 307 Selects all the items in the listbox.
 308
 309 Returns {\tt true} if any items were changed, i.e. if there had been any
 310 unselected items before, or {\tt false} if all the items were already selected.
 311
 312 This method is only valid for multi selection listboxes.
 313
 314 \wxheading{See also}
 315
 316 \helpref{DeselectAll}{wxvlistboxdeselectall}, \helpref{Select}{wxvlistboxselect}
 317
 318
 319 \membersection{wxVListBox::SelectRange}\label{wxvlistboxselectrange}
 320
 321 \func{bool}{SelectRange}{\param{size\_t }{from}, \param{size\_t }{to}}
 322
 323 Selects all items in the specified range which may be given in any order.
 324
 325 Return {\tt true} if the items selection status has changed or {\tt false}
 326 otherwise.
 327
 328 This method is only valid for multi selection listboxes.
 329
 330 \wxheading{See also}
 331
 332 \helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
 333
 334 \membersection{wxVListBox::SetItemCount}\label{wxvlistboxsetitemcount}
 335
 336 \func{void}{SetItemCount}{\param{size\_t }{count}}
 337
 338 Set the number of items to be shown in the control.
 339
 340 This is just a synonym for
 341 \helpref{wxVScrolledWindow::SetRowCount()}{wxvarvscrollhelpersetrowcount}.
 342
 343
 344 \membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins}
 345
 346 \func{void}{SetMargins}{\param{const wxPoint\& }{pt}}
 347
 348 \func{void}{SetMargins}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 349
 350 Set the margins: horizontal margin is the distance between the window
 351 border and the item contents while vertical margin is half of the
 352 distance between items.
 353
 354 By default both margins are $0$.
 355
 356
 357 \membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection}
 358
 359 \func{void}{SetSelection}{\param{int }{selection}}
 360
 361 Set the selection to the specified item, if it is $-1$ the selection is
 362 unset. The selected item will be automatically scrolled into view if it isn't
 363 currently visible.
 364
 365 This method may be used both with single and multiple selection listboxes.
 366
 367
 368 \membersection{wxVListBox::SetSelectionBackground}\label{wxvlistboxsetselectionbackground}
 369
 370 \func{void}{SetSelectionBackground}{\param{const wxColour\& }{col}}
 371
 372 Sets the colour to be used for the selected cells background. The background of
 373 the standard cells may be changed by simply calling
 374 \helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour}.
 375
 376 Notice that using non-default background colour may result in control having
 377 appearance different from the similar native controls and so should in general
 378 be avoided.
 379
 380 \wxheading{See also}
 381
 382 \helpref{GetSelectionBackground}{wxvlistboxgetselectionbackground}
 383
 384
 385 \membersection{wxVListBox::Toggle}\label{wxvlistboxtoggle}
 386
 387 \func{void}{Toggle}{\param{size\_t }{item}}
 388
 389 Toggles the state of the specified \arg{item}, i.e. selects it if it was
 390 unselected and deselects it if it was selected.
 391
 392 This method is only valid for multi selection listboxes.
 393
 394 \wxheading{See also}
 395
 396 \helpref{Select}{wxvlistboxselect}
 397