No changes, just remove functions bodies from interface docs.

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

diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h
index aa3379626676f76db5d113a33e47189fdd912f12..3ab534149fa482c945b3af3eaf66c52b5367743f 100644 (file)
--- a/interface/wx/propgrid/propgrid.h
+++ b/interface/wx/propgrid/propgrid.h
@@ -3,7 +3,7 @@
 // Purpose:     interface of wxPropertyGrid
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Purpose:     interface of wxPropertyGrid
 // Author:      wxWidgets team
 // RCS-ID:      $Id$

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

 /////////////////////////////////////////////////////////////////////////////
 
 
 /////////////////////////////////////////////////////////////////////////////
 
 


@@ -45,7 +45,7 @@ wxPG_BOLD_MODIFIED                  = 0x00000040,
 
 /**
     When wxPropertyGrid is resized, splitter moves to the center. This
 
 /**
     When wxPropertyGrid is resized, splitter moves to the center. This

-    behavior stops once the user manually moves the splitter.
+    behaviour stops once the user manually moves the splitter.

 */
 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
 
 */
 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
 


@@ -89,7 +89,12 @@ wxPG_TOOLBAR                        = 0x00001000,
     wxPropertyGridManager only: Show adjustable text box showing description
     or help text, if available, for currently selected property.
 */
     wxPropertyGridManager only: Show adjustable text box showing description
     or help text, if available, for currently selected property.
 */

-wxPG_DESCRIPTION                    = 0x00002000
+wxPG_DESCRIPTION                    = 0x00002000,
+
+/** wxPropertyGridManager only: don't show an internal border around the
+    property grid. Recommended if you use a header.
+*/
+wxPG_NO_INTERNAL_BORDER             = 0x00004000

 
 };
 
 
 };
 


@@ -152,17 +157,51 @@ wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 /**
     Hides page selection buttons from tool bar.
 */
 /**
     Hides page selection buttons from tool bar.
 */

-wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000
+wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000,
+
+/** Allows multiple properties to be selected by user (by pressing SHIFT
+    when clicking on a property, or by dragging with left mouse button
+    down).
+
+    You can get array of selected properties with
+    wxPropertyGridInterface::GetSelectedProperties(). In multiple selection
+    mode wxPropertyGridInterface::GetSelection() returns
+    property which has editor active (usually the first one
+    selected). Other useful member functions are ClearSelection(),
+    AddToSelection() and RemoveFromSelection().
+*/
+wxPG_EX_MULTIPLE_SELECTION              = 0x02000000,
+
+/**
+    This enables top-level window tracking which allows wxPropertyGrid to
+    notify the application of last-minute property value changes by user.
+
+    This style is not enabled by default because it may cause crashes when
+    wxPropertyGrid is used in with wxAUI or similar system.
+
+    @remarks If you are not in fact using any system that may change
+             wxPropertyGrid's top-level parent window on its own, then you
+             are recommended to enable this style.
+*/
+wxPG_EX_ENABLE_TLP_TRACKING             = 0x04000000,
+
+/** Don't show divider above toolbar, on Windows.
+*/
+wxPG_EX_NO_TOOLBAR_DIVIDER              = 0x04000000,
+
+/** Show a separator below the toolbar.
+*/
+wxPG_EX_TOOLBAR_SEPARATOR               = 0x08000000

 
 };
 
 /** Combines various styles.
 */
 
 };
 
 /** Combines various styles.
 */

-#define wxPG_DEFAULT_STYLE             (0)
+#define wxPG_DEFAULT_STYLE          (0)

 
 /** Combines various styles.
 */
 
 /** Combines various styles.
 */

-#define wxPGMAN_DEFAULT_STYLE      (0)
+#define wxPGMAN_DEFAULT_STYLE       (0)

 
 /** @}
 */
 
 /** @}
 */


