X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/088441b57cb88b8c04f8a03a7be5a5744aac6187..3beb50e570f1b4f7a97c767677451ffc558fa22f:/interface/wx/propgrid/propgridiface.h?ds=sidebyside diff --git a/interface/wx/propgrid/propgridiface.h b/interface/wx/propgrid/propgridiface.h index 36f1bfc1a9..dba072c5e5 100644 --- a/interface/wx/propgrid/propgridiface.h +++ b/interface/wx/propgrid/propgridiface.h @@ -3,7 +3,7 @@ // Purpose: interface of wxPGProperty // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// // ----------------------------------------------------------------------- @@ -91,6 +91,12 @@ public: @return Returns @true if successful or if there was no selection. May fail if validation was enabled and active editor had invalid value. + + @remarks In wxPropertyGrid 1.4, this member function used to send + wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer + does that. + + @see wxPropertyGrid::SelectProperty() */ bool ClearSelection( bool validation = false); @@ -129,16 +135,26 @@ public: bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue ); /** - Deletes a property. + Removes and deletes a property and any children. - @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. + @param id + Pointer or name of a property. + + @remarks If you delete a property in a wxPropertyGrid event + handler, the actual deletion is postponed until the next + idle event. + + 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. */ void DeleteProperty( wxPGPropArg id ); /** Disables a property. + + @see EnableProperty(), wxPGProperty::Enable() */ bool DisableProperty( wxPGPropArg id ); @@ -150,12 +166,15 @@ public: bool EditorValidate(); /** - Enables or disables property. + Enables or disables property. Disabled property usually appears as + having grey text. @param id Name or pointer to a property. @param enable If @false, property is disabled instead. + + @see wxPGProperty::Enable() */ bool EnableProperty( wxPGPropArg id, bool enable = true ); @@ -186,6 +205,13 @@ public: */ bool ExpandAll( bool expand = true ); + /** + Returns auto-resize proportion of the given column. + + @see SetColumnProportion() + */ + int GetColumnProportion( unsigned int column ) const; + /** Returns id of first child of given property. @@ -205,8 +231,12 @@ public: is used. @beginWxPythonOnly - wxPython Note: Instead of ++ operator, use Next() method, and - instead of * operator, use GetProperty() method. + Instead of ++ operator, use Next() method, and instead of * operator, + use GetProperty() method. There is also GetPyIterator() method (which + takes the same arguments but instead returns a pythonic iterator), + @c Properties attribute which is an iterator over all non-category, + non-private properties, and finally @c Items attribute which is an + iterator over all items except private child properties. @endWxPythonOnly */ wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, @@ -228,8 +258,12 @@ public: iteration will instead begin from bottommost valid item. @beginWxPythonOnly - wxPython Note: Instead of ++ operator, use Next() method, and - instead of * operator, use GetProperty() method. + Instead of ++ operator, use Next() method, and instead of * operator, + use GetProperty() method. There is also GetPyIterator() method (which + takes the same arguments but instead returns a pythonic iterator), + @c Properties attribute which is an iterator over all non-category, + non-private properties, and finally @c Items attribute which is an + iterator over all items except private child properties. @endWxPythonOnly */ wxPropertyGridIterator GetIterator( int flags, int startPos ); @@ -245,7 +279,12 @@ public: wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ); /** - Returns id of property with given name (case-sensitive). + Returns pointer to a property with given name (case-sensitive). + If there is no property with such name, @NULL pointer is returned. + + @remarks Properties which have non-category, non-root parent + cannot be accessed globally by their name. Instead, use + "." instead of "". */ wxPGProperty* GetProperty( const wxString& name ) const; @@ -296,7 +335,12 @@ public: wxPGProperty* GetPropertyByLabel( const wxString& label ) const; /** - Returns property with given name. @NULL if none found. + Returns pointer to a property with given name (case-sensitive). + If there is no property with such name, @NULL pointer is returned. + + @remarks Properties which have non-category, non-root parent + cannot be accessed globally by their name. Instead, use + "." instead of "". */ wxPGProperty* GetPropertyByName( const wxString& name ) const; @@ -402,7 +446,20 @@ public: wxVariant GetPropertyValues( const wxString& listname = wxEmptyString, wxPGProperty* baseparent = NULL, long flags = 0 ) const; - /** Returns currently selected property. */ + /** + Returns list of currently selected properties. + + @remarks wxArrayPGProperty should be compatible with std::vector API. + */ + const wxArrayPGProperty& GetSelectedProperties() const; + + /** + Returns currently selected property. NULL if none. + + @remarks When wxPG_EX_MULTIPLE_SELECTION extra style is used, this + member function returns the focused property, that is the + one which can have active editor. + */ wxPGProperty* GetSelection() const; /** @@ -413,8 +470,14 @@ public: @param flags See @ref propgrid_iterator_flags. - wxPython Note: Instead of ++ operator, use Next() method, and - instead of * operator, use GetProperty() method. + @beginWxPythonOnly + Instead of ++ operator, use Next() method, and instead of * operator, + use GetProperty() method. There is also GetPyVIterator() method (which + takes the same arguments but instead returns a pythonic iterator), + @c Properties attribute which is an iterator over all non-category, + non-private properties, and finally @c Items attribute which is an + iterator over all items except private child properties. + @endWxPythonOnly */ virtual wxPGVIterator GetVIterator( int flags ) const; @@ -522,6 +585,11 @@ public: */ bool IsPropertyModified( wxPGPropArg id ) const; + /** + Returns true if property is selected. + */ + virtual bool IsPropertySelected( wxPGPropArg id ) const; + /** Returns @true if property is shown (ie. HideProperty() with @true not called for it). @@ -547,6 +615,21 @@ public: */ static void RegisterAdditionalEditors(); + /** + Removes a property. Does not delete the property object, but + instead returns it. + + @param id + Pointer or name of a property. + + @remarks Removed property cannot have any children. + + Also, if you remove property in a wxPropertyGrid event + handler, the actual removal is postponed until the next + idle event. + */ + wxPGProperty* RemoveProperty( wxPGPropArg id ); + /** Replaces property with id with newly created one. For example, this code replaces existing property named "Flags" with one that @@ -634,6 +717,20 @@ public: static void SetBoolChoices( const wxString& trueChoice, const wxString& falseChoice ); + /** + Set proportion of a auto-stretchable column. wxPG_SPLITTER_AUTO_CENTER + window style needs to be used to indicate that columns are auto- + resizable. + + @returns Returns @false on failure. + + @remarks You should call this for individual pages of + wxPropertyGridManager (if used). + + @see GetColumnProportion() + */ + bool SetColumnProportion( unsigned int column, int proportion ); + /** Sets an attribute for this property. @@ -669,13 +766,14 @@ public: @param colour New background colour. - @param recursively - If True, child properties are affected recursively. Property - categories are skipped if this flag is used. + @param flags + Default is wxPG_RECURSE which causes colour to be set recursively. + Omit this flag to only set colour for the property in question + and not any of its children. */ void SetPropertyBackgroundColour( wxPGPropArg id, const wxColour& colour, - bool recursively = true ); + int flags = wxPG_RECURSE ); /** Sets text, bitmap, and colours for given column's cell. @@ -749,9 +847,6 @@ public: In other words, user cannot change the value in the editor, but they can still copy it. - @remarks This is mainly for use with textctrl editor. Only some other - editors fully support it. - @param id Property name or pointer. @@ -761,6 +856,9 @@ public: @param flags By default changes are applied recursively. Set this parameter wxPG_DONT_RECURSE to prevent this. + + @remarks This is mainly for use with textctrl editor. Only some other + editors fully support it. */ void SetPropertyReadOnly( wxPGPropArg id, bool set = true, int flags = wxPG_RECURSE ); @@ -772,13 +870,14 @@ public: void SetPropertyValueUnspecified( wxPGPropArg id ); /** - Sets various property values from a list of wxVariants. If property with - name is missing from the grid, new property is created under given - default category (or root if omitted). + Sets property values from a list of wxVariants. */ void SetPropertyValues( const wxVariantList& list, wxPGPropArg defaultCategory = wxNullProperty ); + /** + Sets property values from a list of wxVariants. + */ void SetPropertyValues( const wxVariant& list, wxPGPropArg defaultCategory = wxNullProperty ); @@ -815,13 +914,14 @@ public: @param colour New background colour. - @param recursively - If True, child properties are affected recursively. Property - categories are skipped if this flag is used. + @param flags + Default is wxPG_RECURSE which causes colour to be set recursively. + Omit this flag to only set colour for the property in question + and not any of its children. */ void SetPropertyTextColour( wxPGPropArg id, const wxColour& colour, - bool recursively = true ); + int flags = wxPG_RECURSE ); /** Sets validator of a property. @@ -891,6 +991,33 @@ public: */ void SetValidationFailureBehavior( int vfbFlags ); + /** + Sorts all properties recursively. + + @param flags + This can contain any of the following options: + wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their + immediate children. Sorting done by wxPG_AUTO_SORT option + uses this. + + @see SortChildren, wxPropertyGrid::SetSortFunction + */ + void Sort( int flags = 0 ); + + /** + Sorts children of a property. + + @param id + Name or pointer to a property. + + @param flags + This can contain any of the following options: + wxPG_RECURSE: Sorts recursively. + + @see Sort, wxPropertyGrid::SetSortFunction + */ + void SortChildren( wxPGPropArg id, int flags = 0 ); + /** Returns editor pointer of editor with given name; */