PropertyGrid

• Download demo project (VS 2005) - 64.5 Kb
• Download demo project (VS 2003) - 61.1 Kb

Introduction

The system property grid control is a very useful and efficient control for displaying different types of data. But this control has a complicated interface for providing data (see my recent article). This article describes a control derived from the system property grid and which provides more convenient interfaces for data display.

Control

Puma.Control.PropertyGrid Windows control

The control provides a more convenient user interface for browsing the properties of an object in the System.Windows.Forms.PropertyGrid control and extend its functionality.

Remarks:

To use the property grid, you create a new instance of the Puma.Controls.PropertyGrid class on a parent control. Invoke the SetContent method, passing as a parameter, the interface that describes a root item for which to display the properties.

Interfaces that describe items for displaying in a property grid

When the user wants to display an item in the property grid, they have to implement these interfaces for those items. For examples of the implementation of interfaces, see the Puma.Controls.PropertyGrid.PGITemplates namespace. One of those templates use the XmlXsdDocument class as a data provider.

IPropertyGridItem interface

Describes the essential information for the displayed item.

Properties:

• IPropertyGridItemType Type{get}

  Gets the interface which describes the type of the item value.

  If this property returns null, then the property grid does not use this item and some functionality is lost. (For example, the validation of changed items, enumerated values, and so on.)

• string Name {get}

  Gets the name of the item.

• string DisplayedName {get}

  Gets the name that can be displayed in the PropertyGrid.

• string Value {get, set}

  Gets or sets the value of the item in the string representation.

• string Documentation {get}

  Gets the description of the item which can be displayed in the bottom part of the property grid when the item is selected.

• bool IsReadOnly{get}

  Gets a value indicating whether this property is read-only. If read-only, the property grid prohibits changing the value of the item.

• IPropertyGridChildItems Childs{get}

  Gets child items of the item. See IPropertyGridChildItems.

• IPropertyGridItem Parent {get}

  Get the parent item of the item.

IPropertyGridChildItems interface

Describes an item's child items.

Remarks:

See IPropertyGridChildItemsFragment.

Methods:

• IPropertyGridChildItemsFragment this[string Name]{get}

  Gets the appropriate fragment by the specified name.

Interface IPropertyGridChildItemsFragment

Remarks:

Describes sub-sets of child items of an item. Each item in the property grid may have a child that is encountered more than once (array of items). All are allocated in the same fragment. Even if the child item is not present in the child collection but can be added to it, this item is created as a separate fragment.

Properties:

• IPropertyGridItem this[int Index]

  Gets appropriate child item by its specified index.

• string IPropertyGridItem DisplayedName

  Gets the name that can be displayed in a different context of the PropertyGrid.

Contexts:

When the add/remove item appears in the context menu (by the user clicking the left mouse button on a grid item), this property is selected as the text that defines the name of the item that can be added or removed.

• bool IsCanInsert {get}

  Inherited from the Puma.Collections.IShred interface. Item can be added to the fragment.

• bool IsCanRemove {get}

  Inherited from the Puma.Collections.IShred interface. Item can be removed from the fragment.

Methods:

• IPropertyGridItem InsertItem(int Index)

  This method creates and inserts item, if possible, to the collection of child items and return the item. If return is null, the child item failed to be inserted.

• IPropertyGridItem RemoveItem(int Index)

  This method removes an item, if possible, from the collection of child items and return the item. If return is null, the child item failed to be removed.

IPropertyGridItemType interface

Describes the type of an item.

Remarks:

The type of an item affects the behavior of the PropertyGrid when the user sets a new value to the item; this also influences how this value is displayed.

Properties:

• System.Type SystemType {get}

  Return the system type of the item value.

• bool IsComplexType {get}

  Return whether the item has a complex type (can contain child items).

• bool IsComparable{get}

  Return whether the item has a min and max specified value. In the case of this property being true, the SimpleType property should return the ISimpleTypeCompared interface.

• bool IsEnum{get}

  Return whether the item value has a standard Values collection. In the case that this property is true, the SimpleType property should return the ISimpleTypeEnum interface.

• bool IsParseable{get}

  Return whether the system type of the item value has a Parse(string StrVal) method. See the SystemType property.

• IMinMaxOccurs MinMaxOccurs {get}

  Return how many times the item can be encountered in the parent object. See the IMinMaxOccurs interface.

• Object SimpleType {get}

  Return null, or an object having one of the following types: ISimpleTypeCompared, ISimpleTypeEnum, or ISimpleTypeString.

Remarks:

• If the item value has min and max specified values, then this property should return the ISimpleTypeCompared interface.
• If the item value has a standard value collection, then this property should return the ISimpleTypeEnum interface.
• If the item value has a string type and a restriction on the maximum length the string may be, this property should return the ISimpleTypeString interface.
• If none of these cases apply, return null.

• DefaultValue {get}

  Returns the string representation of the default item value. If the item does not have one, return null.

