X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/020b004113a8ab9b9c42a9a56716f3a27b0a8621..5b88a837ba75928cd3835a6b97ae2bf5ad983a6e:/interface/wx/propgrid/propgrid.h diff --git a/interface/wx/propgrid/propgrid.h b/interface/wx/propgrid/propgrid.h index 04a8ac21ad..21de0b0708 100644 --- a/interface/wx/propgrid/propgrid.h +++ b/interface/wx/propgrid/propgrid.h @@ -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), @@ -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(). @{ @@ -265,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, @@ -299,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. @@ -327,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(); @@ -365,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. @@ -430,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 @@ -444,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 ); @@ -525,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. @@ -587,14 +604,12 @@ public: wxColour GetMarginColour() const; /** - Returns cell background colour of a property. - */ - wxColour GetPropertyBackgroundColour( wxPGPropArg id ) 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 GetPropertyTextColour( wxPGPropArg id ) const; + wxVariant GetUncommittedPropertyValue(); /** Returns "root property". It does not have name, etc. and it is not @@ -627,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. */ @@ -641,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. @@ -650,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; @@ -658,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. */ @@ -763,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 - /** 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 @@ -804,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 @@ -819,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 ); }; @@ -857,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 @@ -891,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 );