Migration from the Classic Ribbon to the New Ribbon

November 21 2019

We are pleased to announce the release of the New Office 365-based Ribbon, with ComponentOne 2019 v3. It has now moved from the beta version to the stable release version.

New Features of the Ribbon Control for WinForms

The Simplified Ribbon view that is introduced with the concept of displaying the main features but ensuring that they take up less vertical space.

The ribbon item images are now added to the RibbonItems, using IconSet property as follows:

this.FormatPainterButton.IconSet.Add(new C1.Framework.C1BitmapIcon("FormatPainterButton", new System.Drawing.Size(16, 16), System.Drawing.Color.Transparent, ((System.Drawing.Image)(resources.GetObject("FormatPainterButton.SmallImage")))));

The Gallery in the new Ribbon supports grouping and filtering of items, using AllowGroupFiltering property.
You can scroll through the tabs, in case the tabs are not completely displayed on the Ribbon.
The new Ribbon has many Office2016 themes and a big set of embedded images for dark and light themes.
BackStageView is a new concept related to linking a separate user-control with the Ribbon. This contains all the functionalities related to the tabs in the File menu.

Migration from the Classic Ribbon to the New Ribbon

Your old applications with Classic C1Ribbon can be converted to use the New Ribbon.

Why do we need this migration? Using the new Ribbon with your application simplifies the ribbon and makes it stand at par with the latest Microsoft Office tools. Note that for an existing application, this can be carried out easily without having to create a new project from scratch. Your application gets the latest ribbon with this migration!

Let's now see how this can be carried out with an existing application using Classic Ribbon.

Steps to Migrate the Classic Ribbon to the New Ribbon

Step 1. Create a copy of your original project

We will use a WordPad based application using the classic C1Ribbon. Ensure that you make a reserve copy of the same. It might be needed during conversion, if anything goes wrong.

The Ribbon with this project looks like the image below.

Migration from the Classic Ribbon to the New Ribbon

Step 2. Update the project

The New Ribbon is built for .Net 4.5.2. Thus, the project must have .NET 4.5.2 or higher target version.
Remove C1.Win.C1Ribbon.4 from project references and add reference to C1.Win.Ribbon.4.5.2 assembly instead. Likewise, remove all the other related assemblies and add them corresponding to the 4.5.2 version of the dlls.
Open the licenses.licx file in your project. You will need to replace all lines which reference C1.Win.C1Ribbon.4 For example, if you have these 2 lines:
```
C1.Win.C1Ribbon.C1Ribbon, C1.Win.C1Ribbon.4
C1.Win.C1Ribbon.C1StatusBar, C1.Win.C1Ribbon.4
```
You should replace them with these:
```
C1.Win.Ribbon.C1Ribbon, C1.Win.Ribbon.4.5.2
C1.Win.C1Ribbon.C1StatusBar, C1.Win.Ribbon.4.5.2
```
Likewise, do it for the other related licenses.licx entries, if any.
If you build the project now, you will see a lot of compilation errors about missing C1.Win.C1Ribbon namespace, etc. You should now replace C1.Win.C1Ribbon namespace with C1.Win.Ribbon in your entire application.

Step 3. Handle API changes

If you build the application now, you will see several errors, pointing to code lines with obsolete API. These errors occur due to the changed API and need to be handled manually.

RibbonEventHandler has been removed. Type of C1Ribbon.Ribbon has even been changed to EventHandler.

To fix this, change subscription on RibbonEvent from:

this.c1Ribbon1.RibbonEvent += new RibbnEventHandler(c1Ribbon1_RibbonEvent);

To this:

this.c1Ribbon.RibbonEvent += c1Ribbon1_RibbonEvent;

Now, AppMenuAppearance enum has only two members: Default and Compact. C1BackstageView exists as a separate component in the API. This needs to be configured to the Ribbon and contains various tabs (from BackstageViewTab class).

Existing application cannot set it up via AppMenuAppearance enumeration member. ApplicationMenu related code from the application must be removed to add C1BackStageView related code and some existing code may also need alteration, accordingly. Note that C1BackStageView has no property like BottomPanelItems.

Create a UserControl that will be added to the BackstageViewTab as a control, after defining the main C1BackstageView instance as its Owner.

Refer the following documentation link to understand how to configure BackStage View by code.
As Visual Styles have been removed, RibbonForm does not have VisualStyle or VisualStyleHolder properties or ResetVisualStyle method. Thus, the related code lines must be removed.
For adding images to Ribbon items, IconSet property is used now. IconSet property is used with an aim to add multiple images corresponding to an item, based on the DPI settings and different views.

To allow easy migration of the ribbon, users can use the SmallImage/LargeImage properties directly. During design time, users can open the form designer in Visual Studio to observe that the ribbon converts its old images from SmallImage/LargeImage to the IconSet property automatically. During runtime, users can use SmallImage/LargeImage without having to fix the old code to add images.

Note: New Ribbon has an updated set of embedded images. To use these images, you can replace images for individual items using the smart designer.

Migration from the Classic Ribbon to the New Ribbon

It is recommended to replace the old images from embedded preset with new ones for better presentation. Also, the Ribbon automatically shows large or small embedded images, as per the situation.