Classe `CScrollBar`

Artigo
06/16/2023

Fornece a funcionalidade de um controle de barra de rolagem do Windows.

Sintaxe

class CScrollBar : public CWnd

Membros

Construtores públicos

Nome	Descrição
`CScrollBar::CScrollBar`	Constrói um objeto `CScrollBar`.

Métodos públicos

Nome	Descrição
`CScrollBar::Create`	Cria a barra de rolagem do Windows e a anexa ao objeto `CScrollBar`.
`CScrollBar::EnableScrollBar`	Habilita ou desabilita uma ou ambas as setas de uma barra de rolagem.
`CScrollBar::GetScrollBarInfo`	Recupera informações sobre a barra de rolagem usando uma estrutura `SCROLLBARINFO`.
`CScrollBar::GetScrollInfo`	Recupera as informações sobre a barra de rolagem.
`CScrollBar::GetScrollLimit`	Recupera o limite da barra de rolagem
`CScrollBar::GetScrollPos`	Recupera a posição atual de uma caixa de rolagem.
`CScrollBar::GetScrollRange`	Recupera as posições de barra de rolagem mínima e máxima atuais para a barra de rolagem fornecida.
`CScrollBar::SetScrollInfo`	Define as informações da barra de rolagem.
`CScrollBar::SetScrollPos`	Define a posição atual de uma caixa de rolagem.
`CScrollBar::SetScrollRange`	Define valores mínimos e máximos de posição para a barra de rolagem fornecida.
`CScrollBar::ShowScrollBar`	Mostra ou oculta uma barra de rolagem.

Comentários

Você cria um controle de barra de rolagem em duas etapas. Primeiro, chame o construtor CScrollBar para construir o objeto CScrollBar, então chame a função de membro Create para criar o controle de barra de rolagem do Windows e anexá-lo ao objeto CScrollBar.

Se você criar um objeto CScrollBar dentro de uma caixa de diálogo (por meio de um recurso de caixa de diálogo), CScrollBar será destruído automaticamente quando o usuário fechar a caixa de diálogo.

Se você criar um objeto CScrollBar dentro de uma janela, talvez também seja necessário destruí-lo.

Se você criar o objeto CScrollBar na pilha, ele será destruído automaticamente. Se você criar o objeto CScrollBar no heap usando a função new, deverá chamar o objeto delete para destruí-lo quando o usuário terminar a barra de rolagem do Windows.

Se você alocar qualquer memória no objeto CScrollBar, substitua o destruidor CScrollBar para descartar as alocações.

Para informações relacionadas sobre como usar CScrollBar, confira Controles.

Hierarquia de herança

CObject

CCmdTarget

CWnd

CScrollBar

Requisitos

Cabeçalho: afxwin.h

`CScrollBar::Create`

Cria a barra de rolagem do Windows e a anexa ao objeto CScrollBar.

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parâmetros

dwStyle
Especifica o estilo da barra de rolagem. Aplique qualquer combinação de estilos de barra de rolagem à barra de rolagem.

rect
Especifica o tamanho e a posição da barra de rolagem. Pode ser uma estrutura RECT ou um objeto CRect.

pParentWnd
Especifica a janela pai da barra de rolagem, geralmente um objeto CDialog. Não deve ser NULL.

nID
A ID de controle da barra de rolagem.

Valor de retorno

Diferente de zero se tiver êxito; caso contrário, 0.

Comentários

Um objeto CScrollBar é construído em duas etapas. Primeiro, chame o construtor, que constrói o objeto CScrollBar; então, chame Create, o que cria e inicializa a barra de rolagem associada do Windows e a anexa ao objeto CScrollBar.

Aplique os seguintes estilos de janela a uma barra de rolagem:

WS_CHILD Sempre
WS_VISIBLE Geralmente
WS_DISABLED Raramente
WS_GROUP Para grupar controles

Exemplo

// Example 1:
// Create a horizontal CScrollBar control as a child window of CMyDialog
// class (a CDialog-derived class). The scroll bar is NOT visible until the
// call ShowScrollBar() is made. m_ScrollBarHorz is of type CScrollBar class,
// and it is a member variable in CMyDialog class.
VERIFY(m_ScrollBarHorz.Create(SBS_HORZ | SBS_TOPALIGN | WS_CHILD,
                              CRect(5, 5, 100, 30), this, IDC_SCROLLBARCTRL));

