Windows Forms Documentation Updates : ToolStrip Control

How to Get a ToolStripItem from a Context Menu Click (Right-Click) with ContextMenuStrip

Jay A. Allen — Tue, 20 Jun 2006 22:47:00 GMT

I wanted to display a hierarchical menu for my blog feed reader application. No nesting of categories - just a simple, one-level list with one category at the top and a list of feeds under it. I could have used Treeview control, but Treeview requires custom rendering to display variable font sizes. Blech. I opted instead to use a ToolStrip control with category labels flush against the left, and feeds under the categories displayed as margins. (See the picture from my previous post for a visual.)

I wanted to have a context menu for this "treeview", so that I could add and remove categories and feeds easily. This context menu would need different options - and different actions - depending on what ToolStripItem was underneath the mouse when the user right-clicked.

I thought I could obtain the ToolStripItem underneath the mouse by using the OwnerItem property, as outlined in How to: Handle the ContextMenuStrip Opening Event. No dice. There's no direct ownership between the context menu and the items on the ToolStrip, so this doesn't fly. In order to obtain the ToolStripItem underneath the mouse during right-click, I had to:

Set a ContextMenuStrip for my ToolStrip;
Handle the Opening event on ContextMenuStrip; and
Obtain the ToolStripItem using the GetItemAt() method.

Here's the basic code:

        public Form1()
        {
            InitializeComponent();

            toolStrip1.ContextMenuStrip.Opening += new CancelEventHandler(ContextMenuStrip_Opening);
        }

        void ContextMenuStrip_Opening(object sender, CancelEventArgs e)
        {
            // This must be relative to the upper left corner of ToolStrip.
            Point pt = this.PointToClient(Cursor.Position);
            ToolStripItem item = toolStrip1.GetItemAt(pt);
            if (item == null)
            {
                // Offer to add a new category only.
                // NOTE: Change this to adjust the menu to your application.
                contextMenuStrip1.Items[1].Visible = false;
                contextMenuStrip1.Items[0].Visible = true;
            }
            else
            {
                // This is a category or a feed.
                // NOTE: Change this to adjust the menu to your application.
                contextMenuStrip1.Items[0].Visible = false;
                contextMenuStrip1.Items[1].Visible = true;
            }
        }

NOTE: If you debug, do NOT put your breakpoint on the line that calls PointToClient(), as the call to Cursor.Position will return the coordinates of the mouse in the Visual Studio window.

Radio Buttons on a MenuStrip

Karl Erickson — Mon, 24 Apr 2006 14:20:00 GMT

Check boxes on menu items are nice, but sometimes you want to display options that are more complex than true/false. How do you display radio buttons on menus? The following sneak preview explains how. This topic will appear in the next documentation update.

How to: Display Option Buttons in a MenuStrip

Option buttons, also known as radio buttons, are similar to check boxes except that users can select only one at a time. Although by default the ToolStripMenuItem class does not provide option-button behavior, the class does provide check-box behavior that you can customize to implement option-button behavior for menu items in a MenuStrip control.

When the CheckOnClick property of a menu item is true, users can click the item to toggle the display of a check mark. The Checked property indicates the current state of the item. To implement basic option-button behavior, you must ensure that when an item is selected, you set the Checked property for the previously selected item to false.

The following procedures describe how to implement this and additional functionality in a class that inherits the ToolStripMenuItem class. The ToolStripRadioButtonMenuItem class overrides members such as OnCheckedChanged and OnPaint to provide the selection behavior and appearance of option buttons. Additionally, this class overrides the Enabled property so that options on a submenu are disabled unless the parent item is selected.

To implement option-button selection behavior

1. Initialize the CheckOnClick property to true to enable item selection.

Visual Basic
' Called by all constructors to initialize CheckOnClick.
Private Sub Initialize()
    CheckOnClick = True
End Sub

C#
// Called by all constructors to initialize CheckOnClick.
private void Initialize()
{
    CheckOnClick = true;
}

2. Override the OnCheckedChanged method to clear the selection of the previously selected item when a new item is selected.

