Adding wxUIActionSimulator, a class for programmatically controlling the mouse and...

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

diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h
index 15a7168958c02c01a9b0d9e68ceaa9db46003dff..c7bf80a9967e9feb0acbaae07c9fa45b52316e9b 100644 (file)
--- a/interface/wx/propgrid/propgrid.h
+++ b/interface/wx/propgrid/propgrid.h
@@ -2,12 +2,13 @@
 // 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
 /////////////////////////////////////////////////////////////////////////////
 
 

-/** @section propgrid_window_styles wxPropertyGrid Window Styles
+/**
+    @section propgrid_window_styles wxPropertyGrid Window Styles

 
     SetWindowStyleFlag method can be used to modify some of these at run-time.
     @{
 
     SetWindowStyleFlag method can be used to modify some of these at run-time.
     @{


@@ -15,67 +16,85 @@
 enum wxPG_WINDOW_STYLES
 {
 
 enum wxPG_WINDOW_STYLES
 {
 

-/** This will cause Sort() automatically after an item is added.
+/**
+    This will cause Sort() automatically after an item is added.

     When inserting a lot of items in this mode, it may make sense to
     use Freeze() before operations and Thaw() afterwards to increase
     performance.
 */
 wxPG_AUTO_SORT                      = 0x00000010,
 
     When inserting a lot of items in this mode, it may make sense to
     use Freeze() before operations and Thaw() afterwards to increase
     performance.
 */
 wxPG_AUTO_SORT                      = 0x00000010,
 

-/** Categories are not initially shown (even if added).
+/**
+    Categories are not initially shown (even if added).

     IMPORTANT NOTE: If you do not plan to use categories, then this
     style will waste resources.
     This flag can also be changed using wxPropertyGrid::EnableCategories method.
 */
 wxPG_HIDE_CATEGORIES                = 0x00000020,
 
     IMPORTANT NOTE: If you do not plan to use categories, then this
     style will waste resources.
     This flag can also be changed using wxPropertyGrid::EnableCategories method.
 */
 wxPG_HIDE_CATEGORIES                = 0x00000020,
 

-/* This style combines non-categoric mode and automatic sorting.
+/**
+    This style combines non-categoric mode and automatic sorting.

 */
 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
 
 */
 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
 

-/** Modified values are shown in bold font. Changing this requires Refresh()
+/**
+    Modified values are shown in bold font. Changing this requires Refresh()

     to show changes.
 */
 wxPG_BOLD_MODIFIED                  = 0x00000040,
 
     to show changes.
 */
 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.
 */
 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
 
     behavior stops once the user manually moves the splitter.
 */
 wxPG_SPLITTER_AUTO_CENTER           = 0x00000080,
 

-/** Display tooltips for cell text that cannot be shown completely. If
+/**
+    Display tool tips for cell text that cannot be shown completely. If

     wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
 */
 wxPG_TOOLTIPS                       = 0x00000100,
 
     wxUSE_TOOLTIPS is 0, then this doesn't have any effect.
 */
 wxPG_TOOLTIPS                       = 0x00000100,
 

-/** Disables margin and hides all expand/collapse buttons that would appear
+/**
+    Disables margin and hides all expand/collapse buttons that would appear

     outside the margin (for sub-properties). Toggling this style automatically
     expands all collapsed items.
 */
 wxPG_HIDE_MARGIN                    = 0x00000200,
 
     outside the margin (for sub-properties). Toggling this style automatically
     expands all collapsed items.
 */
 wxPG_HIDE_MARGIN                    = 0x00000200,
 

-/** This style prevents user from moving the splitter.
+/**
+    This style prevents user from moving the splitter.

 */
 wxPG_STATIC_SPLITTER                = 0x00000400,
 
 */
 wxPG_STATIC_SPLITTER                = 0x00000400,
 

-/** Combination of other styles that make it impossible for user to modify
+/**
+    Combination of other styles that make it impossible for user to modify

     the layout.
 */
 wxPG_STATIC_LAYOUT                  = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
 
     the layout.
 */
 wxPG_STATIC_LAYOUT                  = (wxPG_HIDE_MARGIN|wxPG_STATIC_SPLITTER),
 

-/** Disables wxTextCtrl based editors for properties which
-    can be edited in another way. Equals calling wxPropertyGrid::LimitPropertyEditing
-    for all added properties.
+/**
+    Disables wxTextCtrl based editors for properties which
+    can be edited in another way. Equals calling
+    wxPropertyGrid::LimitPropertyEditing() for all added properties.

 */
 wxPG_LIMITED_EDITING                = 0x00000800,
 
 */
 wxPG_LIMITED_EDITING                = 0x00000800,
 

-/** wxPropertyGridManager only: Show toolbar for mode and page selection. */
+/**
+    wxPropertyGridManager only: Show tool bar for mode and page selection.
+*/

 wxPG_TOOLBAR                        = 0x00001000,
 
 wxPG_TOOLBAR                        = 0x00001000,
 

-/** wxPropertyGridManager only: Show adjustable text box showing description
+/**
+    wxPropertyGridManager only: Show adjustable text box showing description

     or help text, if available, for currently selected property.
 */
     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

 
 };
 
 
 };
 