m_ScrollBarHorz.ShowScrollBar();

// Example 2:
// Create a vertical CScrollBar control as a child window of CMyDialog
// class (a CDialog-derived class). m_ScrollBarVert is of type CScrollBar
// class, and it is a member variable in CMyDialog class.
VERIFY(m_ScrollBarVert.Create(SBS_VERT | SBS_LEFTALIGN | WS_CHILD |
                                  WS_VISIBLE,
                              CRect(5, 30, 30, 130), this, IDC_SCROLLBARCTRL));

`CScrollBar::CScrollBar`

Constrói um objeto CScrollBar.

CScrollBar();

Comentários

Depois de construir o objeto, chame a função de membro Create para criar e inicializar a barra de rolagem do Windows.

Exemplo

CScrollBar m_ScrollBarHorz;

`CScrollBar::EnableScrollBar`

Habilita ou desabilita uma ou ambas as setas de uma barra de rolagem.

BOOL EnableScrollBar(UINT nArrowFlags = ESB_ENABLE_BOTH);

Parâmetros

nArrowFlags
Especifica se as setas de rolagem estão habilitadas ou desabilitadas e quais setas estão habilitadas ou desabilitadas. Esse parâmetro pode usar um dos valores a seguir:

ESB_ENABLE_BOTH Habilita as duas setas de uma barra de rolagem.
ESB_DISABLE_LTUP Desabilita a seta para a esquerda de uma barra de rolagem horizontal ou a seta para cima de uma barra de rolagem vertical.
ESB_DISABLE_RTDN Desabilita a seta para a direita de uma barra de rolagem horizontal ou a seta para baixo de uma barra de rolagem vertical.
ESB_DISABLE_BOTH Desabilita as duas setas de uma barra de rolagem.

Valor de retorno

Não zero se as setas estiverem habilitadas ou desabilitadas conforme especificado; caso contrário, 0, que indica que as setas já estão no estado solicitado ou que ocorreu um erro.

Exemplo

Confira o exemplo de CScrollBar::SetScrollRange.

`CScrollBar::GetScrollBarInfo`

Recupera as informações que a estrutura SCROLLBARINFO mantém sobre uma barra de rolagem.

BOOL GetScrollBarInfo(PSCROLLBARINFO pScrollInfo) const;

Parâmetros

pScrollInfo
Um ponteiro para a estrutura SCROLLBARINFO.

Valor de retorno

Retornará TRUE se for bem-sucedido, FALSE em caso de falha.

Comentários

Essa função de membro emula a funcionalidade da mensagem SBM_SCROLLBARINFO, conforme descrito no SDK do Windows.

`CScrollBar::GetScrollInfo`

Recupera as informações que a estrutura SCROLLINFO mantém sobre uma barra de rolagem.

BOOL GetScrollInfo(
    LPSCROLLINFO lpScrollInfo,
    UINT nMask = SIF_ALL);

Parâmetros

lpScrollInfo
Um ponteiro para uma estrutura SCROLLINFO. Para obter mais informações sobre essa estrutura, consulte o SDK do Windows.

nMask
Especifica os parâmetros da barra de rolagem a serem recuperados. Uso típico, SIF_ALL, especifica uma combinação de SIF_PAGE, SIF_POS, SIF_TRACKPOS e SIF_RANGE. Confira SCROLLINFO para mais informações sobre os valores nMask.

Valor de retorno

Se a mensagem tiver recuperado qualquer valor, o retorno será TRUE. Caso contrário, é FALSE.

Comentários

GetScrollInfo permite que os aplicativos usem posições de rolagem de 32 bits.

A estrutura SCROLLINFO contém informações sobre uma barra de rolagem, incluindo as posições de rolagem mínimas e máximas, o tamanho da página e a posição da caixa de rolagem (o polegar). Confira o tópico de estrutura SCROLLINFO no SDK do Windows para mais informações sobre como alterar os padrões de estrutura.

Os manipuladores de mensagens do Windows MFC que indicam a posição da barra de rolagem, CWnd::OnHScroll e CWnd::OnVScroll, fornecem apenas 16 bits de dados de posição. GetScrollInfo e SetScrollInfo fornecem 32 bits de dados de posição da barra de rolagem. Assim, um aplicativo pode chamar GetScrollInfo durante o processamento de CWnd::OnHScroll ou CWnd::OnVScroll para obter dados de posição da barra de rolagem de 32 bits.

