Finished initial review of [v*] interface headers.

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@53425 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/vlbox.h

@@ -10,46 +10,51 @@
     @class wxVListBox
     @wxheader{vlbox.h}
 
-    wxVListBox is a listbox-like control with the following two main differences
+    wxVListBox is a wxListBox-like control with the following two main
-    from a regular listbox: it can have an arbitrarily huge number of items because
+    differences from a regular wxListBox: it can have an arbitrarily huge
-    it doesn't store them itself but uses wxVListBox::OnDrawItem
+    number of items because it doesn't store them itself but uses the
-    callback to draw them (so it is a Virtual listbox) and its items can
+    OnDrawItem() callback to draw them (so it is a virtual listbox) and its
-    have variable height as determined by
+    items can have variable height as determined by OnMeasureItem() (so it is
-    wxVListBox::OnMeasureItem (so it is also a listbox
+    also a listbox with the lines of variable height).
-    with the lines of Variable height).
 
-    Also, as a consequence of its virtual nature, it doesn't have any methods to
+    Also, as a consequence of its virtual nature, it doesn't have any methods
-    append or insert items in it as it isn't necessary to do it: you just have to
+    to append or insert items in it as it isn't necessary to do it: you just
-    call wxVListBox::SetItemCount to tell the control how
+    have to call SetItemCount() to tell the control how many items it should
-    many items it should display. Of course, this also means that you will never
+    display. Of course, this also means that you will never use this class
-    use this class directly because it has pure virtual functions, but will need to
+    directly because it has pure virtual functions, but will need to derive
-    derive your own class, such as wxHtmlListBox, from it.
+    your own class from it (for example, wxHtmlListBox).
 
-    However it emits the same events as wxListBox and the same
+    However it emits the same events as wxListBox and the same event macros may
-    event macros may be used with it. Since wxVListBox does not store its items
+    be used with it. Since wxVListBox does not store its items itself, the
-    itself, the events will only contain the index, not any contents such as the
+    events will only contain the index, not any contents such as the string of
-    string of an item.
+    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();
+
-    //@}
+    /**
+        Destructor.
+    */
+    virtual ~wxVListBox();
 
     /**
         Deletes all items from the control.
@@ -58,23 +63,26 @@ public:
 
     /**
         Creates the control. To finish creating it you also should call
-        SetItemCount() to let it know about the
+        SetItemCount() to let it know about the number of items it contains.
-        number of items it contains.
+
-        The only special style which may be used with wxVListBox is @c wxLB_MULTIPLE
+        The only special style which may be used with wxVListBox is
-        which indicates that the listbox should support multiple selection.
+        @c wxLB_MULTIPLE which indicates that the listbox should support
-        Returns @true on success or @false if the control couldn't be created
+        multiple selection.
+
+        @returns @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,
+                const wxSize& size = wxDefaultSize, long style = 0,
-                long style = 0,
                 const wxString& name = wxVListBoxNameStr);
 
     /**
-        Deselects all the items in the listbox.
+        Deselects all the items in the listbox. This method is only valid for
-        Returns @true if any items were changed, i.e. if there had been any
+        multi selection listboxes.
-        selected items before, or @false if all the items were already deselected.
+
-        This method is only valid for multi selection listboxes.
+        @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.
 
         @see SelectAll(), Select()
     */
@@ -83,11 +91,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
+        @a cookie is an opaque parameter which should be passed to the
-        order to allow parallel iterations over the selected items.
+        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 +128,9 @@ public:
     wxPoint GetMargins() const;
 
     /**
-        Returns the index of the next selected item or @c wxNOT_FOUND if there are
+        Returns the index of the next selected item or @c wxNOT_FOUND if there
-        no more.
+        are no more.
+
         This method is only valid for multi selection listboxes.
 
         @see GetFirstSelected()
@@ -118,41 +139,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(),
+        It is valid for both single and multi selection controls. In the former
-             GetNextSelected()
+        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
+        Returns the background colour used for the selected cells. By default
-        standard system colour is used.
+        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
+        and so supports multiple selection or @false if it is a single
-        listbox.
+        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
+        The current item is always the same as selected one for the single
-        IsSelected() but they are different for multi
+        selection listbox and in this case this method is equivalent to
-        selection listboxes where many items may be selected but only one (at most) is
+        IsSelected() but they are different for multi selection listboxes where
-        current.
+        many items may be selected but only one (at most) is current.
     */
     bool IsCurrent(size_t item) const;
 
@@ -164,6 +186,7 @@ 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
@@ -172,45 +195,48 @@ public:
     void OnDrawBackground(wxDC& dc, const wxRect& rect, size_t n) const;
 
     /**
-        The derived class must implement this function to actually draw the item
+        The derived class must implement this function to actually draw the
-        with the given index on the provided DC.
+        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.
     */
-    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
+        This method may be used to draw separators between the lines. The
-        passed to it may be modified, typically to deflate it a bit before passing to
+        rectangle passed to it may be modified, typically to deflate it a bit
-        OnDrawItem().
+        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.
     */
-    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
+        The derived class must implement this method to return the height of
-        specified item (in pixels).
+        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.
+        @returns @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 +244,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.
+        @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.
+
         This method is only valid for multi selection listboxes.
 
         @see DeselectAll(), Select()
@@ -227,9 +256,12 @@ public:
     bool SelectAll();
 
     /**
-        Selects all items in the specified range which may be given in any order.
+        Selects all items in the specified range which may be given in any
-        Return @true if the items selection status has changed or @false
+        order.
-        otherwise.
+
+        @returns @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 +270,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 +280,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 +289,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
+        unset. The selected item will be automatically scrolled into view if it
-        currently visible.
+        isn't currently visible.
-        This method may be used both with single and multiple selection listboxes.
+
+        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
+        Sets the colour to be used for the selected cells background. The
-        the standard cells may be changed by simply calling
+        background of the standard cells may be changed by simply calling
-        wxWindow::SetBackgroundColour.
+        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
+        @note Using a non-default background colour may result in control
-        be avoided.
+              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);
 };