X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e0c6027b5a0af9050eca56774967437a66241026..05db64b2e987e6c6920f00610b2aa9ad25fb2c64:/docs/latex/wx/vlbox.tex

diff --git a/docs/latex/wx/vlbox.tex b/docs/latex/wx/vlbox.tex
index 90e63340f3..e57ca9fd69 100644
--- a/docs/latex/wx/vlbox.tex
+++ b/docs/latex/wx/vlbox.tex
@@ -6,7 +6,7 @@
 %% Created:     01.06.03
 %% RCS-ID:      $Id$
 %% Copyright:   (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
-%% License:     wxWindows license
+%% License:     wxWidgets license
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
 \section{\class{wxVListBox}}\label{wxvlistbox}
@@ -60,18 +60,59 @@ Deletes all items from the control.
 
 \membersection{wxVListBox::Create}\label{wxvlistboxcreate}
 
-\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}}
+\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}}
 
-Creates the control and optionally sets the initial number of items in it
-(it may also be set or changed later with 
-\helpref{SetItemCount()}{wxvlistboxsetitemcount}).
+Creates the control. To finish creating it you also should call 
+\helpref{SetItemCount()}{wxvlistboxsetitemcount} to let it know about the
+number of items it contains.
 
-There are no special styles defined for wxVListBox, in particular the wxListBox
-styles can not be used here.
+The only special style which may be used with wxVListBox is {\tt wxLB\_MULTIPLE} 
+which indicates that the listbox should support multiple selection.
 
 Returns {\tt true} on success or {\tt false} if the control couldn't be created
 
 
+\membersection{wxVListBox::DeselectAll}\label{wxvlistboxdeselectall}
+
+\func{bool}{DeselectAll}{\void}
+
+Deselects all the items in the listbox.
+
+Returns {\tt true} if any items were changed, i.e. if there had been any
+selected items before, or {\tt false} if all the items were already deselected.
+
+This method is only valid for multi selection listboxes.
+
+\wxheading{See also}
+
+\helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
+
+
+\membersection{wxVListBox::GetFirstSelected}\label{wxvlistboxgetfirstselected}
+
+\constfunc{int}{GetFirstSelected}{\param{unsigned long\& }{cookie}}
+
+Returns the index of the first selected item in the listbox or 
+{\tt wxNOT\_FOUND} if no items are currently selected.
+
+\arg{cookie} is an opaque parameter which should be passed to the subsequent
+calls to \helpref{GetNextSelected}{wxvlistboxgetnextselected}. It is needed in
+order to allow parallel iterations over the selected items.
+
+Here is a typical example of using these functions:
+\begin{verbatim}
+unsigned long cookie;
+int item = hlbox->GetFirstSelected(cookie);
+while ( item != wxNOT_FOUND )
+{
+    ... process item ...
+    item = hlbox->GetNextSelected(cookie);
+}
+\end{verbatim}
+
+This method is only valid for multi selection listboxes.
+
+
 \membersection{wxVListBox::GetItemCount}\label{wxvlistboxgetitemcount}
 
 \constfunc{size\_t}{GetItemCount}{\void}
@@ -83,6 +124,48 @@ Get the number of items in the control.
 \helpref{SetItemCount()}{wxvlistboxsetitemcount}
 
 
+\membersection{wxVListBox::GetMargins}\label{wxvlistboxgetmargins}
+
+\constfunc{wxPoint}{GetMargins}{\void}
+
+Returns the margins used by the control. The {\tt x} field of the returned
+point is the horizontal margin and the {\tt y} field is the vertical one.
+
+\wxheading{See also}
+
+\helpref{SetMargins}{wxvlistboxsetmargins}
+
+
+\membersection{wxVListBox::GetNextSelected}\label{wxvlistboxgetnextselected}
+
+\constfunc{int}{GetNextSelected}{\param{unsigned long\& }{cookie}}
+
+Returns the index of the next selected item or {\tt wxNOT\_FOUND} if there are
+no more.
+
+This method is only valid for multi selection listboxes.
+
+\wxheading{See also}
+
+\helpref{GetFirstSelected}{wxvlistboxgetfirstselected}
+
+
+\membersection{wxVListBox::GetSelectedCount}\label{wxvlistboxgetselectedcount}
+
+\constfunc{size\_t}{GetSelectedCount}{\void}
+
+Returns the number of the items currently selected.
+
+It is valid for both single and multi selection controls. In the former case it
+may only return $0$ or $1$ however.
+
+\wxheading{See also}
+
+\helpref{IsSelected}{wxvlistboxisselected},\\
+\helpref{GetFirstSelected}{wxvlistboxgetfirstselected},\\
+\helpref{GetNextSelected}{wxvlistboxgetnextselected}
+
+
 \membersection{wxVListBox::GetSelection}\label{wxvlistboxgetselection}
 
 \constfunc{int}{GetSelection}{\void}
@@ -90,13 +173,61 @@ Get the number of items in the control.
 Get the currently selected item or $-1$ if there is no selection.
 
 
