Windows Ribbon for WinForms, Part 19 – RecentItems

Windows Ribbon for WinForms library now supports working with recent items in the application menu.
The result of this post is a yet another sample, “16-RecentItems”, found on the project site.

What are recent items?
Recent items are items in a list which appears in the application menu. They doesn’t have to be file names and they doesn’t have to be recent, although it is recommended.

Every item has 3 properties:

• Label – Item name, usually file name without path
• Label Description – Item tooltip, usually full filename path
• Pinned – Boolean that indicates whether the recent item should not be removed from the list

More details can be found at Recent Items on MSDN.

Using RecentItems – Ribbon Markup
Commands section:

Views section:

Things to note:

• The “Recent Items” label can be changed to whatever you need (e.g. “Days of the week”).
• Setting EnablePinning attribute to false will hide the pins from the application menu.
• MaxCount attribute specify how many items to display on the application menu.

Using RecentItems – Code Behind
Initialization:

RibbonRecentItems is the helper class for working with the recent items feature. It has a property named RecentItems of type IList<RecentItemsPropertySet>. This property contains the list of the recent items. Note that it is the user responsibility for providing this list and update it when needed (add / remove items, change pinned state).

Responding to a click on an item:

I know, some explanations are in order.
The OnExecute event is called on two occasions:

1. When the user clicks on one of the items.
2. When the user changes the pinned status of several items and then closes the menu (either by selecting one of the items or by clicking outside the menu).

When the user clicks on an item, the currentValue argument contains the index of the selected item and commandExecutionProperties argument contains the properties of the selected item. The above code shows how to extract them.

When the user changes the pinned status of several items, the currentValue argument contains the new status of the items. It is the user responsibility to update the items in its own list. otherwise the user’s change won’t appear the next time he opens the menu.

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 18 – ContextPopup

Windows Ribbon for WinForms library now supports using a Context Popup.
The result of this post is a yet another sample, “15-ContextPopup”, found on the project site.

What is a Context Popup?
A context popup is a combination of a small toolbar (called MiniToolbar) and a context menu, which a ribbon enabled application can provide. This popup usually appears when right-clicking an application surface and it usually provide common operation relevant for the clicked surface.
Basically it’s just another way to get to your ribbon commands. In fact, since the MiniToolbar (the upper part of the context popup) can’t be access using the keyboard, Microsoft strongly recommends that every command should be also available using the standard ribbon interface.

More details can be found at Context Popup on MSDN.

Using ContextPopup – Ribbon Markup
Following is an example of defining a context popup. Only the Views section is presented since the Commands section is obvious. The result of this markup is shown in the image above.

Things to note:

1. In the ContextPopup.MiniToolbars element you can define a list of available mini toolbars (upper parts).
2. In the ContextPopup.ContextMenus element you can define a list of available context menus (lower parts).
3. The actual definition of the context popup resides in the ContextPopup.ContextMaps element, where you can define a list of context popups. For each context popup you need to specify its upper part and lower part.

Using ContextPopup – Code Behind
In order to show the predefined context popups I present here two ways: the recommended way and the convenient way.

The recommended way
Use the method, Ribbon.ShowContextPopup to show a given context popup in a certain location, usually as a response to right clicking:

Note that the ShowContextPopup gets the location in screen coordinates, so a transformation using the Control.PointToScreen method is required.

The convenient way
If you are used to program client applications in .NET you must be familiar with ContextMenuStrip class. Every WinForms control has a ContextMenuStrip property where you can attach an instance of a predefined ContextMenuStrip instance, thus letting the .NET framework handle the opening of the context menu for you. Unfortunately the ContextMenuStrip property works only with ContextMenuStrip instances (An IContextMenuStrip interface would be great..), so you can’t easily replace the .NET implementation of a context menu with our new ribbon based implementation.

Following is a hack you can use to achieve this. I’ve created a RibbonContextMenuStrip class that inherits from ContextMenuStrip and hacked my way into showing the ribbon context menu instead of the .NET context menu. The advantage is that you have an easier interface for working with the ribbon context menu:

As you can see from the code, it is shorter and use the standard .NET way for setting context menus on controls.

Let’s see the “magic” in action:

Note: The RibbonContextMenuStrip is NOT part of the Windows Ribbon for WinForms library. The code is available as part of the sample “15-ContextPopup”. It works but I don’t like it.

Ribbon Properties
This section has nothing to do with context popup.

The ribbon library now supports 3 general properties for the ribbon UI:

• Minimized - Specifies whether the ribbon is in a collapsed or expanded state.
  Property Identifier: UI_PKey_Minimized
