Função LoadIconMetric (commctrl.h)

  • Artigo

Carrega um recurso de ícone especificado com uma métrica de sistema especificada pelo cliente.

Sintaxe

HRESULT LoadIconMetric(
  [in]  HINSTANCE hinst,
  [in]  PCWSTR    pszName,
  [in]  int       lims,
  [out] HICON     *phico
);

Parâmetros

[in] hinst

Tipo: HINSTANCE

Um identificador para o módulo de um arquivo DLL ou executável (.exe) que contém o ícone a ser carregado. Para obter mais informações, consulte GetModuleHandle.

Para carregar um ícone de sistema predefinido ou um arquivo de ícone autônomo, defina esse parâmetro como NULL.

[in] pszName

Tipo: PCWSTR

Um ponteiro para um buffer Unicode encerrado em nulo que contém informações de localização sobre o ícone a ser carregado.

Se hinst não for NULL, pszName especificará o recurso de ícone por nome ou ordinal. Esse ordinal deve ser empacotado usando a macro MAKEINTRESOURCE .

Se hinst for NULL, pszName especificará o identificador (começando com o prefixo IDI_) de um ícone de sistema predefinido a ser carregado.

[in] lims

Tipo: int

A métrica desejada. Um dos seguintes valores:

Valor Significado
LIM_SMALL
 Corresponde a SM_CXSMICON, a largura de pixel recomendada de um ícone pequeno.
LIM_LARGE
 Corresponde a SM_CXICON, a largura de pixel padrão de um ícone.

[out] phico

Tipo: HICON*

Quando essa função retorna, contém um ponteiro para o identificador do ícone carregado.

Retornar valor

Tipo: HRESULT

Retorna S_OK se tiver êxito, caso contrário, um erro, incluindo o valor a seguir.

Código de retorno Descrição
E_INVALIDARG
 O conteúdo do buffer apontado por pszName não se encaixa em nenhuma das interpretações esperadas.

Comentários

LoadIconMetric é semelhante a LoadIcon, mas com a capacidade de especificar a métrica de ícone. Ele é usado no lugar de LoadIcon quando o aplicativo de chamada deseja garantir um ícone de alta qualidade. Isso é particularmente útil em situações de pontos altos por polegada (dpi).

Os ícones são extraídos ou criados da seguinte maneira.

  1. Se uma correspondência de tamanho exato for encontrada no recurso, esse ícone será usado.
  2. Se uma correspondência de tamanho exato não puder ser encontrada e um ícone maior estiver disponível, um novo ícone será criado escalando a versão maior para baixo para o tamanho desejado.
  3. Se uma correspondência de tamanho exato não puder ser encontrada e nenhum ícone maior estiver disponível, um novo ícone será criado dimensionando um ícone menor até o tamanho desejado.
As chamadas comparativas são mostradas aqui para LoadIconMetric e LoadIcon. 
NOTIFYICONDATA  nidIconData  = {0};
nidIconData.hIcon = LoadIcon(hInstance, MAKEINTRESOURCE(IDI_ICON));

// Or...

HRESULT hr = LoadIconMetric(hInstance, MAKEINTRESOURCE(IDI_ICON), LIM_SMALL, &nidIconData.hIcon);

O aplicativo é responsável por chamar DestroyIcon no ícone recuperado.

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho commctrl.h
Biblioteca Comctl32.lib
DLL Comctl32.dll