Allow to not create wxPaintDC in EVT_PAINT handler in wxMSW.

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

diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h
index 7ceeee2101208da59bcd59e351cc79db411d877b..6a75c9b0452f40a1d3004f5f9b6b3afe6e933315 100644 (file)
--- a/interface/wx/propgrid/propgrid.h
+++ b/interface/wx/propgrid/propgrid.h
@@ -2,7 +2,7 @@
 // Name:        propgrid.h
 // Purpose:     interface of wxPropertyGrid
 // Author:      wxWidgets team
 // Name:        propgrid.h
 // Purpose:     interface of wxPropertyGrid
 // Author:      wxWidgets team

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

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


@@ -32,7 +32,7 @@ wxPG_AUTO_SORT                      = 0x00000010,
 */
 wxPG_HIDE_CATEGORIES                = 0x00000020,
 
 */
 wxPG_HIDE_CATEGORIES                = 0x00000020,
 

-/*
+/**

     This style combines non-categoric mode and automatic sorting.
 */
 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
     This style combines non-categoric mode and automatic sorting.
 */
 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),


@@ -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

 
 };
 
 
 };
 


@@ -150,25 +155,53 @@ wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 
 /**
 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 
 /**

-    With this style Validators on properties will work same as in wxPropertyGrid
-    1.2.
+    Hides page selection buttons from tool bar.
+*/
+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_LEGACY_VALIDATORS               = 0x00800000,
+wxPG_EX_MULTIPLE_SELECTION              = 0x02000000,

 
 /**
 
 /**

-    Hides page selection buttons from tool bar.
+    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_HIDE_PAGE_BUTTONS               = 0x01000000
+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)

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


@@ -215,10 +248,49 @@ wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
 
 typedef wxByte wxPGVFBFlags;
 
 
 typedef wxByte wxPGVFBFlags;
 

+/**
+    wxPGValidationInfo
+
+    Used to convey validation information to and from functions that
+    actually perform validation. Mostly used in custom property classes.
+*/
+class wxPGValidationInfo
+{
+public:
+    /**
+        @return Returns failure behavior which is a combination of
+            @ref propgrid_vfbflags.
+    */
+    wxPGVFBFlags GetFailureBehavior();
+
+    /**
+        Returns current failure message.
+    */
+    const wxString& GetFailureMessage() const;
+
+    /**
+        Returns reference to pending value.
+    */
+    wxVariant& GetValue();
+
+    /** Set validation failure behavior
+
+        @param failureBehavior
+            Mixture of @ref propgrid_vfbflags.
+    */
+    void SetFailureBehavior(wxPGVFBFlags failureBehavior);
+
+    /**
+        Set current failure message.
+    */
+    void SetFailureMessage(const wxString& message);
+};
+

 // -----------------------------------------------------------------------
 
 /**
     @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
 // -----------------------------------------------------------------------
 
 /**
     @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers

+

     These are used with wxPropertyGrid::AddActionTrigger() and
     wxPropertyGrid::ClearActionTriggers().
     @{
     These are used with wxPropertyGrid::AddActionTrigger() and
     wxPropertyGrid::ClearActionTriggers().
     @{


@@ -232,20 +304,39 @@ enum wxPG_KEYBOARD_ACTIONS
     wxPG_ACTION_EXPAND_PROPERTY,
     wxPG_ACTION_COLLAPSE_PROPERTY,
     wxPG_ACTION_CANCEL_EDIT,
     wxPG_ACTION_EXPAND_PROPERTY,
     wxPG_ACTION_COLLAPSE_PROPERTY,
     wxPG_ACTION_CANCEL_EDIT,

-    wxPG_ACTION_CUT,
-    wxPG_ACTION_COPY,
-    wxPG_ACTION_PASTE,

     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);
+

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

-/** @class wxPropertyGrid
+/**
+    @class wxPropertyGrid

 
 

-      wxPropertyGrid is a specialized grid for editing properties - in other
+    wxPropertyGrid is a specialized grid for editing properties - in other

     words name = value pairs. List of ready-to-use property classes include
     strings, numbers, flag sets, fonts, colours and many others. It is possible,
     for example, to categorize properties, set up a complete tree-hierarchy,
     words name = value pairs. List of ready-to-use property classes include
     strings, numbers, flag sets, fonts, colours and many others. It is possible,
     for example, to categorize properties, set up a complete tree-hierarchy,


@@ -266,10 +357,13 @@ 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 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_CHANGING(id, func)}
         Respond to wxEVT_PG_CHANGING event, generated when property value
         is about to be changed by user. Use wxPropertyGridEvent::GetValue()
     @event{EVT_PG_CHANGING(id, func)}
         Respond to wxEVT_PG_CHANGING event, generated when property value
         is about to be changed by user. Use wxPropertyGridEvent::GetValue()


@@ -291,38 +385,56 @@ enum wxPG_KEYBOARD_ACTIONS
     @event{EVT_PG_ITEM_EXPANDED(id, func)}
         Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
         a property or category.
     @event{EVT_PG_ITEM_EXPANDED(id, func)}
         Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
         a property or category.

+    @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
+        Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when 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 wxEVT_PG_LABEL_EDIT_ENDING event, generated when 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 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 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 wxEVT_PG_COL_END_DRAG event, generated after column
+        resize by user has finished.

     @endEventTable
 
     @remarks
     @endEventTable
 
     @remarks

-
-    - Use Freeze() and Thaw() respectively to disable and enable drawing. This
-      will also delay sorting etc. miscellaneous calculations to the last
-      possible moment.
+    Use Freeze() and Thaw() respectively to disable and enable drawing.
+    This will also delay sorting etc. miscellaneous calculations to the last
+    possible moment.

 
     @library{wxpropgrid}
     @category{propgrid}
 
     @library{wxpropgrid}
     @category{propgrid}

+    @appearance{propertygrid.png}

 */
 class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
 {
 public:
 */
 class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
 {
 public:

-
-       /**
-        Two step constructor. Call Create when this constructor is called to
-        build up the wxPropertyGrid
-       */
+    /**
+        Two step constructor.
+        Call Create() when this constructor is called to build up the wxPropertyGrid
+    */

     wxPropertyGrid();
 
     /**
     wxPropertyGrid();
 
     /**

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

 
         @see @ref propgrid_window_styles.
     */
     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,
 
         @see @ref propgrid_window_styles.
     */
     wxPropertyGrid( wxWindow *parent, wxWindowID id = wxID_ANY,

-                           const wxPoint& pos = wxDefaultPosition,
-                           const wxSize& size = wxDefaultSize,
-                           long style = wxPG_DEFAULT_STYLE,
-                           const wxChar* name = wxPropertyGridNameStr );
+                    const wxPoint& pos = wxDefaultPosition,
+                    const wxSize& size = wxDefaultSize,
+                    long style = wxPG_DEFAULT_STYLE,
+                    const wxChar* name = wxPropertyGridNameStr );

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


@@ -332,16 +444,28 @@ public:
 
         @param action
             Which action to trigger. See @ref propgrid_keyboard_actions.
 
         @param action
             Which action to trigger. See @ref propgrid_keyboard_actions.

-

         @param keycode
             Which keycode triggers the action.
         @param keycode
             Which keycode triggers the action.

-

         @param modifiers
             Which key event modifiers, in addition to keycode, are needed to
             trigger the action.
     */
     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 
         @param modifiers
             Which key event modifiers, in addition to keycode, are needed to
             trigger the action.
     */
     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,


@@ -351,6 +475,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 column = 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


@@ -397,37 +536,31 @@ public:
         @see @ref propgrid_window_styles.
     */
     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
         @see @ref propgrid_window_styles.
     */
     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,

-                 const wxPoint& pos = wxDefaultPosition,
-                 const wxSize& size = wxDefaultSize,
-                 long style = wxPG_DEFAULT_STYLE,
-                 const wxChar* name = wxPropertyGridNameStr );
+                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.
+        Enables or disables (shows/hides) categories according to parameter
+        enable.

 
 

