Finished initial review of some [co*] interface headers.

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

diff --git a/interface/collpane.h b/interface/collpane.h
index b8044004c80e041c9f26fcef9dbc7b57d3905189..c60fdc0273ec2b0c57bbf111a78be4c0e03a29cc 100644 (file)
--- a/interface/collpane.h
+++ b/interface/collpane.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        collpane.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        collpane.h

-// Purpose:     interface of wxCollapsiblePaneEvent
+// Purpose:     interface of wxCollapsiblePane

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,11 +10,15 @@
     @class wxCollapsiblePaneEvent
     @wxheader{collpane.h}
 
     @class wxCollapsiblePaneEvent
     @wxheader{collpane.h}
 

-    This event class is used for the events generated by
-    wxCollapsiblePane.
+    This event class is used for the events generated by wxCollapsiblePane.
+
+    @beginEventTable{wxCollapsiblePaneEvent}
+    @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
+           The user expanded or collapsed the collapsible pane.
+    @endEventTable

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{events}

 
     @see wxCollapsiblePane
 */
 
     @see wxCollapsiblePane
 */


@@ -24,8 +28,7 @@ public:
     /**
         The constructor is not normally used by the user code.
     */
     /**
         The constructor is not normally used by the user code.
     */

-    wxCollapsiblePaneEvent(wxObject* generator, int id,
-                           bool collapsed);
+    wxCollapsiblePaneEvent(wxObject* generator, int id, bool collapsed);

 
     /**
         Returns @true if the pane has been collapsed.
 
     /**
         Returns @true if the pane has been collapsed.


@@ -34,8 +37,7 @@ public:
 
     /**
         Sets this as a collapsed pane event (if @a collapsed is @true) or as an
 
     /**
         Sets this as a collapsed pane event (if @a collapsed is @true) or as an

-        expanded
-        pane event (if @a collapsed is @false).
+        expanded pane event (if @a collapsed is @false).

     */
     void SetCollapsed(bool collapsed);
 };
     */
     void SetCollapsed(bool collapsed);
 };


@@ -46,43 +48,36 @@ public:
     @class wxCollapsiblePane
     @wxheader{collpane.h}
 
     @class wxCollapsiblePane
     @wxheader{collpane.h}
 

-    A collapsible pane is a container with an embedded button-like control which
-    can be
-    used by the user to collapse or expand the pane's contents.
+    A collapsible pane is a container with an embedded button-like control
+    which can be used by the user to collapse or expand the pane's contents.

 
 

-    Once constructed you should use the wxCollapsiblePane::GetPane
-    function to access the pane and add your controls inside it (i.e. use the
-    wxCollapsiblePane::GetPane's returned pointer as parent for the
-    controls which must go in the pane, NOT the wxCollapsiblePane itself!).
+    Once constructed you should use the GetPane() function to access the pane
+    and add your controls inside it (i.e. use the returned pointer from
+    GetPane() as parent for the controls which must go in the pane, @b not the
+    wxCollapsiblePane itself!).

 
     Note that because of its nature of control which can dynamically (and
 
     Note that because of its nature of control which can dynamically (and

-    drastically)
-    change its size at run-time under user-input, when putting wxCollapsiblePane
-    inside
-    a wxSizer you should be careful to add it with a proportion value
-    of zero; this is because otherwise all other windows with non-null proportion
-    values
-    would automatically get resized each time the user expands or collapse the pane
-    window
-    resulting usually in a weird, flickering effect.
+    drastically) change its size at run-time under user-input, when putting
+    wxCollapsiblePane inside a wxSizer you should be careful to add it with a
+    proportion value of zero; this is because otherwise all other windows with
+    non-null proportion values will automatically resize each time the user
+    expands or collapse the pane window usually resulting in a weird,
+    flickering effect.

 
     Usage sample:
 
     @code
 
     Usage sample:
 
     @code

-    wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY,
-    wxT("Details:"));
-
-        // add the pane with a zero proportion value to the 'sz' sizer which
-    contains it
-        sz-Add(collpane, 0, wxGROW|wxALL, 5);
-
-        // now add a test label in the collapsible pane using a sizer to layout it:
-        wxWindow *win = collpane-GetPane();
-        wxSizer *paneSz = new wxBoxSizer(wxVERTICAL);
-        paneSz-Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL,
-    2);
-        win-SetSizer(paneSz);
-        paneSz-SetSizeHints(win);
+    wxCollapsiblePane *collpane = new wxCollapsiblePane(this, wxID_ANY, wxT("Details:"));
+
+    // add the pane with a zero proportion value to the 'sz' sizer which contains it
+    sz->Add(collpane, 0, wxGROW|wxALL, 5);
+
+    // now add a test label in the collapsible pane using a sizer to layout it:
+    wxWindow *win = collpane->GetPane();
+    wxSizer *paneSz = new wxBoxSizer(wxVERTICAL);
+    paneSz->Add(new wxStaticText(win, wxID_ANY, wxT("test!")), 1, wxGROW|wxALL, 2);
+    win->SetSizer(paneSz);
+    paneSz->SetSizeHints(win);

     @endcode
 
     It is only available if @c wxUSE_COLLPANE is set to 1 (the default).
     @endcode
 
     It is only available if @c wxUSE_COLLPANE is set to 1 (the default).


@@ -92,9 +87,14 @@ public:
            The default style: 0.
     @endStyleTable
 
            The default style: 0.
     @endStyleTable
 

