XLL+ Class Library (7.0)

Adding ribbon support to a project

AppWizard

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.

Create a Ribbon file

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.

CopyXML
<?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:

  1. Open the project's resource file, MyAddin.rc.

  2. In Resource View, right-click MyAddin.rc and click Add resource....

  3. Click on the Import... button.

  4. In the file dialog, ensure that the Files of Type dropdown contains All Files (*.*) and select MyAddin.RibbonX.

  5. 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.

  6. 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.

  7. In the Properties Grid, change the ID to "RIBBONX". Once again, the quotes and the capitalization are required.

Adding an image

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.

  1. Open the project's resource file, e.g. MyAddin.rc.

  2. In Resource View, right-click MyAddin.rc and click Add resource....

  3. Click on the Import... button.

  4. In the file dialog, ensure that the Files of Type dropdown contains All Files (*.*) and select the PNG file.

  5. 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.

  6. 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.

  7. 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.

Add code to the application header file

In the application header file, MyAddin.h, add the following line, before the start of the class declaration.

CopyC++
#include <xlpribbon.h>

Within the class definition, in a public section, add the following method declaration:

CopyC++
virtual CXlOper OnRibbonEvent(const CRibbonEvtParams& e);

Add code to the main source file

In the main source file, MyAddin.cpp, add the following lines to InitInstance(), after the call to AddStaticFns():

CopyC++
// 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:

CopyC++
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;
}

Registering an add-in with the XLL+ Ribbon Manager

The final step to make the project function correctly in the development environment is to add a build event to the project:

  1. In the Project Explorer, right-click the project node and select Properties.

  2. In the Configuration combo-box, select All Configurations.

  3. In the Platform combo-box, select All Platforms.

  4. In the tree view on the left, select Configuration Properties/Build Events/Post-Build Event.

  5. 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.

  6. In the property list, set Description to the following:

    Registering XLL with Ribbon Manager...

  7. In the property list, ensure that Excluded From Build is set to No.

See Also

Ribbon Reference | Ribbon Manager Configuration Utility