Windows Ribbon for WinForms, Part 4 - Application Menu with Buttons
Before we start to use ribbon features, we must learn the basics of ribbon markup.
Commands and Views
A command is an action that is identified by a number, it can be opening the save-as dialog, printing the current document, closing the application, etc. every thing you can do in a function call.
A view is a graphical representation of [usually several] commands. It defines the type of controls used to activate the commands and their size, order and layout on screen.
So using commands and views is actually just another instance of the MVC design pattern, which allows us to separate business logic from presentation logic.
Now we will write a new WinForms application with ribbon that uses the application menu with simple buttons. We start this sample with the an empty WinForms project that already includes ribbon support (see previous post for details). On the next sections I’ll explain:
- Commands part of the ribbon markup
- Views part of the ribbon markup
- code-behind, responding to ribbon events
As always, the entire code is available at windowsribbon.codeplex.com
General markup review
Just a reminder, our basic ribbon markup looks like this:
<?xml version='1.0' encoding='utf-8'?>
Defining Commands in Ribbon Markup
Following is a definition of some commands in ribbon markup:
TooltipDescription="Create a new image.">
TooltipDescription="Open an existing image.">
TooltipDescription="Save the current image.">
Explanation: here we define 4 different commands. Each command has properties assigned either by xml attributes or child elements. We use the following (full list is available at “Commands and Resources” on MSDN):
- Name – this name is used later in the views section to reference to this command
- Id – this is the ID of the command. We get it in code when a command an event occurs.
- LabelTitle – the label title of the command
- LabelDescription – the label description of the command
- TooltipTitle – the tooltip title of the command
- TooltipDescription – the tooltip description of the command
- LargeImages – large image filename for the command, usually 32x32 pixels
- SmallImages – small image filename for the command, usually 16x16 pixels
Setting shortcuts to menu items
Setting a key shortcut for a menu item is done by adding “&" in LabelTitle before the letter you want as a shortcut (similar to shortcuts in the “old” menu system), see the LabelTitle of “New” command for example.
Some comments about image resources in Ribbon markup
The filename defined in the markup (like in LargeImages and SmallImages element), should be a valid (relative or full) path to a filename, otherwise the resource compiler (rc.exe) will output a compilation error: “error RC2135: file not found: <filename>”.
The image file format should be BMP with 32 BPP ARGB pixel format. Many image editing programs, like Microsoft Paint do not preserve the highest order 8-bit alpha channel when saving, thus creating only 24 bit images, the result is that the image will not appear at all.
Update (18.11.2009): convert2bmp is a tool that enables you to convert your images to the required format.
Under both images elements you can put several image files in different sizes, the ribbon framework will choose the best size according to the current DPI setting. For us, normal users, setting two images for 32x32 and 16x16 should be enough. For more information, see "Specifying Ribbon Image Resources" on MSDN.
Defining Views in Ribbon Markup
Following is a definition of the views part of our ribbon markup:
<Button CommandName='cmdButtonNew' />
<Button CommandName='cmdButtonOpen' />
<Button CommandName='cmdButtonSave' />
<Button CommandName='cmdButtonExit' />
Explanation: here we define an application menu that contains two menu groups and 4 buttons. The button CommandName attribute points to the command that this button should trigger upon click.
Handling Ribbon Events
Here will see how to handle the event of clicking of one of our menu buttons.
The following code should reside in our main form code file (form1.cs in my sample):
public enum RibbonMarkupCommands : uint
cmdApplicationMenu = 1000,
cmdButtonNew = 1001,
cmdButtonOpen = 1002,
cmdButtonSave = 1003,
cmdButtonExit = 1004,
This is just a helper enum, to make the code more readable. Every command ID gets a readable symbol.
The important section is our new implementation of the IUICommandHandler.Execute function:
public HRESULT Execute(uint commandId, UI_ExecutionVerb verb, ref PropertyKey key, ref PropVariant currentValue, IUISimplePropertySet commandExecutionProperties)
if ((commandId == (uint)RibbonMarkupCommands.cmdButtonNew) &&
(verb == UI_ExecutionVerb.Execute))
MessageBox.Show("new button pressed");
Update (18.11.2009): Handling ribbon events is now as simple as normal .NET events. Implementing IUICommandHandler by the user is no longer required.
private Ribbon _ribbon;
private RibbonButton _buttonNew;
_ribbon = new Ribbon();
_buttonNew = new RibbonButton(_ribbon, (uint)RibbonMarkupCommands.cmdButtonNew);
_buttonNew.OnExecute += new OnExecuteEventHandler(_buttonNew_OnExecute);
void _buttonNew_OnExecute(PropertyKeyRef key, PropVariantRef currentValue, IUISimplePropertySet commandExecutionProperties)
MessageBox.Show("new button pressed");
Naturally we added to the beginning of the file:
So there you have it, a WinForms application with a Ribbon Application Menu.
That’s it for now,