Moved all interface headers into a 'wx' subdirectory for proper use of Doxygen path settings.
git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@54385 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775
This commit is contained in:
328
interface/wx/vlbox.h
Normal file
328
interface/wx/vlbox.h
Normal file
@@ -0,0 +1,328 @@
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
// Name: vlbox.h
|
||||
// Purpose: interface of wxVListBox
|
||||
// Author: wxWidgets team
|
||||
// RCS-ID: $Id$
|
||||
// Licence: wxWindows license
|
||||
/////////////////////////////////////////////////////////////////////////////
|
||||
|
||||
/**
|
||||
@class wxVListBox
|
||||
@wxheader{vlbox.h}
|
||||
|
||||
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} -->
|
||||
|
||||
@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,
|
||||
long style = 0, const wxString& name = wxVListBoxNameStr);
|
||||
|
||||
/**
|
||||
Destructor.
|
||||
*/
|
||||
virtual ~wxVListBox();
|
||||
|
||||
/**
|
||||
Deletes all items from the control.
|
||||
*/
|
||||
void Clear();
|
||||
|
||||
/**
|
||||
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.
|
||||
|
||||
@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 wxString& name = wxVListBoxNameStr);
|
||||
|
||||
/**
|
||||
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()
|
||||
*/
|
||||
bool DeselectAll();
|
||||
|
||||
/**
|
||||
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.
|
||||
|
||||
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;
|
||||
|
||||
/**
|
||||
Get the number of items in the control.
|
||||
|
||||
@see SetItemCount()
|
||||
*/
|
||||
size_t GetItemCount() const;
|
||||
|
||||
/**
|
||||
Returns the margins used by the control. The @c x field of the returned
|
||||
point is the horizontal margin and the @c y field is the vertical one.
|
||||
|
||||
@see SetMargins()
|
||||
*/
|
||||
wxPoint GetMargins() const;
|
||||
|
||||
/**
|
||||
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()
|
||||
*/
|
||||
int GetNextSelected(unsigned long& cookie) const;
|
||||
|
||||
/**
|
||||
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()
|
||||
*/
|
||||
size_t GetSelectedCount() const;
|
||||
|
||||
/**
|
||||
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.
|
||||
|
||||
@see wxSystemSettings::GetColour(), SetSelectionBackground()
|
||||
*/
|
||||
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.
|
||||
*/
|
||||
bool HasMultipleSelection() const;
|
||||
|
||||
/**
|
||||
Returns @true if this item is the current one, @false otherwise.
|
||||
|
||||
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;
|
||||
|
||||
/**
|
||||
Returns @true if this item is selected, @false otherwise.
|
||||
*/
|
||||
bool IsSelected(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.
|
||||
|
||||
@param dc
|
||||
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).
|
||||
@param n
|
||||
The index of the item to be drawn.
|
||||
|
||||
@todo Change this function signature to non-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().
|
||||
|
||||
The base class version of this method doesn't do anything.
|
||||
|
||||
@param dc
|
||||
The device context to use for drawing.
|
||||
@param rect
|
||||
The bounding rectangle for the item.
|
||||
@param n
|
||||
The index of the item.
|
||||
|
||||
@todo Change this function signature to non-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).
|
||||
*/
|
||||
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.
|
||||
|
||||
This function is only valid for the multiple selection listboxes, use
|
||||
SetSelection() for the single selection ones.
|
||||
*/
|
||||
bool Select(size_t item, bool select = true);
|
||||
|
||||
/**
|
||||
Selects all the items in the listbox.
|
||||
|
||||
@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.
|
||||
|
||||
This method is only valid for multi selection listboxes.
|
||||
|
||||
@see SelectAll(), Select()
|
||||
*/
|
||||
bool SelectRange(size_t from, size_t to);
|
||||
|
||||
/**
|
||||
Set the number of items to be shown in the control.
|
||||
|
||||
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);
|
||||
void SetMargins(wxCoord x, wxCoord y);
|
||||
//@}
|
||||
|
||||
/**
|
||||
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.
|
||||
*/
|
||||
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().
|
||||
|
||||
@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 @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);
|
||||
};
|
||||
|
Reference in New Issue
Block a user