]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/propgrid/propgrid.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / propgrid / propgrid.h
index 7ceeee2101208da59bcd59e351cc79db411d877b..21de0b07085604c2437d091a67174eaa56ad10d5 100644 (file)
@@ -2,7 +2,7 @@
 // Name:        propgrid.h
 // Purpose:     interface of wxPropertyGrid
 // Author:      wxWidgets team
-// RCS-ID:      $Id:
+// RCS-ID:      $Id$
 // Licence:     wxWindows license
 /////////////////////////////////////////////////////////////////////////////
 
@@ -32,7 +32,7 @@ wxPG_AUTO_SORT                      = 0x00000010,
 */
 wxPG_HIDE_CATEGORIES                = 0x00000020,
 
-/*
+/**
     This style combines non-categoric mode and automatic sorting.
 */
 wxPG_ALPHABETIC_MODE                = (wxPG_HIDE_CATEGORIES|wxPG_AUTO_SORT),
@@ -149,12 +149,6 @@ wxPG_EX_AUTO_UNSPECIFIED_VALUES         = 0x00200000,
 */
 wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES    = 0x00400000,
 
-/**
-    With this style Validators on properties will work same as in wxPropertyGrid
-    1.2.
-*/
-wxPG_EX_LEGACY_VALIDATORS               = 0x00800000,
-
 /**
     Hides page selection buttons from tool bar.
 */
@@ -215,10 +209,49 @@ wxPG_VFB_DEFAULT                    = wxPG_VFB_STAY_IN_PROPERTY|wxPG_VFB_BEEP,
 
 typedef wxByte wxPGVFBFlags;
 
+/**
+    wxPGValidationInfo
+
+    Used to convey validation information to and from functions that
+    actually perform validation. Mostly used in custom property classes.
+*/
+class wxPGValidationInfo
+{
+public:
+    /**
+        @return Returns failure behavior which is a combination of
+            @ref propgrid_vfbflags.
+    */
+    wxPGVFBFlags GetFailureBehavior();
+
+    /**
+        Returns current failure message.
+    */
+    const wxString& GetFailureMessage() const;
+
+    /**
+        Returns reference to pending value.
+    */
+    const wxVariant& GetValue() const;
+
+    /** Set validation failure behavior
+
+        @param failureBehavior
+            Mixture of @ref propgrid_vfbflags.
+    */
+    void SetFailureBehavior(wxPGVFBFlags failureBehavior);
+
+    /**
+        Set current failure message.
+    */
+    void SetFailureMessage(const wxString& message);
+};
+
 // -----------------------------------------------------------------------
 
 /**
     @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers
+
     These are used with wxPropertyGrid::AddActionTrigger() and
     wxPropertyGrid::ClearActionTriggers().
     @{
@@ -232,20 +265,39 @@ enum wxPG_KEYBOARD_ACTIONS
     wxPG_ACTION_EXPAND_PROPERTY,
     wxPG_ACTION_COLLAPSE_PROPERTY,
     wxPG_ACTION_CANCEL_EDIT,
-    wxPG_ACTION_CUT,
-    wxPG_ACTION_COPY,
-    wxPG_ACTION_PASTE,
     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 - in other
+    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,
@@ -266,7 +318,7 @@ enum wxPG_KEYBOARD_ACTIONS
     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)}
         Respond to wxEVT_PG_SELECTED event, generated when property value
         has been changed by user.
@@ -294,35 +346,34 @@ enum wxPG_KEYBOARD_ACTIONS
     @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}
+    @appearance{propertygrid.png}
 */
 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();
 
     /**
-        Constructor. The styles to be used are styles valid for
-        the wxWindow and wxScrolledWindow.
+        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,
-                           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();
@@ -332,10 +383,8 @@ public:
 
         @param action
             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.
@@ -397,10 +446,10 @@ public:
         @see @ref propgrid_window_styles.
     */
     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 );
+                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
@@ -411,21 +460,22 @@ public:
 
         @see wxPGProperty::OnEvent()
     */
-    void EditorsValueWasModified() { m_iFlags |= wxPG_FL_VALUE_MODIFIED; }
+    void EditorsValueWasModified();
 
     /**
         Reverse of EditorsValueWasModified().
 
         @remarks This function should only be called by custom properties.
     */
-    void EditorsValueWasNotModified()
-    {
-        m_iFlags &= ~(wxPG_FL_VALUE_MODIFIED);
-    }
+    void EditorsValueWasNotModified();
 
     /**
         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.
     */
     bool EnableCategories( bool enable );
 
@@ -492,7 +542,7 @@ public:
     /**
         Returns number of columns currently on grid.
     */
