Pop-up de Contexto

  • Artigo

Um Pop-up de Contexto é o controle principal na Exibição ContextPopup da estrutura da Faixa de Opções do Windows. É um sistema de menu de contexto avançado que só é exposto pela estrutura como uma extensão para uma implementação da Faixa de Opções— a estrutura não expõe o Pop-up de Contexto como um controle independente.

Componentes do pop-up de contexto

O Pop-up de Contexto é um contêiner lógico para o Menu de Contexto e Mini-Toolbar sub-controles expostos por meio dos elementos de marcação ContextMenu e MiniToolbar , respectivamente:

Cada subcontrole pode aparecer no máximo uma vez em um pop-up de contexto.

A captura de tela a seguir ilustra o Pop-up de Contexto e seus sub-controles constituintes.

captura de tela com textos explicativos mostrando os componentes contextuais da interface do usuário da faixa de opções.

O Pop-up de Contexto é puramente conceitual e não expõe nenhuma funcionalidade de interface do usuário em si, como posicionamento ou dimensionamento.

Observação

O Pop-up de Contexto normalmente é exibido clicando com o botão direito do mouse (ou por meio do atalho de teclado SHIFT+F10) em um objeto de interesse. No entanto, as etapas necessárias para exibir o Pop-up de Contexto são definidas pelo aplicativo.

 

Implementar o pop-up de contexto

De forma semelhante a outros controles de estrutura da Faixa de Opções do Windows, o Pop-up de Contexto é implementado por meio de um componente de marcação que especifica os detalhes da apresentação e um componente de código que rege sua funcionalidade.

A tabela a seguir lista os controles compatíveis com cada subcontrole pop-up de contexto.

Control Mini-Toolbar Menu de contexto
Botão x x
Caixa de seleção x x
Caixa de combinação x
Botão suspenso x x
Seletor de cores suspenso x x
Galeria suspensa x x
Controle de fonte x
Botão Ajuda
Galeria na Faixa de Opções
Controle giratório
Botão Dividir x x
Galeria de Botões Divididos x x
Botão de alternância x x

 

Marcação

Cada subcontrole pop-up de contexto deve ser declarado individualmente na marcação.

Mini-Toolbar

Ao adicionar controles a uma minibarra de ferramentas pop-up de contexto, as duas recomendações a seguir devem ser consideradas:

  • Os controles devem ser altamente reconhecíveis e fornecer funcionalidade óbvia. Familiaridade é fundamental, pois rótulos e dicas de ferramenta não são expostos para controles Mini-Toolbar.
  • Cada Comando exposto por um controle deve ser apresentado em outro lugar na interface do usuário da faixa de opções. O Mini-Toolbar não dá suporte à navegação por teclado.

O exemplo a seguir demonstra a marcação básica de um elemento MiniToolbar que contém três controles Button .

Observação

Um elemento MenuGroup é especificado para cada linha de controles na Minibarra de Ferramentas.

 

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

Menu de contexto

O exemplo a seguir demonstra a marcação básica de um elemento ContextMenu que contém três controles Button .

Observação

Cada conjunto de controles no elemento MenuGroup é separado por uma barra horizontal no Menu de Contexto.

 

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

Embora um Pop-up de Contexto possa conter no máximo um de cada subcontrole, várias declarações de elemento ContextMenu e MiniToolbar na marcação ribbon são válidas. Isso permite que um aplicativo dê suporte a várias combinações de menu de contexto e controles de Mini-Toolbar, com base em critérios definidos pelo aplicativo, como o contexto do workspace.

Para obter mais informações, consulte o elemento ContextMap .

O exemplo a seguir demonstra a marcação básica para o elemento ContextPopup .

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

Código

Para invocar um Pop-up de Contexto, o método IUIContextualUI::ShowAtLocation é chamado quando a janela de nível superior do aplicativo da Faixa de Opções recebe uma notificação de WM_CONTEXTMENU.

Este exemplo demonstra como lidar com a notificação de WM_CONTEXTMENU no método WndProc() do aplicativo Ribbon.

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

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

O exemplo a seguir demonstra como um aplicativo da Faixa de Opções pode mostrar o Pop-up de Contexto em um local de tela específico usando o método IUIContextualUI::ShowAtLocation .

GetCurrentContext() tem um valor igual cmdContextMap ao definido no exemplo de marcação anterior.

g_pApplication é uma referência à interface IUIFramework .

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;
}

A referência a IUIContextualUI pode ser liberada antes que o Pop-up de Contexto seja ignorado, conforme mostrado no exemplo anterior. No entanto, a referência deve ser liberada em algum momento para evitar vazamentos de memória.

Cuidado

O Mini-Toolbar tem um efeito de fade interno baseado na proximidade do ponteiro do mouse. Por esse motivo, é recomendável que o Mini-Toolbar seja exibido o mais próximo possível do ponteiro do mouse. Caso contrário, devido aos mecanismos de exibição conflitantes, o Mini-Toolbar pode não ser renderizado conforme o esperado.

 

Propriedades pop-up de contexto

Não há chaves de propriedade associadas ao controle pop-up de contexto.

Biblioteca de Controle da Estrutura da Faixa de Opções do Windows

Exemplo de ContextPopup