@@ -170,7 +209,7 @@ wxPG_EX_HIDE_PAGE_BUTTONS               = 0x01000000
 // -----------------------------------------------------------------------
 
 /**
 // -----------------------------------------------------------------------
 
 /**

-    @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags
+    @section propgrid_vfbflags wxPropertyGrid Validation Failure behaviour Flags

     @{
 */
 
     @{
 */
 


@@ -179,7 +218,7 @@ enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
 
 /**
     Prevents user from leaving property unless value is valid. If this
 
 /**
     Prevents user from leaving property unless value is valid. If this

-    behavior flag is not used, then value change is instead cancelled.
+    behaviour flag is not used, then value change is instead cancelled.

 */
 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 
 */
 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 


@@ -194,14 +233,35 @@ wxPG_VFB_BEEP                       = 0x02,
 wxPG_VFB_MARK_CELL                  = 0x04,
 
 /**
 wxPG_VFB_MARK_CELL                  = 0x04,
 
 /**

-    Display customizable text message explaining the situation.
+    Display a text message explaining the situation.
+
+    To customize the way the message is displayed, you need to
+    reimplement wxPropertyGrid::DoShowPropertyError() in a
+    derived class. Default behaviour is to display the text on
+    the top-level frame's status bar, if present, and otherwise
+    using wxMessageBox.

 */
 wxPG_VFB_SHOW_MESSAGE               = 0x08,
 
 */
 wxPG_VFB_SHOW_MESSAGE               = 0x08,
 

+/**
+    Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
+    message using wxMessageBox.
+*/
+wxPG_VFB_SHOW_MESSAGEBOX            = 0x10,
+
+/**
+    Similar to wxPG_VFB_SHOW_MESSAGE, except always displays the
+    message on the status bar (when present - you can reimplement
+    wxPropertyGrid::GetStatusBar() in a derived class to specify
+    this yourself).
+*/
+wxPG_VFB_SHOW_MESSAGE_ON_STATUSBAR  = 0x20,
+

 /**
     Defaults.
 */
 /**
     Defaults.
 */

-wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
+wxPG_VFB_DEFAULT                    = wxPG_VFB_MARK_CELL |
+                                      wxPG_VFB_SHOW_MESSAGEBOX,

 };
 
 /** @}
 };
 
 /** @}


@@ -219,7 +279,7 @@ class wxPGValidationInfo
 {
 public:
     /**
 {
 public:
     /**

-        @return Returns failure behavior which is a combination of
+        @return Returns failure behaviour which is a combination of

             @ref propgrid_vfbflags.
     */
     wxPGVFBFlags GetFailureBehavior();
             @ref propgrid_vfbflags.
     */
     wxPGVFBFlags GetFailureBehavior();


@@ -232,9 +292,9 @@ public:
     /**
         Returns reference to pending value.
     */
     /**
         Returns reference to pending value.
     */

-    const wxVariant& GetValue() const;
+    wxVariant& GetValue();

 
 

-    /** Set validation failure behavior
+    /** Set validation failure behaviour

 
         @param failureBehavior
             Mixture of @ref propgrid_vfbflags.
 
         @param failureBehavior
             Mixture of @ref propgrid_vfbflags.


@@ -260,17 +320,59 @@ public:
 enum wxPG_KEYBOARD_ACTIONS
 {
     wxPG_ACTION_INVALID = 0,
 enum wxPG_KEYBOARD_ACTIONS
 {
     wxPG_ACTION_INVALID = 0,

+
+    /** Select the next property. */

     wxPG_ACTION_NEXT_PROPERTY,
     wxPG_ACTION_NEXT_PROPERTY,

+
+    /** Select the previous property. */

     wxPG_ACTION_PREV_PROPERTY,
     wxPG_ACTION_PREV_PROPERTY,

+
+    /** Expand the selected property, if it has child items. */

     wxPG_ACTION_EXPAND_PROPERTY,
     wxPG_ACTION_EXPAND_PROPERTY,

+
+    /** Collapse the selected property, if it has child items. */

     wxPG_ACTION_COLLAPSE_PROPERTY,
     wxPG_ACTION_COLLAPSE_PROPERTY,

+
+    /** Cancel and undo any editing done in the currently active property
+        editor.
+    */

     wxPG_ACTION_CANCEL_EDIT,
     wxPG_ACTION_CANCEL_EDIT,

+
+    /** Move focus to the editor control of the currently selected
+        property.
+    */
+    wxPG_ACTION_EDIT,
+
+    /** Causes editor's button (if any) to be pressed. */
+    wxPG_ACTION_PRESS_BUTTON,
+

     wxPG_ACTION_MAX
 };
 
 /** @}
 */
 
     wxPG_ACTION_MAX
 };
 
 /** @}
 */
 

