]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/propgrid/propgrid.h
synchronize GTK2 minimum version in docs
[wxWidgets.git] / interface / wx / propgrid / propgrid.h
index c9bc3dfc0af7b060a59456c4ee1bfffdc157cee2..3ab534149fa482c945b3af3eaf66c52b5367743f 100644 (file)
@@ -3,7 +3,7 @@
 // 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
-    behavior stops once the user manually moves the splitter.
+    behaviour stops once the user manually moves the splitter.
 */
 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
-    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,
 
@@ -233,14 +233,35 @@ wxPG_VFB_BEEP                       = 0x02,
 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,
 
+/**
+    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.
 */
-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:
     /**
-        @return Returns failure behavior which is a combination of
+        @return Returns failure behaviour which is a combination of
             @ref propgrid_vfbflags.
     */
     wxPGVFBFlags GetFailureBehavior();
@@ -273,7 +294,7 @@ public:
     */
     wxVariant& GetValue();
 
-    /** Set validation failure behavior
+    /** Set validation failure behaviour
 
         @param failureBehavior
             Mixture of @ref propgrid_vfbflags.
@@ -299,11 +320,32 @@ public:
 enum wxPG_KEYBOARD_ACTIONS
 {
     wxPG_ACTION_INVALID = 0,
+
+    /** Select the next property. */
     wxPG_ACTION_NEXT_PROPERTY,
+
+    /** Select the previous property. */
     wxPG_ACTION_PREV_PROPERTY,
+
+    /** Expand the selected property, if it has child items. */
     wxPG_ACTION_EXPAND_PROPERTY,
+
+    /** Collapse the selected property, if it has child items. */
     wxPG_ACTION_COLLAPSE_PROPERTY,
+
+    /** Cancel and undo any editing done in the currently active property
+        editor.
+    */
     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
 };
 
@@ -359,50 +401,53 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
 
     @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)}
+        Respond to @c 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
+        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)}
-        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)}
-        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)}
-        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)}
-        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)}
-        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)}
-        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)}
-        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 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)}
-        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)}
-        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
 
@@ -415,7 +460,9 @@ typedef int (*wxPGSortCallback)(wxPropertyGrid* propGrid,
     @category{propgrid}
     @appearance{propertygrid.png}
 */
-class wxPropertyGrid : public wxScrolledWindow, public wxPropertyGridInterface
+class wxPropertyGrid : public wxControl,
+                       public wxScrollHelper,
+                       public wxPropertyGridInterface
 {
 public:
     /**
@@ -426,7 +473,7 @@ public:
 
     /**
         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.
     */
@@ -434,7 +481,7 @@ public:
                     const wxPoint& pos = wxDefaultPosition,
                     const wxSize& size = wxDefaultSize,
                     long style = wxPG_DEFAULT_STYLE,
-                    const wxChar* name = wxPropertyGridNameStr );
+                    const wxString& name = wxPropertyGridNameStr );
 
     /** Destructor */
     virtual ~wxPropertyGrid();
@@ -442,6 +489,15 @@ public:
     /**
         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
@@ -488,7 +544,7 @@ public:
 
         @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
@@ -500,11 +556,13 @@ public:
     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.
@@ -521,7 +579,7 @@ public:
 
     /**
         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.
@@ -539,7 +597,17 @@ public:
                 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
@@ -732,7 +800,7 @@ public:
     /**
         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
@@ -740,6 +808,13 @@ public:
     */
     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.
@@ -758,7 +833,7 @@ public:
 
         @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.
     */
@@ -783,6 +858,8 @@ public:
     /**
         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.
 
@@ -815,12 +892,16 @@ public:
     */
     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.
     */
-    static wxPGEditor* RegisterEditorClass( wxPGEditor* editor,
+    static wxPGEditor* DoRegisterEditorClass( wxPGEditor* editor,
                                             const wxString& name,
                                             bool noDefCheck = false );
 
@@ -829,6 +910,17 @@ public:
     */
     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.
@@ -849,7 +941,7 @@ public:
         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.
@@ -858,14 +950,6 @@ public:
     */
     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.
     */
@@ -981,12 +1065,64 @@ public:
     */
     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 );
 
+    /**
+        @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
@@ -1094,6 +1230,11 @@ public:
 
     /**
         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;
 
@@ -1113,7 +1254,7 @@ public:
 
     /**
         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.
 
@@ -1137,8 +1278,8 @@ public:
     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 );
 
@@ -1153,7 +1294,7 @@ public:
         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 );