Visual Basic
Protected Overrides Sub OnCheckedChanged(ByVal e As EventArgs)

    MyBase.OnCheckedChanged(e)

    ' If this item is no longer in the checked state, do nothing.
    If Not Checked Then Return

    ' Clear the checked state for all siblings.
    For Each item As ToolStripItem In Parent.Items

        Dim radioItem As ToolStripRadioButtonMenuItem = _
            TryCast(item, ToolStripRadioButtonMenuItem)
        If radioItem IsNot Nothing AndAlso _
            radioItem IsNot Me AndAlso _
            radioItem.Checked Then

            radioItem.Checked = False

            ' Only one item can be selected at a time,
            ' so there is no need to continue.
            Return

        End If
    Next

End Sub

C#
protected override void OnCheckedChanged(EventArgs e)
{
    base.OnCheckedChanged(e);

    // If this item is no longer in the checked state, do nothing.
    if (!Checked) return;

    // Clear the checked state for all siblings.
    foreach (ToolStripItem item in Parent.Items)
    {
        ToolStripRadioButtonMenuItem radioItem =
            item as ToolStripRadioButtonMenuItem;
        if (radioItem != null && radioItem != this && radioItem.Checked)
        {
            radioItem.Checked = false;

            // Only one item can be selected at a time,
            // so there is no need to continue.
            return;
        }
    }
}

3. Override the OnClick method to ensure that clicking an item that has already been selected will not clear the selection.

Visual Basic
Protected Overrides Sub OnClick(ByVal e As EventArgs)

    ' If the item is already in the checked state, do not call
    ' the base method, which would toggle the value.
    If Checked Then Return

    MyBase.OnClick(e)
End Sub

C#
protected override void OnClick(EventArgs e)
{
    // If the item is already in the checked state, do not call
    // the base method, which would toggle the value.
    if (Checked) return;

    base.OnClick(e);
}

To modify the appearance of the option-button items

1. Override the OnPaint method to paint over the default check-mark by using the RadioButtonRenderer class.

Visual Basic
' Let the item paint itself, and then paint the RadioButton
' where the check mark is displayed, covering the check mark
' if it is present.
Protected Overrides Sub OnPaint(ByVal e As PaintEventArgs)

    MyBase.OnPaint(e)

    ' If the client sets the Image property, the selection behavior
    ' remains unchanged, but the RadioButton is not displayed and the
    ' selection is indicated only by the selection rectangle.
    If Image IsNot Nothing Then Return

    ' Determine the correct state of the RadioButton.
    Dim buttonState As RadioButtonState = _
        RadioButtonState.UncheckedNormal
    If Enabled Then
        If mouseDownState Then
            If Checked Then
                buttonState = RadioButtonState.CheckedPressed
            Else
                buttonState = RadioButtonState.UncheckedPressed
            End If
        ElseIf mouseHoverState Then
            If Checked Then
                buttonState = RadioButtonState.CheckedHot
            Else
                buttonState = RadioButtonState.UncheckedHot
            End If
        Else
            If Checked Then buttonState = RadioButtonState.CheckedNormal
        End If
    Else
        If Checked Then
            buttonState = RadioButtonState.CheckedDisabled
        Else
            buttonState = RadioButtonState.UncheckedDisabled
        End If
    End If

    ' Calculate the position at which to display the RadioButton.
    Dim offset As Int32 = CInt((ContentRectangle.Height - _
        RadioButtonRenderer.GetGlyphSize( _
        e.Graphics, buttonState).Height) / 2)
    Dim imageLocation As Point = New Point( _
        ContentRectangle.Location.X + 4, _
        ContentRectangle.Location.Y + offset)

    ' If the item is selected and the RadioButton paints with partial
    ' transparency, such as when theming is enabled, the check mark
    ' shows through the RadioButton image. In this case, paint a
    ' non-transparent background first to cover the check mark.
    If Checked AndAlso RadioButtonRenderer _
        .IsBackgroundPartiallyTransparent(buttonState) Then

        Dim glyphSize As Size = RadioButtonRenderer _
            .GetGlyphSize(e.Graphics, buttonState)
        glyphSize.Height -= 1
        glyphSize.Width -= 1
        Dim backgroundRectangle As _
            New Rectangle(imageLocation, glyphSize)
        e.Graphics.FillEllipse( _
            SystemBrushes.Control, backgroundRectangle)
    End If

    RadioButtonRenderer.DrawRadioButton( _
        e.Graphics, imageLocation, buttonState)

End Sub

