X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3c4f71cc3d63fb7bdfbd6cec3e39c8a8679f3e60..27608f1130d577131674dc546b62ef11f75226d1:/interface/vlbox.h diff --git a/interface/vlbox.h b/interface/vlbox.h index 6b06db28f1..d376222010 100644 --- a/interface/vlbox.h +++ b/interface/vlbox.h @@ -10,46 +10,50 @@ @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} + @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. @@ -58,23 +62,26 @@ public: /** 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() */ @@ -83,11 +90,23 @@ public: /** 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; @@ -108,8 +127,9 @@ public: 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() @@ -118,41 +138,42 @@ public: /** 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; @@ -164,53 +185,63 @@ public: /** 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. */ @@ -218,8 +249,11 @@ public: /** 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() @@ -227,9 +261,12 @@ public: 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() @@ -238,8 +275,8 @@ public: /** 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); @@ -248,6 +285,7 @@ public: 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); @@ -256,28 +294,34 @@ public: /** 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); };