Implement GetPageText for the OSX WebKit implementation.

[wxWidgets.git] / include / wx / propgrid / propgridiface.h

diff --git a/include/wx/propgrid/propgridiface.h b/include/wx/propgrid/propgridiface.h
index 06712abf3500fcaa78e8a476141607192b3dd557..9cc773d493101fd6677b6f08544be526966521f0 100644 (file)
--- a/include/wx/propgrid/propgridiface.h
+++ b/include/wx/propgrid/propgridiface.h
@@ -1,17 +1,19 @@
 /////////////////////////////////////////////////////////////////////////////
 /////////////////////////////////////////////////////////////////////////////

-// Name:        wx/propgeid/propgridiface.h
+// Name:        wx/propgrid/propgridiface.h

 // Purpose:     wxPropertyGridInterface class
 // Author:      Jaakko Salli
 // Modified by:
 // Created:     2008-08-24
 // RCS-ID:      $Id$
 // Copyright:   (c) Jaakko Salli
 // Purpose:     wxPropertyGridInterface class
 // Author:      Jaakko Salli
 // Modified by:
 // Created:     2008-08-24
 // RCS-ID:      $Id$
 // Copyright:   (c) Jaakko Salli

-// Licence:     wxWindows license
+// Licence:     wxWindows licence

 /////////////////////////////////////////////////////////////////////////////
 
 #ifndef __WX_PROPGRID_PROPGRIDIFACE_H__
 #define __WX_PROPGRID_PROPGRIDIFACE_H__
 
 /////////////////////////////////////////////////////////////////////////////
 
 #ifndef __WX_PROPGRID_PROPGRIDIFACE_H__
 #define __WX_PROPGRID_PROPGRIDIFACE_H__
 

+#include "wx/defs.h"
+

 #if wxUSE_PROPGRID
 
 #include "wx/propgrid/property.h"
 #if wxUSE_PROPGRID
 
 #include "wx/propgrid/property.h"


@@ -19,8 +21,6 @@
 
 // -----------------------------------------------------------------------
 
 
 // -----------------------------------------------------------------------
 

-#ifndef SWIG
-

 /** @section wxPGPropArgCls
 
     Most property grid functions have this type as their argument, as it can
 /** @section wxPGPropArgCls
 
     Most property grid functions have this type as their argument, as it can


@@ -66,13 +66,11 @@ public:
         m_ptr.charName = str;
         m_flags = IsCharPtr;
     }
         m_ptr.charName = str;
         m_flags = IsCharPtr;
     }

-#if wxUSE_WCHAR_T

     wxPGPropArgCls( const wchar_t* str )
     {
         m_ptr.wcharName = str;
         m_flags = IsWCharPtr;
     }
     wxPGPropArgCls( const wchar_t* str )
     {
         m_ptr.wcharName = str;
         m_flags = IsWCharPtr;
     }

-#endif

     /** This constructor is required for NULL. */
     wxPGPropArgCls( int )
     {
     /** This constructor is required for NULL. */
     wxPGPropArgCls( int )
     {


@@ -102,16 +100,12 @@ private:
     {
         wxPGProperty* property;
         const char* charName;
     {
         wxPGProperty* property;
         const char* charName;

-#if wxUSE_WCHAR_T

         const wchar_t* wcharName;
         const wchar_t* wcharName;

-#endif

         const wxString* stringName;
     } m_ptr;
     unsigned char m_flags;
 };
 
         const wxString* stringName;
     } m_ptr;
     unsigned char m_flags;
 };
 

-#endif
-

 typedef const wxPGPropArgCls& wxPGPropArg;
 
 // -----------------------------------------------------------------------
 typedef const wxPGPropArgCls& wxPGPropArg;
 
 // -----------------------------------------------------------------------


@@ -210,8 +204,12 @@ public:
         @return Returns @true if successful or if there was no selection. May
                 fail if validation was enabled and active editor had invalid
                 value.
         @return Returns @true if successful or if there was no selection. May
                 fail if validation was enabled and active editor had invalid
                 value.

+
+        @remarks In wxPropertyGrid 1.4, this member function used to send
+                 wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer
+                 does that.

     */
     */

-    bool ClearSelection( bool validation = false);
+    bool ClearSelection( bool validation = false );

 
     /** Resets modified status of all properties.
     */
 
     /** Resets modified status of all properties.
     */


