From 968f15e262d34c49757a157f8442c0b844c9e717 Mon Sep 17 00:00:00 2001 From: Bryan Petty Date: Thu, 10 Apr 2008 02:57:09 +0000 Subject: [PATCH] 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 --- interface/collpane.h | 101 +++++------ interface/colordlg.h | 27 +-- interface/colour.h | 58 ++---- interface/combo.h | 422 +++++++++++++++++++++++-------------------- 4 files changed, 309 insertions(+), 299 deletions(-) diff --git a/interface/collpane.h b/interface/collpane.h index b8044004c8..c60fdc0273 100644 --- a/interface/collpane.h +++ b/interface/collpane.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: collpane.h -// Purpose: interface of wxCollapsiblePaneEvent +// Purpose: interface of wxCollapsiblePane // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,11 +10,15 @@ @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} - @category{FIXME} + @category{events} @see wxCollapsiblePane */ @@ -24,8 +28,7 @@ public: /** 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. @@ -34,8 +37,7 @@ public: /** 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); }; @@ -46,43 +48,36 @@ public: @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 - 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 - 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). @@ -92,9 +87,14 @@ public: 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} - @appearance{collapsiblepane.png} + @see wxPanel, wxCollapsiblePaneEvent */ @@ -102,8 +102,7 @@ class wxCollapsiblePane : public wxControl { 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, @@ -113,19 +112,14 @@ public: 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 - 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 @@ -149,13 +143,18 @@ public: 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(); /** - 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; diff --git a/interface/colordlg.h b/interface/colordlg.h index 41233fb1bc..1ed5b25cb8 100644 --- a/interface/colordlg.h +++ b/interface/colordlg.h @@ -15,19 +15,21 @@ @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: /** - 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 */ @@ -39,19 +41,18 @@ public: ~wxColourDialog(); /** - Same as @ref ctor() constructor. + Same as wxColourDialog(). */ 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(); /** - 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(); }; diff --git a/interface/colour.h b/interface/colour.h index 86b430e66f..d89e78fd1f 100644 --- a/interface/colour.h +++ b/interface/colour.h @@ -23,8 +23,14 @@ @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 */ @@ -163,45 +169,17 @@ public: }; -/** - An empty colour. -*/ +/** @name Predefined colors. */ +//@{ 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 7147eb84be..95259d4237 100644 --- a/interface/combo.h +++ b/interface/combo.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: combo.h -// Purpose: interface of wxComboPopup +// Purpose: interface of wxComboCtrl and wxComboPopup // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -10,14 +10,13 @@ @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} - @category{FIXME} + @category{ctrl} @see wxComboCtrl */ @@ -25,9 +24,9 @@ class wxComboPopup { 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(); @@ -36,7 +35,7 @@ public: @returns @true if the call succeeded, @false otherwise. */ - bool Create(wxWindow* parent); + virtual bool Create(wxWindow* parent); /** Utility function that hides the popup. @@ -44,123 +43,147 @@ public: 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 - Preferred height. May be -1 to indicate - no preference. + Preferred height. May be -1 to indicate no preference. @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. + 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. */ - 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. */ - 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. */ - 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} - 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 - 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, @@ -172,11 +195,9 @@ public: #include #include - class wxListViewComboPopup : public wxListView, - public wxComboPopup + class wxListViewComboPopup : public wxListView, public wxComboPopup { public: - // Initialize member variables virtual void Init() { @@ -204,7 +225,7 @@ public: virtual wxString GetStringValue() const { if ( m_value >= 0 ) - return wxListView::GetItemText(m_value); + return wxListView::GetItemText(m_value); return wxEmptyString; } @@ -225,7 +246,8 @@ public: } protected: - int m_value; // current item index + + int m_value; // current item index private: DECLARE_EVENT_TABLE() @@ -240,16 +262,16 @@ public: 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 - 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 @@ -281,14 +303,19 @@ public: @library{wxbase} @category{ctrl} - @appearance{comboctrl.png} + - @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent + @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, + wxCommandEvent */ class wxComboCtrl : public wxControl { public: - //@{ + /** + Default constructor. + */ + wxComboCtrl(); + /** Constructor, creating and showing a combo control. @@ -301,8 +328,7 @@ public: @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. @@ -313,7 +339,6 @@ public: @see Create(), wxValidator */ - wxComboCtrl(); 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"); - //@} /** Destructor, destroying the combo control. */ - ~wxComboCtrl(); + virtual ~wxComboCtrl(); /** 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. */ - void Copy(); + virtual void Copy(); /** 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 = "", @@ -360,29 +386,37 @@ public: /** 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. - 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. - 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: + @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); @@ -437,28 +471,31 @@ public: 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. - @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. */ - 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(); @@ -484,15 +521,15 @@ public: 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. */ - void HidePopup(); + virtual void HidePopup(); /** Returns @true if the popup is currently shown @@ -500,53 +537,47 @@ public: 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; /** - 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. */ - 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. */ - 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. @@ -555,7 +586,7 @@ public: @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. @@ -563,14 +594,13 @@ public: @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 - 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. */ @@ -588,18 +618,17 @@ public: @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, - 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); @@ -610,39 +639,41 @@ public: @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. */ - 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); /** - 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); /** - 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 - 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 - 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); @@ -654,69 +685,70 @@ public: 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); /** - 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. */ - 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); /** - 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. - @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. */ - void ShowPopup(); + virtual void ShowPopup(); /** 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); }; -- 2.45.2