Função ScrollWindowEx (winuser.h)

Artigo
08/28/2023

A função ScrollWindowEx rola o conteúdo da área de cliente da janela especificada.

Sintaxe

int ScrollWindowEx(
  [in]  HWND       hWnd,
  [in]  int        dx,
  [in]  int        dy,
  [in]  const RECT *prcScroll,
  [in]  const RECT *prcClip,
  [in]  HRGN       hrgnUpdate,
  [out] LPRECT     prcUpdate,
  [in]  UINT       flags
);

Parâmetros

[in] hWnd

Tipo: HWND

Identificador para a janela em que a área do cliente deve ser rolada.

[in] dx

Tipo: int

Especifica a quantidade, em unidades de dispositivo, da rolagem horizontal. Esse parâmetro deve ser um valor negativo para rolar para a esquerda.

[in] dy

Tipo: int

Especifica a quantidade, em unidades de dispositivo, da rolagem horizontal. Esse parâmetro deve ser um valor negativo para rolar para cima.

[in] prcScroll

Tipo: const RECT*

Ponteiro para uma estrutura RECT que especifica a parte da área do cliente a ser rolada. Se esse parâmetro for NULL, toda a área do cliente será rolada.

[in] prcClip

Tipo: const RECT*

Ponteiro para uma estrutura RECT que contém as coordenadas do retângulo de recorte. Somente os bits de dispositivo dentro do retângulo de recorte são afetados. Os bits rolados do lado de fora do retângulo para dentro são pintados; bits rolados de dentro do retângulo para fora não são pintados. Esse parâmetro pode ser NULL.

[in] hrgnUpdate

Tipo: HRGN

Manipule para a região modificada para manter a região invalidada pela rolagem. Esse parâmetro pode ser NULL.

[out] prcUpdate

Tipo: LPRECT

Ponteiro para uma estrutura RECT que recebe os limites do retângulo invalidados pela rolagem. Esse parâmetro pode ser NULL.

[in] flags

Tipo: UINT

Especifica sinalizadores que controlam a rolagem. Esse parâmetro pode ser uma combinação dos seguintes valores.

Valor	Significado
SW_ERASE	Apaga a região recém-invalidada enviando uma mensagem WM_ERASEBKGND para a janela quando especificada com o sinalizador SW_INVALIDATE.
SW_INVALIDATE	Invalida a região identificada pelo parâmetro hrgnUpdate após a rolagem.
SW_SCROLLCHILDREN	Rola todas as janelas filho que cruzam o retângulo apontado pelo parâmetro prcScroll . As janelas filho são roladas pelo número de pixels especificado pelos parâmetros dx e dy . O sistema envia uma mensagem WM_MOVE para todas as janelas filho que cruzam o retângulo prcScroll , mesmo que elas não se movam.
SW_SMOOTHSCROLL	Rola usando rolagem suave. Use a parte HIWORD do parâmetro flags para indicar quanto tempo, em milissegundos, a operação de rolagem suave deve levar.

Valor retornado

Tipo: int

Se a função for bem-sucedida, o valor retornado será SIMPLEREGION (região invalidada retangular), COMPLEXREGION (região invalidada não retangular; retângulos sobrepostos) ou NULLREGION (nenhuma região invalidada).

Se a função falhar, o valor retornado será ERROR. Para obter informações de erro estendidas, chame GetLastError.

Comentários

Se os sinalizadores SW_INVALIDATE e SW_ERASE não forem especificados, ScrollWindowEx não invalida a área de rolagem. Se um desses sinalizadores estiver definido, ScrollWindowEx invalida essa área. A área não é atualizada até que o aplicativo chame a função UpdateWindow , chame a função RedrawWindow (especificando o sinalizador RDW_UPDATENOW ou RDW_ERASENOW) ou recupere a mensagem WM_PAINT da fila do aplicativo.

Se a janela tiver o estilo WS_CLIPCHILDREN , as áreas retornadas especificadas por hrgnUpdate e prcUpdate representarão a área total da janela rolada que deve ser atualizada, incluindo todas as áreas nas janelas filho que precisam ser atualizadas.

Se o sinalizador SW_SCROLLCHILDREN for especificado, o sistema não atualizará corretamente a tela se parte de uma janela filho for rolada. A parte da janela filho rolada que fica fora do retângulo de origem não é apagada e não é redesenhada corretamente em seu novo destino. Para mover janelas filho que não estão completamente dentro do retângulo especificado por prcScroll, use a função DeferWindowPos . O cursor será reposicionado se o sinalizador SW_SCROLLCHILDREN estiver definido e o retângulo de circunflexo cruzar o retângulo de rolagem.

Todas as coordenadas de entrada e saída (para prcScroll, prcClip, prcUpdate e hrgnUpdate) são determinadas como coordenadas do cliente, independentemente de a janela ter o estilo de classe CS_OWNDC ou CS_CLASSDC . Use as funções LPtoDP e DPtoLP para converter de e para coordenadas lógicas, se necessário.

Exemplos

Para obter um exemplo, consulte Rolando texto com a mensagem WM_PAINT.

Requisitos


Cliente mínimo com suporte	Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte	Windows Server 2003 [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-misc-l1-2-0 (introduzido no Windows 8.1)