Displaying the Ribbon

The Windows Ribbon framework exposes a set of properties that allow an application to specify how the Ribbon UI is displayed at run time.

• Introduction
• Minimize the Ribbon
• Hide the Ribbon
• Example
• Related topics

Introduction

To maximize the area available for the document space (or view port) of a Ribbon framework application, an application can specify whether the ribbon UI is visible or hidden and, when visible, whether the ribbon is in an expanded or collapsed state.

The framework property keys listed in the following table are used to explicitly set the display characteristics of the ribbon UI in a Ribbon framework application. These properties have no effect on the display of the Context Popup control.

Display State	Ribbon Property Key
Expanded or collapsed	UI_PKEY_Minimized
Visible or hidden	UI_PKEY_Viewable

 

Minimize the Ribbon

A Ribbon framework application can dynamically set the minimized state of the ribbon command bar by setting the value of the UI_PKEY_Minimized property key to true or false.

Display State	Property Key Value
Expanded	false
Collapsed	true

 

When the ribbon UI is in a minimized state, the ribbon Tab row remains visible and fully functional.

The following screen shot shows the ribbon in the minimized state.

Note

The Ribbon framework exposes this functionality to the end user through the "Minimize the Ribbon" selection of the ribbon context menu.

 

Hide the Ribbon

A Ribbon framework application can dynamically set the viewable state of the ribbon command bar by setting the value of the UI_PKEY_Viewable property key to true or false.

Display State	Property Key Value
Visible	false
Hidden	true

 

In contrast to the UI_PKEY_Minimized property, setting UI_PKEY_Viewable to false renders the ribbon UI invisible and completely unusable to an end user.

The following screen shot shows the ribbon in the hidden state.

Example

The following example demonstrates how to set the state of the ribbon UI at run time.

In this case, the IUICommandHandler::Execute function is used to expand or collapse the ribbon UI based on the toggle state of a Toggle Button.

//
//  FUNCTION: Execute()
//
//  PURPOSE: Called by the Ribbon framework when a Command is executed 
//           by the user. 
//           This example demonstrates a handler for a Toggle Button
//           that sets the minimized state of the ribbon UI.
//
//  NOTES: g_pFramework is a global pointer to an IUIFramework object 
//         that is assigned when the Ribbon framework is initialized.
//
//         g_pRibbon is a global pointer to the IUIRibbon object
//         that is assigned when the Ribbon framework is initialized.
//
STDMETHODIMP CCommandHandler::Execute(
    UINT nCmdID,
    UI_EXECUTIONVERB verb,
    __in_opt const PROPERTYKEY* key,
    __in_opt const PROPVARIANT* ppropvarValue,
    __in_opt IUISimplePropertySet* pCommandExecutionProperties)
{
    HRESULT hr = E_FAIL;

    if (verb == UI_EXECUTIONVERB_EXECUTE)
    {
        switch (nCmdID)
        {
            // Minimize ribbon Command handler.
            case IDR_CMD_MINIMIZE:
                if (g_pFramework)
                {
                    IPropertyStore *pPropertyStore = NULL;
                    hr = g_pRibbon->QueryInterface(__uuidof(IPropertyStore), 
                                                   (void**)&pPropertyStore);
                    if (SUCCEEDED(hr))
                    {
                        if (ppropvarValue != NULL)
                        {
                            // Is the ToggleButton state on or off?
                            BOOL fToggled;
                            hr = UIPropertyToBoolean(*key, *ppropvarValue, &fToggled);

                            if (SUCCEEDED(hr))
                            {
                                // Set the ribbon display state based on the toggle state.
                                PROPVARIANT propvar;
                                PropVariantInit(&propvar);
                                UIInitPropertyFromBoolean(UI_PKEY_Minimized, 
                                                          fToggled, 
                                                          &propvar);
                                hr = pPropertyStore->SetValue(UI_PKEY_Minimized, 
                                                              propvar);
                                pPropertyStore->Commit();
                            }
                            pPropertyStore->Release();
                        }
                    }
                }
                break;
        }
    }
    return hr;
}

Related topics

Ribbon Properties