ICustomDestinationList::AppendCategory-Methode (shobjidl_core.h)

  • Artikel

Definiert eine benutzerdefinierte Kategorie und die darin enthaltenen Ziele zur Aufnahme in eine benutzerdefinierte Sprungliste.

Syntax

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

Parameter

[in] pszCategory

Typ: LPCWSTR

Ein Zeiger auf eine Zeichenfolge, die den Anzeigenamen der benutzerdefinierten Kategorie enthält. Diese Zeichenfolge wird in der Kopfzeile der Kategorie in der Sprungliste angezeigt. Die Zeichenfolge kann direkt den Anzeigenamen enthalten, oder es kann sich um eine indirekte Zeichenfolgendarstellung wie "@shell32.dll,-1324" handeln, um eine gespeicherte Zeichenfolge zu verwenden. Eine indirekte Zeichenfolge ermöglicht die Anzeige des Kategorieheaders in der ausgewählten Sprache des Benutzers.

Hinweis Jede benutzerdefinierte Kategorie muss einen eindeutigen Namen haben. Doppelte Kategorienamen verursachen Präsentationsprobleme in der Sprungliste.
 

[in] poa

Typ: IObjectArray*

Ein Zeiger auf ein IObjectArray , das ein oder mehrere IShellItem-Objekte darstellt, die die Ziele in der Kategorie darstellen. Einige Ziele in der Liste werden möglicherweise auch durch IShellLink-Objekte dargestellt, wenn auch seltener.

Hinweis Jeder hier verwendete IShellLink muss eine Argumentliste über SetArguments deklarieren. Das Hinzufügen eines IShellLink-Objekts ohne Argumente zu einer benutzerdefinierten Kategorie wird nicht unterstützt, da ein Benutzer diesen Elementtyp nicht aus einer Sprungliste anheften oder lösen kann, noch kann er hinzugefügt oder entfernt werden.
 

Rückgabewert

Typ: HRESULT

Gibt bei erfolgreicher Ausführung S_OK oder andernfalls einen Fehlerwert zurück.

Wenn der Aufruf von AppendCategory versucht, ein Element hinzuzufügen, das sich in der Liste der entfernten Ziele befindet, das vom Aufruf von BeginList abgerufen wurde, der die Sitzung initiiert hat, schlägt der Aufruf von AppendCategory fehl.

Wenn AppendCategory versucht, ein IShellItem hinzuzufügen, das die Anwendung nicht für die Verarbeitung registriert ist, schlägt der Aufruf fehl.

AppendCategory kann fehlschlagen, wenn eine Datenschutzeinstellung Gruppenrichtlinie oder Benutzerdatenschutz aktiviert ist. Benutzerdefinierte Kategorien enthalten benutzerspezifische Elemente, die auf der individuellen Nutzung basieren, was unter diesen Datenschutzeinstellungen nicht zulässig ist.

Eine Einstellung zum Datenschutz Gruppenrichtlinie oder Benutzerdatenschutz führt nicht zu einem Fehler in einer anderen ICustomDestinationList-Methode. Aufgaben sind nicht benutzerspezifisch. AppendKnownCategory führt nicht zur Anzeige der Kategorien Zuletzt verwendet oder Häufig , da diese keine Daten enthalten, aber der Methodenaufruf gibt keinen Fehlercode zurück.

Im Falle eines Fehlercodes in AppendCategory, der durch datenschutzbedingte Gruppenrichtlinie oder Benutzerdatenschutzeinstellungen (E_ACCESSDENIED) verursacht wird, sollte die Anwendung weiterhin Aufgaben aktualisieren und CommitList aufrufen.

Wenn keine Dateitypregistrierung für die zugeordnete Anwendung gefunden wurde, gibt AppendCategory HRESULT 0x80040F03 zurück. Dies kann darauf resultieren, dass eine Anwendung den Dateityp nicht registriert, den sie der Sprungliste hinzufügen möchte, oder aus einem Problem in der Registrierung, z. B. dass die AppUserModelID nicht bereitgestellt wird, wenn die Anwendung eine explizite AppUserModelID verwendet.

Hinweise

Sie müssen BeginList aufrufen, bevor Sie diese Methode aufrufen.

Wenn eine Anwendung eine benutzerdefinierte Kategorie bereitstellt, übernimmt diese Anwendung die Verantwortung für das Auffüllen. Der Kategorieinhalt sollte weiterhin benutzerspezifisch sein und auf dem Verlauf und den Aktionen des Benutzers basieren, aber mithilfe einer benutzerdefinierten Kategorie kann eine Anwendung bestimmen, was nachverfolgt werden soll und was ignoriert werden soll. Für instance können verschiedene Szenarien einbezogen werden, wenn unterschiedliche Anwendungsoptionen ausgewählt werden. Beispielsweise kann ein Audioprogramm festlegen, dass nur kürzlich wiedergegebene Alben enthalten sind und kürzlich wiedergegebene einzelne Titel ignoriert werden. Eine Anwendung kann auch einfach über einen auf ihre spezifische Verwendung zugeschnittenen Nutzungsnachverfolgungsalgorithmus verfügen, der bessere Ergebnisse liefert als die Standardalgorithmen des Systems.