C#
// Let the item paint itself, and then paint the RadioButton
// where the check mark is displayed, covering the check mark
// if it is present.
protected override void OnPaint(PaintEventArgs e)
{
    base.OnPaint(e);

    // If the client sets the Image property, the selection behavior
    // remains unchanged, but the RadioButton is not displayed and the
    // selection is indicated only by the selection rectangle.
    if (Image != null) return;

    // Determine the correct state of the RadioButton.
    RadioButtonState buttonState = RadioButtonState.UncheckedNormal;
    if (Enabled)
    {
        if (mouseDownState)
        {
            if (Checked) buttonState = RadioButtonState.CheckedPressed;
            else buttonState = RadioButtonState.UncheckedPressed;
        }
        else if (mouseHoverState)
        {
            if (Checked) buttonState = RadioButtonState.CheckedHot;
            else buttonState = RadioButtonState.UncheckedHot;
        }
        else
        {
            if (Checked) buttonState = RadioButtonState.CheckedNormal;
        }
    }
    else
    {
        if (Checked) buttonState = RadioButtonState.CheckedDisabled;
        else buttonState = RadioButtonState.UncheckedDisabled;
    }

    // Calculate the position at which to display the RadioButton.
    Int32 offset = (ContentRectangle.Height -
        RadioButtonRenderer.GetGlyphSize(
        e.Graphics, buttonState).Height) / 2;
    Point imageLocation = new Point(
        ContentRectangle.Location.X + 4,
        ContentRectangle.Location.Y + offset);

    // If the item is selected and the RadioButton paints with partial
    // transparency, such as when theming is enabled, the check mark
    // shows through the RadioButton image. In this case, paint a
    // non-transparent background first to cover the check mark.
    if (Checked && RadioButtonRenderer
        .IsBackgroundPartiallyTransparent(buttonState))
    {
        Size glyphSize = RadioButtonRenderer
            .GetGlyphSize(e.Graphics, buttonState);
        glyphSize.Height--;
        glyphSize.Width--;
        Rectangle backgroundRectangle =
            new Rectangle(imageLocation, glyphSize);
        e.Graphics.FillEllipse(
            SystemBrushes.Control, backgroundRectangle);
    }

    RadioButtonRenderer.DrawRadioButton(
        e.Graphics, imageLocation, buttonState);
}

2. Override the OnMouseEnter, OnMouseLeave, OnMouseDown, and OnMouseUp methods to track the state of the mouse and ensure that the OnPaint method paints the correct option-button state.

Visual Basic
Private mouseHoverState As Boolean = False

Protected Overrides Sub OnMouseEnter(ByVal e As EventArgs)
    mouseHoverState = True

    ' Force the item to repaint with the new RadioButton state.
    Invalidate()

    MyBase.OnMouseEnter(e)
End Sub

Protected Overrides Sub OnMouseLeave(ByVal e As EventArgs)
    mouseHoverState = False
    MyBase.OnMouseLeave(e)
End Sub

Private mouseDownState As Boolean = False

Protected Overrides Sub OnMouseDown(ByVal e As MouseEventArgs)
    mouseDownState = True

    ' Force the item to repaint with the new RadioButton state.
    Invalidate()

    MyBase.OnMouseDown(e)
End Sub

Protected Overrides Sub OnMouseUp(ByVal e As MouseEventArgs)
    mouseDownState = False
    MyBase.OnMouseUp(e)
End Sub

C#
private bool mouseHoverState = false;

protected override void OnMouseEnter(EventArgs e)
{
    mouseHoverState = true;

    // Force the item to repaint with the new RadioButton state.
    Invalidate();

    base.OnMouseEnter(e);
}

protected override void OnMouseLeave(EventArgs e)
{
    mouseHoverState = false;
    base.OnMouseLeave(e);
}

private bool mouseDownState = false;

protected override void OnMouseDown(MouseEventArgs e)
{
    mouseDownState = true;

    // Force the item to repaint with the new RadioButton state.
    Invalidate();

    base.OnMouseDown(e);
}

protected override void OnMouseUp(MouseEventArgs e)
{
    mouseDownState = false;
    base.OnMouseUp(e);
}

To disable options on a submenu when the parent item is not selected

1. Override the Enabled property so that the item is disabled when it has a parent item with both a CheckOnClick value of true and a Checked value of false.

