Criando uma aplicação Ribbon

A estrutura da Faixa de Opções do Windows é composta por duas plataformas de desenvolvimento distintas, mas dependentes: uma linguagem de marcação baseada em Extensible Application Markup Language (XAML) para declarar controles e seu layout visual e um conjunto de interfaces baseado em C++ Component Object Model (COM) para definir a funcionalidade de comando e ganchos de aplicativo. Essa divisão de trabalho no framework Ribbon requer que um desenvolvedor que queira tirar partido das funcionalidades avançadas da interface do utilizador oferecidas pelo framework desenhe e descreva a interface do utilizador na marcação e, em seguida, use as interfaces COM do framework Ribbon para ligar o framework à aplicação anfitriã.

• Roteiro de Fitas
• Escreva a marcação
  • compilar a marcação
• Construir a Aplicação
  • Inicializar a Faixa de Opções
  • vincular a marcação ao aplicativo
  • compilar o aplicativo
• Atualizações de tempo de execução e execuções
• Suporte OLE
• Tópicos relacionados

Roteiro da Faixa de Opções

Os aspetos visuais de um aplicativo Ribbon, como quais controlos são exibidos e onde eles são colocados, são declarados no markup (consulte Declarando Comandos e Controles com Ribbon Markup). A lógica de comando do aplicativo, como o que acontece quando um botão é pressionado, é implementada no código.

O processo de implementar uma Faixa de Opções e incorporá-la a um aplicativo do Windows requer quatro tarefas básicas: escrever a marcação, compilar a marcação, escrever o código e compilar e vincular todo o aplicativo.

O diagrama a seguir ilustra o fluxo de trabalho para uma implementação típica da Faixa de Opções.

As seções a seguir descrevem esse processo com mais detalhes.

Escrever o código de marcação

Depois que a interface do usuário da Faixa de Opções tiver sido projetada, a primeira tarefa para um desenvolvedor de aplicativos é descrever a interface do usuário com a marcação da Faixa de Opções.

Os controles da Faixa de Opções, os Comandos da Faixa de Opções (os elementos independentes do controle que fornecem a funcionalidade base para os controles da Faixa de Opções) e todos os layouts de controle e relações visuais são declarados na marcação. A estrutura da marcação da Faixa de Opções enfatiza a distinção entre controles da Faixa de Opções e Comandos por meio de duas hierarquias de nós principais: uma árvore de Comandos e Recursos e uma árvore de Vistas .

Todos os recipientes e ações expostos pela Faixa de Opções são declarados na árvore de Comandos e Recursos . Cada elemento Command é associado a um conjunto de recursos, conforme exigido pelo design da interface do usuário.

Depois de criar os Comandos para uma aplicação, declara controlos na árvore de modos de exibição e vincula cada controlo a um Comando para expor a funcionalidade do Comando. A estrutura da Faixa de Opções determina o posicionamento real dos controles com base na hierarquia de Controle declarada aqui.

O exemplo de código a seguir ilustra como declarar um controle Button, rotulado Exit application, e associá-lo a um Exit Command.

<Application xmlns="http://schemas.microsoft.com/windows/2009/Ribbon">
  <Application.Commands>
    <Command Name="cmdExit" LabelTitle="Exit application" />
  </Application.Commands>

  <Application.Views>
    <Ribbon>
      <Ribbon.Tabs>
        <Tab>
          <Group>
            <Button CommandName="cmdExit" />
          </Group>
        </Tab>
      </Ribbon.Tabs>
    </Ribbon>
  </Application.Views>
</Application>
        

Compilar a marcação

