Compartilhar via


Função ChangeDisplaySettingsExA (winuser.h)

A função ChangeDisplaySettingsEx altera as configurações do dispositivo de exibição especificado para o modo gráfico especificado.

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

LONG ChangeDisplaySettingsExA(
  [in] LPCSTR   lpszDeviceName,
  [in] DEVMODEA *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

Parâmetros

[in] lpszDeviceName

Um ponteiro para uma cadeia de caracteres terminada em nulo que especifica o dispositivo de exibição cujo modo gráfico será alterado. Somente exibir nomes de dispositivo conforme retornado por EnumDisplayDevices são válidos . Consulte EnumDisplayDevices para obter mais informações sobre os nomes associados a esses dispositivos de exibição.

O parâmetro lpszDeviceName pode ser NULL. Um valor NULL especifica o dispositivo de exibição padrão. O dispositivo padrão pode ser determinado chamando EnumDisplayDevices e verificando o sinalizador DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Um ponteiro para uma estrutura DEVMODE que descreve o novo modo gráfico. Se lpDevMode for NULL, todos os valores atualmente no Registro serão usados para a configuração de exibição. Passar NULL para o parâmetro lpDevMode e 0 para o parâmetro dwFlags é a maneira mais fácil de retornar ao modo padrão após uma alteração de modo dinâmico.

O membro dmSize deve ser inicializado para o tamanho, em bytes, da estrutura DEVMODE . O membro dmDriverExtra deve ser inicializado para indicar o número de bytes de dados de driver privados seguindo a estrutura DEVMODE . Além disso, você pode usar qualquer um dos membros a seguir da estrutura DEVMODE .

Membro Significado
dmBitsPerPel Bits por Pixel
dmPelsWidth Largura do pixel
dmPelsHeight Altura do pixel
dmDisplayFlags Sinalizadores de modo
dmDisplayFrequency Frequência do modo
dmPosition Posição do dispositivo em uma configuração de vários monitores.
 

Além de usar um ou mais dos membros DEVMODE anteriores, você também deve definir um ou mais dos seguintes valores no membro dmFields para alterar as configurações de exibição.

Valor Significado
DM_BITSPERPEL Use o valor dmBitsPerPel .
DM_PELSWIDTH Use o valor dmPelsWidth .
DM_PELSHEIGHT Use o valor dmPelsHeight .
DM_DISPLAYFLAGS Use o valor dmDisplayFlags .
DM_DISPLAYFREQUENCY Use o valor dmDisplayFrequency .
DM_POSITION Use o valor dmPosition .

hwnd

Reservados; deve ser NULL.

[in] dwflags

Indica como o modo gráfico deve ser alterado. Esse parâmetro pode usar um dos valores a seguir.

Valor Significado
0
O modo gráfico da tela atual será alterado dinamicamente.
CDS_FULLSCREEN
O modo é temporário por natureza.

Se você mudar de e para outra área de trabalho, esse modo não será redefinido.

CDS_GLOBAL
As configurações serão salvas na área de configurações globais para que elas afetem todos os usuários no computador. Caso contrário, somente as configurações do usuário serão modificadas. Esse sinalizador só é válido quando especificado com o sinalizador CDS_UPDATEREGISTRY.
CDS_NORESET
As configurações serão salvas no registro, mas não entrarão em vigor. Esse sinalizador só é válido quando especificado com o sinalizador CDS_UPDATEREGISTRY.
CDS_RESET
As configurações devem ser alteradas, mesmo que as configurações solicitadas sejam iguais às configurações atuais.
CDS_SET_PRIMARY
Esse dispositivo se tornará o dispositivo principal.
CDS_TEST
O sistema testa se o modo gráfico solicitado pode ser definido.
CDS_UPDATEREGISTRY
O modo gráfico da tela atual será alterado dinamicamente e o modo gráfico será atualizado no Registro. As informações do modo são armazenadas no perfil USER.
CDS_VIDEOPARAMETERS
Quando definido, o parâmetro lParam é um ponteiro para uma estrutura VIDEOPARAMETERS .
CDS_ENABLE_UNSAFE_MODES
Habilita as alterações de configurações em modos gráficos não seguros.
CDS_DISABLE_UNSAFE_MODES
Desabilita as alterações de configurações em modos gráficos não seguros.
 

Especificar CDS_TEST permite que um aplicativo determine quais modos gráficos são realmente válidos, sem fazer com que o sistema mude para eles.

Se CDS_UPDATEREGISTRY for especificado e for possível alterar o modo gráfico dinamicamente, as informações serão armazenadas no registro e DISP_CHANGE_SUCCESSFUL serão retornadas. Se não for possível alterar o modo gráfico dinamicamente, as informações serão armazenadas no registro e DISP_CHANGE_RESTART serão retornadas.

Se CDS_UPDATEREGISTRY for especificado e as informações não puderem ser armazenadas no registro, o modo gráfico não será alterado e DISP_CHANGE_NOTUPDATED será retornado.

[in] lParam

Se dwFlags for CDS_VIDEOPARAMETERS, lParam será um ponteiro para uma estrutura VIDEOPARAMETERS . Caso contrário , lParam deve ser NULL.

Retornar valor

A função ChangeDisplaySettingsEx retorna um dos valores a seguir.

Código de retorno Descrição
DISP_CHANGE_SUCCESSFUL
A alteração das configurações foi bem-sucedida.
DISP_CHANGE_BADDUALVIEW
A alteração das configurações não foi bem-sucedida porque o sistema é compatível com DualView.
DISP_CHANGE_BADFLAGS
Um conjunto inválido de sinalizadores foi passado.
DISP_CHANGE_BADMODE
Não há suporte para o modo gráfico.
DISP_CHANGE_BADPARAM
Um parâmetro inválido foi passado. Isso pode incluir um sinalizador inválido ou uma combinação de sinalizadores.
DISP_CHANGE_FAILED
O driver de exibição falhou no modo gráfico especificado.
DISP_CHANGE_NOTUPDATED
Não é possível gravar configurações no registro.
DISP_CHANGE_RESTART
O computador deve ser reiniciado para que o modo gráfico funcione.

Comentários

Para garantir que a estrutura DEVMODE passada para ChangeDisplaySettingsEx seja válida e contenha apenas valores compatíveis com o driver de exibição, use o DEVMODE retornado pela função EnumDisplaySettings .

Ao adicionar um monitor de exibição a um sistema de vários monitores programaticamente, defina DEVMODE.dmFields como DM_POSITION e especifique uma posição (em DEVMODE.dmPosition) para o monitor que você está adicionando que é adjacente a pelo menos um pixel da área de exibição de um monitor existente. Para desanexar o monitor, defina DEVMODE.dmFields como DM_POSITION mas defina DEVMODE.dmPelsWidth e DEVMODE.dmPelsHeight como zero. Para obter mais informações, consulte Vários Monitores de Exibição.

Quando o modo de exibição é alterado dinamicamente, a mensagem WM_DISPLAYCHANGE é enviada a todos os aplicativos em execução com os parâmetros de mensagem a seguir.

Parâmetros Significado
wParam Novos bits por pixel
LOWORD(lParam) Nova largura de pixel
HIWORD(lParam) Nova altura do pixel
 

Para alterar as configurações de mais de uma exibição ao mesmo tempo, primeiro chame ChangeDisplaySettingsEx para cada dispositivo individualmente para atualizar o registro sem aplicar as alterações. Em seguida, chame ChangeDisplaySettingsEx mais uma vez, com um dispositivo NULL , para aplicar as alterações. Por exemplo, para alterar as configurações de duas exibições, faça o seguinte:


ChangeDisplaySettingsEx (lpszDeviceName1, lpDevMode1, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (lpszDeviceName2, lpDevMode2, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (NULL, NULL, NULL, 0, NULL);

Virtualização de DPI

Essa API não participa da virtualização de DPI. A entrada 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 ChangeDisplaySettingsEx 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)

Confira também

Createdc

DEVMODE

Funções de contexto do dispositivo

Visão geral dos contextos do dispositivo

Enumdisplaydevices

EnumDisplaySettings

VIDEOPARAMETERS

WM_DISPLAYCHANGE