tsai
/
wpftoolkit
mirror of https://github.com/xceedsoftware/wpftoolkit.git
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

Updated PropertyGrid (markdown)

master
DianeXceed 9 years ago
parent
41235503d0
commit
ed571e6ee9
1 changed files with 85 additions and 83 deletions
Whitespace
Show all changes Ignore whitespace when comparing lines Ignore changes in amount of whitespace Ignore changes in whitespace at EOL
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. 168
      PropertyGrid.md

168
PropertyGrid.md

@ -3,21 +3,21 @@ Derives from Control
The PropertyGrid control allows you inspect and edit properties of an object. This PropertyGrid allows you to autogenerate all properties or specify the specific properties you want to display. You can use the standard editors that are provided with the PropertyGrid or you can use custom editors that target a Type, specific properties, or both. The PropertyGrid also supports complex properties, which allows you to drill down into a nested property hierarchy. The PropertyGrid control allows you inspect and edit properties of an object. This PropertyGrid allows you to autogenerate all properties or specify the specific properties you want to display. You can use the standard editors that are provided with the PropertyGrid or you can use custom editors that target a Type, specific properties, or both. The PropertyGrid also supports complex properties, which allows you to drill down into a nested property hierarchy.
* [Specifying Properties](#specifying_properties) * [Specifying Properties](#specifying-properties)
* Custom Editors * [Custom Editors](#custom-editors)
* [DataTemplates](#custom_editors_dataTempates) * [DataTemplates](#custom-editors-with-datatemplates)
* [Attributes](#custom_editors_attributes) * [Attributes](#custom-editors-with-attributes)
* [Custom ItemsSource](#custom_itemssource) * [Custom ItemsSource](#custom-itemssource)
* [Expandable Properties](#expandable_properties) * [Expandable Properties](#expandable-properties)
![](PropertyGrid_propertygrid.jpg) [[PropertyGrid_propertygrid.jpg]]
{anchor:specifying_properties}
## Specifying Properties ### Specifying Properties
By default the propertyGrid will autogenerate all the properties for a given object. You can override this behavior by setting the AutoGenerateProperties property to False, and then provide a collection of PropertyDefinitions of the properties you would like to show. By default the propertyGrid will autogenerate all the properties for a given object. You can override this behavior by setting the AutoGenerateProperties property to False, and then provide a collection of PropertyDefinitions of the properties you would like to show.
![](PropertyGrid_specifyingproperties.jpg) [[PropertyGrid_specifyingproperties.jpg]]
{{ ```
<xctk:PropertyGrid x:Name="_propertyGrid" Width="450" Margin="10" <xctk:PropertyGrid x:Name="_propertyGrid" Width="450" Margin="10"
AutoGenerateProperties="False"> AutoGenerateProperties="False">
<!-- Only the following properties will be displayed in the PropertyGrid --> <!-- Only the following properties will be displayed in the PropertyGrid -->
@ -27,9 +27,9 @@ By default the propertyGrid will autogenerate all the properties for a given obj
<xctk:PropertyDefinition TargetProperties="PetNames" /> <xctk:PropertyDefinition TargetProperties="PetNames" />
</xctk:PropertyGrid.PropertyDefinitions> </xctk:PropertyGrid.PropertyDefinitions>
</xctk:PropertyGrid> </xctk:PropertyGrid>
}} ```
## Custom Editors ### Custom Editors
By default the PropertyGrid comes with 19 built-in editors: By default the PropertyGrid comes with 19 built-in editors:
* ByteUpDownEditor * ByteUpDownEditor
@ -52,14 +52,14 @@ By default the PropertyGrid comes with 19 built-in editors:
* TextBlockEditor * TextBlockEditor
* TextBoxEditor * TextBoxEditor
* TimeSpanEditor * TimeSpanEditor
{anchor:custom_editors_dataTempates}
**Custom Editors with DataTemplates** ### Custom Editors with DataTemplates
You can override the default editors with your own custom editors with a DataTemplate. Simply define an EditorDefinition that either targets a Type, property name, or both and set the EditorDefinition.EditorTemplate to an instance of a DataTemplate. Be sure to bind your custom editor to the bound property item's Value property. You can override the default editors with your own custom editors with a DataTemplate. Simply define an EditorDefinition that either targets a Type, property name, or both and set the EditorDefinition.EditorTemplate to an instance of a DataTemplate. Be sure to bind your custom editor to the bound property item's Value property.
![](PropertyGrid_customeditor_datatemplates.jpg) [[PropertyGrid_customeditor_datatemplates.jpg]]
{{ ```
<xctk:PropertyGrid x:Name="_propertyGrid" Grid.Row="1" <xctk:PropertyGrid x:Name="_propertyGrid" Grid.Row="1"
Width="450" MaxHeight="375" Margin="10" Width="450" MaxHeight="375" Margin="10"
SelectedObject="{Binding}"> SelectedObject="{Binding}">
@ -138,15 +138,15 @@ You can override the default editors with your own custom editors with a DataTem
</xctk:PropertyGrid.EditorDefinitions> </xctk:PropertyGrid.EditorDefinitions>
</xctk:PropertyGrid> </xctk:PropertyGrid>
}} ```
{anchor:custom_editors_attributes}
**Custom Editors with Attributes** ### Custom Editors with Attributes
You can supply editors for a property by using the System.ComponentModel.EditorAttribute. In order to provide an editor with an attribute, the editor MUST implement the ITypeEditor interface. Your editor can be a simple class or a complex UserControl. You can supply editors for a property by using the System.ComponentModel.EditorAttribute. In order to provide an editor with an attribute, the editor MUST implement the ITypeEditor interface. Your editor can be a simple class or a complex UserControl.
![](PropertyGrid_customeditor_attributes.jpg) [[PropertyGrid_customeditor_attributes.jpg]]
{{ ```
public class CustomAttributEditorPerson public class CustomAttributEditorPerson
{ {
[Category("Information")](Category(_Information_)) [Category("Information")](Category(_Information_))
@ -163,11 +163,11 @@ You can supply editors for a property by using the System.ComponentModel.EditorA
[Editor(typeof(LastNameUserControlEditor), typeof(LastNameUserControlEditor))](Editor(typeof(LastNameUserControlEditor),-typeof(LastNameUserControlEditor))) [Editor(typeof(LastNameUserControlEditor), typeof(LastNameUserControlEditor))](Editor(typeof(LastNameUserControlEditor),-typeof(LastNameUserControlEditor)))
public string LastName { get; set; } public string LastName { get; set; }
} }
}} ```
Using a custom class: **Using a custom class:**
{{ ```
//Custom editors that are used as attributes MUST implement the ITypeEditor interface. //Custom editors that are used as attributes MUST implement the ITypeEditor interface.
public class FirstNameEditor : Xceed.Wpf.Toolkit.PropertyGrid.Editors.ITypeEditor public class FirstNameEditor : Xceed.Wpf.Toolkit.PropertyGrid.Editors.ITypeEditor
{ {
@ -186,11 +186,11 @@ Using a custom class:
return textBox; return textBox;
} }
} }
}} ```
Using a UserControl: **Using a UserControl:**
{{ ```
<UserControl x:Class="Samples.Modules.PropertyGrid.LastNameUserControlEditor" <UserControl x:Class="Samples.Modules.PropertyGrid.LastNameUserControlEditor"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation" xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml" xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
@ -200,9 +200,9 @@ Using a UserControl:
<Button Click="Button_Click">Clear</Button> <Button Click="Button_Click">Clear</Button>
</StackPanel> </StackPanel>
</UserControl> </UserControl>
}} ```
{{ ```
public partial class LastNameUserControlEditor : UserControl, ITypeEditor public partial class LastNameUserControlEditor : UserControl, ITypeEditor
{ {
public LastNameUserControlEditor() public LastNameUserControlEditor()
@ -232,14 +232,14 @@ Using a UserControl:
return this; return this;
} }
} }
}} ```
{anchor:custom_itemssource}
## Custom ItemsSource ### Custom ItemsSource
Sometimes it is desirable to want to provide a collection of values represented by a ComboBox for a given property. The PropertyGrid supports this scenario by creating a class that implements the IItemsSource interface and decorating your property with the ItemsSourceAttribute. Sometimes it is desirable to want to provide a collection of values represented by a ComboBox for a given property. The PropertyGrid supports this scenario by creating a class that implements the IItemsSource interface and decorating your property with the ItemsSourceAttribute.
![](PropertyGrid_custom_itemssource.jpg) [[PropertyGrid_custom_itemssource.jpg]]
{{ ```
public class Person public class Person
{ {
[Category("Writing")](Category(_Writing_)) [Category("Writing")](Category(_Writing_))
@ -248,10 +248,10 @@ Sometimes it is desirable to want to provide a collection of values represented
[ItemsSource(typeof(FontSizeItemsSource))](ItemsSource(typeof(FontSizeItemsSource))) [ItemsSource(typeof(FontSizeItemsSource))](ItemsSource(typeof(FontSizeItemsSource)))
public double WritingFontSize { get; set; } public double WritingFontSize { get; set; }
} }
}} ```
The custom ItemsSource class: The custom ItemsSource class:
{{ ```
public class FontSizeItemsSource : IItemsSource public class FontSizeItemsSource : IItemsSource
{ {
public ItemCollection GetValues() public ItemCollection GetValues()
@ -276,14 +276,14 @@ The custom ItemsSource class:
return sizes; return sizes;
} }
} }
}} ```
{anchor:expandable_properties}
## Expandable Properties ### Expandable Properties
Sometimes it is neccessary to show the properties of a complex object. The PropertyGrid supports this scenario and allows you to drill down into a property's heirarchy. To enable this behavior you must decorate your property with the ExpandableObject attribute. Sometimes it is neccessary to show the properties of a complex object. The PropertyGrid supports this scenario and allows you to drill down into a property's heirarchy. To enable this behavior you must decorate your property with the ExpandableObject attribute.
![](PropertyGrid_expandableobject.jpg) [[PropertyGrid_expandableobject.jpg]]
{{ ```
public class Person public class Person
{ {
[Category("Information")](Category(_Information_)) [Category("Information")](Category(_Information_))
@ -296,43 +296,45 @@ Sometimes it is neccessary to show the properties of a complex object. The Prop
[ExpandableObject](ExpandableObject) [ExpandableObject](ExpandableObject)
public Person Spouse { get; set; } public Person Spouse { get; set; }
} }
}} ```
## Properties ### Properties
|| Property || Description | Property | Description |
| AdvancedOptionsMenu | Gets/Sets the contextual menu to use when the advanced menu button is clicked. | --- | --- |
| AutoGenerateProperties | Get/Sets if the propertyGrid should generate all properties for a given object. If False you must provide PropertyDefinitions for the properties you want to generate. | AdvancedOptionsMenu | Gets or sets the contextual menu to use when the advanced menu button is clicked. |
| EditorDefinitions| Get/Sets a collection of custom editors to use in place of the default editors. (Breaking change as of v1.6.0: previously was CustomTypeEditors.) | AutoGenerateProperties | Get or sets if the propertyGrid should generate all properties for a given object. If False you must provide PropertyDefinitions for the properties you want to generate. |
| Filter | Gets/Sets the filter used to filter the visible properties in the PropertyGrid. | EditorDefinitions| Gets or sets a collection of custom editors to use in place of the default editors. (Breaking change as of v1.6.0: previously was CustomTypeEditors.) |
| FilterWatermark | Gets/Sets the watermark used in the filter field. | Filter | Gets or sets the filter used to filter the visible properties in the PropertyGrid. |
| HideInheritedProperties | Gets or sets if the Inherited properties of the selected object will be hidden. Default is False. | FilterWatermark | Gets or sets the watermark used in the filter field. |
| IsCategorized | Gets/Sets the layout of the PropertyGrid. | HideInheritedProperties | Gets or sets if the Inherited properties of the selected object will be hidden. Default is False. |
| IsReadOnly | Gets or sets a value indicating whether the property grid is read-only. | IsCategorized | Gets or sets the layout of the PropertyGrid. |
| NameColumnWidth | Gets/Sets the width of the property name column. | IsReadOnly | Gets or sets a value indicating whether the property grid is read-only. |
| Properties | Gets the current collection of generated PropertyItems. | NameColumnWidth | Gets or sets the width of the property name column. |
| PropertyDefinitions | When **AutoGenerateProperties** = False, gets/sets the properties that will be generated by the PropertyGrid | Properties | Gets the current collection of generated PropertyItems. |
| SelectedObject | Gets/Sets the current object the PropertyGrid is inspecting, | PropertyDefinitions | When **AutoGenerateProperties** = False, gets or sets the properties that will be generated by the PropertyGrid. |
| SelectedObjectName | Gets/Sets the **SelectedObject** name. | SelectedObject | Gets or sets the current object the PropertyGrid is inspecting. |
| SelectedObjectType | Gets/Sets the Type of the **SelectedObject**. | SelectedObjectName | Gets or sets the **SelectedObject** name. |
| SelectedObjectTypeName | Gets/Sets the name of the Type of the **SelectedObject**. | SelectedObjectType | Gets or sets the Type of the **SelectedObject**. |
| SelectedProperty | Gets or sets the selected property or returns null if the selection is empty. | SelectedObjectTypeName | Gets or sets the name of the Type of the **SelectedObject**. |
| SelectedPropertyItem | Gets the currently selected PropertyItem | SelectedProperty | Gets or sets the selected property or returns null if the selection is empty. |
| ShowAdvancedOptions | Gets/Sets the visibility of the advanced options button next to the properties. | SelectedPropertyItem | Gets the currently selected PropertyItem. |
| ShowPreview | Gets or sets if the preview of the control is displayed | ShowAdvancedOptions | Gets or sets the visibility of the advanced options button next to the properties. |
| ShowDescriptionByTooltip | Gets/Sets if the Description of the PropertyItem will be displayed as a tooltip on the PART_Name of the PropertyItem. When ShowDescriptionByTooltip is True and the DescriptionAttribute on the PropertyItem is not null and not empty, it will be displayed as a tooltip. | ShowPreview | Gets or sets if the preview of the control is displayed. |
| ShowSearchBox | Gets/Sets a value indicating whether the search box is displayed. By default, true. | ShowDescriptionByTooltip | Gets or sets if the Description of the PropertyItem will be displayed as a tooltip on the PART_Name of the PropertyItem. When ShowDescriptionByTooltip is True and the DescriptionAttribute on the PropertyItem is not null and not empty, it will be displayed as a tooltip. |
| ShowSortOptions | Gets/Sets a value indicating whether the show sort options are displayed (Categorized and Alphabetical). By default, true. | ShowSearchBox | Gets or sets a value indicating whether the search box is displayed. By default, true. |
| ShowSummary | Gets or sets a value indicating whether the summary pane is shown. | ShowSortOptions | Gets or sets a value indicating whether the show sort options are displayed (Categorized and Alphabetical). By default, true. |
| ShowTitle | Gets or sets a value indicating whether the PropertyGrid's title is displayed. | ShowSummary | Gets or sets a value indicating whether the summary pane is shown. |
| UpdateTextBoxSourceOnEnterKey | Gets or sets if the source of the propertItem represented by a TextBox will be updated when Enter key is pressed. | ShowTitle | Gets or sets a value indicating whether the PropertyGrid's title is displayed. |
| UpdateTextBoxSourceOnEnterKey | Gets or sets if the source of the propertItem represented by a TextBox will be updated when Enter key is pressed. |
## Events
|| Event || Description ### Events
| ClearPropertyItem | This event is raised when an property item is about to be remove from the display in the PropertyGrid. This allow the user to remove any attached handler in the PreparePropertyItem event. | Event | Description |
| PreparePropertyItem | This event is raised when a property item is about to be displayed in the PropertyGrid. This allow the user to customize the property item just before it is displayed. | --- | --- |
| PropertyValueChanged | Raised when a property's value changes. | ClearPropertyItem | This event is raised when an property item is about to be remove from the display in the PropertyGrid. This allow the user to remove any attached handler in the PreparePropertyItem event. |
| SelectedObjectChanged | Raised when SelectedObject changes. | PreparePropertyItem | This event is raised when a property item is about to be displayed in the PropertyGrid. This allow the user to customize the property item just before it is displayed. |
| SelectedPropertyItemChanged | Raised when SelectedProperty changes. | PropertyValueChanged | Raised when a property's value changes. |
| SelectedObjectChanged | Raised when SelectedObject changes. |
**Support this project, check out the [Plus Edition](https://xceed.com/xceed-toolkit-plus-for-wpf/).** | SelectedPropertyItemChanged | Raised when SelectedProperty changes. |
---
---
**Support this project, check out the [Plus Edition](https://xceed.com/xceed-toolkit-plus-for-wpf/).**
Write Preview
Loading…
Cancel
Save