+    @beginEventTable{wxCollapsiblePaneEvent}
+    @event{EVT_COLLAPSIBLEPANE_CHANGED(id, func)}
+           The user expanded or collapsed the collapsible pane.
+    @endEventTable
+

     @library{wxcore}
     @category{ctrl}
     @library{wxcore}
     @category{ctrl}

-    @appearance{collapsiblepane.png}
+    <!-- @appearance{collapsiblepane.png} -->

 
     @see wxPanel, wxCollapsiblePaneEvent
 */
 
     @see wxPanel, wxCollapsiblePaneEvent
 */


@@ -102,8 +102,7 @@ class wxCollapsiblePane : public wxControl
 {
 public:
     /**
 {
 public:
     /**

-        Initializes the object and calls Create() with
-        all the parameters.
+        Initializes the object and calls Create() with all the parameters.

     */
     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
                       const wxString& label,
     */
     wxCollapsiblePane(wxWindow* parent, wxWindowID id,
                       const wxString& label,


@@ -113,19 +112,14 @@ public:
                       const wxValidator& validator = wxDefaultValidator,
                       const wxString& name = "collapsiblePane");
 
                       const wxValidator& validator = wxDefaultValidator,
                       const wxString& name = "collapsiblePane");
 

-    /**
-        Collapses or expands the pane window.
-    */
-    void Collapse(bool collapse = true);
-

     /**
         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param label
     /**
         @param parent
             Parent window, must not be non-@NULL.
         @param id
             The identifier for the control.
         @param label

-            The initial label shown in the button which allows the user to expand or
-        collapse the pane window.
+            The initial label shown in the button which allows the user to
+            expand or collapse the pane window.

         @param pos
             Initial position.
         @param size
         @param pos
             Initial position.
         @param size


@@ -149,13 +143,18 @@ public:
                 const wxString& name = "collapsiblePane");
 
     /**
                 const wxString& name = "collapsiblePane");
 
     /**

-        Same as @c wxCollapsiblePane::Collapse(@false).
+        Collapses or expands the pane window.
+    */
+    void Collapse(bool collapse = true);
+
+    /**
+        Same as calling Collapse(@false).

     */
     void Expand();
 
     /**
     */
     void Expand();
 
     /**

-        Returns a pointer to the pane window. Add controls to the returned wxWindow
-        to make them collapsible.
+        Returns a pointer to the pane window. Add controls to the returned
+        wxWindow to make them collapsible.

     */
     wxWindow* GetPane() const;
 
     */
     wxWindow* GetPane() const;
 

diff --git a/interface/colordlg.h b/interface/colordlg.h
index 41233fb1bcdfd3c02ae9f2db87473d4659a4ac16..1ed5b25cb893119d7c46c84da6d3e3d2ae0e5133 100644 (file)
--- a/interface/colordlg.h
+++ b/interface/colordlg.h
@@ -15,19 +15,21 @@
     @library{wxcore}
     @category{cmndlg}
 
     @library{wxcore}
     @category{cmndlg}
 

-    @see @ref overview_wxcolourdialogoverview "wxColourDialog Overview", wxColour,
-    wxColourData, wxGetColourFromUser()
+    @see @ref overview_cmndlg_colour, wxColour, wxColourData,
+         wxGetColourFromUser()

 */
 class wxColourDialog : public wxDialog
 {
 public:
     /**
 */
 class wxColourDialog : public wxDialog
 {
 public:
     /**

-        Constructor. Pass a parent window, and optionally a pointer to a block of colour
-        data, which will be copied to the colour dialog's colour data. Custom
-        colours from colour data object will be be used in dialog's colour palette.
-        Invalid entries in custom colours list will be ignored on some platforms (GTK)
-        or replaced with white colour on platforms where custom colours palette has
-        fixed size (MSW).
+        Constructor. Pass a parent window, and optionally a pointer to a block
+        of colour data, which will be copied to the colour dialog's colour
+        data.
+
+        Custom colours from colour data object will be be used in the dialog's
+        colour palette. Invalid entries in custom colours list will be ignored
+        on some platforms(GTK) or replaced with white colour on platforms where
+        custom colours palette has fixed size (MSW).

 
         @see wxColourData
     */
 
         @see wxColourData
     */


@@ -39,19 +41,18 @@ public:
     ~wxColourDialog();
 
     /**
     ~wxColourDialog();
 
     /**

-        Same as @ref ctor() constructor.
+        Same as wxColourDialog().

     */
     bool Create(wxWindow* parent, wxColourData* data = NULL);
 
     /**
     */
     bool Create(wxWindow* parent, wxColourData* data = NULL);
 
     /**

-        Returns the @ref overview_wxcolourdata "colour data" associated with the colour
-        dialog.
+        Returns the colour data associated with the colour dialog.

     */
     wxColourData GetColourData();
 
     /**
     */
     wxColourData GetColourData();
 
     /**

-        Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
-        otherwise.
+        Shows the dialog, returning wxID_OK if the user pressed OK, and
+        wxID_CANCEL otherwise.

     */
     int ShowModal();
 };
     */
     int ShowModal();
 };

diff --git a/interface/colour.h b/interface/colour.h
index 86b430e66fc705e5c0884f75875e45ac97dc45cc..d89e78fd1f6d3a37abe4bc98159b912d71239999 100644 (file)
--- a/interface/colour.h
+++ b/interface/colour.h
@@ -23,8 +23,14 @@
     @category{gdi}
 
     @stdobjects
     @category{gdi}
 
     @stdobjects

