/////////////////////////////////////////////////////////////////////////////
// Name: combo.h
-// Purpose: interface of wxComboPopup
+// Purpose: interface of wxComboCtrl and wxComboPopup
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
@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
*/
{
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.
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,
#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()
{
virtual wxString GetStringValue() const
{
if ( m_value >= 0 )
- return wxListView::GetItemText(m_value);
+ return wxListView::GetItemText(m_value);
return wxEmptyString;
}
}
protected:
- int m_value; // current item index
+
+ int m_value; // current item index
private:
DECLARE_EVENT_TABLE()
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
@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.
@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.
@see Create(), wxValidator
*/
- wxComboCtrl();
wxComboCtrl(wxWindow* parent, wxWindowID id,
const wxString& value = "",
const wxPoint& pos = wxDefaultPosition,
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 = "",
/**
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);
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;
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;
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;
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;
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();
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
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.
@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.
@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.
*/
@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);
@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);
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);
};
projects / wxWidgets.git / blobdiff