Método IShellItemImageFactory::GetImage (shobjidl_core.h)

Artigo
11/20/2024

Obtém um HBITMAP que representa um IShellItem. O comportamento padrão é carregar uma miniatura. Se não houver miniatura para oIShellItem atual, ele recuperará uma HBITMAP para o ícone do item. A miniatura ou o ícone será extraído se não estiver armazenado em cache no momento.

Sintaxe

HRESULT GetImage(
  [in]  SIZE    size,
  [in]  SIIGBF  flags,
  [out] HBITMAP *phbm
);

Parâmetros

[in] size

Tipo: TAMANHO do

Uma estrutura que especifica o tamanho da imagem a ser recebida.

[in] flags

Tipo: SIIGBF

Um ou mais dos seguintes:

SIIGBF_RESIZETOFIT (0x00000000)

Reduza o bitmap conforme necessário para se ajustar, preservando sua taxa de proporção.

SIIGBF_BIGGERSIZEOK (0x00000001)

Passados por chamadores se quiserem esticar a imagem retornada por conta própria. Por exemplo, se o chamador passar um tamanho de ícone de 80x80, uma miniatura 96x96 poderá ser retornada. Essa ação pode ser usada como uma otimização de desempenho se o chamador espera que ele precise esticar a imagem. Observe que a implementação do Shell de IShellItemImageFactory executa um estiramento GDI blit. Se o chamador quiser um trecho de imagem de maior qualidade do que o fornecido por esse mecanismo, ele deverá passar esse sinalizador e executar o alongamento por conta própria.

SIIGBF_MEMORYONLY (0x00000002)

Retorne o item somente se ele já estiver na memória. Não acesse o disco mesmo se o item estiver armazenado em cache. Observe que isso só retorna um ícone já armazenado em cache e pode voltar para um ícone por classe se um item tiver um ícone por instância que não tenha sido armazenado em cache. A recuperação de uma miniatura, mesmo que seja armazenada em cache, sempre requer que o disco seja acessado, portanto, GetImage não deve ser chamado do thread de interface do usuário sem passar SIIGBF_MEMORYONLY.

SIIGBF_ICONONLY (0x00000004)

Retornar somente o ícone, nunca a miniatura.

SIIGBF_THUMBNAILONLY (0x00000008)

Retornar somente a miniatura, nunca o ícone. Observe que nem todos os itens têm miniaturas, portanto, SIIGBF_THUMBNAILONLY fará com que o método falhe nesses casos.

SIIGBF_INCACHEONLY (0x00000010)

Permite o acesso ao disco, mas apenas para recuperar um item armazenado em cache. Isso retornará uma miniatura armazenada em cache se ela estiver disponível. Se nenhuma miniatura armazenada em cache estiver disponível, ela retornará um ícone armazenado em cache por instância, mas não extrairá uma miniatura ou ícone.

SIIGBF_CROPTOSQUARE (0x00000020)

introduzido no Windows 8. Se necessário, corte o bitmap em um quadrado.

SIIGBF_WIDETHUMBNAILS (0x00000040)

introduzido no Windows 8. Estique e corte o bitmap para uma taxa de proporção de 0,7.

SIIGBF_ICONBACKGROUND (0x00000080)

introduzido no Windows 8. Se retornar um ícone, pinte um plano de fundo usando a cor da tela de fundo registrada do aplicativo associado.

SIIGBF_SCALEUP (0x00000100)

introduzido no Windows 8. Se necessário, estique o bitmap para que a altura e a largura se ajustem ao tamanho especificado.

[out] phbm

Tipo: HBITMAP*

Ponteiro para um valor que, quando esse método retorna com êxito, recebe o identificador do bitmap recuperado. É responsabilidade do chamador liberar esse recurso recuperado por meio DeleteObject quando ele não for mais necessário.

Valor de retorno

Tipo: HRESULT

Se esse método for bem-sucedido, ele retornará S_OK. Caso contrário, ele retornará um código de erro HRESULT.

Observações

A extração de ícones pode ser demorada. Esse método geralmente não deve ser chamado de um thread de interface do usuário para evitar que esse thread fique sem resposta. Você pode chamar IShellItemImageFactory::GetImage em um thread de interface do usuário se definir o sinalizador de SIIGBF_INCACHEONLY. No entanto, se a imagem não for encontrada no cache, o aplicativo de chamada deverá estar preparado para iniciar um thread de plano de fundo para extrair a imagem. Uma extração nunca deve ser feita em um thread de interface do usuário.

Consulte o exemplo Usando o Image Factory para obter um exemplo completo de como usar esse método.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Windows Vista [somente aplicativos da área de trabalho]
servidor com suporte mínimo	Windows Server 2008 [somente aplicativos da área de trabalho]
da Plataforma de Destino	Windows
cabeçalho	shobjidl_core.h (inclua Shobjidl.h)

Compartilhar via