Gain Design-Time Power with Control Editors, Part 1 of 2 : Page 3

Performing Map Visualization
Normally the Properties window examines a property and displays an appropriate representation of the property's value based on the property's type. For text and numeric properties it displays a textual value, for colors it displays a color sample, and for enumerated types it displays the name of the selected value.

For properties of type image, such as a form's BackgroundImage property, the Properties window displays a tiny thumbnail of the image and the name of the image resource stored in the property, for example, WindowsApplication1.My.Resources.Resources.us_map.

The Properties window can also display a representation of object types by showing the object's property values separated by commas. For example, it might display a Font property as Microsoft Sans Serif, 8.25pt and a Size property as 565, 430.

Finally, the Properties window can use custom type converters and editors to display values and allow you to edit them in the Properties window. For example, the Anchor and Dock properties for Windows Forms display special popup editors that let you set their values graphically.

The StateSelector control displays a special value for its Map property. The Properties window displays "(map)" if a map is loaded (See Figure 2) or "(none)" if no map is loaded.

The StateSelector control's Map property has the datatype StatesMap. The Properties window doesn't really understand the StatesMap class, so it has no clue about how to display the Map property's value.

The key to providing a custom display for a value in the Properties window is to make a type converter to translate a StatesMap value into a string. The first step is to add a TypeConverter attribute to the property's declaration. The following code shows the Map property's definition:

   Private m_Map As StatesMap = Nothing
   <Category("Data")> _
   <Description("The data describing the map borders.")> _
   <Browsable(True)> _
   <TypeConverter(GetType(StatesMapConverter))> _
   <Editor(GetType(StatesMapEditor), GetType(UITypeEditor))> _
   <DefaultValue(GetType(StatesMap), Nothing)> _
   Public Property Map() As StatesMap
      Get
         Return m_Map
      End Get
      Set(ByVal value As StatesMap)
         m_Map = value
         DoAutoSize()
         Me.Invalidate()
      End Set
   End Property

The control stores the property's value in the private variable m_Map. The Category and Description attributes tell the Properties window which category should hold the property and what description to display. The Browsable attribute indicates that developers should see the property in the Properties window.

The TypeConverter attribute tells the Properties window what class it can use to convert the property to other datatypes such as strings. The Editor and DefaultValue attributes are useful for editing the property's value and are covered in the next section of this article.

The Map property's code is straightforward. The Get procedure simply returns the value in m_Map. The Set procedure saves a new value in m_Map, and also calls the DoAutoSize method (which sizes the control to fit its map if the AutoSize property is True). Finally, it invalidates the control to force it to redraw.

With the property definition in place, you need to provide the type converter class, in this case StatesMapConverter shown in the following code. The code is actually fairly simple, but it looks imposing, largely because the two overridden methods have huge parameter lists:

   ' Converts RegionMap objects for Properties window display.
   Public Class StatesMapConverter
      Inherits TypeConverter
   
      ' We can convert StatesMap objects into a string.
      Public Overrides Function CanConvertTo( _
         ByVal context As _
         System.ComponentModel.ITypeDescriptorContext, _
         ByVal destinationType As System.Type) As Boolean
   
         If destinationType Is GetType(String) Then Return True
         Return MyBase.CanConvertTo(context, destinationType)
      End Function
   
      ' Convert a StatesMap object into a string.
      Public Overrides Function ConvertTo( _
         ByVal context As _
         System.ComponentModel.ITypeDescriptorContext, _
         ByVal culture As System.Globalization.CultureInfo, _
         ByVal value As Object, _
         ByVal destinationType As System.Type) As Object
   
         If destinationType Is GetType(String) Then
            If (value Is Nothing) Then
               Return "(none)"
            Else
               Return "(map)"
            End If
         End If
         Return MyBase.ConvertTo(context, culture, _
            value, destinationType)
      End Function
   End Class

The StatesMapConverter class inherits from the TypeConverter base class and overrides two methods: CanConvertTo and ConvertTo. The CanConvertTo function returns a Boolean to indicate whether the converter can convert a value from the property's type to another type. The overridden version returns True only if the destination type is String, letting the Properties window know that the converter can convert a StatesMap into a String.

Function ConvertTo does the actual conversion, converting a StatesMap object into a String. It first checks the destination data type, taking action only if it's converting the object into a String. The function returns either (none) or (map) depending on whether the StatesMap value is Nothing or has a value.

That's all there is to it. If the Map property's value is Nothing, the type converter tells the Properties window to display (none); otherwise the type converter tells the Properties window to display the value (map).

Author's Note: Using a similar technique, you can use a type converter to display objects as compound values. For example, suppose the Contact class includes FirstName, LastName, and Phone properties. You could build a type converter to convert the set of individual property values into a string containing the properties separated by commas. By making the type converter inherit from the ExpandableObjectConverter class, you can let the user expand the property into sub-properties, much as you can expand a Font or Size property. While this article doesn't explain how to display object values in this way, my book Expert One-on-One Visual Basic 2005 Design and Development does.

Previous Page

Next Page