The easiest way to add ribbon support to an XLL+ project is to select ribbon support in the AppWizard when you first create the project. If you wish to add support later, or if you want to add a ribbon to a project created with older versions of XLL+, then follow the steps below.
In the steps below, the instructions are for an application named MyAddin
.
You should replace MyAddin
with the name of your add-in where appropriate.
In Visual Studio, add a new XML file to the project and save it as MyAddin.RibbonX
.
Replace the contents of the file with the XML below, and save the file.
<?xml version="1.0" encoding="UTF-8"?> <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"> <ribbon> <tabs> <!-- This tab element adds its child groups to the "Add-Ins" tab. --> <!-- To create a new tab element specify the id and label attributes, --> <!-- and remove the idMso attribute. --> <tab idMso="TabAddIns"> <!-- This group element creates a new region on the tab specified by its parent element. --> <group id="MyAddin_Group" label="My Group" getVisible="GetVisible"> <!-- This large button displays an image from the resources, whose ID is "LOGO", and a fixed label. --> <!-- When the button is pressed, the application class event handler function OnRibbonEvent() is called. --> <button id="MyAddin_PushButton" size="large" image="LOGO" label="My Button" onAction="OnActionButton" /> </group> </tab> </tabs> </ribbon> </customUI>
Next you need to embed the ribbon definition file as a resource, as follows:
Open the project's resource file, MyAddin.rc.
In Resource View, right-click MyAddin.rc and click Add resource....
Click on the Import... button.
In the file dialog, ensure that the Files of Type dropdown contains All Files (*.*) and select MyAddin.RibbonX
.
In the Custom Resource dialog, enter "XML"
as the resource type. Note that the quotes are required.
Press OK to add the ribbon to the resource file.
In Resource View select the new resource, which will be under the "XML" node, and will have a name like IDR_XML1
.
Press Alt+Enter to view the resource properties.
In the Properties Grid, change the ID to "RIBBONX"
. Once again, the quotes and the capitalization are required.
Image files should be in PNG format, and should usually have a transparent background.
Once you have created an image file, add it to the project and then follow the steps below to embed it as a resource.
Open the project's resource file, e.g. MyAddin.rc
.
In Resource View, right-click MyAddin.rc and click Add resource....
Click on the Import... button.
In the file dialog, ensure that the Files of Type dropdown contains All Files (*.*) and select the PNG file.
Under Visual Studio 2005, the Custom Resource dialog appears: enter RCDATA
as the resource type.
Note that there no quotes around RCDATA
.
Press OK to add the image to the resource file.
In Resource View select the new resource. Under Visual Studio 2005 the resource will will be under the RCDATA
node,
and will have a name like IDR_RCDATA1
.
Under later versions of Visual Studio, the resource will will be under the PNG
node
and will have a name like IDB_PNG1
.
Press Alt+Enter to view the resource properties.
In the Properties Grid, change the ID to the ID of the image, including quotes, e.g.: "LOGO"
. Note that the quotes are always required.
The actual ID you use should correspond to the image ID you have used for the image
attribute in the ribbon file.
In the application header file, MyAddin.h
, add the following line,
before the start of the class declaration.
#include <xlpribbon.h>
Within the class definition, in a public section, add the following method declaration:
virtual CXlOper OnRibbonEvent(const CRibbonEvtParams& e);
In the main source file, MyAddin.cpp
, add the following lines to InitInstance()
, after the call to
AddStaticFns()
:
// Select a ribbon implementation, and then inform // the framework that the add-in contains a ribbon SetRibbonImplementation(RibbonImplementationShared); SetHasRibbon(true);
Add an implementation of the ribbon event handler function, as follows:
CXlOper CMyAddinApp::OnRibbonEvent(const CRibbonEvtParams& e) { CXlOper xloResult = CXllApp::OnRibbonEvent(e); switch (e.GetCallback()) { case RIBBONCALLBACK_GETVISIBLE: if (e.GetId() == _T("MyAddin_Group")) xloResult = true; break; case RIBBONCALLBACK_ONACTION: if (e.GetId() == _T("MyAddin_PushButton")) XlMessageBox(_T("Hello from the ribbon!"), XlMessageBoxTypeInformation); break; } return xloResult; }
The final step to make the project function correctly in the development environment is to add a build event to the project:
In the Project Explorer, right-click the project node and select Properties.
In the Configuration combo-box, select All Configurations.
In the Platform combo-box, select All Platforms.
In the tree view on the left, select Configuration Properties/Build Events/Post-Build Event.
In the property list on the right, set Command Line to the following:
"$(Xlp80InstallDir7)bin\XlpRibbonReg.exe" -a "$(TargetPath)" -q true
Note the quote marks, which are essential. Under Visual Studio 2005, use Xlp80InstallDir7
in the path, as shown above.
Under Visual Studio 2008, use Xlp90InstallDir7
and under Visual Studio 2010, use Xlp100InstallDir7
.
In the property list, set Description to the following:
Registering XLL with Ribbon Manager...
In the property list, ensure that Excluded From Build is set to No
.