-    ::wxNullColour, ::wxBLACK, ::wxWHITE, ::wxRED, ::wxBLUE, ::wxGREEN,
-    ::wxCYAN, ::wxLIGHT_GREY
+    - ::wxNullColour - An empty, invalid colour.
+    - ::wxBLACK
+    - ::wxBLUE
+    - ::wxCYAN
+    - ::wxGREEN
+    - ::wxLIGHT_GREY
+    - ::wxRED
+    - ::wxWHITE

 
     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
 */
 
     @see wxColourDatabase, wxPen, wxBrush, wxColourDialog, wxSystemSettings
 */


@@ -163,45 +169,17 @@ public:
 };
 
 
 };
 
 

-/**
-    An empty colour.
-*/
+/** @name Predefined colors. */
+//@{

 wxColour wxNullColour;
 wxColour wxNullColour;

-
-/**
-    FIXME
-*/
-wxColour wxBLACK;
-
-/**
-    FIXME
-*/
-wxColour wxWHITE;
-
-/**
-    FIXME
-*/
-wxColour wxRED;
-
-/**
-    FIXME
-*/
-wxColour wxBLUE;
-
-/**
-    FIXME
-*/
-wxColour wxGREEN;
-
-/**
-    FIXME
-*/
-wxColour wxCYAN;
-
-/**
-    FIXME
-*/
-wxColour wxLIGHT_GREY;
+wxColour* wxBLACK;
+wxColour* wxBLUE;
+wxColour* wxCYAN;
+wxColour* wxGREEN;
+wxColour* wxLIGHT_GREY;
+wxColour* wxRED;
+wxColour* wxWHITE;
+//@}

 
 
 
 
 
 

diff --git a/interface/combo.h b/interface/combo.h
index 7147eb84be758d90df1c0639c7bd7818e29f4c99..95259d4237affedf83ea96bcd96346aa25124063 100644 (file)
--- a/interface/combo.h
+++ b/interface/combo.h
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        combo.h
 /////////////////////////////////////////////////////////////////////////////
 // Name:        combo.h

-// Purpose:     interface of wxComboPopup
+// Purpose:     interface of wxComboCtrl and wxComboPopup

 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license


@@ -10,14 +10,13 @@
     @class wxComboPopup
     @wxheader{combo.h}
 
     @class wxComboPopup
     @wxheader{combo.h}
 

-    In order to use a custom popup with wxComboCtrl, an interface class must
-    be derived from wxComboPopup.
+    In order to use a custom popup with wxComboCtrl, an interface class must be
+    derived from wxComboPopup.

 
 

-    For more information on how to use it, see @ref overview_wxcomboctrl "Setting Custom Popup for
-    wxComboCtrl".
+    For more information on how to use it, see @ref comboctrl_custompopup.

 
     @library{wxcore}
 
     @library{wxcore}

-    @category{FIXME}
+    @category{ctrl}

 
     @see wxComboCtrl
 */
 
     @see wxComboCtrl
 */


@@ -25,9 +24,9 @@ class wxComboPopup
 {
 public:
     /**
 {
 public:
     /**

-        Default constructor. It is recommended that internal variables
-        are prepared in Init() instead
-        (because @ref mcombo() m_combo is not valid in constructor).
+        Default constructor. It is recommended that internal variables are
+        prepared in Init() instead (because m_combo is not valid in
+        constructor).

     */
     wxComboPopup();
 
     */
     wxComboPopup();
 


@@ -36,7 +35,7 @@ public:
 
         @returns @true if the call succeeded, @false otherwise.
     */
 
         @returns @true if the call succeeded, @false otherwise.
     */

-    bool Create(wxWindow* parent);
+    virtual bool Create(wxWindow* parent);

 
     /**
         Utility function that hides the popup.
 
     /**
         Utility function that hides the popup.


@@ -44,123 +43,147 @@ public:
     void Dismiss();
 
     /**
     void Dismiss();
 
     /**

-        The derived class may implement this to return adjusted size
-        for the popup control, according to the variables given.
+        The derived class may implement this to return adjusted size for the
+        popup control, according to the variables given.

 
         @param minWidth
             Preferred minimum width.
         @param prefHeight
 
         @param minWidth
             Preferred minimum width.
         @param prefHeight

-            Preferred height. May be -1 to indicate
-            no preference.
+            Preferred height. May be -1 to indicate no preference.

         @param maxWidth
         @param maxWidth

-            Max height for window, as limited by
-            screen size.
+            Max height for window, as limited by screen size.

 
 

-        @remarks Called each time popup is about to be shown.
+        @remarks This function is called each time popup is about to be shown.

     */
     */

-    wxSize GetAdjustedSize(int minWidth, int prefHeight,
-                           int maxHeight);
+    virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight);

 
     /**
 
     /**

-        The derived class must implement this to return pointer
-        to the associated control created in Create().
+        The derived class must implement this to return pointer to the
+        associated control created in Create().

     */
     */

-    wxWindow* GetControl();
+    virtual wxWindow* GetControl();

 
     /**
 
     /**

-        The derived class must implement this to return
-        string representation of the value.
+        The derived class must implement this to return string representation
+        of the value.

     */
     */

-    wxString GetStringValue() const;
+    virtual wxString GetStringValue() const;

 
     /**
 
     /**

-        The derived class must implement this to initialize
-        its internal variables. This method is called immediately
-        after construction finishes. @ref mcombo() m_combo
-        member variable has been initialized before the call.
+        The derived class must implement this to initialize its internal
+        variables. This method is called immediately after construction
+        finishes. m_combo member variable has been initialized before the call.

     */
     */

