Export (0) Print
Expand All
1 out of 1 rated this helpful - Rate this topic

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

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 StateRibbon 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
Expandedfalse
Collapsedtrue

 

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.

Screen shot showing the ribbon UI minimized.

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
Visiblefalse
Hiddentrue

 

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.

Screen shot showing the ribbon UI hidden.

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

 

 

Did you find this helpful?
(1500 characters remaining)
Thank you for your feedback

Community Additions

ADD
Show:
© 2014 Microsoft. All rights reserved.