Depois que o arquivo de marcação da Faixa de Opções é criado, ele deve ser compilado em um formato binário pelo compilador de marcação da Faixa de Opções, UICC (UICC (UI Command Compiler), incluído no SDK (Software Development Kit) do Windows. Uma referência a este ficheiro binário é passada para o método IUIFramework::LoadUI durante a inicialização da estrutura Ribbon pelo aplicativo host.

UICC pode ser executado diretamente de uma janela de linha de comando ou adicionado como uma "etapa de compilação personalizada" no Visual Studio.

A imagem a seguir mostra o compilador de marcação UICC na janela do Shell CMD do SDK do Windows 7.

A imagem a seguir mostra UICC adicionado como uma etapa de compilação personalizada no Visual Studio.

O UICC gera três ficheiros: uma versão binária do marcador (.bml), um cabeçalho de definição de identificação (ficheiro .h) para expor elementos do marcador à aplicação host do Ribbon e um script de definição de recursos (ficheiro .rc) para ligar recursos de imagens e cadeias de caracteres do Ribbon à aplicação host em tempo de compilação.

Para obter mais detalhes sobre como compilar a marcação da estrutura da Faixa de Opções, consulte Compilando a marcação da Faixa de Opções.

Criar o aplicativo

Depois de a interface do utilizador preliminar de uma aplicação Ribbon ter sido desenhada e implementada na linguagem de marcação, o código da aplicação deve ser escrito para inicializar a estrutura, consumir a marcação e vincular os Comandos declarados na marcação aos manipuladores de Comandos apropriados na aplicação.

Inicializar a faixa de opções

O diagrama a seguir ilustra as etapas necessárias para implementar um aplicativo simples da Faixa de Opções.

As etapas a seguir descrevem detalhadamente como implementar uma aplicação Ribbon simples.

1. CoCreateInstance

   A aplicação chama a função CoCreateInstance padrão do COM com o ID de classe da estrutura Ribbon para obter um ponteiro para a framework.

   IUIFramework* pFramework = NULL;
   HRESULT hr = ::CoCreateInstance(
               CLSID_UIRibbonFramework, 
               NULL,
               CLSCTX_INPROC_SERVER, 
               IID_PPV_ARGS(&pFramework));
   if (FAILED(hr))
   {
     return hr;
   }
   

2. Inicializar(hwnd, IUIApplication*)

   A aplicação chama IUIFramework::Initialize, passando dois parâmetros: o identificador para a janela de nível superior que conterá o Ribbon e um ponteiro para a implementação IUIApplication que permite que o framework faça retornos de chamada para a aplicação.

   ! [Importante]
   A estrutura da Faixa de Opções é inicializada como um apartamento monothread (STA).

    

   hr = pFramework->Initialize(hWndHost, pApplication);
   if (FAILED(hr))
   {
     return hr;
   }
   

3. LoadUI(instância, resourceName)

   O aplicativo chama IUIFramework::LoadUI para vincular o recurso de marcação. O primeiro parâmetro dessa função é um identificador para a instância do aplicativo Ribbon. O segundo parâmetro é o nome do recurso de marcação binária que foi compilado anteriormente. Ao passar a marcação binária para a estrutura da Faixa de Opções, o aplicativo sinaliza qual deve ser a estrutura da Faixa de Opções e como os controles devem ser organizados. Ele também fornece à estrutura um manifesto de comandos a expor (como Colar, Recortar, Localizar), que são usados pela estrutura quando executa chamadas de retorno relacionadas a comandos em tempo de execução.

   hr = pFramework->LoadUI(GetModuleHandle(NULL), L"APPLICATION_RIBBON");
   if (FAILED(hr))
   {
     return hr;
   }
   

4. IUIApplication::OnCreateUICommand retornos de chamada

   Depois que as etapas 1 a 3 forem concluídas, a estrutura da Faixa de Opções saberá quais Comandos expor na Faixa de Opções. No entanto, a estrutura ainda precisa de duas coisas antes que a Faixa de Opções esteja totalmente funcional: uma maneira de informar ao aplicativo quando os Comandos são executados e uma maneira de obter recursos ou propriedades do Comando em tempo de execução. Por exemplo, se uma caixa de combinação deve aparecer na interface do usuário, a estrutura precisa solicitar os itens com os quais preencher a caixa de combinação.

   Essas duas partes de funcionalidade são manipuladas através do IUICommandHandler interface. Especificamente, para cada comando declarado na marcação binária (consulte a Etapa 3 acima), a estrutura chama IUIApplication::OnCreateUICommand para solicitar ao aplicativo um objeto IUICommandHandler para esse comando

   Observação

   A interface IUICommandHandler permite que um manipulador de comandos seja vinculado a um ou mais comandos.

    

No mínimo, é necessário que o aplicativo implemente os métodos stubs do IUIApplication que retornam E_NOTIMPL, como mostrado no exemplo a seguir.

STDMETHOD(OnViewChanged)(UINT32 viewId,
                         UI_VIEWTYPE typeID,
                         IUnknown *view,
                         UI_VIEWVERB verb,
                         INT32 uReasonCode)
{ 
  return E_NOTIMPL; 
}

STDMETHOD(OnCreateUICommand)(UINT32 commandId,
                             UI_COMMANDTYPE typeID,
                             IUICommandHandler **commandHandler)
{ 
  return E_NOTIMPL; 
}

STDMETHOD(OnDestroyUICommand)(UINT32 commandId,
                              UI_COMMANDTYPE typeID,
                              IUICommandHandler *commandHandler) 
{ 
  return E_NOTIMPL; 
}

Vincular a marcação ao aplicativo

Neste ponto, os arquivos de recurso de marcação devem ser vinculados ao aplicativo host incluindo uma referência ao arquivo de definição de recurso de marcação (que contém uma referência ao arquivo de cabeçalho de marcação) no arquivo de recurso do aplicativo. Por exemplo, um aplicativo chamado RibbonApp com um arquivo de recurso chamado ribbonUI.rc requer a seguinte linha no arquivo RibbonApp.rc.

#include "ribbonUI.rc"

Dependendo do compilador e do vinculador a serem usados, o script de definição de recursos pode também ter de ser compilado antes que o aplicativo Ribbon possa ser compilado. A ferramenta de linha de comando do compilador de recursos (RC) que acompanha o Microsoft Visual Studio e o SDK do Windows pode ser usada para essa tarefa.

Compilar o aplicativo

Depois que o aplicativo da Faixa de Opções é compilado, ele pode ser executado e a interface do usuário testada. Se a interface do usuário exigir ajustes e não houver alterações em nenhum manipulador de comando associado no código principal do aplicativo, revise o arquivo de origem da marcação, recompile a marcação com UICC.exee vincule os novos arquivos de recurso de marcação. Quando o aplicativo é reiniciado, a interface do usuário modificada é exibida.

Tudo isso é possível sem tocar no código principal do aplicativo — uma melhoria significativa em relação ao desenvolvimento e distribuição padrão de aplicativos.

Atualizações e Execuções durante a execução

A estrutura de comunicação em tempo real do Ribbon é baseada num modelo de envio e receção, ou chamador bidirecional.

Esse modelo permite que a estrutura informe o aplicativo quando um comando é executado e permite que a estrutura e o aplicativo consultem, atualizem e invalidem valores de propriedade e recursos da Faixa de Opções. Esta funcionalidade é fornecida através de uma série de interfaces e métodos.

A estrutura extrai informações de propriedade atualizadas do aplicativo Ribbon através do método de retorno de chamada IUICommandHandler::UpdateProperty. Uma ID de Comando e uma chave de propriedade, que identifica a propriedade Command a ser atualizada, são passadas para o método que, em seguida, retorna ou envia por push um valor para essa chave de propriedade para a estrutura.

A estrutura chama IUICommandHandler::Execute quando um Comando é executado, identificando a ID do Comando e o tipo de execução que ocorreu (UI_EXECUTIONVERB). É aqui que o aplicativo especifica a lógica de execução de um comando.

O diagrama a seguir ilustra a comunicação em tempo de execução para a execução de comandos entre a estrutura e o aplicativo.

Suporte OLE

Um aplicativo da Faixa de Opções pode ser configurado como um servidor OLE para oferecer suporte à ativação OLE fora do local.

Os objetos criados em um aplicativo de servidor OLE mantêm sua associação com o aplicativo de servidor quando inseridos (colados ou colocados) em um aplicativo cliente OLE (ou contêiner). Na ativação OLE fora do local, clicar duas vezes no objeto no aplicativo cliente abre uma instância dedicada do aplicativo de servidor e carrega o objeto para edição. Quando o aplicativo de servidor é fechado, todas as alterações feitas no objeto são refletidas no aplicativo cliente.

Tópicos relacionados

Declarando comandos e controlos com a interface Ribbon

Diretrizes de Experiência do Usuário da Faixa de Opções

Processo de Design da Faixa de Opções