ToolStripManager Class

Definition

public ref class ToolStripManager sealed

public ref class ToolStripManager abstract sealed

public sealed class ToolStripManager

public static class ToolStripManager

type ToolStripManager = class

Public NotInheritable Class ToolStripManager

Public Class ToolStripManager

Inheritance

Object

ToolStripManager

Examples

The following code example demonstrates all the typical scenarios of menu item merging.

using System;
using System.Collections.Generic;
using System.ComponentModel;
using System.Data;
using System.Drawing;
using System.Text;
using System.Windows.Forms;

public enum MergeSample
{
 None,
 Append,
 InsertInSameLocation,
 InsertInSameLocationPreservingOrder,
 ReplacingItems,
 MatchOnly
}
public class Form1 : Form
{
 ContextMenuStrip cmsBase;
 ContextMenuStrip cmsItemsToMerge;

 public Form1()
 {
 InitializeComponent();

 components ??= new Container();
 cmsBase = new ContextMenuStrip(components);
 cmsItemsToMerge = new ContextMenuStrip(components);

 // cmsBase is the base ContextMenuStrip.
 cmsBase.Items.Add("one");
 cmsBase.Items.Add("two");
 cmsBase.Items.Add("three");
 cmsBase.Items.Add("four");

 // cmsItemsToMerge contains the items to merge.
 cmsItemsToMerge.Items.Add("one");
 cmsItemsToMerge.Items.Add("two");
 cmsItemsToMerge.Items.Add("three");
 cmsItemsToMerge.Items.Add("four");

 // Distinguish the merged items by setting the shortcut display string.
 foreach (ToolStripMenuItem tsmi in cmsItemsToMerge.Items)
 {
 tsmi.ShortcutKeyDisplayString = "Merged Item";
 }
 // Associate the ContextMenuStrip with the form so that it displays when
 // the user clicks the right mouse button.
 this.ContextMenuStrip = cmsBase;

 CreateCombo();
 }

 #region ComboBox switching code.
 private void CreateCombo()
 {
 // This ComboBox allows the user to switch between the samples.
 ComboBox sampleSelectorCombo = new ComboBox();
 sampleSelectorCombo.DataSource = Enum.GetValues(typeof(MergeSample));
 sampleSelectorCombo.SelectedIndexChanged += new EventHandler(comboBox_SelectedIndexChanged);
 sampleSelectorCombo.Dock = DockStyle.Top;
 this.Controls.Add(sampleSelectorCombo);

 TextBox textBox = new TextBox();
 textBox.Multiline = true;
 textBox.Dock = DockStyle.Left;
 textBox.DataBindings.Add("Text", this, "ScenarioText");
 textBox.ReadOnly = true;
 textBox.Width = 150;
 this.Controls.Add(textBox);
 this.BackColor = ProfessionalColors.MenuStripGradientBegin;
 this.Text = "Right click under selection.";
 }
 void comboBox_SelectedIndexChanged(object sender, EventArgs e)
 {
 ComboBox sampleSelectorCombo = sender as ComboBox;
 if (sampleSelectorCombo.SelectedValue != null)
 {
 CurrentSample = (MergeSample)sampleSelectorCombo.SelectedValue;
 }
 }

 private string scenarioText;

 public string ScenarioText
 {
 get { return scenarioText; }
 set
 {
 scenarioText = value;
 if (ScenarioTextChanged != null)
 {
 ScenarioTextChanged(this, EventArgs.Empty);
 }
 }
 }

 public event EventHandler ScenarioTextChanged;

 #endregion

