Walkthrough: Creating a New Ribbon Application By Using MFC

  • Article

In this walkthrough, you will use the MFC Application Wizard to create an application that has a default ribbon. You will then expand the ribbon by adding a Custom ribbon category with a Favorites ribbon panel and add to it some frequently used commands.

Prerequisites

To complete this walkthrough, you must install the Visual C++ 2008 Feature Pack or install Visual Studio 2008 Service Pack 1.

This walkthrough assumes that you have set up Visual Studio to use General Development Settings. If you are using a different development setting, some Visual Studio windows that we use in this walkthrough might not be displayed by default.

To create a new MFC application that has a ribbon

  1. Use the MFC Application Wizard to create an MFC application that has a default ribbon. To run the wizard, from the File menu select New, and then select Project. The New Project dialog box will be displayed.

  2. In the New Project dialog box, expand the Visual C++ node in the Project types pane and select MFC. Then, in the Templates pane, select MFC Application. Type a name for the project, such as MFCRibbonApp and click OK. The MFC Application Wizard will be displayed.

  3. In the MFC Application Wizard dialog box, click Next. The Application Type pane will be displayed.

  4. In the Application Type pane, under Visual style and colors, select Office 2007 (Blue theme). Leave the other settings as they are. Click Next to display the Compound Document Support pane.

  5. We will not add compound document support. Therefore, make sure that None is selected. Click Next to display the Document Template Strings pane.

  6. In the Document Template Strings pane, decide on a file name extension for the documents that this application will create, such as mfcrbnapp, and type it in the File extension field. Click Next to display the Database Support pane.

  7. We will not add database support to this application. Therefore, make sure that None is selected. Click Next to display the User Interface Features pane.

  8. In the User Interface Features pane, make sure that the Use a ribbon option is selected. Click Next to display the Advanced Features pane.

  9. By default, the MFC Application Wizard adds support for several docking panes. Because the purpose of this walkthrough is to learn about the ribbon, we will remove these options from our application. In the Advanced frame panes pane, clear all options. Click Next to display the Generated Classes pane.

  10. In the Generated Classes pane, click Finish to create your new MFC application.

  11. Verify that the application was created successfully by building and running it. To build the application, from the Build menu select Build Solution. If the application builds successfully, run the application by selecting Start Debugging from the Debug menu.

    The wizard automatically creates a ribbon with one ribbon category that is named Home. This ribbon contains three ribbon panels that are named Clipboard, View, and Window.

To add a ribbon category to the ribbon

  1. The existing ribbon that the project created can be found in the MainFrm.h header. This header contains the following line of code:

    CMFCRibbonBar m_wndRibbonBar;

    To add a category to the ribbon, call the CMFCRibbonBar::AddCategory method. This method has three required parameters. The first parameter is the name of the category. This is the value that will appear in the tab for the category in the ribbon. To make your application easier to localize, add this value to the String Table in the applications resources.

    To do this, click Resource View, expand the MFCRibbonApp and MFCRibbonApp.rc nodes, and then expand the String Table node. If the Resource View tab is not visible, open it by clicking the View menu, then clicking Other Windows, and finally selecting Resource View. Next, double-click String Table. In the window that appears, right-click anywhere and select New String. The system now creates a new entry that has a value that resembles IDS_STRINGnnn. The category we are creating will be labeled Custom, so rename the string to IDS_RIBBON_CUSTOM by clicking in the ID field. Next, click in the Caption field and enter Custom.

    The next two parameters to the CMFCRibbonBar::AddCategory method are the bitmaps that are used as icons for the ribbon elements. Creating custom bitmaps is beyond the scope of this walkthrough. Therefore, we will reuse the bitmaps that were created by the wizard. The second parameter is the resource ID for the small bitmaps that appear on the ribbon. Small bitmaps are 16 pixels by 16 pixels. For these bitmaps, we will select the bitmaps accessed by the IDB_FILESMALL resource ID. The third parameter is the resource ID for the large bitmaps that appear on the ribbon. Large bitmaps are 32 pixels by 32 pixels. For these bitmaps, we will select the bitmaps accessed by the IDB_FILELARGE resource ID.

  2. Open the MainFrm.cpp file and find the CMainFrame::OnCreate method. You will notice these two lines of code:

    m_wndRibbonBar.Create(this);
InitializeRibbon();

    The CMFCRibbonBar::Create method creates the underlying Windows controls for the ribbon, and you can customize the ribbon inside the CMainFrame::InitializeRibbon method.

  3. Navigate to the bottom of the CMainFrame::InitializeRibbon method. To create the ribbon category, add this code:

    // Add "Custom" category:
strTemp.LoadString(IDS_RIBBON_CUSTOM);
CMFCRibbonCategory* pCategoryCustom =
    m_wndRibbonBar.AddCategory(strTemp, IDB_FILESMALL, IDB_FILELARGE);

  4. Verify that the ribbon category was created successfully by building and running the application. To build the application, from the Build menu, select Build Solution. If the application builds successfully, run the application by selecting Start Debugging from the Debug menu. You should now see a Custom tab in the ribbon.

