@class wxVListBox
@wxheader{vlbox.h}
- 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 wxVListBox::OnDrawItem
- callback to draw them (so it is a Virtual listbox) and its items can
- have variable height as determined by
- wxVListBox::OnMeasureItem (so it is also a listbox
- with the lines of Variable 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 wxVListBox::SetItemCount 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 wxHtmlListBox, from it.
-
- However it emits the same events as wxListBox and the same
- 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.
+ wxVListBox is a wxListBox-like control with the following two main
+ differences from a regular wxListBox: it can have an arbitrarily huge
+ number of items because it doesn't store them itself but uses the
+ OnDrawItem() callback to draw them (so it is a virtual listbox) and its
+ items can have variable height as determined by OnMeasureItem() (so it is
+ also a listbox with the lines of variable 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 SetItemCount() 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 from it (for example, wxHtmlListBox).
+
+ However it emits the same events as wxListBox and the same 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.
@library{wxcore}
@category{ctrl}
- @appearance{vlistbox.png}
+ <!-- @appearance{vlistbox.png} -->
@see wxSimpleHtmlListBox, wxHtmlListBox
*/
class wxVListBox : public wxVScrolledWindow
{
public:
- //@{
/**
Default constructor, you must call Create() later.
*/
+ wxVListBox();
+ /**
+ Normal constructor which calls Create() internally.
+ */
wxVListBox(wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
- size_t countItems = 0, long style = 0,
- const wxString& name = wxVListBoxNameStr);
- wxVListBox();
- //@}
+ long style = 0, const wxString& name = wxVListBoxNameStr);
+
+ /**
+ Destructor.
+ */
+ virtual ~wxVListBox();
/**
Deletes all items from the control.
/**
Creates the control. To finish creating it you also should call
- SetItemCount() to let it know about the
- number of items it contains.
- The only special style which may be used with wxVListBox is @c wxLB_MULTIPLE
- which indicates that the listbox should support multiple selection.
- Returns @true on success or @false if the control couldn't be created
+ SetItemCount() to let it know about the number of items it contains.
+
+ The only special style which may be used with wxVListBox is
+ @c wxLB_MULTIPLE which indicates that the listbox should support
+ multiple selection.
+
+ @return @true on success or @false if the control couldn't be created.
*/
bool Create(wxWindow* parent, wxWindowID id = wxID_ANY,
const wxPoint& pos = wxDefaultPosition,
- const wxSize& size = wxDefaultSize,
- long style = 0,
+ const wxSize& size = wxDefaultSize, long style = 0,
const wxString& name = wxVListBoxNameStr);
/**
- Deselects all the items in the listbox.
- Returns @true if any items were changed, i.e. if there had been any
- selected items before, or @false if all the items were already deselected.
- This method is only valid for multi selection listboxes.
+ Deselects all the items in the listbox. This method is only valid for
+ multi selection listboxes.
+
+ @return @true if any items were changed, i.e. if there had been any
+ selected items before, or @false if all the items were already
+ deselected.
@see SelectAll(), Select()
*/
/**
Returns the index of the first selected item in the listbox or
@c wxNOT_FOUND if no items are currently selected.
- @a cookie is an opaque parameter which should be passed to the subsequent
- calls to GetNextSelected(). It is needed in
- order to allow parallel iterations over the selected items.
+
+ @a cookie is an opaque parameter which should be passed to the
+ subsequent calls to GetNextSelected(). It is needed in order to allow
+ parallel iterations over the selected items.
+
Here is a typical example of using these functions:
+ @code
+ unsigned long cookie;
+ int item = hlbox->GetFirstSelected(cookie);
+ while ( item != wxNOT_FOUND )
+ {
+ // ... process item ...
+ item = hlbox->GetNextSelected(cookie);
+ }
+ @endcode
+
This method is only valid for multi selection listboxes.
*/
int GetFirstSelected(unsigned long& cookie) const;
wxPoint GetMargins() const;
/**
- Returns the index of the next selected item or @c wxNOT_FOUND if there are
- no more.
+ Returns the index of the next selected item or @c wxNOT_FOUND if there
+ are no more.
+
This method is only valid for multi selection listboxes.
@see GetFirstSelected()
/**
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.
- @see IsSelected(), GetFirstSelected(),
- GetNextSelected()
+ It is valid for both single and multi selection controls. In the former
+ case it may only return 0 or 1 however.
+
+ @see IsSelected(), GetFirstSelected(), GetNextSelected()
*/
size_t GetSelectedCount() const;
/**
- Get the currently selected item or @c wxNOT_FOUND if there is no selection.
+ Get the currently selected item or @c wxNOT_FOUND if there is no
+ selection.
*/
int GetSelection() const;
/**
- Returns the background colour used for the selected cells. By default the
- standard system colour is used.
+ Returns the background colour used for the selected cells. By default
+ the standard system colour is used.
- @see wxSystemSettings::GetColour, SetSelectionBackground()
+ @see wxSystemSettings::GetColour(), SetSelectionBackground()
*/
- const wxColour GetSelectionBackground() const;
+ const wxColour& GetSelectionBackground() const;
/**
Returns @true if the listbox was created with @c wxLB_MULTIPLE style
- and so supports multiple selection or @false if it is a single selection
- listbox.
+ and so supports multiple selection or @false if it is a single
+ selection listbox.
*/
bool HasMultipleSelection() const;
/**
Returns @true if this item is the current one, @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
- IsSelected() but they are different for multi
- selection listboxes where many items may be selected but only one (at most) is
- current.
+
+ The current item is always the same as selected one for the single
+ selection listbox and in this case this method is equivalent to
+ IsSelected() but they are different for multi selection listboxes where
+ many items may be selected but only one (at most) is current.
*/
bool IsCurrent(size_t item) const;
/**
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.
+
+ @todo Change this function signature to non-const.
*/
void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const;
/**
- The derived class must implement this function to actually draw the item
- with the given index on the provided DC.
+ The derived class must implement this function to actually draw the
+ item with the given index on the provided DC.
@param dc
- The device context to use for drawing
+ The device context to use for drawing.
@param rect
The bounding rectangle for the item being drawn (DC clipping
- region is set to this rectangle before calling this function)
+ region is set to this rectangle before calling this function).
@param n
- The index of the item to be drawn
+ The index of the item to be drawn.
+
+ @todo Change this function signature to non-const.
*/
- void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const;
+ virtual void OnDrawItem(wxDC& dc, const wxRect& rect, size_t n) const;
/**
- 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
- OnDrawItem().
+ 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 OnDrawItem().
+
The base class version of this method doesn't do anything.
@param dc
- The device context to use for drawing
+ The device context to use for drawing.
@param rect
- The bounding rectangle for the item
+ The bounding rectangle for the item.
@param n
- The index of the item
+ The index of the item.
+
+ @todo Change this function signature to non-const.
*/
- void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
+ virtual void OnDrawSeparator(wxDC& dc, wxRect& rect, size_t n) const;
/**
- The derived class must implement this method to return the height of the
- specified item (in pixels).
+ The derived class must implement this method to return the height of
+ the specified item (in pixels).
*/
- wxCoord OnMeasureItem(size_t n) const;
+ virtual wxCoord OnMeasureItem(size_t n) const;
/**
Selects or deselects the specified item which must be valid (i.e. not
equal to @c wxNOT_FOUND).
- Return @true if the items selection status has changed or @false
- otherwise.
+
+ @return @true if the items selection status has changed or @false
+ otherwise.
+
This function is only valid for the multiple selection listboxes, use
SetSelection() for the single selection ones.
*/
/**
Selects all the items in the listbox.
- Returns @true if any items were changed, i.e. if there had been any
- unselected items before, or @false if all the items were already selected.
+
+ @return @true if any items were changed, i.e. if there had been any
+ unselected items before, or @false if all the items were
+ already selected.
+
This method is only valid for multi selection listboxes.
@see DeselectAll(), Select()
bool SelectAll();
/**
- Selects all items in the specified range which may be given in any order.
- Return @true if the items selection status has changed or @false
- otherwise.
+ Selects all items in the specified range which may be given in any
+ order.
+
+ @return @true if the items selection status has changed or @false
+ otherwise.
+
This method is only valid for multi selection listboxes.
@see SelectAll(), Select()
/**
Set the number of items to be shown in the control.
- This is just a synonym for
- wxVScrolledWindow::SetRowCount.
+
+ This is just a synonym for wxVScrolledWindow::SetRowCount().
*/
void SetItemCount(size_t count);
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.
*/
void SetMargins(const wxPoint& pt);
/**
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.
+ 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.
*/
void SetSelection(int selection);
/**
- Sets the colour to be used for the selected cells background. The background of
- the standard cells may be changed by simply calling
- wxWindow::SetBackgroundColour.
- 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.
+ Sets the colour to be used for the selected cells background. The
+ background of the standard cells may be changed by simply calling
+ wxWindow::SetBackgroundColour().
+
+ @note Using a non-default background colour may result in control
+ having an appearance different from the similar native controls
+ and should be avoided in general.
@see GetSelectionBackground()
*/
void SetSelectionBackground(const wxColour& col);
/**
- Toggles the state of the specified @e item, i.e. selects it if it was
+ Toggles the state of the specified @a 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.
+
+ @see Select()
*/
void Toggle(size_t item);
};
projects / wxWidgets.git / blobdiff