@@ -240,22 +238,42 @@ public:
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**

-        Deletes a property by id. If category is deleted, all children are
-        automatically deleted as well.
-     */
+        Removes and deletes a property and any children.
+
+        @param id
+            Pointer or name of a property.
+
+        @remarks If you delete a property in a wxPropertyGrid event
+                 handler, the actual deletion is postponed until the next
+                 idle event.
+
+                 This functions deselects selected property, if any.
+                 Validation failure option wxPG_VFB_STAY_IN_PROPERTY is not
+                 respected, ie. selection is cleared even if editor had
+                 invalid value.
+    */

     void DeleteProperty( wxPGPropArg id );
 
     /**
     void DeleteProperty( wxPGPropArg id );
 
     /**

-        Removes and returns a property.
+        Removes a property. Does not delete the property object, but
+        instead returns it.

 
         @param id
             Pointer or name of a property.
 
         @remarks Removed property cannot have any children.
 
         @param id
             Pointer or name of a property.
 
         @remarks Removed property cannot have any children.

+
+                 Also, if you remove property in a wxPropertyGrid event
+                 handler, the actual removal is postponed until the next
+                 idle event.

     */
     wxPGProperty* RemoveProperty( wxPGPropArg id );
 
     */
     wxPGProperty* RemoveProperty( wxPGPropArg id );
 

-    /** Disables property. */
+    /**
+        Disables a property.
+
+        @see EnableProperty(), wxPGProperty::Enable()
+    */

     bool DisableProperty( wxPGPropArg id ) { return EnableProperty(id,false); }
 
     /**
     bool DisableProperty( wxPGPropArg id ) { return EnableProperty(id,false); }
 
     /**


@@ -268,7 +286,14 @@ public:
 
     /**
         Enables or disables property, depending on whether enable is true or
 
     /**
         Enables or disables property, depending on whether enable is true or

-        false.
+        false. Disabled property usually appears as having grey text.
+
+        @param id
+            Name or pointer to a property.
+        @param enable
+            If @false, property is disabled instead.
+
+        @see wxPGProperty::Enable()

      */
     bool EnableProperty( wxPGPropArg id, bool enable = true );
 
      */
     bool EnableProperty( wxPGPropArg id, bool enable = true );
 


@@ -356,7 +381,7 @@ public:
         If there is no property with such name, @NULL pointer is returned.
 
         @remarks Properties which have non-category, non-root parent
         If there is no property with such name, @NULL pointer is returned.
 
         @remarks Properties which have non-category, non-root parent

-                 can not be accessed globally by their name. Instead, use
+                 cannot be accessed globally by their name. Instead, use

                  "<property>.<subproperty>" instead of "<subproperty>".
     */
     wxPGProperty* GetProperty( const wxString& name ) const
                  "<property>.<subproperty>" instead of "<subproperty>".
     */
     wxPGProperty* GetProperty( const wxString& name ) const


@@ -411,14 +436,12 @@ public:
         return m_pState->GetPropertyCategory(p);
     }
 
         return m_pState->GetPropertyCategory(p);
     }
 

-#ifndef SWIG

     /** Returns client data (void*) of a property. */
     void* GetPropertyClientData( wxPGPropArg id ) const
     {
         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
         return p->GetClientData();
     }
     /** Returns client data (void*) of a property. */
     void* GetPropertyClientData( wxPGPropArg id ) const
     {
         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL)
         return p->GetClientData();
     }