Exemplo

Confira o exemplo de CWnd::OnHScroll.

`CScrollBar::GetScrollLimit`

Recupera a posição máxima de rolagem da barra de rolagem.

int GetScrollLimit();

Valor de retorno

Especifica a posição máxima de uma barra de rolagem se tiver êxito; caso contrário, 0.

Exemplo

Confira o exemplo de CWnd::OnHScroll.

`CScrollBar::GetScrollPos`

Recupera a posição atual de uma caixa de rolagem.

int GetScrollPos() const;

Valor de retorno

Especifica a posição atual da caixa de rolagem se tiver êxito; caso contrário, 0.

Comentários

A posição atual é um valor relativo que depende do intervalo de rolagem atual. Por exemplo, se o intervalo de rolagem for de 100 a 200 e a caixa de rolagem estiver no meio da barra, a posição atual será 150.

Exemplo

Confira o exemplo de CWnd::OnHScroll.

`CScrollBar::GetScrollRange`

Copia as posições de barra de rolagem mínimas e máximas atuais para a barra de rolagem fornecida para os locais especificados por lpMinPos e lpMaxPos.

void GetScrollRange(
    LPINT lpMinPos,
    LPINT lpMaxPos) const;

Parâmetros

lpMinPos
Aponta para a variável inteira que deve receber a posição mínima.

lpMaxPos
Aponta para a variável inteira que deve receber a posição máxima.

Comentários

O intervalo padrão para um controle de barra de rolagem está vazio (ambos os valores são 0).

Exemplo

Confira o exemplo de CWnd::OnHScroll.

`CScrollBar::SetScrollInfo`

Define as informações que a estrutura SCROLLINFO mantém sobre uma barra de rolagem.

BOOL SetScrollInfo(
    LPSCROLLINFO lpScrollInfo,
    BOOL bRedraw = TRUE);

Parâmetros

lpScrollInfo
Um ponteiro para uma estrutura SCROLLINFO.

bRedraw
Especifica se a barra de rolagem deve ser redesenhada para refletir as novas informações. Se bRedraw for TRUE, a barra de rolagem será redesenhada. Se for FALSE, ela não será redesenhada. A barra de rolagem será redesenhada por padrão.

Valor de retorno

Se tiver êxito, o retorno será TRUE. Caso contrário, é FALSE.

Comentários

Você deve fornecer os valores exigidos pelos parâmetros de estrutura SCROLLINFO, incluindo os valores de sinalizador.

Exemplo

// Set SCROLLINFO for the scroll bar. m_ScrollBarHorz is of type
// CScrollBar class, and it is a member variable in CMyDialog class.
SCROLLINFO info;
info.cbSize = sizeof(SCROLLINFO);
info.fMask = SIF_ALL;
info.nMin = 0;
info.nMax = 10;
info.nPage = 2;
info.nPos = 5;
info.nTrackPos = 2;
m_ScrollBarHorz.SetScrollInfo(&info);

`CScrollBar::SetScrollPos`

Define a posição atual de uma caixa de rolagem como a especificada nPos e, se especificada, redesenha a barra de rolagem para refletir a nova posição.

int SetScrollPos(
    int nPos,
    BOOL bRedraw = TRUE);

Parâmetros

nPos
Especifica a nova posição da caixa de rolagem. Ela deve ficar dentro do intervalo de rolagem.

bRedraw
Especifica se a barra de rolagem deve ser redesenhada para refletir a nova posição. Se bRedraw for TRUE, a barra de rolagem será redesenhada. Se for FALSE, ela não será redesenhada. A barra de rolagem será redesenhada por padrão.

Valor de retorno

Especifica a posição anterior da caixa de rolagem se tiver êxito; caso contrário, 0.

Comentários

Defina bRedraw como FALSE sempre que a barra de rolagem for redesenhada por uma chamada subsequente para outra função para evitar que a barra de rolagem seja redesenhada duas vezes em um intervalo curto.

Exemplo

Confira o exemplo de CScrollBar::SetScrollRange.

`CScrollBar::SetScrollRange`

