Share via

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

  • Artigo

Define uma categoria personalizada e os destinos que ela contém, para inclusão em uma Lista de Saltos personalizada.

Sintaxe

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

Parâmetros

[in] pszCategory

Tipo: LPCWSTR

Um ponteiro para uma cadeia de caracteres que contém o nome de exibição da categoria personalizada. Essa cadeia de caracteres é mostrada no cabeçalho da categoria na Lista de Saltos. A cadeia de caracteres pode conter diretamente o nome de exibição ou pode ser uma representação de cadeia de caracteres indireta, como "@shell32.dll,-1324", para usar uma cadeia de caracteres armazenada. Uma cadeia de caracteres indireta permite que o cabeçalho de categoria seja exibido no idioma selecionado do usuário.

Nota Cada categoria personalizada deve ter um nome exclusivo. Nomes de categoria duplicados causarão problemas de apresentação na Lista de Saltos.
 

[in] poa

Tipo: IObjectArray*

Um ponteiro para um IObjectArray que representa um ou mais objetos IShellItem que representam os destinos na categoria. Alguns destinos na lista também podem ser representados por objetos IShellLink , embora com menos frequência.

Nota Qualquer IShellLink usado aqui deve declarar uma lista de argumentos por meio de SetArguments. Não há suporte para a adição de um objeto IShellLink sem argumentos a uma categoria personalizada, pois um usuário não pode fixar ou desafixar esse tipo de item de uma Lista de Saltos, nem pode ser adicionado ou removido.
 

Valor retornado

Tipo: HRESULT

Retorna S_OK se tiver êxito; caso contrário, um valor de erro.

Se a chamada para AppendCategory tentar adicionar um item que está na lista de destinos removidos recuperada pela chamada para BeginList que iniciou a sessão, a chamada para AppendCategory falhará.

Se AppendCategory tentar adicionar um IShellItem que o aplicativo não está registrado para manipular, a chamada falhará.

AppendCategory poderá falhar se houver uma configuração de privacidade Política de Grupo ou privacidade do usuário ativada. As categorias personalizadas contêm itens específicos do usuário com base no uso individual, o que não é permitido nessas configurações de privacidade.

Uma configuração de privacidade Política de Grupo ou privacidade do usuário não causará uma falha em nenhum outro método ICustomDestinationList. As tarefas não são específicas do usuário. AppendKnownCategory não resultará na exibição das categorias Recentes ou Frequentes porque elas não terão dados, mas a chamada de método não retornará um código de falha.

No caso de um código de falha em AppendCategory causado por Política de Grupo de privacidade ou configuração de privacidade do usuário (E_ACCESSDENIED), o aplicativo deve continuar a atualizar tarefas e chamar CommitList.

Se nenhum registro de tipo de arquivo tiver sido encontrado para o aplicativo associado, AppendCategory retornará 0x80040F03 HRESULT. Isso pode resultar de um aplicativo que não está registrando o tipo de arquivo que está tentando adicionar à Lista de Saltos ou de um problema no registro, como não fornecer o AppUserModelID quando o aplicativo estiver usando um AppUserModelID explícito.

Comentários

Você deve chamar BeginList antes de chamar esse método.

Se um aplicativo fornecer uma categoria personalizada, esse aplicativo assumirá a responsabilidade de preenchê-lo. O conteúdo da categoria ainda deve ser específico do usuário e com base no histórico e nas ações do usuário, mas usando uma categoria personalizada, um aplicativo pode determinar o que ele deseja rastrear e o que ele deseja ignorar. Por exemplo, diferentes cenários podem estar envolvidos quando diferentes opções de aplicativo são escolhidas. Por exemplo, um programa de áudio pode optar por incluir apenas álbuns tocados recentemente e ignorar faixas individuais recentemente tocadas. Um aplicativo também pode simplesmente ter um algoritmo de acompanhamento de uso adaptado ao seu uso específico que fornece melhores resultados do que os algoritmos padrão do sistema.

