Edit

Context Popup

  • Article

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

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:

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.

screen shot with callouts showing the ribbon contextual ui components.

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

Note

The Context Popup is typically displayed by right-clicking the mouse (or through the keyboard shortcut SHIFT+F10) on an object of interest. However, the steps required to display the Context Popup are defined by the application.

 

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.

Control Mini-Toolbar Context Menu
Button x x
Check Box x x
Combo Box x
Drop-Down Button x x
Drop-Down Color Picker x x
Drop-Down Gallery x x
Font Control x
Help Button
In-Ribbon Gallery
Spinner
Split Button x x
Split Button Gallery x x
Toggle Button x x

 

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.

Note

One MenuGroup element is specified for each row of controls in the Mini-Toolbar.

 

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

Note

Each set of controls in the MenuGroup element is separated by a horizontal bar in the Context Menu.

 

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

Caution

The Mini-Toolbar has a built-in fade effect that is based on the proximity of the mouse pointer. For this reason, it is recommended that the Mini-Toolbar be displayed as close to the mouse pointer as possible. Otherwise, due to the conflicting display mechanisms, the Mini-Toolbar may not render as expected.

 

Context Popup Properties

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

Windows Ribbon Framework Control Library

ContextPopup Sample