Difference between revisions of "Design of Control Tables"
Line 59: | Line 59: | ||
=== Using Custom Classes inside a Control Table === | === Using Custom Classes inside a Control Table === | ||
+ | Sometimes simple types are not convenient in a <tt>ControlTable</tt>, and a special class is developed to hold the configuration. There are several considerations when making such a class: | ||
+ | # The class must be serializable | ||
+ | # The class must be clonable | ||
+ | # The <tt>ControlTable</tt> must have one or more properties with the type of the class | ||
+ | # When the control table is cloned, each property with the custom type class must also be cloned | ||
+ | # The class may have a custom editor. To use the custom editor, set the Editor attribute for each property | ||
+ | # Changes in the custom object must trigger the <tt>PropertyChanged</tt> event: | ||
+ | ## If the entire object is changed, it is sufficient to just send the event from the property of the ControlTable (typically this works fine | ||
+ | for custom classes with editors) | ||
+ | ## If a property is changed inside the object the <tt>ControlTable</tt> must listen for <tt>PropertyChanged</tt> from the object, and propagate the event. | ||
=== Cloning Control Tables === | === Cloning Control Tables === |
Revision as of 10:58, 21 May 2010
Introduction
A ControlTable is a class whose instances can hold user settings. ControlTables are typically presented in a PropertyGrid, which means that no user interface has to be built for properties with a simple type.
By adding the sttribute Slu.Heureka.BaseLayer.ConfigurationHandling.ControlTable a class is marked as a ControlTable. The system will automatically discover all ControlTables at startup.
Implementation of Control Tables
Creating a new Control Table
Although not required, it is recommended that ControlTables inherit from UndoablePropertyChangedBase. This base class simplifies implementation of the INotifyPropertyChanged interface, which should be used for classes presented in the PropertyGrid.
To add a property of a simple type, follow this example:
public int CleaningVariation {
get { return _cleaningVariation; } [System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.NoInlining)] set { if (value < 0) throw new ArgumentOutOfRangeException("value", "CleaningVariation must be >= 0"); ChangeProperty(ref _cleaningVariation, value); }
}
Note the following:
- NoInlining must be set for the set method, otherwise property changed won't work in release mode
- Validation can be done before the value is changed
- UndoablePropertyChangedBase implements ChangeProperty methods with overloads for the most common simple types.
Presentation of Control Tables
Since ControlTables are presented in a PropertyGrid, the attributes in System.ComponentModel aids with the presentation of a ControlTable, such as:
- Category
- Properties with the same Category are grouped in the PropertyGrid
- DisplayName
- The DisplayName is the name for the property shown in the PropertyGrid.
- Description
- The Description is shown at the bottom of the PropertyGrid when the property is selected. The description should give a brief help to the user.
- DefaultValue
- The DefaultValue is the value set when a new instance of a ControlTable is created. Also, the PropertyGrid shows properties with the default value in a normal font, and properties with a changed value in a bold font.
- Browsable
- The Browsable attribute can be set to false to hide properties in the property grid (unconditionally, to conditionally hide properties see Hiding Properties Conditionally
In addition to this, a number of additional attributes and type converters are available in the Slu.Heureka.BaseLayer.ComponentModel namespace:
- ObjectDefaultValues
- Allows default values to be set on other types than simple types
- PercentTypeConverter
- Presents a property with a fraction (e.g. 0.03) to be presented as a percentage (e.g. 3%)
Hiding Properties Conditionally
If the ControlTable inherits from UndoablePropertyChangedBase, it is easy to hide properties conditionally. Two protected methods can be overriden to hide properties:
- GetCategoryNamesToHide
- Gets names of entire categories to be hidden
- GetPropertyNamesToHide
- Gets names of properties to be hidden
Each time the ControlTable is rendered, these two methods are called, and any returned category or property will be hidden from the user.
Using Custom Classes inside a Control Table
Sometimes simple types are not convenient in a ControlTable, and a special class is developed to hold the configuration. There are several considerations when making such a class:
- The class must be serializable
- The class must be clonable
- The ControlTable must have one or more properties with the type of the class
- When the control table is cloned, each property with the custom type class must also be cloned
- The class may have a custom editor. To use the custom editor, set the Editor attribute for each property
- Changes in the custom object must trigger the PropertyChanged event:
- If the entire object is changed, it is sufficient to just send the event from the property of the ControlTable (typically this works fine
for custom classes with editors)
- If a property is changed inside the object the ControlTable must listen for PropertyChanged from the object, and propagate the event.