-#endif

 
     /**
         Returns first property which label matches given string.
 
     /**
         Returns first property which label matches given string.


@@ -507,10 +530,8 @@ public:
     {
         return (unsigned long) GetPropertyValueAsLong(id);
     }
     {
         return (unsigned long) GetPropertyValueAsLong(id);
     }

-#ifndef SWIG

     int GetPropertyValueAsInt( wxPGPropArg id ) const
         { return (int)GetPropertyValueAsLong(id); }
     int GetPropertyValueAsInt( wxPGPropArg id ) const
         { return (int)GetPropertyValueAsLong(id); }

-#endif

     bool GetPropertyValueAsBool( wxPGPropArg id ) const;
     double GetPropertyValueAsDouble( wxPGPropArg id ) const;
 
     bool GetPropertyValueAsBool( wxPGPropArg id ) const;
     double GetPropertyValueAsDouble( wxPGPropArg id ) const;
 


@@ -569,7 +590,6 @@ public:
     }
 #endif
 
     }
 #endif
 

-#ifndef SWIG

     /** Returns a wxVariant list containing wxVariant versions of all
         property values. Order is not guaranteed.
         @param flags
     /** Returns a wxVariant list containing wxVariant versions of all
         property values. Order is not guaranteed.
         @param flags


@@ -585,17 +605,27 @@ public:
     {
         return m_pState->DoGetPropertyValues(listname, baseparent, flags);
     }
     {
         return m_pState->DoGetPropertyValues(listname, baseparent, flags);
     }

-#endif

 
 

-    /** Returns currently selected property. */
-    wxPGProperty* GetSelection() const
+    /**
+        Returns currently selected property. NULL if none.
+
+        @remarks When wxPG_EX_MULTIPLE_SELECTION extra style is used, this
+                 member function returns the focused property, that is the
+                 one which can have active editor.
+    */
+    wxPGProperty* GetSelection() const;
+
+    /**
+        Returns list of currently selected properties.
+
+        @remarks wxArrayPGProperty should be compatible with std::vector API.
+    */
+    const wxArrayPGProperty& GetSelectedProperties() const

     {
     {

-        return m_pState->GetSelection();
+        return m_pState->m_selection;

     }
 
     }
 

-#ifndef SWIG

     wxPropertyGridPageState* GetState() const { return m_pState; }
     wxPropertyGridPageState* GetState() const { return m_pState; }

-#endif

 
     /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
         which can be useful for forward-iterating through arbitrary property
 
     /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
         which can be useful for forward-iterating through arbitrary property


@@ -720,10 +750,19 @@ public:
         return ( (p->GetFlags() & wxPG_PROP_MODIFIED) ? true : false );
     }
 
         return ( (p->GetFlags() & wxPG_PROP_MODIFIED) ? true : false );
     }
 

