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 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) se trouve 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 qui contient l’ensemble complet des commandes de barre d’outils d’accès rapide (QAT) par défaut (qu’elles soient masquées ou affichées dans la barre d’outils Accès rapide (QAT) et un ensemble d’options de barre d’outils accès rapide (QAT) et du ruban.
La capture d’écran suivante montre un exemple de barre d’outils Accès rapide au ruban (QAT).
La barre d’outils Accès rapide (QAT) se compose d’une combinaison de 20 commandes maximum spécifiées par l’application (appelée liste des valeurs par défaut de l’application) ou 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.
Notes
Bien que presque tous les contrôles du ruban autorisent l’ajout de la commande associée à la barre d’outils Accès rapide (QAT) par le biais du menu contextuel illustré dans la capture d’écran suivante, les commandes exposées dans une fenêtre contextuelle ne fournissent pas ce menu contextuel.
Implémenter la barre d’outils Accès rapide
Comme avec tous les contrôles d’infrastructure du 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 ses fonctionnalités.
balisage
Le contrôle QAT (Quick Access Toolbar) 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 commandes défini par l’application.
En plus du gestionnaire de commandes de base pour la fonctionnalité principale de barre d’outils Accès rapide (QAT), la déclaration de l’attribut facultatif de l’élément CustomizeCommandNameQuickAccessToolbar entraîne l’infrastructure à ajouter un élément Autres commandes à la liste des commandes du menu déroulant Barre d’outils Accès rapide (QAT) qui nécessite la définition d’un gestionnaire de commandes secondaire.
Pour assurer la cohérence entre les applications du ruban, il est recommandé que le gestionnaire de commandes CustomizeCommandName lance une boîte de dialogue de personnalisation de la barre d’outils Accès rapide (QAT). Étant donné que l’infrastructure du ruban fournit uniquement 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 lors de la réception de la notification de rappel pour cette commande.
La capture d’écran suivante montre un menu déroulant Barre d’outils Accès rapide (QAT) avec l’élément Commandes supplémentaires .
La liste des valeurs par défaut de l’application pour la barre d’outils Accès rapide (QAT) est spécifiée par le biais de la propriété QuickAccessToolbar.ApplicationDefaults qui identifie une liste par défaut des commandes recommandées, toutes répertoriées dans le menu déroulant 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 la valeur true. Les images précédentes montrent les résultats de la définition de cet attribut true sur pour les commandes Enregistrer, Annuler et Rétablir .
QuickAccessToolbar.ApplicationDefaults prend en charge trois types de contrôles de ruban : Button, Toggle Button et Check Box.
Notes
Windows 8 et versions ultérieures : tous les contrôles basés sur la galerie sont pris en charge (ComboBox, InRibbonGallery, SplitButtonGallery et DropDownGallery).
Les éléments d’un contrôle de galerie peuvent prendre en charge la mise en surbrillance lors du pointage. Pour prendre en charge la mise en surbrillance du pointage, la galerie doit être une galerie d’éléments et utiliser un FlowMenuLayout de type VerticalMenuLayout.
L’exemple suivant illustre le balisage de base d’un élément QuickAccessToolbar .
Cette section de code présente les déclarations de commande d’un élément QAT (Quick Access Toolbar).
<Command Name="cmdQAT"
Symbol="ID_QAT"
Id="40000"/>
<Command Name="cmdCustomizeQAT"
Symbol="ID_CUSTOM_QAT"
Id="40001"/>
Cette section de code présente les déclarations de contrôle d’un élément QAT (Quick Access Toolbar).
<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 d’infrastructure ribbon doit fournir une méthode de rappel du gestionnaire de commandes pour manipuler la barre d’outils Accès rapide (QAT). Ce gestionnaire fonctionne de la même manière que les gestionnaires de la 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, consultez Utilisation des galeries.
La collection de commandes QAT (Quick Access Toolbar) est récupérée en tant qu’objet IUICollection via la clé de propriété UI_PKEY_ItemsSource . L’ajout de commandes à la barre d’outils Accès rapide (QAT) au moment de l’exécution s’effectue en ajoutant un objet IUISimplePropertySet à IUICollection.
Contrairement aux galeries de commandes, une propriété de type commande (UI_PKEY_CommandType) n’est pas requise pour l’objet IUISimplePropertySet de la barre d’outils d’accès rapide (QAT). Toutefois, la commande doit exister dans la liste des valeurs par défaut de l’application du ruban ou de la barre d’outils Accès rapide (QAT) ; Une nouvelle commande ne peut pas être créée au moment de l’exécution et ajoutée à la barre d’outils Accès rapide (QAT).
Notes
L’application Ribbon ne peut pas remplacer la barre d’outils d’accès rapide (QAT) IUICollection par un objet de collection personnalisé dérivé de IEnumUnknown.
L’exemple suivant illustre une implémentation de gestionnaire de commandes QAT (Quick Access Toolbar) de base.
/* 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 QAT
Les éléments et paramètres de commande QAT (Quick Access Toolbar) peuvent être conservés entre les sessions d’application à l’aide des fonctions IUIRibbon::SaveSettingsToStream et IUIRibbon::LoadSettingsFromStream . Pour plus d’informations, consultez Persistance de l’état du ruban.
Propriétés de la barre d’outils Accès rapide
L’infrastructure du ruban définit une collection de clés de propriété pour le contrôle Barre d’outils Accès rapide (QAT).
En règle générale, une propriété QAT (Quick Access Toolbar) 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 la propriété est mise à jour définie par la méthode de rappel IUICommandHandler::UpdateProperty .
La méthode de rappel IUICommandHandler::UpdateProperty n’est pas exécutée et l’application a demandé une valeur de propriété mise à jour, jusqu’à ce que la propriété soit requise par l’infrastructure. Par exemple, lorsqu’un onglet est activé et qu’un contrôle est révélé dans l’interface utilisateur du ruban, ou lorsqu’une info-bulle est affichée.
Notes
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 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 retourne un pointeur vers un objet IUICollection qui représente les commandes dans le QAT. Chaque commande est identifiée par son ID de commande, qui est obtenu en appelant la méthode IUISimplePropertySet::GetValue et en transmettant la clé de propriété UI_PKEY_CommandId. |
Aucune clé de propriété n’est associée à l’élément Commande Plus de commandes du menu déroulant Barre d’outils Accès rapide (QAT)
Rubriques connexes
Commentaires
Bientôt disponible : Tout au long de 2024, nous allons supprimer progressivement GitHub Issues comme mécanisme de commentaires pour le contenu et le remplacer par un nouveau système de commentaires. Pour plus d’informations, consultez https://aka.ms/ContentUserFeedback.
Envoyer et afficher des commentaires pour