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.
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 |
|---|---|
|
O modo gráfico da tela atual será alterado dinamicamente. |
|
O modo é temporário por natureza.
Se você mudar de e para outra área de trabalho, esse modo não será redefinido. |
|
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. |
|
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. |
|
As configurações devem ser alteradas, mesmo que as configurações solicitadas sejam iguais às configurações atuais. |
|
Esse dispositivo se tornará o dispositivo principal. |
|
O sistema testa se o modo gráfico solicitado pode ser definido. |
|
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. |
|
Quando definido, o parâmetro lParam é um ponteiro para uma estrutura VIDEOPARAMETERS . |
|
Habilita as alterações de configurações em modos gráficos não seguros. |
|
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 |
|---|---|
|
A alteração das configurações foi bem-sucedida. |
|
A alteração das configurações não foi bem-sucedida porque o sistema é compatível com DualView. |
|
Um conjunto inválido de sinalizadores foi passado. |
|
Não há suporte para o modo gráfico. |
|
Um parâmetro inválido foi passado. Isso pode incluir um sinalizador inválido ou uma combinação de sinalizadores. |
|
O driver de exibição falhou no modo gráfico especificado. |
|
Não é possível gravar configurações no registro. |
|
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
Funções de contexto do dispositivo