Função EnumDisplaySettingsExA (winuser.h)

Artigo
08/27/2023

A função EnumDisplaySettingsEx recupera informações sobre um dos modos gráficos de um dispositivo de exibição. Para recuperar informações de todos os modos gráficos de um dispositivo de exibição, faça uma série de chamadas para essa função.

Essa função difere de EnumDisplaySettings porque há um parâmetro dwFlags .

Nota Os aplicativos que você projeta para direcionar Windows 8 e posteriores não podem mais consultar ou definir modos de exibição com menos de 32 bits por pixel (bpp); essas operações falharão. Esses aplicativos têm um manifesto de compatibilidade direcionado a Windows 8. Windows 8 ainda dá suporte a modos de cores de 8 e 16 bits para aplicativos da área de trabalho que foram criados sem um manifesto Windows 8; Windows 8 emula esses modos, mas ainda é executado no modo de cor de 32 bits.

Sintaxe

BOOL EnumDisplaySettingsExA(
  [in]  LPCSTR   lpszDeviceName,
  [in]  DWORD    iModeNum,
  [out] DEVMODEA *lpDevMode,
  [in]  DWORD    dwFlags
);

Parâmetros

[in] lpszDeviceName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o dispositivo de exibição sobre qual modo gráfico a função obterá informações.

Esse parâmetro é NULL ou um DISPLAY_DEVICE. DeviceName retornado de EnumDisplayDevices. Um valor NULL especifica o dispositivo de exibição atual no computador no qual o thread de chamada está sendo executado.

[in] iModeNum

Indica o tipo de informação a ser recuperada. Esse valor pode ser um índice de modo gráfico ou um dos valores a seguir.

Valor	Significado
ENUM_CURRENT_SETTINGS	Recupere as configurações atuais do dispositivo de exibição.
ENUM_REGISTRY_SETTINGS	Recupere as configurações do dispositivo de exibição que estão atualmente armazenados no registro.

Os índices do modo gráfico começam em zero. Para obter informações para todos os modos gráficos de um dispositivo de exibição, faça uma série de chamadas para EnumDisplaySettingsEx, da seguinte maneira: Defina iModeNum como zero para a primeira chamada e incremente iModeNum em uma para cada chamada subsequente. Continue chamando a função até que o valor retornado seja zero.

Quando você chama EnumDisplaySettingsEx com iModeNum definido como zero, o sistema operacional inicializa e armazena em cache informações sobre o dispositivo de exibição. Quando você chama EnumDisplaySettingsEx com iModeNum definido como um valor diferente de zero, a função retorna as informações que foram armazenadas em cache na última vez que a função foi chamada com iModeNum definido como zero.

[out] lpDevMode

Um ponteiro para uma estrutura DEVMODE na qual a função armazena informações sobre o modo gráfico especificado. Antes de chamar EnumDisplaySettingsEx, defina o membro dmSize como sizeof (DEVMODE) e defina o membro dmDriverExtra para indicar o tamanho, em bytes, do espaço adicional disponível para receber dados de driver privados.

A função EnumDisplaySettingsEx preencherá o membro dmFields do lpDevMode e um ou mais membros da estrutura DEVMODE . Para determinar quais membros foram definidos pela chamada para EnumDisplaySettingsEx, inspecione a máscara de bits dmFields . Alguns dos campos normalmente preenchidos por essa função incluem:

dmBitsPerPel
dmPelsWidth
dmPelsHeight
dmDisplayFlags
dmDisplayFrequency
dmPosition
dmDisplayOrientation

[in] dwFlags

Esse parâmetro pode ser o valor a seguir.

Valor	Significado
EDS_RAWMODE	Se definida, a função retornará todos os modos gráficos relatados pelo driver do adaptador, independentemente das funcionalidades do monitor. Caso contrário, ele retornará apenas modos compatíveis com os monitores atuais.
EDS_ROTATEDMODE	Se definida, a função retornará modos gráficos em todas as orientações. Caso contrário, ele retornará apenas modos que têm a mesma orientação que o atualmente definido para a exibição solicitada.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

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

Comentários

A função falhará se iModeNum for maior que o índice do último modo gráfico do dispositivo de exibição. Conforme observado na descrição do parâmetro iModeNum , você pode usar esse comportamento para enumerar todos os modos gráficos de um dispositivo de exibição.

Virtualização de DPI

Essa API não participa da virtualização de DPI. A saída fornecida está sempre em termos de pixels físicos e não está relacionada ao contexto de chamada.

Observação

O cabeçalho winuser.h define EnumDisplaySettingsEx 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	winuser.h (inclua Windows.h)
Biblioteca	User32.lib
DLL	User32.dll
Conjunto de APIs	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introduzido no Windows 10, versão 10.0.14393)