To add a ribbon panel to the ribbon category

  1. You can group items that are logically related to each other by putting them inside a ribbon panel. For example, on the Home tab of this application, the Cut, Copy, and Paste commands are all located in the Clipboard panel.

    To add a ribbon panel to the Custom category, call the CMFCRibbonCategory::AddPanel method.

    This method takes one required parameter, which is the name of the panel. Add this value to the String Table to make your application easier to localize. To do this, click Resource View, expand the MFCRibbonApp and MFCRibbonApp.rc nodes, and then expand the String Table node. Next, double-click String Table. In the window that appears, right-click anywhere and select New String. The system now creates a new entry that has a value that resembles IDS_STRINGnnn. We label the panel that we are creating Favorites, so rename the string to IDS_RIBBON_FAVORITES by clicking the ID field. Next, click in the Caption field and type Favorites.

    You can also provide the resource ID of an icon to the AddPanel method. This icon is displayed if the ribbon panel is added to the Quick Access Toolbar, but it is not actually displayed on the ribbon panel itself. The wizard has already created an instance of a CMFCToolBarImages Class for us that is named m_PanelImages. We will use one of the icons in this bitmap for our code. You can extract the image by calling the CMFCToolBarImages::ExtractIcon method.

  2. To add the Favorites ribbon category to the panel, add the following code underneath the code you added previously to CMainFrame::InitializeRibbon:

    // Create "Favorites" panel:
strTemp.LoadString(IDS_RIBBON_FAVORITES);
CMFCRibbonPanel* pPanelFavorites =
    pCategoryCustom->AddPanel(strTemp, m_PanelImages.ExtractIcon(15));

  3. Verify that the ribbon panel was created successfully by building and running the application. To build the application, from the Build menu, select Build Solution. If the application builds successfully, run the application by selecting Start Debugging from the Debug menu. You should now see a Favorites panel on the Custom tab in the ribbon.

To add elements to the ribbon panels

  1. To add elements to the panel that you created in the previous procedure, call the CMFCRibbonPanel::Add method. This method takes an instance of CMFCRibbonBaseElement Class as a parameter. CMFCRibbonBaseElement is the base class for all the elements that can be added to a panel, such as buttons, check boxes, and combo boxes.

  2. First, we add a Print button. The Print button will have a submenu that contains a Quick Print command (which prints by using the default printer). Both of these commands are already defined for this application because they are located in the application menu.

    To create the Quick Print button, add the following code underneath the code that you added previously to CMainFrame::InitializeRibbon:

    // Create "Quick Print" button:
strTemp.LoadString(IDS_RIBBON_PRINT_QUICK);
CMFCRibbonButton* pBtnFavPrintQuick =
    new CMFCRibbonButton(ID_FILE_PRINT_DIRECT, strTemp, 7);

    The IDS_RIBBON_PRINT_QUICK string is already defined in the String Table, as is the ID_FILE_PRINT_DIRECT command. The third parameter to the CMFCRibbonButton constructor is the small icon that is displayed next to the command. In this case, the Quick Print icon is the seventh bitmap in the IDB_FILESMALL resource ID.

    Next, add the following code to create a Print button. We use the CMFCRibbonButton::AddSubItem method to add the Quick Print button as a subitem of the Print button:

    // Create "Print" button with "Quick Print" as subitem:
strTemp.LoadString(IDS_RIBBON_PRINT);
CMFCRibbonButton* pBtnFavPrint =
    new CMFCRibbonButton(ID_FILE_PRINT, strTemp, 6);
pBtnFavPrint->AddSubItem(pBtnFavPrintQuick);

    The IDS_RIBBON_PRINT string is already defined in the String Table, as is the ID_FILE_PRINT command. The third parameter to the constructor is the small icon that is displayed next to the command. In this case, the Print icon is the sixth bitmap in the IDB_FILESMALL resource ID.

    Next, add the following code to add the Print button to the Favorites panel:

    // Add "Print" button to "Favorites" panel:
pPanelFavorites->Add(pBtnFavPrint);

  3. The second item we will add to the Favorites panel is a combo box. To keep this walkthrough simple, we will not associate the items in the combo box with a command. Rather, we will just demonstrate how to add a combo box to the ribbon.

    The CMFCRibbonComboBox constructor takes five parameters. The first parameter is the command ID for the action that is executed when a user selects an item in the combo box. The second parameter specifies whether the items in the combo box are editable. In this application, we specify FALSE. The third parameter is the width of the combo box. We specify -1, so that the combo box uses the default width of 120 pixels. The fourth parameter is the label for the combo box. In this application, we will not provide a label. The final parameter is the image to display next to the combo box. In this application, we will not provide an image. To create the combo box, type this code underneath the code you added previously to CMainFrame::InitializeRibbon:

    // Create a simple combo box that has two entries:
CMFCRibbonComboBox *pComboSimple =
    new CMFCRibbonComboBox(-1, FALSE, -1, 0, -1);

    Next, we will add two values to the combo box. For simplicity, we will label these values "Hi!" and "Hello!":

    // Add two items to the combo box and select the first item in the list:
pComboSimple->AddItem(_T("Hi!"));
pComboSimple->AddItem(_T("Hello!"));
pComboSimple->SelectItem(0);

    Now we will add the combo box to the panel by calling CMFCRibbonPanel::Add:

    // Add combo button to "Favorites" panel:
pPanelFavorites->Add(pComboSimple);

  4. Verify that the button and combo box were added to the ribbon panel by building and running the application. To build the application, from the Build menu, select Build Solution. If the application builds successfully, run the application by selecting Start Debugging from the Debug menu. You should now see the Print button and the combo box in the Favorites panel on the Custom tab in the ribbon.

Next Steps

Try adding several different ribbon elements to the Favorites panel, such as a CMFCRibbonCheckBox or a CMFCLinkCtrl.

For additional walkthroughs about the Visual C++ 2008 Feature Pack, see Walkthroughs (MFC Feature Pack).

For complete samples that cover many aspects of the Visual C++ 2008 Feature Pack, see Samples (MFC Feature Pack).

See Also

Other Resources

Walkthroughs (MFC Feature Pack)

Samples (MFC Feature Pack)