Visual Basic
' Enable the item only if its parent item is in the checked state
' and its Enabled property has not been explicitly set to false.
Public Overrides Property Enabled() As Boolean
    Get
        Dim ownerMenuItem As ToolStripMenuItem = _
            TryCast(OwnerItem, ToolStripMenuItem)

        ' Use the base value in design mode to prevent the designer
        ' from setting the base value to the calculated value.
        If Not DesignMode AndAlso _
            ownerMenuItem IsNot Nothing AndAlso _
            ownerMenuItem.CheckOnClick Then
            Return MyBase.Enabled AndAlso ownerMenuItem.Checked
        Else
            Return MyBase.Enabled
        End If
    End Get

    Set(ByVal value As Boolean)
        MyBase.Enabled = value
    End Set
End Property

C#
// Enable the item only if its parent item is in the checked state
// and its Enabled property has not been explicitly set to false.
public override bool Enabled
{
    get
    {
        ToolStripMenuItem ownerMenuItem =
            OwnerItem as ToolStripMenuItem;

        // Use the base value in design mode to prevent the designer
        // from setting the base value to the calculated value.
        if (!DesignMode &&
            ownerMenuItem != null && ownerMenuItem.CheckOnClick)
        {
            return base.Enabled && ownerMenuItem.Checked;
        }
        else return base.Enabled;
    }
    set
    {
        base.Enabled = value;
    }
}

2. Override the OnOwnerChanged method to subscribe to the CheckedChanged event of the parent item.

Visual Basic
' When OwnerItem becomes available, if it is a ToolStripMenuItem
' with a CheckOnClick property value of true, subscribe to its
' CheckedChanged event.
Protected Overrides Sub OnOwnerChanged(ByVal e As EventArgs)

    Dim ownerMenuItem As ToolStripMenuItem = _
        TryCast(OwnerItem, ToolStripMenuItem)

    If ownerMenuItem IsNot Nothing AndAlso _
        ownerMenuItem.CheckOnClick Then
        AddHandler ownerMenuItem.CheckedChanged, New _
            EventHandler(AddressOf OwnerMenuItem_CheckedChanged)
    End If

    MyBase.OnOwnerChanged(e)

End Sub

C#
// When OwnerItem becomes available, if it is a ToolStripMenuItem
// with a CheckOnClick property value of true, subscribe to its
// CheckedChanged event.
protected override void OnOwnerChanged(EventArgs e)
{
    ToolStripMenuItem ownerMenuItem =
        OwnerItem as ToolStripMenuItem;
    if (ownerMenuItem != null && ownerMenuItem.CheckOnClick)
    {
        ownerMenuItem.CheckedChanged +=
            new EventHandler(OwnerMenuItem_CheckedChanged);
    }
    base.OnOwnerChanged(e);
}

3. In the handler for the parent-item CheckedChanged event, invalidate the item to update the display with the new enabled state.

Visual Basic
' When the checked state of the parent item changes,
' repaint the item so that the new Enabled state is displayed.
Private Sub OwnerMenuItem_CheckedChanged( _
    ByVal sender As Object, ByVal e As EventArgs)
    Invalidate()
End Sub

C#
// When the checked state of the parent item changes,
// repaint the item so that the new Enabled state is displayed.
private void OwnerMenuItem_CheckedChanged(
    object sender, EventArgs e)
{
    Invalidate();
}

Example

You can download the complete code example from the Attachment(s) section below. The code example provides the complete ToolStripRadioButtonMenuItem class, plus a Form class and Program class to demonstrate the option-button behavior.

Compiling the Code

This example requires:

References to the System, System.Drawing, and System.Windows.Forms assemblies.

Using ToolStrip to Create a Custom Title Bar

Jay A. Allen — Fri, 07 Apr 2006 21:14:00 GMT

Our current documentation on creating nonrectangular forms could stand some enhancement. The most glaring piece of missing info is how to add a custom title bar. The document we do have gives code for how to move the form if the user clicks anywhere in the form area - but how often do you need this? In most cases, you want to slap your own custom title bar on the app, and move the app around when the user clicks on this title bar and drags it about.

Picture 1: Meditate Awake! application