• Viewable - Specifies whether the ribbon user interface (UI) is in a visible or hidden state.
  Property Identifier: UI_PKey_Viewable
• QuickAccessToolbarDock - Specifies whether the quick access toolbar is docked at the top or at the bottom.
  Property Identifier: UI_PKey_QuickAccessToolbarDock

Using these properties is as simple as:

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 17 – ContextualTabs

Windows Ribbon for WinForms library now supports Contextual Tabs.
The result of this post is a yet another sample, “14-ContextualTabs”, found on the project site.

What are contextual tabs?
Contextual tabs are additional tabs that appear when you enable their context.
For example, in word, when you select a table in your document, you get two additional tabs (Design and Layout) with commands relevant only to tables.

The basic working unit is a TabGroup, which is a group of contextual tabs with the same context.
A TabGroup has a property named ContextAvailable (Property Identifier: UI_PKEY_ContextAvailable) which can have the following values:

• Active – context is currently available and the tab group should be active (=“selected”)
• Available – context is currently available (tabs are not necessarily active).
• NotAvailable – context is currently not available.

More details on this subject can be found at Displaying Contextual Tabs on MSDN.

Using ContextualTabs – Ribbon Markup
Following is the views section for defining contextual tabs. The commands section is straightforward.

Here we define a single TabGroup for “Table Tools”, with two contextual tabs, “Design” and “Layout”.
Each tab has some buttons in it.
In addition we define in the main tab two buttons that we will use to set and unset the “Table Tools” context.

Using ContextualTabs – Code Behind
Following is an example of setting the context for a TabGroup thus making it visible.

Here we just register to the ribbon buttons execute events and set the context of the TabGroup accordingly. Of course in a real application you might use a more sophisticated logic for setting the context.

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 16 – ApplicationModes

Windows Ribbon for WinForms library now supports Application Modes.
The result of this post is a yet another sample, “13-ApplicationModes”, found on the project site.

What are application modes?
It is best to explain using examples. Applications some times have different “modes” in which they show different GUI, for example:

• Simple mode VS Advanced mode
• Regular editor mode VS Print mode

The ribbon framework support changing its GUI according to the current application mode. In order to use the ribbon application modes you need to:

• Set the available application modes for each ribbon item. This is done in design time.
• Set the current application mode. This is done in run time.

To summarize, application modes is a feature that allows the ribbon to change its GUI according to the current application context.

More details on this subject can be found at Reconfiguring the Ribbon with Application Modes on MSDN.

Using ApplicationModes extra remarks

• You can set up to 32 different application modes, each identified by a number between 0 and 31.
• Modes can coexist, meaning you can set both simple mode and advanced mode as active at the same time. Internally the current application modes are represented by a single 32bit variable (which represents a Boolean array of size 32), thus explaining why you can only have 32 modes.
• Mode 0 is the default mode. So if you don’t set the ApplicationModes attribute, 0 is the default.
• At least one mode should be set at all times. You can’t disable all the modes (the framework will just ignore your last set).

Using ApplicationModes – Ribbon Markup
Following is an example of the views section where you set the ApplicationModes attribute:

In this example we create a tab with 3 groups in it: Common, Simple and Advanced.
The common group should always appears so we set its ApplicationModes attribute to “0,1”
The simple group should only appear in simple mode (0). Similarly, the advanced group should only appear in advanced mode (1).
Note that the tab element should appear in both modes, so you must also set its ApplicationModes attribute to “0,1”.

ApplicationModes can be set on the following elements:

• Core tabs (as apposed to contextual tabs).
• Groups which are children of core tabs.
• Button, SplitButton and DropDownButton but only when those controls are in the application menu.

ApplicationModes – code behind
Following are two ribbon buttons, “simple” and “advanced”, each changes the current application mode:

The Ribbon.SetModes method is just a simple wrapper that converts a byte array to a compact 32bit integer and pass it to the relevant framework function:

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 15 – Use Ribbon as External DLL

Using Windows Ribbon for WinForms just got a lot easier.

Warning: Boring post. Talks about changes in the ribbon library and their reasons.

But first, let me start by asking for your forgiveness.
I’m trying to create a library which will be easy to use and so the last change to the library wasn’t backward compatible. Namely, classes names and interfaces have changed.
Rest assured that every single change I made is making the library a little more easier to use. However, for all those who have started using the library, I say: sorry. [This is what you get for using a project in BETA]

So, what have changed?

Classes names
I’ve added a “Ribbon” prefix to all the ribbon controls helper classes. This is to prevent collision with the standard WinForms controls, like Button, ComboBox, etc.

