Função CreateEnhMetaFileA (wingdi.h)

Artigo
11/20/2024

A função CreateEnhMetaFile cria um contexto de dispositivo para um metafile 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 metafile 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 metafile aprimorado a ser criado. Se esse parâmetro for NULL, o metafilo 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 serem armazenadas no metafilo 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.

Valor de retorno

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

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

Observações

Quando os argumentos de texto devem usar caracteres Unicode, use a função CreateEnhMetaFile como uma função de caractere largo. Em que 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.

O esquerdo e membros superiores da estrutura rect apontado pelo parâmetro lpRect deve ser menor do que os membros direito e inferiores, respectivamente. Os pontos ao longo das bordas do retângulo são incluídos na imagem. Se lpRect for NULL, a GDI (interface do dispositivo gráfico) 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, "Editor de Gráficos XYZ\0Bald Eagle\0\0", em que \0 representa o caractere nulo. Se lpDescription for NULL, não haverá nenhuma entrada correspondente no cabeçalho de metafile aprimorado.

Os aplicativos usam o contexto do dispositivo criado por essa função para armazenar uma imagem gráfica em um metafile 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 metafile 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 metafile aprimorado no formato de metafile do Windows mais antigo.

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

Exemplos

Para obter um exemplo, consulte Criando umde metafile aprimorado.

Nota

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 do pré-processador UNICODE. A combinação do uso do alias neutro de codificação com código que não é neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Conventions for Function Prototypes.

Requisitos

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

Consulte também

CloseEnhMetaFile

DeleteEnhMetaFile

GetEnhMetaFileDescription

GetEnhMetaFileHeader

GetWinMetaFileBits

Funções de metafile

Visão geral de metafiles

PlayEnhMetaFile

RECT

Compartilhar via