ToolStrip Control Architecture

Artigo
04/23/2007

The ToolStrip and ToolStripItem classes provide a flexible, extensible system for displaying toolbar, status, and menu items. These classes are all contained in the System.Windows.Forms namespace and they are all typically named with the "ToolStrip" prefix (such as ToolStripOverflow) or with the "Strip" suffix (such as MenuStrip).

ToolStrip

The following topics describe ToolStrip and the controls that derive from it.

ToolStrip is the abstract base class for MenuStrip, StatusStrip, and ContextMenuStrip. The following object model shows the ToolStrip inheritance hierarchy.

ToolStrip object model

ToolStrip Object Model

You can access all the items in a ToolStrip through the Items collection. You can access all the items in a ToolStripDropDownItem through the DropDownItems collection. In a class derived from ToolStrip, you can also use the DisplayedItems property to access only those items that are currently displayed. These are the items that are not currently in an overflow menu.

The following items are specifically designed to work seamlessly with both ToolStripSystemRenderer and ToolStripProfessionalRenderer in all orientations. They are available by default at design time for the ToolStrip control:

MenuStrip

MenuStrip is the top-level container that supersedes MainMenu. It also provides key handling and multiple document interface (MDI) features. Functionally, ToolStripDropDownItem and ToolStripMenuItem work along with MenuStrip, although they are derived from ToolStripItem.

The following items are specifically designed to work seamlessly with both ToolStripSystemRenderer and ToolStripProfessionalRenderer in all orientations. They are available by default at design time for the MenuStrip control:

ToolStripMenuItem
ToolStripTextBox
ToolStripComboBox

StatusStrip

StatusStrip replaces the StatusBar control. Special features of StatusStrip include a custom table layout, support for the form's sizing and moving grips, and the Spring property, which allows a ToolStripStatusLabel to fill available space automatically.

ToolStripStatusLabel
ToolStripDropDownButton
ToolStripSplitButton
ToolStripProgressBar

ContextMenuStrip

ContextMenuStrip replaces ContextMenu. You can associate a ContextMenuStrip with any control, and a right mouse click automatically displays the context menu (or shortcut menu). You can show a ContextMenuStrip programmatically by using the Show method. ContextMenuStrip supports cancelable Opening and Closing events to handle dynamic population and multiple-click scenarios. ContextMenuStrip supports images, menu-item check state, text, access keys, shortcuts, and cascading menus.

ToolStripMenuItem
ToolStripSeparator
ToolStripTextBox
ToolStripComboBox

ToolStrip Generic Features

The following topics describe features and behavior that are generic to the ToolStrip and derived controls.

Painting

You can do custom painting in ToolStrip controls in several ways. As with other Windows Forms controls, the ToolStrip and ToolStripItem both have overridable OnPaint methods and Paint events. As with regular painting, the coordinate system is relative to the client area of the control; that is, the upper left-hand corner of the control is 0, 0. The Paint event and OnPaint method for a ToolStripItem behave like other control paint events.

The ToolStrip controls also provide finer access to the rendering of the items and container through the ToolStripRenderer class, which has overridable methods for painting the background, item background, item image, item arrow, item text, and border of the ToolStrip. The event arguments for these methods expose several properties such as rectangles, colors, and text formats that you can adjust as desired.

To adjust just a few aspects of how an item is painted, you typically override the ToolStripRenderer.

If you are writing a new item and want to control all aspects of the painting, override the OnPaint method. From within OnPaint, you can use methods from the ToolStripRenderer.

By default, the ToolStrip is double buffered, taking advantage of the OptimizedDoubleBuffer setting.

Parenting

The concept of container ownership and parenting is more complex in ToolStrip controls than in other Windows Forms container controls. That is necessary to support dynamic scenarios such as overflow, sharing drop-down items across multiple ToolStrip items, and to support the generation of a ContextMenuStrip from a control.

The following list describes members related to parenting and explains their use.