-    void Init();
+    virtual void Init();

 
     /**
         Utility method that returns @true if Create has been called.
 
     /**
         Utility method that returns @true if Create has been called.

+

         Useful in conjunction with LazyCreate().
     */
     bool IsCreated() const;
 
     /**
         Useful in conjunction with LazyCreate().
     */
     bool IsCreated() const;
 
     /**

-        The derived class may implement this to return
-        @true if it wants to delay call to Create()
-        until the popup is shown for the first time. It is more
-        efficient, but on the other hand it is often more convenient
-        to have the control created immediately.
+        The derived class may implement this to return @true if it wants to
+        delay call to Create() until the popup is shown for the first time. It
+        is more efficient, but on the other hand it is often more convenient to
+        have the control created immediately.

 
         @remarks Base implementation returns @false.
     */
 
         @remarks Base implementation returns @false.
     */

-    bool LazyCreate();
+    virtual bool LazyCreate();

 
     /**
 
     /**

-        The derived class may implement this to do something
-        when the parent wxComboCtrl gets double-clicked.
+        The derived class may implement this to do something when the parent
+        wxComboCtrl gets double-clicked.

     */
     */

-    void OnComboDoubleClick();
+    virtual void OnComboDoubleClick();

 
     /**
 
     /**

-        The derived class may implement this to receive
-        key events from the parent wxComboCtrl.
+        The derived class may implement this to receive key events from the
+        parent wxComboCtrl.
+

         Events not handled should be skipped, as usual.
     */
         Events not handled should be skipped, as usual.
     */

-    void OnComboKeyEvent(wxKeyEvent& event);
+    virtual void OnComboKeyEvent(wxKeyEvent& event);

 
     /**
 
     /**

-        The derived class may implement this to do
-        special processing when popup is hidden.
+        The derived class may implement this to do special processing when
+        popup is hidden.

     */
     */

-    void OnDismiss();
+    virtual void OnDismiss();

 
     /**
 
     /**

-        The derived class may implement this to do
-        special processing when popup is shown.
+        The derived class may implement this to do special processing when
+        popup is shown.

     */
     */

-    void OnPopup();
+    virtual void OnPopup();

 
     /**
 
     /**

-        The derived class may implement this to paint
-        the parent wxComboCtrl.
+        The derived class may implement this to paint the parent wxComboCtrl.
+

         Default implementation draws value as string.
     */
         Default implementation draws value as string.
     */

-    void PaintComboControl(wxDC& dc, const wxRect& rect);
+    virtual void PaintComboControl(wxDC& dc, const wxRect& rect);

 
     /**
 
     /**

-        The derived class must implement this to receive
-        string value changes from wxComboCtrl.
+        The derived class must implement this to receive string value changes
+        from wxComboCtrl.

     */
     */

-    void SetStringValue(const wxString& value);
+    virtual void SetStringValue(const wxString& value);

 
     /**
 
     /**

-        wxComboCtrl m_combo
-        Parent wxComboCtrl. This is parameter has
-        been prepared before Init() is called.
+        Parent wxComboCtrl. This is parameter has been prepared before Init()
+        is called.

     */
     */

+    wxComboCtrl m_combo;

 };
 
 
 
 };
 
 
 

