synchronize GTK2 minimum version in docs

[wxWidgets.git] / interface / wx / propgrid / editors.h

diff --git a/interface/wx/propgrid/editors.h b/interface/wx/propgrid/editors.h
index 77ae7bf00594cb5ce67cef3cc5e813148478afeb..8f563a05d735cd4a28444a18a4c867d5a831e875 100644 (file)
--- a/interface/wx/propgrid/editors.h
+++ b/interface/wx/propgrid/editors.h
@@ -2,11 +2,10 @@
 // Name:        editors.h
 // Purpose:     interface of wxPropertyGrid editors
 // Author:      wxWidgets team
 // 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


@@ -40,20 +39,18 @@ class wxPGEditor : public wxObject
 public:
 
     /** Constructor. */
 public:
 
     /** Constructor. */

-    wxPGEditor()
-        : wxObject()
-    {
-        m_clientData = NULL;
-    }
+    wxPGEditor();

 
     /** Destructor. */
     virtual ~wxPGEditor();
 
     /**
         Returns pointer to the name of the editor. For example,
 
     /** Destructor. */
     virtual ~wxPGEditor();
 
     /**
         Returns pointer to the name of the editor. For example,

-        wxPGEditor_TextCtrl has name "TextCtrl".
+        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.


@@ -73,17 +70,10 @@ public:
         @remarks
         - Primary control shall use id wxPG_SUBID1, and secondary (button) control
           shall use wxPG_SUBID2.
         @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.
-                control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
-                                 wxCommandEventHandler(wxPropertyGrid::OnCustomEditorEvent),
-                                 NULL, propgrid);
-            @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,
     */
     virtual wxPGWindowList CreateControls( wxPropertyGrid* propgrid,
                                            wxPGProperty* property,


@@ -102,6 +92,12 @@ public:
     /**
         Handles events. Returns @true if value in control was modified
         (see wxPGProperty::OnEvent() for more information).
     /**
         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;
     */
     virtual bool OnEvent( wxPropertyGrid* propgrid, wxPGProperty* property,
         wxWindow* wnd_primary, wxEvent& event ) const = 0;


@@ -112,26 +108,46 @@ public:
         Returns @true if value was different.
     */
     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,
         Returns @true if value was different.
     */
     virtual bool GetValueFromControl( wxVariant& variant, wxPGProperty* property,

-        wxWindow* ctrl ) const;
+                                      wxWindow* ctrl ) const;

 
     /** Sets value in control to unspecified. */
     virtual void SetValueToUnspecified( wxPGProperty* property,
 
     /** Sets value in control to unspecified. */
     virtual void SetValueToUnspecified( wxPGProperty* property,

-        wxWindow* ctrl ) const = 0;
+                                        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,
 
     /** Sets control's value specifically from string. */
     virtual void SetControlStringValue( wxPGProperty* property,

-        wxWindow* ctrl, const wxString& txt ) const;
+                                        wxWindow* ctrl, const wxString& txt ) const;

 
     /** Sets control's value specifically from int (applies to choice etc.). */
     virtual void SetControlIntValue( wxPGProperty* property,
 
     /** Sets control's value specifically from int (applies to choice etc.). */
     virtual void SetControlIntValue( wxPGProperty* property,

-        wxWindow* ctrl, int value ) const;
+                                     wxWindow* ctrl, int value ) const;

 
     /**
         Inserts item to existing control. Index -1 means end of list.
         Default implementation does nothing. Returns index of item added.
     */
 
     /**
         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;
+    virtual int InsertItem( wxWindow* ctrl, const wxString& label, int index ) const;

 
     /**
         Deletes item from existing control.
 
     /**
         Deletes item from existing control.


@@ -140,19 +156,19 @@ public:
     virtual void DeleteItem( wxWindow* ctrl, int index ) const;
 
     /**
     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;
 
     /**
     */
     virtual void OnFocus( wxPGProperty* property, wxWindow* wnd ) const;
 
     /**

-        Returns @true if control itself can contain the custom image. Default
-        implementation returns @false.
+        Returns @true if control itself can contain the custom image.
+        Default implementation returns @false.

     */
     virtual bool CanContainCustomImage() const;
 };
 
     */
     virtual bool CanContainCustomImage() const;
 };
 

