From 2ea7ff31606c441ae59aed00ea0dded90be310be Mon Sep 17 00:00:00 2001 From: Artur Wieczorek Date: Sat, 25 Jun 2016 18:17:56 +0200 Subject: [PATCH] Updated documentation for wxPropertyGridInterface. Updated documentation and removed doxygen-style comments from propgridiface.h header file. --- include/wx/propgrid/propgridiface.h | 976 ++++++++++---------------- interface/wx/propgrid/propgridiface.h | 166 ++++- 2 files changed, 506 insertions(+), 636 deletions(-) diff --git a/include/wx/propgrid/propgridiface.h b/include/wx/propgrid/propgridiface.h index 7ddea4e35d..c878ef56e4 100644 --- a/include/wx/propgrid/propgridiface.h +++ b/include/wx/propgrid/propgridiface.h @@ -20,11 +20,8 @@ // ----------------------------------------------------------------------- -/** @section wxPGPropArgCls - - Most property grid functions have this type as their argument, as it can - convey a property by either a pointer or name. -*/ +// Most property grid functions have this type as their argument, as it can +// convey a property by either a pointer or name. class WXDLLIMPEXP_PROPGRID wxPGPropArgCls { public: @@ -43,7 +40,7 @@ public: m_ptr = id.m_ptr; m_flags = id.m_flags; } - // This is only needed for wxPython bindings + // This is only needed for wxPython bindings. wxPGPropArgCls( wxString* str, bool WXUNUSED(deallocPtr) ) { m_ptr.stringName = str; @@ -69,7 +66,7 @@ public: m_ptr.wcharName = str; m_flags = IsWCharPtr; } - /** This constructor is required for NULL. */ + // This constructor is required for NULL. wxPGPropArgCls( int ) { m_ptr.property = NULL; @@ -142,176 +139,122 @@ void wxPGGetFailed( const wxPGProperty* p, const wxString& typestr ); // ----------------------------------------------------------------------- -/** @class wxPropertyGridInterface - - Most of the shared property manipulation interface shared by wxPropertyGrid, - wxPropertyGridPage, and wxPropertyGridManager is defined in this class. - - @remarks - - In separate wxPropertyGrid component this class was known as - wxPropertyContainerMethods. - - @library{wxpropgrid} - @category{propgrid} -*/ +// Most of the shared property manipulation interface shared by wxPropertyGrid, +// wxPropertyGridPage, and wxPropertyGridManager is defined in this class. +// In separate wxPropertyGrid component this class was known as +// wxPropertyContainerMethods. +// wxPropertyGridInterface's property operation member functions all accept +// a special wxPGPropArg id argument, using which you can refer to properties +// either by their pointer (for performance) or by their name (for conveniency). class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface { public: - /** Destructor */ + // Destructor. virtual ~wxPropertyGridInterface() { } - /** - Appends property to the list. - - wxPropertyGrid assumes ownership of the object. - Becomes child of most recently added category. - @remarks - - wxPropertyGrid takes the ownership of the property pointer. - - If appending a category with name identical to a category already in - the wxPropertyGrid, then newly created category is deleted, and most - recently added category (under which properties are appended) is set - to the one with same name. This allows easier adding of items to same - categories in multiple passes. - - Does not automatically redraw the control, so you may need to call - Refresh when calling this function after control has been shown for - the first time. - */ + // Appends property to the list. + // wxPropertyGrid assumes ownership of the object. + // Becomes child of most recently added category. + // wxPropertyGrid takes the ownership of the property pointer. + // If appending a category with name identical to a category already in + // the wxPropertyGrid, then newly created category is deleted, and most + // recently added category (under which properties are appended) is set + // to the one with same name. This allows easier adding of items to same + // categories in multiple passes. + // Does not automatically redraw the control, so you may need to call + // Refresh when calling this function after control has been shown for + // the first time. + // 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. wxPGProperty* Append( wxPGProperty* property ); + // Same as Append(), but appends under given parent property. wxPGProperty* AppendIn( wxPGPropArg id, wxPGProperty* newproperty ); - /** - In order to add new items into a property with fixed children (for - instance, wxFlagsProperty), you need to call this method. After - populating has been finished, you need to call EndAddChildren. - */ + // In order to add new items into a property with fixed children (for + // instance, wxFlagsProperty), you need to call this method. After + // populating has been finished, you need to call EndAddChildren. void BeginAddChildren( wxPGPropArg id ); - /** Deletes all properties. - */ + // Deletes all properties. virtual void Clear() = 0; - /** - Clears current selection, if any. - - @param validation - If set to @false, deselecting the property will always work, - even if its editor had invalid value in it. - - @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. - */ + // Clears current selection, if any. + // validation - If set to false, deselecting the property will always work, + // even if its editor had invalid value in it. + // Returns true if successful or if there was no selection. May + // fail if validation was enabled and active editor had invalid + // value. + // In wxPropertyGrid 1.4, this member function used to send + // wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer + // does that. bool ClearSelection( bool validation = false ); - /** Resets modified status of all properties. - */ + // Resets modified status of all properties. void ClearModifiedStatus(); - /** Collapses given category or property with children. - Returns true if actually collapses. - */ + // Collapses given category or property with children. + // Returns true if actually collapses. bool Collapse( wxPGPropArg id ); - /** Collapses all items that can be collapsed. - - @return - Return false if failed (may fail if editor value cannot be validated). - */ + // Collapses all items that can be collapsed. + // Return false if failed (may fail if editor value cannot be validated). bool CollapseAll() { return ExpandAll(false); } - /** - Changes value of a property, as if from an editor. - Use this instead of SetPropertyValue() if you need the value to run - through validation process, and also send the property change event. - - @return - Returns true if value was successfully changed. - */ + // Changes value of a property, as if from an editor. + // Use this instead of SetPropertyValue() if you need the value to run + // through validation process, and also send the property change event. + // Returns true if value was successfully changed. bool ChangePropertyValue( wxPGPropArg id, wxVariant newValue ); - /** - Removes and deletes a property and any children. - - @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. - */ + // Removes and deletes a property and any children. + // id - Pointer or name of a property. + // 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 ); - /** - 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. - */ + // Removes a property. Does not delete the property object, but + // instead returns it. + // id - Pointer or name of a property. + // 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 ); - /** - Disables a property. - - @see EnableProperty(), wxPGProperty::Enable() - */ + // Disables a property. bool DisableProperty( wxPGPropArg id ) { return EnableProperty(id,false); } - /** - Returns true if all property grid data changes have been committed. - - Usually only returns false if value in active editor has been - invalidated by a wxValidator. - */ + // Returns true if all property grid data changes have been committed. + // Usually only returns false if value in active editor has been + // invalidated by a wxValidator. bool EditorValidate(); - /** - Enables or disables property, depending on whether enable is true or - false. 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() - */ + // Enables or disables property, depending on whether enable is true or + // false. Disabled property usually appears as having grey text. + // id - Name or pointer to a property. + // enable - If false, property is disabled instead. bool EnableProperty( wxPGPropArg id, bool enable = true ); - /** Called after population of property with fixed children has finished. - */ + // Called after population of property with fixed children has finished. void EndAddChildren( wxPGPropArg id ); - /** Expands given category or property with children. - Returns true if actually expands. - */ + // Expands given category or property with children. + // Returns true if actually expands. bool Expand( wxPGPropArg id ); - /** Expands all items that can be expanded. - */ + // Expands all items that can be expanded. bool ExpandAll( bool expand = true ); - /** Returns id of first child of given property. - @remarks - Does not return sub-properties! - */ + // Returns id of first child of given property. + // Does not return sub-properties! wxPGProperty* GetFirstChild( wxPGPropArg id ) { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty) @@ -322,19 +265,11 @@ public: return p->Item(0); } - //@{ - /** Returns iterator class instance. - @param flags - See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes - iteration over everything except private child properties. - @param firstProp - Property to start iteration from. If NULL, then first child of root - is used. - @param startPos - Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start - from the first property from the top, and wxBOTTOM means that the - iteration will instead begin from bottommost valid item. - */ + // Returns iterator class instance. + // flags - See wxPG_ITERATOR_FLAGS. Value wxPG_ITERATE_DEFAULT causes + // iteration over everything except private child properties. + // firstProp - Property to start iteration from. If NULL, then first + // child of root is used. wxPropertyGridIterator GetIterator( int flags = wxPG_ITERATE_DEFAULT, wxPGProperty* firstProp = NULL ) { @@ -348,6 +283,12 @@ public: return wxPropertyGridConstIterator( m_pState, flags, firstProp ); } + // Returns iterator class instance. + // flags - See wxPG_ITERATOR_FLAGS. Value wxPG_ITERATE_DEFAULT causes + // iteration over everything except private child properties. + // startPos - Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start + // from the first property from the top, and wxBOTTOM means that the + // iteration will instead begin from bottommost valid item. wxPropertyGridIterator GetIterator( int flags, int startPos ) { return wxPropertyGridIterator( m_pState, flags, startPos ); @@ -357,12 +298,8 @@ public: { return wxPropertyGridConstIterator( m_pState, flags, startPos ); } - //@} - /** Returns id of first item, whether it is a category or property. - @param flags - @link iteratorflags List of iterator flags@endlink - */ + // Returns id of first item that matches given criteria. wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ) { wxPropertyGridIterator it( m_pState, flags, wxNullProperty, 1 ); @@ -374,24 +311,19 @@ public: return ((wxPropertyGridInterface*)this)->GetFirst(flags); } - /** - 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 "". - */ + // Returns pointer to a property with given name (case-sensitive). + // If there is no property with such name, NULL pointer is returned. + // 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 { return GetPropertyByName(name); } - /** Returns map-like storage of property's attributes. - @remarks - Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set, - then builtin-attributes are not included in the storage. - */ + // Returns map-like storage of property's attributes. + // Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set, + // then builtin-attributes are not included in the storage. const wxPGAttributeStorage& GetPropertyAttributes( wxPGPropArg id ) const { // If 'id' refers to invalid property, then we will return dummy @@ -401,14 +333,11 @@ public: return p->GetAttributes(); } - /** Adds to 'targetArr' pointers to properties that have given - flags 'flags' set. However, if 'inverse' is set to true, then - only properties without given flags are stored. - @param flags - Property flags to use. - @param iterFlags - Iterator flags to use. Default is everything expect private children. - */ + // Adds to 'targetArr' pointers to properties that have given + // flags 'flags' set. However, if 'inverse' is set to true, then + // only properties without given flags are stored. + // flags - Property flags to use. + // iterFlags - Iterator flags to use. Default is everything expect private children. void GetPropertiesWithFlag( wxArrayPGProperty* targetArr, wxPGProperty::FlagType flags, bool inverse = false, @@ -416,8 +345,7 @@ public: wxPG_ITERATE_HIDDEN | wxPG_ITERATE_CATEGORIES) const; - /** Returns value of given attribute. If none found, returns NULL-variant. - */ + // Returns value of given attribute. If none found, returns wxNullVariant. wxVariant GetPropertyAttribute( wxPGPropArg id, const wxString& attrName ) const { @@ -425,75 +353,70 @@ public: return p->GetAttribute(attrName); } - /** Returns pointer of property's nearest parent category. If no category - found, returns NULL. - */ + // Returns pointer of property's nearest parent category. If no category + // found, returns NULL. wxPropertyCategory* GetPropertyCategory( wxPGPropArg id ) const { wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(NULL) return m_pState->GetPropertyCategory(p); } - /** Returns client data (void*) of a property. */ + // Returns client data (void*) of a property. void* GetPropertyClientData( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL) return p->GetClientData(); } - /** - Returns first property which label matches given string. - - NULL if none found. Note that this operation is extremely slow when - compared to GetPropertyByName(). - */ + // Returns first property which label matches given string. + // NULL if none found. Note that this operation is extremely slow when + // compared to GetPropertyByName(). 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. wxPGProperty* GetPropertyByName( const wxString& name ) const; - /** Returns child property 'subname' of property 'name'. Same as - calling GetPropertyByName("name.subname"), albeit slightly faster. - */ + // Returns child property 'subname' of property 'name'. Same as + // calling GetPropertyByName("name.subname"), albeit slightly faster. wxPGProperty* GetPropertyByName( const wxString& name, const wxString& subname ) const; - /** Returns property's editor. */ + // Returns property's editor. const wxPGEditor* GetPropertyEditor( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL) return p->GetEditorClass(); } - /** Returns help string associated with a property. */ + // Returns help string associated with a property. wxString GetPropertyHelpString( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxEmptyString) return p->GetHelpString(); } - /** Returns property's custom value image (NULL of none). */ + // Returns property's custom value image (NULL of none). wxBitmap* GetPropertyImage( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL) return p->GetValueImage(); } - /** Returns label of a property. */ + // Returns label of a property. const wxString& GetPropertyLabel( wxPGPropArg id ) { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString) return p->GetLabel(); } - /** Returns name of a property, by which it is globally accessible. */ + // Returns name of a property, by which it is globally accessible. wxString GetPropertyName( wxPGProperty* property ) { return property->GetName(); } - /** Returns parent item of a property. */ + // Returns parent item of a property. wxPGProperty* GetPropertyParent( wxPGPropArg id ) { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty) @@ -501,9 +424,8 @@ public: } #if wxUSE_VALIDATORS - /** Returns validator of a property as a reference, which you - can pass to any number of SetPropertyValidator. - */ + // Returns validator of a property as a reference, which you + // can pass to any number of SetPropertyValidator. wxValidator* GetPropertyValidator( wxPGPropArg id ) { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL) @@ -511,11 +433,9 @@ public: } #endif - /** Returns value as wxVariant. To get wxObject pointer from it, - you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro. - - If property value is unspecified, Null variant is returned. - */ + // Returns value as wxVariant. To get wxObject pointer from it, + // you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro. + // If property value is unspecified, wxNullVariant is returned. wxVariant GetPropertyValue( wxPGPropArg id ) { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxVariant()) @@ -587,36 +507,27 @@ public: } #endif - /** Returns a wxVariant list containing wxVariant versions of all - property values. Order is not guaranteed. - @param flags - Use wxPG_KEEP_STRUCTURE to retain category structure; each sub - category will be its own wxVariantList of wxVariant. - Use wxPG_INC_ATTRIBUTES to include property attributes as well. - Each attribute will be stored as list variant named - "@@@@attr." - @remarks - */ + // Returns a wxVariant list containing wxVariant versions of all + // property values. Order is not guaranteed. + // flags - Use wxPG_KEEP_STRUCTURE to retain category structure; each sub + // category will be its own wxVariantList of wxVariant. + // Use wxPG_INC_ATTRIBUTES to include property attributes as well. + // Each attribute will be stored as list variant named + // "@@@@attr." wxVariant GetPropertyValues( const wxString& listname = wxEmptyString, wxPGProperty* baseparent = NULL, long flags = 0 ) const { return m_pState->DoGetPropertyValues(listname, baseparent, flags); } - /** - 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. - */ + // Returns currently selected property. NULL if none. + // 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; - /** - Returns list of currently selected properties. - - @remarks wxArrayPGProperty should be compatible with std::vector API. - */ + // Returns list of currently selected properties. + // wxArrayPGProperty should be compatible with std::vector API. const wxArrayPGProperty& GetSelectedProperties() const { return m_pState->m_selection; @@ -624,123 +535,90 @@ public: wxPropertyGridPageState* GetState() const { return m_pState; } - /** Similar to GetIterator(), but instead returns wxPGVIterator instance, - which can be useful for forward-iterating through arbitrary property - containers. - - @param flags - See @ref propgrid_iterator_flags. - */ + // Similar to GetIterator(), but instead returns wxPGVIterator instance, + // which can be useful for forward-iterating through arbitrary property + // containers. + // flags - See wxPG_ITERATOR_FLAGS. virtual wxPGVIterator GetVIterator( int flags ) const; - /** Hides or reveals a property. - @param hide - If true, hides property, otherwise reveals it. - @param flags - By default changes are applied recursively. Set this paramter - wxPG_DONT_RECURSE to prevent this. - */ + // Hides or reveals a property. + // hide - If true, hides property, otherwise reveals it. + // flags - By default changes are applied recursively. Set this paramter + // wxPG_DONT_RECURSE to prevent this. bool HideProperty( wxPGPropArg id, bool hide = true, int flags = wxPG_RECURSE ); #if wxPG_INCLUDE_ADVPROPS - /** Initializes *all* property types. Causes references to most object - files in the library, so calling this may cause significant increase - in executable size when linking with static library. - */ + // Initializes *all* property types. Causes references to most object + // files in the library, so calling this may cause significant increase + // in executable size when linking with static library. static void InitAllTypeHandlers(); #else static void InitAllTypeHandlers() { } #endif - //@{ - /** Inserts property to the property container. - - @param priorThis - New property is inserted just prior to this. Available only - in the first variant. There are two versions of this function - to allow this parameter to be either an id or name to - a property. - - @param newproperty - Pointer to the inserted property. wxPropertyGrid will take - ownership of this object. - - @param parent - New property is inserted under this category. Available only - in the second variant. There are two versions of this function - to allow this parameter to be either an id or name to - a property. - - @param index - Index under category. Available only in the second variant. - If index is < 0, property is appended in category. - - @return - Returns id for the property, - - @remarks - - - wxPropertyGrid takes the ownership of the property pointer. - - - While Append may be faster way to add items, make note that when - both types of data storage (categoric and - non-categoric) are active, Insert becomes even more slow. This is - especially true if current mode is non-categoric. - - Example of use: - - @code - - // append category - wxPGProperty* my_cat_id = propertygrid->Append( - new wxPropertyCategory("My Category") ); - - ... - - // insert into category - using second variant - wxPGProperty* my_item_id_1 = propertygrid->Insert( - my_cat_id, 0, new wxStringProperty("My String 1") ); - - // insert before to first item - using first variant - wxPGProperty* my_item_id_2 = propertygrid->Insert( - my_item_id, new wxStringProperty("My String 2") ); - - @endcode - - */ + // Inserts property to the property container. + // priorThis - New property is inserted just prior to this. Available only + // in the first variant. There are two versions of this function + // to allow this parameter to be either an id or name to + // a property. + // newproperty - Pointer to the inserted property. wxPropertyGrid will take + // ownership of this object. + // Returns id for the property, + // wxPropertyGrid takes the ownership of the property pointer. + // While Append may be faster way to add items, make note that when + // both types of data storage (categoric and + // non-categoric) are active, Insert becomes even more slow. This is + // especially true if current mode is non-categoric. + // Example of use: + // // append category + // wxPGProperty* my_cat_id = propertygrid->Append( + // new wxPropertyCategory("My Category") ); + // ... + // // insert into category - using second variant + // wxPGProperty* my_item_id_1 = propertygrid->Insert( + // my_cat_id, 0, new wxStringProperty("My String 1") ); + // // insert before to first item - using first variant + // wxPGProperty* my_item_id_2 = propertygrid->Insert( + // my_item_id, new wxStringProperty("My String 2") ); wxPGProperty* Insert( wxPGPropArg priorThis, wxPGProperty* newproperty ); + + // Inserts property to the property container. + //See the other overload for more details. + // parent - New property is inserted under this category. Available only + // in the second variant. There are two versions of this function + // to allow this parameter to be either an id or name to + // a property. + // index - Index under category. Available only in the second variant. + // If index is < 0, property is appended in category. + // newproperty - Pointer to the inserted property. wxPropertyGrid will take + // ownership of this object. + // Returns id for the property. wxPGProperty* Insert( wxPGPropArg parent, int index, wxPGProperty* newproperty ); - //@} - /** Returns true if property is a category. */ + // Returns true if property is a category. bool IsPropertyCategory( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false) return p->IsCategory(); } - /** Returns true if property is enabled. */ + // Returns true if property is enabled. bool IsPropertyEnabled( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false) return !p->HasFlag(wxPG_PROP_DISABLED); } - /** - Returns true if given property is expanded. - - Naturally, always returns false for properties that cannot be expanded. - */ + // Returns true if given property is expanded. + // Naturally, always returns false for properties that cannot be expanded. bool IsPropertyExpanded( wxPGPropArg id ) const; - /** - Returns true if property has been modified after value set or modify - flag clear by software. - */ + // Returns true if property has been modified after value set or modify + // flag clear by software. bool IsPropertyModified( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false) @@ -751,91 +629,74 @@ public: #endif } - /** - Returns true if property is selected. - */ + // Returns true if property is selected. bool IsPropertySelected( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false) return m_pState->DoIsPropertySelected(p); } - /** - Returns true if property is shown (i.e. HideProperty with true not - called for it). - */ + // Returns true if property is shown (i.e. HideProperty with true not + // called for it). bool IsPropertyShown( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false) return !p->HasFlag(wxPG_PROP_HIDDEN); } - /** Returns true if property value is set to unspecified. - */ + // Returns true if property value is set to unspecified. bool IsPropertyValueUnspecified( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false) return p->IsValueUnspecified(); } - /** - Disables (limit = true) or enables (limit = false) wxTextCtrl editor of - a property, if it is not the sole mean to edit the value. - */ + // Disables (limit = true) or enables (limit = false) wxTextCtrl editor + // of a property, if it is not the sole mean to edit the value. void LimitPropertyEditing( wxPGPropArg id, bool limit = true ); - /** If state is shown in it's grid, refresh it now. - */ + // If state is shown in it's grid, refresh it now. virtual void RefreshGrid( wxPropertyGridPageState* state = NULL ); #if wxPG_INCLUDE_ADVPROPS - /** - Initializes additional property editors (SpinCtrl etc.). Causes - references to most object files in the library, so calling this may - cause significant increase in executable size when linking with static - library. - */ + // Initializes additional property editors (SpinCtrl etc.). Causes + // references to most object files in the library, so calling this may + // cause significant increase in executable size when linking with static + // library. static void RegisterAdditionalEditors(); #else static void RegisterAdditionalEditors() { } #endif - /** Replaces property with id with newly created property. For example, - this code replaces existing property named "Flags" with one that - will have different set of items: - @code - pg->ReplaceProperty("Flags", - wxFlagsProperty("Flags", wxPG_LABEL, newItems)) - @endcode - For more info, see wxPropertyGrid::Insert. - */ + // Replaces property with id with newly created property. For example, + // this code replaces existing property named "Flags" with one that + // will have different set of items: + // pg->ReplaceProperty("Flags", + // wxFlagsProperty("Flags", wxPG_LABEL, newItems)) + // For more info, see wxPropertyGrid::Insert. wxPGProperty* ReplaceProperty( wxPGPropArg id, wxPGProperty* property ); - /** @anchor propgridinterface_editablestate_flags - - Flags for wxPropertyGridInterface::SaveEditableState() and - wxPropertyGridInterface::RestoreEditableState(). - */ + // Flags for wxPropertyGridInterface::SaveEditableState() + // and wxPropertyGridInterface::RestoreEditableState(). enum EditableStateFlags { - /** Include selected property. */ + // Include selected property. SelectionState = 0x01, - /** Include expanded/collapsed property information. */ + // Include expanded/collapsed property information. ExpandedState = 0x02, - /** Include scrolled position. */ + // Include scrolled position. ScrollPosState = 0x04, - /** Include selected page information. - Only applies to wxPropertyGridManager. */ + // Include selected page information. + // Only applies to wxPropertyGridManager. PageState = 0x08, - /** Include splitter position. Stored for each page. */ + // Include splitter position. Stored for each page. SplitterPosState = 0x10, - /** Include description box size. - Only applies to wxPropertyGridManager. */ + // Include description box size. + // Only applies to wxPropertyGridManager. DescBoxState = 0x20, - /** - Include all supported user editable state information. - This is usually the default value. */ + // Include all supported user editable state information. + // This is usually the default value. AllStates = SelectionState | ExpandedState | ScrollPosState | @@ -844,82 +705,52 @@ public: DescBoxState }; - /** - Restores user-editable state. - - See also wxPropertyGridInterface::SaveEditableState(). - - @param src - String generated by SaveEditableState. - - @param restoreStates - Which parts to restore from source string. See @ref - propgridinterface_editablestate_flags "list of editable state - flags". - - @return - False if there was problem reading the string. - - @remarks - If some parts of state (such as scrolled or splitter position) fail to - restore correctly, please make sure that you call this function after - wxPropertyGrid size has been set (this may sometimes be tricky when - sizers are used). - */ + // Restores user-editable state. + // See also wxPropertyGridInterface::SaveEditableState(). + // src - String generated by SaveEditableState. + // restoreStates - Which parts to restore from source string. See @ref + // propgridinterface_editablestate_flags "list of editable state + // flags". + // Returns false if there was problem reading the string. + // If some parts of state (such as scrolled or splitter position) fail to + // restore correctly, please make sure that you call this function after + // wxPropertyGrid size has been set (this may sometimes be tricky when + // sizers are used). bool RestoreEditableState( const wxString& src, int restoreStates = AllStates ); - /** - Used to acquire user-editable state (selected property, expanded - properties, scrolled position, splitter positions). - - @param includedStates - Which parts of state to include. See @ref - propgridinterface_editablestate_flags "list of editable state flags". - */ + // Used to acquire user-editable state (selected property, expanded + // properties, scrolled position, splitter positions). + // includedStates - Which parts of state to include. See EditableStateFlags. wxString SaveEditableState( int includedStates = AllStates ) const; - /** - Lets user set the strings listed in the choice dropdown of a - wxBoolProperty. Defaults are "True" and "False", so changing them to, - say, "Yes" and "No" may be useful in some less technical applications. - */ + // Lets user set the strings listed in the choice dropdown of a + // wxBoolProperty. Defaults are "True" and "False", so changing them to, + // say, "Yes" and "No" may be useful in some less technical applications. 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() - */ + // 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 false on failure. + // You should call this for individual pages of wxPropertyGridManager + // (if used). bool SetColumnProportion( unsigned int column, int proportion ); - /** - Returns auto-resize proportion of the given column. - - @see SetColumnProportion() - */ + // Returns auto-resize proportion of the given column. int GetColumnProportion( unsigned int column ) const { return m_pState->DoGetColumnProportion(column); } - /** Sets an attribute for this property. - @param name - Text identifier of attribute. See @ref propgrid_property_attributes. - @param value - Value of attribute. - @param argFlags - Optional. Use wxPG_RECURSE to set the attribute to child properties - recursively. - */ + // Sets an attribute for this property. + // name - Text identifier of attribute. See @ref propgrid_property_attributes. + // value - Value of attribute. + // argFlags - Optional. Use wxPG_RECURSE to set the attribute to child + // properties recursively. + // Setting attribute's value to wxNullVariant will simply remove it + // from property's set of attributes. void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName, wxVariant value, @@ -928,38 +759,25 @@ public: DoSetPropertyAttribute(id,attrName,value,argFlags); } - /** Sets property attribute for all applicable properties. - Be sure to use this method only after all properties have been - added to the grid. - */ + // Sets property attribute for all applicable properties. + // Be sure to use this method only after all properties have been + // added to the grid. void SetPropertyAttributeAll( const wxString& attrName, wxVariant value ); - /** - Sets background colour of a property. - - @param id - Property name or pointer. - - @param colour - New background colour. - - @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. - */ + // Sets background colour of a property. + // id - Property name or pointer. + // colour - New background colour. + // 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, int flags = wxPG_RECURSE ); - /** Resets text and background colours of given property. - @param id - Property name or pointer. - - @param flags - Default is wxPG_DONT_RECURSE which causes colour to be reset - only for the property in question (for backward compatibility). - */ + // Resets text and background colours of given property. + // id - Property name or pointer. + // flags - Default is wxPG_DONT_RECURSE which causes colour to be reset + // only for the property in question (for backward compatibility). #if WXWIN_COMPATIBILITY_3_0 void SetPropertyColoursToDefault(wxPGPropArg id); void SetPropertyColoursToDefault(wxPGPropArg id, int flags); @@ -967,48 +785,33 @@ public: void SetPropertyColoursToDefault(wxPGPropArg id, int flags = wxPG_DONT_RECURSE); #endif // WXWIN_COMPATIBILITY_3_0 - /** - Sets text colour of a property. - - @param id - Property name or pointer. - - @param colour - New background colour. - - @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. - */ + // Sets text colour of a property. + // id - Property name or pointer. + // colour - New background colour. + // 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& col, int flags = wxPG_RECURSE ); - /** - Returns background colour of first cell of a property. - */ + // Returns background colour of first cell of a property. wxColour GetPropertyBackgroundColour( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxColour()) return p->GetCell(0).GetBgCol(); } - /** - Returns text colour of first cell of a property. - */ + // Returns text colour of first cell of a property. wxColour GetPropertyTextColour( wxPGPropArg id ) const { wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxColour()) return p->GetCell(0).GetFgCol(); } - /** Sets text, bitmap, and colours for given column's cell. - - @remarks - - You can set label cell by setting column to 0. - - You can use wxPG_LABEL as text to use default text for column. - */ + // Sets text, bitmap, and colours for given column's cell. + // You can set label cell by setting column to 0. + // You can use wxPG_LABEL as text to use default text for column. void SetPropertyCell( wxPGPropArg id, int column, const wxString& text = wxEmptyString, @@ -1016,26 +819,20 @@ public: const wxColour& fgCol = wxNullColour, const wxColour& bgCol = wxNullColour ); - /** Sets client data (void*) of a property. - @remarks - This untyped client data has to be deleted manually. - */ + // Sets client data (void*) of a property. + // This untyped client data has to be deleted manually. void SetPropertyClientData( wxPGPropArg id, void* clientData ) { wxPG_PROP_ARG_CALL_PROLOG() p->SetClientData(clientData); } - /** Sets editor for a property. - - @param editor - For builtin editors, use wxPGEditor_X, where X is builtin editor's - name (TextCtrl, Choice, etc. see wxPGEditor documentation for full - list). - - For custom editors, use pointer you received from - wxPropertyGrid::RegisterEditorClass(). - */ + // Sets editor for a property. + // editor - For builtin editors, use wxPGEditor_X, where X is builtin editor's + // name (TextCtrl, Choice, etc. see wxPGEditor documentation for full + // list). + // For custom editors, use pointer you received from + // wxPropertyGrid::RegisterEditorClass(). void SetPropertyEditor( wxPGPropArg id, const wxPGEditor* editor ) { wxPG_PROP_ARG_CALL_PROLOG() @@ -1044,61 +841,48 @@ public: RefreshProperty(p); } - /** Sets editor control of a property. As editor argument, use - editor name string, such as "TextCtrl" or "Choice". - */ + // Sets editor control of a property. As editor argument, use + // editor name string, such as "TextCtrl" or "Choice". void SetPropertyEditor( wxPGPropArg id, const wxString& editorName ) { SetPropertyEditor(id,GetEditorByName(editorName)); } - /** Sets label of a property. - */ + // Sets label of a property. + // Properties under same parent may have same labels. However, + // property names must still remain unique. void SetPropertyLabel( wxPGPropArg id, const wxString& newproplabel ); - /** - Sets name of a property. - - @param id - Name or pointer of property which name to change. - - @param newName - New name for property. - */ + // Sets name of a property. + // id - Name or pointer of property which name to change. + // newName - New name for property. void SetPropertyName( wxPGPropArg id, const wxString& newName ) { wxPG_PROP_ARG_CALL_PROLOG() m_pState->DoSetPropertyName( p, newName ); } - /** - Sets property (and, recursively, its children) to have read-only value. - 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. Not all other editors fully - support it. - @param flags - By default changes are applied recursively. Set this parameter - wxPG_DONT_RECURSE to prevent this. - */ + // Sets property (and, recursively, its children) to have read-only value. + // In other words, user cannot change the value in the editor, but they + // can still copy it. + // This is mainly for use with textctrl editor. Not all other editors fully + // support it. + // By default changes are applied recursively. Set parameter "flags" + // to wxPG_DONT_RECURSE to prevent this. void SetPropertyReadOnly( wxPGPropArg id, bool set = true, int flags = wxPG_RECURSE ); - /** Sets property's value to unspecified. - If it has children (it may be category), then the same thing is done to - them. - */ + // Sets property's value to unspecified. + // If it has children (it may be category), then the same thing is done to + // them. void SetPropertyValueUnspecified( wxPGPropArg id ) { wxPG_PROP_ARG_CALL_PROLOG() p->SetValueToUnspecified(); } - /** - Sets property values from a list of wxVariants. - */ + // Sets property values from a list of wxVariants. void SetPropertyValues( const wxVariantList& list, wxPGPropArg defaultCategory = wxNullProperty ) { @@ -1108,33 +892,27 @@ public: m_pState->DoSetPropertyValues(list, p); } - /** - Sets property values from a list of wxVariants. - */ + // Sets property values from a list of wxVariants. void SetPropertyValues( const wxVariant& list, wxPGPropArg defaultCategory = wxNullProperty ) { SetPropertyValues(list.GetList(),defaultCategory); } - /** Associates the help string with property. - @remarks - By default, text is shown either in the manager's "description" - text box or in the status bar. If extra window style - wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a - tooltip. - */ + // Associates the help string with property. + // By default, text is shown either in the manager's "description" + // text box or in the status bar. If extra window style + // wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a + // tooltip. void SetPropertyHelpString( wxPGPropArg id, const wxString& helpString ) { wxPG_PROP_ARG_CALL_PROLOG() p->SetHelpString(helpString); } - /** Set wxBitmap in front of the value. - @remarks - - Bitmap will be scaled to a size returned by - wxPropertyGrid::GetImageSize(); - */ + // Set wxBitmap in front of the value. + // Bitmap will be scaled to a size returned by + // wxPropertyGrid::GetImageSize(); void SetPropertyImage( wxPGPropArg id, wxBitmap& bmp ) { wxPG_PROP_ARG_CALL_PROLOG() @@ -1142,13 +920,11 @@ public: RefreshProperty(p); } - /** Sets max length of property's text. - */ + // Sets max length of property's text. bool SetPropertyMaxLength( wxPGPropArg id, int maxLen ); #if wxUSE_VALIDATORS - /** Sets validator of a property. - */ + // Sets validator of a property. void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator ) { wxPG_PROP_ARG_CALL_PROLOG() @@ -1156,50 +932,53 @@ public: } #endif - /** Sets value (long integer) of a property. - */ + // Sets value (long integer) of a property. void SetPropertyValue( wxPGPropArg id, long value ) { wxVariant v(value); SetPropVal( id, v ); } - /** Sets value (integer) of a property. - */ + // Sets value (integer) of a property. void SetPropertyValue( wxPGPropArg id, int value ) { wxVariant v((long)value); SetPropVal( id, v ); } - /** Sets value (floating point) of a property. - */ + + // Sets value (floating point) of a property. void SetPropertyValue( wxPGPropArg id, double value ) { wxVariant v(value); SetPropVal( id, v ); } - /** Sets value (bool) of a property. - */ + + // Sets value (bool) of a property. void SetPropertyValue( wxPGPropArg id, bool value ) { wxVariant v(value); SetPropVal( id, v ); } + + // Sets value (wchar_t*) of a property. void SetPropertyValue( wxPGPropArg id, const wchar_t* value ) { SetPropertyValueString( id, wxString(value) ); } + + // Sets value (char*) of a property. void SetPropertyValue( wxPGPropArg id, const char* value ) { SetPropertyValueString( id, wxString(value) ); } + + // Sets value (string) of a property. void SetPropertyValue( wxPGPropArg id, const wxString& value ) { SetPropertyValueString( id, value ); } - /** Sets value (wxArrayString) of a property. - */ + // Sets value (wxArrayString) of a property. void SetPropertyValue( wxPGPropArg id, const wxArrayString& value ) { wxVariant v(value); @@ -1207,6 +986,7 @@ public: } #if wxUSE_DATETIME + // Sets value (wxDateTime) of a property. void SetPropertyValue( wxPGPropArg id, const wxDateTime& value ) { wxVariant v(value); @@ -1214,14 +994,14 @@ public: } #endif - /** Sets value (wxObject*) of a property. - */ + // Sets value (wxObject*) of a property. void SetPropertyValue( wxPGPropArg id, wxObject* value ) { wxVariant v(value); SetPropVal( id, v ); } + // Sets value (wxObject&) of a property. void SetPropertyValue( wxPGPropArg id, wxObject& value ) { wxVariant v(&value); @@ -1230,30 +1010,28 @@ public: #if wxUSE_LONGLONG #ifdef wxLongLong_t - /** Sets value (wxLongLong_t&) of a property. - */ + // Sets value (native 64-bit int) of a property. void SetPropertyValue(wxPGPropArg id, wxLongLong_t value) { wxVariant v = WXVARIANT(wxLongLong(value)); SetPropVal(id, v); } #endif + // Sets value (wxLongLong) of a property. void SetPropertyValue( wxPGPropArg id, wxLongLong value ) { wxVariant v = WXVARIANT(value); SetPropVal( id, v ); } #ifdef wxULongLong_t - /** Sets value (wxULongLong_t&) of a property. - */ + // Sets value (native 64-bit unsigned int) of a property. void SetPropertyValue(wxPGPropArg id, wxULongLong_t value) { wxVariant v = WXVARIANT(wxULongLong(value)); SetPropVal(id, v); } #endif - /** Sets value (wxULongLong&) of a property. - */ + // Sets value (wxULongLong) of a property. void SetPropertyValue( wxPGPropArg id, wxULongLong value ) { wxVariant v = WXVARIANT(value); @@ -1261,79 +1039,59 @@ public: } #endif - /** Sets value (wxArrayInt&) of a property. - */ + // Sets value (wxArrayInt&) of a property. void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value ) { wxVariant v = WXVARIANT(value); SetPropVal( id, v ); } - /** Sets value (wxString) of a property. - - @remarks - This method uses wxPGProperty::SetValueFromString, which all properties - should implement. This means that there should not be a type error, - and instead the string is converted to property's actual value type. - */ + // Sets value (wxString) of a property. + // This method uses wxPGProperty::SetValueFromString, which all properties + // should implement. This means that there should not be a type error, + // and instead the string is converted to property's actual value type. void SetPropertyValueString( wxPGPropArg id, const wxString& value ); - /** Sets value (wxVariant&) of a property. - - @remarks - Use wxPropertyGrid::ChangePropertyValue() instead if you need to run - through validation process and send property change event. - */ + // Sets value (wxVariant) of a property. + // Use wxPropertyGrid::ChangePropertyValue() instead if you need to run + // through validation process and send property change event. void SetPropertyValue( wxPGPropArg id, wxVariant value ) { SetPropVal( id, value ); } - /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but - accepts reference. */ + // Sets value (wxVariant&) of a property. Same as SetPropertyValue, + // but accepts reference. void SetPropVal( wxPGPropArg id, wxVariant& value ); - /** Adjusts how wxPropertyGrid behaves when invalid value is entered - in a property. - @param vfbFlags - See @link vfbflags list of valid flags values@endlink - */ + // Adjusts how wxPropertyGrid behaves when invalid value is entered + // in a property. + // vfbFlags - See wxPG_VALIDATION_FAILURE_BEHAVIOR_FLAGS for possible values. 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 - */ + // Sorts all properties recursively. + // 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 - */ + // Sorts children of a property. + // id - Name or pointer to a property. + // flags - This can contain any of the following options: + // wxPG_RECURSE: Sorts recursively. + // See Sort, wxPropertyGrid::SetSortFunction void SortChildren( wxPGPropArg id, int flags = 0 ) { wxPG_PROP_ARG_CALL_PROLOG() m_pState->DoSortChildren(p, flags); } - // GetPropertyByName With nice assertion error message. + // GetPropertyByName() with nice assertion error message. wxPGProperty* GetPropertyByNameA( const wxString& name ) const; + // Returns editor pointer of editor with given name. static wxPGEditor* GetEditorByName( const wxString& editorName ); // NOTE: This function reselects the property and may cause @@ -1346,10 +1104,8 @@ protected: bool DoClearSelection( bool validation = false, int selFlags = 0 ); - /** - In derived class, implement to set editable state component with - given name to given value. - */ + // In derived class, implement to set editable state component with + // given name to given value. virtual bool SetEditableStateItem( const wxString& name, wxVariant value ) { wxUnusedVar(name); @@ -1357,10 +1113,8 @@ protected: return false; } - /** - In derived class, implement to return editable state component with - given name. - */ + // In derived class, implement to return editable state component with + // given name. virtual wxVariant GetEditableStateItem( const wxString& name ) const { wxUnusedVar(name); diff --git a/interface/wx/propgrid/propgridiface.h b/interface/wx/propgrid/propgridiface.h index 98b2c82949..b5931ea2d7 100644 --- a/interface/wx/propgrid/propgridiface.h +++ b/interface/wx/propgrid/propgridiface.h @@ -1,5 +1,5 @@ ///////////////////////////////////////////////////////////////////////////// -// Name: property.h +// Name: propgridiface.h // Purpose: interface of wxPGProperty // Author: wxWidgets team // Licence: wxWindows licence @@ -24,12 +24,12 @@ @library{wxpropgrid} @category{propgrid} */ -class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface +class wxPropertyGridInterface { public: - /** Destructor */ - virtual ~wxPropertyGridInterface() { } + /** Destructor. */ + virtual ~wxPropertyGridInterface(); /** Appends property to the list. wxPropertyGrid assumes ownership of the @@ -118,6 +118,9 @@ public: /** Collapses all items that can be collapsed. + @return + Return @false if failed (may fail if editor value cannot be validated). + @remarks This functions clears selection. Validation failure option wxPG_VFB_STAY_IN_PROPERTY is not respected, ie. selection is cleared even if editor had invalid value. @@ -253,6 +256,7 @@ public: wxPropertyGridConstIterator GetIterator( int flags, int startPos ) const; //@} + //@{ /** Returns id of first item that matches given criteria. @@ -261,6 +265,9 @@ public: */ wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ); + const wxPGProperty* GetFirst( int flags = wxPG_ITERATE_ALL ) const; + //@} + /** Returns pointer to a property with given name (case-sensitive). If there is no property with such name, @NULL pointer is returned. @@ -296,6 +303,15 @@ public: */ wxVariant GetPropertyAttribute( wxPGPropArg id, const wxString& attrName ) const; + /** + Returns map-like storage of property's attributes. + + @remarks + Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set, + then builtin-attributes are not included in the storage. + */ + const wxPGAttributeStorage& GetPropertyAttributes( wxPGPropArg id ) const; + /** Returns background colour of first cell of a property. */ @@ -349,12 +365,21 @@ public: */ wxBitmap* GetPropertyImage( wxPGPropArg id ) const; - /** Returns label of a property. */ + /** + Returns label of a property. + */ const wxString& GetPropertyLabel( wxPGPropArg id ); - /** Returns property's name, by which it is globally accessible. */ + /** + Returns property's name, by which it is globally accessible. + */ wxString GetPropertyName( wxPGProperty* property ); + /** + Returns parent item of a property. + */ + wxPGProperty* GetPropertyParent( wxPGPropArg id ); + /** Returns text colour of first cell of a property. */ @@ -369,7 +394,7 @@ public: /** Returns property's value as wxVariant. - If property value is unspecified, Null variant is returned. + If property value is unspecified, wxNullVariant is returned. */ wxVariant GetPropertyValue( wxPGPropArg id ); @@ -437,7 +462,7 @@ public: const wxArrayPGProperty& GetSelectedProperties() const; /** - Returns currently selected property. NULL if none. + 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 @@ -560,12 +585,12 @@ public: bool IsPropertyModified( wxPGPropArg id ) const; /** - Returns true if property is selected. + Returns @true if property is selected. */ virtual bool IsPropertySelected( wxPGPropArg id ) const; /** - Returns @true if property is shown (ie. HideProperty() with @true not + Returns @true if property is shown (i.e. HideProperty() with @true not called for it). */ bool IsPropertyShown( wxPGPropArg id ) const; @@ -581,6 +606,11 @@ public: */ void LimitPropertyEditing( wxPGPropArg id, bool limit = true ); + /** + If state is shown in it's grid, refresh it now. + */ + virtual void RefreshGrid( wxPropertyGridPageState* state = NULL ); + /** Initializes additional property editors (SpinCtrl etc.). Causes references to most object files in the library, so calling this may @@ -626,24 +656,44 @@ public: */ enum EditableStateFlags { - /** Include selected property. */ + /** + Include selected property. + @hideinitializer + */ SelectionState = 0x01, - /** Include expanded/collapsed property information. */ + /** + Include expanded/collapsed property information. + @hideinitializer + */ ExpandedState = 0x02, - /** Include scrolled position. */ + /** + Include scrolled position. + @hideinitializer + */ ScrollPosState = 0x04, - /** Include selected page information. Only applies to - wxPropertyGridManager. */ + /** + Include selected page information. Only applies to + wxPropertyGridManager. + @hideinitializer + */ PageState = 0x08, - /** Include splitter position. Stored for each page. */ + /** + Include splitter position. Stored for each page. + @hideinitializer + */ SplitterPosState = 0x10, - /** Include description box size. - Only applies to wxPropertyGridManager. */ + /** + Include description box size. + Only applies to wxPropertyGridManager. + @hideinitializer + */ DescBoxState = 0x20, /** Include all supported user editable state information. - This is usually the default value. */ + This is usually the default value. + @hideinitializer + */ AllStates = SelectionState | ExpandedState | ScrollPosState | @@ -718,7 +768,7 @@ public: Optional. Use wxPG_RECURSE to set the attribute to child properties recursively. - @remarks Setting attribute's value to Null variant will simply remove it + @remarks Setting attribute's value to wxNullVariant will simply remove it from property's set of attributes. */ void SetPropertyAttribute( wxPGPropArg id, const wxString& attrName, @@ -773,8 +823,14 @@ public: /** Resets text and background colours of given property. + @param id + Property name or pointer. + + @param flags + Default is wxPG_DONT_RECURSE which causes colour to be reset + only for the property in question (for backward compatibility). */ - void SetPropertyColoursToDefault( wxPGPropArg id ); + void SetPropertyColoursToDefault(wxPGPropArg id, int flags = wxPG_DONT_RECURSE); /** Sets editor for a property. @@ -829,7 +885,7 @@ public: @param flags By default changes are applied recursively. Set this parameter - wxPG_DONT_RECURSE to prevent this. + to wxPG_DONT_RECURSE to prevent this. @remarks This is mainly for use with textctrl editor. Only some other editors fully support it. @@ -902,7 +958,7 @@ public: */ void SetPropertyValidator( wxPGPropArg id, const wxValidator& validator ); - /** Sets value (integer) of a property. */ + /** Sets value (long integer) of a property. */ void SetPropertyValue( wxPGPropArg id, long value ); /** Sets value (integer) of a property. */ @@ -914,6 +970,12 @@ public: /** Sets value (bool) of a property. */ void SetPropertyValue( wxPGPropArg id, bool value ); + /** Sets value (wchar_t*) of a property. */ + void SetPropertyValue( wxPGPropArg id, const wchar_t* value ); + + /** Sets value (char*) of a property. */ + void SetPropertyValue( wxPGPropArg id, const char* value ); + /** Sets value (string) of a property. */ void SetPropertyValue( wxPGPropArg id, const wxString& value ); @@ -932,9 +994,15 @@ public: /** Sets value (native 64-bit int) of a property. */ void SetPropertyValue( wxPGPropArg id, wxLongLong_t value ); + /** Sets value (wxLongLong) of a property. */ + void SetPropertyValue( wxPGPropArg id, wxLongLong value ); + /** Sets value (native 64-bit unsigned int) of a property. */ void SetPropertyValue( wxPGPropArg id, wxULongLong_t value ); + /** Sets value (wxULongLong) of a property. */ + void SetPropertyValue( wxPGPropArg id, wxULongLong value ); + /** Sets value (wxArrayInt&) of a property. */ void SetPropertyValue( wxPGPropArg id, const wxArrayInt& value ); @@ -949,13 +1017,19 @@ public: void SetPropertyValueString( wxPGPropArg id, const wxString& value ); /** - Sets value (wxVariant&) of a property. + Sets value (wxVariant) of a property. @remarks Use wxPropertyGrid::ChangePropertyValue() instead if you need to run through validation process and send property change event. */ void SetPropertyValue( wxPGPropArg id, wxVariant value ); + /** + Sets value (wxVariant&) of a property. Same as SetPropertyValue, + but accepts reference. + */ + void SetPropVal( wxPGPropArg id, wxVariant& value ); + /** Adjusts how wxPropertyGrid behaves when invalid value is entered in a property. @@ -993,8 +1067,50 @@ public: void SortChildren( wxPGPropArg id, int flags = 0 ); /** - Returns editor pointer of editor with given name; + Returns editor pointer of editor with given name. */ static wxPGEditor* GetEditorByName( const wxString& editorName ); + + /** + GetPropertyByName() with assertion error message. + */ + wxPGProperty* GetPropertyByNameA( const wxString& name ) const; + + /** + @remarks This function reselects the property and may cause + excess flicker, so to just call Refresh() on a rect + of single property, call DrawItem() instead. + */ + virtual void RefreshProperty( wxPGProperty* p ) = 0; }; +// ----------------------------------------------------------------------- + +/** @section wxPGPropArgCls + + Most property grid functions have this type as their argument, + as it can convey a property by either a pointer or name. +*/ +class wxPGPropArgCls +{ +public: + wxPGPropArgCls( const wxPGProperty* property ); + wxPGPropArgCls( const wxString& str ); + wxPGPropArgCls( const wxPGPropArgCls& id ); + /** This is only needed for wxPython bindings. */ + wxPGPropArgCls( wxString* str, bool WXUNUSED(deallocPtr) ); + ~wxPGPropArgCls(); + + wxPGProperty* GetPtr() const; + wxPGPropArgCls( const char* str ); + wxPGPropArgCls( const wchar_t* str ); + /** This constructor is required for @NULL. */ + wxPGPropArgCls( int ); + wxPGProperty* GetPtr( wxPropertyGridInterface* iface ) const; + wxPGProperty* GetPtr( const wxPropertyGridInterface* iface ) const; + wxPGProperty* GetPtr0() const; + bool HasName() const; + const wxString& GetName() const; +}; + +typedef const wxPGPropArgCls& wxPGPropArg;