+/** This callback function is used for sorting properties.
+
+    Call wxPropertyGrid::SetSortFunction() to set it.
+
+    Sort function should return a value greater than 0 if position of p1 is
+    after p2. So, for instance, when comparing property names, you can use
+    following implementation:
+
+        @code
+            int MyPropertySortFunction(wxPropertyGrid* propGrid,
+                                       wxPGProperty* p1,
+                                       wxPGProperty* p2)
+            {
+                return p1->GetBaseName().compare( p2->GetBaseName() );
+            }
+        @endcode
+*/
+typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
+                                wxPGProperty* p1,
+                                wxPGProperty* p2);
+

 // -----------------------------------------------------------------------
 
 /**
 // -----------------------------------------------------------------------
 
 /**


@@ -297,31 +399,56 @@ enum wxPG_KEYBOARD_ACTIONS
     To process input from a property grid control, use these event handler macros
     to direct input to member functions that take a wxPropertyGridEvent argument.
 
     To process input from a property grid control, use these event handler macros
     to direct input to member functions that take a wxPropertyGridEvent argument.
 

-    @beginEventTable{wxPropertyGridEvent}
+    @beginEventEmissionTable{wxPropertyGridEvent}

     @event{EVT_PG_SELECTED (id, func)}
     @event{EVT_PG_SELECTED (id, func)}

-        Respond to wxEVT_PG_SELECTED event, generated when property value
-        has been changed by user.
+        Respond to @c wxEVT_PG_SELECTED event, generated when a property selection
+        has been changed, either by user action or by indirect program
+        function. For instance, collapsing a parent property programmatically
+        causes any selected child property to become unselected, and may
+        therefore cause this event to be generated.
+    @event{EVT_PG_CHANGED(id, func)}
+        Respond to @c wxEVT_PG_CHANGED event, generated when property value
+        has been changed by the user.

     @event{EVT_PG_CHANGING(id, func)}
     @event{EVT_PG_CHANGING(id, func)}

-        Respond to wxEVT_PG_CHANGING event, generated when property value
+        Respond to @c wxEVT_PG_CHANGING event, generated when property value

         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
         to take a peek at the pending value, and wxPropertyGridEvent::Veto()
         to prevent change from taking place, if necessary.
     @event{EVT_PG_HIGHLIGHTED(id, func)}
         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
         to take a peek at the pending value, and wxPropertyGridEvent::Veto()
         to prevent change from taking place, if necessary.
     @event{EVT_PG_HIGHLIGHTED(id, func)}

-        Respond to wxEVT_PG_HIGHLIGHTED event, which occurs when mouse
+        Respond to @c wxEVT_PG_HIGHLIGHTED event, which occurs when mouse

         moves over a property. Event's property is NULL if hovered area does
         not belong to any property.
     @event{EVT_PG_RIGHT_CLICK(id, func)}
         moves over a property. Event's property is NULL if hovered area does
         not belong to any property.
     @event{EVT_PG_RIGHT_CLICK(id, func)}

-        Respond to wxEVT_PG_RIGHT_CLICK event, which occurs when property is
+        Respond to @c wxEVT_PG_RIGHT_CLICK event, which occurs when property is

         clicked on with right mouse button.
     @event{EVT_PG_DOUBLE_CLICK(id, func)}
         clicked on with right mouse button.
     @event{EVT_PG_DOUBLE_CLICK(id, func)}

-        Respond to wxEVT_PG_DOUBLE_CLICK event, which occurs when property is
+        Respond to @c wxEVT_PG_DOUBLE_CLICK event, which occurs when property is

         double-clicked on with left mouse button.
     @event{EVT_PG_ITEM_COLLAPSED(id, func)}
         double-clicked on with left mouse button.
     @event{EVT_PG_ITEM_COLLAPSED(id, func)}

-        Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses
+        Respond to @c wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses

         a property or category.
     @event{EVT_PG_ITEM_EXPANDED(id, func)}
         a property or category.
     @event{EVT_PG_ITEM_EXPANDED(id, func)}

-        Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
+        Respond to @c wxEVT_PG_ITEM_EXPANDED event, generated when user expands

         a property or category.
         a property or category.

+    @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
+        Respond to @c wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is
+        about to begin editing a property label. You can veto this event to
+        prevent the action.
+    @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}
+        Respond to @c wxEVT_PG_LABEL_EDIT_ENDING event, generated when user is
+        about to end editing of a property label. You can veto this event to
+        prevent the action.
+    @event{EVT_PG_COL_BEGIN_DRAG(id, func)}
+        Respond to @c wxEVT_PG_COL_BEGIN_DRAG event, generated when user
+        starts resizing a column - can be vetoed.
+    @event{EVT_PG_COL_DRAGGING,(id, func)}
+        Respond to @c wxEVT_PG_COL_DRAGGING, event, generated when a
+        column resize by user is in progress. This event is also generated
+        when user double-clicks the splitter in order to recenter
+        it.
+    @event{EVT_PG_COL_END_DRAG(id, func)}
+        Respond to @c wxEVT_PG_COL_END_DRAG event, generated after column
+        resize by user has finished.

     @endEventTable
 
     @remarks
     @endEventTable
 
     @remarks


@@ -333,7 +460,9 @@ enum wxPG_KEYBOARD_ACTIONS
     @category{propgrid}
     @appearance{propertygrid.png}
 */
     @category{propgrid}
     @appearance{propertygrid.png}
 */

