Context Popup

A Context Popup is the principal control in the ContextPopup View of the Windows Ribbon framework. It is a rich context menu system that is only exposed by the framework as an extension to a Ribbon implementation—the framework does not expose the Context Popup as an independent control.

• Components of the Context Popup
• Implement the Context Popup
  • Markup
  • Code
• Context Popup Properties
• Related topics

Components of the Context Popup

The Context Popup is a logical container for the Context Menu and Mini-Toolbar sub-controls that are exposed through the ContextMenu and MiniToolbar markup elements, respectively:

• The ContextMenu exposes a menu of Commands and galleries.
• The MiniToolbar exposes a floating toolbar of various Commands, galleries, and complex controls such as the Font Control and the Combo Box.

Each sub-control can appear at most once in a Context Popup.

The following screen shot illustrates the Context Popup and its constituent sub-controls.

The Context Popup is purely conceptual and does not expose any UI functionality itself, such as positioning or sizing.

Implement the Context Popup

In similar fashion to other Windows Ribbon framework controls, the Context Popup is implemented through a markup component that specifies its presentation details and a code component that governs its functionality.

The following table lists the controls that are supported by each Context Popup sub-control.

Markup

Each Context Popup sub-control must be declared individually in markup.

Mini-Toolbar

When adding controls to a Context Popup Mini-Toolbar, the following two recommendations should be considered:

• Controls should be highly recognizable and provide obvious functionality. Familiarity is key, as labels and tooltips are not exposed for Mini-Toolbar controls.
• Each Command exposed by a control should be presented elsewhere in the ribbon UI. The Mini-Toolbar does not support keyboard navigation.

The following example demonstrates the basic markup for a MiniToolbar element that contains three Button controls.

<MiniToolbar Name="MiniToolbar">
  <MenuGroup>
    <Button CommandName="cmdButton1" />
    <Button CommandName="cmdButton2" />
    <Button CommandName="cmdButton3" />
  </MenuGroup>
</MiniToolbar>

Context Menu

The following example demonstrates the basic markup for a ContextMenu element that contains three Button controls.

<ContextMenu Name="ContextMenu">
  <MenuGroup>
    <Button CommandName="cmdCut" />
    <Button CommandName="cmdCopy" />
    <Button CommandName="cmdPaste" />
  </MenuGroup>
</ContextMenu>

Although a Context Popup can contain at most one of each sub-control, multiple ContextMenu and MiniToolbar element declarations in the Ribbon markup are valid. This allows an application to support various combinations of Context Menu and Mini-Toolbar controls, based on criteria defined by the application, such as workspace context.

For more information, see the ContextMap element.

The following example demonstrates the basic markup for the ContextPopup element.

<ContextPopup>
  <ContextPopup.MiniToolbars>
    <MiniToolbar Name="MiniToolbar">
      <MenuGroup>
        <Button CommandName="cmdButton1" />
        <Button CommandName="cmdButton2" />
        <Button CommandName="cmdButton3" />
      </MenuGroup>
    </MiniToolbar>
  </ContextPopup.MiniToolbars>
  <ContextPopup.ContextMenus>
    <ContextMenu Name="ContextMenu">
      <MenuGroup>
        <Button CommandName="cmdCut" />
        <Button CommandName="cmdCopy" />
        <Button CommandName="cmdPaste" />
      </MenuGroup>
    </ContextMenu>
  </ContextPopup.ContextMenus>
  <ContextPopup.ContextMaps>
    <ContextMap CommandName="cmdContextMap" ContextMenu="ContextMenu" MiniToolbar="MiniToolbar"/>
  </ContextPopup.ContextMaps>
</ContextPopup>

Code

To invoke a Context Popup, the IUIContextualUI::ShowAtLocation method is called when the top-level window of the Ribbon application receives a WM_CONTEXTMENU notification.

This example demonstrates how to handle the WM_CONTEXTMENU notification in the WndProc() method of the Ribbon application.

case WM_CONTEXTMENU:
  POINT pt;
  POINTSTOPOINT(pt, lParam);

  // ShowContextualUI method defined by the application.
  ShowContextualUI (pt, hWnd);
  break;

The following example demonstrates how a Ribbon application can show the Context Popup at a specific screen location using the IUIContextualUI::ShowAtLocation method.

GetCurrentContext() has a value of cmdContextMap as defined in the preceding markup example.

g_pApplication is a reference to the IUIFramework interface.

HRESULT ShowContextualUI(POINT& ptLocation, HWND hWnd)
{
  GetDisplayLocation(ptLocation, hWnd);

  HRESULT hr = E_FAIL;

  IUIContextualUI* pContextualUI = NULL;
 
  if (SUCCEEDED(g_pFramework->GetView(
                                g_pApplication->GetCurrentContext(), 
                                IID_PPV_ARGS(&pContextualUI))))
  {
    hr = pContextualUI->ShowAtLocation(ptLocation.x, ptLocation.y);
    pContextualUI->Release();
  }

  return hr;
}

The reference to IUIContextualUI can be released before the Context Popup is dismissed, as shown in the preceding example. However, the reference must be released at some point to avoid memory leaks.

Context Popup Properties

There are no property keys associated with the Context Popup control.

Related topics

Windows Ribbon Framework Control Library

ContextPopup Sample