]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/propgrid/editors.h
synchronize GTK2 minimum version in docs
[wxWidgets.git] / interface / wx / propgrid / editors.h
index 693112e573181068a86a1b2c59858f4490fe4007..8f563a05d735cd4a28444a18a4c867d5a831e875 100644 (file)
@@ -2,26 +2,27 @@
 // Name:        editors.h
 // Purpose:     interface of wxPropertyGrid editors
 // Author:      wxWidgets team
-// RCS-ID:      $Id:
-// Licence:     wxWindows license
+// RCS-ID:      $Id$
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
-// -----------------------------------------------------------------------
 
-/** @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,175 @@ 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
+                 @c wxEVT_COMMAND_TEXT_ENTER is received and when it results in
+                 property value being modified. This happens regardless of
+                 editor type (ie. behaviour 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;
+
+    /**
+        Called by property grid to set new appearance for the control.
+        Default implementation  sets foreground colour, background colour,
+        font, plus text for wxTextCtrl and wxComboCtrl.
+
+        The parameter @a appearance represents the new appearance to be applied.
+
+        The parameter @a oldAppearance is the previously applied appearance. 
+        Used to detect which control attributes need to be changed (e.g. so we only
+        change background colour if really needed).
+
+        Finally, the parameter @a unspecified if @true tells this function that
+        the new appearance represents an unspecified property value.
+    */
+    virtual void SetControlAppearance( wxPropertyGrid* pg,
+                                       wxPGProperty* property,
+                                       wxWindow* ctrl,
+                                       const wxPGCell& appearance,
+                                       const wxPGCell& oldAppearance,
+                                       bool unspecified ) const;
 
     /** 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 <wx/propgrid/editors.h>
 
-    class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor
+    class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
     {
-        WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor)
+        wxDECLARE_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)
+    wxIMPLEMENT_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 +220,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 +242,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 +281,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.
+
+        @param propGrid
+            wxPropertyGrid given in CreateControls().
 
-    /** Returns number of buttons.
+        @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_