-class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
+class wxPropertyGrid : public wxControl,
+                       public wxScrollHelper,
+                       public wxPropertyGridInterface

 {
 public:
     /**
 {
 public:
     /**


@@ -344,7 +473,7 @@ public:
 
     /**
         Constructor.
 
     /**
         Constructor.

-        The styles to be used are styles valid for the wxWindow and wxScrolledWindow.
+        The styles to be used are styles valid for the wxWindow.

 
         @see @ref propgrid_window_styles.
     */
 
         @see @ref propgrid_window_styles.
     */


@@ -352,7 +481,7 @@ public:
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxPG_DEFAULT_STYLE,
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxPG_DEFAULT_STYLE,

-                    const wxChar* name = wxPropertyGridNameStr );
+                    const wxString& name = wxPropertyGridNameStr );

 
     /** Destructor */
     virtual ~wxPropertyGrid();
 
     /** Destructor */
     virtual ~wxPropertyGrid();


@@ -360,6 +489,15 @@ public:
     /**
         Adds given key combination to trigger given action.
 
     /**
         Adds given key combination to trigger given action.
 

+        Here is a sample code to make Enter key press move focus to
+        the next property.
+
+        @code
+            propGrid->AddActionTrigger(wxPG_ACTION_NEXT_PROPERTY,
+                                       WXK_RETURN);
+            propGrid->DedicateKey(WXK_RETURN);
+        @endcode
+

         @param action
             Which action to trigger. See @ref propgrid_keyboard_actions.
         @param keycode
         @param action
             Which action to trigger. See @ref propgrid_keyboard_actions.
         @param keycode


@@ -370,6 +508,20 @@ public:
     */
     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 
     */
     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 

+    /**
+        Adds given property into selection. If wxPG_EX_MULTIPLE_SELECTION
+        extra style is not used, then this has same effect as
+        calling SelectProperty().
+
+        @remarks Multiple selection is not supported for categories. This
+                 means that if you have properties selected, you cannot
+                 add category to selection, and also if you have category
+                 selected, you cannot add other properties to selection.
+                 This member function will fail silently in these cases,
+                 even returning true.
+    */
+    bool AddToSelection( wxPGPropArg id );
+

     /**
         This static function enables or disables automatic use of
         wxGetTranslation() for following strings: wxEnumProperty list labels,
     /**
         This static function enables or disables automatic use of
         wxGetTranslation() for following strings: wxEnumProperty list labels,


@@ -379,6 +531,21 @@ public:
     */
     static void AutoGetTranslation( bool enable );
 
     */
     static void AutoGetTranslation( bool enable );
 

+    /**
+        Creates label editor wxTextCtrl for given column, for property
+        that is currently selected. When multiple selection is
+        enabled, this applies to whatever property GetSelection()
+        returns.
+
+        @param colIndex
+            Which column's label to edit. Note that you should not
+            use value 1, which is reserved for property value
+            column.
+
+        @see EndLabelEdit(), MakeColumnEditable()
+    */
+    void BeginLabelEdit( unsigned int colIndex = 0 );
+

     /**
         Changes value of a property, as if from an editor. Use this instead of
         SetPropertyValue() if you need the value to run through validation
     /**
         Changes value of a property, as if from an editor. Use this instead of
         SetPropertyValue() if you need the value to run through validation


@@ -389,11 +556,13 @@ public:
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**
     bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue );
 
     /**

-        Centers the splitter. If argument is true, automatic splitter centering
-        is enabled (only applicable if style wxPG_SPLITTER_AUTO_CENTER was
-        defined).
+        Centers the splitter.
+
+        @param enableAutoResizing
+            If @true, automatic column resizing is enabled (only applicapple
+            if window style wxPG_SPLITTER_AUTO_CENTER is used).

     */
     */