-        @see wxPGProperty::OnEvent()
+        @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.

     */
     */

-    void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
+    bool EnableCategories( bool enable );

 
     /**
 
     /**

-        Reverse of EditorsValueWasModified().
+        Destroys label editor wxTextCtrl, if any.

 
 

-        @remarks This function should only be called by custom properties.
-    */
-    void EditorsValueWasNotModified()
-    {
-        m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
-    }
+        @param commit
+            Use @true (default) to store edited label text in
+            property cell data.

 
 

-    /**
-        Enables or disables (shows/hides) categories according to parameter
-        enable.
+        @see BeginLabelEdit(), MakeColumnEditable()

     */
     */

-    bool EnableCategories( bool enable );
+    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.


@@ -453,11 +586,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.


@@ -492,7 +630,7 @@ public:
     /**
         Returns number of columns currently on grid.
     */
     /**
         Returns number of columns currently on grid.
     */

-    int GetColumnCount() const;
+    unsigned int GetColumnCount() const;

 
     /**
         Returns colour of empty space below properties.
 
     /**
         Returns colour of empty space below properties.


@@ -553,16 +691,6 @@ public:
     */
     wxColour GetMarginColour() const;
 
     */
     wxColour GetMarginColour() const;
 

-    /**
-        Returns cell background colour of a property.
-    */
-    wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
-
-    /**
-        Returns cell background colour of a property.
-    */
-    wxColour GetPropertyTextColour( wxPGPropArg id ) const;
-

     /**
         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.


@@ -594,6 +722,13 @@ 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.
     */


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

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

     */
     */

