So let's see how to use the Ribbon class to add ribbon support to an empty WinForms application.
Step 0 – Download Windows Ribbon for WinForms
As I’ve mentioned in previous posts, you can download the code for my ribbon wrapper library along with numerous samples (currently one..) from windowsribbon.codeplex.com
Also, I remind you to download the helper library, Windows API Code Pack .
Update (18.11.2009): The project doesn’t depends anymore on Windows API Code Pack.
In this post I'll review how to create your first, ribbon-enabled WinForms application, the result is the sample application “01-AddingRibbonSupport”, included on the site.
Step 1 – Reference Windows Ribbon for WinForms
Create a new C# WinForms application and add a reference to our developed library, Ribbon.dll
Also, add to your main form (form1.cs) the following lines:
Step 2 – Add ribbon markup XML file
Add an empty file named RibbonMarkup.xml to the project
Set the file text to the following:
Right click on the editor where RibbonMarkup.xml is opened and click properties, now set the Schemas property to: C:\Program Files\Microsoft SDKs\Windows\v7.0\Bin\UICC.xsd
This will [visual] assist you in the future while editing the ribbon markup file (try Ctrl+Space on the xml editor to see the ribbon markup syntax).
Note: this is the moment where some of you will discover they didn’t install Windows 7 SDK, so go ahead and fix it, I'll wait.
Step 3 – Set UI compiler to compile markup during build
Step 3.1 – Set pre-build events
Go to: Project Properties -> Build Events -> Pre-build event command line
Add the following 3 lines:
"%PROGRAMFILES%\Microsoft SDKs\Windows\v7.0\Bin\UICC.exe" "$(ProjectDir)RibbonMarkup.xml" "$(ProjectDir)RibbonMarkup.bml" /res:"$(ProjectDir)RibbonMarkup.rc"
"%PROGRAMFILES%\Microsoft SDKs\Windows\v7.0\Bin\rc.exe" /v "$(ProjectDir)RibbonMarkup.rc"
cmd /c "("$(DevEnvDir)..\..\VC\bin\vcvars32.bat") && ("$(DevEnvDir)..\..\VC\bin\link.exe" /VERBOSE /NOENTRY /DLL /OUT:"$(ProjectDir)$(OutDir)$(TargetName).ribbon.dll" "$(ProjectDir)RibbonMarkup.res")"
The first line compiles the ribbon markup file to a binary compressed format, along with a small RC file that describes it.
The second line creates a native win32 resource file to be attached to the project native resources.
The third line creates a resource dll from the native win32 resource file.
Step 3.2 – Compile
Compile, in order to invoke the pre-build events.
Update (18.11.2009): Step 3.3 is no longer needed since the resource is loaded from the resource dll.
Step 3.3 – Add native resource Go to: Project Properties -> Application -> Resources -> Resource File
Set Resource file to point to:
When it says it can’t find the file, close the properties window anyway. It will save and find the file.
If you wish to be on the safe side, just set the Resource file to the full path of the file (which is dependent on your project location).
Step 4 – Implement IRibbonForm
Have your main form implement IRibbonForm interface, which is defined in Ribbon.dll, you can follow the following guidelines:
- The Ribbon framework needs the main form window handle for initialization, hence:
- The Ribbon framework will partly hide your form, unless you write some code that repositions your controls according to the ribbon current height. A simple way of doing this is adding a SplitContainer control to the main form and setting the following properties: (you should change them using the GUI properties, not by code):
Now, all you need to do is put your form controls inside panel2 of the SplitContainer and update panel1 height when the ribbon height changes (panel1 act as a placeholder for the ribbon). The SplitContainer will automatically reposition your controls accordingly. The actual update is done in the IRibbonForm implementation:
- The major part of the communication between the ribbon framework and your application is done by implementing the two following methods
, which we’ll initially give a default implementation:
Update (18.11.2009): These functions should not be implemented by the user anymore, since the Ribbon class now provides a general implementation, thus simplifying the use of the library.
Step 5 – Initialize Ribbon Framework on application load
To initialize and destroy the ribbon framework, handle both form’s Load and FormClosed events, respectively:
Enjoy your first Ribbon WinForms application
Note: If you run your application and don’t see the ribbon, try to enlarge the window size. The windows ribbon has a feature that if the window size is too small, it doesn’t show. Unfortunately, Visual Studio default form size is too small.
That’s it for now,