-    void CenterSplitter( bool enable_auto_centering = false );
+    void CenterSplitter( bool enableAutoResizing = false );

 
     /**
         Deletes all properties.
 
     /**
         Deletes all properties.


@@ -410,7 +579,7 @@ public:
 
     /**
         Forces updating the value of property from the editor control.
 
     /**
         Forces updating the value of property from the editor control.

-        Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
+        Note that @c wxEVT_PG_CHANGING and @c wxEVT_PG_CHANGED are dispatched using

         ProcessEvent, meaning your event handlers will be called immediately.
 
         @return Returns @true if anything was changed.
         ProcessEvent, meaning your event handlers will be called immediately.
 
         @return Returns @true if anything was changed.


@@ -428,25 +597,17 @@ public:
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxPG_DEFAULT_STYLE,
                 const wxPoint& pos = wxDefaultPosition,
                 const wxSize& size = wxDefaultSize,
                 long style = wxPG_DEFAULT_STYLE,

-                const wxChar* name = wxPropertyGridNameStr );
-
-    /**
-        Call when editor widget's contents is modified. For example, this is
-        called when changes text in wxTextCtrl (used in wxStringProperty and
-        wxIntProperty).
-
-        @remarks This function should only be called by custom properties.
-
-        @see wxPGProperty::OnEvent()
-    */
-    void EditorsValueWasModified();
+                const wxString& name = wxPropertyGridNameStr );

 
     /**
 
     /**

-        Reverse of EditorsValueWasModified().
+        Dedicates a specific keycode to wxPropertyGrid. This means that such
+        key presses will not be redirected to editor controls.

 
 

-        @remarks This function should only be called by custom properties.
+        Using this function allows, for example, navigation between
+        properties using arrow keys even when the focus is in the editor
+        control.

     */
     */

-    void EditorsValueWasNotModified();
+    void DedicateKey( int keycode );

 
     /**
         Enables or disables (shows/hides) categories according to parameter
 
     /**
         Enables or disables (shows/hides) categories according to parameter


@@ -458,6 +619,17 @@ public:
     */
     bool EnableCategories( bool enable );
 
     */
     bool EnableCategories( bool enable );
 

+    /**
+        Destroys label editor wxTextCtrl, if any.
+
+        @param commit
+            Use @true (default) to store edited label text in
+            property cell data.
+
+        @see BeginLabelEdit(), MakeColumnEditable()
+    */
+    void EndLabelEdit( bool commit = true );
+

     /**
         Scrolls and/or expands items to ensure that the given item is visible.
 
     /**
         Scrolls and/or expands items to ensure that the given item is visible.
 


@@ -482,11 +654,16 @@ public:
     */
     wxSize FitColumns();
 
     */
     wxSize FitColumns();
 

+    /**
+        Returns currently active label editor, NULL if none.
+    */
+    wxTextCtrl* GetLabelEditor() const;
+

     /**
         Returns wxWindow that the properties are painted on, and which should be
         used as the parent for editor controls.
     */
     /**
         Returns wxWindow that the properties are painted on, and which should be
         used as the parent for editor controls.
     */

-    wxPanel* GetPanel() const;
+    wxWindow* GetPanel();

 
     /**
         Returns current category caption background colour.
 
     /**
         Returns current category caption background colour.


@@ -582,14 +759,6 @@ public:
     */
     wxColour GetMarginColour() const;
 
     */
     wxColour GetMarginColour() const;
 

-    /**
-        Returns most up-to-date value of selected property. This will return
-        value different from GetSelectedProperty()->GetValue() only when text
-        editor is activate and string edited by user represents valid,
-        uncommitted property value.
-    */
-    wxVariant GetUncommittedPropertyValue();
-

     /**
         Returns "root property". It does not have name, etc. and it is not
         visible. It is only useful for accessing its children.
     /**
         Returns "root property". It does not have name, etc. and it is not
         visible. It is only useful for accessing its children.


@@ -621,10 +790,17 @@ public:
     */
     wxColour GetSelectionForegroundColour() const;
 
     */
     wxColour GetSelectionForegroundColour() const;
 

+    /**
+        Returns the property sort function (default is @NULL).
+
+        @see SetSortFunction
+    */
+    wxPGSortCallback GetSortFunction() const;
+

     /**
         Returns current splitter x position.
     */
     /**
         Returns current splitter x position.
     */

-    int GetSplitterPosition() const;
+    int GetSplitterPosition( unsigned int splitterIndex = 0 ) const;

 
     /**
         Returns wxTextCtrl active in currently selected property, if any. Takes
 
     /**
         Returns wxTextCtrl active in currently selected property, if any. Takes


@@ -633,17 +809,33 @@ public:
     wxTextCtrl* GetEditorTextCtrl() const;
 
     /**
     wxTextCtrl* GetEditorTextCtrl() const;
 
     /**

-        Returns current vertical spacing.
+        Returns current appearance of unspecified value cells.
+
+        @see SetUnspecifiedValueAppearance()

     */
     */

-    int GetVerticalSpacing() const;
+    const wxPGCell& GetUnspecifiedValueAppearance() const;

 
     /**
 
     /**

-        Returns true if editor's value was marked modified.
+        Returns (visual) text representation of the unspecified
+        property value.
+
+        @param argFlags For internal use only.

     */
     */

