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: vlbox.tex 53430 2008-05-02 15:46:36Z BP $ 8%% Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwindows.org> 9%% License: wxWindows license 10%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% 11 12\section{\class{wxVListBox}}\label{wxvlistbox} 13 14wxVListBox is a listbox-like control with the following two main differences 15from a regular listbox: it can have an arbitrarily huge number of items because 16it doesn't store them itself but uses \helpref{OnDrawItem()}{wxvlistboxondrawitem} 17callback to draw them (so it is a {\Large V}irtual listbox) and its items can 18have variable height as determined by 19\helpref{OnMeasureItem()}{wxvlistboxonmeasureitem} (so it is also a listbox 20with the lines of {\Large V}ariable height). 21 22Also, as a consequence of its virtual nature, it doesn't have any methods to 23append or insert items in it as it isn't necessary to do it: you just have to 24call \helpref{SetItemCount()}{wxvlistboxsetitemcount} to tell the control how 25many items it should display. Of course, this also means that you will never 26use this class directly because it has pure virtual functions, but will need to 27derive your own class, such as \helpref{wxHtmlListBox}{wxhtmllistbox}, from it. 28 29However it emits the same events as \helpref{wxListBox}{wxlistbox} and the same 30event 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{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}} 54 55Normal constructor which calls \helpref{Create()}{wxvlistboxcreate} internally. 56 57\func{}{wxVListBox}{\void} 58 59Default constructor, you must call \helpref{Create()}{wxvlistboxcreate} later. 60 61 62\membersection{wxVListBox::Clear}\label{wxvlistboxclear} 63 64\func{void}{Clear}{\void} 65 66Deletes 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 73Creates the control. To finish creating it you also should call 74\helpref{SetItemCount()}{wxvlistboxsetitemcount} to let it know about the 75number of items it contains. 76 77The only special style which may be used with wxVListBox is {\tt wxLB\_MULTIPLE} 78which indicates that the listbox should support multiple selection. 79 80Returns {\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 87Deselects all the items in the listbox. 88 89Returns {\tt true} if any items were changed, i.e. if there had been any 90selected items before, or {\tt false} if all the items were already deselected. 91 92This 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 103Returns 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 107calls to \helpref{GetNextSelected}{wxvlistboxgetnextselected}. It is needed in 108order to allow parallel iterations over the selected items. 109 110Here is a typical example of using these functions: 111\begin{verbatim} 112unsigned long cookie; 113int item = hlbox->GetFirstSelected(cookie); 114while ( item != wxNOT_FOUND ) 115{ 116 ... process item ... 117 item = hlbox->GetNextSelected(cookie); 118} 119\end{verbatim} 120 121This method is only valid for multi selection listboxes. 122 123 124\membersection{wxVListBox::GetItemCount}\label{wxvlistboxgetitemcount} 125 126\constfunc{size\_t}{GetItemCount}{\void} 127 128Get 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 139Returns the margins used by the control. The {\tt x} field of the returned 140point 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 151Returns the index of the next selected item or {\tt wxNOT\_FOUND} if there are 152no more. 153 154This 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 165Returns the number of the items currently selected. 166 167It is valid for both single and multi selection controls. In the former case it 168may 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 181Get 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 188Returns the background colour used for the selected cells. By default the 189standard 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 201Returns {\tt true} if the listbox was created with {\tt wxLB\_MULTIPLE} style 202and so supports multiple selection or {\tt false} if it is a single selection 203listbox. 204 205 206\membersection{wxVListBox::IsCurrent}\label{wxvlistboxiscurrent} 207 208\constfunc{bool}{IsCurrent}{\param{size\_t }{item}} 209 210Returns {\tt true} if this item is the current one, {\tt false} otherwise. 211 212Current item is always the same as selected one for the single selection 213listbox and in this case this method is equivalent to 214\helpref{IsSelected}{wxvlistboxisselected} but they are different for multi 215selection listboxes where many items may be selected but only one (at most) is 216current. 217 218 219\membersection{wxVListBox::IsSelected}\label{wxvlistboxisselected} 220 221\constfunc{bool}{IsSelected}{\param{size\_t }{item}} 222 223Returns {\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 230This method is used to draw the items background and, maybe, a border 231around it. 232 233The base class version implements a reasonable default behaviour which 234consists in drawing the selected item with the standard background 235colour and drawing a border around the item if it is either selected or 236current. 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 243The derived class must implement this function to actually draw the item 244with 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 251region 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 260This method may be used to draw separators between the lines. The rectangle 261passed to it may be modified, typically to deflate it a bit before passing to 262\helpref{OnDrawItem()}{wxvlistboxondrawitem}. 263 264The 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 279The derived class must implement this method to return the height of the 280specified 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 287Selects or deselects the specified item which must be valid (i.e. not 288equal to {\tt wxNOT\_FOUND}). 289 290Return {\tt true} if the items selection status has changed or {\tt false} 291otherwise. 292 293This 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 301Selects all the items in the listbox. 302 303Returns {\tt true} if any items were changed, i.e. if there had been any 304unselected items before, or {\tt false} if all the items were already selected. 305 306This 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 317Selects all items in the specified range which may be given in any order. 318 319Return {\tt true} if the items selection status has changed or {\tt false} 320otherwise. 321 322This 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 332Set the number of items to be shown in the control. 333 334This 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 344Set the margins: horizontal margin is the distance between the window 345border and the item contents while vertical margin is half of the 346distance between items. 347 348By default both margins are $0$. 349 350 351\membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection} 352 353\func{void}{SetSelection}{\param{int }{selection}} 354 355Set the selection to the specified item, if it is $-1$ the selection is 356unset. The selected item will be automatically scrolled into view if it isn't 357currently visible. 358 359This 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 366Sets the colour to be used for the selected cells background. The background of 367the standard cells may be changed by simply calling 368\helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour}. 369 370\wxheading{See also} 371 372\helpref{GetSelectionBackground}{wxvlistboxgetselectionbackground} 373 374 375\membersection{wxVListBox::Toggle}\label{wxvlistboxtoggle} 376 377\func{void}{Toggle}{\param{size\_t }{item}} 378 379Toggles the state of the specified \arg{item}, i.e. selects it if it was 380unselected and deselects it if it was selected. 381 382This method is only valid for multi selection listboxes. 383 384\wxheading{See also} 385 386\helpref{Select}{wxvlistboxselect} 387 388