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{size\_t }{countItems = 0}, \param{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}}
  64
  65 Creates the control and optionally sets the initial number of items in it
  66 (it may also be set or changed later with
  67 \helpref{SetItemCount()}{wxvlistboxsetitemcount}).
  68
  69 There are no special styles defined for wxVListBox, in particular the wxListBox
  70 styles can not be used here.
  71
  72 Returns {\tt true} on success or {\tt false} if the control couldn't be created
  73
  74
  75 \membersection{wxVListBox::GetItemCount}\label{wxvlistboxgetitemcount}
  76
  77 \constfunc{size\_t}{GetItemCount}{\void}
  78
  79 Get the number of items in the control.
  80
  81 \wxheading{See also}
  82
  83 \helpref{SetItemCount()}{wxvlistboxsetitemcount}
  84
  85
  86 \membersection{wxVListBox::GetSelection}\label{wxvlistboxgetselection}
  87
  88 \constfunc{int}{GetSelection}{\void}
  89
  90 Get the currently selected item or $-1$ if there is no selection.
  91
  92
  93 \membersection{wxVListBox::IsSelected}\label{wxvlistboxisselected}
  94
  95 \constfunc{bool}{IsSelected}{\param{size\_t }{line}}
  96
  97 Returns {\tt true} if this item is selected, {\tt false} otherwise.
  98
  99
 100 \membersection{wxVListBox::OnDrawItem}\label{wxvlistboxondrawitem}
 101
 102 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
 103
 104 The derived class must implement this function to actually draw the item
 105 with the given index on the provided DC.
 106
 107 \wxheading{Parameters}
 108
 109 \docparam{dc}{The device context to use for drawing}
 110
 111 \docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
 112 region is set to this rectangle before calling this function)}
 113
 114 \docparam{n}{The index of the item to be drawn}
 115
 116
 117 \membersection{wxVListBox::OnDrawSeparator}\label{wxvlistboxondrawseparator}
 118
 119 \constfunc{void}{OnDrawSeparator}{\param{wxDC\& }{dc}, \param{wxRect\& }{rect}, \param{size\_t }{n}}
 120
 121 This method may be used to draw separators between the lines. The rectangle
 122 passed to it may be modified, typically to deflate it a bit before passing to
 123 \helpref{OnDrawItem()}{wxvlistboxondrawitem}.
 124
 125 The base class version of this method doesn't do anything.
 126
 127 \wxheading{Parameters}
 128
 129 \docparam{dc}{The device context to use for drawing}
 130
 131 \docparam{rect}{The bounding rectangle for the item}
 132
 133 \docparam{n}{The index of the item}
 134
 135
 136 \membersection{wxVListBox::OnMeasureItem}\label{wxvlistboxonmeasureitem}
 137
 138 \constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{n}}
 139
 140 The derived class must implement this method to return the height of the
 141 specified item (in pixels).
 142
 143
 144 \membersection{wxVListBox::SetItemCount}\label{wxvlistboxsetitemcount}
 145
 146 \func{void}{SetItemCount}{\param{size\_t }{count}}
 147
 148 Set the number of items to be shown in the control.
 149
 150 This is just a synonym for
 151 \helpref{wxVScrolledWindow::SetLineCount()}{wxvscrolledwindowsetlinecount}.
 152
 153
 154 \membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins}
 155
 156 \func{void}{SetMargins}{\param{const wxPoint\& }{pt}}
 157
 158 \func{void}{SetMargins}{\param{wxCoord }{x}, \param{wxCoord }{y}}
 159
 160 Set the margins: horizontal margin is the distance between the window
 161 border and the item contents while vertical margin is half of the
 162 distance between items.
 163
 164 By default both margins are $0$.
 165
 166
 167 \membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection}
 168
 169 \func{void}{SetSelection}{\param{int }{selection}}
 170
 171 Set the selection to the specified item, if it is $-1$ the selection is
 172 unset. The selected item will be automatically scrolled into view if it isn't
 173 currently visible.
 174