-    int GetVerticalSpacing() const { return (int)m_vspacing; }
+    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
+            wxScrolledWindow::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;
 


@@ -625,12 +776,47 @@ 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 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.
+    */
+    void RefreshEditor();
+

     /**
         Redraws given property.
     */
     /**
         Redraws given property.
     */


@@ -650,10 +836,15 @@ public:
     */
     void ResetColours();
 
     */
     void ResetColours();
 

+    /**
+        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).


@@ -664,7 +855,13 @@ 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()
+        @remarks In wxPropertyGrid 1.4, this member function used to generate
+                 wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer
+                 does that.
+
+        @remarks This clears any previous selection.
+
+        @see wxPropertyGridInterface::ClearSelection()

     */
     bool SelectProperty( wxPGPropArg id, bool focus = false );
 
     */
     bool SelectProperty( wxPGPropArg id, bool focus = false );
 


@@ -730,32 +927,50 @@ public:
     void SetMarginColour(const wxColour& col);
 
     /**
     void SetMarginColour(const wxColour& col);
 
     /**

-        Sets background colour of property and all its children. Colours of
-        captions are not affected. Background brush cache is optimized for often
-        set colours to be set last.
+        Set entire new selection from given list of properties.

     */
     */

-    void SetPropertyBackgroundColour( wxPGPropArg id, const wxColour& col );
+    void SetSelection( const wxArrayPGProperty& newSelection );

 
     /**
 
     /**

-        Resets text and background colours of given property.
+        Sets selection background colour - applies to selected property name
+        background.

     */
     */

-    void SetPropertyColoursToDefault( wxPGPropArg id );
+    void SetSelectionBackgroundColour(const wxColour& col);

 
     /**
 
     /**

-        Sets text colour of property and all its children.
+        Sets selection foreground colour - applies to selected property name text.

     */
     */

-    void SetPropertyTextColour( wxPGPropArg id, const wxColour& col,
-                                bool recursively = true );
+    void SetSelectionTextColour(const wxColour& col);

 
 

-    /** Sets selection background colour - applies to selected property name
-        background. */
-    void SetSelectionBackgroundColour(const wxColour& col);

 
 