Define valores mínimos e máximos de posição para a barra de rolagem fornecida.

void SetScrollRange(
    int nMinPos,
    int nMaxPos,
    BOOL bRedraw = TRUE);

Parâmetros

nMinPos
Especifica a posição mínima de rolagem.

nMaxPos
Especifica a posição máxima de rolagem.

bRedraw
Especifica se a barra de rolagem deve ser redesenhada para refletir a alteração. Se bRedraw for TRUE, a barra de rolagem será redesenhada; se FALSE, ela não será redesenhada. É redesenhada por padrão.

Comentários

Defina nMinPos e nMaxPos como 0 para ocultar barras de rolagem padrão.

Não chame essa função para ocultar uma barra de rolagem ao processar uma mensagem de notificação da barra de rolagem.

Se uma chamada para SetScrollRange seguir imediatamente uma chamada para a função de membro SetScrollPos, defina bRedraw em SetScrollPos como 0 para impedir que a barra de rolagem seja redesenhada duas vezes.

A diferença entre os valores especificados por nMinPos e nMaxPos não deve ser maior que 32.767. O intervalo padrão para um controle de barra de rolagem está vazio (nMinPos e nMaxPos são 0).

Exemplo

// Sets minimum (0) and maximum (10) position values for the
// CScrollBar control. m_ScrollBarVert is of type CScrollBar class,
// and it is a member variable in CMyDialog class.
m_ScrollBarVert.SetScrollRange(0, 10);

// Set the position of the scroll box.
m_ScrollBarVert.SetScrollPos(5);

// Disable the down arrow of the scroll bar. By default, both arrows
// are enabled.
m_ScrollBarVert.EnableScrollBar(ESB_DISABLE_DOWN);

`CScrollBar::ShowScrollBar`

Mostra ou oculta uma barra de rolagem.

void ShowScrollBar(BOOL bShow = TRUE);

Parâmetros

bShow
Especifica se a barra de rolagem é mostrada ou oculta. Se esse parâmetro for TRUE, a barra de rolagem será mostrada; caso contrário, ela ficará oculta.

Comentários

Um aplicativo não deve chamar essa função para ocultar uma barra de rolagem durante o processamento de uma mensagem de notificação da barra de rolagem.

Exemplo

Confira o exemplo de CScrollBar::Create.

Confira também

Classe CWnd
Gráfico da hierarquia
Classe CButton
Classe CComboBox
Classe CEdit
Classe CListBox
Classe CStatic
Classe CDialog

Partilhar via

Classe CScrollBar

Sintaxe

Membros

Construtores públicos

Métodos públicos

Comentários

Hierarquia de herança

Requisitos

CScrollBar::Create

Parâmetros

Valor de retorno

Comentários

Exemplo

CScrollBar::CScrollBar

Comentários

Exemplo

CScrollBar::EnableScrollBar

Parâmetros

Valor de retorno

Exemplo

CScrollBar::GetScrollBarInfo

Parâmetros

Valor de retorno

Comentários

CScrollBar::GetScrollInfo

Parâmetros

Valor de retorno

Comentários

Exemplo

CScrollBar::GetScrollLimit

Valor de retorno

Exemplo

CScrollBar::GetScrollPos

Valor de retorno

Comentários

Exemplo

CScrollBar::GetScrollRange

Parâmetros

Comentários

Exemplo

CScrollBar::SetScrollInfo

Parâmetros

Valor de retorno

Comentários

Exemplo

CScrollBar::SetScrollPos

Parâmetros

Valor de retorno

Comentários

Exemplo

CScrollBar::SetScrollRange

Parâmetros

Comentários

Exemplo

CScrollBar::ShowScrollBar

Parâmetros

Comentários

Exemplo

Confira também

Comentários

Recursos adicionais

Classe `CScrollBar`

`CScrollBar::Create`

`CScrollBar::CScrollBar`

`CScrollBar::EnableScrollBar`

`CScrollBar::GetScrollBarInfo`

`CScrollBar::GetScrollInfo`

`CScrollBar::GetScrollLimit`

`CScrollBar::GetScrollPos`

`CScrollBar::GetScrollRange`

`CScrollBar::SetScrollInfo`

`CScrollBar::SetScrollPos`

`CScrollBar::SetScrollRange`

`CScrollBar::ShowScrollBar`