Barre d’outils Accès rapide
La barre d’outils Accès rapide (QAT) est une petite barre d’outils personnalisable qui expose un ensemble de commandes spécifiées par l’application ou sélectionnées par l’utilisateur.
- Introduction
- Implémenter la barre d’outils Accès rapide
- Persistance de la QAT
- Propriétés de la barre d’outils Accès rapide
- Rubriques connexes
Introduction
Par défaut, la barre d’outils Accès rapide (QAT) est située dans la barre de titre de la fenêtre de l’application mais peut être configurée pour s’afficher sous le ruban. En plus d’exposer des commandes, la barre d’outils Accès rapide (QAT) comprend également un menu déroulant personnalisable contenant l’ensemble complet des commandes par défaut de la barre d’outils Accès rapide (QAT) (qu’elles soient cachées ou affichées dans la barre d’outils Accès rapide (QAT)) et un ensemble d’options de la barre d’outils Accès rapide (QAT) et du ruban.
La capture d’écran suivante montre un exemple de la barre d’outils Accès rapide du ruban (QAT).
La barre d’outils Accès rapide (QAT) se compose d’une combinaison de jusqu’à 20 commandes soit spécifiées par l’application (connues sous le nom de liste par défaut de l’application) soit sélectionnées par l’utilisateur. La barre d’outils Accès rapide (QAT) peut contenir des commandes uniques qui ne sont pas disponibles ailleurs dans l’interface utilisateur du ruban.
Remarque
Alors que presque tous les contrôles du ruban permettent d’ajouter leur commande associée à la barre d’outils Accès rapide (QAT) via le menu contextuel montré dans la capture d’écran suivante, les commandes exposées dans un menu contextuel ne fournissent pas ce menu contextuel.
Implémenter la barre d’outils Accès rapide
Comme pour tous les contrôles du framework de ruban Windows, tirer pleinement parti de la barre d’outils Accès rapide (QAT) nécessite à la fois un composant de balisage qui contrôle sa présentation dans le ruban et un composant de code qui régit sa fonctionnalité.
balisage
Le contrôle de la barre d’outils Accès rapide (QAT) est déclaré et associé à un ID de commande dans le balisage via l’élément QuickAccessToolbar. L’ID de commande est utilisé pour identifier et lier la barre d’outils Accès rapide (QAT) à un gestionnaire de commande défini par l’application.
En plus du gestionnaire de commande de base pour la fonctionnalité principale de la barre d’outils Accès rapide (QAT), la déclaration de l’attribut d’élément optionnel CustomizeCommandName QuickAccessToolbar fait en sorte que le framework ajoute un élément Plus de commandes à la liste de commandes du menu déroulant de la barre d’outils Accès rapide (QAT) qui nécessite qu’un gestionnaire de commande secondaire soit défini.
Pour une cohérence entre les applications de ruban, il est recommandé que le gestionnaire de commande CustomizeCommandName lance une boîte de dialogue de personnalisation de la barre d’outils Accès rapide (QAT). Comme le framework de ruban ne fournit que le point de lancement dans l’interface utilisateur, l’application est seule responsable de fournir l’implémentation de la boîte de dialogue de personnalisation lorsque la notification de rappel pour cette commande est reçue.
La capture d’écran suivante montre un menu déroulant de la barre d’outils Accès rapide (QAT) avec l’élément de commande Plus de commandes.
La liste des valeurs par défaut de l’application pour la barre d’outils Accès rapide (QAT) est spécifiée via la propriété QuickAccessToolbar.ApplicationDefaults qui identifie une liste par défaut de commandes recommandées, toutes répertoriées dans le menu déroulant de la barre d’outils Accès rapide (QAT).
Pour afficher les commandes de la liste des valeurs par défaut de l’application dans la barre d’outils Accès rapide (QAT), l’attribut ApplicationDefaults.IsChecked de chaque élément de contrôle doit avoir une valeur de true. Les images précédentes montrent les résultats de la définition de cet attribut sur true pour les commandes Sauvegarder, Annuler, et Rétablir.
QuickAccessToolbar.ApplicationDefaults prend en charge trois types de contrôles de ruban : Bouton, Bouton bascule, et Case à cocher.
Remarque
Windows 8 et plus récent : tous les contrôles basés sur une galerie sont pris en charge (ComboBox, InRibbonGallery, SplitButtonGallery, et DropDownGallery).
Les éléments dans un contrôle de galerie peuvent prendre en charge la mise en surbrillance au survol. Pour prendre en charge la mise en surbrillance au survol, la galerie doit être une galerie d’éléments et utiliser une FlowMenuLayout de type VerticalMenuLayout.
L’exemple suivant montre le balisage de base pour un élément QuickAccessToolbar.
Cette section de code montre les déclarations de commande pour un élément Quick Access Toolbar (QAT).
<Command Name="cmdQAT"
Symbol="ID_QAT"
Id="40000"/>
<Command Name="cmdCustomizeQAT"
Symbol="ID_CUSTOM_QAT"
Id="40001"/>
Cette section de code montre les déclarations de contrôle pour un élément Quick Access Toolbar (QAT).
<Ribbon.QuickAccessToolbar>
<QuickAccessToolbar CommandName="cmdQAT"
CustomizeCommandName="cmdCustomizeQAT">
<QuickAccessToolbar.ApplicationDefaults>
<Button CommandName="cmdButton1"/>
<ToggleButton CommandName="cmdMinimize"
ApplicationDefaults.IsChecked="false"/>
</QuickAccessToolbar.ApplicationDefaults>
</QuickAccessToolbar>
</Ribbon.QuickAccessToolbar>
Code
L’application du framework de ruban doit fournir une méthode de rappel du gestionnaire de commande pour manipuler la barre d’outils Accès rapide (QAT). Ce gestionnaire fonctionne de manière similaire aux gestionnaires de galerie de commandes, sauf que la barre d’outils Accès rapide (QAT) ne prend pas en charge les catégories. Pour plus d’informations, veuillez consulter la section Travailler avec les galeries.
La collection de commandes de la barre d’outils Accès rapide (QAT) est récupérée comme un objet IUICollection via la clé de propriété UI_PKEY_ItemsSource. Ajouter des commandes à la barre d’outils Accès rapide (QAT) en temps réel se fait en ajoutant un objet IUISimplePropertySet à IUICollection.
Contrairement aux galeries de commandes, une propriété de type de commande (UI_PKEY_CommandType) n’est pas requise pour l’objet IUISimplePropertySet de la barre d’outils Accès rapide (QAT). Cependant, la commande doit exister dans la liste des valeurs par défaut de l’application de la barre d’outils ou du ruban ; une nouvelle commande ne peut pas être créée en temps réel et ajoutée à la barre d’outils Accès rapide (QAT).
Remarque
L’application du ruban ne peut pas remplacer IUICollection de la barre d’outils Accès rapide (QAT) par un objet de collection personnalisé dérivé de IEnumUnknown.
L’exemple suivant montre une implémentation de base du gestionnaire de commandes de la barre d’outils Accès rapide (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;
}
};
Persistance de la QAT
Les éléments de commande et les paramètres de la barre d’outils Accès rapide (QAT) peuvent être conservés entre les sessions d’application en utilisant les fonctions IUIRibbon::SaveSettingsToStream et IUIRibbon::LoadSettingsFromStream. Pour plus d’informations, veuillez consulter la section Persistance de l’état du ruban.
Propriétés de la barre d’outils Accès rapide
Le framework de ruban définit une collection de clés de propriété pour le contrôle de la barre d’outils Accès rapide (QAT).
En général, une propriété de la barre d’outils Accès rapide (QAT) est mise à jour dans l’interface utilisateur du ruban en invalidant la commande associée au contrôle via un appel à la méthode IUIFramework::InvalidateUICommand. L’événement d’invalidation est géré et les mises à jour des propriétés définies par la méthode de rappel IUICommandHandler::UpdateProperty.
La méthode de rappel IUICommandHandler::UpdateProperty n’est pas exécutée et l’application interrogée pour une valeur de propriété mise à jour jusqu’à ce que la propriété soit requise par le framework. Par exemple, lorsqu’un onglet est activé et qu’un contrôle est révélé dans l’interface utilisateur du ruban, ou lorsqu’un tooltip est affiché.
Remarque
Dans certains cas, une propriété peut être récupérée via la méthode IUIFramework::GetUICommandProperty et définie avec la méthode IUIFramework::SetUICommandProperty.
Le tableau suivant répertorie les clés de propriété associées au contrôle de la barre d’outils Accès rapide (QAT).
| Clé de propriété | Notes |
|---|---|
| UI_PKEY_ItemsSource | Prend en charge IUIFramework::GetUICommandProperty (ne prend pas en charge IUIFramework::SetUICommandProperty).IUIFramework::GetUICommandProperty renvoie un pointeur vers un objet IUICollection représentant les commandes dans la QAT. Chaque commande est identifiée par son ID de commande, qui est obtenu en appelant la méthode IUISimplePropertySet::GetValue et en passant la clé de propriété UI_PKEY_CommandId. |
Il n’y a pas de clés de propriété associées à l’élément de commande Plus de commandes du menu déroulant de la barre d’outils Accès rapide (QAT).