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:     wxWidgets 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 \arg{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::GetSelectionBackground}\label{wxvlistboxgetselectionbackground}
 177
 178 \constfunc{const wxColour\&}{GetSelectionBackground}{\void}
 179
 180 Returns the background colour used for the selected cells. By default the
 181 standard system colour is used.
 182
 183 \wxheading{See also}
 184
 185 \helpref{wxSystemSettings::GetColour}{wxsystemsettingsgetcolour},\\
 186 \helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground}
 187
 188
 189 \membersection{wxVListBox::HasMultipleSelection}\label{wxvlistboxishasmultipleselection}
 190
 191 \constfunc{bool}{HasMultipleSelection}{\void}
 192
 193 Returns {\tt true} if the listbox was created with {\tt wxLB\_MULTIPLE} style
 194 and so supports multiple selection or {\tt false} if it is a single selection
 195 listbox.
 196
 197
 198 \membersection{wxVListBox::IsCurrent}\label{wxvlistboxiscurrent}
 199
 200 \constfunc{bool}{IsCurrent}{\param{size\_t }{item}}
 201
 202 Returns {\tt true} if this item is the current one, {\tt false} otherwise.
 203
 204 Current item is always the same as selected one for the single selection
 205 listbox and in this case this method is equivalent to
 206 \helpref{IsSelected}{wxvlistboxisselected} but they are different for multi
 207 selection listboxes where many items may be selected but only one (at most) is
 208 current.
 209
 210
 211 \membersection{wxVListBox::IsSelected}\label{wxvlistboxisselected}
 212
 213 \constfunc{bool}{IsSelected}{\param{size\_t }{item}}
 214
 215 Returns {\tt true} if this item is selected, {\tt false} otherwise.
 216
 217
 218 \membersection{wxVListBox::OnDrawBackground}\label{wxvlistboxondrawbackground}
 219
 220 \constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 221
 222 This method is used to draw the items background and, maybe, a border
 223 around it.
 224
 225 The base class version implements a reasonable default behaviour which
 226 consists in drawing the selected item with the standard background
 227 colour and drawing a border around the item if it is either selected or
 228 current.
 229
 230
 231 \membersection{wxVListBox::OnDrawItem}\label{wxvlistboxondrawitem}
 232
 233 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 234
 235 The derived class must implement this function to actually draw the item
 236 with the given index on the provided DC.
 237
 238 \wxheading{Parameters}
 239
 240 \docparam{dc}{The device context to use for drawing}
 241
 242 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 243 region is set to this rectangle before calling this function)}
 244
 245 \docparam{n}{The index of the item to be drawn}
 246
 247
 248 \membersection{wxVListBox::OnDrawSeparator}\label{wxvlistboxondrawseparator}
 249
 250 \constfunc{void}{OnDrawSeparator}{\param{wxDC\& }{dc}, \param{wxRect\& }{rect}, \param{size\_t }{n}}
 251
 252 This method may be used to draw separators between the lines. The rectangle
 253 passed to it may be modified, typically to deflate it a bit before passing to
 254 \helpref{OnDrawItem()}{wxvlistboxondrawitem}.
 255
 256 The base class version of this method doesn't do anything.
 257
 258 \wxheading{Parameters}
 259
 260 \docparam{dc}{The device context to use for drawing}
 261
 262 \docparam{rect}{The bounding rectangle for the item}
 263
 264 \docparam{n}{The index of the item}
 265
 266
 267 \membersection{wxVListBox::OnMeasureItem}\label{wxvlistboxonmeasureitem}
 268
 269 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{n}}
 270
 271 The derived class must implement this method to return the height of the
 272 specified item (in pixels).
 273
 274
 275 \membersection{wxVListBox::Select}\label{wxvlistboxselect}
 276
 277 \func{bool}{Select}{\param{size\_t }{item}, \param{bool }{select = true}}
 278
 279 Selects or deselects the specified item which must be valid (i.e. not
 280 equal to {\tt wxNOT\_FOUND}).
 281
 282 Return {\tt true} if the items selection status has changed or {\tt false}
 283 otherwise.
 284
 285 This function is only valid for the multiple selection listboxes, use
 286 \helpref{SetSelection}{wxvlistboxsetselection} for the single selection ones.
 287
 288
 289 \membersection{wxVListBox::SelectAll}\label{wxvlistboxselectall}
 290
 291 \func{bool}{SelectAll}{\void}
 292
 293 Selects all the items in the listbox.
 294
 295 Returns {\tt true} if any items were changed, i.e. if there had been any
 296 unselected items before, or {\tt false} if all the items were already selected.
 297
 298 This method is only valid for multi selection listboxes.
 299
 300 \wxheading{See also}
 301
 302 \helpref{DeselectAll}{wxvlistboxdeselectall}, \helpref{Select}{wxvlistboxselect}
 303
 304
 305 \membersection{wxVListBox::SelectRange}\label{wxvlistboxselectrange}
 306
 307 \func{bool}{SelectRange}{\param{size\_t }{from}, \param{size\_t }{to}}
 308
 309 Selects all items in the specified range which may be given in any order.
 310
 311 Return {\tt true} if the items selection status has changed or {\tt false}
 312 otherwise.
 313
 314 This method is only valid for multi selection listboxes.
 315
 316 \wxheading{See also}
 317
 318 \helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
 319
 320 \membersection{wxVListBox::SetItemCount}\label{wxvlistboxsetitemcount}
 321
 322 \func{void}{SetItemCount}{\param{size\_t }{count}}
 323
 324 Set the number of items to be shown in the control.
 325
 326 This is just a synonym for
 327 \helpref{wxVScrolledWindow::SetLineCount()}{wxvscrolledwindowsetlinecount}.
 328
 329
 330 \membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins}
 331
 332 \func{void}{SetMargins}{\param{const wxPoint\& }{pt}}
 333
 334 \func{void}{SetMargins}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 335
 336 Set the margins: horizontal margin is the distance between the window
 337 border and the item contents while vertical margin is half of the
 338 distance between items.
 339
 340 By default both margins are $0$.
 341
 342
 343 \membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection}
 344
 345 \func{void}{SetSelection}{\param{int }{selection}}
 346
 347 Set the selection to the specified item, if it is $-1$ the selection is
 348 unset. The selected item will be automatically scrolled into view if it isn't
 349 currently visible.
 350
 351 This method may be used both with single and multiple selection listboxes.
 352
 353
 354 \membersection{wxVListBox::SetSelectionBackground}\label{wxvlistboxsetselectionbackground}
 355
 356 \func{void}{SetSelectionBackground}{\param{const wxColour\& }{col}}
 357
 358 Sets the colour to be used for the selected cells background. The background of
 359 the standard cells may be changed by simply calling
 360 \helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour}.
 361
 362 \wxheading{See also}
 363
 364 \helpref{GetSelectionBackground}{wxvlistboxgetselectionbackground}
 365
 366
 367 \membersection{wxVListBox::Toggle}\label{wxvlistboxtoggle}
 368
 369 \func{void}{Toggle}{\param{size\_t }{item}}
 370
 371 Toggles the state of the specified \arg{item}, i.e. selects it if it was
 372 unselected and deselects it if it was selected.
 373
 374 This method is only valid for multi selection listboxes.
 375
 376 \wxheading{See also}
 377
 378 \helpref{Select}{wxvlistboxselect}
 379