Um aplicativo pode chamar AppendCategory mais de uma vez em uma sessão de criação de lista para adicionar várias categorias personalizadas. Nesse caso, as categorias devem ser projetadas para que seu conteúdo seja mutuamente exclusivo. Cada categoria personalizada deve ser criada em torno de um cenário específico para que os itens não sejam duplicados entre eles.

Categorias em uma Lista de Saltos personalizada, incluindo as categorias Recentes ou Frequentes conhecidas, são mostradas na ordem em que são adicionadas, com os itens mais recentes adicionados ao final da lista. Se não houver espaço suficiente para mostrar todas as entradas, as últimas entradas na lista desaparecerão da tela primeiro. Portanto, as categorias mais importantes devem ser adicionadas primeiro para garantir sua melhor chance de serem sempre mostradas. Os destinos dentro da categoria são mostrados na ordem em que são armazenados no objeto IObjectArray apontado por poa.

O usuário pode decidir fixar um ou mais dos destinos fornecidos na categoria personalizada à Lista de Saltos. A lista de destinos fixados não está disponível para o aplicativo, mas a duplicação é impedida pela interface do usuário para que nenhuma ação extra seja necessária do aplicativo. Visualmente, um item fixado se move para a seção Fixado da Lista de Saltos e desaparece de sua localização original.

Uma chamada bem-sucedida para AppendCategory não garante que esses itens sejam exibidos. Qualquer número de destinos adicionados sobre o valor apontado pelo parâmetro pcMinItems em ICustomDestinationList::BeginList não são mostrados. A categoria Pinned tem prioridade sobre todas as outras listas de destino. A lista Fixada é exibida e, em seguida, o espaço restante é alocado para as outras listas de destino. É possível que um usuário fixe destinos suficientes na Lista de Saltos para impedir que outros destinos sejam exibidos. Outros fatores, como uma resolução de tela reduzida ou um tamanho de fonte maior, também podem fazer com que os destinos fornecidos pelo aplicativo sejam truncados da lista. O aplicativo não tem como prever essas situações e não é notificado quando elas ocorrem. O aplicativo deve apenas estar ciente de que a possibilidade existe. Como o truncamento da lista de destino ou listas ocorre de baixo para cima, o aplicativo deve colocar suas categorias e destinos mais importantes na parte superior da lista para que eles tenham a melhor chance de serem mostrados.

Durante uma sessão iniciada com BeginList e terminando com CommitList, você pode chamar AppendCategory mais de uma vez. Se qualquer uma dessas chamadas falhar devido a uma tentativa de adicionar uma categoria que contém um item na lista de itens removidos, a chamada para CommitList não limpará a lista de itens removidos. Para que a lista de itens removidos seja desmarcada, todas as chamadas para AppendCategory em uma sessão devem retornar com êxito.

As instâncias IShellLink fornecidas por meio do IObjectArray apontado por poa devem fornecer o seguinte:

O nome de exibição deve ser definido por meio da propriedade System.Title (PKEY_Title) do item. A propriedade pode conter diretamente o nome de exibição ou pode ser uma representação de cadeia de caracteres indireta, como "@shell32.dll,-1324", para usar uma cadeia de caracteres armazenada. Uma cadeia de caracteres indireta permite que o nome do item seja exibido no idioma selecionado do usuário.

Opcionalmente, o campo de descrição (SetDescription) pode ser definido para fornecer uma dica de ferramenta personalizada para o item na Lista de Saltos.

Requisitos

   
Cliente mínimo com suporte Windows 7 [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 R2 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho shobjidl_core.h (inclua Shobjidl.h)
Biblioteca Shell32.lib
DLL Shell32.dll (versão 6.1 ou posterior)

Confira também

ICustomDestinationList

ICustomDestinationList::AddUserTasks

ICustomDestinationList::AppendKnownCategory

Extensões da barra de tarefas