Método ICustomDestinationList::AppendCategory (shobjidl_core.h)

  • Artículo

Define una categoría personalizada y los destinos que contiene, para su inclusión en una lista de accesos directos personalizado.

Sintaxis

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

Parámetros

[in] pszCategory

Tipo: LPCWSTR

Puntero a una cadena que contiene el nombre para mostrar de la categoría personalizada. Esta cadena se muestra en el encabezado de la categoría en la lista de accesos directos. La cadena puede contener directamente el nombre para mostrar o puede ser una representación indirecta de cadena, como "@shell32.dll,-1324", para usar una cadena almacenada. Una cadena indirecta permite mostrar el encabezado de categoría en el idioma seleccionado del usuario.

Nota Cada categoría personalizada debe tener un nombre único. Los nombres de categoría duplicados provocarán problemas de presentación en la lista de accesos directos.
 

[in] poa

Tipo: IObjectArray*

Puntero a IObjectArray que representa uno o varios objetos IShellItem que representan los destinos de la categoría. Algunos destinos de la lista también se pueden representar mediante objetos IShellLink , aunque con menos frecuencia.

Nota Cualquier IShellLink usado aquí debe declarar una lista de argumentos a través de SetArguments. No se admite agregar un objeto IShellLink sin argumentos a una categoría personalizada, ya que un usuario no puede anclar ni desanclar este tipo de elemento de una lista de accesos directos, ni se pueden agregar ni quitar.
 

Valor devuelto

Tipo: HRESULT

Devuelve S_OK si se realiza correctamente; de lo contrario, un valor de error.

Si la llamada a AppendCategory intenta agregar un elemento que se encuentra en la lista de destinos quitados recuperada por la llamada a BeginList que inició la sesión, se produce un error en la llamada a AppendCategory .

Si AppendCategory intenta agregar un objeto IShellItem que la aplicación no está registrada para controlar, se produce un error en la llamada.

AppendCategory puede producir un error si hay una configuración de privacidad directiva de grupo o de privacidad del usuario activada. Las categorías personalizadas contienen elementos específicos del usuario en función del uso individual, que no se permite en esa configuración de privacidad.

Una configuración de privacidad directiva de grupo o privacidad del usuario no provocará un error en ningún otro método ICustomDestinationList. Las tareas no son específicas del usuario. AppendKnownCategory no dará lugar a la presentación de las categorías Recientes o Frecuentes porque no tendrán datos, pero la llamada al método no devolverá un código de error.

En el caso de un código de error en AppendCategory causado por la configuración de privacidad directiva de grupo o privacidad del usuario (E_ACCESSDENIED), la aplicación debe seguir actualizando tareas y llamando a CommitList.

Si no se encontró ningún registro de tipo de archivo para la aplicación asociada, AppendCategory devuelve HRESULT 0x80040F03. Esto puede deberse a que una aplicación no registra el tipo de archivo que intenta agregar a la lista de accesos directos o a un problema en el registro, como no proporcionar el AppUserModelID cuando la aplicación usa un AppUserModelID explícito.

Comentarios

Debe llamar a BeginList antes de llamar a este método.

Si una aplicación proporciona una categoría personalizada, esa aplicación asume la responsabilidad de rellenarla. El contenido de la categoría debe seguir siendo específico del usuario y en función del historial y las acciones del usuario, pero mediante un uso de una categoría personalizada una aplicación puede determinar lo que quiere realizar un seguimiento y lo que quiere omitir. Por ejemplo, se podrían implicar diferentes escenarios cuando se eligen diferentes opciones de aplicación. Por ejemplo, un programa de audio podría optar por incluir solo álbumes reproducidos recientemente e ignorar las pistas individuales reproducidas recientemente. Una aplicación también podría tener simplemente un algoritmo de seguimiento de uso adaptado a su uso específico que proporciona mejores resultados que los algoritmos predeterminados del sistema.

