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