@@ -86,108 +105,142 @@ enum wxPG_EX_WINDOW_STYLES
     NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
     member function.
 
     NOTE: wxPG_EX_xxx are extra window styles and must be set using SetExtraStyle()
     member function.
 

-    Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if wxPG_HIDE_CATEGORIES
-    is not defined, the non-categorized data storage is not activated, and switching
-    the mode first time becomes somewhat slower. wxPG_EX_INIT_NOCAT activates the
-    non-categorized data storage right away. IMPORTANT NOTE: If you do plan not
-    switching to non-categoric mode, or if you don't plan to use categories at
-    all, then using this style will result in waste of resources.
+    Speeds up switching to wxPG_HIDE_CATEGORIES mode. Initially, if
+    wxPG_HIDE_CATEGORIES is not defined, the non-categorized data storage is not
+    activated, and switching the mode first time becomes somewhat slower.
+    wxPG_EX_INIT_NOCAT activates the non-categorized data storage right away.

 
 

+    NOTE: If you do plan not switching to non-categoric mode, or if
+    you don't plan to use categories at all, then using this style will result
+    in waste of resources.

 */
 wxPG_EX_INIT_NOCAT                  = 0x00001000,
 
 */
 wxPG_EX_INIT_NOCAT                  = 0x00001000,
 

-/** Extended window style that sets wxPropertyGridManager toolbar to not
+/**
+    Extended window style that sets wxPropertyGridManager tool bar to not

     use flat style.
 */
 wxPG_EX_NO_FLAT_TOOLBAR             = 0x00002000,
 
     use flat style.
 */
 wxPG_EX_NO_FLAT_TOOLBAR             = 0x00002000,
 

-/** Shows alphabetic/categoric mode buttons from toolbar.
+/**
+    Shows alphabetic/categoric mode buttons from tool bar.

 */
 wxPG_EX_MODE_BUTTONS                = 0x00008000,
 
 */
 wxPG_EX_MODE_BUTTONS                = 0x00008000,
 

-/** Show property help strings as tool tips instead as text on the status bar.
+/**
+    Show property help strings as tool tips instead as text on the status bar.

     You can set the help strings using SetPropertyHelpString member function.
 */
 wxPG_EX_HELP_AS_TOOLTIPS            = 0x00010000,
 
     You can set the help strings using SetPropertyHelpString member function.
 */
 wxPG_EX_HELP_AS_TOOLTIPS            = 0x00010000,
 

-/** Prevent TAB from focusing to wxButtons. This behavior was default
-    in version 1.2.0 and earlier.
-    NOTE! Tabbing to button doesn't work yet. Problem seems to be that on wxMSW
-      atleast the button doesn't properly propagate key events (yes, I'm using
-      wxWANTS_CHARS).
-*/
-//wxPG_EX_NO_TAB_TO_BUTTON            = 0x00020000,
-
-/** Allows relying on native double-buffering.
+/**
+    Allows relying on native double-buffering.

 */
 wxPG_EX_NATIVE_DOUBLE_BUFFERING         = 0x00080000,
 
 */
 wxPG_EX_NATIVE_DOUBLE_BUFFERING         = 0x00080000,
 

-/** Set this style to let user have ability to set values of properties to
+/**
+    Set this style to let user have ability to set values of properties to

     unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
     all properties.
 */
 wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 
     unspecified state. Same as setting wxPG_PROP_AUTO_UNSPECIFIED for
     all properties.
 */
 wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 

-/** If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and wxPG_STRING_PASSWORD)
-    are not stored into property's attribute storage (thus they are not readable).
+/**
+    If this style is used, built-in attributes (such as wxPG_FLOAT_PRECISION and
+    wxPG_STRING_PASSWORD) are not stored into property's attribute storage (thus
+    they are not readable).

 
     Note that this option is global, and applies to all wxPG property containers.
 */
 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 
 
     Note that this option is global, and applies to all wxPG property containers.
 */
 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_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_LEGACY_VALIDATORS               = 0x00800000,
+wxPG_EX_ENABLE_TLP_TRACKING             = 0x04000000,

 
 

-/** Hides page selection buttons from toolbar.
+/** Don't show divider above toolbar, on Windows.

 */
 */

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

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