 private void RebuildItemsToMerge()
 {
 // This handles cases where the items collection changes for the sample.
 cmsItemsToMerge.SuspendLayout();
 cmsItemsToMerge.Items.Clear();
 cmsItemsToMerge.Items.Add("one");
 cmsItemsToMerge.Items.Add("two");
 cmsItemsToMerge.Items.Add("three");
 cmsItemsToMerge.Items.Add("four");
 // Distinguish the merged items by setting the shortcut display string.
 foreach (ToolStripMenuItem tsmi in cmsItemsToMerge.Items)
 {
 tsmi.ShortcutKeyDisplayString = "Merged Item";
 }
 cmsItemsToMerge.ResumeLayout();
 }
 #region Switching current samples.
 private MergeSample currentSample = MergeSample.None;
 private MergeSample CurrentSample
 {
 get { return currentSample; }
 set
 {
 if (currentSample != value)
 {
 bool resetRequired = false;

 if (currentSample == MergeSample.MatchOnly)
 {
 resetRequired = true;
 }
 currentSample = value;
 // Undo previous merge, if any.
 ToolStripManager.RevertMerge(cmsBase, cmsItemsToMerge);
 if (resetRequired)
 {
 RebuildItemsToMerge();
 }

 switch (currentSample)
 {
 case MergeSample.None:
 return;
 case MergeSample.Append:
 ScenarioText = "This sample adds items to the end of the list using MergeAction.Append.\r\n\r\nThis is the default setting for MergeAction. A typical scenario is adding menu items to the end of the menu when some part of the program is activated.";
 ShowAppendSample();
 break;
 case MergeSample.InsertInSameLocation:
 ScenarioText = "This sample adds items to the middle of the list using MergeAction.Insert.\r\n\r\nNotice here how the items are added in reverse order: four, three, two, one. This is because they all have the same merge index.\r\n\r\nA typical scenario is adding menu items to the middle or beginning of the menu when some part of the program is activated. ";
 ShowInsertInSameLocationSample();
 break;
 case MergeSample.InsertInSameLocationPreservingOrder:
 ScenarioText = "This sample is the same as InsertInSameLocation, except the items are added in normal order by increasing the MergeIndex of \"two merged items\" to be 3, \"three merged items\" to be 5, and so on.\r\n You could also add the original items backwards to the source ContextMenuStrip.";
 ShowInsertInSameLocationPreservingOrderSample();
 break;
 case MergeSample.ReplacingItems:
 ScenarioText = "This sample replaces a menu item using MergeAction.Replace. Use this for the MDI scenario where saving does something completely different.\r\n\r\nMatching is based on the Text property. If there is no text match, merging reverts to MergeIndex.";
 ShowReplaceSample();
 break;
 case MergeSample.MatchOnly:
 ScenarioText = "This sample adds only the subitems from the child to the target ContextMenuStrip.";
 ShowMatchOnlySample();
 break;
 }
 // Reapply with the new settings.
 ToolStripManager.Merge(cmsItemsToMerge, cmsBase);
 }
 }
 }
 #endregion

 #region MergeSample.Append
 /* Example 1 - Add all items to the end of the list.
 * one
 * two
 * three
 * four
 * merge-one
 * merge-two
 * merge-three
 * merge-four
 */
 public void ShowAppendSample()
 {
 foreach (ToolStripItem item in cmsItemsToMerge.Items)
 {
 item.MergeAction = MergeAction.Append;
 }
 }
 #endregion

 #region MergeSample.InsertInSameLocation
 /* Example 2 - Place all in the same location.
 * one
 * two
 * merge-four
 * merge-three
 * merge-two
 * merge-one
 * three
 * four
 
 */
 public void ShowInsertInSameLocationSample()
 {
 // Notice how the items are in backward order. 
 // This is because "merge-one" gets applied, then a search occurs for the new second position 
 // for "merge-two", and so on.
 foreach (ToolStripItem item in cmsItemsToMerge.Items)
 {
 item.MergeAction = MergeAction.Insert;
 item.MergeIndex = 2;
 }
 }
 #endregion

 #region MergeSample.InsertInSameLocationPreservingOrder
 /* Example 3 - Insert items in the right order.
 * one
 * two
 * merge-one
 * merge-two
 * merge-three
 * merge-four
 * three
 * four 
 */
 public void ShowInsertInSameLocationPreservingOrderSample()
 {

 // Undo previous merges, if any.
 ToolStripManager.RevertMerge(cmsBase, cmsItemsToMerge);

 // This is the same as above, but increases the MergeIndex so that
 // subsequent items are placed afterwards.
 int i = 0;
 foreach (ToolStripItem item in cmsItemsToMerge.Items)
 {
 item.MergeAction = MergeAction.Insert;
 item.MergeIndex = 2 + i++;
 }

 // Reapply with new settings.
 ToolStripManager.Merge(cmsItemsToMerge, cmsBase);
 }
 #endregion

 #region MergeSample.ReplacingItems
 /* Example 4 - 
 * merge-one
 * merge-two
 * merge-three
 * merge-four
 */
 public void ShowReplaceSample()
 {

 // MergeAction.Replace compares Text property values. 
 // If matching text is not found, Replace reverts to MergeIndex. 

 foreach (ToolStripItem item in cmsItemsToMerge.Items)
 {
 item.MergeAction = MergeAction.Replace;
 }
 }
 #endregion

