Designer Commands and the DesignerAction Object Model for Windows Forms
Caution
This content was written for .NET Framework. If you're using .NET 6 or a later version, use this content with caution. The designer system has changed for Windows Forms and it's important that you review the Designer changes since .NET Framework article.
Designer commands and the DesignerAction object model provide a generalized way for you to specify a set of actions for a component at design time. Users then access these actions from the design surface, typically by clicking on a component's smart-tag glyph (.gif "Smart Tag Glyph")
) and selecting one of the offered actions from the smart-tag panel. This model unifies the various ways a designer can offer commands to users.
Smart Tags
The smart-tag feature enables components and controls to display context-sensitive information and commands to users. The smart tag can be thought of as a replacement for designer verbs, because you can choose to display a smart tag item in the smart-tag panel and also in the shortcut menu associated with a component or control.
For a full example of how you can implement smart tags, see How to: Attach Smart Tags to a Windows Forms Component.
Designer Command Classes
The following table describes the ways designer commands are exposed to you when you are developing components and controls.
Class |
Description |
|---|---|
A delegate attached to a command ID. It does not define the command text, its placement, or other metadata. |
|
A menu command that also defines its text and other metadata. Verbs are generally offered on a per-designer basis and are specific to the designer. Designer verbs are generally shown on a shortcut menu or on the View menu of the main menu bar. |
|
A menu command that defines text and other metadata to describe a targeted action that can be performed. Actions typically walk the user through some multi-step process, such as configuring a data source for a component. |
Push and Pull Models
The following table shows the two models for programmatically accessing designer commands.
Model |
Description |
|---|---|
Push |
A designer specifically requests a service and adds commands to that service. |
Pull |
A designer is queried by a service for commands that it offers. |
Unifying Existing Commands
There is much in common among the kinds of commands listed in the previous table of designer command classes. The DesignerAction API brings these together to present a uniform model for exposing commands to users of a designer.
Note
Not all designers support all models. A designer can query what kinds of support are offered, and in response it may change how it offers commands. In addition, both push and pull models may not be supported for all kinds of commands. Not all designers will expose designer actions as smart tags. For example, some designers may expose designer actions in a tool window.
DesignerAction Object Model
The following table describes the important classes that implement the DesignerAction object model.
Class |
Description |
|---|---|
Represents a panel item on a smart-tag panel. |
|
Defines a list of items used to create a smart-tag panel. |
|
Establishes a design-time service that manages the collection of DesignerActionItem objects for components. |
|
Represents a static text item on a panel. Derives from DesignerActionItem. |
|
Represents a panel item that is associated with a property in a class derived from DesignerActionList. Derives from DesignerActionItem. |
|
Represents a panel item that is associated with a method in a class derived from DesignerActionList. Derives from DesignerActionItem. |
|
Represents a static header item on a smart-tag panel. Derives from DesignerActionTextItem. |
Using the DesignerAction Object Model
To enable designer actions for your component or control, derive from the DesignerActionList base class. Use this derived class to populate a smart-tag panel, which represents the menu-like UI.
Your derived class may override the virtualGetSortedActionItems method to return a collection of objects derived from DesignerActionItem. These objects represent the panel items. Each item is displayed in the panel according to its type. For example, a DesignerActionTextItem is displayed as a static text label. Active panel items, represented by the DesignerActionPropertyItem and DesignerActionMethodItem types, have a corresponding publicly accessible property or method, respectively, that implements the functionality for that item.
Once your derived class is created, you can add it to a control in two ways:
With the pull model, you add an instance of your derived class to the ActionLists property on the ComponentDesigner class. This provides a way for inheriting classes to provide other action lists and for their items to be merged.
With the push model, you call Add to add an instance of your derived class to the collection maintained by the global DesignerActionService. These action lists will be merged with those in the collection maintained by ComponentDesigner.
A DesignerActionPropertyItem is represented in the designer by its corresponding UITypeEditor. A DesignerActionMethodItem is represented in the designer by an active UI element, such as a hyperlink, that invokes a programmer-supplied method. Your action list's implementation of the GetSortedActionItems method returns the properties and methods in the order they should be displayed in the smart-tag panel.
For a full example of implementing smart tags, see the topic How to: Attach Smart Tags to a Windows Forms Component.
Existing Verbs in Action Lists
Controls and components with existing DesignerVerb implementations automatically receive DesignerActionList support. The design environment queries a component’s designer for an action list, and if none is available, one is created for existing verbs.
Action List Items in the Shortcut Menu
If you want an item to appear in both the shortcut menu and an action list, you can specify the IncludeAsDesignerVerb flag on DesignerActionMethodItem.
When Add is called, the action list is scanned for any DesignerActionMethodItem with the IncludeAsDesignerVerb flag set. If it is set, the AddVerb method will be called for that item to add that to the component’s verbs and hence, its shortcut menu.
Changes to Designer Command Types
The MenuCommand and DesignerVerb classes from the .NET Framework version 1.1 have been slightly changed to support the DesignerAction object model. Both types now expose a new property called Properties, which is an IDictionary that stores all the public properties for the command object. The dictionary key is the name of the public property. This enables generic enumeration of properties and provides a consistent base from which new properties can be added without modifying the class definition.
In addition, the MenuCommandService class provides a standard implementation of the IMenuCommandService and performs the correct verb integration. This class raises events notifying of additions and removals to commands. With this class you can create a UI based on the results of these events. MenuCommandService, as well as IMenuCommandService, are available in the service container.
See Also
Tasks
How to: Attach Smart Tags to a Windows Forms Component