X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/bb3400a8738a90b33a055e410cf02e34e66193bc..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/combo.h diff --git a/interface/wx/combo.h b/interface/wx/combo.h index 25e1ef7756..3531173f4b 100644 --- a/interface/wx/combo.h +++ b/interface/wx/combo.h @@ -3,9 +3,23 @@ // 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 @@ -36,11 +50,42 @@ public: */ 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. @@ -86,7 +131,7 @@ public: 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 @@ -254,13 +299,13 @@ struct wxComboCtrlFeatures 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: @@ -285,7 +330,7 @@ struct wxComboCtrlFeatures @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_COMMAND_TEXT_ENTER (otherwise pressing Enter key is either processed internally by the control or used for navigation between dialog controls). Windows only. @@ -300,15 +345,15 @@ struct wxComboCtrlFeatures @beginEventEmissionTable{wxCommandEvent} @event{EVT_TEXT(id, func)} - Process a wxEVT_COMMAND_TEXT_UPDATED event, when the text changes. + Process a @c wxEVT_COMMAND_TEXT_UPDATED 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_COMMAND_TEXT_ENTER event, when RETURN is pressed in the combo control. - @event{EVT_COMBOX_DROPDOWN(id, func)} - Process a wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated + @event{EVT_COMBOBOX_DROPDOWN(id, func)} + Process a @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event, which is generated when the popup window is shown (drops down). - @event{EVT_COMBOX_CLOSEUP(id, func)} - Process a wxEVT_COMMAND_COMBOBOX_CLOSEUP event, which is generated + @event{EVT_COMBOBOX_CLOSEUP(id, func)} + Process a @c wxEVT_COMMAND_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 @@ -320,7 +365,8 @@ struct wxComboCtrlFeatures @see wxComboBox, wxChoice, wxOwnerDrawnComboBox, wxComboPopup, wxCommandEvent */ -class wxComboCtrl : public wxControl +class wxComboCtrl : public wxControl, + public wxTextEntry { public: /** @@ -388,12 +434,52 @@ public: */ virtual void Cut(); + /** + Dismisses the popup window. + + Notice that calling this function will generate a + @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event. + + @since 2.9.2 + */ + virtual void Dismiss(); + + /** Enables or disables popup animation, if any, depending on the value of the argument. */ 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(). @@ -448,6 +534,15 @@ public: */ 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. @@ -514,7 +609,9 @@ public: @param generateEvent Set this to @true in order to generate - wxEVT_COMMAND_COMBOBOX_CLOSEUP event. + @c wxEVT_COMMAND_COMBOBOX_CLOSEUP event. + + @deprecated Use Dismiss() instead. */ virtual void HidePopup(bool generateEvent=false); @@ -551,6 +648,16 @@ public: */ virtual void Paste(); + /** + Shows the popup portion of the combo control. + + Notice that calling this function will generate a + @c wxEVT_COMMAND_COMBOBOX_DROPDOWN event. + + @since 2.9.2 + */ + virtual void Popup(); + /** Removes the text between the two positions in the combo control text field. @@ -620,6 +727,18 @@ public: */ void SetCustomPaintWidth(int width); + /** + Sets a hint shown in an empty unfocused combo control. + + Notice that hints are known as cue banners under MSW or + placeholder strings under OS X. + + @see wxTextEntry::SetHint() + + @since 2.9.1 + */ + virtual bool SetHint(const wxString& hint); + /** Sets the insertion point in the text field. @@ -713,6 +832,22 @@ public: */ 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 @@ -732,13 +867,15 @@ public: 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(); @@ -774,7 +911,7 @@ protected: /** 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. + 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