Metodo ICustomDestinationList::AppendCategory (shobjidl_core.h)

  • Articolo

Definisce una categoria personalizzata e le destinazioni che contiene, per l'inclusione in una jump list personalizzata.

Sintassi

HRESULT AppendCategory(
  [in] LPCWSTR      pszCategory,
  [in] IObjectArray *poa
);

Parametri

[in] pszCategory

Tipo: LPCWSTR

Puntatore a una stringa contenente il nome visualizzato della categoria personalizzata. Questa stringa viene visualizzata nell'intestazione della categoria nella Jump List. La stringa può contenere direttamente il nome visualizzato oppure può essere una rappresentazione di stringa indiretta, ad esempio "@shell32.dll,-1324", per usare una stringa archiviata. Una stringa indiretta consente di visualizzare l'intestazione della categoria nella lingua selezionata dell'utente.

Nota Ogni categoria personalizzata deve avere un nome univoco. I nomi di categoria duplicati causeranno problemi di presentazione nella Jump List.
 

[in] poa

Tipo: IObjectArray*

Puntatore a un oggetto IObjectArray che rappresenta uno o più oggetti IShellItem che rappresentano le destinazioni nella categoria. Alcune destinazioni nell'elenco potrebbero anche essere rappresentate da oggetti IShellLink , anche se meno spesso.

Nota Qualsiasi IShellLink usato qui deve dichiarare un elenco di argomenti tramite SetArguments. L'aggiunta di un oggetto IShellLink senza argomenti a una categoria personalizzata non è supportata perché un utente non può aggiungere o rimuovere questo tipo di elemento da un jump list, né può essere aggiunto o rimosso.
 

Valore restituito

Tipo: HRESULT

Restituisce S_OK in caso di esito positivo o un valore di errore in caso contrario.

Se la chiamata a AppendCategory tenta di aggiungere un elemento incluso nell'elenco delle destinazioni rimosse recuperato dalla chiamata a BeginList che ha avviato la sessione, la chiamata a AppendCategory ha esito negativo.

Se AppendCategory tenta di aggiungere un oggetto IShellItem che l'applicazione non è registrata per la gestione, la chiamata ha esito negativo.

AppendCategory può avere esito negativo se è attiva un'impostazione di privacy Criteri di gruppo o privacy dell'utente. Le categorie personalizzate contengono elementi specifici dell'utente in base all'utilizzo individuale, che non è consentito nelle impostazioni di privacy.

Un'impostazione di privacy Criteri di gruppo o privacy dell'utente non causerà un errore in nessun altro metodo ICustomDestinationList. Le attività non sono specifiche dell'utente. AppendKnownCategory non genererà la visualizzazione delle categorie Recenti o Frequenti perché non avranno dati, ma la chiamata al metodo non restituirà un codice di errore.

In caso di codice di errore in AppendCategory causato dall'impostazione di privacy Criteri di gruppo o privacy dell'utente (E_ACCESSDENIED), l'applicazione deve continuare ad aggiornare le attività e chiamare CommitList.

Se non è stata trovata alcuna registrazione del tipo di file per l'applicazione associata, AppendCategory restituisce HRESULT 0x80040F03. Ciò può derivare da un'applicazione che non registra il tipo di file che sta tentando di aggiungere alla Jump List o da un problema nella registrazione, ad esempio non fornendo AppUserModelID quando l'applicazione usa un AppUserModelID esplicito.

Commenti

È necessario chiamare BeginList prima di chiamare questo metodo.

Se un'applicazione fornisce una categoria personalizzata, tale applicazione assume la responsabilità di popolarla. Il contenuto della categoria deve essere ancora specifico dell'utente e in base alla cronologia e alle azioni dell'utente, ma usando una categoria personalizzata un'applicazione può determinare cosa vuole tenere traccia e cosa vuole ignorare. Ad esempio, possono essere coinvolti scenari diversi quando vengono scelte diverse opzioni dell'applicazione. Ad esempio, un programma audio potrebbe scegliere di includere solo album riprodotti di recente e ignorare i singoli brani riprodotti di recente. Un'applicazione potrebbe anche avere semplicemente un algoritmo di rilevamento dell'utilizzo personalizzato in base all'uso specifico che offre risultati migliori rispetto agli algoritmi predefiniti del sistema.

