Property Grid

PropertyGrid is a grid-based control that provides user interface for browsing and editing the properties of an object.

Binding to an object

The PropertyGrid control can be bound to any object or an array of objects as specified by its selectedObject property. If showAllProperties is set to true, the control enumerates all properties and fields of the object and its prototype chain, resolves their data types and displays their name and value in a grid layout. If showAllProperties is set to false, only properties and fields included in the metaData dictionary are displayed.

Custom metadata

The metaData property of PropertyGrid is a dictionary that stores the properties' configuration data in the form "propertyName": {configurationObject}. The list of the supported fields in the configuration object includes:

- dataType
The control tires to resolve the property data type automatically based on its value. The automatically resolvable types are StringType, BooleanType, DateType, IntegerType, RealNumberType, LookupType. Any properties that cannot be automatically resolved will be created with the ObjectType. You can override this behavior and explicitly set the dataType in property's configuration.

- category
If category names are provided, the control will group and sort the properties by their category.

- displayName
Use it to override the default display title (propertyName).

- customEditor
The default in-place editors created by the control for the Date, DateTime, Image and Lookup data types are:

• <input type="date"> for Date
• <input type="datetime-local"> for DateTime
• <input type="file"> for Image
• <select> for Lookup

You can replace the default editors with a corresponging control from the MindFusion.Common.UI library (e.g. DateTimePicker for Date and DateTime types, ImagePicker for Image type, CheckListPicker for Lookup type) by setting the "customEditor" field in property's configuration. The value of the "customEditor" field can be an empty object or a dictionary of property names and values, that you wish to set for the alternative UI control.

- customType
Provides another way to customize a default inplace editor by setting its type attribute e.g. in to display <input type="color"> for a property, call:

JavaScript

propGrid.metaData.set("colorProperty", { customType: "color" });

- customAttributes
Provides further customization of a default editor by setting additional attributes e.g. in order to display <input type="range" min="0" max="10" step="1"> for a property, call:

JavaScript

propGrid.metaData.set("rangeProperty", { 
    customAttributes: {
        type: "range",
        min: 0,
        max: 10,
        step: 1
});

- values and keyValues
The Lookup data type requires either a "values" array or a "keyValues" map of items to choose from. The default in-place editor for the Lookup type is <select>. You could set the customEditor field in configuration in order to use CheckListPicker instead, which allows multiple selection and has a built-in support for enums and flag enums.

- nullable and nullValue
Right-clicking the property name displays a context menu that allows you to clear the corresponding property's value. To disable this, set nullable to false. To specify a custom value to be used instead of null, assign it to the nullValue field.

- allowAdd and allowRemove
True by default, these two fields specify whether Add and Remove Item buttons are displayed when collection object is selected.

- __selectedObject__
You can specify metadata for the main object instead of a property by using the __selectedObject__ keyword instead of a propertyName e.g.

JavaScript

propGrid.metaData.set(
    "__selectedObject__", {
        dataType: dv.CollectionType
});

Read-only properties

Set the showReadonlyProperties property to specify whether or not read-only properties and fields should be displayed. By default, the control will not display in-place editors for read-only properties and they will be grayed-out. You can override this behavior by setting editReadonlyProperties to true.

Events

The PropertyGrid control raises a number of events, which can also be used for controlling the display of properties.

• the rowLoading event is raised before a property is enumerated and can be used to cancel the enumeration of certain properties or applying changes to their meta data dictionary.
• currentObjectChanging and currentObjectChanged events are raised before and after the current object, whose properties are displayed in the control is changed, e.g. when expanding a property of Collection or Object types. You can use the currentObjectChanging event to pass different metaData maps to the control, which can be necessary, for example, when different objects contain properties with the same name.
• the propertyValueChanging and propertyValueChanged events are raised before and after user modifications to a property value are passed to the underlying object.

Accessing the current object

The currently displayed object can be accessed through the currentObject getter. The currently selected property can be accessed through the currentProperty getter. Objects that are members of a collection property can be accessed by the combination of currentProperty and currentIndex.

Editing collections

When displaying an object of CollectionType, the control shows "Add" and "Remove" buttons in the header area. You can bind your custom code to these buttons' actions by handling the propertyValueChanging event and checking whether the event arguments action field equals RowAction.Create or RowAction.Delete.

Rebinding

To refresh the PropertyGrid control's displayed data after making external changes to the underlying object, call the rebind method.

User interface

The header of the control displays a "Group by category" button and a "Sort" button, and "Add" and "Remove" buttons when a collection object is selected. The footer of the control displays a tab for every object that has been selected. Clicking on a tab closes the current object, and all objects that are higher in the chain. Upon right-click on the property name column, a context menu is shown, which allows setting null / default values. You can search for a property name by typing in the property name column.