Eine Anwendung kann AppendCategory in einer Listenerstellungssitzung mehrmals aufrufen, um mehrere benutzerdefinierte Kategorien hinzuzufügen. In diesem Fall sollten die Kategorien so gestaltet werden, dass sich ihre Inhalte gegenseitig ausschließen. Jede benutzerdefinierte Kategorie sollte um ein bestimmtes Szenario herum erstellt werden, sodass Elemente nicht zwischen ihnen dupliziert werden.

Kategorien in einer benutzerdefinierten Sprungliste, einschließlich der bekannten Kategorien Zuletzt oder Häufig , werden in der Reihenfolge angezeigt, in der sie hinzugefügt werden, wobei die letzten Elemente am Ende der Liste hinzugefügt werden. Wenn nicht genügend Platz zum Anzeigen aller Einträge vorhanden ist, werden die letzten Einträge in der Liste zuerst vom Bildschirm entfernt. Daher sollten zuerst die wichtigsten Kategorien hinzugefügt werden, um ihre beste Chance zu gewährleisten, immer angezeigt zu werden. Ziele innerhalb der Kategorie werden in der Reihenfolge angezeigt, in der sie im IObjectArray-Objekt gespeichert werden, auf das poa verweist.

Der Benutzer entscheidet sich möglicherweise, eines oder mehrere der in der benutzerdefinierten Kategorie bereitgestellten Ziele an die Sprungliste anzuheften. Die Liste der angehefteten Ziele ist für die Anwendung nicht verfügbar. Duplizierung wird jedoch durch die Benutzeroberfläche verhindert, sodass keine zusätzliche Aktion der Anwendung erforderlich ist. Visuell wechselt ein angeheftetes Element in den Angehefteten Abschnitt der Sprungliste und verschwindet von seinem ursprünglichen Speicherort.

Ein erfolgreicher Aufruf von AppendCategory garantiert nicht, dass diese Elemente angezeigt werden. Eine beliebige Anzahl von Zielen, die über den Wert hinzugefügt werden, auf den der parameter pcMinItems in ICustomDestinationList::BeginList verweist, werden nicht angezeigt. Die Angeheftete Kategorie hat Vorrang vor allen anderen Ziellisten. Die Angeheftete Liste wird angezeigt, dann wird der verbleibende Speicherplatz den anderen Ziellisten zugeordnet. Es ist möglich, dass ein Benutzer genügend Ziele an die Sprungliste anheften kann, damit keine anderen Ziele angezeigt werden. Andere Faktoren, z. B. eine reduzierte Bildschirmauflösung oder ein erhöhter Schriftgrad, können auch dazu führen, dass von der Anwendung bereitgestellte Ziele aus der Liste abgeschnitten werden. Die Anwendung hat keine Möglichkeit, diese Situationen vorherzusagen und wird nicht benachrichtigt, wenn sie auftreten. Die Anwendung muss sich lediglich darüber im Klaren sein, dass die Möglichkeit besteht. Da das Abschneiden der Zielliste oder -listen von unten nach oben erfolgt, sollte die Anwendung die wichtigsten Kategorien und Ziele an den Anfang der Liste setzen, damit sie die besten Chancen haben, angezeigt zu werden.

Während einer Sitzung, die mit BeginList beginnt und mit CommitList endet, können Sie AppendCategory mehrmals aufrufen. Wenn einer dieser Aufrufe fehlschlägt, weil versucht wird, eine Kategorie hinzuzufügen, die ein Element in der Liste der entfernten Elemente enthält, wird die Liste der entfernten Elemente durch den Aufruf von CommitList nicht gelöscht. Damit die Liste der entfernten Elemente gelöscht wird, müssen alle Aufrufe von AppendCategory in einer Sitzung erfolgreich zurückgegeben werden.

IShellLink-Instanzen , die über das IObjectArray bereitgestellt werden, auf das von poa verwiesen wird, müssen Folgendes bereitstellen:

Der Anzeigename muss über die System.Title-Eigenschaft (PKEY_Title) des Elements festgelegt werden. Die -Eigenschaft kann den Anzeigenamen direkt enthalten, oder es kann sich um eine indirekte Zeichenfolgendarstellung wie "@shell32.dll,-1324" handeln, um eine gespeicherte Zeichenfolge zu verwenden. Eine indirekte Zeichenfolge ermöglicht die Anzeige des Elementnamens in der ausgewählten Sprache des Benutzers.

Optional kann das Beschreibungsfeld (SetDescription) so festgelegt werden, dass eine benutzerdefinierte QuickInfo für das Element in der Sprungliste bereitgestellt wird.

Anforderungen

   
Unterstützte Mindestversion (Client) Windows 7 [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2008 R2 [nur Desktop-Apps]
Zielplattform Windows
Kopfzeile shobjidl_core.h (shobjidl.h einschließen)
Bibliothek Shell32.lib
DLL Shell32.dll (Version 6.1 oder höher)

Weitere Informationen

ICustomDestinationList

ICustomDestinationList::AddUserTasks

ICustomDestinationList::AppendKnownCategory

Taskleistenerweiterungen