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