+/**
+    Features enabled for wxComboCtrl.
+
+    @see wxComboCtrl::GetFeatures()
+*/
+struct wxComboCtrlFeatures
+{
+    enum
+    {
+        MovableButton   = 0x0001, ///< Button can be on either side of control.
+        BitmapButton    = 0x0002, ///< Button may be replaced with bitmap.
+        ButtonSpacing   = 0x0004, ///< Button can have spacing from the edge
+                                  ///< of the control.
+        TextIndent      = 0x0008, ///< wxComboCtrl::SetTextIndent() can be used.
+        PaintControl    = 0x0010, ///< Combo control itself can be custom painted.
+        PaintWritable   = 0x0020, ///< A variable-width area in front of writable
+                                  ///< combo control's textctrl can be custom
+                                  ///< painted.
+        Borderless      = 0x0040, ///< wxNO_BORDER window style works.
+
+        All             = MovableButton | BitmapButton | ButtonSpacing |
+                          TextIndent | PaintControl | PaintWritable |
+                          Borderless ///< All features.
+    };
+};
+
+

 /**
     @class wxComboCtrl
     @wxheader{combo.h}
 
 /**
     @class wxComboCtrl
     @wxheader{combo.h}
 

-    A combo control is a generic combobox that allows totally custom popup.
-    In addition it has other customization features.
-    For instance, position and size of the dropdown button can be changed.
+    A combo control is a generic combobox that allows totally custom popup. In
+    addition it has other customization features. For instance, position and
+    size of the dropdown button can be changed.

 
 

-    @section wxcomboctrl_custompopup Setting Custom Popup for wxComboCtrl
+    @section comboctrl_custompopup Setting Custom Popup for wxComboCtrl

 
     wxComboCtrl needs to be told somehow which control to use and this is done
 
     wxComboCtrl needs to be told somehow which control to use and this is done

-    by SetPopupControl().
-    However, we need something more than just a wxControl in this method as,
-    for example, we need to call SetStringValue("initial text value") and
-    wxControl doesn't have such method. So we also need a wxComboPopup which
-    is an interface which must be implemented by a control to be usable as a popup.
+    by SetPopupControl(). However, we need something more than just a wxControl
+    in this method as, for example, we need to call
+    SetStringValue("initial text value") and wxControl doesn't have such
+    method. So we also need a wxComboPopup which is an interface which must be
+    implemented by a control to be usable as a popup.

 
     We couldn't derive wxComboPopup from wxControl as this would make it
     impossible to have a class deriving from a wxWidgets control and from it,
 
     We couldn't derive wxComboPopup from wxControl as this would make it
     impossible to have a class deriving from a wxWidgets control and from it,


@@ -172,11 +195,9 @@ public:
     #include <wx/combo.h>
     #include <wx/listctrl.h>
 
     #include <wx/combo.h>
     #include <wx/listctrl.h>
 

-    class wxListViewComboPopup : public wxListView,
-                                public wxComboPopup
+    class wxListViewComboPopup : public wxListView, public wxComboPopup

     {
     public:
     {
     public:

-

         // Initialize member variables
         virtual void Init()
         {
         // Initialize member variables
         virtual void Init()
         {


@@ -204,7 +225,7 @@ public:
         virtual wxString GetStringValue() const
         {
             if ( m_value >= 0 )
         virtual wxString GetStringValue() const
         {
             if ( m_value >= 0 )

-                return wxListView::GetItemText(m_value);
+            return wxListView::GetItemText(m_value);

             return wxEmptyString;
         }
 
             return wxEmptyString;
         }
 


@@ -225,7 +246,8 @@ public:
         }
 
     protected:
         }
 
     protected:

-        int             m_value; // current item index
+
+        int m_value; // current item index

 
     private:
         DECLARE_EVENT_TABLE()
 
     private:
         DECLARE_EVENT_TABLE()


@@ -240,16 +262,16 @@ public:
     Here's how you would create and populate it in a dialog constructor:
 
     @code
     Here's how you would create and populate it in a dialog constructor:
 
     @code

-    wxComboCtrl* comboCtrl = new wxComboCtrl(this,wxID_ANY,wxEmptyString);
+    wxComboCtrl* comboCtrl = new wxComboCtrl(this, wxID_ANY, wxEmptyString);

 
     wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
 
     comboCtrl->SetPopupControl(popupCtrl);
 
     // Populate using wxListView methods
 
     wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
 
     comboCtrl->SetPopupControl(popupCtrl);
 
     // Populate using wxListView methods

-    popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("First Item"));
-    popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Second Item"));
-    popupCtrl->InsertItem(popupCtrl->GetItemCount(),wxT("Third Item"));
+    popupCtrl->InsertItem(popupCtrl->GetItemCount(), "First Item");
+    popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Second Item");
+    popupCtrl->InsertItem(popupCtrl->GetItemCount(), "Third Item");

     @endcode
 
     @beginStyleTable
     @endcode
 
     @beginStyleTable


@@ -281,14 +303,19 @@ public:
 
     @library{wxbase}
     @category{ctrl}
 
     @library{wxbase}
     @category{ctrl}

-    @appearance{comboctrl.png}
+    <!-- @appearance{comboctrl.png} -->

 
 

-    @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent
+    @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup,
+         wxCommandEvent

 */
 class wxComboCtrl : public wxControl
 {
 public:
 */
 class wxComboCtrl : public wxControl
 {
 public:

-    //@{
+    /**
+        Default constructor.
+    */
+    wxComboCtrl();
+

     /**
         Constructor, creating and showing a combo control.
 
     /**
         Constructor, creating and showing a combo control.
 


@@ -301,8 +328,7 @@ public:
         @param pos
             Window position.
         @param size
         @param pos
             Window position.
         @param size

-            Window size. If wxDefaultSize is specified then the window is
-        sized
+            Window size. If wxDefaultSize is specified then the window is sized

             appropriately.
         @param style
             Window style. See wxComboCtrl.
             appropriately.
         @param style
             Window style. See wxComboCtrl.


@@ -313,7 +339,6 @@ public:
 
         @see Create(), wxValidator
     */
 
         @see Create(), wxValidator
     */

-    wxComboCtrl();

     wxComboCtrl(wxWindow* parent, wxWindowID id,
                 const wxString& value = "",
                 const wxPoint& pos = wxDefaultPosition,
     wxComboCtrl(wxWindow* parent, wxWindowID id,
                 const wxString& value = "",
                 const wxPoint& pos = wxDefaultPosition,


@@ -321,33 +346,34 @@ public:
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxString& name = "comboCtrl");
                 long style = 0,
                 const wxValidator& validator = wxDefaultValidator,
                 const wxString& name = "comboCtrl");

-    //@}

 
     /**
         Destructor, destroying the combo control.
     */
 
     /**
         Destructor, destroying the combo control.
     */

-    ~wxComboCtrl();
+    virtual ~wxComboCtrl();

 
     /**
         This member function is not normally called in application code.
 
     /**
         This member function is not normally called in application code.

-        Instead, it can be implemented in a derived class to create a
-        custom popup animation.
+        Instead, it can be implemented in a derived class to create a custom
+        popup animation.

 
 

-        @returns @true if animation finishes before the function returns. @false
-                 otherwise. In the latter case you need to manually call
-                 DoShowPopup after the animation ends.
+        The parameters are the same as those for DoShowPopup().
+
+        @returns @true if animation finishes before the function returns,
+                 @false otherwise. In the latter case you need to manually call
+                 DoShowPopup() after the animation ends.

     */
     virtual bool AnimateShow(const wxRect& rect, int flags);
 
     /**
         Copies the selected text to the clipboard.
     */
     */
     virtual bool AnimateShow(const wxRect& rect, int flags);
 
     /**
         Copies the selected text to the clipboard.
     */

-    void Copy();
+    virtual void Copy();

 
     /**
         Creates the combo control for two-step construction. Derived classes
 
     /**
         Creates the combo control for two-step construction. Derived classes

-        should call or replace this function. See wxComboCtrl()
-        for further details.
+        should call or replace this function. See wxComboCtrl() for further
+        details.

     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& value = "",
     */
     bool Create(wxWindow* parent, wxWindowID id,
                 const wxString& value = "",


@@ -360,29 +386,37 @@ public:
     /**
         Copies the selected text to the clipboard and removes the selection.
     */
     /**
         Copies the selected text to the clipboard and removes the selection.
     */

-    void Cut();
+    virtual void Cut();

 
     /**
         This member function is not normally called in application code.
 
     /**
         This member function is not normally called in application code.

-        Instead, it can be implemented in a derived class to return
-        default wxComboPopup, incase @c popup is @NULL.
-        @note If you have implemented OnButtonClick to do
-        something else than show the popup, then DoSetPopupControl
-        must always return @NULL.
+        Instead, it can be implemented in a derived class to return default
+        wxComboPopup, incase @a popup is @NULL.
+
+        @note If you have implemented OnButtonClick() to do something else than
+              show the popup, then DoSetPopupControl() must always set @a popup
+              to @NULL.

     */
     void DoSetPopupControl(wxComboPopup* popup);
 
     /**
         This member function is not normally called in application code.
     */
     void DoSetPopupControl(wxComboPopup* popup);
 
     /**
         This member function is not normally called in application code.

-        Instead, it must be called in a derived class to make sure popup
-        is properly shown after a popup animation has finished (but only
-        if AnimateShow() did not finish
-        the animation within it's function scope).
+        Instead, it must be called in a derived class to make sure popup is
+        properly shown after a popup animation has finished (but only if
+        AnimateShow() did not finish the animation within its function scope).

 
         @param rect
             Position to show the popup window at, in screen coordinates.
         @param flags
             Combination of any of the following:
 
         @param rect
             Position to show the popup window at, in screen coordinates.
         @param flags
             Combination of any of the following:

+            @beginTable
+            @row2col{wxComboCtrl::ShowAbove,
+                     Popup is shown above the control instead of below.}
+            @row2col{wxComboCtrl::CanDeferShow,
+                     Showing the popup can be deferred to happen sometime after
+                     ShowPopup() has finished. In this case, AnimateShow() must
+                     return false.}
+            @endTable

     */
     virtual void DoShowPopup(const wxRect& rect, int flags);
 
     */
     virtual void DoShowPopup(const wxRect& rect, int flags);
 


@@ -437,28 +471,31 @@ public:
     int GetCustomPaintWidth() const;
 
     /**
     int GetCustomPaintWidth() const;
 
     /**

-        Returns features supported by wxComboCtrl. If needed feature is missing,
-        you need to instead use wxGenericComboCtrl, which however may lack
-        native look and feel (but otherwise sports identical API).
+        Returns features supported by wxComboCtrl. If needed feature is
+        missing, you need to instead use wxGenericComboCtrl, which however may
+        lack a native look and feel (but otherwise sports identical API).

 
 

-        @returns Value returned is a combination of following flags:
+        @returns Value returned is a combination of the flags defined in
+                 wxComboCtrlFeatures.

     */
     static int GetFeatures();
 
     /**
         Returns the insertion point for the combo control's text field.
     */
     static int GetFeatures();
 
     /**
         Returns the insertion point for the combo control's text field.

-        @note Under wxMSW, this function always returns 0 if the combo control
-        doesn't have the focus.
+
+        @note Under Windows, this function always returns 0 if the combo
+              control doesn't have the focus.

     */
     */

-    long GetInsertionPoint() const;
+    virtual long GetInsertionPoint() const;

 
     /**
         Returns the last position in the combo control text field.
     */
 
     /**
         Returns the last position in the combo control text field.
     */

-    long GetLastPosition() const;
+    virtual long GetLastPosition() const;

 
     /**
 
     /**

-        Returns current popup interface that has been set with SetPopupControl.
+        Returns current popup interface that has been set with
+        SetPopupControl().

     */
     wxComboPopup* GetPopupControl();
 
     */
     wxComboPopup* GetPopupControl();
 


@@ -484,15 +521,15 @@ public:
     const wxRect GetTextRect() const;
 
     /**
     const wxRect GetTextRect() const;
 
     /**

-        Returns text representation of the current value. For writable
-        combo control it always returns the value in the text field.
+        Returns text representation of the current value. For writable combo
+        control it always returns the value in the text field.

     */
     */

-    wxString GetValue() const;
+    virtual wxString GetValue() const;

 
     /**
         Dismisses the popup window.
     */
 
     /**
         Dismisses the popup window.
     */

-    void HidePopup();
+    virtual void HidePopup();

 
     /**
         Returns @true if the popup is currently shown
 
     /**
         Returns @true if the popup is currently shown


@@ -500,53 +537,47 @@ public:
     bool IsPopupShown() const;
 
     /**
     bool IsPopupShown() const;
 
     /**

-        Returns @true if the popup window is in the given state.
-        Possible values are:
-
-        @c Hidden()
+        Returns @true if the popup window is in the given state. Possible
+        values are:

 
 

-        Popup window is hidden.
-
-        @c Animating()
-
-        Popup window is being shown, but the
-        popup animation has not yet finished.
-
-        @c Visible()
-
-        Popup window is fully visible.
+        @beginTable
+        @row2col{wxComboCtrl::Hidden,    Popup window is hidden.}
+        @row2col{wxComboCtrl::Animating, Popup window is being shown, but the
+                                         popup animation has not yet finished.}
+        @row2col{wxComboCtrl::Visible,   Popup window is fully visible.}
+        @endTable

     */
     bool IsPopupWindowState(int state) const;
 
     /**
     */
     bool IsPopupWindowState(int state) const;
 
     /**

-        Implement in a derived class to define what happens on
-        dropdown button click.
-        Default action is to show the popup.
-        @note If you implement this to do something else than
-        show the popup, you must then also implement
-        DoSetPopupControl() to always
-        return @NULL.
+        Implement in a derived class to define what happens on dropdown button
+        click. Default action is to show the popup.
+
+        @note If you implement this to do something else than show the popup,
+              you must then also implement DoSetPopupControl() to always return
+              @NULL.

     */
     */

-    void OnButtonClick();
+    virtual void OnButtonClick();

 
     /**
         Pastes text from the clipboard to the text field.
     */
 
     /**
         Pastes text from the clipboard to the text field.
     */

-    void Paste();
+    virtual void Paste();

 
     /**
 
     /**

-        Removes the text between the two positions in the combo control text field.
+        Removes the text between the two positions in the combo control text
+        field.

 
         @param from
             The first position.
         @param to
             The last position.
     */
 
         @param from
             The first position.
         @param to
             The last position.
     */

-    void Remove(long from, long to);
+    virtual void Remove(long from, long to);

 
     /**
 
     /**

-        Replaces the text between two positions with the given text, in the combo
-        control text field.
+        Replaces the text between two positions with the given text, in the
+        combo control text field.

 
         @param from
             The first position.
 
         @param from
             The first position.


@@ -555,7 +586,7 @@ public:
         @param text
             The text to insert.
     */
         @param text
             The text to insert.
     */

-    void Replace(long from, long to, const wxString& value);
+    virtual void Replace(long from, long to, const wxString& value);

 
     /**
         Sets custom dropdown button graphics.
 
     /**
         Sets custom dropdown button graphics.


@@ -563,14 +594,13 @@ public:
         @param bmpNormal
             Default button image.
         @param pushButtonBg
         @param bmpNormal
             Default button image.
         @param pushButtonBg

-            If @true, blank push button background is painted
-            below the image.
+            If @true, blank push button background is painted below the image.

         @param bmpPressed
             Depressed button image.
         @param bmpHover
         @param bmpPressed
             Depressed button image.
         @param bmpHover

-            Button image when mouse hovers above it. This
-            should be ignored on platforms and themes that do not generally draw
-            different kind of button on mouse hover.
+            Button image when mouse hovers above it. This should be ignored on
+            platforms and themes that do not generally draw different kind of
+            button on mouse hover.

         @param bmpDisabled
             Disabled button image.
     */
         @param bmpDisabled
             Disabled button image.
     */


@@ -588,18 +618,17 @@ public:
         @param height
             Button height. Value = 0 specifies default.
         @param side
         @param height
             Button height. Value = 0 specifies default.
         @param side

-            Indicates which side the button will be placed.
-            Value can be wxLEFT or wxRIGHT.
+            Indicates which side the button will be placed. Value can be wxLEFT
+            or wxRIGHT.

         @param spacingX
             Horizontal spacing around the button. Default is 0.
     */
     void SetButtonPosition(int width = -1, int height = -1,
         @param spacingX
             Horizontal spacing around the button. Default is 0.
     */
     void SetButtonPosition(int width = -1, int height = -1,

-                           int side = wxRIGHT,
-                           int spacingX = 0);
+                           int side = wxRIGHT, int spacingX = 0);

 
     /**
 
     /**

-        Set width, in pixels, of custom painted area in control without @c wxCB_READONLY
-        style. In read-only wxOwnerDrawnComboBox, this is used
+        Set width, in pixels, of custom painted area in control without
+        @c wxCB_READONLY style. In read-only wxOwnerDrawnComboBox, this is used

         to indicate area that is not covered by the focus rectangle.
     */
     void SetCustomPaintWidth(int width);
         to indicate area that is not covered by the focus rectangle.
     */
     void SetCustomPaintWidth(int width);


@@ -610,39 +639,41 @@ public:
         @param pos
             The new insertion point.
     */
         @param pos
             The new insertion point.
     */

-    void SetInsertionPoint(long pos);
+    virtual void SetInsertionPoint(long pos);

 
     /**
         Sets the insertion point at the end of the combo control text field.
     */
 
     /**
         Sets the insertion point at the end of the combo control text field.
     */

-    void SetInsertionPointEnd();
+    virtual void SetInsertionPointEnd();

 
     /**
 
     /**

-        Set side of the control to which the popup will align itself. Valid values are
-        @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that the most appropriate
-        side is used (which, currently, is always @c wxLEFT).
+        Set side of the control to which the popup will align itself. Valid
+        values are @c wxLEFT, @c wxRIGHT and 0. The default value 0 means that
+        the most appropriate side is used (which, currently, is always
+        @c wxLEFT).

     */
     void SetPopupAnchor(int anchorSide);
 
     /**
     */
     void SetPopupAnchor(int anchorSide);
 
     /**

-        Set popup interface class derived from wxComboPopup.
-        This method should be called as soon as possible after the control
-        has been created, unless OnButtonClick()
-        has been overridden.
+        Set popup interface class derived from wxComboPopup. This method should
+        be called as soon as possible after the control has been created,
+        unless OnButtonClick() has been overridden.

     */
     void SetPopupControl(wxComboPopup* popup);
 
     /**
     */
     void SetPopupControl(wxComboPopup* popup);
 
     /**

-        Extends popup size horizontally, relative to the edges of the combo control.
+        Extends popup size horizontally, relative to the edges of the combo
+        control.

 
         @param extLeft
 
         @param extLeft

-            How many pixel to extend beyond the left edge of the
-            control. Default is 0.
+            How many pixel to extend beyond the left edge of the control.
+            Default is 0.

         @param extRight
         @param extRight

-            How many pixel to extend beyond the right edge of the
-            control. Default is 0.
+            How many pixel to extend beyond the right edge of the control.
+            Default is 0.

 
 

-        @remarks Popup minimum width may override arguments.
+        @remarks Popup minimum width may override arguments. It is up to the
+                 popup to fully take this into account.

     */
     void SetPopupExtents(int extLeft, int extRight);
 
     */
     void SetPopupExtents(int extLeft, int extRight);
 


@@ -654,69 +685,70 @@ public:
     void SetPopupMaxHeight(int height);
 
     /**
     void SetPopupMaxHeight(int height);
 
     /**

-        Sets minimum width of the popup. If wider than combo control, it will extend to
-        the left.
+        Sets minimum width of the popup. If wider than combo control, it will
+        extend to the left.

 
 

-        @remarks Value -1 indicates the default.
+        @remarks Value -1 indicates the default. Also, popup implementation may
+                 choose to ignore this.

     */
     void SetPopupMinWidth(int width);
 
     /**
     */
     void SetPopupMinWidth(int width);
 
     /**

-        Selects the text between the two positions, in the combo control text field.
+        Selects the text between the two positions, in the combo control text
+        field.

 
         @param from
             The first position.
         @param to
             The second position.
     */
 
         @param from
             The first position.
         @param to
             The second position.
     */

-    void SetSelection(long from, long to);
+    virtual void SetSelection(long from, long to);

 
     /**
 
     /**

-        Sets the text for the text field without affecting the
-        popup. Thus, unlike SetValue(), it works
-        equally well with combo control using @c wxCB_READONLY style.
+        Sets the text for the text field without affecting the popup. Thus,
+        unlike SetValue(), it works equally well with combo control using
+        @c wxCB_READONLY style.

     */
     void SetText(const wxString& value);
 
     /**
     */
     void SetText(const wxString& value);
 
     /**

-        This will set the space in pixels between left edge of the control and the
-        text, regardless whether control is read-only or not. Value -1 can be
-        given to indicate platform default.
+        This will set the space in pixels between left edge of the control and
+        the text, regardless whether control is read-only or not. Value -1 can
+        be given to indicate platform default.

     */
     void SetTextIndent(int indent);
 
     /**
         Sets the text for the combo control text field.
     */
     void SetTextIndent(int indent);
 
     /**
         Sets the text for the combo control text field.

-        @note For a combo control with @c wxCB_READONLY style the
-        string must be accepted by the popup (for instance, exist in the dropdown
-        list), otherwise the call to SetValue() is ignored
+
+        @note For a combo control with @c wxCB_READONLY style the string must
+              be accepted by the popup (for instance, exist in the dropdown
+              list), otherwise the call to SetValue() is ignored.

     */
     */

-    void SetValue(const wxString& value);
+    virtual void SetValue(const wxString& value);

 
     /**
 
     /**

-        Same as SetValue, but also sends wxCommandEvent of type
-        wxEVT_COMMAND_TEXT_UPDATED
-        if @c withEvent is @true.
+        Same as SetValue(), but also sends wxCommandEvent of type
+        wxEVT_COMMAND_TEXT_UPDATED if @a withEvent is @true.

     */
     */

-    void SetValueWithEvent(const wxString& value,
-                           bool withEvent = true);
+    void SetValueWithEvent(const wxString& value, bool withEvent = true);

 
     /**
         Show the popup.
     */
 
     /**
         Show the popup.
     */

-    void ShowPopup();
+    virtual void ShowPopup();

 
     /**
         Undoes the last edit in the text field. Windows only.
     */
 
     /**
         Undoes the last edit in the text field. Windows only.
     */

-    void Undo();
+    virtual void Undo();

 
     /**
 
     /**

-        Enable or disable usage of an alternative popup window, which guarantees
-        ability to focus the popup control, and allows common native controls to
-        function normally. This alternative popup window is usually a wxDialog,
-        and as such, when it is shown, its parent top-level window will appear
-        as if the focus has been lost from it.
+        Enable or disable usage of an alternative popup window, which
+        guarantees ability to focus the popup control, and allows common native
+        controls to function normally. This alternative popup window is usually
+        a wxDialog, and as such, when it is shown, its parent top-level window
+        will appear as if the focus has been lost from it.

     */
     void UseAltPopupWindow(bool enable = true);
 };
     */
     void UseAltPopupWindow(bool enable = true);
 };