Barra de ferramentas de acesso rápido
A Barra de Ferramentas de Acesso Rápido (QAT) é uma barra de ferramentas pequena e personalizável que expõe um conjunto de comandos especificados pelo aplicativo ou selecionados pelo usuário.
- Introdução
- Implementar a barra de ferramentas de acesso rápido
- Persistência da QAT
- Propriedades da Barra de Ferramentas de Acesso Rápido
- Tópicos relacionados
Introdução
Por padrão, a Barra de Ferramentas de Acesso Rápido (QAT) está localizada na barra de título da janela do aplicativo, mas pode ser configurada para ser exibida abaixo da faixa de opções. Além de expor comandos, a barra de ferramentas de acesso rápido (QAT) também inclui um menu suspenso personalizável que contém o conjunto completo de comandos padrão da barra de ferramentas de acesso rápido (QAT) (ocultos ou exibidos na barra de ferramentas de acesso rápido (QAT)) e um conjunto de opções de barra de ferramentas de acesso rápido (QAT) e faixa de opções.
A captura de tela a seguir mostra um exemplo da Barra de Ferramentas de Acesso Rápido (QAT) da Faixa de Opções.
A Barra de Ferramentas de Acesso Rápido (QAT) consiste em uma combinação de até 20 comandos especificados pelo aplicativo (conhecidos como lista de padrões do aplicativo) ou selecionados pelo usuário. A Barra de Ferramentas de Acesso Rápido (QAT) pode conter comandos exclusivos que não estão disponíveis em nenhum outro lugar na interface do usuário da faixa de opções.
Observação
Embora quase todos os controles da faixa de opções permitam que seu comando associado seja adicionado à QAT (Barra de Ferramentas de Acesso Rápido) por meio do menu de contexto mostrado na captura de tela a seguir, os comandos expostos em um pop-up de contexto não fornecem esse menu de contexto.
Implementar a barra de ferramentas de acesso rápido
Assim como acontece com todos os controles de estrutura da Faixa de Opções do Windows, aproveitar ao máximo a QAT (Barra de Ferramentas de Acesso Rápido) requer um componente de marcação que controla sua apresentação na faixa de opções e um componente de código que controla sua funcionalidade.
Marcação
O controle QAT (Barra de Ferramentas de Acesso Rápido) é declarado e associado a uma ID de Comando, na marcação por meio do elemento QuickAccessToolbar. A ID do Comando é usada para identificar e vincular a Barra de Ferramentas de Acesso Rápido (QAT) a um manipulador de Comandos definido pelo aplicativo.
Além do manipulador de comandos básico para a funcionalidade primária da Barra de Ferramentas de Acesso Rápido (QAT), declarar o atributo de elemento opcional CustomizeCommandName QuickAccessToolbar faz com que a estrutura adicione um item Mais Comandos à lista de Comandos do menu suspenso da Barra de Ferramentas de Acesso Rápido (QAT) que requer a definição de um manipulador de Comandos secundário.
Para consistência entre aplicativos da Faixa de Opções, é recomendável que o manipulador de comandos CustomizeCommandName inicie uma caixa de diálogo de personalização da Barra de Ferramentas de Acesso Rápido (QAT). Como a estrutura da Faixa de Opções fornece apenas o ponto de inicialização na interface do usuário, o aplicativo é o único responsável por fornecer a implementação da caixa de diálogo de personalização quando a notificação de retorno de chamada para esse Comando é recebida.
A captura de tela a seguir mostra um menu suspenso QAT (Barra de Ferramentas de Acesso Rápido) com o item Comando Mais Comandos.
A lista de padrões do aplicativo para a Barra de Ferramentas de Acesso Rápido (QAT) é especificada por meio da propriedade QuickAccessToolbar.ApplicationDefaults, que identifica uma lista padrão de Comandos recomendados, todos listados no menu suspenso da Barra de Ferramentas de Acesso Rápido (QAT).
Para exibir Comandos da lista de padrões do aplicativo na barra de ferramentas QAT (Barra de Ferramentas de Acesso Rápido), o atributo ApplicationDefaults.IsChecked de cada elemento de controle deve ter um valor de true. As imagens anteriores mostram os resultados da configuração desse atributo como true para os comandos Salvar, Desfazer e Refazer.
QuickAccessToolbar.ApplicationDefaults dá suporte a três tipos de controles da Faixa de Opções: Botão, Botão de Alternância e Caixa de Seleção.
Observação
Windows 8 e mais recente: há suporte para todos os controles baseados em galeria (ComboBox, InRibbonGallery, SplitButtonGallery e DropDownGallery).
Os itens em um controle de galeria podem dar suporte ao realce ao passar o mouse. Para dar suporte ao realce de foco, a galeria deve ser uma galeria de itens e usar um FlowMenuLayout do tipo VerticalMenuLayout.
O exemplo a seguir demonstra a marcação básica para um elemento QuickAccessToolbar.
Esta seção de código mostra as declarações de comando para um elemento QAT (Barra de Ferramentas de Acesso Rápido).
<Command Name="cmdQAT"
Symbol="ID_QAT"
Id="40000"/>
<Command Name="cmdCustomizeQAT"
Symbol="ID_CUSTOM_QAT"
Id="40001"/>
Esta seção de código mostra as declarações de código para um elemento QAT (Barra de Ferramentas de Acesso Rápido).
<Ribbon.QuickAccessToolbar>
<QuickAccessToolbar CommandName="cmdQAT"
CustomizeCommandName="cmdCustomizeQAT">
<QuickAccessToolbar.ApplicationDefaults>
<Button CommandName="cmdButton1"/>
<ToggleButton CommandName="cmdMinimize"
ApplicationDefaults.IsChecked="false"/>
</QuickAccessToolbar.ApplicationDefaults>
</QuickAccessToolbar>
</Ribbon.QuickAccessToolbar>
Código
O aplicativo da estrutura da Faixa de Opções deve fornecer um método de retorno de chamada do manipulador de comandos para manipular a QAT (Barra de Ferramentas de Acesso Rápido). Esse manipulador funciona de maneira semelhante aos manipuladores de galeria de comandos, exceto que a QAT (Barra de Ferramentas de Acesso Rápido) não oferece suporte a categorias. Para saber mais, consulte Trabalhando com Galerias.
A coleção de comandos QAT (Barra de Ferramentas de Acesso Rápido) é recuperada como um objeto IUICollection por meio da chave de propriedade UI_PKEY_ItemsSource. A adição de comandos à QAT (Barra de Ferramentas de Acesso Rápido) em tempo de execução é realizada adicionando um objeto IUISimplePropertySet ao IUICollection.
Ao contrário das galerias de comandos, uma propriedade de tipo de comando (UI_PKEY_CommandType) não é necessária para o objeto IUISimplePropertySet da Barra de Ferramentas de Acesso Rápido (QAT). No entanto, o Comando deve existir na faixa de opções ou na lista de padrões do aplicativo QAT (Barra de Ferramentas de Acesso Rápido); um novo comando não pode ser criado em tempo de execução e adicionado à barra de ferramentas de acesso rápido (QAT).
Observação
O aplicativo da Faixa de Opções não pode substituir a IUICollection da QAT (Barra de Ferramentas de Acesso Rápido) por um objeto de coleção personalizado derivado de IEnumUnknown.
O exemplo a seguir demonstra uma implementação básica do manipulador de comandos QAT (Barra de Ferramentas de Acesso Rápido).
/* QAT COMMAND HANDLER IMPLEMENTATION */
class CQATCommandHandler
: public CComObjectRootEx<CComMultiThreadModel>
, public IUICommandHandler
{
public:
BEGIN_COM_MAP(CQATCommandHandler)
COM_INTERFACE_ENTRY(IUICommandHandler)
END_COM_MAP()
// QAT command handler's Execute method
STDMETHODIMP Execute(UINT nCmdID,
UI_EXECUTIONVERB verb,
const PROPERTYKEY* key,
const PROPVARIANT* ppropvarValue,
IUISimplePropertySet* pCommandExecutionProperties)
{
UNREFERENCED_PARAMETER(nCmdID);
UNREFERENCED_PARAMETER(verb);
UNREFERENCED_PARAMETER(ppropvarValue);
UNREFERENCED_PARAMETER(pCommandExecutionProperties);
// Do not expect Execute callback for a QAT command
return E_NOTIMPL;
}
// QAT command handler's UpdateProperty method
STDMETHODIMP UpdateProperty(UINT nCmdID,
REFPROPERTYKEY key,
const PROPVARIANT* ppropvarCurrentValue,
PROPVARIANT* ppropvarNewValue)
{
UNREFERENCED_PARAMETER(nCmdID);
UNREFERENCED_PARAMETER(ppropvarNewValue);
HRESULT hr = E_NOTIMPL;
if (key == UI_PKEY_ItemsSource)
{
ATLASSERT(ppropvarCurrentValue->vt == VT_UNKNOWN);
CComQIPtr<IUICollection> spCollection(ppropvarCurrentValue->punkVal);
UINT nCount;
if (SUCCEEDED(hr = spCollection->GetCount(&nCount)))
{
if (nCount == 0)
{
// If the current Qat list is empty, then we will add a few items here.
UINT commands[] = { cmdSave, cmdUndo};
int count = _countof(commands);
for (int i = 0; i < count; i++)
{
PROPERTYKEY keys[1] = {UI_PKEY_CommandId};
CComObject<CItemProperties> *pItem = NULL;
if (SUCCEEDED(CComObject<CItemProperties>::CreateInstance(&pItem)))
{
PROPVARIANT vars[1];
InitPropVariantFromUInt32(commands[i], &vars[0]);
pItem->Initialize(NULL, _countof(vars), keys, vars);
CComPtr<IUnknown> spUnknown;
pItem->QueryInterface(&spUnknown);
spCollection->Add(spUnknown);
FreePropVariantArray(_countof(vars), vars);
}
}
}
else
{
// Do nothing if the Qat list is not empty.
// Return S_FALSE to indicate the callback succeeded.
return S_FALSE;
}
}
}
return hr;
}
};
Persistência da QAT
Os itens e as configurações do comando QAT (Barra de Ferramentas de Acesso Rápido) podem ser mantidos em sessões de aplicativo usando as funções IUIRibbon::SaveSettingsToStream e IUIRibbon::LoadSettingsFromStream. Para obter mais informações, consulte Persistindo o estado da faixa de opções.
Propriedades da Barra de Ferramentas de Acesso Rápido
A estrutura da Faixa de Opções define uma coleção de chaves de propriedade para o controle QAT (Barra de Ferramentas de Acesso Rápido).
Normalmente, uma propriedade QAT (Barra de Ferramentas de Acesso Rápido) é atualizada na interface do usuário da faixa de opções invalidando o Command associado ao controle por meio de uma chamada para o método IUIFramework::InvalidateUICommand. O evento de invalidação é manipulado e as atualizações de propriedade definidas pelo método de retorno de chamada IUICommandHandler::UpdateProperty.
O método de retorno de chamada IUICommandHandler::UpdateProperty não é executado e o aplicativo é consultado em busca de um valor de propriedade atualizado, até que a propriedade seja exigida pela estrutura. Por exemplo, quando uma guia é ativada e um controle revelado na interface do usuário da faixa de opções ou quando uma dica de ferramenta é exibida.
Observação
Em alguns casos, uma propriedade pode ser recuperada por meio do método IUIFramework::GetUICommandProperty e definida com o método IUIFramework::SetUICommandProperty.
A tabela a seguir lista as chaves de propriedade associadas ao controle QAT (Barra de Ferramentas de Acesso Rápido).
| Chave de propriedade | Observações |
|---|---|
| UI_PKEY_ItemsSource | Dá suporte a IUIFramework::GetUICommandProperty (não dá suporte a IUIFramework::SetUICommandProperty).IUIFramework::GetUICommandProperty retorna um ponteiro para um objeto IUICollection que representa os comandos no QAT. Cada Comando é identificado por sua ID de Comando, que é obtida chamando o método IUISimplePropertySet::GetValue e passando a chave de propriedade UI_PKEY_CommandId. |
Não há chaves de propriedade associadas com o item de Comando Mais Comandos do menu suspenso QAT (Barra de Ferramentas de Acesso Rápido)