OwnerItem accesses the item that is the source of the drop-down item. This is similar to SourceControl, but instead of returning a control, it returns a ToolStripItem.
SourceControl determines which control is the source of the ContextMenuStrip when multiple controls share the same ContextMenuStrip.
GetCurrentParent is a read-only accessor to the Parent property. A parent differs from an owner in that a parent denotes the returned current ToolStrip in which the item is displayed, which might be in the overflow area.
Owner returns the ToolStrip whose Items collection contains the current ToolStripItem. This is the best way to reference ImageList or other properties in the top-level ToolStrip without writing special code to handle overflow.

Behavior of Inherited Controls

The following controls are locked whenever they are used in inheritance:

ToolStrip
MenuStrip
ContextMenuStrip
StatusStrip
ToolStripPanel that includes the panels in a ToolStripContainer and also individual ToolStripPanel controls.

For example, create a new Windows Forms application by using one or more of the controls in the previous list. Set the access modifier of one or more controls to public or protected, and then build the project. Add a form that inherits from the first form, and then select an inherited control. The control appears locked, behaving as if its access modifier was private.

ToolStripContainer Support of Inheritance

The ToolStripContainer control supports limited inherited scenarios, similar to the following example:

Create a new Windows Forms application.
Add a ToolStripContainer to the form.
Set the access modifier of the ToolStripContainer to public or protected.
Add any combination of ToolStrip, MenuStrip, and ContextMenuStrip controls to the ToolStripPanel regions of the ToolStripContainer.
Build the project.
Add a form that inherits from the first form.
Select the inherited ToolStripContainer on the form.

Inherited Behavior of Child Controls

After you complete the previous steps, the following inherited behavior occurs:

In the designer, the control appears with an inherited icon.
The ToolStripPanel controls are locked; you cannot select or rearrange their contents.
You can add controls to the ToolStripContentPanel, move the controls, and make them child controls of the ToolStripContentPanel.
Your changes persist after building the form.

Note

Remove the access modifiers from all ToolStripPanel controls that are part of a ToolStripContainer. The access modifier of the ToolStripContainer governs the whole control.

Note
Remove the access modifiers from all ToolStripPanel controls that are part of a ToolStripContainer. The access modifier of the ToolStripContainer governs the whole control.

Partial Trust

The limitations of ToolStrips under partial trust are designed to prevent inadvertent entry of personal information that might be used by unauthorized persons or services. The protective measures are as follows:

ToolStripDropDown controls require AllWindows to display items in a ToolStripControlHost. This applies to both intrinsic controls such as ToolStripTextBox, ToolStripComboBox, and ToolStripProgressBar as well as to user-created controls. If this requirement is not met, these items are not displayed. No exception is thrown.
Setting the AutoClose property to false is not allowed, and the cancelable Closing event parameter is ignored. This makes it impossible to enter more than one keystroke without dismissing the drop-down item. If this requirement is not met, such items are not displayed. No exception is thrown.
Many keystroke handling events will not be raised if they occur in partial trust contexts other than AllWindows.
Access keys are not processed when AllWindows is not granted.

Usage

The following usage patterns have a bearing on ToolStrip layout, keyboard interaction, and end-user behavior:

Joined in a ToolStripPanel

The ToolStrip can be repositioned within the ToolStripPanel and across ToolStripPanels. The Dock property is ignored, and if the Stretch property is false, the size of the ToolStrip grows as items are added to the ToolStripPanel. Typically, the ToolStrip does not participate in the tab order.
Docked

The ToolStrip is placed on one side of a container in a fixed position, and its size expands over the entire edge to which it is docked. Typically, the ToolStrip does not participate in the tab order.
Absolutely positioned

The ToolStrip is like other controls, in that it is placed by the Location property, has a fixed size, and typically participates in the tab order.

Keyboard Interaction

Access Keys

Combined with or following the ALT key, access keys are one way to activate a control using the keyboard. ToolStrip supports both explicit and implicit access keys. Explicit definition uses an ampersand (&) character preceding the letter. Implicit definition uses an algorithm that attempts to find a matching item based on the order of characters in a given Text property.

