X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/d9fb481c56002b3f8fcda13069e0890d33a00511..5b88a837ba75928cd3835a6b97ae2bf5ad983a6e:/interface/wx/propgrid/editors.h diff --git a/interface/wx/propgrid/editors.h b/interface/wx/propgrid/editors.h index 693112e573..29738a5c22 100644 --- a/interface/wx/propgrid/editors.h +++ b/interface/wx/propgrid/editors.h @@ -2,26 +2,27 @@ // Name: editors.h // Purpose: interface of wxPropertyGrid editors // Author: wxWidgets team -// RCS-ID: $Id: +// RCS-ID: $Id$ // Licence: wxWindows license ///////////////////////////////////////////////////////////////////////////// -// ----------------------------------------------------------------------- -/** @class wxPGEditor +/** + @class wxPGEditor Base class for custom wxPropertyGrid editors. @remarks - - Names of builtin property editors are: TextCtrl, Choice, - ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional editors - include SpinCtrl and DatePickerCtrl, but using them requires calling - wxPropertyGrid::RegisterAdditionalEditors() prior use. + - Names of built-in property editors are: TextCtrl, Choice, + ComboBox, CheckBox, TextCtrlAndButton, and ChoiceAndButton. Additional + editors include SpinCtrl and DatePickerCtrl, but using them requires + calling wxPropertyGrid::RegisterAdditionalEditors() prior use. - - Pointer to builtin editor is available as wxPGEditor_EditorName + - Pointer to built-in editor is available as wxPGEditor_EditorName (eg. wxPGEditor_TextCtrl). - - To add new editor you need to register it first using static function + - Before you start using new editor you just created, you need to register + it using static function wxPropertyGrid::RegisterEditorClass(), with code like this: @code wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor"); @@ -38,136 +39,153 @@ class wxPGEditor : public wxObject public: /** Constructor. */ - wxPGEditor() - : wxObject() - { - m_clientData = NULL; - } + wxPGEditor(); /** Destructor. */ virtual ~wxPGEditor(); - /** Returns pointer to the name of the editor. For example, wxPG_EDITOR(TextCtrl) - has name "TextCtrl". This method is autogenerated for custom editors. + /** + Returns pointer to the name of the editor. For example, + wxPGEditor_TextCtrl has name "TextCtrl". If you dont' need to access + your custom editor by string name, then you do not need to implement + this function. */ - virtual wxString GetName() const = 0; + virtual wxString GetName() const; + + /** + Instantiates editor controls. - /** Instantiates editor controls. @param propgrid - wxPropertyGrid to which the property belongs (use as parent for control). + wxPropertyGrid to which the property belongs (use as parent for control). + @param property - Property for which this method is called. + Property for which this method is called. + @param pos - Position, inside wxPropertyGrid, to create control(s) to. + Position, inside wxPropertyGrid, to create control(s) to. + @param size - Initial size for control(s). + Initial size for control(s). @remarks - Primary control shall use id wxPG_SUBID1, and secondary (button) control shall use wxPG_SUBID2. - - Implementation shoud connect all necessary events to the - wxPropertyGrid::OnCustomEditorEvent. For Example: - @code - // Relays wxEVT_COMMAND_TEXT_UPDATED events of primary editor - // control to the OnEvent. - propgrid->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED, - wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent)); - @endcode - OnCustomEditorEvent will then forward events, first to - wxPGEditor::OnEvent() and then to wxPGProperty::OnEvent(). + - Unlike in previous version of wxPropertyGrid, it is no longer + necessary to call wxEvtHandler::Connect() for interesting editor + events. Instead, all events from control are now automatically + forwarded to wxPGEditor::OnEvent() and wxPGProperty::OnEvent(). */ - virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid, wxPGProperty* property, - const wxPoint& pos, const wxSize& size ) const = 0; + virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid, + wxPGProperty* property, + const wxPoint& pos, + const wxSize& size ) const = 0; /** Loads value from property to the control. */ virtual void UpdateControl( wxPGProperty* property, wxWindow* ctrl ) const = 0; - /** Draws value for given property. + /** + Draws value for given property. */ - virtual void DrawValue( wxDC& dc, const wxRect& rect, wxPGProperty* property, const wxString& text ) const; - - /** Handles events. Returns true if value in control was modified - (see wxPGProperty::OnEvent for more information). + virtual void DrawValue( wxDC& dc, const wxRect& rect, + wxPGProperty* property, const wxString& text ) const; + + /** + Handles events. Returns @true if value in control was modified + (see wxPGProperty::OnEvent() for more information). + + @remarks wxPropertyGrid will automatically unfocus the editor when + wxEVT_COMMAND_TEXT_ENTER is received and when it results in + property value being modified. This happens regardless of + editor type (ie. behavior is same for any wxTextCtrl and + wxComboBox based editor). */ virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property, wxWindow* wnd_primary, wxEvent& event ) const = 0; - /** Returns value from control, via parameter 'variant'. - Usually ends up calling property's StringToValue or IntToValue. - Returns true if value was different. + /** + Returns value from control, via parameter 'variant'. + Usually ends up calling property's StringToValue() or IntToValue(). + Returns @true if value was different. */ - virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property, wxWindow* ctrl ) const; + virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property, + wxWindow* ctrl ) const; /** Sets value in control to unspecified. */ - virtual void SetValueToUnspecified( wxPGProperty* property, wxWindow* ctrl ) const = 0; + virtual void SetValueToUnspecified( wxPGProperty* property, + wxWindow* ctrl ) const = 0; /** Sets control's value specifically from string. */ - virtual void SetControlStringValue( wxPGProperty* property, wxWindow* ctrl, const wxString& txt ) const; + virtual void SetControlStringValue( wxPGProperty* property, + wxWindow* ctrl, const wxString& txt ) const; /** Sets control's value specifically from int (applies to choice etc.). */ - virtual void SetControlIntValue( wxPGProperty* property, wxWindow* ctrl, int value ) const; + virtual void SetControlIntValue( wxPGProperty* property, + wxWindow* ctrl, int value ) const; - /** Inserts item to existing control. Index -1 means appending. + /** + Inserts item to existing control. Index -1 means end of list. Default implementation does nothing. Returns index of item added. */ virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const; - /** Deletes item from existing control. + /** + Deletes item from existing control. Default implementation does nothing. */ virtual void DeleteItem( wxWindow* ctrl, int index ) const; - /** Extra processing when control gains focus. For example, wxTextCtrl - based controls should select all text. + /** + Extra processing when control gains focus. + For example, wxTextCtrl based controls should select all text. */ virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const; - /** Returns true if control itself can contain the custom image. Default is - to return false. + /** + Returns @true if control itself can contain the custom image. + Default implementation returns @false. */ virtual bool CanContainCustomImage() const; - - // - // This member is public so scripting language bindings - // wrapper code can access it freely. - void* m_clientData; }; -// ----------------------------------------------------------------------- -/** @class wxPGMultiButton + +/** + @class wxPGMultiButton This class can be used to have multiple buttons in a property editor. You will need to create a new property editor class, override CreateControls, and have it return wxPGMultiButton instance in wxPGWindowList::SetSecondary(). - For instance, here we add three buttons to a textctrl editor: - @code + For instance, here we add three buttons to a TextCtrl editor: + @code #include - class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor + class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor { - WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor) + DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor) public: - wxMultiButtonTextCtrlEditor() {} - virtual ~wxMultiButtonTextCtrlEditor() {} + wxSampleMultiButtonEditor() {} + virtual ~wxSampleMultiButtonEditor() {} + + virtual wxString GetName() const { return "SampleMultiButtonEditor"; } - wxPG_DECLARE_CREATECONTROLS + virtual wxPGWindowList CreateControls( wxPropertyGrid* propGrid, + wxPGProperty* property, + const wxPoint& pos, + const wxSize& sz ) const; virtual bool OnEvent( wxPropertyGrid* propGrid, wxPGProperty* property, wxWindow* ctrl, wxEvent& event ) const; - }; - WX_PG_IMPLEMENT_EDITOR_CLASS(MultiButtonTextCtrlEditor, wxMultiButtonTextCtrlEditor, - wxPGTextCtrlEditor) + IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor) - wxPGWindowList wxMultiButtonTextCtrlEditor::CreateControls( wxPropertyGrid* propGrid, - wxPGProperty* property, - const wxPoint& pos, - const wxSize& sz ) const + wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid, + wxPGProperty* property, + const wxPoint& pos, + const wxSize& sz ) const { // Create and populate buttons-subwindow wxPGMultiButton* buttons = new wxPGMultiButton( propGrid, sz ); @@ -180,20 +198,21 @@ public: // Create the 'primary' editor control (textctrl in this case) wxPGWindowList wndList = wxPGTextCtrlEditor::CreateControls - ( propGrid, property, pos, buttons->GetPrimarySize() ); + ( propGrid, property, pos, + buttons->GetPrimarySize() ); // Finally, move buttons-subwindow to correct position and make sure // returned wxPGWindowList contains our custom button list. - buttons->FinalizePosition(pos); + buttons->Finalize(propGrid, pos); wndList.SetSecondary( buttons ); return wndList; } - bool wxMultiButtonTextCtrlEditor::OnEvent( wxPropertyGrid* propGrid, - wxPGProperty* property, - wxWindow* ctrl, - wxEvent& event ) const + bool wxSampleMultiButtonEditor::OnEvent( wxPropertyGrid* propGrid, + wxPGProperty* property, + wxWindow* ctrl, + wxEvent& event ) const { if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED ) { @@ -201,38 +220,37 @@ public: if ( event.GetId() == buttons->GetButtonId(0) ) { - // Do something when first button is pressed - return true; + // Do something when the first button is pressed + // Return true if the action modified the value in editor. + ... } if ( event.GetId() == buttons->GetButtonId(1) ) { - // Do something when first button is pressed - return true; + // Do something when the second button is pressed + ... } if ( event.GetId() == buttons->GetButtonId(2) ) { - // Do something when second button is pressed - return true; + // Do something when the third button is pressed + ... } } return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event); } - @endcode Further to use this editor, code like this can be used: @code - // Register editor class - needs only to be called once - wxPGRegisterEditorClass( MultiButtonTextCtrlEditor ); + wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor(); + wxPropertyGrid::RegisterEditorClass( multiButtonEditor ); // Insert the property that will have multiple buttons propGrid->Append( new wxLongStringProperty("MultipleButtons", wxPG_LABEL) ); // Change property to use editor created in the previous code segment - propGrid->SetPropertyEditor( "MultipleButtons", wxPG_EDITOR(MultiButtonTextCtrlEditor) ); - + propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor ); @endcode @library{wxpropgrid} @@ -241,36 +259,58 @@ public: class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow { public: - + /** + Constructor. + */ wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz ); + /** + Destructor. + */ virtual ~wxPGMultiButton() { } - wxWindow* GetButton( unsigned int i ) { return (wxWindow*) m_buttons[i]; } - const wxWindow* GetButton( unsigned int i ) const { return (const wxWindow*) m_buttons[i]; } + /** + Adds new button, with given label. + */ + void Add( const wxString& label, int id = -2 ); - /** Utility function to be used in event handlers. + /** + Adds new bitmap button. */ - int GetButtonId( unsigned int i ) const { return GetButton(i)->GetId(); } + void Add( const wxBitmap& bitmap, int id = -2 ); + + /** + Call this in CreateControls() of your custom editor class + after all buttons have been added. - /** Returns number of buttons. + @param propGrid + wxPropertyGrid given in CreateControls(). + + @param pos + wxPoint given in CreateControls(). */ - int GetCount() const { return m_buttons.Count(); } + void Finalize( wxPropertyGrid* propGrid, const wxPoint& pos ); - void Add( const wxString& label, int id = -2 ); - void Add( const wxBitmap& bitmap, int id = -2 ); + /** + Returns pointer to one of the buttons. + */ + wxWindow* GetButton( unsigned int i ); - wxSize GetPrimarySize() const - { - return wxSize(m_fullEditorSize.x - m_buttonsWidth, m_fullEditorSize.y); - } + /** + Returns Id of one of the buttons. + This is utility function to be used in event handlers. + */ + int GetButtonId( unsigned int i ) const; - void FinalizePosition( const wxPoint& pos ) - { - Move( pos.x + m_fullEditorSize.x - m_buttonsWidth, pos.y ); - } -}; + /** + Returns number of buttons. + */ + unsigned int GetCount(); -// ----------------------------------------------------------------------- + /** + Returns size of primary editor control, as appropriately + reduced by number of buttons present. + */ + wxSize GetPrimarySize() const; +}; -#endif // _WX_PROPGRID_EDITORS_H_