Criando um aplicativo de faixa de opções
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 XAML (Extensible Application Markup Language) para declarar controles e seu layout visual e um conjunto de interfaces baseadas em COM (Component Object Model) do C++ para definir a funcionalidade de comando e os ganchos de aplicativo. Essa divisão de mão-de-obra na arquitetura da estrutura da Faixa de Opções exige que um desenvolvedor que queira aproveitar os recursos avançados de interface do usuário oferecidos pela estrutura deva projetar e descrever a interface do usuário na marcação e, em seguida, usar as interfaces COM da estrutura da Faixa de Opções para conectar a estrutura ao aplicativo host.
- Roteiro da Faixa de Opções
- Gravar a marcação
- Compilar o aplicativo
- Execuções e Atualizações de tempo de execução
- Suporte ao OLE
- Tópicos relacionados
Roteiro da Faixa de Opções
Os aspectos visuais de um aplicativo da Faixa de Opções, como quais controles são exibidos e onde eles são colocados, são declarados na marcação (consulte Declarando comandos e controles com marcação de faixa de opções). 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 em um aplicativo do Windows requer quatro tarefas básicas: gravar 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.
Gravar a 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.
Importante
O arquivo de esquema de marcação da estrutura da Faixa de Opções, UICC.xsd, é instalado com o Microsoft Windows Software Development Kit (SDK) para Windows 7 e .NET Framework 4.0. Usando o caminho de instalação padrão, o arquivo está localizado na pasta %ProgramFiles%\Microsoft SDKs\Windows\[version number]\Bin, na qual pode ser referenciado por muitos editores XML para fornecer dicas e preenchimento automático.
Controles de faixa de opções, Comandos da Faixa de Opções (os elementos independentes de controle que fornecem a funcionalidade base para 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ó primário: uma árvore comandos e recursos e uma árvore de exibições .
Todos os contêineres e ações expostos pela Faixa de Opções são declarados na árvore 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 um aplicativo, declare controles na árvore Exibições e associe cada controle a um Comando para expor a funcionalidade 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 como Sair do aplicativo e associá-lo a um comando Exit.
<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>
Dica
Embora seja possível usar qualquer extensão de nome de arquivo para o arquivo de marcação da Faixa de Opções, .xml é a extensão recomendada que é usada em toda a documentação.
Compilar a marcação
Depois que o arquivo de marcação da Faixa de Opções for criado, ele deverá ser compilado em um formato binário pelo compilador de marcação da Faixa de Opções, UICC (Compilador de Comandos de Interface do Usuário), que está incluído no SDK (Software Development Kit) do Windows. Uma referência a esse arquivo binário é passada para o método IUIFramework::LoadUI durante a inicialização da estrutura da Faixa de Opções pelo aplicativo host.
O UICC pode ser executado diretamente de uma janela de linha de comando ou adicionado como uma "Etapa de Build 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 a UICC adicionada como uma Etapa de Build Personalizada no Visual Studio.
O UICC gera três arquivos: uma versão binária da marcação (.bml), um cabeçalho de definição de ID (arquivo .h) para expor elementos de marcação ao aplicativo host da Faixa de Opções e um script de definição de recurso (arquivo .rc) para vincular recursos de cadeia de caracteres e imagem da Faixa de Opções ao aplicativo 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.
Compilar o aplicativo
Depois que a interface do usuário preliminar de um aplicativo da Faixa de Opções tiver sido projetada e implementada na marcação, o código do aplicativo deverá ser escrito que inicialize a estrutura, consuma a marcação e associe os Comandos declarados na marcação aos manipuladores de Comando apropriados no aplicativo.
Importante
Como a estrutura da Faixa de Opções é baseada em COM, é recomendável que os projetos da Faixa de Opções usem o operador __uuidof() para fazer referência aos GUIDs para interfaces de estrutura da Faixa de Opções (IIDs). Nos casos em que não é possível usar o operador __uuidof(), como quando um compilador não Microsoft é usado ou o aplicativo host é baseado em C, os IIDs devem ser definidos pelo aplicativo, pois não estão contidos em uuid.lib.
Se os IIDs forem definidos pelo aplicativo, os GUIDs especificados em UIRibbon.idl deverão ser usados.
UIRibbon.idl é fornecido como parte do SDK (Software Development Kit) do Windows e pode ser encontrado no caminho de instalação padrão de %ProgramFiles%\Microsoft SDKs\Windows\v7.0\Include.
Inicializar a faixa de opções
O diagrama a seguir ilustra as etapas necessárias para implementar um aplicativo de Faixa de Opções simples.
As etapas a seguir descrevem detalhadamente como implementar um aplicativo de Faixa de Opções simples.
Cocreateinstance
O aplicativo chama a função COCreateInstance COM padrão com a ID da classe de estrutura da Faixa de Opções para obter um ponteiro para a estrutura.
IUIFramework* pFramework = NULL; HRESULT hr = ::CoCreateInstance( CLSID_UIRibbonFramework, NULL, CLSCTX_INPROC_SERVER, IID_PPV_ARGS(&pFramework)); if (FAILED(hr)) { return hr; }Initialize(hwnd, IUIApplication*)
O aplicativo chama IUIFramework::Initialize, passando dois parâmetros: o identificador para a janela de nível superior que conterá a Faixa de Opções e um ponteiro para a implementação IUIApplication que permite que a estrutura faça retornos de chamada para o aplicativo.
! [Importante]
A estrutura da Faixa de Opções é inicializada como um STA (single-threaded apartment).hr = pFramework->Initialize(hWndHost, pApplication); if (FAILED(hr)) { return hr; }LoadUI(instance, resourceName)
O aplicativo chama IUIFramework::LoadUI para associar o recurso de marcação. O primeiro parâmetro dessa função é um identificador para a instância de aplicativo da Faixa de Opções. 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 serem expostos (como Colar, Recortar, Localizar), que são usados pela estrutura quando ela faz retornos de chamada relacionados ao comando em tempo de execução.
hr = pFramework->LoadUI(GetModuleHandle(NULL), L"APPLICATION_RIBBON"); if (FAILED(hr)) { return hr; }Retornos de chamada IUIApplication::OnCreateUICommand
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 seja totalmente funcional: uma maneira de informar o aplicativo quando os comandos são executados e uma maneira de obter recursos de comando, ou propriedades, em tempo de execução. Por exemplo, se uma caixa de combinação for exibida na interface do usuário, a estrutura precisará solicitar os itens com os quais preencher a caixa de combinação.
Essas duas partes da funcionalidade são tratadas por meio da interface IUICommandHandler . 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 associado a um ou mais Comandos.
No mínimo, o aplicativo é necessário para implementar stubs de métodos IUIApplication que retornam E_NOTIMPL conforme 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 que está sendo usado, o script de definição de recurso também pode exigir a compilação antes que o aplicativo da Faixa de Opções 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 for compilado, ele poderá 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 do aplicativo principal, revise o arquivo de origem de marcação, recompile a marcação com UICC.exe e 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 de aplicativos padrão.
Execuções e Atualizações de tempo de execução
A estrutura de comunicação em tempo de execução da estrutura da Faixa de Opções baseia-se em um modelo de push e pull 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. Essa funcionalidade é fornecida por meio de várias interfaces e métodos.
A estrutura extrai informações de propriedade atualizadas do aplicativo Ribbon por meio 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 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 execução de comando entre a estrutura e o aplicativo.
Observação
A implementação das funções IUICommandHandler::UpdateProperty e IUICommandHandler::Execute não é necessária para exibir inicialmente uma Faixa de Opções em um aplicativo. No entanto, esses métodos são necessários para garantir que o aplicativo funcione corretamente quando os comandos são executados pelo usuário.
Suporte ao OLE
Um aplicativo da Faixa de Opções pode ser configurado como um servidor OLE para dar 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 servidor e carrega o objeto para edição. Quando o aplicativo do servidor é fechado, todas as alterações feitas no objeto são refletidas no aplicativo cliente.
Observação
A estrutura da Faixa de Opções não dá suporte à ativação OLE in-loco. Os objetos criados em um servidor OLE baseado na Faixa de Opções não podem ser editados de dentro do aplicativo cliente OLE. Uma instância dedicada externa do aplicativo de servidor é necessária.
Tópicos relacionados