HypernovaDesktop Components · docs
Binarymission
WinForms › Menu Item › BinaryMenuItem

BinaryMenuItem

class.NET Framework 4.8Binarymission.WinForms.Controls.MenuControls

A drop-in replacement for the classic MenuItem that draws itself: menus with a picture beside each command, a coloured side bar, check marks and radio dots in colours of your choice, Office style highlighting, and group headers that divide a long menu into sections.

public class BinaryMenuItem : MenuItem

Inherits from / implements: MenuItem

Remarks

Build a MainMenu or ContextMenu exactly as usual, with BinaryMenuItem objects in place of MenuItem; every item draws itself, so there is no drawing code to write. Items can be nested, checked, radio-checked, disabled and given shortcuts as usual. A caption of "-" makes a separator.

Colours

The colours are shared by every item in the application and set on BinaryMenuItemManager: background, highlight, side bar, border, check mark, and the theme of the side bar. Each item takes a copy as it is created; after changing them, call BinaryMenuItemManager.PerformPaint with the form so that items already built pick up the change. PrepareCustomColorMatrix gives a single item colours of its own.

This class is in the .NET Framework edition only; the classic menu does not exist in .NET 6 and later.

Examples

using System;
using System.Drawing;
using System.Windows.Forms;
using Binarymission.WinForms.Controls.MenuControls;

public class InvoiceForm : Form
{
    public InvoiceForm()
    {
        BinaryMenuItemManager.MenuRenderingStyle = MenuRenderingStyle.OutlookBlueTheme;

        BinaryMenuItem file = new BinaryMenuItem("&File", null, false);
        file.MenuItems.Add(new BinaryMenuItem("Recent invoices", null, true));
        file.MenuItems.Add(new BinaryMenuItem("INV-20431 - Northwind", OnOpenRecent, false));
        file.MenuItems.Add(new BinaryMenuItem("-", null, false));
        file.MenuItems.Add(new BinaryMenuItem("&Save", OnSave, Shortcut.CtrlS, Properties.Resources.Save16, false));
        file.MenuItems.Add(new BinaryMenuItem("&Print...", OnPrint, Shortcut.CtrlP, Properties.Resources.Print16, false));

        Menu = new MainMenu(new MenuItem[] { file });
        BinaryMenuItemManager.PerformPaint(this);
    }

    private void OnOpenRecent(object sender, EventArgs e) { }
    private void OnSave(object sender, EventArgs e) { }
    private void OnPrint(object sender, EventArgs e) { }
}

See also

Members at a glance

Constructors
BinaryMenuItemInitialises a new item with no caption, ready for its Text to be set.
BinaryMenuItemInitialises a new item with a caption, a click handler and a keyboard shortcut.
BinaryMenuItemInitialises a new item with a caption, a click handler, a keyboard shortcut and a picture.
BinaryMenuItemInitialises a new item with a caption, a click handler, a keyboard shortcut and a picture given either directly or from an image list.
BinaryMenuItemInitialises a new item with a caption and a click handler.
Properties
GroupHeaderBackColorGets or sets the background colour of the item when it is a group header.
GroupHeaderBorderColorGets or sets the colour of the border round the item when it is a group header.
GroupHeaderDottedBorderDepthGets or sets the length of each dot in a group header's dotted border.
GroupHeaderDottedBorderGapGets or sets the space between the dots of a group header's dotted border.
GroupHeaderForeColorGets or sets the colour of the caption when the item is a group header.
GroupHeaderGapWithTheBorderGets or sets the space above and below a group header's coloured band, inside its border.
ImageIndexGets or sets the position in ImageList of the item's picture.
ImageListGets or sets an image list to take the item's picture from, at ImageIndex.
IsGroupHeaderBorderDrawnAsDotsGets or sets whether a group header's border is dotted rather than solid.
IsMenuItemAGroupHeaderGets or sets whether the item is drawn as a group header – a bold, coloured band that titles the items below it.
MenuItemClickHandlerGets or sets the click handler given to the item's constructor.
MenuItemImageGets or sets the picture shown in the side bar beside the caption.
ShortcutTextGets or sets the text shown at the right of the item, such as "Ctrl+S".
TextGets or sets the item's caption.
TransparentColorForImageGets or sets the colour left out of the item's picture, so the side bar shows through.
Methods
OnDrawItemDraws the item: its background, side bar, picture or check mark, caption and shortcut, in the colours of BinaryMenuItemManager.
OnMeasureItemTells Windows the item's size: the menu font's height, and the width of the caption and the shortcut text.
OnSelectRaises the MenuItem.Select event.
PrepareCustomColorMatrixGives this item colours of its own, in place of those shared through BinaryMenuItemManager.

