Função CreateDCA (wingdi.h)

Artigo
03/04/2024

A função CreateDC cria um DC (contexto de dispositivo) para um dispositivo usando o nome especificado.

Sintaxe

HDC CreateDCA(
       LPCSTR         pwszDriver,
  [in] LPCSTR         pwszDevice,
       LPCSTR         pszPort,
  [in] const DEVMODEA *pdm
);

Parâmetros

pwszDriver

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica DISPLAY ou o nome de um dispositivo de exibição específico. Para impressão, recomendamos que você passe NULL para lpszDriver porque a GDI ignora o lpszDriver para dispositivos de impressora.

[in] pwszDevice

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o nome do dispositivo de saída específico que está sendo usado, conforme mostrado pelo Gerenciador de Impressão (por exemplo, Epson FX-80). Não é o nome do modelo de impressora. O parâmetro lpszDevice deve ser usado.

Para obter nomes válidos para exibições, chame EnumDisplayDevices.

Se lpszDriver for DISPLAY ou o nome do dispositivo de um dispositivo de exibição específico, lpszDevice deverá ser NULL ou o mesmo nome do dispositivo. Se lpszDevice for NULL, um DC será criado para o dispositivo de exibição primário.

Se houver vários monitores no sistema, chamar CreateDC(TEXT("DISPLAY"),NULL,NULL,NULL) criará um controlador de domínio que abrange todos os monitores.

pszPort

Esse parâmetro é ignorado e deve ser definido como NULL. Ele é fornecido apenas para compatibilidade com o Windows de 16 bits.

[in] pdm

Um ponteiro para uma estrutura DEVMODE que contém dados de inicialização específicos do dispositivo para o driver de dispositivo. A função DocumentProperties recupera essa estrutura preenchida para um dispositivo especificado. O parâmetro pdm deverá ser NULL se o driver de dispositivo for usar a inicialização padrão (se houver) especificada pelo usuário.

Se lpszDriver for DISPLAY, pdm deverá ser NULL; A GDI usa o DEVMODE atual do dispositivo de exibição.

Retornar valor

Se a função for bem-sucedida, o valor retornado será o identificador para um controlador de domínio do dispositivo especificado.

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

Comentários

Observe que o identificador para o controlador de domínio só pode ser usado por um único thread a qualquer momento.

Para os parâmetros lpszDriver e lpszDevice, chame EnumDisplayDevices para obter nomes válidos para exibições.

Quando você não precisar mais do CONTROLADOR de domínio, chame a função DeleteDC .

Se lpszDriver ou lpszDevice for DISPLAY, o thread que chama CreateDC será o proprietário do HDC criado. Quando esse thread é destruído, o HDC não é mais válido. Portanto, se você criar o HDC e passá-lo para outro thread, sair do primeiro thread, o segundo thread não poderá usar o HDC.

Ao chamar CreateDC para criar o HDC para um dispositivo de exibição, você deve passar para pdmNULL ou um ponteiro para DEVMODE que corresponda ao DEVMODE atual do dispositivo de exibição que lpszDevice especifica. É recomendável passar NULL e não tentar corresponder exatamente ao DEVMODE para o dispositivo de exibição atual.

Quando você chama CreateDC para criar o HDC para um dispositivo de impressora, o driver da impressora valida o DEVMODE. Se o driver da impressora determinar que o DEVMODE é inválido (ou seja, o driver da impressora não pode converter ou consumir o DEVMODE), o driver da impressora fornecerá um DEVMODE padrão para criar o HDC para o dispositivo de impressora.

ICM: Para habilitar o ICM, defina o membro dmICMMethod da estrutura DEVMODE (apontado pelo parâmetro pInitData ) como o valor apropriado.

Exemplos

Para obter um exemplo, consulte Capturando uma imagem.

Observação

O cabeçalho wingdi.h define CreateDC 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