-/** wxPropertyGrid Validation Failure Behavior Flags
+/**
+    @section propgrid_vfbflags wxPropertyGrid Validation Failure Behavior Flags

     @{
 */
 
 enum wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS
 {
 
     @{
 */
 
 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.
 */
 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 
     behavior flag is not used, then value change is instead cancelled.
 */
 wxPG_VFB_STAY_IN_PROPERTY           = 0x01,
 

-/** Calls wxBell() on validation failure.
+/**
+    Calls wxBell() on validation failure.

 */
 wxPG_VFB_BEEP                       = 0x02,
 
 */
 wxPG_VFB_BEEP                       = 0x02,
 

-/** Cell with invalid value will be marked (with red colour).
+/**
+    Cell with invalid value will be marked (with red colour).

 */
 wxPG_VFB_MARK_CELL                  = 0x04,
 
 */
 wxPG_VFB_MARK_CELL                  = 0x04,
 

-/** Display customizable text message explaining the situation.
+/**
+    Display customizable text message explaining the situation.

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

-/** Defaults. */
+/**
+    Defaults.
+*/

 wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
 wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,

-
-/** Only used internally. */
-wxPG_VFB_UNDEFINED                  = 0x80
-

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


@@ -195,38 +248,51 @@ wxPG_VFB_UNDEFINED                  = 0x80
 
 typedef wxByte wxPGVFBFlags;
 
 
 typedef wxByte wxPGVFBFlags;
 

-/** wxPGValidationInfo
+/**
+    wxPGValidationInfo

 
     Used to convey validation information to and from functions that
 
     Used to convey validation information to and from functions that

-    actually perform validation.
+    actually perform validation. Mostly used in custom property classes.

 */
 */

-struct wxPGValidationInfo
+class wxPGValidationInfo

 {
 {

-    /** Value to be validated.
+public:
+    /**
+        @return Returns failure behavior which is a combination of
+            @ref propgrid_vfbflags.

     */
     */

-    wxVariant*      m_pValue;
+    wxPGVFBFlags GetFailureBehavior();

 
 

-    /** Message displayed on validation failure.
+    /**
+        Returns current failure message.

     */
     */

-    wxString        m_failureMessage;
+    const wxString& GetFailureMessage() const;

 
 

-    /** Validation failure behavior. Use wxPG_VFB_XXX flags.
+    /**
+        Returns reference to pending value.

     */
     */

-    wxPGVFBFlags    m_failureBehavior;
+    wxVariant& GetValue();

 
 

-    wxPGVFBFlags GetFailureBehavior() const { return m_failureBehavior; }
+    /** Set validation failure behavior

 
 

-    void SetFailureBehavior(wxPGVFBFlags failureBehavior) { m_failureBehavior = failureBehavior; }
-
-    const wxString& GetFailureMessage() const { return m_failureMessage; }
+        @param failureBehavior
+            Mixture of @ref propgrid_vfbflags.
+    */
+    void SetFailureBehavior(wxPGVFBFlags failureBehavior);

 
 

-    void SetFailureMessage(const wxString& message) { m_failureMessage = message; }
+    /**
+        Set current failure message.
+    */
+    void SetFailureMessage(const wxString& message);

 };
 
 // -----------------------------------------------------------------------
 
 };
 
 // -----------------------------------------------------------------------
 

-/** wxPropertyGrid Action Identifiers
-    These are used with wxPropertyGrid::AddActionTrigger() and wxPropertyGrid::ClearActionTriggers().
+/**
+    @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
+
+    These are used with wxPropertyGrid::AddActionTrigger() and
+    wxPropertyGrid::ClearActionTriggers().

     @{
 */
 
     @{
 */
 


@@ -238,27 +304,47 @@ 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
-    such as strings, numbers, flagsets, fonts, and colours. wxPropertySheet
-    used to do the very same thing, but it hasn't been updated for a while
-    and it is currently deprecated.
+    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,
+    add more than two columns, and set arbitrary per-property attributes.

 
 

-    Please note that most member functions are inherited and as such not documented on
-    this page. This means you will probably also want to read wxPropertyGridInterface
-    class reference.
+    Please note that most member functions are inherited and as such not
+    documented on this page. This means you will probably also want to read
+    wxPropertyGridInterface class reference.

 
     See also @ref overview_propgrid.
 
 
     See also @ref overview_propgrid.
 


@@ -268,13 +354,19 @@ enum wxPG_KEYBOARD_ACTIONS
 
     @section propgrid_event_handling Event Handling
 
 
     @section propgrid_event_handling Event Handling
 

-    To process input from a propertygrid 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_CHANGED(id, func)}
+        Respond to wxEVT_PG_CHANGED event, generated when property value
+        has been changed by the user.

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


@@ -289,460 +381,713 @@ enum wxPG_KEYBOARD_ACTIONS
         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
         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

-        double-clicked onwith left mouse button.
+        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
     @event{EVT_PG_ITEM_COLLAPSED(id, func)}
         Respond to wxEVT_PG_ITEM_COLLAPSED event, generated when user collapses

-        a property or category..
+        a property or category.

     @event{EVT_PG_ITEM_EXPANDED(id, func)}
         Respond to wxEVT_PG_ITEM_EXPANDED event, generated when user expands
     @event{EVT_PG_ITEM_EXPANDED(id, func)}
         Respond to 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 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 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 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();
 

-    /** The default constructor. The styles to be used are styles valid for
-        the wxWindow and wxScrolledWindow.
-        @sa @link wndflags Additional Window Styles@endlink
+    /**
+        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,
     */
     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();
 

-    /** Adds given key combination to trigger given action.
+    /**
+        Adds given key combination to trigger given action.
+

         @param action
         @param action

-        Which action to trigger. See @link pgactions List of list of wxPropertyGrid actions@endlink.
+            Which action to trigger. See @ref propgrid_keyboard_actions.
+        @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 );
 
     */
     void AddActionTrigger( int action, int keycode, int modifiers = 0 );
 

-    /** This static function enables or disables automatic use of wxGetTranslation for
-        following strings: wxEnumProperty list labels, wxFlagsProperty sub-property
-        labels.
+    /**
+        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,
+        wxFlagsProperty child property labels.
+

         Default is false.
     */
     static void AutoGetTranslation( bool enable );
 
         Default is false.
     */
     static void AutoGetTranslation( bool enable );
 

-    /** Changes value of a property, as if from an editor. Use this instead of SetPropertyValue()
-        if you need the value to run through validation process, and also send the property
-        change event.
+    /**
+        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.

 
 

-        @return
-        Returns true if value was successfully changed.
+        @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
+        process, and also send the property change event.
+
+        @return Returns true if value was successfully changed.

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

     */
     virtual void Clear();
 
     */
     virtual void Clear();
 

-    /** Clears action triggers for given action.
+    /**
+        Clears action triggers for given action.
+

         @param action
         @param action

-        Which action to trigger. See @link pgactions List of list of wxPropertyGrid actions@endlink.
+            Which action to trigger. @ref propgrid_keyboard_actions.

     */
     void ClearActionTriggers( int action );
 
     */
     void ClearActionTriggers( int action );
 

-    /** Forces updating the value of property from the editor control.
-        Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using ProcessEvent,
-        meaning your event handlers will be called immediately.
+    /**
+        Forces updating the value of property from the editor control.
+        Note that wxEVT_PG_CHANGING and wxEVT_PG_CHANGED are dispatched using
+        ProcessEvent, meaning your event handlers will be called immediately.

 
 

-        @retval
-        Returns true if anything was changed.
+        @return Returns @true if anything was changed.

     */
     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 
     */
     virtual bool CommitChangesFromEditor( wxUint32 flags = 0 );
 

-    /** Two step creation. Whenever the control is created without any parameters, use Create to actually
-        create it. Don't access the control's public methods before this is called
-        @sa @link wndflags Additional Window Styles@endlink
+    /**
+        Two step creation. Whenever the control is created without any
+        parameters, use Create to actually create it. Don't access the control's
+        public methods before this is called
+
+        @see @ref propgrid_window_styles.

     */
     bool Create( wxWindow *parent, wxWindowID id = wxID_ANY,
     */
     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 );
-
-    /** 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()
+                const wxPoint& pos = wxDefaultPosition,
+                const wxSize& size = wxDefaultSize,
+                long style = wxPG_DEFAULT_STYLE,
+                const wxChar* name = wxPropertyGridNameStr );
+
+    /**
+        Enables or disables (shows/hides) categories according to parameter
+        enable.
+
+        @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.
+        @param commit
+            Use @true (default) to store edited label text in
+            property cell data.
+
+        @see BeginLabelEdit(), MakeColumnEditable()

     */
     */

-    void EditorsValueWasNotModified()
-    {
-        m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
-    }
+    void EndLabelEdit( bool commit = true );

 
 

-    /** Enables or disables (shows/hides) categories according to parameter enable. */
-    bool EnableCategories( bool enable );
+    /**
+        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.
-        Returns true if something was actually done.
+        @return Returns @true if something was actually done.

     */
     bool EnsureVisible( wxPGPropArg id );
 
     */
     bool EnsureVisible( wxPGPropArg id );
 

-    /** Reduces column sizes to minimum possible that contents are still visibly (naturally
-        some margin space will be applied as well).
+    /**
+        Reduces column sizes to minimum possible, while still retaining
+        fully visible grid contents (labels, images).

 
 

-        @return
-        Minimum size for the grid to still display everything.
+        @return Minimum size for the grid to still display everything.

 
 

-        @remarks
-        Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.
+        @remarks Does not work well with wxPG_SPLITTER_AUTO_CENTER window style.

 
 

-        This function only works properly if grid size prior to call was already
-        fairly large.
+                This function only works properly if grid size prior to call was
+                already fairly large.

 
 

-        Note that you can also get calculated column widths by calling GetState->GetColumnWidth()
-        immediately after this function returns.
+                Note that you can also get calculated column widths by calling
+                GetState->GetColumnWidth() immediately after this function
+                returns.

     */
     */

-    wxSize FitColumns()
-    {
-        wxSize sz = m_pState->DoFitColumns();
-        return sz;
-    }
+    wxSize FitColumns();

 
 

-    /** Returns wxWindow that the properties are painted on, and which should be used
-        as the parent for editor controls.
+    /**
+        Returns currently active label editor, NULL if none.

     */
     */

-    wxPanel* GetPanel() const
-    {
-        return m_canvas;
-    }
+    wxTextCtrl* GetLabelEditor() const;

 
 

-    /** Returns current category caption background colour. */
-    wxColour GetCaptionBackgroundColour() const { return m_colCapBack; }
+    /**
+        Returns wxWindow that the properties are painted on, and which should be
+        used as the parent for editor controls.
+    */
+    wxWindow* GetPanel();

 
 

-    wxFont& GetCaptionFont() { return m_captionFont; }
+    /**
+        Returns current category caption background colour.
+    */
+    wxColour GetCaptionBackgroundColour() const;

 
 

-    const wxFont& GetCaptionFont() const { return m_captionFont; }
+    /**
+        Returns current category caption font.
+    */
+    wxFont& GetCaptionFont();

 
 

-    /** Returns current category caption text colour. */
-    wxColour GetCaptionForegroundColour() const { return m_colCapFore; }
+    /**
+        Returns current category caption text colour.
+    */
+    wxColour GetCaptionForegroundColour() const;

 
 

-    /** Returns current cell background colour. */
-    wxColour GetCellBackgroundColour() const { return m_colPropBack; }
+    /**
+        Returns current cell background colour.
+    */
+    wxColour GetCellBackgroundColour() const;

 
 

-    /** Returns current cell text colour when disabled. */
-    wxColour GetCellDisabledTextColour() const { return m_colDisPropFore; }
+    /**
+        Returns current cell text colour when disabled.
+    */
+    wxColour GetCellDisabledTextColour() const;

 
 

-    /** Returns current cell text colour. */
-    wxColour GetCellTextColour() const { return m_colPropFore; }
+    /**
+        Returns current cell text colour.
+    */
+    wxColour GetCellTextColour() const;

 
 

-    /** Returns number of columns on current page. */
-    int GetColumnCount() const
-    {
-        return m_pState->m_colWidths.size();
-    }
+    /**
+        Returns number of columns currently on grid.
+    */
+    unsigned int GetColumnCount() const;

 
 

-    /** Returns colour of empty space below properties. */
-    wxColour GetEmptySpaceColour() const { return m_colEmptySpace; }
+    /**
+        Returns colour of empty space below properties.
+    */
+    wxColour GetEmptySpaceColour() const;

 
 

-    /** Returns height of highest characters of used font. */
-    int GetFontHeight() const { return m_fontHeight; }
+    /**
+        Returns height of highest characters of used font.
+    */
+    int GetFontHeight() const;

 
 

-    /** Returns pointer to itself. Dummy function that enables same kind
+    /**
+        Returns pointer to itself. Dummy function that enables same kind

         of code to use wxPropertyGrid and wxPropertyGridManager.
     */
         of code to use wxPropertyGrid and wxPropertyGridManager.
     */

-    wxPropertyGrid* GetGrid() { return this; }
+    wxPropertyGrid* GetGrid();

 
 

-    /** Returns rectangle of custom paint image.
+    /**
+        Returns rectangle of custom paint image.
+
+        @param property
+            Return image rectangle for this property.
+
+        @param item
+            Which choice of property to use (each choice may have
+            different image).

     */
     */

-    wxRect GetImageRect( wxPGProperty* p, int item ) const;
+    wxRect GetImageRect( wxPGProperty* property, int item ) const;
+
+    /**
+        Returns size of the custom paint image in front of property.

 
 

-    /** Returns size of the custom paint image in front of property.
-        If no argument is given, returns preferred size.
+        @param property
+            Return image rectangle for this property.
+            If this argument is NULL, then preferred size is returned.
+
+        @param item
+            Which choice of property to use (each choice may have
+            different image).

     */
     */

-    wxSize GetImageSize( wxPGProperty* p = NULL, int item = -1 ) const;
+    wxSize GetImageSize( wxPGProperty* property = NULL, int item = -1 ) const;
+
+    /**
+        Returns last item which could be iterated using given flags.

 
 

-    //@{
-    /** Returns last item which could be iterated using given flags.

         @param flags
         @param flags

-        See @ref propgrid_iterator_flags.
+            See @ref propgrid_iterator_flags.

     */
     */

-    wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT )
-    {
-        return m_pState->GetLastItem(flags);
-    }
+    wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT );

 
 

