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
  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 {\it 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::OnDrawItem}\label{wxvlistboxondrawitem}
 219
 220 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 221
 222 The derived class must implement this function to actually draw the item
 223 with the given index on the provided DC.
 224
 225 \wxheading{Parameters}
 226
 227 \docparam{dc}{The device context to use for drawing}
 228
 229 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 230 region is set to this rectangle before calling this function)}
 231
 232 \docparam{n}{The index of the item to be drawn}
 233
 234
 235 \membersection{wxVListBox::OnDrawSeparator}\label{wxvlistboxondrawseparator}
 236
 237 \constfunc{void}{OnDrawSeparator}{\param{wxDC\& }{dc}, \param{wxRect\& }{rect}, \param{size\_t }{n}}
 238
 239 This method may be used to draw separators between the lines. The rectangle
 240 passed to it may be modified, typically to deflate it a bit before passing to
 241 \helpref{OnDrawItem()}{wxvlistboxondrawitem}.
 242
 243 The base class version of this method doesn't do anything.
 244
 245 \wxheading{Parameters}
 246
 247 \docparam{dc}{The device context to use for drawing}
 248
 249 \docparam{rect}{The bounding rectangle for the item}
 250
 251 \docparam{n}{The index of the item}
 252
 253
 254 \membersection{wxVListBox::OnMeasureItem}\label{wxvlistboxonmeasureitem}
 255
 256 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{n}}
 257
 258 The derived class must implement this method to return the height of the
 259 specified item (in pixels).
 260
 261
 262 \membersection{wxVListBox::Select}\label{wxvlistboxselect}
 263
 264 \func{bool}{Select}{\param{size\_t }{item}, \param{bool }{select = true}}
 265
 266 Selects or deselects the specified item which must be valid (i.e. not
 267 equal to {\tt wxNOT\_FOUND}).
 268
 269 Return {\tt true} if the items selection status has changed or {\tt false}
 270 otherwise.
 271
 272 This function is only valid for the multiple selection listboxes, use
 273 \helpref{SetSelection}{wxvlistboxsetselection} for the single selection ones.
 274
 275
 276 \membersection{wxVListBox::SelectAll}\label{wxvlistboxselectall}
 277
 278 \func{bool}{SelectAll}{\void}
 279
 280 Selects all the items in the listbox.
 281
 282 Returns {\tt true} if any items were changed, i.e. if there had been any
 283 unselected items before, or {\tt false} if all the items were already selected.
 284
 285 This method is only valid for multi selection listboxes.
 286
 287 \wxheading{See also}
 288
 289 \helpref{DeselectAll}{wxvlistboxdeselectall}, \helpref{Select}{wxvlistboxselect}
 290
 291
 292 \membersection{wxVListBox::SelectRange}\label{wxvlistboxselectrange}
 293
 294 \func{bool}{SelectRange}{\param{size\_t }{from}, \param{size\_t }{to}}
 295
 296 Selects all items in the specified range which may be given in any order.
 297
 298 Return {\tt true} if the items selection status has changed or {\tt false}
 299 otherwise.
 300
 301 This method is only valid for multi selection listboxes.
 302
 303 \wxheading{See also}
 304
 305 \helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
 306
 307
 308 \func{void}{SetItemCount}{\param{size\_t }{count}}
 309
 310 Set the number of items to be shown in the control.
 311
 312 This is just a synonym for
 313 \helpref{wxVScrolledWindow::SetLineCount()}{wxvscrolledwindowsetlinecount}.
 314
 315
 316 \membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins}
 317
 318 \func{void}{SetMargins}{\param{const wxPoint\& }{pt}}
 319
 320 \func{void}{SetMargins}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 321
 322 Set the margins: horizontal margin is the distance between the window
 323 border and the item contents while vertical margin is half of the
 324 distance between items.
 325
 326 By default both margins are $0$.
 327
 328
 329 \membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection}
 330
 331 \func{void}{SetSelection}{\param{int }{selection}}
 332
 333 Set the selection to the specified item, if it is $-1$ the selection is
 334 unset. The selected item will be automatically scrolled into view if it isn't
 335 currently visible.
 336
 337 This method may be used both with single and multiple selection listboxes.
 338
 339
 340 \membersection{wxVListBox::SetSelectionBackground}\label{wxvlistboxsetselectionbackground}
 341
 342 \func{void}{SetSelectionBackground}{\param{const wxColour\& }{col}}
 343
 344 Sets the colour to be used for the selected cells background. The background of
 345 the standard cells may be changed by simply calling
 346 \helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour}.
 347
 348 \wxheading{See also}
 349
 350 \helpref{GetSelectionBackground}{wxvlistboxgetselectionbackground}
 351
 352
 353 \membersection{wxVListBox::Toggle}\label{wxvlistboxtoggle}
 354
 355 \func{void}{Toggle}{\param{size\_t }{item}}
 356
 357 Toggles the state of the specified {\it item}, i.e. selects it if it was
 358 unselected and deselects it if it was selected.
 359
 360 This method is only valid for multi selection listboxes.
 361
 362 \wxheading{See also}
 363
 364 \helpref{Select}{wxvlistboxselect}
 365