1 /////////////////////////////////////////////////////////////////////////////
2 // Name: wx/propgeid/propgridiface.h
3 // Purpose: wxPropertyGridInterface class
4 // Author: Jaakko Salli
8 // Copyright: (c) Jaakko Salli
9 // Licence: wxWindows license
10 /////////////////////////////////////////////////////////////////////////////
12 #ifndef __WX_PROPGRID_PROPGRIDIFACE_H__
13 #define __WX_PROPGRID_PROPGRIDIFACE_H__
17 #include "wx/propgrid/property.h"
18 #include "wx/propgrid/propgridpagestate.h"
20 // -----------------------------------------------------------------------
24 /** @section wxPGPropArgCls
26 Most property grid functions have this type as their argument, as it can
27 convey a property by either a pointer or name.
29 class WXDLLIMPEXP_PROPGRID wxPGPropArgCls
33 wxPGPropArgCls( const wxPGProperty
* property
)
35 m_ptr
.property
= (wxPGProperty
*) property
;
38 wxPGPropArgCls( const wxString
& str
)
40 m_ptr
.stringName
= &str
;
43 wxPGPropArgCls( const wxPGPropArgCls
& id
)
48 // This is only needed for wxPython bindings
49 wxPGPropArgCls( wxString
* str
, bool WXUNUSED(deallocPtr
) )
51 m_ptr
.stringName
= str
;
52 m_flags
= IsWxString
| OwnsWxString
;
56 if ( m_flags
& OwnsWxString
)
57 delete m_ptr
.stringName
;
59 wxPGProperty
* GetPtr() const
61 wxCHECK( m_flags
== IsProperty
, NULL
);
62 return m_ptr
.property
;
64 wxPGPropArgCls( const char* str
)
70 wxPGPropArgCls( const wchar_t* str
)
72 m_ptr
.wcharName
= str
;
76 /** This constructor is required for NULL. */
79 m_ptr
.property
= NULL
;
82 wxPGProperty
* GetPtr( wxPropertyGridInterface
* iface
) const;
83 wxPGProperty
* GetPtr( const wxPropertyGridInterface
* iface
) const
85 return GetPtr((wxPropertyGridInterface
*)iface
);
87 wxPGProperty
* GetPtr0() const { return m_ptr
.property
; }
88 bool HasName() const { return (m_flags
!= IsProperty
); }
89 const wxString
& GetName() const { return *m_ptr
.stringName
; }
103 wxPGProperty
* property
;
104 const char* charName
;
106 const wchar_t* wcharName
;
108 const wxString
* stringName
;
110 unsigned char m_flags
;
115 typedef const wxPGPropArgCls
& wxPGPropArg
;
117 // -----------------------------------------------------------------------
120 void wxPGTypeOperationFailed( const wxPGProperty
* p
,
121 const wxString
& typestr
,
122 const wxString
& op
);
124 void wxPGGetFailed( const wxPGProperty
* p
, const wxString
& typestr
);
126 // -----------------------------------------------------------------------
128 // Helper macro that does necessary preparations when calling
129 // some wxPGProperty's member function.
130 #define wxPG_PROP_ARG_CALL_PROLOG_0(PROPERTY) \
131 PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
134 #define wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(PROPERTY, RETVAL) \
135 PROPERTY *p = (PROPERTY*)id.GetPtr(this); \
136 if ( !p ) return RETVAL;
138 #define wxPG_PROP_ARG_CALL_PROLOG() \
139 wxPG_PROP_ARG_CALL_PROLOG_0(wxPGProperty)
141 #define wxPG_PROP_ARG_CALL_PROLOG_RETVAL(RVAL) \
142 wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(wxPGProperty, RVAL)
144 #define wxPG_PROP_ID_CONST_CALL_PROLOG() \
145 wxPG_PROP_ARG_CALL_PROLOG_0(const wxPGProperty)
147 #define wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(RVAL) \
148 wxPG_PROP_ARG_CALL_PROLOG_RETVAL_0(const wxPGProperty, RVAL)
150 // -----------------------------------------------------------------------
153 /** @class wxPropertyGridInterface
155 Most of the shared property manipulation interface shared by wxPropertyGrid,
156 wxPropertyGridPage, and wxPropertyGridManager is defined in this class.
159 - In separate wxPropertyGrid component this class was known as
160 wxPropertyContainerMethods.
165 class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface
170 virtual ~wxPropertyGridInterface() { }
173 Appends property to the list.
175 wxPropertyGrid assumes ownership of the object.
176 Becomes child of most recently added category.
178 - wxPropertyGrid takes the ownership of the property pointer.
179 - If appending a category with name identical to a category already in
180 the wxPropertyGrid, then newly created category is deleted, and most
181 recently added category (under which properties are appended) is set
182 to the one with same name. This allows easier adding of items to same
183 categories in multiple passes.
184 - Does not automatically redraw the control, so you may need to call
185 Refresh when calling this function after control has been shown for
188 wxPGProperty
* Append( wxPGProperty
* property
);
190 wxPGProperty
* AppendIn( wxPGPropArg id
, wxPGProperty
* newproperty
);
193 In order to add new items into a property with fixed children (for
194 instance, wxFlagsProperty), you need to call this method. After
195 populating has been finished, you need to call EndAddChildren.
197 void BeginAddChildren( wxPGPropArg id
);
199 /** Deletes all properties.
201 virtual void Clear() = 0;
204 Clears current selection, if any.
207 If set to @false, deselecting the property will always work,
208 even if its editor had invalid value in it.
210 @return Returns @true if successful or if there was no selection. May
211 fail if validation was enabled and active editor had invalid
214 @remarks In wxPropertyGrid 1.4, this member function used to send
215 wxPG_EVT_SELECTED. In wxWidgets 2.9 and later, it no longer
218 bool ClearSelection( bool validation
= false );
220 /** Resets modified status of all properties.
222 void ClearModifiedStatus();
224 /** Collapses given category or property with children.
225 Returns true if actually collapses.
227 bool Collapse( wxPGPropArg id
);
229 /** Collapses all items that can be collapsed.
232 Return false if failed (may fail if editor value cannot be validated).
234 bool CollapseAll() { return ExpandAll(false); }
237 Changes value of a property, as if from an editor.
238 Use this instead of SetPropertyValue() if you need the value to run
239 through validation process, and also send the property change event.
242 Returns true if value was successfully changed.
244 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
247 Deletes a property by id. If category is deleted, all children are
248 automatically deleted as well.
250 void DeleteProperty( wxPGPropArg id
);
253 Removes and returns a property.
256 Pointer or name of a property.
258 @remarks Removed property cannot have any children.
260 wxPGProperty
* RemoveProperty( wxPGPropArg id
);
262 /** Disables property. */
263 bool DisableProperty( wxPGPropArg id
) { return EnableProperty(id
,false); }
266 Returns true if all property grid data changes have been committed.
268 Usually only returns false if value in active editor has been
269 invalidated by a wxValidator.
271 bool EditorValidate();
274 Enables or disables property, depending on whether enable is true or
277 bool EnableProperty( wxPGPropArg id
, bool enable
= true );
279 /** Called after population of property with fixed children has finished.
281 void EndAddChildren( wxPGPropArg id
);
283 /** Expands given category or property with children.
284 Returns true if actually expands.
286 bool Expand( wxPGPropArg id
);
288 /** Expands all items that can be expanded.
290 bool ExpandAll( bool expand
= true );
292 /** Returns id of first child of given property.
294 Does not return sub-properties!
296 wxPGProperty
* GetFirstChild( wxPGPropArg id
)
298 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty
)
300 if ( !p
->GetChildCount() || p
->HasFlag(wxPG_PROP_AGGREGATE
) )
301 return wxNullProperty
;
307 /** Returns iterator class instance.
309 See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
310 iteration over everything except private child properties.
312 Property to start iteration from. If NULL, then first child of root
315 Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start
316 from the first property from the top, and wxBOTTOM means that the
317 iteration will instead begin from bottommost valid item.
319 wxPropertyGridIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
320 wxPGProperty
* firstProp
= NULL
)
322 return wxPropertyGridIterator( m_pState
, flags
, firstProp
);
325 wxPropertyGridConstIterator
326 GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
327 wxPGProperty
* firstProp
= NULL
) const
329 return wxPropertyGridConstIterator( m_pState
, flags
, firstProp
);
332 wxPropertyGridIterator
GetIterator( int flags
, int startPos
)
334 return wxPropertyGridIterator( m_pState
, flags
, startPos
);
337 wxPropertyGridConstIterator
GetIterator( int flags
, int startPos
) const
339 return wxPropertyGridConstIterator( m_pState
, flags
, startPos
);
343 /** Returns id of first item, whether it is a category or property.
345 @link iteratorflags List of iterator flags@endlink
347 wxPGProperty
* GetFirst( int flags
= wxPG_ITERATE_ALL
)
349 wxPropertyGridIterator
it( m_pState
, flags
, wxNullProperty
, 1 );
353 const wxPGProperty
* GetFirst( int flags
= wxPG_ITERATE_ALL
) const
355 return ((wxPropertyGridInterface
*)this)->GetFirst(flags
);
359 Returns pointer to a property with given name (case-sensitive).
360 If there is no property with such name, @NULL pointer is returned.
362 @remarks Properties which have non-category, non-root parent
363 can not be accessed globally by their name. Instead, use
364 "<property>.<subproperty>" instead of "<subproperty>".
366 wxPGProperty
* GetProperty( const wxString
& name
) const
368 return GetPropertyByName(name
);
371 /** Returns map-like storage of property's attributes.
373 Note that if extra style wxPG_EX_WRITEONLY_BUILTIN_ATTRIBUTES is set,
374 then builtin-attributes are not included in the storage.
376 const wxPGAttributeStorage
& GetPropertyAttributes( wxPGPropArg id
) const
378 // If 'id' refers to invalid property, then we will return dummy
379 // attributes (ie. root property's attributes, which contents should
380 // should always be empty and of no consequence).
381 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_pState
->DoGetRoot()->GetAttributes());
382 return p
->GetAttributes();
385 /** Adds to 'targetArr' pointers to properties that have given
386 flags 'flags' set. However, if 'inverse' is set to true, then
387 only properties without given flags are stored.
389 Property flags to use.
391 Iterator flags to use. Default is everything expect private children.
393 void GetPropertiesWithFlag( wxArrayPGProperty
* targetArr
,
394 wxPGProperty::FlagType flags
,
395 bool inverse
= false,
396 int iterFlags
= wxPG_ITERATE_PROPERTIES
|
397 wxPG_ITERATE_HIDDEN
|
398 wxPG_ITERATE_CATEGORIES
) const;
400 /** Returns value of given attribute. If none found, returns NULL-variant.
402 wxVariant
GetPropertyAttribute( wxPGPropArg id
,
403 const wxString
& attrName
) const
405 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullVariant
)
406 return p
->GetAttribute(attrName
);
409 /** Returns pointer of property's nearest parent category. If no category
412 wxPropertyCategory
* GetPropertyCategory( wxPGPropArg id
) const
414 wxPG_PROP_ID_CONST_CALL_PROLOG_RETVAL(NULL
)
415 return m_pState
->GetPropertyCategory(p
);
419 /** Returns client data (void*) of a property. */
420 void* GetPropertyClientData( wxPGPropArg id
) const
422 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL
)
423 return p
->GetClientData();
428 Returns first property which label matches given string.
430 NULL if none found. Note that this operation is extremely slow when
431 compared to GetPropertyByName().
433 wxPGProperty
* GetPropertyByLabel( const wxString
& label
) const;
435 /** Returns property with given name. NULL if none found.
437 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
439 /** Returns child property 'subname' of property 'name'. Same as
440 calling GetPropertyByName("name.subname"), albeit slightly faster.
442 wxPGProperty
* GetPropertyByName( const wxString
& name
,
443 const wxString
& subname
) const;
445 /** Returns property's editor. */
446 const wxPGEditor
* GetPropertyEditor( wxPGPropArg id
) const
448 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL
)
449 return p
->GetEditorClass();
452 /** Returns help string associated with a property. */
453 wxString
GetPropertyHelpString( wxPGPropArg id
) const
455 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString
)
456 return p
->GetHelpString();
459 /** Returns property's custom value image (NULL of none). */
460 wxBitmap
* GetPropertyImage( wxPGPropArg id
) const
462 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL
)
463 return p
->GetValueImage();
466 /** Returns label of a property. */
467 const wxString
& GetPropertyLabel( wxPGPropArg id
)
469 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(m_emptyString
)
470 return p
->GetLabel();
473 /** Returns name of a property, by which it is globally accessible. */
474 wxString
GetPropertyName( wxPGProperty
* property
)
476 return property
->GetName();
479 /** Returns parent item of a property. */
480 wxPGProperty
* GetPropertyParent( wxPGPropArg id
)
482 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxNullProperty
)
483 return p
->GetParent();
487 /** Returns validator of a property as a reference, which you
488 can pass to any number of SetPropertyValidator.
490 wxValidator
* GetPropertyValidator( wxPGPropArg id
)
492 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(NULL
)
493 return p
->GetValidator();
497 /** Returns value as wxVariant. To get wxObject pointer from it,
498 you will have to use WX_PG_VARIANT_TO_WXOBJECT(VARIANT,CLASSNAME) macro.
500 If property value is unspecified, Null variant is returned.
502 wxVariant
GetPropertyValue( wxPGPropArg id
)
504 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxVariant())
505 return p
->GetValue();
508 wxString
GetPropertyValueAsString( wxPGPropArg id
) const;
509 long GetPropertyValueAsLong( wxPGPropArg id
) const;
510 unsigned long GetPropertyValueAsULong( wxPGPropArg id
) const
512 return (unsigned long) GetPropertyValueAsLong(id
);
515 int GetPropertyValueAsInt( wxPGPropArg id
) const
516 { return (int)GetPropertyValueAsLong(id
); }
518 bool GetPropertyValueAsBool( wxPGPropArg id
) const;
519 double GetPropertyValueAsDouble( wxPGPropArg id
) const;
521 #define wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL(TYPENAME, DEFVAL) \
522 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(DEFVAL) \
523 wxString typeName(wxS(TYPENAME)); \
524 wxVariant value = p->GetValue(); \
525 if ( value.GetType() != typeName ) \
527 wxPGGetFailed(p, typeName); \
531 #define wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL_WFALLBACK(TYPENAME, DEFVAL) \
532 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(DEFVAL) \
533 wxVariant value = p->GetValue(); \
534 if ( value.GetType() != wxS(TYPENAME) ) \
537 wxArrayString GetPropertyValueAsArrayString( wxPGPropArg id ) const
539 wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("arrstring",
541 return value
.GetArrayString();
545 wxLongLong_t
GetPropertyValueAsLongLong( wxPGPropArg id
) const
547 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
548 return p
->GetValue().GetLongLong().GetValue();
551 wxULongLong_t
GetPropertyValueAsULongLong( wxPGPropArg id
) const
553 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(0)
554 return p
->GetValue().GetULongLong().GetValue();
558 wxArrayInt
GetPropertyValueAsArrayInt( wxPGPropArg id
) const
560 wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("wxArrayInt",
568 wxDateTime
GetPropertyValueAsDateTime( wxPGPropArg id
) const
570 wxPG_PROP_ID_GETPROPVAL_CALL_PROLOG_RETVAL("datetime",
572 return value
.GetDateTime();
577 /** Returns a wxVariant list containing wxVariant versions of all
578 property values. Order is not guaranteed.
580 Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
581 category will be its own wxVariantList of wxVariant.
582 Use wxPG_INC_ATTRIBUTES to include property attributes as well.
583 Each attribute will be stored as list variant named
584 "@@<propname>@@attr."
587 wxVariant
GetPropertyValues( const wxString
& listname
= wxEmptyString
,
588 wxPGProperty
* baseparent
= NULL
, long flags
= 0 ) const
590 return m_pState
->DoGetPropertyValues(listname
, baseparent
, flags
);
595 Returns currently selected property. NULL if none.
597 @remarks When wxPG_EX_MULTIPLE_SELECTION extra style is used, this
598 member function returns the focused property, that is the
599 one which can have active editor.
601 wxPGProperty
* GetSelection() const;
604 Returns list of currently selected properties.
606 @remarks wxArrayPGProperty should be compatible with std::vector API.
608 const wxArrayPGProperty
& GetSelectedProperties() const
610 return m_pState
->m_selection
;
614 wxPropertyGridPageState
* GetState() const { return m_pState
; }
617 /** Similar to GetIterator(), but instead returns wxPGVIterator instance,
618 which can be useful for forward-iterating through arbitrary property
622 See @ref propgrid_iterator_flags.
624 virtual wxPGVIterator
GetVIterator( int flags
) const;
626 /** Hides or reveals a property.
628 If true, hides property, otherwise reveals it.
630 By default changes are applied recursively. Set this paramter
631 wxPG_DONT_RECURSE to prevent this.
633 bool HideProperty( wxPGPropArg id
,
635 int flags
= wxPG_RECURSE
);
637 #if wxPG_INCLUDE_ADVPROPS
638 /** Initializes *all* property types. Causes references to most object
639 files in the library, so calling this may cause significant increase
640 in executable size when linking with static library.
642 static void InitAllTypeHandlers();
644 static void InitAllTypeHandlers() { }
648 /** Inserts property to the property container.
651 New property is inserted just prior to this. Available only
652 in the first variant. There are two versions of this function
653 to allow this parameter to be either an id or name to
657 Pointer to the inserted property. wxPropertyGrid will take
658 ownership of this object.
661 New property is inserted under this category. Available only
662 in the second variant. There are two versions of this function
663 to allow this parameter to be either an id or name to
667 Index under category. Available only in the second variant.
668 If index is < 0, property is appended in category.
671 Returns id for the property,
675 - wxPropertyGrid takes the ownership of the property pointer.
677 - While Append may be faster way to add items, make note that when
678 both types of data storage (categoric and
679 non-categoric) are active, Insert becomes even more slow. This is
680 especially true if current mode is non-categoric.
687 wxPGProperty* my_cat_id = propertygrid->Append(
688 new wxPropertyCategory("My Category") );
692 // insert into category - using second variant
693 wxPGProperty* my_item_id_1 = propertygrid->Insert(
694 my_cat_id, 0, new wxStringProperty("My String 1") );
696 // insert before to first item - using first variant
697 wxPGProperty* my_item_id_2 = propertygrid->Insert(
698 my_item_id, new wxStringProperty("My String 2") );
703 wxPGProperty
* Insert( wxPGPropArg priorThis
, wxPGProperty
* newproperty
);
704 wxPGProperty
* Insert( wxPGPropArg parent
,
706 wxPGProperty
* newproperty
);
709 /** Returns true if property is a category. */
710 bool IsPropertyCategory( wxPGPropArg id
) const
712 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
713 return p
->IsCategory();
716 /** Returns true if property is enabled. */
717 bool IsPropertyEnabled( wxPGPropArg id
) const
719 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
720 return (!(p
->GetFlags() & wxPG_PROP_DISABLED
))?true:false;
724 Returns true if given property is expanded.
726 Naturally, always returns false for properties that cannot be expanded.
728 bool IsPropertyExpanded( wxPGPropArg id
) const;
731 Returns true if property has been modified after value set or modify
732 flag clear by software.
734 bool IsPropertyModified( wxPGPropArg id
) const
736 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
737 return ( (p
->GetFlags() & wxPG_PROP_MODIFIED
) ? true : false );
741 Returns true if property is selected.
743 bool IsPropertySelected( wxPGPropArg id
) const
745 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
746 return m_pState
->DoIsPropertySelected(p
);
750 Returns true if property is shown (ie hideproperty with true not
753 bool IsPropertyShown( wxPGPropArg id
) const
755 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
756 return (!(p
->GetFlags() & wxPG_PROP_HIDDEN
))?true:false;
759 /** Returns true if property value is set to unspecified.
761 bool IsPropertyValueUnspecified( wxPGPropArg id
) const
763 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(false)
764 return p
->IsValueUnspecified();
768 Disables (limit = true) or enables (limit = false) wxTextCtrl editor of
769 a property, if it is not the sole mean to edit the value.
771 void LimitPropertyEditing( wxPGPropArg id
, bool limit
= true );
773 /** If state is shown in it's grid, refresh it now.
775 virtual void RefreshGrid( wxPropertyGridPageState
* state
= NULL
);
777 #if wxPG_INCLUDE_ADVPROPS
779 Initializes additional property editors (SpinCtrl etc.). Causes
780 references to most object files in the library, so calling this may
781 cause significant increase in executable size when linking with static
784 static void RegisterAdditionalEditors();
786 static void RegisterAdditionalEditors() { }
789 /** Replaces property with id with newly created property. For example,
790 this code replaces existing property named "Flags" with one that
791 will have different set of items:
793 pg->ReplaceProperty("Flags",
794 wxFlagsProperty("Flags", wxPG_LABEL, newItems))
796 For more info, see wxPropertyGrid::Insert.
798 wxPGProperty
* ReplaceProperty( wxPGPropArg id
, wxPGProperty
* property
);
800 /** @anchor propgridinterface_editablestate_flags
802 Flags for wxPropertyGridInterface::SaveEditableState() and
803 wxPropertyGridInterface::RestoreEditableState().
805 enum EditableStateFlags
807 /** Include selected property. */
808 SelectionState
= 0x01,
809 /** Include expanded/collapsed property information. */
810 ExpandedState
= 0x02,
811 /** Include scrolled position. */
812 ScrollPosState
= 0x04,
813 /** Include selected page information.
814 Only applies to wxPropertyGridManager. */
816 /** Include splitter position. Stored for each page. */
817 SplitterPosState
= 0x10,
818 /** Include description box size.
819 Only applies to wxPropertyGridManager. */
823 Include all supported user editable state information.
824 This is usually the default value. */
825 AllStates
= SelectionState
|
834 Restores user-editable state.
836 See also wxPropertyGridInterface::SaveEditableState().
839 String generated by SaveEditableState.
842 Which parts to restore from source string. See @ref
843 propgridinterface_editablestate_flags "list of editable state
847 False if there was problem reading the string.
850 If some parts of state (such as scrolled or splitter position) fail to
851 restore correctly, please make sure that you call this function after
852 wxPropertyGrid size has been set (this may sometimes be tricky when
855 bool RestoreEditableState( const wxString
& src
,
856 int restoreStates
= AllStates
);
859 Used to acquire user-editable state (selected property, expanded
860 properties, scrolled position, splitter positions).
862 @param includedStates
863 Which parts of state to include. See @ref
864 propgridinterface_editablestate_flags "list of editable state flags".
866 wxString
SaveEditableState( int includedStates
= AllStates
) const;
869 Lets user to set the strings listed in the choice dropdown of a
870 wxBoolProperty. Defaults are "True" and "False", so changing them to,
871 say, "Yes" and "No" may be useful in some less technical applications.
873 static void SetBoolChoices( const wxString
& trueChoice
,
874 const wxString
& falseChoice
);
876 /** Sets an attribute for this property.
878 Text identifier of attribute. See @ref propgrid_property_attributes.
882 Optional. Use wxPG_RECURSE to set the attribute to child properties
885 void SetPropertyAttribute( wxPGPropArg id
,
886 const wxString
& attrName
,
890 DoSetPropertyAttribute(id
,attrName
,value
,argFlags
);
893 /** Sets property attribute for all applicapple properties.
894 Be sure to use this method only after all properties have been
897 void SetPropertyAttributeAll( const wxString
& attrName
, wxVariant value
);
900 Sets background colour of a property.
903 Property name or pointer.
906 New background colour.
909 Default is wxPG_RECURSE which causes colour to be set recursively.
910 Omit this flag to only set colour for the property in question
911 and not any of its children.
913 void SetPropertyBackgroundColour( wxPGPropArg id
,
914 const wxColour
& colour
,
915 int flags
= wxPG_RECURSE
);
917 /** Resets text and background colours of given property.
919 void SetPropertyColoursToDefault( wxPGPropArg id
);
922 Sets text colour of a property.
925 Property name or pointer.
928 New background colour.
931 Default is wxPG_RECURSE which causes colour to be set recursively.
932 Omit this flag to only set colour for the property in question
933 and not any of its children.
935 void SetPropertyTextColour( wxPGPropArg id
,
937 int flags
= wxPG_RECURSE
);
940 Returns background colour of first cell of a property.
942 wxColour
GetPropertyBackgroundColour( wxPGPropArg id
) const
944 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxColour())
945 return p
->GetCell(0).GetBgCol();
949 Returns text colour of first cell of a property.
951 wxColour
GetPropertyTextColour( wxPGPropArg id
) const
953 wxPG_PROP_ARG_CALL_PROLOG_RETVAL(wxColour())
954 return p
->GetCell(0).GetFgCol();
957 /** Sets text, bitmap, and colours for given column's cell.
960 - You can set label cell by setting column to 0.
961 - You can use wxPG_LABEL as text to use default text for column.
963 void SetPropertyCell( wxPGPropArg id
,
965 const wxString
& text
= wxEmptyString
,
966 const wxBitmap
& bitmap
= wxNullBitmap
,
967 const wxColour
& fgCol
= wxNullColour
,
968 const wxColour
& bgCol
= wxNullColour
);
971 /** Sets client data (void*) of a property.
973 This untyped client data has to be deleted manually.
975 void SetPropertyClientData( wxPGPropArg id
, void* clientData
)
977 wxPG_PROP_ARG_CALL_PROLOG()
978 p
->SetClientData(clientData
);
981 /** Sets editor for a property.
984 For builtin editors, use wxPGEditor_X, where X is builtin editor's
985 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
988 For custom editors, use pointer you received from
989 wxPropertyGrid::RegisterEditorClass().
991 void SetPropertyEditor( wxPGPropArg id
, const wxPGEditor
* editor
)
993 wxPG_PROP_ARG_CALL_PROLOG()
994 wxCHECK_RET( editor
, wxT("unknown/NULL editor") );
995 p
->SetEditor(editor
);
1000 /** Sets editor control of a property. As editor argument, use
1001 editor name string, such as "TextCtrl" or "Choice".
1003 void SetPropertyEditor( wxPGPropArg id
, const wxString
& editorName
)
1005 SetPropertyEditor(id
,GetEditorByName(editorName
));
1008 /** Sets label of a property.
1010 void SetPropertyLabel( wxPGPropArg id
, const wxString
& newproplabel
);
1013 Sets name of a property.
1016 Name or pointer of property which name to change.
1019 New name for property.
1021 void SetPropertyName( wxPGPropArg id
, const wxString
& newName
)
1023 wxPG_PROP_ARG_CALL_PROLOG()
1024 m_pState
->DoSetPropertyName( p
, newName
);
1028 Sets property (and, recursively, its children) to have read-only value.
1029 In other words, user cannot change the value in the editor, but they
1032 This is mainly for use with textctrl editor. Not all other editors fully
1035 By default changes are applied recursively. Set this paramter
1036 wxPG_DONT_RECURSE to prevent this.
1038 void SetPropertyReadOnly( wxPGPropArg id
,
1040 int flags
= wxPG_RECURSE
)
1042 wxPG_PROP_ARG_CALL_PROLOG()
1043 if ( flags
& wxPG_RECURSE
)
1044 p
->SetFlagRecursively(wxPG_PROP_READONLY
, set
);
1046 p
->ChangeFlag(wxPG_PROP_READONLY
, set
);
1049 /** Sets property's value to unspecified.
1050 If it has children (it may be category), then the same thing is done to
1053 void SetPropertyValueUnspecified( wxPGPropArg id
)
1055 wxPG_PROP_ARG_CALL_PROLOG()
1056 wxVariant nullVariant
;
1057 SetPropVal(p
, nullVariant
);
1062 Sets property values from a list of wxVariants.
1064 void SetPropertyValues( const wxVariantList
& list
,
1065 wxPGPropArg defaultCategory
= wxNullProperty
)
1068 if ( defaultCategory
.HasName() ) p
= defaultCategory
.GetPtr(this);
1069 else p
= defaultCategory
.GetPtr0();
1070 m_pState
->DoSetPropertyValues(list
, p
);
1074 Sets property values from a list of wxVariants.
1076 void SetPropertyValues( const wxVariant
& list
,
1077 wxPGPropArg defaultCategory
= wxNullProperty
)
1079 SetPropertyValues(list
.GetList(),defaultCategory
);
1083 /** Associates the help string with property.
1085 By default, text is shown either in the manager's "description"
1086 text box or in the status bar. If extra window style
1087 wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as a
1090 void SetPropertyHelpString( wxPGPropArg id
, const wxString
& helpString
)
1092 wxPG_PROP_ARG_CALL_PROLOG()
1093 p
->SetHelpString(helpString
);
1096 /** Set wxBitmap in front of the value.
1098 - Bitmap will be scaled to a size returned by
1099 wxPropertyGrid::GetImageSize();
1101 void SetPropertyImage( wxPGPropArg id
, wxBitmap
& bmp
)
1103 wxPG_PROP_ARG_CALL_PROLOG()
1104 p
->SetValueImage(bmp
);
1108 /** Sets max length of property's text.
1110 bool SetPropertyMaxLength( wxPGPropArg id
, int maxLen
);
1112 #if wxUSE_VALIDATORS
1113 /** Sets validator of a property.
1115 void SetPropertyValidator( wxPGPropArg id
, const wxValidator
& validator
)
1117 wxPG_PROP_ARG_CALL_PROLOG()
1118 p
->SetValidator(validator
);
1123 /** Sets value (long integer) of a property.
1125 void SetPropertyValue( wxPGPropArg id
, long value
)
1128 SetPropVal( id
, v
);
1131 /** Sets value (integer) of a property.
1133 void SetPropertyValue( wxPGPropArg id
, int value
)
1135 wxVariant
v((long)value
);
1136 SetPropVal( id
, v
);
1138 /** Sets value (floating point) of a property.
1140 void SetPropertyValue( wxPGPropArg id
, double value
)
1143 SetPropVal( id
, v
);
1145 /** Sets value (bool) of a property.
1147 void SetPropertyValue( wxPGPropArg id
, bool value
)
1150 SetPropVal( id
, v
);
1153 void SetPropertyValue( wxPGPropArg id
, const wchar_t* value
)
1155 SetPropertyValueString( id
, wxString(value
) );
1158 void SetPropertyValue( wxPGPropArg id
, const char* value
)
1160 SetPropertyValueString( id
, wxString(value
) );
1162 void SetPropertyValue( wxPGPropArg id
, const wxString
& value
)
1164 SetPropertyValueString( id
, value
);
1167 /** Sets value (wxArrayString) of a property.
1169 void SetPropertyValue( wxPGPropArg id
, const wxArrayString
& value
)
1172 SetPropVal( id
, v
);
1176 void SetPropertyValue( wxPGPropArg id
, const wxDateTime
& value
)
1179 SetPropVal( id
, v
);
1183 /** Sets value (wxObject*) of a property.
1185 void SetPropertyValue( wxPGPropArg id
, wxObject
* value
)
1188 SetPropVal( id
, v
);
1191 void SetPropertyValue( wxPGPropArg id
, wxObject
& value
)
1193 wxVariant
v(&value
);
1194 SetPropVal( id
, v
);
1198 /** Sets value (wxLongLong&) of a property.
1200 void SetPropertyValue( wxPGPropArg id
, wxLongLong_t value
)
1202 wxVariant v
= WXVARIANT(wxLongLong(value
));
1203 SetPropVal( id
, v
);
1205 /** Sets value (wxULongLong&) of a property.
1207 void SetPropertyValue( wxPGPropArg id
, wxULongLong_t value
)
1209 wxVariant v
= WXVARIANT(wxULongLong(value
));
1210 SetPropVal( id
, v
);
1214 /** Sets value (wxArrayInt&) of a property.
1216 void SetPropertyValue( wxPGPropArg id
, const wxArrayInt
& value
)
1218 wxVariant v
= WXVARIANT(value
);
1219 SetPropVal( id
, v
);
1223 /** Sets value (wxString) of a property.
1226 This method uses wxPGProperty::SetValueFromString, which all properties
1227 should implement. This means that there should not be a type error,
1228 and instead the string is converted to property's actual value type.
1230 void SetPropertyValueString( wxPGPropArg id
, const wxString
& value
);
1232 /** Sets value (wxVariant&) of a property.
1235 Use wxPropertyGrid::ChangePropertyValue() instead if you need to run
1236 through validation process and send property change event.
1238 void SetPropertyValue( wxPGPropArg id
, wxVariant value
)
1240 SetPropVal( id
, value
);
1244 /** Sets value (wxVariant&) of a property. Same as SetPropertyValue, but
1245 accepts reference. */
1246 void SetPropVal( wxPGPropArg id
, wxVariant
& value
);
1249 /** Adjusts how wxPropertyGrid behaves when invalid value is entered
1252 See @link vfbflags list of valid flags values@endlink
1254 void SetValidationFailureBehavior( int vfbFlags
);
1257 Sorts all properties recursively.
1260 This can contain any of the following options:
1261 wxPG_SORT_TOP_LEVEL_ONLY: Only sort categories and their
1262 immediate children. Sorting done by wxPG_AUTO_SORT option
1265 @see SortChildren, wxPropertyGrid::SetSortFunction
1267 void Sort( int flags
= 0 );
1270 Sorts children of a property.
1273 Name or pointer to a property.
1276 This can contain any of the following options:
1277 wxPG_RECURSE: Sorts recursively.
1279 @see Sort, wxPropertyGrid::SetSortFunction
1281 void SortChildren( wxPGPropArg id
, int flags
= 0 )
1283 wxPG_PROP_ARG_CALL_PROLOG()
1284 m_pState
->DoSortChildren(p
, flags
);
1287 // GetPropertyByName With nice assertion error message.
1288 wxPGProperty
* GetPropertyByNameA( const wxString
& name
) const;
1290 static wxPGEditor
* GetEditorByName( const wxString
& editorName
);
1292 // NOTE: This function reselects the property and may cause
1293 // excess flicker, so to just call Refresh() on a rect
1294 // of single property, call DrawItem() instead.
1295 virtual void RefreshProperty( wxPGProperty
* p
) = 0;
1299 bool DoClearSelection( bool validation
= false,
1303 In derived class, implement to set editable state component with
1304 given name to given value.
1306 virtual bool SetEditableStateItem( const wxString
& name
, wxVariant value
)
1314 In derived class, implement to return editable state component with
1317 virtual wxVariant
GetEditableStateItem( const wxString
& name
) const
1320 return wxNullVariant
;
1323 // Returns page state data for given (sub) page (-1 means current page).
1324 virtual wxPropertyGridPageState
* GetPageState( int pageIndex
) const
1326 if ( pageIndex
<= 0 )
1331 virtual bool DoSelectPage( int WXUNUSED(index
) ) { return true; }
1333 // Default call's m_pState's BaseGetPropertyByName
1334 virtual wxPGProperty
* DoGetPropertyByName( const wxString
& name
) const;
1338 // Deriving classes must set this (it must be only or current page).
1339 wxPropertyGridPageState
* m_pState
;
1341 // Intermediate version needed due to wxVariant copying inefficiency
1342 void DoSetPropertyAttribute( wxPGPropArg id
,
1343 const wxString
& name
,
1344 wxVariant
& value
, long argFlags
);
1346 // Empty string object to return from member functions returning const
1348 wxString m_emptyString
;
1351 // Cannot be GetGrid() due to ambiguity issues.
1352 wxPropertyGrid
* GetPropertyGrid()
1356 return m_pState
->GetGrid();
1359 // Cannot be GetGrid() due to ambiguity issues.
1360 const wxPropertyGrid
* GetPropertyGrid() const
1364 return static_cast<const wxPropertyGrid
*>(m_pState
->GetGrid());
1366 #endif // #ifndef SWIG
1368 friend class wxPropertyGrid
;
1369 friend class wxPropertyGridManager
;
1372 #endif // wxUSE_PROPGRID
1374 #endif // __WX_PROPGRID_PROPGRIDIFACE_H__