X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/404b9c623a3ecc5ae9e256cb60491c4ced77e03c..277806225e146740f73965b11375d387b02961b7:/interface/wx/propgrid/propgrid.h diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h index 202dd9c717..16c785c43d 100644 --- a/interface/wx/propgrid/propgrid.h +++ b/interface/wx/propgrid/propgrid.h @@ -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), @@ -213,15 +213,14 @@ typedef wxByte wxPGVFBFlags; wxPGValidationInfo Used to convey validation information to and from functions that - actually perform validation. Mostly used in custom property - classes. + actually perform validation. Mostly used in custom property classes. */ class wxPGValidationInfo { public: /** @return Returns failure behavior which is a combination of - @ref propgrid_vfbflags. + @ref propgrid_vfbflags. */ wxPGVFBFlags GetFailureBehavior(); @@ -252,6 +251,7 @@ public: /** @section propgrid_keyboard_actions wxPropertyGrid Action Identifiers + These are used with wxPropertyGrid::AddActionTrigger() and wxPropertyGrid::ClearActionTriggers(). @{ @@ -271,11 +271,33 @@ 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); + // ----------------------------------------------------------------------- -/** @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, @@ -324,37 +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(); @@ -364,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. @@ -429,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 @@ -443,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 ); @@ -593,16 +611,6 @@ public: */ 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. @@ -634,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. */ @@ -648,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. @@ -672,20 +687,9 @@ public: bool IsFrozen() const; /** - When creating custom property editors, connect required editor events to - this function. For instance: - - @code - control->Connect(control->GetId(), wxEVT_COMMAND_TEXT_UPDATED, - wxEventHandler(wxPropertyGrid::OnCustomEditorEvent), - NULL, propgrid); - @endcode - - @remarks You should never need to call this function directly! - - @see wxPGEditor::CreateControls(), wxEvtHandler::Connect() + Refreshes any active editor control. */ - void OnCustomEditorEvent( wxEvent &event ); + void RefreshEditor(); /** Redraws given property. @@ -786,32 +790,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 - /** Sets x coordinate of the splitter. + @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. @remarks Splitter position cannot exceed grid size, and therefore setting it during form creation may fail as initial grid size is often @@ -827,10 +844,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 @@ -842,16 +856,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 ); }; @@ -880,10 +884,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 @@ -914,7 +915,7 @@ public: Set if event can be vetoed. */ void SetCanVeto( bool canVeto ); - + /** Changes the property associated with this event. */ void SetProperty( wxPGProperty* p );