Função CreateEnhMetaFileA (wingdi.h)

Artigo
03/09/2024

A função CreateEnhMetaFile cria um contexto de dispositivo para um metarquivo de formato aprimorado. Esse contexto de dispositivo pode ser usado para armazenar uma imagem independente do dispositivo.

Sintaxe

HDC CreateEnhMetaFileA(
  [in] HDC        hdc,
  [in] LPCSTR     lpFilename,
  [in] const RECT *lprc,
  [in] LPCSTR     lpDesc
);

Parâmetros

[in] hdc

Um identificador para um dispositivo de referência para o meta-arquivo aprimorado. Esse parâmetro pode ser NULL; para obter mais informações, consulte Comentários.

[in] lpFilename

Um ponteiro para o nome do arquivo para o meta-arquivo aprimorado a ser criado. Se esse parâmetro for NULL, o meta-arquivo aprimorado será baseado em memória e seu conteúdo será perdido quando for excluído usando a função DeleteEnhMetaFile .

[in] lprc

Um ponteiro para uma estrutura RECT que especifica as dimensões (em unidades de 0,01 milímetro) da imagem a ser armazenada no metarquivo aprimorado.

[in] lpDesc

Um ponteiro para uma cadeia de caracteres que especifica o nome do aplicativo que criou a imagem, bem como o título da imagem. Esse parâmetro pode ser NULL; para obter mais informações, consulte Comentários.

Retornar valor

Se a função for bem-sucedida, o valor retornado será um identificador para o contexto do dispositivo para o meta-arquivo aprimorado.

Se a função falhar, o valor retornado será NULL.

Comentários

Quando os argumentos de texto devem usar caracteres Unicode, use a função CreateEnhMetaFile como uma função de caractere largo. Quando os argumentos de texto devem usar caracteres do conjunto de caracteres do Windows, use essa função como uma função ANSI.

O sistema usa o dispositivo de referência identificado pelo parâmetro hdcRef para registrar a resolução e as unidades do dispositivo no qual uma imagem apareceu originalmente. Se o parâmetro hdcRef for NULL, ele usará o dispositivo de exibição atual para referência.

Os membros esquerdos e superiores da estrutura RECT apontados pelo parâmetro lpRect devem ser menores que os membros direito e inferior , respectivamente. Pontos ao longo das bordas do retângulo são incluídos na imagem. Se lpRect for NULL, a GDI (interface gráfica do dispositivo) calculará as dimensões do menor retângulo que envolve a imagem desenhada pelo aplicativo. O parâmetro lpRect deve ser fornecido sempre que possível.

A cadeia de caracteres apontada pelo parâmetro lpDescription deve conter um caractere nulo entre o nome do aplicativo e o nome da imagem e deve terminar com dois caracteres nulos, por exemplo, "Elementos gráficos XYZ Editor\0Bald Eagle\0\0", em que \0 representa o caractere nulo. Se lpDescription for NULL, não haverá nenhuma entrada correspondente no cabeçalho enhanced-metafile.

Os aplicativos usam o contexto do dispositivo criado por essa função para armazenar uma imagem gráfica em um metarquivo aprimorado. O identificador que identifica esse contexto de dispositivo pode ser passado para qualquer função GDI.

Depois que um aplicativo armazena uma imagem em um metarquivo aprimorado, ele pode exibir a imagem em qualquer dispositivo de saída chamando a função PlayEnhMetaFile . Ao exibir a imagem, o sistema usa o retângulo apontado pelo parâmetro lpRect e os dados de resolução do dispositivo de referência para posicionar e dimensionar a imagem.

O contexto do dispositivo retornado por essa função contém os mesmos atributos padrão associados a qualquer novo contexto de dispositivo.

Os aplicativos devem usar a função GetWinMetaFileBits para converter um metarquivo aprimorado para o formato de metarquivo mais antigo do Windows.

O nome do arquivo para o metarquivo aprimorado deve usar a extensão .emf.

Exemplos

Para obter um exemplo, consulte Criando um metarquivo avançado.

Observação

O cabeçalho wingdi.h define CreateEnhMetaFile como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows 2000 Professional [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows 2000 Server [somente aplicativos da área de trabalho]
Plataforma de Destino	Windows
Cabeçalho	wingdi.h (inclua Windows.h)
Biblioteca	Gdi32.lib
DLL	Gdi32.dll