// Name: combo.h
// Purpose: interface of wxComboCtrl and wxComboPopup
// Author: wxWidgets team
-// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
+//
+// New window styles for wxComboCtrlBase
+//
+enum
+{
+ // Double-clicking a read-only combo triggers call to popup's OnComboPopup.
+ // In wxOwnerDrawnComboBox, for instance, it cycles item.
+ wxCC_SPECIAL_DCLICK = 0x0100,
+
+ // Dropbutton acts like standard push button.
+ wxCC_STD_BUTTON = 0x0200
+};
+
+
/**
@class wxComboPopup
@return @true if the call succeeded, @false otherwise.
*/
- virtual bool Create(wxWindow* parent);
+ virtual bool Create(wxWindow* parent) = 0;
+
+ /**
+ You only need to implement this member function if you create
+ your popup class in non-standard way. The default implementation can
+ handle both multiple-inherited popup control (as seen in wxComboCtrl
+ samples) and one allocated separately in heap.
+
+ If you do completely re-implement this function, make sure it calls
+ Destroy() for the popup control and also deletes @a this object
+ (usually as the last thing).
+ */
+ virtual void DestroyPopup();
/**
Utility function that hides the popup.
*/
void Dismiss();
+ /**
+ Implement to customize matching of value string to an item container
+ entry.
+
+ @param item
+ String entered, usually by user or from SetValue() call.
+
+ @param trueItem
+ When item matches an entry, but the entry's string representation
+ is not exactly the same (case mismatch, for example), then the
+ true item string should be written back to here, if it is not
+ a NULL pointer.
+
+ @remarks
+ Default implementation always return true and does not alter
+ trueItem.
+ */
+ virtual bool FindItem(const wxString& item, wxString* trueItem=NULL);
+
/**
The derived class may implement this to return adjusted size for the
popup control, according to the variables given.
Preferred minimum width.
@param prefHeight
Preferred height. May be -1 to indicate no preference.
- @param maxWidth
+ @param maxHeight
Max height for window, as limited by screen size.
@remarks This function is called each time popup is about to be shown.
*/
virtual wxSize GetAdjustedSize(int minWidth, int prefHeight, int maxHeight);
+ /**
+ Returns pointer to the associated parent wxComboCtrl.
+ */
+ wxComboCtrl* GetComboCtrl() const;
+
/**
The derived class must implement this to return pointer to the
associated control created in Create().
*/
- virtual wxWindow* GetControl();
+ virtual wxWindow* GetControl() = 0;
/**
The derived class must implement this to return string representation
of the value.
*/
- virtual wxString GetStringValue() const;
+ virtual wxString GetStringValue() const = 0;
/**
The derived class must implement this to initialize its internal
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
*/
virtual void SetStringValue(const wxString& value);
+protected:
/**
- Parent wxComboCtrl. This is parameter has been prepared before Init()
- is called.
+ Parent wxComboCtrl. This member variable is prepared automatically
+ before Init() is called.
*/
- wxComboCtrl m_combo;
+ wxComboCtrl* m_combo;
};
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.
+ TextIndent = 0x0008, ///< wxComboCtrl::SetMargins() 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
int m_value; // current item index
private:
- DECLARE_EVENT_TABLE()
+ wxDECLARE_EVENT_TABLE();
};
- BEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
+ wxBEGIN_EVENT_TABLE(wxListViewComboPopup, wxListView)
EVT_MOTION(wxListViewComboPopup::OnMouseMove)
EVT_LEFT_UP(wxListViewComboPopup::OnMouseClick)
- END_EVENT_TABLE()
+ wxEND_EVENT_TABLE()
@endcode
Here's how you would create and populate it in a dialog constructor:
wxListViewComboPopup* popupCtrl = new wxListViewComboPopup();
+ // It is important to call SetPopupControl() as soon as possible
comboCtrl->SetPopupControl(popupCtrl);
// Populate using wxListView methods
@style{wxCB_SORT}
Sorts the entries in the list alphabetically.
@style{wxTE_PROCESS_ENTER}
- The control will generate the event wxEVT_COMMAND_TEXT_ENTER
+ The control will generate the event @c wxEVT_TEXT_ENTER
(otherwise pressing Enter key is either processed internally by the
control or used for navigation between dialog controls). Windows
only.
Drop button will behave more like a standard push button.
@endStyleTable
- @beginEventTable{wxCommandEvent}
+ @beginEventEmissionTable{wxCommandEvent}
@event{EVT_TEXT(id, func)}
- Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes.
+ Process a @c wxEVT_TEXT event, when the text changes.
@event{EVT_TEXT_ENTER(id, func)}
- Process a wxEVT_COMMAND_TEXT_ENTER event, when RETURN is pressed in
+ Process a @c wxEVT_TEXT_ENTER event, when RETURN is pressed in
the combo control.
+ @event{EVT_COMBOBOX_DROPDOWN(id, func)}
+ Process a @c wxEVT_COMBOBOX_DROPDOWN event, which is generated
+ when the popup window is shown (drops down).
+ @event{EVT_COMBOBOX_CLOSEUP(id, func)}
+ Process a @c wxEVT_COMBOBOX_CLOSEUP event, which is generated
+ when the popup window of the combo control disappears (closes up).
+ You should avoid adding or deleting items in this event.
@endEventTable
- @library{wxbase}
+ @library{wxcore}
@category{ctrl}
- <!-- @appearance{comboctrl.png} -->
+ @appearance{comboctrl}
@see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup,
wxCommandEvent
*/
-class wxComboCtrl : public wxControl
+class wxComboCtrl : public wxControl,
+ public wxTextEntry
{
public:
/**
Initial selection string. An empty string indicates no selection.
@param pos
Window position.
+ If ::wxDefaultPosition is specified then a default position is chosen.
@param size
- Window size. If wxDefaultSize is specified then the window is sized
- appropriately.
+ Window size.
+ If ::wxDefaultSize is specified then the window is sized appropriately.
@param style
Window style. See wxComboCtrl.
@param validator
@see Create(), wxValidator
*/
- wxComboCtrl(wxWindow* parent, wxWindowID id,
- const wxString& value = "",
+ wxComboCtrl(wxWindow* parent, wxWindowID id = wxID_ANY,
+ const wxString& value = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
- const wxString& name = "comboCtrl");
+ const wxString& name = wxComboBoxNameStr);
/**
Destructor, destroying the combo control.
*/
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.
-
- 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.
*/
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 = wxID_ANY,
+ const wxString& value = wxEmptyString,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = 0,
const wxValidator& validator = wxDefaultValidator,
- const wxString& name = "comboCtrl");
+ const wxString& name = wxComboBoxNameStr);
/**
Copies the selected text to the clipboard and removes the selection.
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 @a popup is @NULL.
+ Dismisses the popup window.
- @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);
+ Notice that calling this function will generate a
+ @c wxEVT_COMBOBOX_CLOSEUP event.
- /**
- 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 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
+ @since 2.9.2
*/
- virtual void DoShowPopup(const wxRect& rect, int flags);
+ virtual void Dismiss();
+
/**
Enables or disables popup animation, if any, depending on the value of
*/
void EnablePopupAnimation(bool enable = true);
+
+ /**
+ Returns true if given key combination should toggle the popup.
+ */
+ virtual bool IsKeyPopupToggle(const wxKeyEvent& event) const;
+
+
+ /**
+ Prepare background of combo control or an item in a dropdown list in a
+ way typical on platform. This includes painting the focus/disabled
+ background and setting the clipping region.
+
+ Unless you plan to paint your own focus indicator, you should always
+ call this in your wxComboPopup::PaintComboControl implementation. In
+ addition, it sets pen and text colour to what looks good and proper
+ against the background.
+
+ flags: wxRendererNative flags:
+ wxCONTROL_ISSUBMENU: is drawing a list item instead of combo control
+ wxCONTROL_SELECTED: list item is selected
+ wxCONTROL_DISABLED: control/item is disabled
+ */
+ virtual void PrepareBackground( wxDC& dc, const wxRect& rect, int flags ) const;
+
+ /**
+ Returns true if focus indicator should be drawn in the control.
+ */
+ bool ShouldDrawFocus() const;
+
/**
Returns disabled button bitmap that has been set with
SetButtonBitmaps().
@return A reference to the disabled state bitmap.
*/
- const wxBitmap GetBitmapDisabled() const;
+ const wxBitmap& GetBitmapDisabled() const;
/**
Returns button mouse hover bitmap that has been set with
@return A reference to the mouse hover state bitmap.
*/
- const wxBitmap GetBitmapHover() const;
+ const wxBitmap& GetBitmapHover() const;
/**
Returns default button bitmap that has been set with
@return A reference to the normal state bitmap.
*/
- const wxBitmap GetBitmapNormal() const;
+ const wxBitmap& GetBitmapNormal() const;
/**
Returns depressed button bitmap that has been set with
@return A reference to the depressed state bitmap.
*/
- const wxBitmap GetBitmapPressed() const;
+ const wxBitmap& GetBitmapPressed() const;
/**
Returns current size of the dropdown button.
*/
static int GetFeatures();
+ /**
+ Returns the current hint string.
+
+ See SetHint() for more information about hints.
+
+ @since 2.9.1
+ */
+ virtual wxString GetHint() const;
+
/**
Returns the insertion point for the combo control's text field.
*/
virtual long GetLastPosition() const;
+ /**
+ Returns the margins used by the control. The @c x field of the returned
+ point is the horizontal margin and the @c y field is the vertical one.
+
+ @remarks If given margin cannot be accurately determined, its value
+ will be set to -1.
+
+ @see SetMargins()
+
+ @since 2.9.1
+ */
+ wxPoint GetMargins() const;
+
/**
Returns current popup interface that has been set with
SetPopupControl().
/**
Returns actual indentation in pixels.
+
+ @deprecated Use GetMargins() instead.
*/
wxCoord GetTextIndent() const;
Returns area covered by the text field (includes everything except
borders and the dropdown button).
*/
- const wxRect GetTextRect() const;
+ const wxRect& GetTextRect() const;
/**
Returns text representation of the current value. For writable combo
/**
Dismisses the popup window.
+
+ @param generateEvent
+ Set this to @true in order to generate
+ @c wxEVT_COMBOBOX_CLOSEUP event.
+
+ @deprecated Use Dismiss() instead.
*/
- virtual void HidePopup();
+ virtual void HidePopup(bool generateEvent=false);
/**
Returns @true if the popup is currently shown
*/
virtual void Paste();
+ /**
+ Shows the popup portion of the combo control.
+
+ Notice that calling this function will generate a
+ @c wxEVT_COMBOBOX_DROPDOWN event.
+
+ @since 2.9.2
+ */
+ virtual void Popup();
+
/**
Removes the text between the two positions in the combo control text
field.
@param text
The text to insert.
*/
- virtual void Replace(long from, long to, const wxString& value);
+ virtual void Replace(long from, long to, const wxString& text);
/**
Sets custom dropdown button graphics.
*/
void SetCustomPaintWidth(int width);
+ /**
+ Sets a hint shown in an empty unfocused combo control.
+
+ Notice that hints are known as <em>cue banners</em> under MSW or
+ <em>placeholder strings</em> under OS X.
+
+ @see wxTextEntry::SetHint()
+
+ @since 2.9.1
+ */
+ virtual bool SetHint(const wxString& hint);
+
/**
Sets the insertion point in the text field.
*/
virtual void SetInsertionPointEnd();
+ //@{
+ /**
+ Attempts to set the control margins. When margins are given as wxPoint,
+ x indicates the left and y the top margin. Use -1 to indicate that
+ an existing value should be used.
+
+ @return
+ @true if setting of all requested margins was successful.
+
+ @since 2.9.1
+ */
+ bool SetMargins(const wxPoint& pt);
+ bool SetMargins(wxCoord left, wxCoord top = -1);
+ //@}
+
/**
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
*/
void SetText(const wxString& value);
+ /**
+ Set a custom window style for the embedded wxTextCtrl. Usually you
+ will need to use this during two-step creation, just before Create().
+ For example:
+
+ @code
+ wxComboCtrl* comboCtrl = new wxComboCtrl();
+
+ // Let's make the text right-aligned
+ comboCtrl->SetTextCtrlStyle(wxTE_RIGHT);
+
+ comboCtrl->Create(parent, wxID_ANY, wxEmptyString);
+ @endcode
+ */
+ void SetTextCtrlStyle( int style );
+
/**
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.
+
+ @deprecated Use SetMargins() instead.
*/
void SetTextIndent(int indent);
virtual void SetValue(const wxString& value);
/**
- 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);
+ Changes value of the control as if user had done it by selecting an
+ item from a combo box drop-down list.
+ */
+ void SetValueByUser(const wxString& value);
/**
Show the popup.
+
+ @deprecated Use Popup() instead.
*/
virtual void ShowPopup();
will appear as if the focus has been lost from it.
*/
void UseAltPopupWindow(bool enable = true);
+
+protected:
+
+ /**
+ 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.
+
+ 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);
+
+ /**
+ This member function is not normally called in application code.
+ Instead, it can be implemented in a derived class to return default
+ wxComboPopup, in case @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.
+ */
+ virtual 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 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);
};
projects / wxWidgets.git / blobdiff