Understanding Control Concepts
Before discussing design time tools (we'll get there eventually), you should know what the StateSelector control does. This control displays a StatesMap object. That object contains an array of MapState objects that represent regions on the map. Each MapState has a Name
property and contains an array of Point objects that define its border.
The control loads a file containing an XML serialization of a StatesMap object and draws the MapStates that it contains. At run time, users can click on the states to select and deselect them as shown in Figure 1
|Author's Note: You can use the MapMaker program, included in this article's download, to build map serializations. It lets you load an image file containing a map and then trace over the image to define the states. This program is useful for building map files but doesn't demonstrate any design time features so it's not described here.)
Here's a brief overview of the StateSelector control's properties and methods. The BorderColor
property determines the color used to draw the states' borders. The SelectedColor
properties determine the color used to fill selected and non-selected states.
property holds one of the LineStyles enumeration values: Solid
, or Dotted
. It determines the line styles used to draw the states' borders.
The control's Selected property gets or sets a comma-separated list of the selected states' names. For example, for the states selected in Figure 1, the property returns the string "ND, MN, WI, SD, NE, KS, MO, IL, IN." If you set this property, the control automatically selects the appropriate states.
The control's LoadMap method loads a map's XML serialization. The SelectAll, DeselectAll, and ToggleAll methods give you a programmatic way to select, deselect, or toggle the selection status of all the map's states.
Exceptional Design-Time Support
The Properties window does a great job of allowing developers to view and modify common control properties. It displays numeric and text values and lets the user enter new ones, validating numeric values. It provides dropdown lists for Boolean values and enumerated types. It automatically displays selection dialogs for colors, fonts, and images.
However, there are times when the Properties window's support doesn't quite do the trick. For example, the Selected property lets you get and set the selected states textually, but it would be really handy to view and set these values graphically as shown in Figure 1—and that's possible. The Properties window can display custom editors such as this one—but not without some additional help. Other advanced features such as smart tags, command verbs, and property pages also require extra work.
The following list summarizes the design time features that make using the StateSelector control easier:
- In the Properties window shown in Figure 2, the LineStyle property displays a sample (a dashed line in this example). The Map property displays (map) if a map is loaded (as is the case here) or (none) if no map is loaded.
|Figure 2. StateSelector Properties: The StateSelector control provides custom displays for the LineStyle and Map properties in the Properties window.||
|Figure 3. Selecting a LineStyle: The LineStyle property lets you select a value from a graphical dropdown list.||
- If you click the dropdown arrow to the right of the LineStyle property, the dropdown list shown in Figure 3 appears, letting you select a new style.
- If you select the Map property, an ellipsis appears to the right. If you click the ellipsis, a file selection dialog appears to let you select a map file. You can remove the map by right-clicking the Map property and selecting Reset, or by selecting the text in the Map property and pressing the Delete key.
- If you click the Selected property, an ellipsis appears to the right. If you click the ellipsis, the dialog shown in Figure 1 appears so you can select and deselect states. When you're done, click OK or Cancel to accept or cancel the changes to the Selected property.
- The smart tag popup shown in Figure 4 lets you set the control's key properties in a popup.
- Command verbs appear both at the bottom of the Properties window shown in Figure 2 and Figure 3, and at the bottom of the smart tag popup shown in Figure 4. You can click these verbs to perform more complex actions on the control.
|Figure 4. Smart Tag: A smart tag lets you set key properties and invoke verbs in a popup.||
|Figure 5. Dialog-Based Property Settings: Property pages let you set properties in a custom dialog.||
- The property pages shown in Figure 5 let you set the control's key properties in a dialog. This figure shows two tabs (on the left) for setting the Basic and Map properties. Because the dialog can be quite large and can display many pages, it can show more properties than a smart tag popup can.
Part one of this two-part article explains the first few of these tools. It uses the StateSelector example (you can download the code
in both VB.NET and C#) to explain how to display LineStyle
samples, letting users pick LineStyles
from a dropdown; how to display custom values for properties, such as (none)
values displayed for the Map
property; and how to display a file selection dialog when a user clicks in the Properties dialog, such as the one the StateSelector displays when a user clicks the ellipsis beside the Map
property. Part two explains how to provide a dialog editor for the Selected
property, build smart tags and command verbs, and create property pages.