-    const wxPGProperty* GetLastItem( int flags = wxPG_ITERATE_DEFAULT ) const
-    {
-        return m_pState->GetLastItem(flags);
-    }
-    //@}
-
-    /** Returns colour of lines between cells. */
-    wxColour GetLineColour() const { return m_colLine; }
+    /**
+        Returns colour of lines between cells.
+    */
+    wxColour GetLineColour() const;

 
 

-    /** Returns background colour of margin. */
-    wxColour GetMarginColour() const { return m_colMargin; }
+    /**
+        Returns background colour of margin.
+    */
+    wxColour GetMarginColour() const;

 
 

-    /** Returns cell background colour of a property. */
-    wxColour GetPropertyBackgroundColour( 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.
+    */
+    wxPGProperty* GetRoot() const;

 
 

-    /** Returns cell background colour of a property. */
-    wxColour GetPropertyTextColour( wxPGPropArg id ) const;
+    /**
+        Returns height of a single grid row (in pixels).
+    */
+    int GetRowHeight() const;

 
 

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

     */
     */

-    wxPGProperty* GetRoot() const { return m_pState->m_properties; }
+    wxPGProperty* GetSelectedProperty() const;

 
 

-    /** Returns height of a single grid row (in pixels). */
-    int GetRowHeight() const { return m_lineHeight; }
+    /**
+        Returns currently selected property.
+    */
+    wxPGProperty* GetSelection() const;

 
 

-    /** Returns currently selected property. */
-    wxPGProperty* GetSelectedProperty () const { return GetSelection(); }
+    /**
+        Returns current selection background colour.
+    */
+    wxColour GetSelectionBackgroundColour() const;

 
 

-    /** Returns currently selected property. */
-    wxPGProperty* GetSelection() const
-    {
-        return m_selected;
-    }
+    /**
+        Returns current selection text colour.
+    */
+    wxColour GetSelectionForegroundColour() const;

 
 

-    /** Returns current selection background colour. */
-    wxColour GetSelectionBackgroundColour() const { return m_colSelBack; }
+    /**
+        Returns the property sort function (default is @NULL).

 
 

-    /** Returns current selection text colour. */
-    wxColour GetSelectionForegroundColour() const { return m_colSelFore; }
+        @see SetSortFunction
+    */
+    wxPGSortCallback GetSortFunction() const;

 
 

-    /** Returns current splitter x position. */
-    int GetSplitterPosition() const { return m_pState->DoGetSplitterPosition(0); }
+    /**
+        Returns current splitter x position.
+    */
+    int GetSplitterPosition( unsigned int splitterIndex = 0 ) const;

 
 

-    /** Returns wxTextCtrl active in currently selected property, if any. Takes
-        into account wxOwnerDrawnComboBox.
+    /**
+        Returns wxTextCtrl active in currently selected property, if any. Takes
+        wxOwnerDrawnComboBox into account.

     */
     wxTextCtrl* GetEditorTextCtrl() const;
 
     */
     wxTextCtrl* GetEditorTextCtrl() const;
 

-    wxPGValidationInfo& GetValidationInfo()
-    {
-        return m_validationInfo;
-    }
+    /**
+        Returns current appearance of unspecified value cells.

 
 

-    /** Returns current vertical spacing. */
-    int GetVerticalSpacing() const { return (int)m_vspacing; }
+        @see SetUnspecifiedValueAppearance()
+    */
+    const wxPGCell& GetUnspecifiedValueAppearance() const;
+
+    /**
+        Returns (visual) text representation of the unspecified
+        property value.

 
 

-    /** Returns true if editor's value was marked modified.
+        @param argFlags For internal use only.

     */
     */

-    bool IsEditorsValueModified() const { return  ( m_iFlags & wxPG_FL_VALUE_MODIFIED ) ? true : false; }
+    wxString GetUnspecifiedValueText( int argFlags = 0 ) const;

 
 

-    /** Returns information about arbitrary position in the grid.
+    /**
+        Returns current vertical spacing.
+    */
+    int GetVerticalSpacing() const;
+
+    /**
+        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;
 

-    /** Returns true if any property has been modified by the user. */
-    bool IsAnyModified() const { return (m_pState->m_anyModified>0); }
+    /**
+        Returns true if any property has been modified by the user.
+    */
+    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;
+
+    /**
+        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.

 
 

-    /** Returns true if updating is frozen (ie. Freeze() called but not yet Thaw() ). */
-    bool IsFrozen() const { return (m_frozen>0)?true:false; }
+        @param newTLP
+            New top-level parent that is about to be set. Old top-level parent
+            window should still exist as the current one.

 
 

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

-    /** Registers a new editor class.
-        @retval
-        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, const wxString& name,
+    static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
+                                            const wxString& name,

                                             bool noDefCheck = false );
 
                                             bool noDefCheck = false );
 

-    /** Resets all colours to the original system values.
+    /**
+        Resets all colours to the original system values.

     */
     void ResetColours();
 
     */
     void ResetColours();
 

-    /** Selects a property. Editor widget is automatically created, but
-        not focused unless focus is true. This will generate wxEVT_PG_SELECT event.
+    /**
+        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
+        not focused unless focus is true.
+

         @param id
         @param id

-        Property to select.
-        @retval
-        True if selection finished successfully. Usually only fails if current
-        value in editor is not valid.
-        @sa wxPropertyGrid::Unselect
-    */
-    bool SelectProperty( wxPGPropArg id, bool focus = false )
-    {
-        wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
-        return DoSelectProperty(p,focus?wxPG_SEL_FOCUS:0);
-    }
-
-    /** Changes keyboard shortcut to push the editor button.
-        @remarks
-        You can set default with keycode 0. Good value for the platform is guessed,
-        but don't expect it to be very accurate.
+            Property to select (name or pointer).
+
+        @param focus
+            If @true, move keyboard focus to the created editor right away.
+
+        @return returns @true if selection finished successfully. Usually only
+        fails if current value in editor is not valid.
+
+        @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 );
+
+    /**
+        Changes keyboard shortcut to push the editor button.
+
+        @remarks You can set default with keycode 0. Good value for the platform
+                is guessed, but don't expect it to be very accurate.

     */
     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 
     */
     void SetButtonShortcut( int keycode, bool ctrlDown = false, bool altDown = false );
 

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

     void SetCaptionBackgroundColour(const wxColour& col);
 
     void SetCaptionBackgroundColour(const wxColour& col);
 

-    /** Sets category caption text colour. */
+    /**
+        Sets category caption text colour.
+    */

     void SetCaptionTextColour(const wxColour& col);
 
     void SetCaptionTextColour(const wxColour& col);
 

-    /** Sets default cell background colour - applies to property cells.
+    /**
+        Sets default cell background colour - applies to property cells.

         Note that appearance of editor widgets may not be affected.
     */
     void SetCellBackgroundColour(const wxColour& col);
 
         Note that appearance of editor widgets may not be affected.
     */
     void SetCellBackgroundColour(const wxColour& col);
 

-    /** Sets cell text colour for disabled properties.
+    /**
+        Sets cell text colour for disabled properties.

     */
     void SetCellDisabledTextColour(const wxColour& col);
 
     */
     void SetCellDisabledTextColour(const wxColour& col);
 

-    /** Sets default cell text colour - applies to property name and value text.
+    /**
+        Sets default cell text colour - applies to property name and value text.

         Note that appearance of editor widgets may not be affected.
     */
     void SetCellTextColour(const wxColour& col);
 
         Note that appearance of editor widgets may not be affected.
     */
     void SetCellTextColour(const wxColour& col);
 

-    /** Set number of columns (2 or more).
+    /**
+        Set number of columns (2 or more).

     */
     */

-    void SetColumnCount( int colCount )
-    {
-        m_pState->SetColumnCount(colCount);
-        Refresh();
-    }
+    void SetColumnCount( int colCount );

 
 

-    /** Sets the 'current' category - Append will add non-category properties under it.
+    /**
+        Sets the 'current' category - Append will add non-category properties
+        under it.

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

-    /** Sets colour of empty space below properties. */
+    /**
+        Sets colour of empty space below properties.
+    */

     void SetEmptySpaceColour(const wxColour& col);
 
     void SetEmptySpaceColour(const wxColour& col);
 

-    /** Sets colour of lines between cells. */
+    /**
+        Sets colour of lines between cells.
+    */

     void SetLineColour(const wxColour& col);
 
     void SetLineColour(const wxColour& col);
 

-    /** Sets background colour of margin. */
+    /**
+        Sets background colour of margin.
+    */

     void SetMarginColour(const wxColour& col);
 
     void SetMarginColour(const wxColour& col);
 

-    /** Sets property attribute for all applicapple properties.
-        Be sure to use this method only after all properties have been
-        added to the grid.
+    /**
+        Set entire new selection from given list of properties.

     */
     */

-    void SetPropertyAttributeAll( const wxString& attrName, wxVariant value );
+    void SetSelection( const wxArrayPGProperty& newSelection );

 
 

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

     */
     */

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

 
 

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

     */
     */

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

 
 

-    /** Sets text colour of property and all its children.
-    */
-    void SetPropertyTextColour( wxPGPropArg id, const wxColour& col, bool recursively = true );

 
 

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

 
 

-    /** Sets selection foreground colour - applies to selected property name text. */
-    void SetSelectionTextColour(const wxColour& col);
+        @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

 
 

-    /** Sets x coordinate of the splitter.

         @remarks
         @remarks

-        Splitter position cannot exceed grid size, and therefore setting it during
-        form creation may fail as initial grid size is often smaller than desired
-        splitter position, especially when sizers are being used.
+            Default property sort function sorts properties by their labels
+            (case-insensitively).
+
+        @see GetSortFunction, wxPropertyGridInterface::Sort,
+             wxPropertyGridInterface::SortChildren

     */
     */

-    void SetSplitterPosition( int newxpos, int col = 0 )
-    {
-        DoSetSplitterPosition_(newxpos, true, col);
-        m_iFlags |= wxPG_FL_SPLITTER_PRE_SET;
-    }
+    void SetSortFunction( wxPGSortCallback sortFunction );

 
 

-    /** Set virtual width for this particular page. Width -1 indicates that the
-        virtual width should be disabled. */
-    void SetVirtualWidth( int width );
+    /**
+        Sets x coordinate of the splitter.

 
 

-    /** Sets name of a property.
-        @param id
-        Name or pointer of property which name to change.
-        @param newname
-        New name.
+        @remarks Splitter position cannot exceed grid size, and therefore setting
+                it during form creation may fail as initial grid size is often
+                smaller than desired splitter position, especially when sizers
+                are being used.

     */
     */

-    void SetPropertyName( wxPGPropArg id, const wxString& newname )
-    {
-        wxPG_PROP_ARG_CALL_PROLOG()
-        DoSetPropertyName( p, newname );
-    }
+    void SetSplitterPosition( int newxpos, int col = 0 );

 
 

-    /** Moves splitter as left as possible, while still allowing all
+    /**
+        Moves splitter as left as possible, while still allowing all

         labels to be shown in full.
         labels to be shown in full.

-        @param subProps
-        If false, will still allow sub-properties (ie. properties which
-        parent is not root or category) to be cropped.
+
+        @param privateChildrenToo
+            If @false, will still allow private children to be cropped.

     */
     */

-    void SetSplitterLeft( bool subProps = false )
-    {
-        m_pState->SetSplitterLeft(subProps);
-    }
+    void SetSplitterLeft( bool privateChildrenToo = false );

 
 

-    /** Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
+    /**
+        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.
         height. Value of 2 should be default on most platforms.

-        @remarks
-        On wxMSW, wxComboBox, when used as property editor widget, will spill
-        out with anything less than 3.

     */
     */

-    void SetVerticalSpacing( int vspacing )
-    {
-        m_vspacing = (unsigned char)vspacing;
-        CalculateFontAndBitmapStuff( vspacing );
-        if ( !m_pState->m_itemsAdded ) Refresh();
-    }
+    void SetVerticalSpacing( int vspacing );
+
+
+    /**
+        @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.

 
 

-    /** Shows an brief error message that is related to a property. */
-    void ShowPropertyError( wxPGPropArg id, const wxString& msg )
-    {
-        wxPG_PROP_ARG_CALL_PROLOG()
-        DoShowPropertyError(p, msg);
-    }
+        @see wxPGProperty::OnEvent()
+    */
+    void EditorsValueWasModified();

 
 

-    /** Sorts all items at all levels (except sub-properties). */
-    void Sort();
+    /**
+        Reverse of EditorsValueWasModified().

 
 

-    /** Sorts children of a category.
+        @remarks This function should only be called by custom properties.

     */
     */

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

 };
 
 
 };
 
 

