Implement wxGraphicsContext::SetInterpolationQuality() for wxMSW.

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

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

-// RCS-ID:      $Id:
-// Licence:     wxWindows license
+// RCS-ID:      $Id$
+// Licence:     wxWindows licence

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


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


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

 
 };
 
 
 };
 


@@ -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_LEGACY_VALIDATORS               = 0x00800000,
+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,

 
 /**
 
 /**

-    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_HIDE_PAGE_BUTTONS               = 0x01000000
+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)

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


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

     @{
 */
 
     @{
 */
 


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


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

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


@@ -215,10 +269,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 behaviour 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 behaviour
+
+        @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().
     @{


@@ -227,25 +320,65 @@ typedef wxByte wxPGVFBFlags;
 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,

-    wxPG_ACTION_CUT,
-    wxPG_ACTION_COPY,
-    wxPG_ACTION_PASTE,
+
+    /** 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);
+

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

-/** @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,63 +399,89 @@ 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

-
-    - 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
+class wxPropertyGrid : public wxControl,
+                       public wxScrollHelper,
+                       public wxPropertyGridInterface

 {
 public:
 {
 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.

 
         @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 wxString& name = wxPropertyGridNameStr );

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


@@ -330,18 +489,39 @@ 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 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 +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


@@ -361,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.


@@ -382,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.


@@ -397,37 +594,41 @@ 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 wxString& 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.
+        Dedicates a specific keycode to wxPropertyGrid. This means that such
+        key presses will not be redirected to editor controls.

 
 

-        @see wxPGProperty::OnEvent()
+        Using this function allows, for example, navigation between
+        properties using arrow keys even when the focus is in the editor
+        control.

     */
     */

-    void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
+    void DedicateKey( int keycode );

 
     /**
 
     /**

-        Reverse of EditorsValueWasModified().
+        Enables or disables (shows/hides) categories according to parameter
+        enable.

 
 

-        @remarks This function should only be called by custom properties.
+        @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 EditorsValueWasNotModified()
-    {
-        m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
-    }
+    bool EnableCategories( bool enable );

 
     /**
 
     /**

-        Enables or disables (shows/hides) categories according to parameter
-        enable.
+        Destroys label editor wxTextCtrl, if any.
+
+        @param commit
+            Use @true (default) to store edited label text in
+            property cell data.
+
+        @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 +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.


@@ -492,7 +698,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 +759,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,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


@@ -606,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 { 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
+            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;
 


@@ -625,23 +844,64 @@ 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.
+    */
+    void RefreshEditor();
+

     /**
         Redraws given property.
     */
     virtual void RefreshProperty( wxPGProperty* p );
 
     /**
         Redraws given property.
     */
     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 );
 


@@ -650,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).


@@ -664,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.


@@ -730,32 +1004,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).

 
 

-    /** Sets x coordinate of the splitter.
+        @see GetSortFunction, wxPropertyGridInterface::Sort,
+             wxPropertyGridInterface::SortChildren
+    */
+    void SetSortFunction( wxPGSortCallback sortFunction );
+
+    /**
+        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 +1056,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 +1063,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


@@ -794,19 +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 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()
+    */
+    virtual void DoShowPropertyError( wxPGProperty* property,
+                                      const wxString& msg );
+
+    /**
+        Override in derived class to hide an error displayed by
+        DoShowPropertyError().
+
+        @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.
+    */
+    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 Sort();
+    void ShowPropertyError( wxPGPropArg id, const wxString& msg );

 
     /**
 
     /**

-        Sorts children of a property.
+        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).

     */
     */

-    void SortChildren( wxPGPropArg id );
+    bool WasValueChangedInEvent() const;
+
+    //@}

 };
 
 
 };
 
 


@@ -835,10 +1209,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


@@ -852,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;
 


@@ -861,23 +1244,44 @@ 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.

     */
     */

-    const wxVariant& GetValue() const;
+    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 );
 
     /**

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


@@ -890,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 );