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