Função ChangeDisplaySettingsW (winuser.h)

Artigo
11/20/2024

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

Para alterar as configurações de um dispositivo de exibição especificado, use a função ChangeDisplaySettingsEx.

Observação Aplicativos que você projeta para o Windows 8 e posterior não pode 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 ao Windows 8. O 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 do Windows 8; O Windows 8 emula esses modos, mas ainda é executado no modo de cor de 32 bits.

Sintaxe

LONG ChangeDisplaySettingsW(
  [in] DEVMODEW *lpDevMode,
  [in] DWORD    dwFlags
);

Parâmetros

[in] lpDevMode

Um ponteiro para uma estrutura de 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 dmSize membro de DEVMODE deve ser inicializado para o tamanho, em bytes, da estrutura de DEVMODE. O dmDriverExtra membro de DEVMODE deve ser inicializado para indicar o número de bytes de dados de driver privados seguindo a estrutura de DEVMODE . Além disso, você pode usar qualquer um ou todos os membros a seguir da estrutura de DEVMODE .

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

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

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

[in] dwFlags

Indica como o modo gráfico deve ser alterado. Esse parâmetro pode ser 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ê alterar 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 as mesmas das 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.

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 esse modo gráfico.

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á retornado. 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á retornada.

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.

Valor de retorno

A função ChangeDisplaySettings 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 teve êxito porque o sistema é capaz de 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.

Observações

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

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

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

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.

Nota

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

Consulte também

ChangeDisplaySettingsEx

CreateDC

DEVMODE

Funções de contexto do dispositivo

Visão geral dos contextos do dispositivo

EnumDisplayDevices

EnumDisplaySettings

WM_DISPLAYCHANGE

Compartilhar via