(untagged)

XmlGrid

El'Cachubrey

0.00/5 (No votes)

9 Jun 2005

A control for displaying and editing data of an XML file in a property grid.

Sample Image

Introduction

The control is intended for displaying and editing data of an XML file in property grid. Also this control fits data for convenient displaying by particular rules defined in a schema file.

Displaying rules are incorporated in the schema file of the corresponding XML file. These rules are defined by means of custom attributes.

Attribute	Reference	Apply to
`XmlGrid:CaptionIsName` type: `boolean` default: `false`	If this attribute has "`true`" value, then all elements of the XML document will be displayed with the name corresponding to the "`name`" attribute. If this attribute has "`false`" value, then all elements of the XML document will be displayed with name corresponding to the "`msdata:Caption`" attribute if one exists, otherwise to the "`name`" attribute.	`xs:schema`
`XmlGrid:Omit` type: `boolean` default: `false`	`false`: has no effect `true`: element to which this attribute is applied is not displayed in the property grid. Sub-elements are also not displayed.	`xs:element`
`XmlGrid:Gap` type: `boolean` default: `false`	`false`: has no effect `true`: element to which this attribute is applied is not displayed in the property grid. But sub-elements are displayed.	first child element of "`xs:schema`" or first child element of "`xs:element`" which also has same attribute and all those parents having the same attribute. All sibling elements of this element will be displayed with same rules as one.
`XmlGrid:OmitXmlDeclarartion` type: `boolean` default: `false`	If this attribute has "`true`" value, then XML declaration is not displayed in the property grid. If this attribute has "`false`" value, then XML declaration is displayed in the property grid.	`xs:schema`
`XmlGrid:ParentEntry` type: `boolean` default: `false`	`false`: has no effect `true`: element�s value to which this attribute is applied is displayed in the property grid as composite part of the parent element value.	simple type "`xs:element`" which belongs to a complex type "`xs:elemen`"
`XmlGrid:BindAsCategory` type: `boolean` default: `false`	`false`: has no effect. `true`: element to which this attribute is applied is displayed in the property grid as category. All sub-elements of this element will belong to this category.	Applied to first child element of "`xs:schema`" or to first child element of "`xs:element`" which has `Gap` attribute with "`true`" value and all those parents having the same one. All sibling elements of this element will be displayed with same rules as one.
`XmlGrid:BindAsArray` type: `boolean` default: `false`	`false`: has no effect. `true`: all elements with this attribute is displayed in property grid as a collection. Create particular subset for all elements of XML document with equal name. This subset can be edited with the �Collection editor� dialog or/and �Context menu�. Attributes `minOccurs`, `maxOccurs` when applied to the same element define number of elements enabled for add/remove from subset.	`xs:element`
Enumeration restriction	Value of any element defined with "`xs:enumeration` restriction" is displayed as drop list, with items filled with "`value`" attributes.	`xs:simpleType`/ `xs:restriction`/ `xs:enumeration`
Min, max length restriction	Value of any element with restrictions "`xs:minLength`", "`xs:maxLength`" will be controlled by this restriction when edited.	`xs:simpleType`/`xs:restriction base="xs:string"`/`[xs:minLength],[xs:maxLength]`
	`xs:documantation` element defines property reference which will be displayed in the bottom part of the property grid.	`xs:annotation`/ `xs:documantation`
`masdata:ReadOnly`	`false`: has no effect. `true`: element to which this attribute is applied is displayed in the property grid as read only property.	simple type `xs:element`
Type: `xs:date`	Value with this type can be edited with `DateTimePicker` control. Also this value will be controlled by pattern �yyyy-MM-dd� when edited.	`xs:element type="xs:date"`
Type: `xs:time`	Value with this type will be controlled by pattern �HH:mm:ss� when edited.	`xs:element type="xs:time"`
Type: `xs:dateTime`	Value with this type can be edited with `DateTimePicker` control. Also this value will be controlled by pattern �yyyy-MM-dd HH:mm:ss� when edited.	`xs:element type="xs:dateTime"`

Methods

Methods	Reference
`LoadXml(string XmlFileName, string XmlSchemaFileName)`	Load XML file in `XmlGrid` by rules defined in the XML schema file. If `XmlFileName` is `null`, then XML file will be created automatically by data from the schema file.
`SaveXml(string XmlFileName)`	Save XML file currently loaded in `XmlGrid`.

Properties

Properties	Reference
`XmlFileName`	Return name of XML file currently loaded in `XmlGrid`.
`XmlSchemaFileName`	Return name of XSD file currently loaded in `XmlGrid`.
`XmlDocument`	Return `XmlDocument` related with XML file currently loaded in `XmlGrid`.
`XmlSchema`	Return `XmlSchema` related with XSD file currently loaded in `XmlGrid`.
`OmitXmlDeclaration`	Return value of `XmlGrid:OmitXmlDeclaration` attribute from currently loaded XSD file.
`CaptionIsName`	Return value of `XmlGrid:CaptionIsName` attribute from currently loaded XSD file.
`EditCollectionMode`	Define way for edited elements to be displayed as collections (see `XmlGrid:BindAsArray` attribute). `EditCollectionModes.CollectionEditor` - subset of collectioned nodes can be edited with the �Collection editor� dialog. `EditCollectionModes.ContextMenu` - subset of collectioned nodes can be edited with the �Context menu�. `EditCollectionModes.BothEditors` - subset of collectioned nodes can be edited with both the �Context menu� and the �Collection editor� dialog. `EditCollectionModes.NoneEditor` - subset of collectioned nodes cannot be edited.