-/** @class wxPropertyGridEvent
+/**
+    @class wxPropertyGridEvent

 
 

-    A propertygrid event holds information about events associated with
+    A property grid event holds information about events associated with

     wxPropertyGrid objects.
 
     @library{wxpropgrid}
     wxPropertyGrid objects.
 
     @library{wxpropgrid}


@@ -761,79 +1106,95 @@ public:
     /** Destructor. */
     ~wxPropertyGridEvent();
 
     /** Destructor. */
     ~wxPropertyGridEvent();
 

-    /** Copyer. */
-    virtual wxEvent* Clone() const;
+    /**
+        Returns true if you can veto the action that the event is signaling.
+    */
+    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
+        children.

 
 

-    wxPGProperty* GetMainParent() const
-    {
-        wxASSERT(m_property);
-        return m_property->GetMainParent();
-    }
+        @remarks If immediate parent is root or category, this will return the
+                property itself.
+    */
+    wxPGProperty* GetMainParent() const;

 
 

-    /** Returns id of associated property. */
-    wxPGProperty* GetProperty() const
-    {
-        return m_property;
-    }
+    /**
+        Returns property associated with this event.
+    */
+    wxPGProperty* GetProperty() const;

 
 

-    wxPGValidationInfo& GetValidationInfo()
-    {
-        wxASSERT(m_validationInfo);
-        return *m_validationInfo;
-    }
+    /**
+        Returns current validation failure flags.
+    */
+    wxPGVFBFlags GetValidationFailureBehavior() const;

 
 

