84e3b6cd27
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/branches/WX_2_8_BRANCH@53430 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
388 lines
12 KiB
TeX
388 lines
12 KiB
TeX
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
%% Name: vlbox.tex
|
|
%% Purpose: wxVListBox documentation
|
|
%% Author: Vadim Zeitlin
|
|
%% Modified by:
|
|
%% Created: 01.06.03
|
|
%% RCS-ID: $Id$
|
|
%% Copyright: (c) 2003 Vadim Zeitlin <vadim@wxwindows.org>
|
|
%% License: wxWindows license
|
|
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
|
|
|
|
\section{\class{wxVListBox}}\label{wxvlistbox}
|
|
|
|
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}
|
|
callback to draw them (so it is a {\Large V}irtual listbox) and its items can
|
|
have variable height as determined by
|
|
\helpref{OnMeasureItem()}{wxvlistboxonmeasureitem} (so it is also a listbox
|
|
with the lines of {\Large V}ariable height).
|
|
|
|
Also, as a consequence of its virtual nature, it doesn't have any methods to
|
|
append or insert items in it as it isn't necessary to do it: you just have to
|
|
call \helpref{SetItemCount()}{wxvlistboxsetitemcount} to tell the control how
|
|
many items it should display. Of course, this also means that you will never
|
|
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.
|
|
|
|
\wxheading{Derived from}
|
|
|
|
\helpref{wxVScrolledWindow}{wxvscrolledwindow}\\
|
|
\helpref{wxPanel}{wxpanel}\\
|
|
\helpref{wxWindow}{wxwindow}\\
|
|
\helpref{wxEvtHandler}{wxevthandler}\\
|
|
\helpref{wxObject}{wxobject}
|
|
|
|
\wxheading{Include files}
|
|
|
|
<wx/vlbox.h>
|
|
|
|
\wxheading{See also}
|
|
|
|
\helpref{wxSimpleHtmlListBox}{wxsimplehtmllistbox}, \helpref{wxHtmlListBox}{wxhtmllistbox}
|
|
|
|
\latexignore{\rtfignore{\wxheading{Members}}}
|
|
|
|
|
|
\membersection{wxVListBox::wxVListBox}\label{wxvlistboxctor}
|
|
|
|
\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}}
|
|
|
|
Normal constructor which calls \helpref{Create()}{wxvlistboxcreate} internally.
|
|
|
|
\func{}{wxVListBox}{\void}
|
|
|
|
Default constructor, you must call \helpref{Create()}{wxvlistboxcreate} later.
|
|
|
|
|
|
\membersection{wxVListBox::Clear}\label{wxvlistboxclear}
|
|
|
|
\func{void}{Clear}{\void}
|
|
|
|
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{long }{style = 0}, \param{const wxString\& }{name = wxVListBoxNameStr}}
|
|
|
|
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.
|
|
|
|
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}
|
|
|
|
Get the number of items in the control.
|
|
|
|
\wxheading{See also}
|
|
|
|
\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 {\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 }{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}}
|
|
|
|
The derived class must implement this function to actually draw the item
|
|
with the given index on the provided DC.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{dc}{The device context to use for drawing}
|
|
|
|
\docparam{rect}{The bounding rectangle for the item being drawn (DC clipping
|
|
region is set to this rectangle before calling this function)}
|
|
|
|
\docparam{n}{The index of the item to be drawn}
|
|
|
|
|
|
\membersection{wxVListBox::OnDrawSeparator}\label{wxvlistboxondrawseparator}
|
|
|
|
\constfunc{void}{OnDrawSeparator}{\param{wxDC\& }{dc}, \param{wxRect\& }{rect}, \param{size\_t }{n}}
|
|
|
|
This method may be used to draw separators between the lines. The rectangle
|
|
passed to it may be modified, typically to deflate it a bit before passing to
|
|
\helpref{OnDrawItem()}{wxvlistboxondrawitem}.
|
|
|
|
The base class version of this method doesn't do anything.
|
|
|
|
\wxheading{Parameters}
|
|
|
|
\docparam{dc}{The device context to use for drawing}
|
|
|
|
\docparam{rect}{The bounding rectangle for the item}
|
|
|
|
\docparam{n}{The index of the item}
|
|
|
|
|
|
\membersection{wxVListBox::OnMeasureItem}\label{wxvlistboxonmeasureitem}
|
|
|
|
\constfunc{wxCoord}{OnMeasureItem}{\param{size\_t }{n}}
|
|
|
|
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}}
|
|
|
|
Set the number of items to be shown in the control.
|
|
|
|
This is just a synonym for
|
|
\helpref{wxVScrolledWindow::SetLineCount()}{wxvscrolledwindowsetlinecount}.
|
|
|
|
|
|
\membersection{wxVListBox::SetMargins}\label{wxvlistboxsetmargins}
|
|
|
|
\func{void}{SetMargins}{\param{const wxPoint\& }{pt}}
|
|
|
|
\func{void}{SetMargins}{\param{wxCoord }{x}, \param{wxCoord }{y}}
|
|
|
|
Set the margins: horizontal margin is the distance between the window
|
|
border and the item contents while vertical margin is half of the
|
|
distance between items.
|
|
|
|
By default both margins are $0$.
|
|
|
|
|
|
\membersection{wxVListBox::SetSelection}\label{wxvlistboxsetselection}
|
|
|
|
\func{void}{SetSelection}{\param{int }{selection}}
|
|
|
|
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}
|
|
|