 #region MergeSample.MatchOnly
 /* Example 5 - Match to add subitems to a menu item.
 * Add items to the flyout menus for the original collection.
 * one -> subitem from "one merged item"
 * two -> subitem from "two merged items"
 * three -> subitem from "three merged items"
 * four -> subitem from "four merged items"
 */
 public void ShowMatchOnlySample()
 {

 foreach (ToolStripMenuItem item in cmsItemsToMerge.Items)
 {
 item.MergeAction = MergeAction.MatchOnly;
 item.DropDownItems.Add("subitem from \"" + item.Text + " " + item.ShortcutKeyDisplayString + "\"");
 }
 }
 #endregion

 private System.ComponentModel.IContainer components = null;
 protected override void Dispose(bool disposing)
 {
 if (disposing && (components != null))
 {
 components.Dispose();
 }
 base.Dispose(disposing);
 }

 private void InitializeComponent()
 {
 this.components = new System.ComponentModel.Container();
 this.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font;
 this.Text = "Form1";
 }
 [STAThread]
 static void Main()
 {
 Application.EnableVisualStyles();
 Application.SetCompatibleTextRenderingDefault(false);
 Application.Run(new Form1());
 }
}

Imports System.Collections.Generic
Imports System.ComponentModel
Imports System.Data
Imports System.Drawing
Imports System.Text
Imports System.Windows.Forms

Public Enum MergeSample
 None
 Append
 InsertInSameLocation
 InsertInSameLocationPreservingOrder
 ReplacingItems
 MatchOnly
End Enum

