X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8c6791e43ca1adb11db20674a2327dc5e354f629..3201a1046ba71ba8e5ef2ed694fde34d12f743f3:/interface/combo.h diff --git a/interface/combo.h b/interface/combo.h index 7147eb84be..353daaf8f5 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,18 +24,18 @@ 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(); /** The derived class must implement this to create the popup control. - @returns @true if the call succeeded, @false otherwise. + @return @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 <wx/combo.h> #include <wx/listctrl.h> - 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} + <!-- @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(). + + @return @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); @@ -396,7 +430,7 @@ public: Returns disabled button bitmap that has been set with SetButtonBitmaps(). - @returns A reference to the disabled state bitmap. + @return A reference to the disabled state bitmap. */ const wxBitmap GetBitmapDisabled() const; @@ -404,7 +438,7 @@ public: Returns button mouse hover bitmap that has been set with SetButtonBitmaps(). - @returns A reference to the mouse hover state bitmap. + @return A reference to the mouse hover state bitmap. */ const wxBitmap GetBitmapHover() const; @@ -412,7 +446,7 @@ public: Returns default button bitmap that has been set with SetButtonBitmaps(). - @returns A reference to the normal state bitmap. + @return A reference to the normal state bitmap. */ const wxBitmap GetBitmapNormal() const; @@ -420,7 +454,7 @@ public: Returns depressed button bitmap that has been set with SetButtonBitmaps(). - @returns A reference to the depressed state bitmap. + @return A reference to the depressed state bitmap. */ const wxBitmap GetBitmapPressed() const; @@ -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: + @return 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); };