Shortcut Keys

The shortcut keys used by a MenuStrip use a combination of the Keys enumeration (which is not order-specific) to define the shortcut key. You can also use the ShortcutKeyDisplayString property to display a shortcut key with text only, such as displaying "Del" instead of "Delete."

The ALT key activates the MenuStrip pointed to by MainMenuStrip. From there, CTRL+TAB navigates between ToolStrip controls within ToolStripPanels. The TAB key and the arrow keys on the numeric keypad navigate between items in a ToolStrip. A special algorithm handles navigation in the overflow region. SPACEBAR selects a ToolStripButton, ToolStripDropDownButton, or ToolStripSplitButton.

Focus and Validation

When activated by the ALT key, the MenuStrip or ToolStrip typically neither take nor remove the focus from the control that currently has the focus. If there is a control hosted within the MenuStrip or a drop-down of the MenuStrip, the control gains focus when the user presses the TAB key. In general, the GotFocus, LostFocus, Enter, and Leave events of MenuStrip might not be raised when they are activated by the keyboard. In such cases, use the MenuActivate and MenuDeactivate events instead.

By default, CausesValidation is false. Call Validate explicitly on your form to perform validation.

Layout

You control ToolStrip layout by choosing one of the members of ToolStripLayoutStyle with the LayoutStyle property.

Stack Layouts

Stacking is the arranging of items beside each other at both ends of the ToolStrip. The following list describes the stack layouts.

StackWithOverflow is the default. This setting causes the ToolStrip to alter its layout automatically in accordance with the Orientation property to handle dragging and docking scenarios.
VerticalStackWithOverflow renders the ToolStrip items beside each other vertically.
HorizontalStackWithOverflow renders the ToolStrip items beside each other horizontally.

Other Features of Stack Layouts

Alignment determines the end of the ToolStrip to which the item is aligned.

When items do not fit within the ToolStrip, an overflow button automatically appears. The Overflow property setting determines whether an item appears in the overflow area always, as needed, or never.

In the LayoutCompleted event, you can inspect the Placement property to determine whether an item was placed on the main ToolStrip, the overflow ToolStrip, or if it is not currently showing at all. The typical reasons why an item is not displayed are that the item did not fit on the main ToolStrip and its Overflow property was set to Never.

Make a ToolStrip movable by putting it in a ToolStripPanel and setting its GripStyle to Visible.

Other Layout Options

The other layout options are Flow and Table.

Flow Layout

Flow layout is the default for ContextMenuStrip, ToolStripDropDownMenu, and ToolStripOverflow. It is similar to the FlowLayoutPanel. The features of Flow layout are as follows:

All of the features of FlowLayoutPanel are exposed by the LayoutSettings property. You must cast the LayoutSettings class to a FlowLayoutSettings class.
You can use the Dock and Anchor properties in code to align the items within the row.
The Alignment property is ignored.
In the LayoutCompleted event, you can inspect the Placement property to determine whether an item was placed on the main ToolStrip or did not fit.
The grip is not rendered, and therefore a ToolStrip in Flow layout style in a ToolStripPanel cannot be moved.
The ToolStrip overflow button is not rendered, and Overflow is ignored.

Table Layout

Table layout is the default for StatusStrip. It is similar to TableLayoutPanel. The features of Flow layout are as follows:

All of the features of TableLayoutPanel are exposed by the LayoutSettings property. You must cast the LayoutSettings class to a TableLayoutSettings class.
You can use the Dock and Anchor properties in code to align the items within the table cell.
The Alignment property is ignored.
In the LayoutCompleted event, you can inspect the Placement property to determine whether an item was placed on the main ToolStrip or did not fit.
The grip is not rendered, and therefore a ToolStrip in Table layout style in a ToolStripPanel cannot be moved.
The ToolStrip overflow button is not rendered, and Overflow is ignored.

ToolStripItem

The following topics describe ToolStripItem and the controls that derive from it.