Background

Any object can provide information about itself for the property grid through reflection or through the System.ComponentModel.IcustomTypeDescriptor interface. This project uses the second case.

Fig1

Fig 1. demonstrates how property grid receives information about a displayed object through the ICustomTypeDescriptor object. This is an incomplete schema but one that exposes the most important parts of the routine.

Property grid selects into itself an object derived from ICustomTypeDescriptor interface, by calling the SelectedObject property.
Property grid invokes the GetProperties() method of the selected object which returns a collection of property descriptors (instances of classes derived from ProprertyDescriptor).
PropertyDescriptor contains methods and properties for description of a name, attributes, value and other parameters of the displayed property.
Property grid retrieves necessary data for each returned property descriptor and displays the corresponding properties in the property grid.
A peculiar property of PropertyDescriptor class is the Converter property. One return object derived form System.ComponentModel.TypeConverter class provides a unified way of converting types of values to other types, as well as for accessing standard values and subproperties. Property grid uses this object for the proper reflection value of the displayed property.

Using the code

Fig2

Fig 2. demonstrates XmlGrid common schema.

There are 6 valuable objects of the XmlGrid project.

XmlGrid � Windows control derived from System.Windows.Forms.PropertyGrid. Object which is supplied to external users for loading, editing and saving an XML file.
XlmGridNode � Class derived from System.ComponentModel.ICustomTypeDescriptor used by XmlGrid for retrieving information about displayed elements.
XmlGridNodeSchemaBinded � Class providing information about a particular XML node and related with one description peeked up from corresponding schema file.
Classes derived from System.ComponentModel.PropertyDescriptor which describe information about each particular element.

Fig3

Fig.3 demonstrates XmlGrid static structure.

XmlGrid static structure reference

The XmlGrid class is derived from the System.Windows.Forms class. It provides for the user a number of methods for loading, saving and retrieving information of an XML file. Contains XmlGridNode object corresponding to the topmost XML node (document node) of the currently loaded XML file.
The XmlGridNode class derived from System.Windows.ComponentModel.ITypeDescriptor provides data necessary for displaying nodes of an XML file as properties of the PropertyGrid Windows control.
Contains instance of the XmlGridNodeSchemaBinded class corresponding to the current XML node. Contains instance of PropertyDescriptorCollection class which contains a set of objects derived from the PropertyDescriptor class.

All interface members are implemented in a standard way to use the TypeDescriptor class besides the GetProperties(�) method which initializes and returns an object of the PropertyDescriptorCollection class.
The XmlGridNodeSchemaBinded class contains methods and properties which describe a particular XML node in conjunction with data retrieved from an XSD file for this one.
The XmlGridNodePropertyDescriptor class is derived from System.ComponentModel.PopertyDescriptor class and used by PropertyGrid for retrieving information about complex type nodes (nodes which contain child nodes) by means of invoking properties and methods of one. The most essential method of this class is the GetValue(�) method which returns the XmlGridNode object, which in turn describes sub-properties (each sub-property corresponds to a particular child node of this node) of the current property.
Contains XmlGridNode object which is passed during instantiation time through the constructor.
The XmlGriNodeSimpleTypeNodeDescriptor class derived from System.ComponentModel.PopertyDescriptor class is used by PropertyGrid for retrieving information about simple type nodes.
Contains XmlGridNodeSchemaBinded object which is passed on instantiation time through the constructor and then used by the PropertyGrid which requests information about this property.
The XmlGridNodesCollectionPropertyDescriptor class derived from System.ComponentModel.PopertyDescriptor class is used by the PropertyGrid for retrieving information about nodes which are recognized as collection nodes.
Contains instances of CollectionEditor and XmlGidNodesCollection classes.
The XmlGidNodesCollection class derived from System.Windows.ComponentModel.ITypeDescriptor provides data necessary for displaying nodes which are contained in the current collection as properties of the PropertyGrid Windows control.
Contains instance of System.ComponentModel.PropertyDescriptorCollection class which is created on instantiation.
The CollectionEditor class derived from System.ComponentModel.Design.ArrayEditor provides a user interface that can edit collections of nodes.
Contains collection of CollectionEditorEntry objects.
The CollectionEditorEntry class derived from System.ComponentModel.ICustomTypeDescriptor interface provides data for displaying corresponding nodes in the CollectionEditor user interface.
Contains System.ComponentModel.PropertyDescriptor object which is passed on instantiation through the constructor.

For all other details, see the code!

Troubles

If the object properties that are displayed by using the PropertyGrid class have child members that display a modal dialog box by using the UITypeEditor class, you receive the following error message when you close the modal dialog box: "Index was outside the bounds of the array". The fix can be found here.
In the collection edit entry dialog, names of members are displayed as "CollectionEditorEntry".

References

Customized display of collection data in a PropertyGrid.

History

31 May 2005 [originated].
8 July 2005
- Added support for the following types: xs:date, xs:time, xs:dateTime.
9 July 2005
- Added new mean for editing elements which are displayed as collections (see XmlGrid:BindAsArray attribute).
- Feature now available to add and remove elements to collection through context menu.
  
  Pic. 1. Demonstrates how to add elements to a collection.
  
  Pic. 2. Demonstrates how to remove elements from a collection.
Attributes minOccurs, maxOccurs when applied to the same element define number of elements enabled to add/remove from subset. If those limits are exceeded then corresponding context menu items are disabled.
Added new property EditCollectionMode to XmlGrid control, related with subject above.

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here