-// -----------------------------------------------------------------------
+

 
 /**
     @class wxPGMultiButton
 
 /**
     @class wxPGMultiButton


@@ -164,12 +180,12 @@ public:
     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 wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
     {
     #include <wx/propgrid/editors.h>
 
     class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor
     {

-        DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)
+        wxDECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor);
+        

     public:
         wxSampleMultiButtonEditor() {}
         virtual ~wxSampleMultiButtonEditor() {}
     public:
         wxSampleMultiButtonEditor() {}
         virtual ~wxSampleMultiButtonEditor() {}


@@ -186,7 +202,7 @@ public:
                               wxEvent& event ) const;
     };
 
                               wxEvent& event ) const;
     };
 

-    IMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor)
+    wxIMPLEMENT_DYNAMIC_CLASS(wxSampleMultiButtonEditor, wxPGTextCtrlEditor);

 
     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
                                                               wxPGProperty* property,
 
     wxPGWindowList wxSampleMultiButtonEditor::CreateControls( wxPropertyGrid* propGrid,
                                                               wxPGProperty* property,


@@ -226,29 +242,28 @@ public:
 
             if ( event.GetId() == buttons->GetButtonId(0) )
             {
 
             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) )
             {
             }
             if ( event.GetId() == buttons->GetButtonId(1) )
             {

-                // Do something when second button is pressed
-                return true;
+                // Do something when the second button is pressed
+                ...

             }
             if ( event.GetId() == buttons->GetButtonId(2) )
             {
             }
             if ( event.GetId() == buttons->GetButtonId(2) )
             {

-                // Do something when third button is pressed
-                return true;
+                // Do something when the third button is pressed
+                ...

             }
         }
         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
     }
             }
         }
         return wxPGTextCtrlEditor::OnEvent(propGrid, property, ctrl, event);
     }

-

     @endcode
 
     Further to use this editor, code like this can be used:
 
     @code
     @endcode
 
     Further to use this editor, code like this can be used:
 
     @code

-

         // Register editor class - needs only to be called once
         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );
         // Register editor class - needs only to be called once
         wxPGEditor* multiButtonEditor = new wxSampleMultiButtonEditor();
         wxPropertyGrid::RegisterEditorClass( multiButtonEditor );


@@ -258,7 +273,6 @@ public:
 
         // Change property to use editor created in the previous code segment
         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );
 
         // Change property to use editor created in the previous code segment
         propGrid->SetPropertyEditor( "MultipleButtons", multiButtonEditor );

-

     @endcode
 
     @library{wxpropgrid}
     @endcode
 
     @library{wxpropgrid}


@@ -267,7 +281,6 @@ public:
 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 {
 public:
 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 {
 public:

-

     /**
         Constructor.
     */
     /**
         Constructor.
     */


@@ -306,15 +319,15 @@ public:
     wxWindow* GetButton( unsigned int i );
 
     /**
     wxWindow* GetButton( unsigned int i );
 
     /**

-        Returns Id of one of the buttons. This is utility function to be
-        used in event handlers.
+        Returns Id of one of the buttons.
+        This is utility function to be used in event handlers.

     */
     int GetButtonId( unsigned int i ) const;
 
     /**
         Returns number of buttons.
     */
     */
     int GetButtonId( unsigned int i ) const;
 
     /**
         Returns number of buttons.
     */

-    int GetCount();
+    unsigned int GetCount();

 
     /**
         Returns size of primary editor control, as appropriately
 
     /**
         Returns size of primary editor control, as appropriately


@@ -323,4 +336,3 @@ public:
     wxSize GetPrimarySize() const;
 };
 
     wxSize GetPrimarySize() const;
 };
 

-// -----------------------------------------------------------------------