For the sample app I've been developing, I decided to replace the standard title bar with a ToolStrip that acts like a title bar. (Can't you tell I'm no graphic designer?) It was surprisingly easy to enable the ToolStrip to act like a title bar. The secret ingredient was setting ToolStrip.Capture to True when the mouse button is clicked; this is necessary to prevent the cursor from moving faster than the form, which results in the cursor flying away from the ToolStrip before you've released the left mouse button.

Private _MouseOffset As Point
Private isMouseDown As Boolean = False

    Private Sub TitleStrip_MouseDown(ByVal sender As Object, ByVal e As System.Windows.Forms.MouseEventArgs) Handles TitleStrip.MouseDown
        If e.Button = System.Windows.Forms.MouseButtons.Left Then
            _MouseOffset = New Point(e.X, e.Y)
            _IsMouseDown = True
            TitleStrip.Capture = True
        End If
    End Sub

    Private Sub TitleStrip_MouseMove(ByVal sender As Object, ByVal e As System.Windows.Forms.MouseEventArgs) Handles TitleStrip.MouseMove
        If _IsMouseDown Then
            Dim _CurrentPos As Point = Control.MousePosition
            _CurrentPos.X = _CurrentPos.X - _MouseOffset.X
            _CurrentPos.Y = _CurrentPos.Y - _MouseOffset.Y
            Me.Location = _CurrentPos
        End If
    End Sub

    Private Sub TitleStrip_MouseUp(ByVal sender As Object, ByVal e As System.Windows.Forms.MouseEventArgs) Handles TitleStrip.MouseUp
        If e.Button = System.Windows.Forms.MouseButtons.Left Then
            _IsMouseDown = False
            TitleStrip.Capture = False
        End If
    End Sub

Using ToolStrip as a TabControl Alternative in Windows Forms

WinFormsUE — Tue, 21 Mar 2006 23:06:00 GMT

I've been going back and forth lately with Karl Erickson, another member of our team, and the guy who owns the TabControl docs. It appears that my gripes with TabControl weren't mine alone. He's been fielding reports of various weird bugs, such as the visual styles weirdness and the funky way TabControl handles layout at run time. Basically, the darn thing isn't meant to have its tab layout order changed at run time; properties like Alignment are best set at design time, and then kept like that for the life of your app.

So, yes: it's possible to hack up TabControl to make right-aligned and left-aligned tabs work.

Or, you can use ToolStrip instead.

Picture 1: ToolStrip Tab Imitator

The idea is simple. Add a SplitContainer to your form. Make one panel the "nav" panel, and the other the content panel. (You could just Dock it Left, but using SplitContainer makes it easier to resize. And yes, I know that ToolStripContainer exists - I'm still trying to force it to do my bidding.) Add a ToolStrip to the nav panel and set it to Dock=Full. Add image and text for each of the buttons, and use the following settings on each button:

.DisplayType=TextAndImage
.ImageAlign=MiddleLeft
.TextAlign=MiddleRight
.TextImageRelation=Overlay

For the panels themselves, you can develop separate UserControl classes, and switch between them whenever a user clicks a button. You can incorporate interfaces onto the UserControls to test if there is any data that needs to be persisted before switching tabs. E.g., if you're on the Pay Bills tab, and the user has unconfirmed bill payments, you might want to prompt to confirm or discard the transactions.

Here's another screenshot of a rinky-dink app I've been using as a testbed. I haven't written any of the panels yet, so there's a big gaping hole in the middle there, but this shows how to do the same thing using larger, more stylized buttons on the right hand side. These use .TextImageRelation=ImageBeforeText to make them work. Also, the RenderStyle of ToolStrip is set to System, and the BackColor to White to blend in with the buttons. (Don't attempt to use TransparencyKey when using complex images.)

You'll have to forgive the app's slight klunkiness; I've hacked it to bits recently. And yes, that is a ToolStrip control I'm using as the title bar!

Picture 2: Right-Aligned Buttons

The benefits of this approach are numerous. Because you're using ToolStrip, you can use features like drop-down buttons, embedded ComboBoxes, fly-out menus, context menus, etc. ToolStrip is a great "kitchen sink" control that's been designed to do just about anything. It has a modern look and feel by default; you can make it very slick without writing a lick of code. If the built-in renderers don't meet your needs, however, never fear: ToolStrip can be stylized out the wazoo using a custom renderer.