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

  • Artigo

Especifica os itens a serem incluídos na categoria Tarefas de uma Lista de Atalhos personalizada.

Sintaxe

HRESULT AddUserTasks(
  [in] IObjectArray *poa
);

Parâmetros

[in] poa

Tipo: IObjectArray*

Um ponteiro para um IObjectArray que representa um ou mais objetos IShellLink (ou, mais raramente, IShellItem) que representam as tarefas.

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. Um usuário não pode fixar ou desafixar esse tipo de item de uma Lista de Atalhos, nem pode ser adicionado ou removido.
 

Retornar valor

Tipo: HRESULT

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

Comentários

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

O cabeçalho da categoria Tarefas sempre é mostrado na lista por padrão, a menos que a categoria esteja vazia. Este texto de cabeçalho não pode ser alterado. Ele é exibido no idioma selecionado do usuário.

A categoria Tarefas , embora sempre apareça como a última categoria em uma Lista de Atalhos, tem prioridade sobre todas as outras categorias na lista. Essa lista é preenchida e, em seguida, o espaço restante é alocado para as outras categorias. Ao contrário de outras categorias, os itens na categoria Tarefas não podem ser removidos ou fixados pelo usuário. Os aplicativos devem equilibrar o valor para o usuário das tarefas nessa categoria em relação ao espaço necessário para outras categorias.

As tarefas devem ser aplicadas ao aplicativo como um todo; eles não devem ser específicos para uma janela ou documento individual. Para essas tarefas contextuais mais granulares, um aplicativo pode fornecê-las por meio de uma barra de ferramentas em miniatura.

Nota É altamente recomendável que a lista de tarefas seja estática. A lista de tarefas deve permanecer a mesma, independentemente do estado ou status do aplicativo— essas tarefas estão disponíveis mesmo quando o aplicativo não está em execução. Não há nenhuma proibição programática contra o uso de AddUserTasks para variar a lista de tarefas quando ela é atualizada, mas você deve considerar que isso pode confundir o usuário que não espera que essa parte da Lista de Atalhos seja alterada. No entanto, se um aplicativo optar por alterar o estado de uma tarefa, como "Entrar" para "Sair", será responsabilidade desse aplicativo garantir que a lista de tarefas esteja correta e atualizada. Além disso, se o aplicativo for desligado inesperadamente, a barra de tarefas usará sua última versão válida conhecida da lista de tarefas sem chamar o aplicativo para solicitar um, levando à possibilidade de itens desatualizados.
 

As instâncias de IShellLink fornecidas por meio do IObjectArray apontado pelo 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 Atalhos.

Uma lista de tarefas também pode incluir separadores. Eles são criados incluindo um IShellLink em branco (essa é a única exceção ao requisito de lista de argumentos) e a definição da propriedade System.AppUserModel.IsDestListSeparator como TRUE por meio da interface IPropertyStore do objeto IShellLink. Quaisquer outros valores no IShellLink serão ignorados. Os separadores não ocuparão um espaço completo na lista e não são contados no número de itens na lista. Se dois separadores forem fornecidos sem itens entre eles, um dos separadores não será mostrado. Separadores no início ou no final da lista também são ignorados.

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)

Confira também

ICustomDestinationList

ICustomDestinationList::AppendCategory

ICustomDestinationList::AppendKnownCategory

Extensões da barra de tarefas