1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: interface of wxPGProperty
4 // Author: wxWidgets team
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
9 // -----------------------------------------------------------------------
12 @class wxPropertyGridInterface
14 Most of the shared property manipulation interface shared by wxPropertyGrid,
15 wxPropertyGridPage, and wxPropertyGridManager is defined in this class.
18 - In separate wxPropertyGrid component this class was known as
19 wxPropertyContainerMethods.
21 - wxPropertyGridInterface's property operation member functions all accept
22 a special wxPGPropArg id argument, using which you can refer to properties
23 either by their pointer (for performance) or by their name (for conveniency).
28 class WXDLLIMPEXP_PROPGRID wxPropertyGridInterface
33 virtual ~wxPropertyGridInterface() { }
36 Appends property to the list. wxPropertyGrid assumes ownership of the
37 object. Becomes child of most recently added category.
40 - wxPropertyGrid takes the ownership of the property pointer.
41 - If appending a category with name identical to a category already in
42 the wxPropertyGrid, then newly created category is deleted, and most
43 recently added category (under which properties are appended) is set
44 to the one with same name. This allows easier adding of items to same
45 categories in multiple passes.
46 - Does not automatically redraw the control, so you may need to call
47 Refresh() when calling this function after control has been shown for
50 wxPGProperty
* Append( wxPGProperty
* property
);
53 Same as Append(), but appends under given parent property.
56 Name or pointer to parent property.
61 wxPGProperty
* AppendIn( wxPGPropArg id
, wxPGProperty
* newProperty
);
64 In order to add new items into a property with private children (for
65 instance, wxFlagsProperty), you need to call this method. After
66 populating has been finished, you need to call EndAddChildren().
70 void BeginAddChildren( wxPGPropArg id
);
73 Deletes all properties.
75 virtual void Clear() = 0;
78 Deselect current selection, if any.
80 @return Returns @true if success (ie. validator did not intercept).
82 bool ClearSelection();
85 Resets modified status of all properties.
87 void ClearModifiedStatus();
90 Collapses given category or property with children.
92 @return Returns @true if actually collapsed.
94 bool Collapse( wxPGPropArg id
);
97 Collapses all items that can be collapsed.
99 @return Returns @false if failed (may fail if value in active
100 editor cannot be validated).
105 Changes value of a property, as if by user. Use this instead of
106 SetPropertyValue() if you need the value to run through validation
107 process, and also send the property change event.
109 @return Returns @true if value was successfully changed.
111 bool ChangePropertyValue( wxPGPropArg id
, wxVariant newValue
);
114 Resets value of a property to its default.
116 bool ClearPropertyValue( wxPGPropArg id
);
121 void DeleteProperty( wxPGPropArg id
);
126 bool DisableProperty( wxPGPropArg id
);
129 Returns true if all property grid data changes have been committed. Usually
130 only returns false if value in active editor has been invalidated by a
133 bool EditorValidate();
136 Enables or disables property.
139 Name or pointer to a property.
142 If @false, property is disabled instead.
144 bool EnableProperty( wxPGPropArg id
, bool enable
= true );
147 Called after population of property with fixed children has finished.
149 @see BeginAddChildren()
151 void EndAddChildren( wxPGPropArg id
);
154 Expands given category or property with children.
156 @return Returns @true if actually expanded.
158 bool Expand( wxPGPropArg id
);
161 Expands all items that can be expanded.
163 bool ExpandAll( bool expand
= true );
166 Returns list of expanded properties.
168 wxArrayPGProperty
GetExpandedProperties() const;
171 Returns id of first child of given property.
173 @remarks Does not return private children!
175 wxPGProperty
* GetFirstChild( wxPGPropArg id
);
178 /** Returns iterator class instance.
181 See @ref propgrid_iterator_flags. Value wxPG_ITERATE_DEFAULT causes
182 iteration over everything except private child properties.
185 Property to start iteration from. If NULL, then first child of root
189 Either wxTOP or wxBOTTOM. wxTOP will indicate that iterations start
190 from the first property from the top, and wxBOTTOM means that the
191 iteration will instead begin from bottommost valid item.
193 <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
194 instead of * operator, use GetProperty() method.
196 wxPropertyGridIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
197 wxPGProperty
* firstProp
= NULL
);
198 wxPropertyGridConstIterator
GetIterator( int flags
= wxPG_ITERATE_DEFAULT
,
199 wxPGProperty
* firstProp
= NULL
) const;
200 wxPropertyGridIterator
GetIterator( int flags
, int startPos
);
201 wxPropertyGridConstIterator
GetIterator( int flags
, int startPos
) const;
205 Returns id of first item that matches given criteria.
208 See @ref propgrid_iterator_flags.
210 wxPGProperty
* GetFirst( int flags
= wxPG_ITERATE_ALL
);
213 Returns id of property with given name (case-sensitive).
215 wxPGProperty
* GetProperty( const wxString
& name
) const
217 return GetPropertyByName(name
);
221 Adds to 'targetArr' pointers to properties that have given
222 flags 'flags' set. However, if 'inverse' is set to true, then
223 only properties without given flags are stored.
226 Property flags to use.
229 Iterator flags to use. Default is everything expect private children.
230 See @ref propgrid_iterator_flags.
232 void GetPropertiesWithFlag( wxArrayPGProperty
* targetArr
,
233 wxPGProperty::FlagType flags
,
234 bool inverse
= false,
235 int iterFlags
= (wxPG_ITERATE_PROPERTIES
|wxPG_ITERATE_HIDDEN
|wxPG_ITERATE_CATEGORIES
) ) const;
238 Returns value of given attribute. If none found, returns wxNullVariant.
240 wxVariant
GetPropertyAttribute( wxPGPropArg id
, const wxString
& attrName
) const;
243 Returns pointer of property's nearest parent category. If no category
246 wxPropertyCategory
* GetPropertyCategory( wxPGPropArg id
) const;
248 /** Returns client data (void*) of a property. */
249 void* GetPropertyClientData( wxPGPropArg id
) const;
252 Returns first property which label matches given string. NULL if none
253 found. Note that this operation is very slow when compared to
256 wxPGProperty
* GetPropertyByLabel( const wxString
& label
) const;
259 Returns property with given name. NULL if none found.
261 wxPGProperty
* GetPropertyByName( const wxString
& name
) const;
264 Returns child property 'subname' of property 'name'. Same as
265 calling GetPropertyByName("name.subname"), albeit slightly faster.
267 wxPGProperty
* GetPropertyByName( const wxString
& name
,
268 const wxString
& subname
) const;
271 Returns property's editor.
273 const wxPGEditor
* GetPropertyEditor( wxPGPropArg id
) const;
276 Returns help string associated with a property.
278 wxString
GetPropertyHelpString( wxPGPropArg id
) const;
281 Returns property's custom value image (NULL of none).
283 wxBitmap
* GetPropertyImage( wxPGPropArg id
) const;
285 /** Returns label of a property. */
286 const wxString
& GetPropertyLabel( wxPGPropArg id
);
288 /** Returns property's name, by which it is globally accessible. */
289 wxString
GetPropertyName( wxPGProperty
* property
);
292 Returns validator of a property as a reference, which you
293 can pass to any number of SetPropertyValidator.
295 wxValidator
* GetPropertyValidator( wxPGPropArg id
);
298 Returns property's value as wxVariant.
300 If property value is unspecified, Null variant is returned.
302 wxVariant
GetPropertyValue( wxPGPropArg id
);
304 /** Return's property's value as wxArrayInt. */
305 wxArrayInt
GetPropertyValueAsArrayInt( wxPGPropArg id
) const;
307 /** Returns property's value as wxArrayString. */
308 wxArrayString
GetPropertyValueAsArrayString( wxPGPropArg id
) const;
310 /** Returns property's value as bool */
311 bool GetPropertyValueAsBool( wxPGPropArg id
) const;
313 /** Return's property's value as wxDateTime. */
314 wxDateTime
GetPropertyValueAsDateTime( wxPGPropArg id
) const;
316 /** Returns property's value as double-precision floating point number. */
317 double GetPropertyValueAsDouble( wxPGPropArg id
) const;
319 /** Returns property's value as integer */
320 int GetPropertyValueAsInt( wxPGPropArg id
) const;
322 /** Returns property's value as integer */
323 long GetPropertyValueAsLong( wxPGPropArg id
) const;
325 /** Returns property's value as native signed 64-bit integer. */
326 wxLongLong_t
GetPropertyValueAsLongLong( wxPGPropArg id
) const;
329 Returns property's value as wxString. If property does not
330 use string value type, then its value is converted using
331 wxPGProperty::GetValueAsString().
333 wxString
GetPropertyValueAsString( wxPGPropArg id
) const;
335 /** Returns property's value as unsigned integer */
336 unsigned long GetPropertyValueAsULong( wxPGPropArg id
) const;
338 /** Returns property's value as native unsigned 64-bit integer. */
339 wxULongLong_t
GetPropertyValueAsULongLong( wxPGPropArg id
) const;
342 Returns a wxVariant list containing wxVariant versions of all
343 property values. Order is not guaranteed.
346 Use wxPG_KEEP_STRUCTURE to retain category structure; each sub
347 category will be its own wxVariantList of wxVariant.
349 Use wxPG_INC_ATTRIBUTES to include property attributes as well.
350 Each attribute will be stored as list variant named
351 "@@<propname>@@attr."
353 wxVariant
GetPropertyValues( const wxString
& listname
= wxEmptyString
,
354 wxPGProperty
* baseparent
= NULL
, long flags
= 0 ) const;
356 /** Returns currently selected property. */
357 wxPGProperty
* GetSelection() const;
360 Similar to GetIterator(), but instead returns wxPGVIterator instance,
361 which can be useful for forward-iterating through arbitrary property
365 See @ref propgrid_iterator_flags.
367 <b>wxPython Note:</b> Instead of ++ operator, use Next() method, and
368 instead of * operator, use GetProperty() method.
370 virtual wxPGVIterator
GetVIterator( int flags
) const;
373 Hides or reveals a property.
376 If @true, hides property, otherwise reveals it.
379 By default changes are applied recursively. Set this parameter
380 wxPG_DONT_RECURSE to prevent this.
382 bool HideProperty( wxPGPropArg id
, bool hide
= true, int flags
= wxPG_RECURSE
);
385 Initializes *all* property types. Causes references to most object
386 files in the library, so calling this may cause significant increase
387 in executable size when linking with static library.
389 static void InitAllTypeHandlers();
392 /** Inserts property to the property container.
395 New property is inserted just prior to this. Available only
396 in the first variant. There are two versions of this function
397 to allow this parameter to be either an id or name to
401 Pointer to the inserted property. wxPropertyGrid will take
402 ownership of this object.
405 New property is inserted under this category. Available only
406 in the second variant. There are two versions of this function
407 to allow this parameter to be either an id or name to
411 Index under category. Available only in the second variant.
412 If index is < 0, property is appended in category.
414 @return Returns newProperty.
418 - wxPropertyGrid takes the ownership of the property pointer.
420 - While Append may be faster way to add items, make note that when
421 both types of data storage (categoric and
422 non-categoric) are active, Insert becomes even more slow. This is
423 especially true if current mode is non-categoric.
430 wxPGProperty* my_cat_id = propertygrid->Append( new wxPropertyCategory("My Category") );
434 // insert into category - using second variant
435 wxPGProperty* my_item_id_1 = propertygrid->Insert( my_cat_id, 0, new wxStringProperty("My String 1") );
437 // insert before to first item - using first variant
438 wxPGProperty* my_item_id_2 = propertygrid->Insert( my_item_id, new wxStringProperty("My String 2") );
443 wxPGProperty
* Insert( wxPGPropArg priorThis
, wxPGProperty
* newProperty
);
444 wxPGProperty
* Insert( wxPGPropArg parent
, int index
, wxPGProperty
* newProperty
);
447 /** Returns @true if property is a category. */
448 bool IsPropertyCategory( wxPGPropArg id
) const;
450 /** Returns @true if property is enabled. */
451 bool IsPropertyEnabled( wxPGPropArg id
) const;
454 Returns true if given property is expanded. Naturally, always returns
455 @false for properties that cannot be expanded.
457 bool IsPropertyExpanded( wxPGPropArg id
) const;
460 Returns @true if property has been modified after value set or modify
461 flag clear by software.
463 bool IsPropertyModified( wxPGPropArg id
) const;
466 Returns true if property is shown (ie. HideProperty() with @true not
469 bool IsPropertyShown( wxPGPropArg id
) const;
472 Returns true if property value is set to unspecified.
474 bool IsPropertyValueUnspecified( wxPGPropArg id
) const;
477 Disables (limit = @true) or enables (limit = @false) wxTextCtrl editor
478 of a property, if it is not the sole mean to edit the value.
480 void LimitPropertyEditing( wxPGPropArg id
, bool limit
= true );
483 Initializes additional property editors (SpinCtrl etc.). Causes
484 references to most object files in the library, so calling this may
485 cause significant increase in executable size when linking with static
488 static void RegisterAdditionalEditors();
491 Replaces property with id with newly created one. For example,
492 this code replaces existing property named "Flags" with one that
493 will have different set of items:
496 pg->ReplaceProperty("Flags",
497 wxFlagsProperty("Flags", wxPG_LABEL, newItems))
502 wxPGProperty
* ReplaceProperty( wxPGPropArg id
, wxPGProperty
* property
);
505 @anchor propgridinterface_editablestate_flags
507 Flags for wxPropertyGridInterface::SaveEditableState() and
508 wxPropertyGridInterface::RestoreEditableState().
510 enum EditableStateFlags
512 /** Include selected property. */
513 SelectionState
= 0x01,
514 /** Include expanded/collapsed property information. */
515 ExpandedState
= 0x02,
516 /** Include scrolled position. */
517 ScrollPosState
= 0x04,
518 /** Include selected page information. Only applies to
519 wxPropertyGridManager. */
521 /** Include splitter position. Stored for each page. */
522 SplitterPosState
= 0x10,
524 /** Include all supported user editable state information. This is
525 usually the default value. */
526 AllStates
= SelectionState
| ExpandedState
| ScrollPosState
|
527 PageState
| SplitterPosState
531 Restores user-editable state. See also wxPropertyGridInterface::SaveEditableState().
534 String generated by SaveEditableState.
537 Which parts to restore from source string. See @ref propgridinterface_editablestate_flags
538 "list of editable state flags".
540 @return Returns @false if there was problem reading the string.
542 @remarks If some parts of state (such as scrolled or splitter position)
543 fail to restore correctly, please make sure that you call this
544 function after wxPropertyGrid size has been set (this may
545 sometimes be tricky when sizers are used).
547 bool RestoreEditableState( const wxString
& src
,
548 int restoreStates
= AllStates
);
551 Used to acquire user-editable state (selected property, expanded
552 properties, scrolled position, splitter positions).
554 @param includedStates
555 Which parts of state to include. See @ref propgridinterface_editablestate_flags
556 "list of editable state flags".
558 wxString
SaveEditableState( int includedStates
= AllStates
) const;
561 Sets strings listed in the choice dropdown of a wxBoolProperty.
563 Defaults are "True" and "False", so changing them to, say, "Yes" and
564 "No" may be useful in some less technical applications.
566 static void SetBoolChoices( const wxString
& trueChoice
,
567 const wxString
& falseChoice
);
570 Sets or clears flag(s) of all properties in given array.
573 Property flags to set or clear.
576 Set to true if you want to clear flag instead of setting them.
578 void SetPropertiesFlag( const wxArrayPGProperty
& srcArr
, wxPGProperty::FlagType flags
,
579 bool inverse
= false );
582 Sets an attribute for this property.
585 Text identifier of attribute. See @ref propgrid_property_attributes.
591 Optional. Use wxPG_RECURSE to set the attribute to child properties
594 @remarks Setting attribute's value to Null variant will simply remove it
595 from property's set of attributes.
597 void SetPropertyAttribute( wxPGPropArg id
, const wxString
& attrName
,
598 wxVariant value
, long argFlags
= 0 );
601 Sets property attribute for all applicapple properties.
602 Be sure to use this method only after all properties have been
605 void SetPropertyAttributeAll( const wxString
& attrName
, wxVariant value
);
608 Sets text, bitmap, and colours for given column's cell.
611 - You can set label cell by using column 0.
612 - You can use wxPG_LABEL as text to use default text for column.
614 void SetPropertyCell( wxPGPropArg id
,
616 const wxString
& text
= wxEmptyString
,
617 const wxBitmap
& bitmap
= wxNullBitmap
,
618 const wxColour
& fgCol
= wxNullColour
,
619 const wxColour
& bgCol
= wxNullColour
);
622 Sets client data (void*) of a property.
625 This untyped client data has to be deleted manually.
627 void SetPropertyClientData( wxPGPropArg id
, void* clientData
);
630 Sets editor for a property.
633 For builtin editors, use wxPGEditor_X, where X is builtin editor's
634 name (TextCtrl, Choice, etc. see wxPGEditor documentation for full
637 For custom editors, use pointer you received from wxPropertyGrid::RegisterEditorClass().
639 void SetPropertyEditor( wxPGPropArg id
, const wxPGEditor
* editor
);
642 Sets editor control of a property. As editor argument, use
643 editor name string, such as "TextCtrl" or "Choice".
645 void SetPropertyEditor( wxPGPropArg id
, const wxString
& editorName
);
648 Sets label of a property.
651 - Properties under same parent may have same labels. However,
652 property names must still remain unique.
654 void SetPropertyLabel( wxPGPropArg id
, const wxString
& newproplabel
);
657 Set modified status of a property and all its children.
659 void SetPropertyModifiedStatus( wxPGPropArg id
, bool modified
);
662 Sets property (and, recursively, its children) to have read-only value.
663 In other words, user cannot change the value in the editor, but they can
666 @remarks This is mainly for use with textctrl editor. Only some other
667 editors fully support it.
670 Property name or pointer.
673 Use @true to enable read-only, @false to disable it.
676 By default changes are applied recursively. Set this parameter
677 wxPG_DONT_RECURSE to prevent this.
679 void SetPropertyReadOnly( wxPGPropArg id
, bool set
= true,
680 int flags
= wxPG_RECURSE
);
683 Sets property's value to unspecified. If it has children (it may be
684 category), then the same thing is done to them.
686 void SetPropertyValueUnspecified( wxPGPropArg id
);
689 Sets various property values from a list of wxVariants. If property with
690 name is missing from the grid, new property is created under given
691 default category (or root if omitted).
693 void SetPropertyValues( const wxVariantList
& list
,
694 wxPGPropArg defaultCategory
= wxNullProperty
);
696 void SetPropertyValues( const wxVariant
& list
,
697 wxPGPropArg defaultCategory
= wxNullProperty
);
700 Associates the help string with property.
702 @remarks By default, text is shown either in the manager's "description"
703 text box or in the status bar. If extra window style
704 wxPG_EX_HELP_AS_TOOLTIPS is used, then the text will appear as
707 void SetPropertyHelpString( wxPGPropArg id
, const wxString
& helpString
);
710 Set wxBitmap in front of the value.
712 @remarks Bitmap will be scaled to a size returned by
713 wxPropertyGrid::GetImageSize();
715 void SetPropertyImage( wxPGPropArg id
, wxBitmap
& bmp
);
718 Sets max length of property's text.
720 bool SetPropertyMaxLength( wxPGPropArg id
, int maxLen
);
723 Sets validator of a property.
725 void SetPropertyValidator( wxPGPropArg id
, const wxValidator
& validator
);
727 /** Sets value (integer) of a property. */
728 void SetPropertyValue( wxPGPropArg id
, long value
);
730 /** Sets value (integer) of a property. */
731 void SetPropertyValue( wxPGPropArg id
, int value
);
733 /** Sets value (floating point) of a property. */
734 void SetPropertyValue( wxPGPropArg id
, double value
);
736 /** Sets value (bool) of a property. */
737 void SetPropertyValue( wxPGPropArg id
, bool value
);
739 /** Sets value (string) of a property. */
740 void SetPropertyValue( wxPGPropArg id
, const wxString
& value
);
742 /** Sets value (wxArrayString) of a property. */
743 void SetPropertyValue( wxPGPropArg id
, const wxArrayString
& value
);
745 /** Sets value (wxDateTime) of a property. */
746 void SetPropertyValue( wxPGPropArg id
, const wxDateTime
& value
);
748 /** Sets value (wxObject*) of a property. */
749 void SetPropertyValue( wxPGPropArg id
, wxObject
* value
);
751 /** Sets value (wxObject&) of a property. */
752 void SetPropertyValue( wxPGPropArg id
, wxObject
& value
);
754 /** Sets value (native 64-bit int) of a property. */
755 void SetPropertyValue( wxPGPropArg id
, wxLongLong_t value
);
757 /** Sets value (native 64-bit unsigned int) of a property. */
758 void SetPropertyValue( wxPGPropArg id
, wxULongLong_t value
);
760 /** Sets value (wxArrayInt&) of a property. */
761 void SetPropertyValue( wxPGPropArg id
, const wxArrayInt
& value
);
764 Sets value (wxString) of a property.
766 @remarks This method uses wxPGProperty::SetValueFromString(), which all
767 properties should implement. This means that there should not be
768 a type error, and instead the string is converted to property's
771 void SetPropertyValueString( wxPGPropArg id
, const wxString
& value
);
774 Sets value (wxVariant&) of a property.
776 @remarks Use wxPropertyGrid::ChangePropertyValue() instead if you need to
777 run through validation process and send property change event.
779 void SetPropertyValue( wxPGPropArg id
, wxVariant value
);
782 Adjusts how wxPropertyGrid behaves when invalid value is entered
786 See @ref propgrid_vfbflags for possible values.
788 void SetValidationFailureBehavior( int vfbFlags
);
791 Returns editor pointer of editor with given name;
793 static wxPGEditor
* GetEditorByName( const wxString
& editorName
);