Minor tweak to improve understandability

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

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

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

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


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

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

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


@@ -209,7 +209,7 @@ wxPG_EX_TOOLBAR_SEPARATOR               = 0x08000000
 // -----------------------------------------------------------------------
 
 /**
 // -----------------------------------------------------------------------
 
 /**

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

     @{
 */
 
     @{
 */
 


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


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

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


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

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

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


@@ -273,7 +294,7 @@ public:
     */
     wxVariant& GetValue();
 
     */
     wxVariant& GetValue();
 

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

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


@@ -299,11 +320,32 @@ public:
 enum wxPG_KEYBOARD_ACTIONS
 {
     wxPG_ACTION_INVALID = 0,
 enum wxPG_KEYBOARD_ACTIONS
 {
     wxPG_ACTION_INVALID = 0,

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

     wxPG_ACTION_NEXT_PROPERTY,
     wxPG_ACTION_NEXT_PROPERTY,

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

     wxPG_ACTION_PREV_PROPERTY,
     wxPG_ACTION_PREV_PROPERTY,

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

     wxPG_ACTION_EXPAND_PROPERTY,
     wxPG_ACTION_EXPAND_PROPERTY,

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

     wxPG_ACTION_COLLAPSE_PROPERTY,
     wxPG_ACTION_COLLAPSE_PROPERTY,

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

     wxPG_ACTION_CANCEL_EDIT,
     wxPG_ACTION_CANCEL_EDIT,

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

     wxPG_ACTION_MAX
 };
 
     wxPG_ACTION_MAX
 };
 


@@ -359,53 +401,53 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
 
     @beginEventEmissionTable{wxPropertyGridEvent}
     @event{EVT_PG_SELECTED (id, func)}
 
     @beginEventEmissionTable{wxPropertyGridEvent}
     @event{EVT_PG_SELECTED (id, func)}

-        Respond to wxEVT_PG_SELECTED event, generated when a property selection
+        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)}
         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
+        Respond to @c wxEVT_PG_CHANGED event, generated when property value

         has been changed by the user.
     @event{EVT_PG_CHANGING(id, func)}
         has been changed by the user.
     @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.
     @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}
         a property or category.
     @event{EVT_PG_LABEL_EDIT_BEGIN(id, func)}

-        Respond to wxEVT_PG_LABEL_EDIT_BEGIN event, generated when user is
+        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)}
         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
+        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)}
         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
+        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)}
         starts resizing a column - can be vetoed.
     @event{EVT_PG_COL_DRAGGING,(id, func)}

-        Respond to wxEVT_PG_COL_DRAGGING, event, generated when a
+        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)}
         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
+        Respond to @c wxEVT_PG_COL_END_DRAG event, generated after column

         resize by user has finished.
     @endEventTable
 
         resize by user has finished.
     @endEventTable
 


@@ -418,7 +460,9 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
     @category{propgrid}
     @appearance{propertygrid.png}
 */
     @category{propgrid}
     @appearance{propertygrid.png}
 */

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

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


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

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

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


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

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

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


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

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

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


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


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

-                const wxChar* name = wxPropertyGridNameStr );
+                const wxString& name = wxPropertyGridNameStr );
+
+    /**
+        Dedicates a specific keycode to wxPropertyGrid. This means that such
+        key presses will not be redirected to editor controls.
+
+        Using this function allows, for example, navigation between
+        properties using arrow keys even when the focus is in the editor
+        control.
+    */
+    void DedicateKey( int keycode );

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


@@ -770,7 +833,7 @@ public:
 
         @param pt
             Coordinates in the virtual grid space. You may need to use
 
         @param pt
             Coordinates in the virtual grid space. You may need to use

-            wxScrolledWindow::CalcScrolledPosition() for translating
+            wxScrolled<T>::CalcScrolledPosition() for translating

             wxPropertyGrid client coordinates into something this member
             function can use.
     */
             wxPropertyGrid client coordinates into something this member
             function can use.
     */


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

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

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

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

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


@@ -874,7 +941,7 @@ public:
         fails if current value in editor is not valid.
 
         @remarks In wxPropertyGrid 1.4, this member function used to generate
         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
+                 @c wxEVT_PG_SELECTED. In wxWidgets 2.9 and later, it no longer

                  does that.
 
         @remarks This clears any previous selection.
                  does that.
 
         @remarks This clears any previous selection.


@@ -883,14 +950,6 @@ public:
     */
     bool SelectProperty( wxPGPropArg id, bool focus = false );
 
     */
     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 );
-

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


@@ -1025,6 +1084,45 @@ public:
     */
     void SetVerticalSpacing( int vspacing );
 
     */
     void SetVerticalSpacing( int vspacing );
 

+    /**
+        @name wxPropertyGrid customization
+
+        Reimplement these member functions in derived class for better
+        control over wxPropertyGrid behaviour.
+    */
+    //@{
+
+    /**
+        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
 
     /**
         @name Property development functions


@@ -1134,7 +1232,7 @@ public:
         Returns property associated with this event.
 
         @remarks You should assume that this property can always be NULL.
         Returns property associated with this event.
 
         @remarks You should assume that this property can always be NULL.

-                 For instance, wxEVT_PG_SELECTED is emitted not only when
+                 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.
     */
                  a new property is selected, but also when selection is
                  cleared by user activity.
     */


@@ -1156,7 +1254,7 @@ public:
 
     /**
         Returns value of the associated property. Works for all event
 
     /**
         Returns value of the associated property. Works for all event

-        types, but for wxEVT_PG_CHANGING this member function returns
+        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.
 
         the value that is pending, so you can call Veto() if the
         value is not satisfactory.
 


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

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

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


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