Yea, I know, this is why we have namespaces. However having a WinForms project with both a button and a ribbon button is not a rare case. When this happens the user can’t add “using RibbonLib.Controls;” so almost every other line is cluttered with “RibbonLib.Controls” prefix, for example:

Instead of:

IUICommandHandler Implementation
I’ve added a general implementation of IUICommandHandler (Execute and UpdateProperty functions) to the Ribbon class, so that these methods should not be implemented anymore by the user. This means the user doesn’t need to write anymore the following code in its Form class:

The new implementation, which resides in the Ribbon class just delegates the call to the correct ribbon control, according to the command ID:

The _mapRibbonControls is an internal dictionary that contains all the ribbon controls helper classes the user have created in the main form.

Note: I’ve made these functions virtual so that if some user wants direct access to the notifications from the ribbon framework he can still get them by deriving from the Ribbon class and overriding these methods.

Support for Ribbon External DLL
Now you can have your ribbon resource reside in an external dll instead of inside the application executable, as a native resource. This issue was a problem for developers who needed the native resource for other uses (like setting the application icon).

In fact, I’ve made this the default behavior of the ribbon. So now when you call the simplest form of Ribbon.InitFramework, the ribbon library tries to load the ribbon from your_app_name.ribbon.dll and only if it fails to find this file it will revert back to the previous behavior, that is, try to load ribbon from your executable native resource.

Of course you can provide your own dll name to load, or even load it yourself and pass the dll handle (=what returns from LoadLibrary) to the different overloads of Ribbon.InitFramework. This allows you to implement a custom ribbon loading mechanism which can be useful if you wish to load different ribbons on different scenarios, e.g. add localization support (different locale has different ribbon).

What this means for the user of the ribbon library is that he needs to add one more step to the pre-build event. This step will create the ribbon resource dll from the resource file created by previous steps.
So the pre-build events for projects that uses the ribbon library are now:

I know, this looks like a pile of junk, but actually what’s written is:

• UICC – please convert RibbonMarkup.xml to RibbonMarkup.rc
• rc – please convert RibbonMarkup.rc to RibbonMarkup.res
• link – please convert RibbonMarkup.res to YourAppName.ribbon.dll

I’ve updated all the ribbon library samples to use the ribbon resource dll.

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 14 – FontControl

Windows Ribbon for WinForms library now supports FontControl control.
The result of this post is a yet another sample, “12-FontControl”, found on the project site.

FontControl Control
FontControl is another special control provided by the Windows Ribbon Framework.
It allows you to choose font family, size, colors and related effects.
It has three types, each exposing a little more functionality then the other:

• Font Only
• Font With Color
• Rich Font

Check Font Control on MSDN for full details on the differences between the types.

FontControl Properties
Following is the list of properties which are unique for FontControl control. The rest of the properties have been reviewed in previous posts.

• FontProperties – This property is of type IPropertyStore and holds all the font specific properties, like Size, Bold, Underline, etc.
  In the FontControl helper class I use this property internally to access the other properties but do not expose it to the user, since it has no use other then being an access point to the other properties.
  Property Identifier: UI_PKEY_FontProperties
• ChangedProperties – This property contains all the recently changed properties.
  The FontControl doesn’t expose it but provides it as one of the parameters in the Execute / Preview / CancelPreview events. For example, if you click on the “Bold” button, the Execute event will be called and the this property will contain only the Bold property.
  Property Identifier: UI_PKEY_FontProperties_ChangedProperties
• Family – The selected font family name.
  Property Identifier: UI_PKEY_FontProperties_Family
• Size – The size of the font.
  Property Identifier: UI_PKEY_FontProperties_Size
• Bold – Flag that indicates whether bold is selected.
  Property Identifier: UI_PKEY_FontProperties_Bold
• Italic – Flag that indicates whether italic is selected.
  Property Identifier: UI_PKEY_FontProperties_Italic
• Underline – Flag that indicates whether underline is selected.
  Property Identifier: UI_PKEY_FontProperties_Underline
• Strikethrough – Flag that indicates whether strikethrough is selected (sometimes called Strikeout).
  Property Identifier: UI_PKEY_FontProperties_Strikethrough
• VerticalPositioning – Flag that indicates which one of the Subscript and Superscript buttons are selected, if any.
  Property Identifier: UI_PKEY_FontProperties_VerticalPositioning
• ForegroundColor – Contains the text color if ForegroundColorType is set to RGB. The FontControl helper class expose this property as a .NET Color  and handles internally the conversion to and from COLORREF structure.
  Property Identifier: UI_PKEY_FontProperties_ForegroundColor