-    /** Sets selection foreground colour - applies to selected property name
-        text. */
-    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.

 
         @remarks Splitter position cannot exceed grid size, and therefore setting
                 it during form creation may fail as initial grid size is often
 
         @remarks Splitter position cannot exceed grid size, and therefore setting
                 it during form creation may fail as initial grid size is often


@@ -764,17 +979,6 @@ public:
     */
     void SetSplitterPosition( int newxpos, int col = 0 );
 
     */
     void SetSplitterPosition( int newxpos, int col = 0 );
 

-    /**
-        Sets name of a property.
-
-        @param id
-            Name or pointer of property which name to change.
-
-        @param newname
-            New name.
-    */
-    void SetPropertyName( wxPGPropArg id, const wxString& newname );
-

     /**
         Moves splitter as left as possible, while still allowing all
         labels to be shown in full.
     /**
         Moves splitter as left as possible, while still allowing all
         labels to be shown in full.


@@ -782,10 +986,20 @@ public:
         @param privateChildrenToo
             If @false, will still allow private children to be cropped.
     */
         @param privateChildrenToo
             If @false, will still allow private children to be cropped.
     */

-    void SetSplitterLeft( bool privateChildrenToo = false )
-    {
-        m_pState->SetSplitterLeft(subProps);
-    }
+    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
 
     /**
         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font


@@ -793,20 +1007,64 @@ public:
     */
     void SetVerticalSpacing( int vspacing );
 
     */
     void SetVerticalSpacing( int vspacing );
 

+

     /**
     /**

-        Shows an brief error message that is related to a property.
+        @name Property development functions
+
+        These member functions are usually only called when creating custom
+        user properties.

     */
     */

-    void ShowPropertyError( wxPGPropArg id, const wxString& msg );
+    //@{
+
+    /**
+        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();

 
     /**
 
     /**

-        Sorts all items at all levels (except private children).
+        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.

     */
     */

-    void Sort();
+    wxVariant GetUncommittedPropertyValue();

 
     /**
 
     /**

-        Sorts children of a property.
+        Returns true if editor's value was marked modified.
+    */
+    bool IsEditorsValueModified() const;
+
+    /**
+        Shows an brief error message that is related to a property.

     */
     */

-    void SortChildren( wxPGPropArg id );
+    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;
+
+    //@}

 };
 
 
 };
 
 


@@ -835,10 +1093,14 @@ public:
     /**
         Returns true if you can veto the action that the event is signaling.
     */
     /**
         Returns true if you can veto the action that the event is signaling.
     */

-    bool CanVeto() const { return m_canVeto; }
+    bool CanVeto() const;

 
 

-    /** Copyer. */
-    virtual wxEvent* Clone() 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
 
     /**
         Returns highest level non-category, non-root parent of property for


@@ -861,15 +1123,36 @@ 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.

     */
     */

-    const wxVariant& GetValue() const;
+    wxString GetPropertyName() const;
+
+    /**
+        Returns value of the associated property. Works for all event
+        types, but for 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()
+    */
+    wxVariant GetValue() const;

 
     /**
         Set if event can be vetoed.
     */
     void SetCanVeto( bool canVeto );
 
     /**
         Set if event can be vetoed.
     */
     void SetCanVeto( bool canVeto );

-    
+

     /** Changes the property associated with this event. */
     void SetProperty( wxPGProperty* p );
 
     /** Changes the property associated with this event. */
     void SetProperty( wxPGProperty* p );
 


@@ -877,7 +1160,7 @@ public:
         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 behavior. Only effective if Veto() was
         also called, and only allowed if event type is wxEVT_PG_CHANGING.
     */

-    void SetValidationFailureBehavior( int flags );
+    void SetValidationFailureBehavior( wxPGVFBFlags flags );

 
     /**
         Sets custom failure message for this time only. Only applies if
 
     /**
         Sets custom failure message for this time only. Only applies if