-    bool IsEditorsValueModified() const;
+    wxString GetUnspecifiedValueText( int argFlags = 0 ) const;
+
+    /**
+        Returns current vertical spacing.
+    */
+    int GetVerticalSpacing() const;

 
     /**
         Returns information about arbitrary position in the grid.
 
     /**
         Returns information about arbitrary position in the grid.

+
+        @param pt
+            Coordinates in the virtual grid space. You may need to use
+            wxScrolled<T>::CalcScrolledPosition() for translating
+            wxPropertyGrid client coordinates into something this member
+            function can use.

     */
     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 
     */
     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 


@@ -652,12 +844,44 @@ public:
     */
     bool IsAnyModified() const;
 
     */
     bool IsAnyModified() const;
 

+    /**
+        Returns @true if a property editor control has focus.
+    */
+    bool IsEditorFocused() const;
+

     /**
         Returns true if updating is frozen (ie. Freeze() called but not
         yet Thaw() ).
     */
     bool IsFrozen() const;
 
     /**
         Returns true if updating is frozen (ie. Freeze() called but not
         yet Thaw() ).
     */
     bool IsFrozen() const;
 

+    /**
+        Makes given column editable by user.
+
+        @param column
+            The index of the column to make editable.
+        @param editable
+            Using @false here will disable column from being editable.
+
+        @see BeginLabelEdit(), EndLabelEdit()
+    */
+    void MakeColumnEditable( unsigned int column, bool editable = true );
+
+    /**
+        It is recommended that you call this function any time your code causes
+        wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
+        handler should be able to detect most changes, but it is not perfect.
+
+        @param newTLP
+            New top-level parent that is about to be set. Old top-level parent
+            window should still exist as the current one.
+
+        @remarks This function is automatically called from wxPropertyGrid::
+                 Reparent() and wxPropertyGridManager::Reparent(). You only
+                 need to use it if you reparent wxPropertyGrid indirectly.
+    */
+    void OnTLPChanging( wxWindow* newTLP );
+

     /**
         Refreshes any active editor control.
     */
     /**
         Refreshes any active editor control.
     */


@@ -668,12 +892,16 @@ public:
     */
     virtual void RefreshProperty( wxPGProperty* p );
 
     */
     virtual void RefreshProperty( wxPGProperty* p );
 

+
+    /** Forwards to DoRegisterEditorClass with empty name. */
+    static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
+                                            bool noDefCheck = false );

     /**
         Registers a new editor class.
 
         @return Returns pointer  to the editor class instance that should be used.
     */
     /**
         Registers a new editor class.
 
         @return Returns pointer  to the editor class instance that should be used.
     */

-    static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
+    static wxPGEditor* DoRegisterEditorClass( wxPGEditor* editor,

                                             const wxString& name,
                                             bool noDefCheck = false );
 
                                             const wxString& name,
                                             bool noDefCheck = false );
 


@@ -682,10 +910,26 @@ public:
     */
     void ResetColours();
 
     */
     void ResetColours();
 

+    /**
+        Resets column sizes and splitter positions, based on proportions.
+
+        @param enableAutoResizing
+            If @true, automatic column resizing is enabled (only applicapple
+            if window style wxPG_SPLITTER_AUTO_CENTER is used).
+
+        @see wxPropertyGridInterface::SetColumnProportion()
+    */
+    void ResetColumnSizes( bool enableAutoResizing = false );
+
+    /**
+        Removes given property from selection. If property is not selected,
+        an assertion failure will occur.
+    */
+    bool RemoveFromSelection( wxPGPropArg id );
+

     /**
         Selects a property. Editor widget is automatically created, but
     /**
         Selects a property. Editor widget is automatically created, but

-        not focused unless focus is true. This will generate wxEVT_PG_SELECT
-        event.
+        not focused unless focus is true.

 
         @param id
             Property to select (name or pointer).
 
         @param id
             Property to select (name or pointer).


@@ -696,17 +940,15 @@ public:
         @return returns @true if selection finished successfully. Usually only
         fails if current value in editor is not valid.
 
         @return returns @true if selection finished successfully. Usually only
         fails if current value in editor is not valid.
 

-        @see wxPropertyGrid::ClearSelection()
-    */
-    bool SelectProperty( wxPGPropArg id, bool focus = false );
+        @remarks In wxPropertyGrid 1.4, this member function used to generate
+                 @c wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
+                 does that.

 
 

