Added drawing context to allow 'virtual' (dynamic) attributes, for e.g. showing bookm...

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

diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h
index d206fa37f0d685a7d477671bcffff3ce674b5cbf..7de8048cdbb9b3e24e54fd34a8a488ce57395780 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,
 


@@ -91,7 +91,8 @@ wxPG_TOOLBAR                        = 0x00001000,
 */
 wxPG_DESCRIPTION                    = 0x00002000,
 
 */
 wxPG_DESCRIPTION                    = 0x00002000,
 

-/** wxPropertyGridManager only: don't show an internal border around the property grid
+/** wxPropertyGridManager only: don't show an internal border around the
+    property grid. Recommended if you use a header.

 */
 wxPG_NO_INTERNAL_BORDER             = 0x00004000
 
 */
 wxPG_NO_INTERNAL_BORDER             = 0x00004000
 


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

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

     @{
 */
 
     @{
 */
 


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


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

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


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


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


@@ -298,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
 };
 


@@ -358,40 +401,54 @@ 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.
         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.
     @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 is about to
-        begin editing a property label. You can veto this event to prevent the
-        action.
+        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)}
     @event{EVT_PG_LABEL_EDIT_ENDING(id, func)}

-        Respond to wxEVT_PG_LABEL_EDIT_ENDING event, generated when is about to
-        end editing of a property label. You can veto this event to prevent the
-        action.
+        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


@@ -403,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:
     /**


@@ -414,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.
     */


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


@@ -476,7 +544,7 @@ public:
 
         @see EndLabelEdit(), MakeColumnEditable()
     */
 
         @see EndLabelEdit(), MakeColumnEditable()
     */

-    void BeginLabelEdit( unsigned int column = 0 );
+    void BeginLabelEdit( unsigned int colIndex = 0 );

 
     /**
         Changes value of a property, as if from an editor. Use this instead of
 
     /**
         Changes value of a property, as if from an editor. Use this instead of


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


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


@@ -529,6 +599,16 @@ public:
                 long style = wxPG_DEFAULT_STYLE,
                 const wxChar* name = wxPropertyGridNameStr );
 
                 long style = wxPG_DEFAULT_STYLE,
                 const wxChar* 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
         enable.
     /**
         Enables or disables (shows/hides) categories according to parameter
         enable.


@@ -720,7 +800,7 @@ public:
     /**
         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


@@ -728,6 +808,21 @@ public:
     */
     wxTextCtrl* GetEditorTextCtrl() const;
 
     */
     wxTextCtrl* GetEditorTextCtrl() const;
 

+    /**
+        Returns current appearance of unspecified value cells.
+
+        @see SetUnspecifiedValueAppearance()
+    */
+    const wxPGCell& GetUnspecifiedValueAppearance() const;
+
+    /**
+        Returns (visual) text representation of the unspecified
+        property value.
+
+        @param argFlags For internal use only.
+    */
+    wxString GetUnspecifiedValueText( int argFlags = 0 ) const;
+

     /**
         Returns current vertical spacing.
     */
     /**
         Returns current vertical spacing.
     */


@@ -738,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.
     */


@@ -763,6 +858,8 @@ public:
     /**
         Makes given column editable by user.
 
     /**
         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.
 
         @param editable
             Using @false here will disable column from being editable.
 


@@ -809,6 +906,17 @@ 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.
     /**
         Removes given property from selection. If property is not selected,
         an assertion failure will occur.


@@ -829,7 +937,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.


@@ -961,12 +1069,64 @@ public:
     */
     void SetSplitterLeft( bool privateChildrenToo = false );
 
     */
     void SetSplitterLeft( bool privateChildrenToo = false );
 

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

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


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

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

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


@@ -1067,6 +1234,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;
 


@@ -1086,7 +1258,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.
 


@@ -1110,8 +1282,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 );
 


@@ -1126,7 +1298,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 );