How can I customize the system menu of a Windows Form?

Question

I want to add the age old About menu item to my application. I want to add it to the 'system menu' of the application (the one which pops up when we click the application icon in the top-left corner). So, how can I do it in .NET?

Answer 1

Windows makes it fairly easy to get a handle to a copy of the form's system menu for customization purposes with the GetSystemMenu function. The hard part is that you're on your own to perform the appropriate modifications to the menu it returns, using functions such as AppendMenu, InsertMenu, and DeleteMenu just as you would if you were programming directly against the Win32 API.

However, if all you want to do is add a simple menu item, it's really not all that difficult. For example, you would only need to use the AppendMenu function because all you want to do is add an item or two to the end of the menu. Doing anything more advanced (like inserting an item in the middle of the menu, displaying a bitmap on the menu item, showing menu items checked, setting a default menu item, etc.) requires a bit more work. But once you know how it's done, you can go wild. The documentation on menu-related functions tells all.

Here's the complete code for a form that adds a separator line and an "About" item to the bottom of its system menu (also called a window menu):

using System;
using System.Windows.Forms;
using System.Runtime.InteropServices;

public class CustomForm : Form
{
    // P/Invoke constants
    private const int WM_SYSCOMMAND = 0x112;
    private const int MF_STRING = 0x0;
    private const int MF_SEPARATOR = 0x800;

    // P/Invoke declarations
    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern IntPtr GetSystemMenu(IntPtr hWnd, bool bRevert);

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern bool AppendMenu(IntPtr hMenu, int uFlags, int uIDNewItem, string lpNewItem);

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern bool InsertMenu(IntPtr hMenu, int uPosition, int uFlags, int uIDNewItem, string lpNewItem);


    // ID for the About item on the system menu
    private int SYSMENU_ABOUT_ID = 0x1;

    public CustomForm()
    {
    }

    protected override void OnHandleCreated(EventArgs e)
    {
        base.OnHandleCreated(e);

        // Get a handle to a copy of this form's system (window) menu
        IntPtr hSysMenu = GetSystemMenu(this.Handle, false);

        // Add a separator
        AppendMenu(hSysMenu, MF_SEPARATOR, 0, string.Empty);

        // Add the About menu item
        AppendMenu(hSysMenu, MF_STRING, SYSMENU_ABOUT_ID, "&About…");
    }

    protected override void WndProc(ref Message m)
    {
        base.WndProc(ref m);

        // Test if the About item was selected from the system menu
        if ((m.Msg == WM_SYSCOMMAND) && ((int)m.WParam == SYSMENU_ABOUT_ID))
        {
            MessageBox.Show("Custom About Dialog");
        }

    }
}

And here's what the finished product looks like:

  

Answer 2

I've taken Cody Gray's solution one step further and made a reusable class out of it. It's part of my application log submit tool that should hide its About info in the system menu.

https://github.com/ygoe/FieldLog/blob/master/LogSubmit/Unclassified/UI/SystemMenu.cs

It can easily be used like this:

class MainForm : Form
{
    private SystemMenu systemMenu;

    public MainForm()
    {
        InitializeComponent();

        // Create instance and connect it with the Form
        systemMenu = new SystemMenu(this);

        // Define commands and handler methods
        // (Deferred until HandleCreated if it's too early)
        // IDs are counted internally, separator is optional
        systemMenu.AddCommand("&About…", OnSysMenuAbout, true);
    }

    protected override void WndProc(ref Message msg)
    {
        base.WndProc(ref msg);

        // Let it know all messages so it can handle WM_SYSCOMMAND
        // (This method is inlined)
        systemMenu.HandleMessage(ref msg);
    }

    // Handle menu command click
    private void OnSysMenuAbout()
    {
        MessageBox.Show("My about message");
    }
}

Answer 3

The value-add is rather small for the amount of pinvoke you'll need. But it is possible. Use GetSystemMenu() to retrieve the system menu handle. Then InsertMenuItem to add an entry. You have to do this in an override of OnHandleCreated() so you recreate the menu when the window gets recreated.

Override WndProc() to recognize the WM_SYSCOMMAND message that's generated when the user clicks it. Visit pinvoke.net for the pinvoke declarations you'll need.

Answer 4

I know this answer is old but I really liked LonelyPixel's answer. However, it needed some work to work correctly with WPF. Below is a WPF version I wrote, so you do not have to :).

/// <summary>
/// Extends the system menu of a window with additional commands.
/// Adapted from:
/// https://github.com/dg9ngf/FieldLog/blob/master/LogSubmit/Unclassified/UI/SystemMenu.cs
/// </summary>
public class SystemMenuExtension
{
    #region Native methods

    private const int WM_SYSCOMMAND = 0x112;
    private const int MF_STRING = 0x0;
    private const int MF_SEPARATOR = 0x800;

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern IntPtr GetSystemMenu(IntPtr hWnd, bool bRevert);

    [DllImport("user32.dll", CharSet = CharSet.Auto, SetLastError = true)]
    private static extern bool AppendMenu(IntPtr hMenu, int uFlags, int uIDNewItem, string lpNewItem);

    #endregion Native methods

    #region Private data
    private Window window;
    private IntPtr hSysMenu;
    private int lastId = 0;
    private List<Action> actions = new List<Action>();
    private List<CommandInfo> pendingCommands;