• ForegroundColorType – The text color type. Valid values are RGB and Automatic.
  If RGB is selected, the user should get the color from the ForegroundColor property.
  If Automatic is selected the user should use SystemColors.WindowText.
  The FontControl helper class doesn’t expose the ForegroundColorType property. Instead it implements the color selection algorithm internally (i.e. return correct color according to the type property).
  Property Identifier: UI_PKEY_FontProperties_ForegroundColorType
• BackgroundColor – Contains the background color if BackgroundColorType is set to RGB. The FontControl helper class expose this property as a .NET Color  and handles internally the conversion to and from COLORREF structure. 
  Property Identifier: UI_PKEY_FontProperties_BackgroundColor
• BackgroundColorType – The background color type. Valid values are RGB and NoColor.
  If RGB is selected, the user should get the color from the BackgroundColor property.
  If NoColor is selected the user should use SystemColors.Window.
  The FontControl helper class doesn’t expose the ForegroundColorType property. Instead it implements the color selection algorithm internally (i.e. return correct color according to the type property).
  Property Identifier: UI_PKEY_FontProperties_BackgroundColorType
• DeltaSize – Indicated whether the “Grow Font” or “Shrink Font” buttons were pressed. This property is only available as part of the ChangedProperties property and is not exposed by the FontControl helper class.
  Property Identifier: UI_PKEY_FontProperties_DeltaSize

Using FontControl – Ribbon Markup
Commands and Views sections:

More details on FontControl attributes can be found on MSDN.

Using FontControl – Code Behind
The following code shows the basic steps of using a ribbon FontControl which stays in sync with the selected text in a standard .NET RichTextBox control.

• Initializing:

• Setting RichTextBox properties when FontControl has changed:

Note: RichTextBox doesn’t support Subscript and Superscript natively. What it does support is setting the character offset, so this is what I use to simulate the required behavior.

• Adding support for preview while changing font family and size:

Note: Only font family and font size should support preview since only they have attached combo boxes.

• Updating FontControl when text selection changes in RichTextBox:

Update (18.11.2009): The updated version of the Ribbon class provides an implementation for IUICommandHandler, so the user doesn't need to implement Execute and UpdateProperty methods anymore.

• Connect IUICommandHandler implementation with the helper class implementation:

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 13 – DropDownColorPicker

Windows Ribbon for WinForms library now supports DropDownColorPicker control.
The result of this post is a yet another sample, “11-DropDownColorPicker”, found on the project site.

DropDownColorPicker Control
The drop down color picker looks like this:

DropDownColorPicker Properties
Following is the list of properties which are unique for DropDownColorPicker control. The rest of the properties have been reviewed in previous posts.

• Color – The selected color.
  Property Identifier: UI_PKEY_Color
• ColorType – The type of selected color. Can be: NoColor, Automatic or RGB (meaning specific color).
  Property Identifier: UI_PKEY_ColorType
• AutomaticColorLabel – Defines the label for the “Automatic” color button.
  Property Identifier: UI_PKEY_AutomaticColorLabel
• MoreColorsLabel – Defines the label for the “More colors...” button.
  Property Identifier: UI_PKEY_MoreColorsLabel
• NoColorLabel – Defines the label for the “No color” button.
  Property Identifier: UI_PKEY_NoColorLabel
• RecentColorsCategoryLabel – Defines the label for the “Recent colors” category.
  Property Identifier: UI_PKEY_RecentColorsCategoryLabel
• StandardColorsCategoryLabel – Defines the label for the “Standard colors” category.
  Property Identifier: UI_PKEY_StandardColorsCategoryLabel
• ThemeColorsCategoryLabel – Defines the label for the “Theme colors” category.
  Property Identifier: UI_PKEY_ThemeColorsCategoryLabel

Note: The different labels in the drop down color picker allows you to localize the control.

For more details on DropDownColorPicker control, check out Drop-Down Color Picker on MSDN.

Using DropDownColorPicker – Ribbon Markup
Commands and Views sections:

Using DropDownColorPicker – Code Behind
Initializing:

Update (18.11.2009): The updated version of the Ribbon class provides an implementation for IUICommandHandler, so the user doesn't need to implement Execute and UpdateProperty methods anymore.

Connect IUICommandHandler implementation with the helper classes implementations:

Respond to selected color event:

Windows Ribbon for WinForms Library Update
Warning: Internal details ahead. Not related to DropDownColorPicker in any way.