ToolStripItem is the abstract base class for all the items that go into a ToolStrip. The following object model shows the ToolStripItem inheritance hierarchy.

ToolStripItem object model

ToolStripItem Object Model

ToolStripItem classes either inherit directly from ToolStripItem, or they inherit indirectly from ToolStripItem through ToolStripControlHost or ToolStripDropDownItem.

ToolStripItem controls must be contained in a ToolStrip, MenuStrip, StatusStrip, or ContextMenuStrip and cannot be added directly to a form. The various container classes are designed to contain an appropriate subset of ToolStripItem controls.

The following table lists the stock ToolStripItem controls and the containers in which they look best. Although any ToolStrip item can be hosted in any ToolStrip-derived container, these items were designed to look best in the following containers:

Note
ToolStripDropDown does not appear in the designer toolbox.

Contained item	ToolStrip	MenuStrip	ContextMenuStrip	StatusStrip	ToolStripDropDown
ToolStripButton	Yes	No	No	No	Yes
ToolStripComboBox	Yes	Yes	Yes	No	Yes
ToolStripSplitButton	Yes	No	No	Yes	Yes
ToolStripLabel	Yes	No	No	Yes	Yes
ToolStripSeparator	Yes	Yes	Yes	No	Yes
ToolStripDropDownButton	Yes	No	No	Yes	Yes
ToolStripTextBox	Yes	Yes	Yes	No	Yes
ToolStripMenuItem	No	Yes	Yes	No	No
ToolStripStatusLabel	No	No	No	Yes	No
ToolStripProgressBar	Yes	No	No	Yes	No
ToolStripControlHost	Yes	Yes	No	Yes	Yes

ToolStripButton

ToolStripButton is the button item for ToolStrip. You can display it with various border styles, and you can use it to represent and activate operational states. You can also define it to have the focus by default.

ToolStripLabel

The ToolStripLabel provides label functionality in ToolStrip controls. The ToolStripLabel is like a ToolStripButton that does not get focus by default and that does not render as pushed or highlighted.

ToolStripLabel as a hosted item supports access keys.

Use the LinkColor, LinkVisited, and LinkBehavior properties on a ToolStripLabel to support link control in a ToolStrip.

ToolStripStatusLabel

ToolStripStatusLabel is a version of ToolStripLabel designed specifically for use in StatusStrip. The special features include BorderStyle, BorderSides, and Spring.

ToolStripSeparator

The ToolStripSeparator adds a vertical or horizontal line to a toolbar or menu, depending on the orientation. It provides grouping of or distinction between items, such as those on a menu.

You can add a ToolStripSeparator at design time by choosing it from a drop-down list. However, you can also automatically create a ToolStripSeparator by typing a hyphen (-) in either the designer template node or in the Add method.

ToolStripControlHost

ToolStripControlHost is the abstract base class for ToolStripComboBox, ToolStripTextBox, and ToolStripProgressBar. ToolStripControlHost can host other controls, including custom controls, in two ways:

Construct a ToolStripControlHost with a class that derives from Control. To fully access the hosted control and properties, you must cast the Control property back to the actual class it represents.
Extend ToolStripControlHost, and in the inherited class's default constructor, call the base class constructor passing a class that derives from Control. This option lets you wrap common control methods and properties for easy access in a ToolStrip.

ToolStripComboBox

ToolStripComboBox is the ComboBox optimized for hosting in a ToolStrip. A subset of the hosted control's properties and events are exposed at the ToolStripComboBox level, but the underlying ComboBox control is fully accessible through the ComboBox property.

ToolStripTextBox

ToolStripTextBox is the TextBox optimized for hosting in a ToolStrip. A subset of the hosted control's properties and events are exposed at the ToolStripTextBox level, but the underlying TextBox control is fully accessible through the TextBox property.

ToolStripProgressBar

ToolStripProgressBar is the ProgressBar optimized for hosting in a ToolStrip. A subset of the hosted control's properties and events are exposed at the ToolStripProgressBar level, but the underlying ProgressBar control is fully accessible through the ProgressBar property.

