Use single quotes in wxMarkupText unit test to work around VC6 bug.

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

diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h
index 665674620b535771bd83cc9d09342da486a9d500..e4b3d7b2c16d36d8bdd56953f4906441a9d5b25c 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

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


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


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

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


@@ -270,7 +292,7 @@ public:
     /**
         Returns reference to pending value.
     */
     /**
         Returns reference to pending value.
     */

-    const wxVariant& GetValue() const;
+    wxVariant& GetValue();

 
     /** Set validation failure behavior
 
 
     /** Set validation failure behavior
 


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


@@ -583,7 +663,7 @@ public:
         Returns wxWindow that the properties are painted on, and which should be
         used as the parent for editor controls.
     */
         Returns wxWindow that the properties are painted on, and which should be
         used as the parent for editor controls.
     */

-    wxPanel* GetPanel() const;
+    wxWindow* GetPanel();

 
     /**
         Returns current category caption background colour.
 
     /**
         Returns current category caption background colour.


@@ -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 behavior.
+    */
+    //@{
+
+    /**
+        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 behavior 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;
 


@@ -1076,9 +1248,30 @@ public:
     wxPGVFBFlags GetValidationFailureBehavior() const;
 
     /**
     wxPGVFBFlags GetValidationFailureBehavior() const;
 
     /**

-        Returns value that is about to be set for wxEVT_PG_CHANGING.
+        Returns name of the associated property.
+
+        @remarks Property name is stored in event, so it remains
+                 accessible even after the associated property or
+                 the property grid has been deleted.
+    */
+    wxString GetPropertyName() const;
+
+    /**
+        Returns value of the associated property. Works for all event
+        types, but for @c wxEVT_PG_CHANGING this member function returns
+        the value that is pending, so you can call Veto() if the
+        value is not satisfactory.
+
+        @remarks Property value is stored in event, so it remains
+                 accessible even after the associated property or
+                 the property grid has been deleted.
+    */
+    wxVariant GetPropertyValue() const
+
+    /**
+        @see GetPropertyValue()

     */
     */

-    const wxVariant& GetValue() const;
+    wxVariant GetValue() const;

 
     /**
         Set if event can be vetoed.
 
     /**
         Set if event can be vetoed.


@@ -1090,7 +1283,7 @@ public:
 
     /**
         Set override validation failure behavior. Only effective if Veto() was
 
     /**
         Set override validation failure behavior. Only effective if Veto() was

-        also called, and only allowed if event type is wxEVT_PG_CHANGING.
+        also called, and only allowed if event type is @c wxEVT_PG_CHANGING.

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


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