No changes, just removed the whitespace.

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

diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h
index eec0ae384295607a2f6410d95ee9b7de396ac39a..3709af9cef10dfa406c37f48eecf344743b223f0 100644 (file)
--- a/interface/wx/propgrid/propgrid.h
+++ b/interface/wx/propgrid/propgrid.h
@@ -271,6 +271,27 @@ enum wxPG_KEYBOARD_ACTIONS
 /** @}
 */
 
 /** @}
 */
 

+/** 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);
+

 // -----------------------------------------------------------------------
 
 /**
 // -----------------------------------------------------------------------
 
 /**


@@ -297,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.
 
     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.
     @event{EVT_PG_SELECTED (id, func)}
         Respond to wxEVT_PG_SELECTED event, generated when property value
         has been changed by user.


@@ -430,27 +451,13 @@ public:
                 long style = wxPG_DEFAULT_STYLE,
                 const wxChar* name = wxPropertyGridNameStr );
 
                 long style = wxPG_DEFAULT_STYLE,
                 const wxChar* name = wxPropertyGridNameStr );
 

-    /**
-        Call when editor widget's contents is modified. For example, this is
-        called when changes text in wxTextCtrl (used in wxStringProperty and
-        wxIntProperty).
-
-        @remarks This function should only be called by custom properties.
-
-        @see wxPGProperty::OnEvent()
-    */
-    void EditorsValueWasModified();
-
-    /**
-        Reverse of EditorsValueWasModified().
-
-        @remarks This function should only be called by custom properties.
-    */
-    void EditorsValueWasNotModified();
-

     /**
         Enables or disables (shows/hides) categories according to parameter
         enable.
     /**
         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 );
 
     */
     bool EnableCategories( bool enable );
 


@@ -578,24 +585,6 @@ public:
     */
     wxColour GetMarginColour() const;
 
     */
     wxColour GetMarginColour() const;
 

-    /**
-        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.
-    */
-    wxVariant GetUncommittedPropertyValue();
-
-    /**
-        Returns cell background colour of a property.
-    */
-    wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const;
-
-    /**
-        Returns cell background colour of a property.
-    */
-    wxColour GetPropertyTextColour( wxPGPropArg id ) const;
-

     /**
         Returns "root property". It does not have name, etc. and it is not
         visible. It is only useful for accessing its children.
     /**
         Returns "root property". It does not have name, etc. and it is not
         visible. It is only useful for accessing its children.


@@ -627,6 +616,13 @@ public:
     */
     wxColour GetSelectionForegroundColour() const;
 
     */
     wxColour GetSelectionForegroundColour() const;
 

+    /**
+        Returns the property sort function (default is @NULL).
+
+        @see SetSortFunction
+    */
+    wxPGSortCallback GetSortFunction() const;
+

     /**
         Returns current splitter x position.
     */
     /**
         Returns current splitter x position.
     */


@@ -643,13 +639,14 @@ public:
     */
     int GetVerticalSpacing() const;
 
     */
     int GetVerticalSpacing() const;
 

-    /**
-        Returns true if editor's value was marked modified.
-    */
-    bool IsEditorsValueModified() const;
-

     /**
         Returns information about arbitrary position in the grid.
     /**
         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;
 
     */
     wxPropertyGridHitTestResult HitTest( const wxPoint& pt ) const;
 


@@ -658,6 +655,11 @@ public:
     */
     bool IsAnyModified() const;
 
     */
     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() ).
     /**
         Returns true if updating is frozen (ie. Freeze() called but not
         yet Thaw() ).


@@ -665,20 +667,24 @@ public:
     bool IsFrozen() const;
 
     /**
     bool IsFrozen() const;
 
     /**

-        When creating custom property editors, connect required editor events to
-        this function. For instance:
+        It is recommended that you call this function any time your code causes
+        wxPropertyGrid's top-level parent to change. wxPropertyGrid's OnIdle()
+        handler should be able to detect most changes, but it is not perfect.

 
 

-        @code
-            control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED,
-                            wxEventHandler(wxPropertyGrid::OnCustomEditorEvent),
-                            NULL, propgrid);
-        @endcode
+        @param newTLP
+            New top-level parent that is about to be set. Old top-level parent
+            window should still exist as the current one.

 
 

-        @remarks You should never need to call this function directly!
+        @remarks This function is automatically called from wxPropertyGrid::
+                 Reparent() and wxPropertyGridManager::Reparent(). You only
+                 need to use it if you reparent wxPropertyGrid indirectly.
+    */
+    void OnTLPChanging( wxWindow* newTLP );

 
 