    #endregion Private data

    #region Constructors

    /// <summary>
    /// Initialises a new instance of the <see cref="SystemMenu"/> class for the specified
    /// <see cref="Form"/>.
    /// </summary>
    /// <param name="window">The window for which the system menu is expanded.</param>
    public SystemMenuExtension(Window window)
    {
        this.window = window;
        if(this.window.IsLoaded)
        {
            WindowLoaded(null, null);
        }
        else
        {
            this.window.Loaded += WindowLoaded;
        }
    }

    #endregion Constructors

    #region Public methods

    /// <summary>
    /// Adds a command to the system menu.
    /// </summary>
    /// <param name="text">The displayed command text.</param>
    /// <param name="action">The action that is executed when the user clicks on the command.</param>
    /// <param name="separatorBeforeCommand">Indicates whether a separator is inserted before the command.</param>
    public void AddCommand(string text, Action action, bool separatorBeforeCommand)
    {
        int id = ++this.lastId;
        if (!this.window.IsLoaded)
        {
            // The window is not yet created, queue the command for later addition
            if (this.pendingCommands == null)
            {
                this.pendingCommands = new List<CommandInfo>();
            }
            this.pendingCommands.Add(new CommandInfo
            {
                Id = id,
                Text = text,
                Action = action,
                Separator = separatorBeforeCommand
            });
        }
        else
        {
            // The form is created, add the command now
            if (separatorBeforeCommand)
            {
                AppendMenu(this.hSysMenu, MF_SEPARATOR, 0, "");
            }
            AppendMenu(this.hSysMenu, MF_STRING, id, text);
        }
        this.actions.Add(action);
    }

    #endregion Public methods

    #region Private methods

    private void WindowLoaded(object sender, RoutedEventArgs e)
    {
        var interop = new WindowInteropHelper(this.window);
        HwndSource source = PresentationSource.FromVisual(this.window) as HwndSource;
        source.AddHook(WndProc);

        this.hSysMenu = GetSystemMenu(interop.EnsureHandle(), false);

        // Add all queued commands now
        if (this.pendingCommands != null)
        {
            foreach (CommandInfo command in this.pendingCommands)
            {
                if (command.Separator)
                {
                    AppendMenu(this.hSysMenu, MF_SEPARATOR, 0, "");
                }
                AppendMenu(this.hSysMenu, MF_STRING, command.Id, command.Text);
            }
            this.pendingCommands = null;
        }
    }

    private IntPtr WndProc(IntPtr hwnd, int msg, IntPtr wParam, IntPtr lParam, ref bool handled)
    {
        if (msg == WM_SYSCOMMAND)
        {
            if ((long)wParam > 0 && (long)wParam <= lastId)
            {
                this.actions[(int)wParam - 1]();
            }
        }

        return IntPtr.Zero;
    }

    #endregion Private methods

    #region Classes

    private class CommandInfo
    {
        public int Id { get; set; }
        public string Text { get; set; }
        public Action Action { get; set; }
        public bool Separator { get; set; }
    }

    #endregion Classes

Answer 5

VB.NET version of accepted answer:

Imports System.Windows.Forms
Imports System.Runtime.InteropServices

Public Class CustomForm
    Inherits Form
    ' P/Invoke constants
    Private Const WM_SYSCOMMAND As Integer = &H112
    Private Const MF_STRING As Integer = &H0
    Private Const MF_SEPARATOR As Integer = &H800

    ' P/Invoke declarations
    <DllImport("user32.dll", CharSet := CharSet.Auto, SetLastError := True)> _
    Private Shared Function GetSystemMenu(hWnd As IntPtr, bRevert As Boolean) As IntPtr
    End Function

    <DllImport("user32.dll", CharSet := CharSet.Auto, SetLastError := True)> _
    Private Shared Function AppendMenu(hMenu As IntPtr, uFlags As Integer, uIDNewItem As Integer, lpNewItem As String) As Boolean
    End Function

    <DllImport("user32.dll", CharSet := CharSet.Auto, SetLastError := True)> _
    Private Shared Function InsertMenu(hMenu As IntPtr, uPosition As Integer, uFlags As Integer, uIDNewItem As Integer, lpNewItem As String) As Boolean
    End Function


    ' ID for the About item on the system menu
    Private SYSMENU_ABOUT_ID As Integer = &H1

    Public Sub New()
    End Sub

    Protected Overrides Sub OnHandleCreated(e As EventArgs)
        MyBase.OnHandleCreated(e)

        ' Get a handle to a copy of this form's system (window) menu
        Dim hSysMenu As IntPtr = GetSystemMenu(Me.Handle, False)

        ' Add a separator
        AppendMenu(hSysMenu, MF_SEPARATOR, 0, String.Empty)

        ' Add the About menu item
        AppendMenu(hSysMenu, MF_STRING, SYSMENU_ABOUT_ID, "&About…")
    End Sub

    Protected Overrides Sub WndProc(ByRef m As Message)
        MyBase.WndProc(m)

        ' Test if the About item was selected from the system menu
        If (m.Msg = WM_SYSCOMMAND) AndAlso (CInt(m.WParam) = SYSMENU_ABOUT_ID) Then
            MessageBox.Show("Custom About Dialog")
        End If

    End Sub
End Class