--- title: "ToolStrip Control Architecture" ms.date: "03/30/2017" helpviewer_keywords: - "ToolStrip control [Windows Forms], architecture" ms.assetid: 71df2d18-862e-4701-9ff9-c1fe606f94f2 --- # ToolStrip Control Architecture The and classes provide a flexible, extensible system for displaying toolbar, status, and menu items. These classes are all contained in the namespace and they are all typically named with the "ToolStrip" prefix (such as ) or with the "Strip" suffix (such as ). ## ToolStrip The following topics describe and the controls that derive from it. is the abstract base class for , , and . The following object model shows the inheritance hierarchy. ![Diagram that shows the ToolStrip object model.](./media/toolstrip-control-architecture/toolstrip-object-model.gif) You can access all the items in a through the collection. You can access all the items in a through the collection. In a class derived from , you can also use the 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 and in all orientations. They are available by default at design time for the control: - - - - - - - ### MenuStrip is the top-level container that supersedes . It also provides key handling and multiple document interface (MDI) features. Functionally, and work along with , although they are derived from . The following items are specifically designed to work seamlessly with both and in all orientations. They are available by default at design time for the control: - - - ### StatusStrip replaces the control. Special features of include a custom table layout, support for the form's sizing and moving grips, and the `Spring` property, which allows a to fill available space automatically. The following items are specifically designed to work seamlessly with both and in all orientations. They are available by default at design time for the control: - - - - ### ContextMenuStrip replaces . You can associate a with any control, and a right mouse click automatically displays the context menu (or shortcut menu). You can show a programmatically by using the method. supports cancelable and events to handle dynamic population and multiple-click scenarios. supports images, menu-item check state, text, access keys, shortcuts, and cascading menus. The following items are specifically designed to work seamlessly with both and in all orientations. They are available by default at design time for the control: - - - - ### ToolStrip Generic Features The following topics describe features and behavior that are generic to the and derived controls. #### Painting You can do custom painting in controls in several ways. As with other Windows Forms controls, the and 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 behave like other control paint events. The controls also provide finer access to the rendering of the items and container through the class, which has overridable methods for painting the background, item background, item image, item arrow, item text, and border of the . 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 . 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 . By default, the is double buffered, taking advantage of the setting. #### Parenting The concept of container ownership and parenting is more complex in controls than in other Windows Forms container controls. That is necessary to support dynamic scenarios such as overflow, sharing drop-down items across multiple items, and to support the generation of a from a control. The following list describes members related to parenting and explains their use. - accesses the item that is the source of the drop-down item. This is similar to , but instead of returning a control, it returns a . - determines which control is the source of the when multiple controls share the same . - is a read-only accessor to the property. A parent differs from an owner in that a parent denotes the returned current in which the item is displayed, which might be in the overflow area. - returns the whose Items collection contains the current . This is the best way to reference or other properties in the top-level without writing special code to handle overflow. #### Behavior of Inherited Controls The following controls are locked whenever they are used in inheritance: - - - - - that includes the panels in a and also individual 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 control supports limited inherited scenarios, similar to the following example: 1. Create a new Windows Forms application. 2. Add a to the form. 3. Set the access modifier of the to `public` or `protected`. 4. Add any combination of , , and controls to the regions of the . 5. Build the project. 6. Add a form that inherits from the first form. 7. Select the inherited 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 controls are locked; you cannot select or rearrange their contents. - You can add controls to the , move the controls, and make them child controls of the . - Your changes persist after building the form. > [!NOTE] > Remove the access modifiers from all controls that are part of a . The access modifier of the governs the whole control. #### Partial Trust The limitations of `ToolStrip`s 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 to display items in a . This applies to both intrinsic controls such as , , and as well as to user-created controls. If this requirement is not met, these items are not displayed. No exception is thrown. - Setting the property to `false` is not allowed, and the cancelable 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 . - Access keys are not processed when is not granted. #### Usage The following usage patterns have a bearing on layout, keyboard interaction, and end-user behavior: - Joined in a The can be repositioned within the and across s. The `Dock` property is ignored, and if the property is `false`, the size of the grows as items are added to the . Typically, the does not participate in the tab order. - Docked The 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 does not participate in the tab order. - Absolutely positioned The is like other controls, in that it is placed by the 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. 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 use a combination of the enumeration (which is not order-specific) to define the shortcut key. You can also use the property to display a shortcut key with text only, such as displaying "Del" instead of "Delete." ##### Navigation The ALT key activates the pointed to by . From there, CTRL+TAB navigates between controls within `ToolStripPanel`s. The TAB key and the arrow keys on the numeric keypad navigate between items in a . A special algorithm handles navigation in the overflow region. SPACEBAR selects a , , or . ##### Focus and Validation When activated by the ALT key, the or typically neither take nor remove the focus from the control that currently has the focus. If there is a control hosted within the or a drop-down of the , the control gains focus when the user presses the TAB key. In general, the , , , and events of might not be raised when they are activated by the keyboard. In such cases, use the and events instead. By default, is `false`. Call explicitly on your form to perform validation. #### Layout You control layout by choosing one of the members of with the property. ##### Stack Layouts Stacking is the arranging of items beside each other at both ends of the . The following list describes the stack layouts. - is the default. This setting causes the to alter its layout automatically in accordance with the property to handle dragging and docking scenarios. - renders the items beside each other vertically. - renders the items beside each other horizontally. ##### Other Features of Stack Layouts determines the end of the to which the item is aligned. When items do not fit within the , an overflow button automatically appears. The property setting determines whether an item appears in the overflow area always, as needed, or never. In the event, you can inspect the property to determine whether an item was placed on the main , the overflow , 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 and its property was set to . Make a movable by putting it in a and setting its to . ##### Other Layout Options The other layout options are and . ##### Flow Layout layout is the default for , , and . It is similar to the . The features of layout are as follows: - All of the features of are exposed by the property. You must cast the class to a class. - You can use the and properties in code to align the items within the row. - The property is ignored. - In the event, you can inspect the property to determine whether an item was placed on the main or did not fit. - The grip is not rendered, and therefore a in layout style in a cannot be moved. - The overflow button is not rendered, and is ignored. ##### Table Layout layout is the default for . It is similar to . The features of layout are as follows: - All of the features of are exposed by the property. You must cast the class to a class. - You can use the and properties in code to align the items within the table cell. - The property is ignored. - In the event, you can inspect the property to determine whether an item was placed on the main or did not fit. - The grip is not rendered, and therefore a in layout style in a cannot be moved. - The overflow button is not rendered, and is ignored. ## ToolStripItem The following topics describe and the controls that derive from it. is the abstract base class for all the items that go into a . The following object model shows the inheritance hierarchy. ![Diagram that shows the ToolStripItem object model.](./media/toolstrip-control-architecture/toolstripitem-object-model.gif) classes either inherit directly from , or they inherit indirectly from through or . controls must be contained in a , , , or and cannot be added directly to a form. The various container classes are designed to contain an appropriate subset of controls. The following table lists the stock controls and the containers in which they look best. Although any item can be hosted in any -derived container, these items were designed to look best in the following containers: > [!NOTE] > does not appear in the designer toolbox. |Contained item|ToolStrip|MenuStrip|ContextMenuStrip|StatusStrip|ToolStripDropDown| |--------------------|---------------|---------------|----------------------|-----------------|-----------------------| ||Yes|No|No|No|Yes| ||Yes|Yes|Yes|No|Yes| ||Yes|No|No|Yes|Yes| ||Yes|No|No|Yes|Yes| ||Yes|Yes|Yes|No|Yes| ||Yes|No|No|Yes|Yes| ||Yes|Yes|Yes|No|Yes| ||No|Yes|Yes|No|No| ||No|No|No|Yes|No| ||Yes|No|No|Yes|No| ||Yes|Yes|No|Yes|Yes| ### ToolStripButton is the button item for . 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 provides label functionality in controls. The is like a that does not get focus by default and that does not render as pushed or highlighted. as a hosted item supports access keys. Use the , , and properties on a to support link control in a . ### ToolStripStatusLabel is a version of designed specifically for use in . The special features include , , and . ### ToolStripSeparator The 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 at design time by choosing it from a drop-down list. However, you can also automatically create a by typing a hyphen (-) in either the designer template node or in the method. ### ToolStripControlHost is the abstract base class for , , and . can host other controls, including custom controls, in two ways: - Construct a with a class that derives from . To fully access the hosted control and properties, you must cast the property back to the actual class it represents. - Extend , and in the inherited class's parameterless constructor, call the base class constructor passing a class that derives from . This option lets you wrap common control methods and properties for easy access in a . ### ToolStripComboBox is the optimized for hosting in a . A subset of the hosted control's properties and events are exposed at the level, but the underlying control is fully accessible through the property. ### ToolStripTextBox is the optimized for hosting in a . A subset of the hosted control's properties and events are exposed at the level, but the underlying control is fully accessible through the property. ### ToolStripProgressBar is the optimized for hosting in a . A subset of the hosted control's properties and events are exposed at the level, but the underlying control is fully accessible through the property. ### ToolStripDropDownItem is the abstract base class for , , and , which can host items directly or host additional items in a drop-down container. You do this by setting the property to a and setting the property of the . Access these drop-down items directly through the property. ### ToolStripMenuItem is a that works with and to handle the special highlighting, layout, and column arrangement for menus. ### ToolStripDropDownButton looks like , but it shows a drop-down area when the user clicks it. Hide or show the drop-down arrow by setting the property. hosts a that displays items that overflow the . ### ToolStripSplitButton combines button and drop-down button functionality. Use the property to synchronize the event of the chosen drop-down item with the item shown on the button. ### ToolStripItem Generic Features provides the following generic features and options to inheriting controls: - Core events - Image handling - Alignment - Text and image relationship - Display style #### Core Events controls receive their own click, mouse, and paint events, and can perform some keyboard preprocessing also. #### Image Handling The , , , , and properties pertain to various aspects of image handling. Use images in controls by setting these properties directly or by setting the run-time–only property. Image scaling is determined by the interaction of properties in both and , as follows: - is the scale of the final image as determined by the combination of the image's setting and the container's setting. - If is `true` (the default) and is , no image scaling occurs, and the size is that of the largest item, or a prescribed minimum size. - If is `false` and is , neither image nor scaling occurs. #### Alignment The value of the property determines the end of the at which an item appears. The property works only when the layout style of the is set to one of the stack overflow values. Items are placed on the in the order in which the items appear in the Items collection. To programmatically change where an item is laid out, use the method to move the item in the collection. This method moves the item but does not duplicate it. #### Text and Image Relationship The property defines the relative placement of the image with respect to the text on a . Items that lack an image, text, or both are treated as special cases so that the does not display a blank spot for the missing element or elements. #### Display Style 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: - supports -related tasks for entire applications, such as merging, settings, and renderer options. - allows you to apply a particular style or theme to a easily. - creates pens and brushes based on a replaceable color table (). - applies system colors and a flat visual style to applications. - is similar to . It uses four docked side panels (instances of ) and one central panel (an instance of ) 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 , , or controls in the side panels, and you can use the central panel for other controls. The also provides a way to get renderer support into the body of your form for a consistent appearance. does not support multiple document interface (MDI). - provides space for moving and arranging controls. You can use only one panel if you so choose, and works well in MDI scenarios. ## See also - [ToolStrip Control Overview](toolstrip-control-overview-windows-forms.md) - [ToolStrip Technology Summary](toolstrip-technology-summary.md) - [ToolStrip Control](toolstrip-control-windows-forms.md) - [MenuStrip Control](menustrip-control-windows-forms.md) - [StatusStrip Control](statusstrip-control.md) - [ContextMenuStrip Control](contextmenustrip-control.md) - [BindingNavigator Control](bindingnavigator-control-windows-forms.md)