Constructors

BinaryMenuItem

public BinaryMenuItem() : this(null, null, false)

Initialises a new item with no caption, ready for its Text to be set.

BinaryMenuItem

public BinaryMenuItem(string MenuItemText, EventHandler CustomEventHandler, Shortcut ShortCutToAssociate, bool isMenuItemAGroupHeader) : this(MenuItemText, CustomEventHandler, isMenuItemAGroupHeader)

Initialises a new item with a caption, a click handler and a keyboard shortcut.

Parameters
MenuItemText
The caption, with & before the access key letter, or "-" for a separator line.
CustomEventHandler
The handler for the item's MenuItem.Click event, or null.
ShortCutToAssociate
The keyboard shortcut, shown at the right of the item, such as CtrlS.
isMenuItemAGroupHeader
true to draw the item as a group header (see IsMenuItemAGroupHeader).

BinaryMenuItem

public BinaryMenuItem(string MenuItemText, EventHandler CustomEventHandler, Shortcut ShortCutToAssociate, Bitmap Icon, bool isMenuItemAGroupHeader) : this(MenuItemText, CustomEventHandler, isMenuItemAGroupHeader)

Initialises a new item with a caption, a click handler, a keyboard shortcut and a picture.

Parameters
MenuItemText
The caption, with & before the access key letter, or "-" for a separator line.
CustomEventHandler
The handler for the item's MenuItem.Click event, or null.
ShortCutToAssociate
The keyboard shortcut, shown at the right of the item, such as CtrlS.
Icon
The picture shown in the side bar beside the caption, ideally 16 by 16 pixels, or null.
isMenuItemAGroupHeader
true to draw the item as a group header (see IsMenuItemAGroupHeader).

BinaryMenuItem

public BinaryMenuItem(string MenuItemText, EventHandler CustomEventHandler, Shortcut ShortCutToAssociate, Bitmap Icon, ImageList ImagelistToAssociate, int ImagelistIndex, bool isMenuItemAGroupHeader) : this(MenuItemText, CustomEventHandler, isMenuItemAGroupHeader)

Initialises a new item with a caption, a click handler, a keyboard shortcut and a picture given either directly or from an image list.

Parameters
MenuItemText
The caption, with & before the access key letter, or "-" for a separator line.
CustomEventHandler
The handler for the item's MenuItem.Click event, or null.
ShortCutToAssociate
The keyboard shortcut, shown at the right of the item, such as CtrlS.
Icon
The picture shown beside the caption, or null to take it from ImagelistToAssociate. A picture given here wins over the image list.
ImagelistToAssociate
An image list to take the picture from, or null.
ImagelistIndex
The position of the picture in ImagelistToAssociate, or -1 for none.
isMenuItemAGroupHeader
true to draw the item as a group header (see IsMenuItemAGroupHeader).

BinaryMenuItem

public BinaryMenuItem(string MenuItemText, EventHandler CustomEventHandler, bool isMenuItemAGroupHeader) : base(MenuItemText, CustomEventHandler)

Initialises a new item with a caption and a click handler.

Parameters
MenuItemText
The caption, with & before the access key letter, or "-" for a separator line.
CustomEventHandler
The handler for the item's MenuItem.Click event, or null.
isMenuItemAGroupHeader
true to draw the item as a group header (see IsMenuItemAGroupHeader).
Remarks

A picture can be added later with MenuItemImage or ImageList.

Properties

GroupHeaderBackColor

public Color GroupHeaderBackColor

Gets or sets the background colour of the item when it is a group header.

Value
The default is SystemColors.ControlDark.

GroupHeaderBorderColor

public Color GroupHeaderBorderColor

Gets or sets the colour of the border round the item when it is a group header.

Value
The default is SystemColors.ControlDarkDark.

GroupHeaderDottedBorderDepth

public int GroupHeaderDottedBorderDepth

Gets or sets the length of each dot in a group header's dotted border.

Value
The length in pixels. The default is 1.

GroupHeaderDottedBorderGap

public int GroupHeaderDottedBorderGap

Gets or sets the space between the dots of a group header's dotted border.

Value
The space in pixels. The default is 2.

GroupHeaderForeColor

public Color GroupHeaderForeColor