-    /**
-        Changes keyboard shortcut to push the editor button.
+        @remarks This clears any previous selection.

 
 

-        @remarks You can set default with keycode 0. Good value for the platform
-                is guessed, but don't expect it to be very accurate.
+        @see wxPropertyGridInterface::ClearSelection()

     */
     */

-    void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
+    bool SelectProperty( wxPGPropArg id, bool focus = false );

 
     /**
         Sets category caption background colour.
 
     /**
         Sets category caption background colour.


@@ -761,6 +1003,11 @@ public:
     */
     void SetMarginColour(const wxColour& col);
 
     */
     void SetMarginColour(const wxColour& col);
 

+    /**
+        Set entire new selection from given list of properties.
+    */
+    void SetSelection( const wxArrayPGProperty& newSelection );
+

     /**
         Sets selection background colour - applies to selected property name
         background.
     /**
         Sets selection background colour - applies to selected property name
         background.


@@ -772,6 +1019,33 @@ public:
     */
     void SetSelectionTextColour(const wxColour& col);
 
     */
     void SetSelectionTextColour(const wxColour& col);
 

+
+    /**
+        Sets the property sorting function.
+
+        @param sortFunction
+            The sorting function to be used. It should return a value greater
+            than 0 if position of p1 is after p2. So, for instance, when
+            comparing property names, you can use following implementation:
+
+            @code
+                int MyPropertySortFunction(wxPropertyGrid* propGrid,
+                                           wxPGProperty* p1,
+                                           wxPGProperty* p2)
+                {
+                    return p1->GetBaseName().compare( p2->GetBaseName() );
+                }
+            @endcode
+
+        @remarks
+            Default property sort function sorts properties by their labels
+            (case-insensitively).
+
+        @see GetSortFunction, wxPropertyGridInterface::Sort,
+             wxPropertyGridInterface::SortChildren
+    */
+    void SetSortFunction( wxPGSortCallback sortFunction );
+

     /**
         Sets x coordinate of the splitter.
 
     /**
         Sets x coordinate of the splitter.
 


@@ -791,6 +1065,19 @@ public:
     */
     void SetSplitterLeft( bool privateChildrenToo = false );
 
     */
     void SetSplitterLeft( bool privateChildrenToo = false );
 

+    /**
+        Sets appearance of value cells representing an unspecified property
+        value. Default appearance is blank.
+
+        @remarks If you set the unspecified value to have any
+                 textual representation, then that will override
+                 "InlineHelp" attribute.
+
+        @see wxPGProperty::SetValueToUnspecified(),
+             wxPGProperty::IsValueUnspecified()
+    */
+    void SetUnspecifiedValueAppearance( const wxPGCell& cell );
+

     /**
         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
         height. Value of 2 should be default on most platforms.
     /**
         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
         height. Value of 2 should be default on most platforms.


@@ -798,27 +1085,102 @@ public:
     void SetVerticalSpacing( int vspacing );
 
     /**
     void SetVerticalSpacing( int vspacing );
 
     /**

-        Shows an brief error message that is related to a property.
+        @name wxPropertyGrid customization
+
+        Reimplement these member functions in derived class for better
+        control over wxPropertyGrid behaviour.

     */
     */

-    void ShowPropertyError( wxPGPropArg id, const wxString& msg );
+    //@{

 
     /**
 
     /**

-        Sorts all items at all levels (except private children).
+        Override in derived class to display error messages in custom manner
+        (these message usually only result from validation failure).

 
 

-        @remarks 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.
+        @remarks If you implement this, then you also need to implement
+                 DoHidePropertyError() - possibly to do nothing, if error
+                 does not need hiding (e.g. it was logged or shown in a
+                 message box).
+
+        @see DoHidePropertyError()

     */
     */

-    void Sort();
+    virtual void DoShowPropertyError( wxPGProperty* property,
+                                      const wxString& msg );

 
     /**
 
     /**

-        Sorts children of a property.
+        Override in derived class to hide an error displayed by
+        DoShowPropertyError().

 
 

-        @remarks 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.
+        @see DoShowPropertyError()
+    */
+    virtual void DoHidePropertyError( wxPGProperty* property );
+
+    /**
+        Return wxStatusBar that is used by this wxPropertyGrid. You can
+        reimplement this member function in derived class to override
+        the default behaviour of using the top-level wxFrame's status
+        bar, if any.

     */
     */