Public Class Form1
 Inherits Form
 Private cmsBase As ContextMenuStrip
 Private cmsItemsToMerge As ContextMenuStrip
 
 
 Public Sub New()
 InitializeComponent()
 
 If components Is Nothing Then
 components = New Container()
 End If
 cmsBase = New ContextMenuStrip(components)
 cmsItemsToMerge = New ContextMenuStrip(components)
 
 ' cmsBase is the base ContextMenuStrip.
 cmsBase.Items.Add("one")
 cmsBase.Items.Add("two")
 cmsBase.Items.Add("three")
 cmsBase.Items.Add("four")
 
 
 ' cmsItemsToMerge contains the items to merge.
 cmsItemsToMerge.Items.Add("one")
 cmsItemsToMerge.Items.Add("two")
 cmsItemsToMerge.Items.Add("three")
 cmsItemsToMerge.Items.Add("four")
 
 ' Distinguish the merged items by setting the shortcut display string.
 Dim tsmi As ToolStripMenuItem
 For Each tsmi In cmsItemsToMerge.Items
 tsmi.ShortcutKeyDisplayString = "Merged Item"
 Next tsmi
 ' Associate the ContextMenuStrip with the form so that it displays when
 ' the user clicks the right mouse button.
 Me.ContextMenuStrip = cmsBase
 
 CreateCombo()
 End Sub
 
 
 #Region "ComboBox switching code."
 
 Private Sub CreateCombo()
 ' This ComboBox allows the user to switch between the samples.
 Dim sampleSelectorCombo As New ComboBox()
 sampleSelectorCombo.DataSource = [Enum].GetValues(GetType(MergeSample))
 AddHandler sampleSelectorCombo.SelectedIndexChanged, AddressOf comboBox_SelectedIndexChanged
 sampleSelectorCombo.Dock = DockStyle.Top
 Me.Controls.Add(sampleSelectorCombo)
 Dim textBox As New TextBox()
 textBox.Multiline = True
 textBox.Dock = DockStyle.Left
 textBox.DataBindings.Add("Text", Me, "ScenarioText")
 textBox.ReadOnly = True
 textBox.Width = 150
 Me.Controls.Add(textBox)
 Me.BackColor = ProfessionalColors.MenuStripGradientBegin
 Me.Text = "Right click under selection."
 End Sub
 
 Private Sub comboBox_SelectedIndexChanged(sender As Object, e As EventArgs)
 Dim sampleSelectorCombo As ComboBox = sender 
 If Not (sampleSelectorCombo.SelectedValue Is Nothing) Then
 CurrentSample = CType(sampleSelectorCombo.SelectedValue, MergeSample)
 End If
 End Sub
 
 Private scenarioText1 As String
 
 
 Public Property ScenarioText() As String
 Get
 Return scenarioText1
 End Get
 Set
 scenarioText1 = value
 RaiseEvent ScenarioTextChanged(Me, EventArgs.Empty)
 End Set
 End Property
 
 Public Event ScenarioTextChanged As EventHandler
 
 #End Region
 
 
 Private Sub RebuildItemsToMerge()
 ' This handles cases where the items collection changes for the sample.
 cmsItemsToMerge.SuspendLayout()
 cmsItemsToMerge.Items.Clear()
 cmsItemsToMerge.Items.Add("one")
 cmsItemsToMerge.Items.Add("two")
 cmsItemsToMerge.Items.Add("three")
 cmsItemsToMerge.Items.Add("four")
 ' Distinguish the merged items by setting the shortcut display string.
 Dim tsmi As ToolStripMenuItem
 For Each tsmi In cmsItemsToMerge.Items
 tsmi.ShortcutKeyDisplayString = "Merged Item"
 Next tsmi
 cmsItemsToMerge.ResumeLayout()
 End Sub
 #Region "Switching current samples."
 Private currentSample1 As MergeSample = MergeSample.None
 
 Private Property CurrentSample() As MergeSample
 Get
 Return currentSample1
 End Get
 Set
 If currentSample1 <> value Then
 Dim resetRequired As Boolean = False
 
 If currentSample1 = MergeSample.MatchOnly Then
 resetRequired = True
 End If
 currentSample1 = value
 ' Undo previous merge, if any.
 ToolStripManager.RevertMerge(cmsBase, cmsItemsToMerge)
 If resetRequired Then
 RebuildItemsToMerge()
 End If
 
 Select Case currentSample1
 Case MergeSample.None
 Return
 Case MergeSample.Append
 ScenarioText = "This sample adds items to the end of the list using MergeAction.Append." + ControlChars.Cr + ControlChars.Lf + ControlChars.Cr + ControlChars.Lf + "This is the default setting for MergeAction. A typical scenario is adding menu items to the end of the menu when some part of the program is activated."
 ShowAppendSample()
 Case MergeSample.InsertInSameLocation
 ScenarioText = "This sample adds items to the middle of the list using MergeAction.Insert." + ControlChars.Cr + ControlChars.Lf + ControlChars.Cr + ControlChars.Lf + "Notice here how the items are added in reverse order: four, three, two, one. This is because they all have the same merge index." + ControlChars.Cr + ControlChars.Lf + ControlChars.Cr + ControlChars.Lf + "A typical scenario is adding menu items to the middle or beginning of the menu when some part of the program is activated. "
 ShowInsertInSameLocationSample()
 Case MergeSample.InsertInSameLocationPreservingOrder
 ScenarioText = "This sample is the same as InsertInSameLocation, except the items are added in normal order by increasing the MergeIndex of ""two merged items"" to be 3, ""three merged items"" to be 5, and so on." + ControlChars.Cr + ControlChars.Lf + " You could also add the original items backwards to the source ContextMenuStrip."
 ShowInsertInSameLocationPreservingOrderSample()
 Case MergeSample.ReplacingItems
 ScenarioText = "This sample replaces a menu item using MergeAction.Replace. Use this for the MDI scenario where saving does something completely different." + ControlChars.Cr + ControlChars.Lf + ControlChars.Cr + ControlChars.Lf + "Matching is based on the Text property. If there is no text match, merging reverts to MergeIndex."
 ShowReplaceSample()
 Case MergeSample.MatchOnly
 ScenarioText = "This sample adds only the subitems from the child to the target ContextMenuStrip."
 ShowMatchOnlySample()
 End Select
 
 ' Reapply with the new settings.
 ToolStripManager.Merge(cmsItemsToMerge, cmsBase)
 End If
 End Set
 End Property
 #End Region
 
 #Region "MergeSample.Append"
 
 ' Example 1 - Add all items to the end of the list.
' * one
' * two
' * three
' * four
' * merge-one
' * merge-two
' * merge-three
' * merge-four
' 
 Public Sub ShowAppendSample()
 Dim item As ToolStripItem
 For Each item In cmsItemsToMerge.Items
 item.MergeAction = MergeAction.Append
 Next item
 End Sub
 #End Region
 
 #Region "MergeSample.InsertInSameLocation"
 
 ' Example 2 - Place all in the same location.