Una aplicación puede llamar a AppendCategory más de una vez en una sesión de creación de listas para agregar varias categorías personalizadas. En este caso, las categorías deben diseñarse para que su contenido sea mutuamente excluyente. Cada categoría personalizada debe crearse en torno a un escenario específico para que los elementos no estén duplicados entre ellos.

Las categorías de una lista de accesos directos personalizada, incluidas las categorías recientes o frecuentes conocidas, se muestran en el orden en que se agregan, con los elementos más recientes agregados al final de la lista. Si no hay espacio suficiente para mostrar todas las entradas, las últimas entradas de la lista desaparecerán primero de la pantalla. Por lo tanto, primero se deben agregar las categorías más importantes para garantizar su mejor oportunidad de mostrarse siempre. Los destinos de la categoría se muestran en el orden en que se almacenan en el objeto IObjectArray al que apunta poa.

El usuario puede decidir anclar uno o varios de los destinos proporcionados en la categoría personalizada a la lista de accesos directos. La lista de destinos anclados no está disponible para la aplicación, pero la interfaz de usuario impide la duplicación, por lo que no se requiere ninguna acción adicional de la aplicación. Visualmente, un elemento anclado se mueve a la sección Anclada de la lista de accesos directos y desaparece de su ubicación original.

Una llamada correcta a AppendCategory no garantiza que se muestren esos elementos. No se muestran ningún número de destinos agregados sobre el valor al que apunta el parámetro pcMinItems en ICustomDestinationList::BeginList . La categoría Anclada tiene prioridad sobre todas las demás listas de destino. Se muestra la lista anclada y, a continuación, se asigna el espacio restante a las otras listas de destino. Es posible que un usuario ancle suficientes destinos a la lista de accesos directos para evitar que se muestren otros destinos. Otros factores, como una resolución de pantalla reducida o un mayor tamaño de fuente, también pueden hacer que los destinos proporcionados por la aplicación se trunquen de la lista. La aplicación no tiene ninguna manera de predecir estas situaciones y no se notifica cuando se producen. La aplicación debe ser consciente de que existe la posibilidad. Dado que el truncamiento de la lista o listas de destino se produce desde la parte inferior hacia arriba, la aplicación debe colocar sus categorías y destinos más importantes en la parte superior de la lista para que tengan la mejor oportunidad de mostrarse.

Durante una sesión iniciada con BeginList y finalizando con CommitList, puede llamar a AppendCategory más de una vez. Si se produce un error en alguna de esas llamadas debido a un intento de agregar una categoría que contiene un elemento en la lista de elementos quitados, la llamada a CommitList no borra la lista de elementos quitados. Para que se borre la lista de elementos quitados, todas las llamadas a AppendCategory en una sesión deben devolverse correctamente.

Las instancias de IShellLink proporcionadas a través de IObjectArray a las que apunta poa deben proporcionar lo siguiente:

El nombre para mostrar debe establecerse a través de la propiedad System.Title (PKEY_Title) del elemento. La propiedad puede contener directamente el nombre para mostrar o puede ser una representación de cadena indirecta, como "@shell32.dll,-1324", para usar una cadena almacenada. Una cadena indirecta permite mostrar el nombre del elemento en el idioma seleccionado del usuario.

Opcionalmente, el campo de descripción (SetDescription) se puede establecer para proporcionar una información sobre herramientas personalizada para el elemento en la lista de accesos directos.

Requisitos

   
Cliente mínimo compatible Windows 7 [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2008 R2 [solo aplicaciones de escritorio]
Plataforma de destino Windows
Encabezado shobjidl_core.h (incluya Shobjidl.h)
Library Shell32.lib
Archivo DLL Shell32.dll (versión 6.1 o posterior)

Consulte también

ICustomDestinationList

ICustomDestinationList::AddUserTasks

ICustomDestinationList::AppendKnownCategory

Extensiones de la barra de tareas