-    /** Returns true if event has associated property. */
-    bool HasProperty() const { return ( m_property != (wxPGProperty*) NULL ); }
+    /**
+        Returns name of the associated property.

 
 

-    /** Returns true if you can veto the action that the event is signaling.
+        @remarks Property name is stored in event, so it remains
+                 accessible even after the associated property or
+                 the property grid has been deleted.

     */
     */

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

 
 

-    /** Call this from your event handler to veto action that the event is signaling.
-        You can only veto a shutdown if wxPropertyGridEvent::CanVeto returns true.
-        @remarks
-        Currently only wxEVT_PG_CHANGING supports vetoing.
+    /**
+        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.

     */
     */

-    void Veto( bool veto = true ) { m_wasVetoed = veto; }
+    wxVariant GetPropertyValue() const

 
 

-    /** Returns value that is about to be set for wxEVT_PG_CHANGING.
+    /**
+        @see GetPropertyValue()

     */
     */

-    const wxVariant& GetValue() const
-    {
-        wxASSERT_MSG( m_validationInfo,
-                      wxT("Only call GetValue from a handler of event type that supports it") );
-        return *m_validationInfo->m_pValue;
-    }
+    wxVariant GetValue() const;

 
 

-    /** Set override validation failure behavior. Only effective if Veto was also called,
-        and only allowed if event type is wxEVT_PG_CHANGING.
+    /**
+        Set if event can be vetoed.

     */
     */