ToolStripDropDownItem

ToolStripDropDownItem is the abstract base class for ToolStripMenuItem, ToolStripDropDownButton, and ToolStripSplitButton, which can host items directly or host additional items in a drop-down container. You do this by setting the DropDown property to a ToolStripDropDown and setting the Items property of the ToolStripDropDown. Access these drop-down items directly through the DropDownItems property.

ToolStripMenuItem

ToolStripMenuItem is a ToolStripDropDownItem that works with ToolStripDropDownMenu and ContextMenuStrip to handle the special highlighting, layout, and column arrangement for menus.

ToolStripDropDownButton

ToolStripDropDownButton looks like ToolStripButton, but it shows a drop-down area when the user clicks it. Hide or show the drop-down arrow by setting the ShowDropDownArrow property. ToolStripDropDownButton hosts a ToolStripOverflowButton that displays items that overflow the ToolStrip.

ToolStripSplitButton

ToolStripSplitButton combines button and drop-down button functionality.

Use the DefaultItem property to synchronize the Click event of the chosen drop-down item with the item shown on the button.

ToolStripItem Generic Features

ToolStripItem provides the following generic features and options to inheriting controls:

Core events
Image handling
Alignment
Text and image relationship
Display style

Core Events

ToolStripItem controls receive their own click, mouse, and paint events, and can perform some keyboard preprocessing also.

Image Handling

The Image, ImageAlign, ImageIndex, ImageKey, and ImageScaling properties pertain to various aspects of image handling. Use images in ToolStrip controls by setting these properties directly or by setting the run-time–only ImageList property.

Image scaling is determined by the interaction of properties in both ToolStrip and ToolStripItem, as follows:

ImageScalingSize is the scale of the final image as determined by the combination of the image's ImageScaling setting and the container's AutoSize setting.
- If AutoSize is true (the default) and ToolStripItemImageScaling is SizeToFit, no image scaling occurs, and the ToolStrip size is that of the largest item, or a prescribed minimum size.
- If AutoSize is false and ToolStripItemImageScaling is None, neither image nor ToolStrip scaling occurs.

Alignment

The value of the Alignment property determines the end of the ToolStrip at which an item appears. The Alignment property works only when the layout style of the ToolStrip is set to one of the stack overflow values.

Items are placed on the ToolStrip in the order in which the items appear in the Items collection. To programmatically change where an item is laid out, use the Insert method to move the item in the collection. This method moves the item but does not duplicate it.

Text and Image Relationship

The TextImageRelation property defines the relative placement of the image with respect to the text on a ToolStripItem. Items that lack an image, text, or both are treated as special cases so that the ToolStripItem does not display a blank spot for the missing element or elements.

Display Style

DisplayStyle allows you to set the values of an item's Text and Image properties while displaying only what you want. This is typically used to change only the display style when showing the same item in a different context.

Accessory Classes

Classes that provide various other functionality include:

ToolStripManager supports ToolStrip-related tasks for entire applications, such as merging, settings, and renderer options.
ToolStripRenderer allows you to apply a particular style or theme to a ToolStrip easily.
ToolStripProfessionalRenderer creates pens and brushes based on a replaceable color table (ProfessionalColorTable).
ToolStripSystemRenderer applies system colors and a flat visual style to ToolStrip applications.
ToolStripContainer is similar to SplitContainer. It uses four docked side panels (instances of ToolStripPanel) and one central panel (an instance of ToolStripContentPanel) to create a typical arrangement. You cannot remove the side panels, but you can hide them. You can neither remove nor hide the central panel. You can arrange one or more ToolStrip, MenuStrip, or StatusStrip controls in the side panels, and you can use the central panel for other controls. The ToolStripContentPanel also provides a way to get renderer support into the body of your form for a consistent appearance. ToolStripContainer does not support multiple document interface (MDI).
ToolStripPanel provides space for moving and arranging ToolStrip controls. You can use only one panel if you so choose, and ToolStripPanel works well in MDI scenarios.

Compartilhar via