Méthode ICustomDestinationList::AppendCategory (shobjidl_core.h)
Définit une catégorie personnalisée et les destinations qu’elle contient, à inclure dans une liste de raccourcis personnalisée.
Syntaxe
HRESULT AppendCategory(
[in] LPCWSTR pszCategory,
[in] IObjectArray *poa
);
Paramètres
[in] pszCategory
Type : LPCWSTR
Pointeur vers une chaîne qui contient le nom d’affichage de la catégorie personnalisée. Cette chaîne s’affiche dans l’en-tête de la catégorie dans la liste de raccourcis. La chaîne peut contenir directement le nom d’affichage ou il peut s’agir d’une représentation de chaîne indirecte, telle que « @shell32.dll,-1324 », pour utiliser une chaîne stockée. Une chaîne indirecte permet d’afficher l’en-tête de catégorie dans la langue sélectionnée de l’utilisateur.
[in] poa
Type : IObjectArray*
Pointeur vers un IObjectArray qui représente un ou plusieurs objets IShellItem qui représentent les destinations de la catégorie. Certaines destinations de la liste peuvent également être représentées par des objets IShellLink , bien que moins souvent.
Valeur retournée
Type : HRESULT
Retourne S_OK en cas de réussite, ou une valeur d’erreur dans le cas contraire.
Si l’appel à AppendCategory tente d’ajouter un élément figurant dans la liste des destinations supprimées récupérée par l’appel à BeginList qui a lancé la session, l’appel à AppendCategory échoue.
Si AppendCategory tente d’ajouter un IShellItem que l’application n’est pas inscrite pour gérer, l’appel échoue.
AppendCategory peut échouer si un paramètre de confidentialité stratégie de groupe ou de confidentialité utilisateur est activé. Les catégories personnalisées contiennent des éléments spécifiques à l’utilisateur en fonction de l’utilisation individuelle, ce qui n’est pas autorisé dans ces paramètres de confidentialité.
Un stratégie de groupe de confidentialité ou un paramètre de confidentialité utilisateur ne provoque pas d’échec dans une autre méthode ICustomDestinationList. Les tâches ne sont pas spécifiques à l’utilisateur. AppendKnownCategory n’entraîne pas l’affichage des catégories Récents ou Fréquents , car elles n’auront pas de données, mais l’appel de méthode ne retournera pas de code d’échec.
En cas de code d’échec dans AppendCategory causé par le paramètre de confidentialité stratégie de groupe ou de confidentialité utilisateur (E_ACCESSDENIED), l’application doit continuer à mettre à jour les tâches et appeler CommitList.
Si aucune inscription de type de fichier n’a été trouvée pour l’application associée, AppendCategory retourne la 0x80040F03 HRESULT. Cela peut provenir d’une application qui n’inscrit pas le type de fichier qu’elle tente d’ajouter à la liste de raccourcis ou d’un problème dans l’inscription, par exemple en ne fournissant pas l’AppUserModelID lorsque l’application utilise un AppUserModelID explicite.
Remarques
Vous devez appeler BeginList avant d’appeler cette méthode.
Si une application fournit une catégorie personnalisée, cette application assume la responsabilité de la remplir. Le contenu de la catégorie doit toujours être spécifique à l’utilisateur et basé sur l’historique et les actions de l’utilisateur, mais à l’aide d’une catégorie personnalisée, une application peut déterminer ce qu’elle souhaite suivre et ce qu’elle souhaite ignorer. Pour instance, différents scénarios peuvent être impliqués lorsque différentes options d’application sont choisies. Par exemple, un programme audio peut choisir d’inclure uniquement les albums récemment lus et d’ignorer les pistes individuelles récemment lues. Une application peut également simplement avoir un algorithme de suivi de l’utilisation adapté à son utilisation spécifique qui donne de meilleurs résultats que les algorithmes par défaut du système.
Une application peut appeler AppendCategory plusieurs fois dans une session de création de liste pour ajouter plusieurs catégories personnalisées. Dans ce cas, les catégories doivent être conçues de sorte que leur contenu s’exclue mutuellement. Chaque catégorie personnalisée doit être construite autour d’un scénario spécifique afin que les éléments ne soient pas dupliqués entre eux.
Les catégories d’une liste de raccourcis personnalisée, y compris les catégories récentes ou fréquentes connues, sont affichées dans l’ordre dans lequel elles sont ajoutées, les éléments les plus récents étant ajoutés à la fin de la liste. S’il n’y a pas suffisamment d’espace pour afficher toutes les entrées, les dernières entrées de la liste disparaissent d’abord de l’écran. Par conséquent, les catégories les plus importantes doivent être ajoutées en premier pour garantir leur meilleure chance d’être toujours affichées. Les destinations de la catégorie sont affichées dans l’ordre dans lequel elles sont stockées dans l’objet IObjectArray pointé par poa.
L’utilisateur peut décider d’épingler une ou plusieurs des destinations fournies dans la catégorie personnalisée à la liste de raccourcis. La liste des destinations épinglées n’est pas disponible pour l’application, mais la duplication étant empêchée par l’interface utilisateur, aucune action supplémentaire n’est requise de l’application. Visuellement, un élément épinglé se déplace vers la section Épinglée de la liste de raccourcis et disparaît de son emplacement d’origine.
Un appel réussi à AppendCategory ne garantit pas que ces éléments seront affichés. Le nombre de destinations ajoutées par rapport à la valeur pointée par le paramètre pcMinItems dans ICustomDestinationList::BeginList n’est pas affiché. La catégorie épinglée prend la priorité sur toutes les autres listes de destination. La liste épinglée s’affiche, puis l’espace restant est alloué aux autres listes de destination. Il est possible pour un utilisateur d’épingler suffisamment de destinations à la liste de raccourcis pour empêcher l’affichage d’autres destinations. D’autres facteurs, tels qu’une résolution d’écran réduite ou une taille de police accrue, peuvent également entraîner la troncation des destinations fournies par l’application de la liste. L’application n’a aucun moyen de prédire ces situations et n’est pas avertie lorsqu’elles se produisent. L’application doit simplement savoir que la possibilité existe. Étant donné que la troncation de la ou des listes de destination se produit de bas en haut, l’application doit placer ses catégories et destinations les plus importantes en haut de la liste afin qu’elles aient les meilleures chances d’être affichées.
Au cours d’une session démarrée avec BeginList et se terminant par CommitList, vous pouvez appeler AppendCategory plusieurs fois. Si l’un de ces appels échoue en raison d’une tentative d’ajout d’une catégorie contenant un élément dans la liste des éléments supprimés, l’appel à CommitList n’efface pas la liste des éléments supprimés. Pour que la liste des éléments supprimés soit effacée, tous les appels à AppendCategory dans une session doivent être retournés avec succès.
Les instances IShellLink fournies via le IObjectArray pointé par poa doivent fournir les éléments suivants :
- Pointeur vers une liste d’identificateurs d’élément (PIDL) (SetIDList) ou le chemin cible (SetPath ou SetRelativePath)
- Arguments de ligne de commande (SetArguments)
- Emplacement de l’icône (SetIconLocation)
Si vous le souhaitez, le champ de description (SetDescription) peut être défini pour fournir une info-bulle personnalisée pour l’élément dans la liste de raccourcis.
Configuration requise
| Client minimal pris en charge | Windows 7 [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 R2 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | shobjidl_core.h (inclure Shobjidl.h) |
| Bibliothèque | Shell32.lib |
| DLL | Shell32.dll (version 6.1 ou ultérieure) |
Voir aussi
ICustomDestinationList::AddUserTasks
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