Barra di accesso rapido
La barra di accesso rapido (QAT) è una barra degli strumenti piccola e personalizzabile che espone un set di comandi specificati dall'applicazione o selezionati dall'utente.
- Introduzione
- Implementare la barra di accesso rapido
- Persistenza QAT
- Proprietà della barra di accesso rapido
- Argomenti correlati
Introduzione
Per impostazione predefinita, la barra di accesso rapido (QAT) si trova nella barra del titolo della finestra dell'applicazione, ma può essere configurata per la visualizzazione sotto la barra multifunzione. Oltre a esporre i comandi, la barra di accesso rapido (QAT) include anche un menu a discesa personalizzabile che contiene il set completo di comandi predefiniti della barra di accesso rapido (QAT) (nascosti o visualizzati nella barra di accesso rapido (QAT) e un set di opzioni della barra di accesso rapido (QAT) e barra multifunzione.
La schermata seguente mostra un esempio della barra degli strumenti di accesso rapido della barra multifunzione (QAT).
La barra di accesso rapido (QAT) è costituita da una combinazione di un massimo di 20 comandi specificati dall'applicazione (noti come elenco di impostazioni predefinite dell'applicazione) o selezionati dall'utente. La barra di accesso rapido (QAT) può contenere comandi univoci che non sono disponibili altrove nell'interfaccia utente della barra multifunzione.
Nota
Anche se quasi tutti i controlli della barra multifunzione consentono di aggiungere il comando associato alla barra di accesso rapido (QAT) tramite il menu di scelta rapida illustrato nella schermata seguente, i comandi esposti in un popup di scelta rapida non forniscono questo menu di scelta rapida.
Implementare la barra di accesso rapido
Come per tutti i controlli framework della barra multifunzione di Windows, sfruttare appieno la barra di accesso rapido (QAT) richiede sia un componente di markup che controlla la presentazione all'interno della barra multifunzione che un componente di codice che ne controlla la funzionalità.
markup
Il controllo Barra di accesso rapido (QAT) viene dichiarato e associato a un ID comando, nel markup tramite l'elemento QuickAccessToolbar . L'ID comando viene usato per identificare e associare la barra di accesso rapido (QAT) a un gestore di comandi definito dall'applicazione.
Oltre al gestore dei comandi di base per la funzionalità QAT (Quick Access Toolbar) principale, dichiarando l'attributo facoltativo dell'elemento CustomizeCommandNameQuickAccessToolbar , il framework aggiunge un elemento More Commands all'elenco a discesa Command del menu a discesa Barra di accesso rapido (QAT) che richiede la definizione di un gestore comandi secondario.
Per garantire la coerenza tra le applicazioni della barra multifunzione, è consigliabile che il gestore del comando CustomizeCommandName avvii una finestra di dialogo di personalizzazione della barra di accesso rapido (QAT). Poiché il framework della barra multifunzione fornisce solo il punto di avvio nell'interfaccia utente, l'applicazione è responsabile esclusivamente di fornire l'implementazione della finestra di dialogo di personalizzazione quando viene ricevuta la notifica di callback per questo comando.
La schermata seguente mostra un menu a discesa Barra di accesso rapido (QAT) con l'elemento Altro comando comandi .
L'elenco delle impostazioni predefinite dell'applicazione per la barra di accesso rapido (QAT) viene specificato tramite la proprietà QuickAccessToolbar.ApplicationDefaults che identifica un elenco predefinito di comandi consigliati, tutti elencati nel menu a discesa Barra di accesso rapido (QAT).
Per visualizzare i comandi dall'elenco delle impostazioni predefinite dell'applicazione nella barra degli strumenti QAT (Quick Access Toolbar), l'attributo ApplicationDefaults.IsChecked di ogni elemento del controllo deve avere un valore .true Le immagini precedenti mostrano i risultati dell'impostazione di questo attributo su true per i comandi Salva, Annulla e Ripeti .
QuickAccessToolbar.ApplicationDefaults supporta tre tipi di controlli della barra multifunzione: Button, Toggle Button e Check Box.
Nota
Windows 8 e versioni successive: sono supportati tutti i controlli basati sulla raccolta (ComboBox, InRibbonGallery, SplitButtonGallery e DropDownGallery).
Gli elementi in un controllo raccolta possono supportare l'evidenziazione al passaggio del mouse. Per supportare l'evidenziazione del passaggio del mouse, la raccolta deve essere una raccolta di elementi e usare un oggetto FlowMenuLayout di tipo VerticalMenuLayout.
Nell'esempio seguente viene illustrato il markup di base per un elemento QuickAccessToolbar .
Questa sezione di codice mostra le dichiarazioni Command per un elemento QAT (Quick Access Toolbar).
<Command Name="cmdQAT"
Symbol="ID_QAT"
Id="40000"/>
<Command Name="cmdCustomizeQAT"
Symbol="ID_CUSTOM_QAT"
Id="40001"/>
Questa sezione di codice mostra le dichiarazioni di controllo per un elemento 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>
Codice
L'applicazione framework della barra multifunzione deve fornire un metodo di callback del gestore comandi per modificare la barra di accesso rapido (QAT). Questo gestore funziona in modo simile ai gestori della raccolta comandi, ad eccezione del fatto che la barra di accesso rapido (QAT) non supporta le categorie. Per altre informazioni, vedere Uso delle raccolte.
L'insieme Quick Access Toolbar (QAT) Command viene recuperato come oggetto IUICollection tramite la chiave della proprietà UI_PKEY_ItemsSource . L'aggiunta di comandi alla barra di accesso rapido (QAT) in fase di esecuzione viene eseguita aggiungendo un oggetto IUISimplePropertySet a IUICollection.
A differenza delle raccolte di comandi, non è necessaria una proprietà del tipo di comando (UI_PKEY_CommandType) per l'oggetto IUISimplePropertySet (Quick Access Toolbar). Tuttavia, il comando deve esistere nella barra multifunzione o nell'elenco delle impostazioni predefinite dell'applicazione QAT (Quick Access Toolbar). Non è possibile creare un nuovo comando in fase di esecuzione e aggiungerlo alla barra di accesso rapido (QAT).
Nota
L'applicazione della barra multifunzione non può sostituire IUICollection (Quick Access Toolbar) con un oggetto raccolta personalizzato derivato da IEnumUnknown.
Nell'esempio seguente viene illustrata un'implementazione di base del gestore dei comandi QAT (Quick Access Toolbar).
/* 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;
}
};
Persistenza QAT
Gli elementi e le impostazioni dei comandi della barra di accesso rapido (QAT) possono essere mantenuti tra le sessioni dell'applicazione usando le funzioni IUIRibbon::SaveSettingsToStream e IUIRibbon::LoadSettingsFromStream . Per altre informazioni, vedere Salvataggio permanente dello stato della barra multifunzione.
Proprietà della barra di accesso rapido
Il framework della barra multifunzione definisce una raccolta di chiavi di proprietà per il controllo QAT (Quick Access Toolbar).
In genere, una proprietà QAT (Quick Access Toolbar) viene aggiornata nell'interfaccia utente della barra multifunzione invalidando il comando associato al controllo tramite una chiamata al metodo IUIFramework::InvalidateUICommand . L'evento di invalidazione viene gestito e le proprietà vengono aggiornate definite dal metodo di callback IUICommandHandler::UpdateProperty .
Il metodo di callback IUICommandHandler::UpdateProperty non viene eseguito e l'applicazione ha eseguito una query per un valore di proprietà aggiornato, fino a quando la proprietà non è richiesta dal framework. Ad esempio, quando viene attivata una scheda e viene visualizzato un controllo nell'interfaccia utente della barra multifunzione o quando viene visualizzata una descrizione comando.
Nota
In alcuni casi, una proprietà può essere recuperata tramite il metodo IUIFramework::GetUICommandProperty e impostata con il metodo IUIFramework::SetUICommandProperty .
Nella tabella seguente sono elencate le chiavi di proprietà associate al controllo QaT (Quick Access Toolbar).
| Chiave proprietà | Note |
|---|---|
| UI_PKEY_ItemsSource | Supporta IUIFramework::GetUICommandProperty (non supporta IUIFramework::SetUICommandProperty). IUIFramework::GetUICommandProperty restituisce un puntatore a un oggetto IUICollection che rappresenta i comandi in QAT. Ogni comando viene identificato dal relativo ID comando, ottenuto chiamando il metodo IUISimplePropertySet::GetValue e passando la chiave della proprietà UI_PKEY_CommandId. |
Nessuna chiave di proprietà associata alla voce Altri comandi del menu a discesa Barra di accesso rapido (QAT)
Argomenti correlati
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per