X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/e0c6027b5a0af9050eca56774967437a66241026..c36cdfc084f779b67668af8cad3eb6906182af21:/docs/latex/wx/vlbox.tex diff --git a/docs/latex/wx/vlbox.tex b/docs/latex/wx/vlbox.tex index 90e63340f3..81e19d5966 100644 --- a/docs/latex/wx/vlbox.tex +++ b/docs/latex/wx/vlbox.tex @@ -13,9 +13,9 @@ wxVListBox is a listbox-like control with the following two main differences from a regular listbox: it can have an arbitrarily huge number of items because -it doesn't store them itself but uses \helpref{OnDrawItem()}{wxvlistboxondrawitem} +it doesn't store them itself but uses \helpref{OnDrawItem()}{wxvlistboxondrawitem} callback to draw them (so it is a {\Large V}irtual listbox) and its items can -have variable height as determined by +have variable height as determined by \helpref{OnMeasureItem()}{wxvlistboxonmeasureitem} (so it is also a listbox with the lines of {\Large V}ariable height). @@ -27,16 +27,30 @@ use this class directly because it has pure virtual functions, but will need to derive your own class, such as \helpref{wxHtmlListBox}{wxhtmllistbox}, from it. However it emits the same events as \helpref{wxListBox}{wxlistbox} and the same -event macros may be used with it. - +event macros may be used with it. Since wxVListBox does not store its items +itself, the events will only contain the index, not any contents such as the +string of an item. + \wxheading{Derived from} -\helpref{wxVScrolledWindow}{wxvscrolledwindow} +\helpref{wxVScrolledWindow}{wxvscrolledwindow}\\ +\helpref{wxPanel}{wxpanel}\\ +\helpref{wxWindow}{wxwindow}\\ +\helpref{wxEvtHandler}{wxevthandler}\\ +\helpref{wxObject}{wxobject} \wxheading{Include files} +\wxheading{Library} + +\helpref{wxCore}{librarieslist} + +\wxheading{See also} + +\helpref{wxSimpleHtmlListBox}{wxsimplehtmllistbox}, \helpref{wxHtmlListBox}{wxhtmllistbox} + \latexignore{\rtfignore{\wxheading{Members}}} @@ -60,18 +74,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,20 +138,110 @@ 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} -Get the currently selected item or $-1$ if there is no selection. +Get the currently selected item or {\tt wxNOT\_FOUND} 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 +286,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}} @@ -148,7 +338,7 @@ specified item (in pixels). Set the number of items to be shown in the control. This is just a synonym for -\helpref{wxVScrolledWindow::SetLineCount()}{wxvscrolledwindowsetlinecount}. +\helpref{wxVScrolledWindow::SetRowCount()}{wxvarvscrollhelpersetrowcount}. \membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins} @@ -172,3 +362,36 @@ 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}. + +Notice that using non-default background colour may result in control having +appearance different from the similar native controls and so should in general +be avoided. + +\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} +