' * one
' * two
' * merge-four
' * merge-three
' * merge-two
' * merge-one
' * three
' * four
' 
' 
 Public Sub ShowInsertInSameLocationSample()
 ' Notice how the items are in backward order. 
 ' This is because "merge-one" gets applied, then a search occurs for the new second position 
 ' for "merge-two", and so on.
 Dim item As ToolStripItem
 For Each item In cmsItemsToMerge.Items
 item.MergeAction = MergeAction.Insert
 item.MergeIndex = 2
 Next item
 End Sub
 #End Region
 
 #Region "MergeSample.InsertInSameLocationPreservingOrder"
 
 ' Example 3 - Insert items in the right order.
' * one
' * two
' * merge-one
' * merge-two
' * merge-three
' * merge-four
' * three
' * four 
' 
 Public Sub ShowInsertInSameLocationPreservingOrderSample()
 
 ' Undo previous merges, if any.
 ToolStripManager.RevertMerge(cmsBase, cmsItemsToMerge)
 
 ' This is the same as above, but increases the MergeIndex so that
 ' subsequent items are placed afterwards.
 Dim i As Integer = 0
 Dim item As ToolStripItem
 For Each item In cmsItemsToMerge.Items
 item.MergeAction = MergeAction.Insert
 item.MergeIndex = 2 + i
 Next item
 
 ' Reapply with new settings.
 ToolStripManager.Merge(cmsItemsToMerge, cmsBase)
 End Sub
 #End Region
 
 #Region "MergeSample.ReplacingItems"
 
 ' Example 4 - 
' * merge-one
' * merge-two
' * merge-three
' * merge-four
' 
 Public Sub ShowReplaceSample()
 
 ' MergeAction.Replace compares Text property values. 
 ' If matching text is not found, Replace reverts to MergeIndex. 
 Dim item As ToolStripItem
 For Each item In cmsItemsToMerge.Items
 item.MergeAction = MergeAction.Replace
 Next item
 End Sub
 
 
 #End Region
 
 #Region "MergeSample.MatchOnly"
 
 ' Example 5 - Match to add subitems to a menu item.
' * Add items to the flyout menus for the original collection.
' * one -> subitem from "one merged item"
' * two -> subitem from "two merged items"
' * three -> subitem from "three merged items"
' * four -> subitem from "four merged items"
' 
 Public Sub ShowMatchOnlySample()
 
 Dim item As ToolStripMenuItem
 For Each item In cmsItemsToMerge.Items
 item.MergeAction = MergeAction.MatchOnly
 item.DropDownItems.Add(("subitem from """ + item.Text + " " + item.ShortcutKeyDisplayString + """"))
 Next item
 End Sub
 
 #End Region
 
 Private components As System.ComponentModel.IContainer = Nothing
 
 Protected Overrides Sub Dispose(disposing As Boolean)
 If disposing AndAlso Not (components Is Nothing) Then
 components.Dispose()
 End If
 MyBase.Dispose(disposing)
 End Sub
 
 
 Private Sub InitializeComponent()
 Me.components = New System.ComponentModel.Container()
 Me.AutoScaleMode = System.Windows.Forms.AutoScaleMode.Font
 Me.Text = "Form1"
 End Sub
 
 <STAThread()> _
 Shared Sub Main()
 Application.EnableVisualStyles()
 Application.SetCompatibleTextRenderingDefault(False)
 Application.Run(New Form1())
 End Sub
End Class

The following code example demonstrates a call to ToolStripManager and some of its members.

toolStrip1->RenderMode = 
 ToolStripRenderMode::ManagerRenderMode;
ToolStripManager::Renderer = gcnew RedTextRenderer;

toolStrip1.RenderMode = ToolStripRenderMode.ManagerRenderMode;
ToolStripManager.Renderer = new RedTextRenderer();

toolStrip1.RenderMode = ToolStripRenderMode.ManagerRenderMode
ToolStripManager.Renderer = New RedTextRenderer()

Remarks

ToolStripManager supports ToolStrip-related tasks for entire applications, such as merging, settings, and renderer options. The overloaded Merge method combines ToolStrip controls with each other, and the overloaded RevertMerge method undoes a merge operation.

Use the ToolStripRenderer class with the ToolStripManager class to gain even more control and customizability over painting and layout style.

See also

• ToolStripRenderer
• ToolStripProfessionalRenderer
• ToolStripContainer
• MergeAction
• MergeIndex
• MergeAction
• AllowMerge
• How to: Customize Colors in ToolStrip Applications
• How to: Set the ToolStrip Renderer at Run Time
• How to: Set the ToolStrip Renderer for an Application