-    void SortChildren( wxPGPropArg id );
+    virtual wxStatusBar* GetStatusBar();
+
+    //@}
+
+    /**
+        @name Property development functions
+
+        These member functions are usually only called when creating custom
+        user properties.
+    */
+    //@{
+
+    /**
+        Call when editor widget's contents is modified. For example, this is
+        called when changes text in wxTextCtrl (used in wxStringProperty and
+        wxIntProperty).
+
+        @remarks This function should only be called by custom properties.
+
+        @see wxPGProperty::OnEvent()
+    */
+    void EditorsValueWasModified();
+
+    /**
+        Reverse of EditorsValueWasModified().
+
+        @remarks This function should only be called by custom properties.
+    */
+    void EditorsValueWasNotModified();
+
+    /**
+        Returns most up-to-date value of selected property. This will return
+        value different from GetSelectedProperty()->GetValue() only when text
+        editor is activate and string edited by user represents valid,
+        uncommitted property value.
+    */
+    wxVariant GetUncommittedPropertyValue();
+
+    /**
+        Returns true if editor's value was marked modified.
+    */
+    bool IsEditorsValueModified() const;
+
+    /**
+        Shows an brief error message that is related to a property.
+    */
+    void ShowPropertyError( wxPGPropArg id, const wxString& msg );
+
+    /**
+        You can use this member function, for instance, to detect in
+        wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
+        already called in wxPGEditor::OnEvent(). It really only detects
+        if was value was changed using wxPGProperty::SetValueInEvent(), which
+        is usually used when a 'picker' dialog is displayed. If value was
+        written by "normal means" in wxPGProperty::StringToValue() or
+        IntToValue(), then this function will return false (on the other hand,
+        wxPGProperty::OnEvent() is not even called in those cases).
+    */
+    bool WasValueChangedInEvent() const;
+
+    //@}

 };
 
 
 };
 
 


@@ -849,6 +1211,13 @@ public:
     */
     bool CanVeto() const;
 
     */
     bool CanVeto() const;
 

+    /**
+        Returns the column index associated with this event.
+        For the column dragging events, it is the column to the left
+        of the splitter being dragged
+    */
+    unsigned int GetColumn() const;
+

     /**
         Returns highest level non-category, non-root parent of property for
         which event occurred. Useful when you have nested properties with
     /**
         Returns highest level non-category, non-root parent of property for
         which event occurred. Useful when you have nested properties with


@@ -861,6 +1230,11 @@ public:
 
     /**
         Returns property associated with this event.
 
     /**
         Returns property associated with this event.

+
+        @remarks You should assume that this property can always be NULL.
+                 For instance, @c wxEVT_PG_SELECTED is emitted not only when
+                 a new property is selected, but also when selection is
+                 cleared by user activity.

     */
     wxPGProperty* GetProperty() const;
 
     */
     wxPGProperty* GetProperty() const;
 


@@ -870,9 +1244,30 @@ public:
     wxPGVFBFlags GetValidationFailureBehavior() const;
 
     /**
     wxPGVFBFlags GetValidationFailureBehavior() const;
 
     /**

-        Returns value that is about to be set for wxEVT_PG_CHANGING.
+        Returns name of the associated property.
+
+        @remarks Property name is stored in event, so it remains
+                 accessible even after the associated property or
+                 the property grid has been deleted.
+    */
+    wxString GetPropertyName() const;
+
+    /**
+        Returns value of the associated property. Works for all event
+        types, but for @c wxEVT_PG_CHANGING this member function returns
+        the value that is pending, so you can call Veto() if the
+        value is not satisfactory.
+
+        @remarks Property value is stored in event, so it remains
+                 accessible even after the associated property or
+                 the property grid has been deleted.
+    */
+    wxVariant GetPropertyValue() const
+
+    /**
+        @see GetPropertyValue()

     */
     */

-    const wxVariant& GetValue() const;
+    wxVariant GetValue() const;

 
     /**
         Set if event can be vetoed.
 
     /**
         Set if event can be vetoed.


@@ -883,8 +1278,8 @@ public:
     void SetProperty( wxPGProperty* p );
 
     /**
     void SetProperty( wxPGProperty* p );
 
     /**

-        Set override validation failure behavior. Only effective if Veto() was
-        also called, and only allowed if event type is wxEVT_PG_CHANGING.
+        Set override validation failure behaviour. Only effective if Veto() was
+        also called, and only allowed if event type is @c wxEVT_PG_CHANGING.

     */
     void SetValidationFailureBehavior( wxPGVFBFlags flags );
 
     */
     void SetValidationFailureBehavior( wxPGVFBFlags flags );
 


@@ -899,7 +1294,7 @@ public:
         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
         returns true.
 
         signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
         returns true.
 

-        @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
+        @remarks Currently only @c wxEVT_PG_CHANGING supports vetoing.

     */
     void Veto( bool veto = true );
 
     */
     void Veto( bool veto = true );