+    /**
+        Returns true if property is selected.
+    */
+    bool IsPropertySelected( wxPGPropArg id ) const
+    {
+        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
+        return m_pState->DoIsPropertySelected(p);
+    }
+

     /**
         Returns true if property is shown (ie hideproperty with true not
         called for it).
     /**
         Returns true if property is shown (ie hideproperty with true not
         called for it).

-     */
+    */

     bool IsPropertyShown( wxPGPropArg id ) const
     {
         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
     bool IsPropertyShown( wxPGPropArg id ) const
     {
         wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)


@@ -840,13 +879,37 @@ public:
     wxString SaveEditableState( int includedStates = AllStates ) const;
 
     /**
     wxString SaveEditableState( int includedStates = AllStates ) const;
 
     /**

-        Lets user to set the strings listed in the choice dropdown of a
+        Lets user set the strings listed in the choice dropdown of a

         wxBoolProperty. Defaults are "True" and "False", so changing them to,
         say, "Yes" and "No" may be useful in some less technical applications.
     */
     static void SetBoolChoices( const wxString& trueChoice,
                                 const wxString& falseChoice );
 
         wxBoolProperty. Defaults are "True" and "False", so changing them to,
         say, "Yes" and "No" may be useful in some less technical applications.
     */
     static void SetBoolChoices( const wxString& trueChoice,
                                 const wxString& falseChoice );
 

+    /**
+        Set proportion of a auto-stretchable column. wxPG_SPLITTER_AUTO_CENTER
+        window style needs to be used to indicate that columns are auto-
+        resizable.
+
+        @returns Returns @false on failure.
+
+        @remarks You should call this for individual pages of
+                 wxPropertyGridManager (if used).
+
+        @see GetColumnProportion()
+    */
+    bool SetColumnProportion( unsigned int column, int proportion );
+
+    /**
+        Returns auto-resize proportion of the given column.
+
+        @see SetColumnProportion()
+    */
+    int GetColumnProportion( unsigned int column ) const
+    {
+        return m_pState->DoGetColumnProportion(column);
+    }
+

     /** Sets an attribute for this property.
         @param name
             Text identifier of attribute. See @ref propgrid_property_attributes.
     /** Sets an attribute for this property.
         @param name
             Text identifier of attribute. See @ref propgrid_property_attributes.


@@ -879,13 +942,14 @@ public:
         @param colour
             New background colour.
 
         @param colour
             New background colour.
 

-        @param recursively
-            If True, child properties are affected recursively. Property
-            categories are skipped if this flag is used.
+        @param flags
+            Default is wxPG_RECURSE which causes colour to be set recursively.
+            Omit this flag to only set colour for the property in question
+            and not any of its children.

     */
     void SetPropertyBackgroundColour( wxPGPropArg id,
                                       const wxColour& colour,
     */
     void SetPropertyBackgroundColour( wxPGPropArg id,
                                       const wxColour& colour,

-                                      bool recursively = true );
+                                      int flags = wxPG_RECURSE );

 
     /** Resets text and background colours of given property.
     */
 
     /** Resets text and background colours of given property.
     */


@@ -900,13 +964,14 @@ public:
         @param colour
             New background colour.
 
         @param colour
             New background colour.
 

-        @param recursively
-            If True, child properties are affected recursively. Property
-            categories are skipped if this flag is used.
+        @param flags
+            Default is wxPG_RECURSE which causes colour to be set recursively.
+            Omit this flag to only set colour for the property in question
+            and not any of its children.

     */
     void SetPropertyTextColour( wxPGPropArg id,
                                 const wxColour& col,
     */
     void SetPropertyTextColour( wxPGPropArg id,
                                 const wxColour& col,

-                                bool recursively = true );
+                                int flags = wxPG_RECURSE );

 
     /**
         Returns background colour of first cell of a property.
 
     /**
         Returns background colour of first cell of a property.


@@ -939,7 +1004,6 @@ public:
                           const wxColour& fgCol = wxNullColour,
                           const wxColour& bgCol = wxNullColour );
 
                           const wxColour& fgCol = wxNullColour,
                           const wxColour& bgCol = wxNullColour );
 

-#ifndef SWIG

     /** Sets client data (void*) of a property.
         @remarks
         This untyped client data has to be deleted manually.
     /** Sets client data (void*) of a property.
         @remarks
         This untyped client data has to be deleted manually.


@@ -967,7 +1031,6 @@ public:
         p->SetEditor(editor);
         RefreshProperty(p);
     }
         p->SetEditor(editor);
         RefreshProperty(p);
     }

-#endif

 
     /** Sets editor control of a property. As editor argument, use
         editor name string, such as "TextCtrl" or "Choice".
 
     /** Sets editor control of a property. As editor argument, use
         editor name string, such as "TextCtrl" or "Choice".


@@ -1025,14 +1088,11 @@ public:
     void SetPropertyValueUnspecified( wxPGPropArg id )
     {
         wxPG_PROP_ARG_CALL_PROLOG()
     void SetPropertyValueUnspecified( wxPGPropArg id )
     {
         wxPG_PROP_ARG_CALL_PROLOG()

-        wxVariant nullVariant;
-        SetPropVal(p, nullVariant);
+        p->SetValueToUnspecified();

     }
 
     }
 

-#ifndef SWIG
-    /** Sets various property values from a list of wxVariants. If property with
-        name is missing from the grid, new property is created under given
-        default category (or root if omitted).
+    /**
+        Sets property values from a list of wxVariants.

     */
     void SetPropertyValues( const wxVariantList& list,
                             wxPGPropArg defaultCategory = wxNullProperty )
     */
     void SetPropertyValues( const wxVariantList& list,
                             wxPGPropArg defaultCategory = wxNullProperty )


@@ -1043,12 +1103,14 @@ public:
         m_pState->DoSetPropertyValues(list, p);
     }
 
         m_pState->DoSetPropertyValues(list, p);
     }
 

+    /**
+        Sets property values from a list of wxVariants.
+    */

     void SetPropertyValues( const wxVariant& list,
                             wxPGPropArg defaultCategory = wxNullProperty )
     {
         SetPropertyValues(list.GetList(),defaultCategory);
     }
     void SetPropertyValues( const wxVariant& list,
                             wxPGPropArg defaultCategory = wxNullProperty )
     {
         SetPropertyValues(list.GetList(),defaultCategory);
     }

-#endif

 
     /** Associates the help string with property.
         @remarks
 
     /** Associates the help string with property.
         @remarks


@@ -1089,7 +1151,6 @@ public:
     }
 #endif
 
     }
 #endif
 

-#ifndef SWIG

     /** Sets value (long integer) of a property.
     */
     void SetPropertyValue( wxPGPropArg id, long value )
     /** Sets value (long integer) of a property.
     */
     void SetPropertyValue( wxPGPropArg id, long value )