-        @see wxPGEditor::CreateControls(), wxEvtHandler::Connect()
+    /**
+        Refreshes any active editor control.

     */
     */

-    void OnCustomEditorEvent( wxEvent &event );
+    void RefreshEditor();

 
     /**
         Redraws given property.
 
     /**
         Redraws given property.


@@ -778,24 +784,6 @@ public:
     */
     void SetMarginColour(const wxColour& col);
 
     */
     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.
-    */
-    void SetPropertyBackgroundColour( wxPGPropArg id, const wxColour& col );
-
-    /**
-        Resets text and background colours of given property.
-    */
-    void SetPropertyColoursToDefault( wxPGPropArg id );
-
-    /**
-        Sets text colour of property and all its children.
-    */
-    void SetPropertyTextColour( wxPGPropArg id, const wxColour& col,
-                                bool recursively = true );
-

     /**
         Sets selection background colour - applies to selected property name
         background.
     /**
         Sets selection background colour - applies to selected property name
         background.


@@ -807,6 +795,33 @@ public:
     */
     void SetSelectionTextColour(const wxColour& col);
 
     */
     void SetSelectionTextColour(const wxColour& col);
 

+
+    /**
+        Sets the property sorting function.
+
+        @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:
+
+            @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).
+
+        @see GetSortFunction, wxPropertyGridInterface::Sort,
+             wxPropertyGridInterface::SortChildren
+    */
+    void SetSortFunction( wxPGSortCallback sortFunction );
+

     /**
         Sets x coordinate of the splitter.
 
     /**
         Sets x coordinate of the splitter.
 


@@ -832,20 +847,64 @@ public:
     */
     void SetVerticalSpacing( int vspacing );
 
     */
     void SetVerticalSpacing( int vspacing );
 

+

     /**
     /**

-        Shows an brief error message that is related to a property.
+        @name Property development functions
+
+        These member functions are usually only called when creating custom
+        user properties.

     */
     */

-    void ShowPropertyError( wxPGPropArg id, const wxString& msg );
+    //@{
+
+    /**
+        Call when editor widget's contents is modified. For example, this is
+        called when changes text in wxTextCtrl (used in wxStringProperty and
+        wxIntProperty).
+
+        @remarks This function should only be called by custom properties.
+
+        @see wxPGProperty::OnEvent()
+    */
+    void EditorsValueWasModified();
+
+    /**
+        Reverse of EditorsValueWasModified().
+
+        @remarks This function should only be called by custom properties.
+    */
+    void EditorsValueWasNotModified();
+
+    /**
+        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.
+    */
+    wxVariant GetUncommittedPropertyValue();
+
+    /**
+        Returns true if editor's value was marked modified.
+    */
+    bool IsEditorsValueModified() const;

 
     /**
 
     /**

-        Sorts all items at all levels (except private children).
+        Shows an brief error message that is related to a property.

     */
     */

-    void Sort();
+    void ShowPropertyError( wxPGPropArg id, const wxString& msg );

 
     /**
 
     /**

-        Sorts children of a property.
+        You can use this member function, for instance, to detect in
+        wxPGProperty::OnEvent() if wxPGProperty::SetValueInEvent() was
+        already called in wxPGEditor::OnEvent(). It really only detects
+        if was value was changed using wxPGProperty::SetValueInEvent(), which
+        is usually used when a 'picker' dialog is displayed. If value was
+        written by "normal means" in wxPGProperty::StringToValue() or
+        IntToValue(), then this function will return false (on the other hand,
+        wxPGProperty::OnEvent() is not even called in those cases).

     */
     */

-    void SortChildren( wxPGPropArg id );
+    bool WasValueChangedInEvent() const;
+
+    //@}

 };
 
 
 };
 
 


@@ -876,9 +935,6 @@ public:
     */
     bool CanVeto() const;
 
     */
     bool CanVeto() const;
 

-    /** Copyer. */
-    virtual wxEvent* Clone() 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