-    int GetColumnCount() const;
+    unsigned int GetColumnCount() const;
 
     /**
         Returns colour of empty space below properties.
@@ -554,14 +604,12 @@ public:
     wxColour GetMarginColour() const;
 
     /**
-        Returns cell background colour of a property.
+        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.
     */
-    wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
-
-    /**
-        Returns cell background colour of a property.
-    */
-    wxColour GetPropertyTextColour( wxPGPropArg id ) const;
+    wxVariant GetUncommittedPropertyValue();
 
     /**
         Returns "root property". It does not have name, etc. and it is not
@@ -594,6 +642,13 @@ public:
     */
     wxColour GetSelectionForegroundColour() const;
 
+    /**
+        Returns the property sort function (default is @NULL).
+
+        @see SetSortFunction
+    */
+    wxPGSortCallback GetSortFunction() const;
+
     /**
         Returns current splitter x position.
     */
@@ -608,7 +663,7 @@ public:
     /**
         Returns current vertical spacing.
     */
-    int GetVerticalSpacing() const { return (int)m_vspacing; }
+    int GetVerticalSpacing() const;
 
     /**
         Returns true if editor's value was marked modified.
@@ -617,6 +672,12 @@ public:
 
     /**
         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;
 
@@ -625,12 +686,22 @@ public:
     */
     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;
 
+    /**
+        Refreshes any active editor control.
+    */
+    void RefreshEditor();
+
     /**
         Redraws given property.
     */
@@ -730,32 +801,45 @@ public:
     void SetMarginColour(const wxColour& col);
 
     /**
-        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 the property sorting function.
 
-    /** Sets selection background colour - applies to selected property name
-        background. */
-    void SetSelectionBackgroundColour(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:
 
-    /** Sets selection foreground colour - applies to selected property name
-        text. */
-    void SetSelectionTextColour(const wxColour& col);
+            @code
+                int MyPropertySortFunction(wxPropertyGrid* propGrid,
+                                           wxPGProperty* p1,
+                                           wxPGProperty* p2)
+                {
+                    return p1->GetBaseName().compare( p2->GetBaseName() );
+                }
+            @endcode
+
+        @remarks
+            Default property sort function sorts properties by their labels
+            (case-insensitively).
 
-    /** Sets x coordinate of the splitter.
+        @see GetSortFunction, wxPropertyGridInterface::Sort,
+             wxPropertyGridInterface::SortChildren
+    */
+    void SetSortFunction( wxPGSortCallback sortFunction );
+
+    /**
+        Sets x coordinate of the splitter.
 
         @remarks Splitter position cannot exceed grid size, and therefore setting
                 it during form creation may fail as initial grid size is often
@@ -764,17 +848,6 @@ public:
     */
     void SetSplitterPosition( int newxpos, int col = 0 );
 
-    /**
-        Sets name of a property.
-
-        @param id
-            Name or pointer of property which name to change.
-
-        @param newname
-            New name.
-    */
-    void SetPropertyName( wxPGPropArg id, const wxString& newname );
-
     /**
         Moves splitter as left as possible, while still allowing all
         labels to be shown in full.
@@ -782,10 +855,7 @@ public:
         @param privateChildrenToo
             If @false, will still allow private children to be cropped.
     */
-    void SetSplitterLeft( bool privateChildrenToo = false )
-    {
-        m_pState->SetSplitterLeft(subProps);
-    }
+    void SetSplitterLeft( bool privateChildrenToo = false );
 
     /**
         Sets vertical spacing. Can be 1, 2, or 3 - a value relative to font
@@ -797,16 +867,6 @@ public:
         Shows an brief error message that is related to a property.
     */
     void ShowPropertyError( wxPGPropArg id, const wxString& msg );
-
-    /**
-        Sorts all items at all levels (except private children).
-    */
-    void Sort();
-
-    /**
-        Sorts children of a property.
-    */
-    void SortChildren( wxPGPropArg id );
 };
 
 
@@ -835,10 +895,7 @@ public:
     /**
         Returns true if you can veto the action that the event is signaling.
     */
-    bool CanVeto() const { return m_canVeto; }
-
-    /** Copyer. */
-    virtual wxEvent* Clone() const;
+    bool CanVeto() const;
 
     /**
         Returns highest level non-category, non-root parent of property for
@@ -869,7 +926,7 @@ public:
         Set if event can be vetoed.
     */
     void SetCanVeto( bool canVeto );
-    
+
     /** Changes the property associated with this event. */
     void SetProperty( wxPGProperty* p );
 
@@ -877,7 +934,7 @@ public:
         Set override validation failure behavior. Only effective if Veto() was
         also called, and only allowed if event type is wxEVT_PG_CHANGING.
     */
-    void SetValidationFailureBehavior( int flags );
+    void SetValidationFailureBehavior( wxPGVFBFlags flags );
 
     /**
         Sets custom failure message for this time only. Only applies if