Un'applicazione può chiamare AppendCategory più volte in una sessione di compilazione di elenchi per aggiungere più categorie personalizzate. In questo caso, le categorie devono essere progettate in modo che il loro contenuto si escludono a vicenda. Ogni categoria personalizzata deve essere compilata in uno scenario specifico in modo che gli elementi non vengano duplicati tra di essi.

Le categorie in un jump list personalizzato, incluse le categorie recenti o frequenti note, vengono visualizzate nell'ordine in cui vengono aggiunte, con gli elementi più recenti aggiunti alla fine dell'elenco. Se non è presente spazio sufficiente per visualizzare tutte le voci, le ultime voci dell'elenco scompaiono prima dalla schermata. Pertanto, le categorie più importanti devono essere aggiunte prima per garantire la migliore probabilità di essere sempre visualizzate. Le destinazioni all'interno della categoria vengono visualizzate nell'ordine in cui sono archiviate nell'oggetto IObjectArray a cui punta poa.

L'utente potrebbe decidere di aggiungere una o più delle destinazioni fornite nella categoria personalizzata alla Jump List. L'elenco delle destinazioni aggiunte non è disponibile per l'applicazione, ma la duplicazione viene impedita dall'interfaccia utente, quindi non è necessaria alcuna azione aggiuntiva per l'applicazione. Visivamente, un elemento aggiunto passa alla sezione Aggiunta della Jump List e scompare dalla posizione originale.

Una chiamata riuscita a AppendCategory non garantisce che tali elementi vengano visualizzati. Qualsiasi numero di destinazioni aggiunte sul valore a cui punta il parametro pcMinItems in ICustomDestinationList::BeginList non viene visualizzato. La categoria Aggiunta ha la priorità su tutti gli altri elenchi di destinazione. Viene visualizzato l'elenco Elementi aggiunti , quindi lo spazio rimanente viene allocato agli altri elenchi di destinazione. È possibile che un utente assegnare destinazioni sufficienti alla Jump List per impedire la visualizzazione di altre destinazioni. Altri fattori, ad esempio una risoluzione ridotta dello schermo o una maggiore dimensione del carattere, possono anche causare il troncamento delle destinazioni fornite dall'applicazione dall'elenco. L'applicazione non ha modo di prevedere queste situazioni e non riceve alcuna notifica quando si verificano. L'applicazione deve solo tenere presente che esiste la possibilità. Poiché il troncamento dell'elenco di destinazione o degli elenchi si verifica dal basso verso l'alto, l'applicazione deve inserire le categorie e le destinazioni più importanti nella parte superiore dell'elenco in modo che abbiano la migliore probabilità di essere visualizzati.

Durante una sessione avviata con BeginList e termina con CommitList, è possibile chiamare AppendCategory più volte. Se una di queste chiamate ha esito negativo a causa di un tentativo di aggiungere una categoria contenente un elemento nell'elenco elementi rimossi, la chiamata a CommitList non cancella l'elenco elementi rimossi. Affinché l'elenco di elementi rimossi venga cancellato, tutte le chiamate a AppendCategory in una sessione devono essere restituite correttamente.

Le istanze di IShellLink fornite tramite IObjectArray a cui punta poa devono fornire quanto segue:

Il nome visualizzato deve essere impostato tramite la proprietà System.Title (PKEY_Title) dell'elemento. La proprietà può contenere direttamente il nome visualizzato oppure può essere una rappresentazione di stringa indiretta, ad esempio "@shell32.dll,-1324", per usare una stringa archiviata. Una stringa indiretta consente di visualizzare il nome dell'elemento nella lingua selezionata dell'utente.

Facoltativamente, il campo descrizione (SetDescription) può essere impostato per fornire una descrizione comando personalizzata per l'elemento nella Jump List.

Requisiti

   
Client minimo supportato Windows 7 [solo app desktop]
Server minimo supportato Windows Server 2008 R2 [solo app desktop]
Piattaforma di destinazione Windows
Intestazione shobjidl_core.h (include Shobjidl.h)
Libreria Shell32.lib
DLL Shell32.dll (versione 6.1 o successiva)

Vedi anche

ICustomDestinationList

ICustomDestinationList::AddUserTasks

ICustomDestinationList::AppendKnownCategory

Estensioni della barra delle applicazioni