X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/798c0d873bad83f0ac2d198b129858f9d4659da5..41d6e8b6833f5fb9b997c0cf0f0c9c37ebc589c3:/interface/wx/propgrid/propgrid.h diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h index aa33796266..3709af9cef 100644 --- 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. - @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. @@ -430,24 +451,6 @@ public: 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. @@ -582,14 +585,6 @@ public: */ 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 "root property". It does not have name, etc. and it is not visible. It is only useful for accessing its children. @@ -621,6 +616,13 @@ public: */ wxColour GetSelectionForegroundColour() const; + /** + Returns the property sort function (default is @NULL). + + @see SetSortFunction + */ + wxPGSortCallback GetSortFunction() const; + /** Returns current splitter x position. */ @@ -637,13 +639,14 @@ public: */ int GetVerticalSpacing() const; - /** - Returns true if editor's value was marked modified. - */ - bool IsEditorsValueModified() const; - /** 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; @@ -652,12 +655,32 @@ 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; + /** + 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. + + @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 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 ); + /** Refreshes any active editor control. */ @@ -772,6 +795,33 @@ public: */ 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. @@ -797,28 +847,64 @@ public: */ 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 ); + //@{ /** - Sorts all items at all levels (except private children). + 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 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. + @remarks This function should only be called by custom properties. + + @see wxPGProperty::OnEvent() */ - void Sort(); + void EditorsValueWasModified(); /** - Sorts children of a property. + Reverse of EditorsValueWasModified(). - @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. + @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; + + /** + Shows an brief error message that is related to a property. + */ + void ShowPropertyError( wxPGPropArg id, const wxString& msg ); + + /** + 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; + + //@} };