-    void SetValidationFailureBehavior( int flags )
-    {
-        wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
-        m_validationInfo->m_failureBehavior = (wxPGVFBFlags) flags;
-    }
+    void SetCanVeto( bool canVeto );

 
 

-    /** Sets custom failure message for this time only. Only applies if
-        wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
+    /** 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.

     */
     */

-    void SetValidationFailureMessage( const wxString& message )
-    {
-        wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
-        m_validationInfo->m_failureMessage = message;
-    }
+    void SetValidationFailureBehavior( wxPGVFBFlags flags );

 
 

-    wxPGVFBFlags GetValidationFailureBehavior() const
-    {
-        wxASSERT( GetEventType() == wxEVT_PG_CHANGING );
-        return m_validationInfo->m_failureBehavior;
-    }
+    /**
+        Sets custom failure message for this time only. Only applies if
+        wxPG_VFB_SHOW_MESSAGE is set in validation failure flags.
+    */
+    void SetValidationFailureMessage( const wxString& message );

 
 

-    void SetCanVeto( bool canVeto ) { m_canVeto = canVeto; }
-    bool WasVetoed() const { return m_wasVetoed; }
+    /**
+        Call this from your event handler to veto action that the event is
+        signaling. You can only veto a shutdown if wxPropertyGridEvent::CanVeto()
+        returns true.

 
 

-    /** Changes the associated property. */
-    void SetProperty( wxPGProperty* p ) { m_property = p; }
+        @remarks Currently only wxEVT_PG_CHANGING supports vetoing.
+    */
+    void Veto( bool veto = true );

 
 

-    void SetPropertyGrid( wxPropertyGrid* pg ) { m_pg = pg; }
+    /**
+        Returns @true if event was vetoed.
+    */
+    bool WasVetoed() const;

 };
 };