Design of Control Tables - Revision history

Fkl: /* Serialization and Deserialization of Control Tables */

2010-05-21T09:02:33Z

Serialization and Deserialization of Control Tables

Fkl: /* Extending Control Tables */

2010-05-21T09:02:12Z

Extending Control Tables

Fkl: /* Cloning Control Tables */

2010-05-21T09:00:40Z

Cloning Control Tables

Fkl: /* Using Custom Classes inside a Control Table */

2010-05-21T08:58:39Z

Using Custom Classes inside a Control Table

Fkl: /* Hiding Properties Conditionally */

2010-05-21T08:40:44Z

Hiding Properties Conditionally

Fkl: /* Creating a new Control Table */

2010-05-21T08:35:52Z

Creating a new Control Table

2010-05-21T07:53:09Z

Created page with '== Introduction == A <tt>ControlTable</tt> is a class whose instances can hold user settings. <tt>ControlTables</tt> are typically presented in a <tt>PropertyGrid</tt>, which me�?�'

New page

== Introduction ==

A <tt>ControlTable</tt> is a class whose instances can hold user settings. <tt>ControlTables</tt> are typically presented in a <tt>PropertyGrid</tt>, which means that no user interface has to be built for properties with a simple type.

By adding the sttribute <tt>Slu.Heureka.BaseLayer.ConfigurationHandling.ControlTable</tt> a class is marked as a <tt>ControlTable</tt>. The system will automatically discover all <tt>ControlTables</tt> at startup.

== Implementation of Control Tables ==

=== Creating a new Control Table ===

Although not required, it is recommended that <tt>ControlTables</tt> inherit from <tt>UndoablePropertyChangedBase</tt>. This base class simplifies implementation of the INotifyPropertyChanged interface, which should be used for classes presented in the <tt>PropertyGrid</tt>.

To add a property of a simple type, follow this example:

<tt>
public int CleaningVariation
{
get { return _cleaningVariation; }
[System.Runtime.CompilerServices.MethodImpl(System.Runtime.CompilerServices.MethodImplOptions.NoInlining)]
set
{
if (value < 0)
throw new ArgumentOutOfRangeException("value", "CleaningVar must be >= 0");
ChangeProperty(ref _cleaningVariation, value);
}
}
</tt>

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
* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for
=== Presentation of Control Tables ===

Since <tt>ControlTables</tt> are presented in a <tt>PropertyGrid</tt>, the attributes in <tt>System.ComponentModel</tt> aids with the presentation of a <tt>ControlTable</tt>, such as:

;Category: Properties with the same Category are grouped in the <tt>PropertyGrid</tt>
;DisplayName: The DisplayName is the name for the property shown in the <tt>PropertyGrid</tt>.
;Description: The Description is shown at the bottom of the <tt>PropertyGrid</tt> 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 <tt>ControlTable</tt> is created. Also, the <tt>PropertyGrid</tt> 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|Hiding Properties Conditionally]]

In addition to this, a number of additional attributes and type converters are available in the <tt>Slu.Heureka.BaseLayer.ComponentModel</tt> 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 ===
=== Using Custom Classes inside a Control Table ===

=== Cloning Control Tables ===
=== Extending Control Tables ===

=== Serialization and Deserialization of Control Tables ===

← Older revision		Revision as of 09:02, 21 May 2010
Line 81:		Line 81:

	It is possible to extend a <tt>ControlTable</tt> by inheriting from it. When <tt>ControlTables</tt> are loaded automatically, only the <tt>ControlTable</tt> lowest in the inheritance hierarchy will be loaded.		It is possible to extend a <tt>ControlTable</tt> by inheriting from it. When <tt>ControlTables</tt> are loaded automatically, only the <tt>ControlTable</tt> lowest in the inheritance hierarchy will be loaded.
−
−	~~=== Serialization and Deserialization of Control Tables ===~~

← Older revision		Revision as of 09:02, 21 May 2010
Line 79:		Line 79:

	=== Extending Control Tables ===		=== Extending Control Tables ===
		+
		+	It is possible to extend a <tt>ControlTable</tt> by inheriting from it. When <tt>ControlTables</tt> are loaded automatically, only the <tt>ControlTable</tt> lowest in the inheritance hierarchy will be loaded.

	=== Serialization and Deserialization of Control Tables ===		=== Serialization and Deserialization of Control Tables ===

← Older revision		Revision as of 08:58, 21 May 2010
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 ===

← Older revision		Revision as of 08:40, 21 May 2010
Line 49:		Line 49:

	=== Hiding Properties Conditionally ===		=== Hiding Properties Conditionally ===
		+
		+	If the <tt>ControlTable</tt> inherits from <tt>UndoablePropertyChangedBase</tt>, 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 <tt>ControlTable</tt> 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 ===		=== Using Custom Classes inside a Control Table ===

@@ Line 72: / Line 72: @@
 === Cloning Control Tables ===
 === Extending Control Tables ===
 === Serialization and Deserialization of Control Tables ===

@@ Line 21: / Line 21: @@
+     {
          if (value < 0)
-             throw new ArgumentOutOfRangeException("value", "CleaningVar must be >= 0");
+             throw new ArgumentOutOfRangeException("value", "CleaningVariation must be >= 0");
          ChangeProperty(ref _cleaningVariation, value);
+     }
@@ Line 29: / Line 29: @@
 Note the following:
-* NoInlining must be set for the set method, otherwise property changed won't work in release mode
+* <tt>NoInlining</tt> 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
-* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for
+* <tt>UndoablePropertyChangedBase</tt> implements <tt>ChangeProperty</tt> methods with overloads for the most common simple types.
 === Presentation of Control Tables ===