Barra de herramientas de acceso rápido
La barra de herramientas de acceso rápido (QAT) es una barra de herramientas pequeña y personalizable que expone un conjunto de comandos especificados por la aplicación o seleccionados por el usuario.
- Introducción
- Implementar la barra de herramientas de acceso rápido
- Persistencia de QAT
- Propiedades de la barra de herramientas de acceso rápido
- Temas relacionados
Introducción
De forma predeterminada, la barra de herramientas de acceso rápido (QAT) se encuentra en la barra de título de la ventana de la aplicación, pero se puede configurar para mostrar debajo de la cinta de opciones. Además de exponer comandos, la barra de herramientas de acceso rápido (QAT) también incluye un menú desplegable personalizable que contiene el conjunto completo de comandos predeterminados de barra de herramientas de acceso rápido (QAT) (ya sean ocultos o mostrados en la barra de herramientas de acceso rápido (QAT)) y un conjunto de opciones de barra de herramientas de acceso rápido (QAT) y opciones de cinta.
En la captura de pantalla siguiente se muestra un ejemplo de la barra de herramientas de acceso rápido (QAT) de la cinta de opciones.
La barra de herramientas de acceso rápido (QAT) consta de una combinación de hasta 20 comandos especificados por la aplicación (conocida como lista de valores predeterminados de la aplicación) o seleccionado por el usuario. La barra de herramientas de acceso rápido (QAT) puede contener comandos únicos que no están disponibles en otra parte de la interfaz de usuario de la cinta de opciones.
Nota
Aunque casi todos los controles de cinta permiten agregar su comando asociado a la barra de herramientas de acceso rápido (QAT) a través del menú contextual que se muestra en la siguiente captura de pantalla, los comandos expuestos en un menú emergente contextual no proporcionan este menú contextual.
Implementar la barra de herramientas de acceso rápido
Al igual que con todos los controles del marco de la cinta de Opciones de Windows, aprovechar al máximo la barra de herramientas de acceso rápido (QAT) requiere un componente de marcado que controla su presentación dentro de la cinta de opciones y un componente de código que rige su funcionalidad.
marcado
El control Barra de herramientas de acceso rápido (QAT) se declara y se asocia a un identificador de comando, en el marcado mediante el elemento QuickAccessToolbar . El identificador de comando se usa para identificar y enlazar la barra de herramientas de acceso rápido (QAT) a un controlador de comandos definido por la aplicación.
Además del controlador de comandos básico para la funcionalidad principal de la barra de herramientas de acceso rápido (QAT), declarar el atributo de elemento CustomizeCommandNameQuickAccessToolbar opcional hace que el marco agregue un elemento Más comandos a la lista de comandos del menú desplegable Barra de herramientas de acceso rápido (QAT) que requiere que se defina un controlador de comandos secundario.
Para la coherencia entre las aplicaciones de cinta de opciones, se recomienda que el controlador de comandos CustomizeCommandName inicie un cuadro de diálogo de personalización de la barra de herramientas de acceso rápido (QAT). Dado que el marco de la cinta de opciones solo proporciona el punto de inicio en la interfaz de usuario, la aplicación es el único responsable de proporcionar la implementación del cuadro de diálogo de personalización cuando se recibe la notificación de devolución de llamada para este comando.
En la captura de pantalla siguiente se muestra un menú desplegable barra de herramientas de acceso rápido (QAT) con el elemento Comando Más comandos .
La lista predeterminada de la aplicación para la barra de herramientas de acceso rápido (QAT) se especifica a través de la propiedad QuickAccessToolbar.ApplicationDefaults que identifica una lista predeterminada de comandos recomendados, todos los cuales se enumeran en el menú desplegable Barra de herramientas de acceso rápido (QAT).
Para mostrar comandos de la lista predeterminada de la aplicación en la barra de herramientas de la barra de herramientas de acceso rápido (QAT), el atributo ApplicationDefaults.IsChecked de cada elemento de control debe tener un valor de true. Las imágenes anteriores muestran los resultados de establecer este atributo true en para los comandos Guardar, Deshacer y Rehacer .
QuickAccessToolbar.ApplicationDefaults admite tres tipos de controles de cinta: Button, Toggle Button y Check Box.
Nota
Windows 8 y versiones más recientes: se admiten todos los controles basados en la galería (ComboBox, InRibbonGallery, SplitButtonGallery y DropDownGallery).
Los elementos de un control de galería pueden admitir el resaltado al mantener el puntero. Para admitir el resaltado del puntero, la galería debe ser una galería de elementos y usar flowMenuLayout de tipo VerticalMenuLayout.
En el ejemplo siguiente se muestra el marcado básico de un elemento QuickAccessToolbar .
En esta sección de código se muestran las declaraciones de comandos para un elemento barra de herramientas de acceso rápido (QAT).
<Command Name="cmdQAT"
Symbol="ID_QAT"
Id="40000"/>
<Command Name="cmdCustomizeQAT"
Symbol="ID_CUSTOM_QAT"
Id="40001"/>
En esta sección de código se muestran las declaraciones de control para un elemento de barra de herramientas de acceso rápido (QAT).
<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
La aplicación del marco de la cinta de opciones debe proporcionar un método de devolución de llamada del controlador de comandos para manipular la barra de herramientas de acceso rápido (QAT). Este controlador funciona de forma similar a los controladores de la galería de comandos, salvo que la barra de herramientas de acceso rápido (QAT) no admite categorías. Para obtener más información, vea Trabajar con galerías.
La colección Command de la barra de herramientas de acceso rápido (QAT) se recupera como un objeto IUICollection a través de la clave de propiedad UI_PKEY_ItemsSource . Para agregar comandos a la barra de herramientas de acceso rápido (QAT) en tiempo de ejecución, se agrega un objeto IUISimplePropertySet a IUICollection.
A diferencia de las galerías de comandos, no se requiere una propiedad de tipo de comando (UI_PKEY_CommandType) para el objeto IUISimplePropertySet de la barra de herramientas de acceso rápido (QAT). Sin embargo, el comando debe existir en la cinta de opciones o en la lista predeterminada de la aplicación barra de herramientas de acceso rápido (QAT); No se puede crear un nuevo comando en tiempo de ejecución y agregarse a la barra de herramientas de acceso rápido (QAT).
Nota
La aplicación Ribbon no puede reemplazar la IUICollection de la barra de herramientas de acceso rápido (QAT) por un objeto de colección personalizado derivado de IEnumUnknown.
En el ejemplo siguiente se muestra una implementación básica del controlador de comandos de barra de herramientas de acceso rápido (QAT).
/* 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;
}
};
Persistencia de QAT
Los elementos y la configuración de la barra de herramientas de acceso rápido (QAT) se pueden conservar en las sesiones de la aplicación mediante las funciones IUIRibbon::SaveSettingsToStream e IUIRibbon::LoadSettingsFromStream . Para obtener más información, vea Conservar el estado de la cinta de opciones.
Propiedades de la barra de herramientas de acceso rápido
El marco de la cinta define una colección de claves de propiedad para el control Barra de herramientas de acceso rápido (QAT).
Normalmente, una propiedad barra de herramientas de acceso rápido (QAT) se actualiza en la interfaz de usuario de la cinta de opciones invalidando el comando asociado al control a través de una llamada al método IUIFramework::InvalidateUICommand . El evento de invalidación se controla y la propiedad se actualiza definida por el método de devolución de llamada IUICommandHandler::UpdateProperty .
El método de devolución de llamada IUICommandHandler::UpdateProperty no se ejecuta y la aplicación consulta para obtener un valor de propiedad actualizado, hasta que el marco requiera la propiedad. Por ejemplo, cuando se activa una pestaña y se muestra un control en la interfaz de usuario de la cinta de opciones, o cuando se muestra una información sobre herramientas.
Nota
En algunos casos, se puede recuperar una propiedad a través del método IUIFramework::GetUICommandProperty y establecer con el método IUIFramework::SetUICommandProperty .
En la tabla siguiente se enumeran las claves de propiedad asociadas al control Barra de herramientas de acceso rápido (QAT).
| Clave de propiedad | Notas |
|---|---|
| UI_PKEY_ItemsSource | Admite IUIFramework::GetUICommandProperty (no admite IUIFramework::SetUICommandProperty). IUIFramework::GetUICommandProperty devuelve un puntero a un objeto IUICollection que representa los comandos del QAT. Cada comando se identifica mediante su identificador de comando, que se obtiene llamando al método IUISimplePropertySet::GetValue y pasando la clave de propiedad UI_PKEY_CommandId. |
No hay claves de propiedad asociadas al elemento Comando Más comandos del menú desplegable Barra de herramientas de acceso rápido (QAT)
Temas relacionados
Comentarios
Próximamente: A lo largo de 2024 iremos eliminando gradualmente GitHub Issues como mecanismo de comentarios sobre el contenido y lo sustituiremos por un nuevo sistema de comentarios. Para más información, vea: https://aka.ms/ContentUserFeedback.
Enviar y ver comentarios de