@@ -1119,12 +1180,10 @@ public:
         wxVariant v(value);
         SetPropVal( id, v );
     }
         wxVariant v(value);
         SetPropVal( id, v );
     }

-#if wxUSE_WCHAR_T

     void SetPropertyValue( wxPGPropArg id, const wchar_t* value )
     {
         SetPropertyValueString( id, wxString(value) );
     }
     void SetPropertyValue( wxPGPropArg id, const wchar_t* value )
     {
         SetPropertyValueString( id, wxString(value) );
     }

-#endif

     void SetPropertyValue( wxPGPropArg id, const char* value )
     {
         SetPropertyValueString( id, wxString(value) );
     void SetPropertyValue( wxPGPropArg id, const char* value )
     {
         SetPropertyValueString( id, wxString(value) );


@@ -1188,7 +1247,6 @@ public:
         wxVariant v = WXVARIANT(value);
         SetPropVal( id, v );
     }
         wxVariant v = WXVARIANT(value);
         SetPropVal( id, v );
     }

-#endif  // !SWIG

 
     /** Sets value (wxString) of a property.
 
 
     /** Sets value (wxString) of a property.
 


@@ -1210,11 +1268,9 @@ public:
         SetPropVal( id, value );
     }
 
         SetPropVal( id, value );
     }
 

-#ifndef SWIG

     /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but
         accepts reference. */
     void SetPropVal( wxPGPropArg id, wxVariant& value );
     /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but
         accepts reference. */
     void SetPropVal( wxPGPropArg id, wxVariant& value );

-#endif

 
     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
         in a property.
 
     /** Adjusts how wxPropertyGrid behaves when invalid value is entered
         in a property.


@@ -1259,10 +1315,16 @@ public:
 
     static wxPGEditor* GetEditorByName( const wxString& editorName );
 
 
     static wxPGEditor* GetEditorByName( const wxString& editorName );
 

+    // NOTE: This function reselects the property and may cause
+    //       excess flicker, so to just call Refresh() on a rect
+    //       of single property, call DrawItem() instead.

     virtual void RefreshProperty( wxPGProperty* p ) = 0;
 
 protected:
 
     virtual void RefreshProperty( wxPGProperty* p ) = 0;
 
 protected:
 

+    bool DoClearSelection( bool validation = false,
+                           int selFlags = 0 );
+

     /**
         In derived class, implement to set editable state component with
         given name to given value.
     /**
         In derived class, implement to set editable state component with
         given name to given value.


@@ -1297,8 +1359,6 @@ protected:
     // Default call's m_pState's BaseGetPropertyByName
     virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
 
     // Default call's m_pState's BaseGetPropertyByName
     virtual wxPGProperty* DoGetPropertyByName( const wxString& name ) const;
 

-#ifndef SWIG
-

     // Deriving classes must set this (it must be only or current page).
     wxPropertyGridPageState*         m_pState;
 
     // Deriving classes must set this (it must be only or current page).
     wxPropertyGridPageState*         m_pState;
 


@@ -1315,15 +1375,19 @@ private:
     // Cannot be GetGrid() due to ambiguity issues.
     wxPropertyGrid* GetPropertyGrid()
     {
     // Cannot be GetGrid() due to ambiguity issues.
     wxPropertyGrid* GetPropertyGrid()
     {

+        if ( !m_pState )
+            return NULL;

         return m_pState->GetGrid();
     }
 
     // Cannot be GetGrid() due to ambiguity issues.
     const wxPropertyGrid* GetPropertyGrid() const
     {
         return m_pState->GetGrid();
     }
 
     // Cannot be GetGrid() due to ambiguity issues.
     const wxPropertyGrid* GetPropertyGrid() const
     {

-        return (const wxPropertyGrid*) m_pState->GetGrid();
+        if ( !m_pState )
+            return NULL;
+
+        return m_pState->GetGrid();

     }
     }

-#endif // #ifndef SWIG

 
     friend class wxPropertyGrid;
     friend class wxPropertyGridManager;
 
     friend class wxPropertyGrid;
     friend class wxPropertyGridManager;