+\membersection{wxVListBox::GetSelectionBackground}\label{wxvlistboxgetselectionbackground}
+
+\constfunc{const wxColour\&}{GetSelectionBackground}{\void}
+
+Returns the background colour used for the selected cells. By default the
+standard system colour is used.
+
+\wxheading{See also}
+
+\helpref{wxSystemSettings::GetColour}{wxsystemsettingsgetcolour},\\
+\helpref{SetSelectionBackground}{wxvlistboxsetselectionbackground}
+
+
+\membersection{wxVListBox::HasMultipleSelection}\label{wxvlistboxishasmultipleselection}
+
+\constfunc{bool}{HasMultipleSelection}{\void}
+
+Returns {\tt true} if the listbox was created with {\tt wxLB\_MULTIPLE} style
+and so supports multiple selection or {\tt false} if it is a single selection
+listbox.
+
+
+\membersection{wxVListBox::IsCurrent}\label{wxvlistboxiscurrent}
+
+\constfunc{bool}{IsCurrent}{\param{size\_t }{item}}
+
+Returns {\tt true} if this item is the current one, {\tt false} otherwise.
+
+Current item is always the same as selected one for the single selection
+listbox and in this case this method is equivalent to 
+\helpref{IsSelected}{wxvlistboxisselected} but they are different for multi
+selection listboxes where many items may be selected but only one (at most) is
+current.
+
+
 \membersection{wxVListBox::IsSelected}\label{wxvlistboxisselected}
 
-\constfunc{bool}{IsSelected}{\param{size\_t }{line}}
+\constfunc{bool}{IsSelected}{\param{size\_t }{item}}
 
 Returns {\tt true} if this item is selected, {\tt false} otherwise.
 
 
+\membersection{wxVListBox::OnDrawBackground}\label{wxvlistboxondrawbackground}
+
+\constfunc{void}{OnDrawBackground}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
+
+This method is used to draw the items background and, maybe, a border
+around it.
+
+The base class version implements a reasonable default behaviour which
+consists in drawing the selected item with the standard background
+colour and drawing a border around the item if it is either selected or
+current.
+
+
 \membersection{wxVListBox::OnDrawItem}\label{wxvlistboxondrawitem}
 
 \constfunc{void}{OnDrawItem}{\param{wxDC\& }{dc}, \param{const wxRect\& }{rect}, \param{size\_t }{n}}
@@ -141,6 +272,51 @@ The derived class must implement this method to return the height of the
 specified item (in pixels).
 
 
+\membersection{wxVListBox::Select}\label{wxvlistboxselect}
+
+\func{bool}{Select}{\param{size\_t }{item}, \param{bool }{select = true}}
+
+Selects or deselects the specified item which must be valid (i.e. not
+equal to {\tt wxNOT\_FOUND}).
+
+Return {\tt true} if the items selection status has changed or {\tt false}
+otherwise.
+
+This function is only valid for the multiple selection listboxes, use 
+\helpref{SetSelection}{wxvlistboxsetselection} for the single selection ones.
+
+
+\membersection{wxVListBox::SelectAll}\label{wxvlistboxselectall}
+
+\func{bool}{SelectAll}{\void}
+
+Selects all the items in the listbox.
+
+Returns {\tt true} if any items were changed, i.e. if there had been any
+unselected items before, or {\tt false} if all the items were already selected.
+
+This method is only valid for multi selection listboxes.
+
+\wxheading{See also}
+
+\helpref{DeselectAll}{wxvlistboxdeselectall}, \helpref{Select}{wxvlistboxselect}
+
+
+\membersection{wxVListBox::SelectRange}\label{wxvlistboxselectrange}
+
+\func{bool}{SelectRange}{\param{size\_t }{from}, \param{size\_t }{to}}
+
+Selects all items in the specified range which may be given in any order.
+
+Return {\tt true} if the items selection status has changed or {\tt false}
+otherwise.
+
+This method is only valid for multi selection listboxes.
+
+\wxheading{See also}
+
+\helpref{SelectAll}{wxvlistboxselectall}, \helpref{Select}{wxvlistboxselect}
+
 \membersection{wxVListBox::SetItemCount}\label{wxvlistboxsetitemcount}
 
 \func{void}{SetItemCount}{\param{size\_t }{count}}
@@ -172,3 +348,32 @@ Set the selection to the specified item, if it is $-1$ the selection is
 unset. The selected item will be automatically scrolled into view if it isn't
 currently visible.
 
+This method may be used both with single and multiple selection listboxes.
+
+
+\membersection{wxVListBox::SetSelectionBackground}\label{wxvlistboxsetselectionbackground}
+
+\func{void}{SetSelectionBackground}{\param{const wxColour\& }{col}}
+
+Sets the colour to be used for the selected cells background. The background of
+the standard cells may be changed by simply calling 
+\helpref{SetBackgroundColour}{wxwindowsetbackgroundcolour}.
+
+\wxheading{See also}
+
+\helpref{GetSelectionBackground}{wxvlistboxgetselectionbackground}
+
+
+\membersection{wxVListBox::Toggle}\label{wxvlistboxtoggle}
+
+\func{void}{Toggle}{\param{size\_t }{item}}
+
+Toggles the state of the specified \arg{item}, i.e. selects it if it was
+unselected and deselects it if it was selected.
+
+This method is only valid for multi selection listboxes.
+
+\wxheading{See also}
+
+\helpref{Select}{wxvlistboxselect}
+
