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

Artigo
03/02/2024

Especifica que a categoria Frequente ou Recente deve ser incluída em uma Lista de Saltos personalizada.

Sintaxe

HRESULT AppendKnownCategory(
  [in] KNOWNDESTCATEGORY category
);

Parâmetros

[in] category

Tipo: KNOWNDESTCATEGORY

Um dos seguintes valores que indicam qual categoria conhecida adicionar à lista:

KDC_FREQUENT (1)

0x1. Adicione a categoria Frequente .

KDC_RECENT (2)

0x2. Adicione a categoria Recente .

Retornar valor

Tipo: HRESULT

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

Se houver uma configuração de privacidade Política de Grupo ou privacidade do usuário presente, isso poderá afetar o resultado desse método. Categorias que contêm itens específicos do usuário com base no uso individual não são permitidas nessas configurações de privacidade. Devido a isso, as categorias Recentes ou Frequentes adicionadas por meio desse método não terão dados e categorias sem dados não serão exibidas. No entanto, nessa situação, essa chamada de método não resultará em um código de falha.

Comentários

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

A categoria Recente é mostrada em uma Lista de Saltos padrão, mas para mostrá-la em uma Lista de Saltos personalizada junto com categorias personalizadas, você deve solicitá-la explicitamente por meio desse método.

Com AppendCategory e AppendKnownCategory, uma Lista de Saltos personalizada deve ser projetada para evitar que qualquer item apareça em mais de uma categoria. Se duas categorias forem simplesmente exibições diferentes nos mesmos dados, uma dessas categorias deverá ser removida, pois ela está usando o espaço jump list sem contribuir para a conveniência do usuário. As duplicatas não são ocultadas pelo sistema, exceto no caso de um destino fixado, nesse caso, esse destino é mostrado na categoria Fixado e oculto em todos os outros.

As categorias Frequente e Recente provavelmente conterão um grau de sobreposição e, portanto, você não deve adicionar ambas as categorias a uma única Lista de Saltos. Qual dos dois é melhor para seu aplicativo depende de sua natureza. Um aplicativo que gera arquivos, como Microsoft Word ou Microsoft Paint, deve usar a categoria Recente, pois é mais provável que os usuários queiram retornar aos arquivos nos quais trabalharam recentemente. Um aplicativo que é mais usado para navegação ou reprodução de dados criados em outro lugar deve usar a categoria Frequente porque o usuário tem maior probabilidade de acessar um número maior de itens, muitos deles apenas uma vez. Em outras palavras, se o aplicativo tiver maior probabilidade de acessar um grande número de itens apenas algumas vezes cada, o que contribui para o menor conjunto de itens que os usuários desejam acessar muitas vezes, Frequente é a melhor opção. Se o aplicativo tiver maior probabilidade de acessar um número menor de itens mais recentes na maior parte do tempo, você deverá escolher Recente.

Categorias em uma Lista de Saltos personalizada, incluindo a categoria Recente ou Frequente conhecida, são mostradas na ordem em que são adicionadas, com as categorias adicionadas mais recentemente na parte inferior da lista.

Qualquer número de destinos adicionados sobre o valor apontado pelo parâmetro pcMinItems em ICustomDestinationList::BeginList não são mostrados.

Categorias vazias não são mostradas.

O conteúdo das categorias Frequente e Recente é calculado para cada aplicativo que usa SHAddToRecentDocs diretamente. Em alguns casos de ação do usuário, como abrir um arquivo por meio do Windows Explorer ou usar a caixa de diálogo de arquivo comum para abrir, salvar ou criar um arquivo, o Shell chama SHAddToRecentDocs em nome de um aplicativo e essas chamadas também são levadas em conta nas estatísticas de uso. O Shell também chama SHAddToRecentDocs em nome do aplicativo quando um destino é iniciado de sua Lista de Saltos. No entanto, é uma boa prática para o aplicativo chamar explicitamente SHAddToRecentDocs mesmo se for esperado que o Shell faça a chamada. Isso garante que o uso seja registrado e os algoritmos para acompanhar o uso recente ou frequente serão corrigidos para chamadas duplicadas.

Requisitos

Requisito	Valor
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)