Interface IMinMaxOccurs

Defines how many times the item can be encountered in the parent.

Properties:

• int MinOccurs {get}

  Return the minimum number of times the item can be encountered in the parent item. If a value of –1 is returned, then MinOccurs is ignored.

• int MaxOccurs {get}

  Return the maximum number of times the item can be encountered in the parent item. If a value of –1 is returned, then MaxOccurs is ignored.

ISimpleTypeCompared interface

Defines what minimum and maximum values for the item value specified are.

Properties:

• object MinValue{get}

  Defines what minimum value is specified for the item value. The returned object should have the same type as the item. If null is returned, then MinValue is ignored.

• object MaxValue{get}

  Defines what maximum value is specified for the item value. The returned object should have the same type as the item. If null is returned, then MaxValue is ignored.

ISimpleTypeEnum interfaec

Defines the standard values collection for the item value.

Properties:

• Puma.Collections.NameValueCollectionUnique NameValuePares{get}

  Returns a name / value pair of the standard values for the item value. In this pair, the name is displayed in the appropriate drop-down list of the item, and the value is set as the item value when the corresponding name is selected.

ISimpleTypeString interface

Defines what the minimum and maximum number of characters are accepted for the item value, if it has the string type.

Properties:

• int MinLength {get}

  Minimum number of characters that are accepted for the item value. If –1 is returned, then MinLength is ignored.

• int MaxLength {get}

  Maximum number of characters that are accepted for the item value. If –1 is returned, then MaxLength is ignored.

How these interfaces are used by the property grid

• string IPropertyGridItem.DisplayedName

  String that is displayed as the item name in the property grid window for the corresponding item.

• string IPropertyGridItem.Value
  • get – string that is displayed as the item value in the property grid window for the corresponding item.
  • set – string value that is set for the item when the user changes it in the property grid.
• string IPropertyGridItem.Documentation

  String that is displayed in the bottom part of property grid when the corresponding item is selected.

• bool IsReadOnly

  

  Value that is defined when the corresponding item can be changed by the user.

• string IPropertyGridChildItemsFragment.DisplayedName

  

  When the add/remove item context menu appears (i.e., the user clicks on the left mouse button on a grid item), this value is selected as the text that defines the name of the item that can be added or removed.

• bool IPropertyGridChildItemsFragment.IsCanInsert

  

  When the add/remove item context menu appears (i.e., the user clicks on the left mouse button on a parent grid item), this value identifies the item available for adding. If true is returned, this item is displayed in the context menu list of items for adding.

• bool IPropertyGridChildItemsFragment.IsCanRemove

  

  When the add/remove item context menu appears (i.e., the user clicks on the left mouse button on a parent grid item), this value identifies the item available for removing. If true is returned, this item is displayed in the context menu list of items for removing.

• System.Type IPropertyGridItemType.SystemType

  If this property is not null and IPropertyGridItemType.IsParsable is true, the following occurs: when a user changes an item value in the property grid, this new value is validated by this type, i.e., the property grid defines whether the value entered falls into the range of valid values for this type. If not, then the recently changed value is canceled, and the old one is displayed. Also see: IsParsable.

• bool IPropertyGridItemType.IsComplexType {get}

  

  If this property returns true, and it is assumed that the item can contain sub-items, it is displayed in the property grid as an extensible item.

• bool IPropertyGridItemType.IsComparable{get}

  If this property returns true, then SimpleType should return the ISimpleTypeCompared interface. When the user changes an item value in the property grid, this new value is validated by the ISimpleTypeCompared interface, i.e., the property grid defines if this entered value falls within the range provided by the interface. Also, this value type should satisfy the IsParseable condition. If the entered value falls outside the range of valid values, then the entered value is canceled and the old value is displayed .

• bool IPropertyGridItemType.IsEnum {get}

  

  If this property returns true, then SimpleType returns the ISimpleTypeEnum interface. This return value should contain name / value pairs. The value should be the same type as the item type. Each name is added to the dropdown list that is displayed when the user changes the item value. When the user selects the appropriate name, the item value is changed to the value corresponding to the selected name.

• bool IPropertyGridItemType.IsParseable{get}

  See System.Type IPropertyGridItemType.SystemType.

• Object IPropertyGridItemType.SimpleType{get}

  When the item value has string type, and this property returns the ISimpleTypeString interface when the user changes the value of the item, it is validated by this interface, i.e., the interface checks if the string does not exceed the length defined for it. If it exceeds the length, the new value is canceled and the old value is restored. Also see: IsComparable and IsEnum properties.

• IMinMaxOccurs IPropertyGridItemType.MinMaxOccurs

  Not used, since the number of child items that can be added or removed from the item is controlled by the IPropertyGridChildItemsFragment.IsCanInsert and IPropertyGridChildItemsFragment.IsCanRemoved properties.

Thanks to Arnie Berg for his contribution in this article's writing.