Barra de Ferramentas de Acesso Rápido
A QAT (Barra de Ferramentas de Acesso Rápido) é 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 de QAT
- Propriedades da Barra de Ferramentas de Acesso Rápido
- Tópicos relacionados
Introdução
Por padrão, a QAT (Barra de Ferramentas de Acesso Rápido) está localizada na barra de título da janela do aplicativo, mas pode ser configurada para exibição abaixo da faixa de opções. Além de expor Comandos, a QAT (Barra de Ferramentas de Acesso Rápido) também inclui um menu suspenso personalizável que contém o conjunto completo de comandos padrão da QAT (Barra de Ferramentas de Acesso Rápido) (ocultos ou exibidos na QAT (Barra de Ferramentas de Acesso Rápido) e um conjunto de opções de QAT (Barra de Ferramentas de Acesso Rápido) e opções de faixa de opções.
A captura de tela a seguir mostra um exemplo da QAT (Barra de Ferramentas de Acesso Rápido) da Faixa de Opções.
A QAT (Barra de Ferramentas de Acesso Rápido) consiste em uma combinação de até 20 comandos especificados pelo aplicativo (conhecido como lista de padrões do aplicativo) ou selecionados pelo usuário. A QAT (Barra de Ferramentas de Acesso Rápido) pode conter comandos exclusivos que não estão disponíveis em outro lugar na interface do usuário da faixa de opções.
Observação
Embora quase todos os controles de 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 da 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 dentro da faixa de opções e um componente de código que rege 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 de Comando é usada para identificar e associar a QAT (Barra de Ferramentas de Acesso Rápido) a um manipulador de comando definido pelo aplicativo.
Além do manipulador de comando básico para a funcionalidade de QAT (Barra de Ferramentas de Acesso Rápido) primário, declarar o atributo opcional do elemento CustomizeCommandNameQuickAccessToolbar faz com que a estrutura adicione um item Mais Comandos à lista comando do menu suspenso QAT (Barra de Ferramentas de Acesso Rápido) que exige que um manipulador de comando secundário seja definido.
Para consistência em aplicativos da Faixa de Opções, é recomendável que o manipulador de comandos CustomizeCommandName inicie uma caixa de diálogo de personalização qat (Barra de Ferramentas de Acesso Rápido). 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 QAT (Barra de Ferramentas de Acesso Rápido) é especificada por meio da propriedade QuickAccessToolbar.ApplicationDefaults que identifica uma lista padrão de Comandos recomendados, todos listados no menu suspenso QAT (Barra de Ferramentas de Acesso Rápido).
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 true como 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 recentes: todos os controles baseados em galeria têm suporte (ComboBox, InRibbonGallery, SplitButtonGallery e DropDownGallery).
Os itens em um controle de galeria podem dar suporte ao realce no foco. 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 de 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 controle de 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 de 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 da galeria de comandos, exceto que a QAT (Barra de Ferramentas de Acesso Rápido) não dá suporte a categorias. Para obter mais informações, 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 à IUICollection.
Ao contrário das galerias command, 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 à QAT (Barra de Ferramentas de Acesso Rápido).
Observação
O aplicativo Ribbon não pode substituir a IUICollection da Barra de Ferramentas de Acesso Rápido (QAT) 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 de QAT
Os itens e as configurações do comando QAT (Barra de Ferramentas de Acesso Rápido) podem ser persistidos entre sessões de aplicativo usando as funções IUIRibbon::SaveSettingsToStream e IUIRibbon::LoadSettingsFromStream . Para obter mais informações, consulte Persisting Ribbon State.
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 Comando associado ao controle por meio de uma chamada para o método IUIFramework::InvalidateUICommand . O evento de invalidação é tratado 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 consultou 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 ao item Comando Mais Comandos do menu suspenso QAT (Barra de Ferramentas de Acesso Rápido)
Tópicos relacionados
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de