don't place NULL pointers in the GDK window array in GTKGetWindow()

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

diff --git a/interface/wx/propgrid/editors.h b/interface/wx/propgrid/editors.h
index 693112e573181068a86a1b2c59858f4490fe4007..29738a5c22ee858211196d9d47c76d035dacd49f 100644 (file)
--- 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
 // Name:        editors.h
 // Purpose:     interface of wxPropertyGrid editors
 // Author:      wxWidgets team

-// RCS-ID:      $Id:
+// RCS-ID:      $Id$

 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 

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

 
 

-/** @class wxPGEditor
+/**
+    @class wxPGEditor

 
     Base class for custom wxPropertyGrid editors.
 
     @remarks
 
     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).
 
       (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");
       wxPropertyGrid::RegisterEditorClass(), with code like this:
         @code
             wxPGEditor* editorPointer = wxPropertyGrid::RegisterEditorClass(new MyEditorClass(), "MyEditor");


@@ -38,136 +39,153 @@ class wxPGEditor : public wxObject
 public:
 
     /** Constructor. */
 public:
 
     /** Constructor. */

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

 
     /** Destructor. */
     virtual ~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
         @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
         @param property

-        Property for which this method is called.
+            Property for which this method is called.
+

         @param pos
         @param pos

-        Position, inside wxPropertyGrid, to create control(s) to.
+            Position, inside wxPropertyGrid, to create control(s) to.
+

         @param size
         @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.
 
         @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;
 
 
     /** 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;
 
     */
     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. */
 
     /** 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. */
 
     /** 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.). */
 
     /** 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;
 
         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;
 
         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;
 
     */
     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;
     */
     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().
 
     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>
 
     #include <wx/propgrid/editors.h>
 

-    class wxMultiButtonTextCtrlEditor : public wxPGTextCtrlEditor
+    class wxSampleMultiButtonEditor : public wxPGTextCtrlEditor

     {
     {

-        WX_PG_DECLARE_EDITOR_CLASS(wxMultiButtonTextCtrlEditor)
+        DECLARE_DYNAMIC_CLASS(wxSampleMultiButtonEditor)

     public:
     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;
         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 );
     {
         // 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
 
         // 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.
 
         // 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;
     }
 
 
         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 )
         {
     {
         if ( event.GetEventType() == wxEVT_COMMAND_BUTTON_CLICKED )
         {


@@ -201,38 +220,37 @@ 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 first 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 second 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
         // 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
 
         // 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}
     @endcode
 
     @library{wxpropgrid}


@@ -241,36 +259,58 @@ public:
 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 {
 public:
 class WXDLLIMPEXP_PROPGRID wxPGMultiButton : public wxWindow
 {
 public:

-
+    /**
+        Constructor.
+    */

     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 
     wxPGMultiButton( wxPropertyGrid* pg, const wxSize& sz );
 

+    /**
+        Destructor.
+    */

     virtual ~wxPGMultiButton() { }
 
     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_