Microsoft recently released PreviewRibbon. It is a sample application that helps you design a ribbon enabled application by giving you a preview of how your markup will look. The application is built as a command line tool that accepts a ribbon markup xml file and displays the result. It is written in C# using WinForms and thus can be used as a sample of how to use the ribbon in a .NET application, which is similar to what I’ve been trying to do.

This is the place to mention RibbonExplorer by Alon Fliess, which is another great tool for previewing a ribbon and manipulating its properties, written in C++/ATL.

Since both Windows Ribbon for WinForms and PreviewRibbon projects use the ribbon thru COM Interop and written in C#, they solve similar problems. So I've decided to review the PreviewRibbon code to learn how they solved some of the issues I’ve faced.

The end result of the review is as follow:

• I’ve created my own version of PropertyKey class, which is basically a copy of the one PreviewRibbon use, only I’ve separated the PropertyKey definition from ribbon related code.
• I've created my own version of PropVariant class.
  Decimal value handling is taken from PreviewRibbon (well done!).
  Vectors handling is taken from Windows API Code Pack.
• As a small bonus, since now I have my own versions of PropertyKey and PropVariant, the project doesn’t depends anymore on Windows API Code Pack.
• Changed the naming convention of the ribbon enums (removed UI_ prefix) and ribbon property keys (removed UI_PKEY_ prefix).

That’s it for now,
Arik Poznanski.

Windows Ribbon for WinForms, Part 12 – CheckBox and ToggleButton

CheckBox and ToggleButton
In short, I’ve added support for CheckBox and ToggleButton ribbon controls.
A new sample, named “10-CheckBox” has been added to the project site. The result look like this:

Using CheckBox and ToggleButton – Ribbon Markup
Commands and Views sections:

Using CheckBox and ToggleButton – Code Behind
Initializing:

Connect IUICommandHandler implementation with the helper classes implementations: [If this the first time you see this, you should really check the previous posts..]

Update (18.11.2009): The updated version of the Ribbon class provides an implementation for IUICommandHandler, so the user doesn't need to implement Execute and UpdateProperty methods anymore.

Get / Set CheckBox status:

Windows Ribbon for WinForms Library Internal Design Issues
Warning: the rest of this post is extremely boring. It discusses internal details of my ribbon library implementation. This doesn’t change anything for the user of the library. Also, it has nothing to do with the checkbox feature.

So now that I’m the only one left, I can discuss some internal details of the library. I’ve just made a major refactoring of the ribbon library.

The ribbon library is composed of:

• Windows Ribbon Framework API wrappers
• Main ribbon class
• Helper classes for different ribbon controls, such as Button, ComboBox, DropDownGallery etc.

In the old version of the RibbonLib, the controls helper classes had lots of duplicated code. For instance, each control that had images attached to it (LargeImage, SmallImage, … properties) needed to handle those images in the same way (manipulating internal variables, notifying the parent ribbon that an image has invalidated etc.). Now, I don’t know about you, but whenever I copy-paste code I always get this strange feeling that something is wrong. So after several sample projects I couldn’t take it anymore and decided to redesign this section.

What I’ve done was encapsulate common code in classes, so they can be reused in several controls without duplicating code.

So now every ribbon control is composed from several properties providers (like ImagePropertiesProvider and TooltipPropertiesProvider) and events providers (like ExeciteEventsProvider and PreviewEventsProvider).

Note: The following sentence is hard, but there is an example right after, so be strong.

Each provider component has its own interface which the using-control also implements by delegating the execution to the component.

For example, I have an ImagePropertiesProvider class that implements the interface IImagePropertiesProvider, which exposes 4 image properties (LargeImage, SmallImage, ..).
In my Button helper class I create a member variable of type ImagePropertiesProvider and make the Button class also implement IImagePropertiesProvider by calling the corresponding methods on the member variable.

This is one of those cases where multiple inheritance was really missing. As a substitute, what I did was used multiple inheritance of interfaces, aggregation and delegation pattern. So the controls still has some duplicated code (the delegation code) but this code is really simple and has no logic in it.

Also, each ribbon control has an Execute and UpdateProperty methods it needs to implement according to the properties and events it exposes. So I’ve made a general implementation which resided in the BaseRibbonControl class that search the implementation of a property or event inside one of the registered providers, thus simplifying this code section in every control (now it doesn’t exists, the simplest way I know).

The results of all these changes are:

• Shorter code with less duplications.
• Developing of new helper classes is extremely simple.
• Cool class diagrams..

Properties Providers Class Diagram

Events Providers Class Diagram

Ribbon Controls Class Diagram

That’s it for now,
Arik Poznanski.