Gets or sets the colour of the caption when the item is a group header.

Value
The default is SystemColors.Window.

GroupHeaderGapWithTheBorder

public int GroupHeaderGapWithTheBorder

Gets or sets the space above and below a group header's coloured band, inside its border.

Value
The space in pixels, from 0 to 5; larger values are ignored. The default is 0.

ImageIndex

public int ImageIndex

Gets or sets the position in ImageList of the item's picture.

Value
The index, or -1 for no picture. The default is -1.

ImageList

public ImageList ImageList

Gets or sets an image list to take the item's picture from, at ImageIndex.

Value
The image list, or null. The default is null.
Remarks

Used only while MenuItemImage is null and ImageIndex is not -1.

IsGroupHeaderBorderDrawnAsDots

public bool IsGroupHeaderBorderDrawnAsDots

Gets or sets whether a group header's border is dotted rather than solid.

Value
true for dots of GroupHeaderDottedBorderDepth pixels, GroupHeaderDottedBorderGap apart; the default is true.

IsMenuItemAGroupHeader

public bool IsMenuItemAGroupHeader

Gets or sets whether the item is drawn as a group header – a bold, coloured band that titles the items below it.

Value
true for a header; the default is false.
Remarks

A header is drawn in GroupHeaderBackColor and GroupHeaderForeColor inside a GroupHeaderBorderColor border, and is not highlighted under the pointer. It can still be clicked, so give it no click handler, or set MenuItem.Enabled to false.

Example
BinaryMenuItem header = new BinaryMenuItem("Recent customers", null, true)
{
    GroupHeaderBackColor = Color.SteelBlue,
    GroupHeaderForeColor = Color.White,
    GroupHeaderBorderColor = Color.Navy
};
contextMenu.MenuItems.Add(header);

MenuItemClickHandler

public EventHandler MenuItemClickHandler

Gets or sets the click handler given to the item's constructor.

Value
The handler, or null.
Remarks

Setting it records the handler but does not attach it to MenuItem.Click; to handle clicks on an existing item, use item.Click += handler.

MenuItemImage

public Bitmap MenuItemImage

Gets or sets the picture shown in the side bar beside the caption.

Value
The picture, ideally 16 by 16 pixels, or null. Pixels of TransparentColorForImage are left out.
Remarks

A picture set here wins over ImageList. A checked item with a picture shows the picture on a highlighted square instead of a check mark. Takes effect when the menu is next opened.

ShortcutText

public string ShortcutText

Gets or sets the text shown at the right of the item, such as "Ctrl+S".

Value
The text. The default is an empty string.
Remarks

When the item has a MenuItem.Shortcut, the text is replaced with that shortcut spelt out each time the menu is measured, so set it only for items without one – for example to show a key combination your form handles itself.

Text

public new string Text

Gets or sets the item's caption.

Value
The caption, with & before the access key letter, or "-" to make the item a separator line.

TransparentColorForImage

public Color TransparentColorForImage

Gets or sets the colour left out of the item's picture, so the side bar shows through.

Value
The colour. The default is teal, #008080, the usual background of classic toolbar bitmaps.
Remarks

The item draws a copy of the picture; your bitmap is not changed.

Methods

OnDrawItem

protected override void OnDrawItem(DrawItemEventArgs e)

Draws the item: its background, side bar, picture or check mark, caption and shortcut, in the colours of BinaryMenuItemManager.

Parameters
e
The surface, bounds and state (selected, disabled) to draw.

OnMeasureItem

protected override void OnMeasureItem(MeasureItemEventArgs e)

Tells Windows the item's size: the menu font's height, and the width of the caption and the shortcut text.

Parameters
e
The surface to measure on, and where to report the size.

OnSelect

protected override void OnSelect(EventArgs e)

Raises the MenuItem.Select event.

Parameters
e
The event data.

PrepareCustomColorMatrix

public void PrepareCustomColorMatrix( Color menuItemBackgroundColor, Color menuItemSelectionColor, Color menuItemControlColor)

Gives this item colours of its own, in place of those shared through BinaryMenuItemManager.

Parameters
menuItemBackgroundColor
The background colour, or Color.Empty for the shared one.
menuItemSelectionColor
The highlight colour, or Color.Empty for the shared one.
menuItemControlColor
The side bar colour, or Color.Empty for the shared one.
Remarks

The colours are used as given, without the alpha blending the shared colours go through. A later BinaryMenuItemManager.PerformPaint puts the shared colours back.