QScrollBar Class Reference

The QScrollBar widget provides a vertical or horizontal scroll bar. More...

#include <qscrollbar.h>

Inherits QRangeControl and QWidget.

List of all member functions.

Public Members

• QScrollBar ( QWidget * parent, const char * name=0 ) 
• QScrollBar ( Orientation, QWidget * parent, const char * name=0 ) 
• QScrollBar ( int minValue, int maxValue, int LineStep, int PageStep, int value, Orientation, QWidget * parent, const char * name=0 ) 
• virtual void setOrientation ( Orientation ) 
• Orientation orientation () const
• virtual void setTracking ( bool enable ) 
• bool tracking () const
• bool draggingSlider () const
• virtual void setPalette ( const QPalette & ) 
• void setMinValue ( int ) 
• void setMaxValue ( int ) 
• void setLineStep ( int ) 
• void setPageStep ( int ) 

Signals

• void valueChanged ( int value ) 
• void sliderPressed () 
• void sliderMoved ( int value ) 
• void sliderReleased () 
• void nextLine () 
• void prevLine () 
• void nextPage () 
• void prevPage () 

Protected Members

• virtual void valueChange () (internal)
• virtual void stepChange () (internal)
• virtual void rangeChange () (internal)
• int sliderStart () const
• QRect sliderRect () const

Properties

Type	Name	READ	WRITE	Options
int	minValue	minValue	setMinValue
int	maxValue	maxValue	setMaxValue
int	lineStep	lineStep	setLineStep
int	pageStep	pageStep	setPageStep
int	value	value	setValue
bool	tracking	tracking	setTracking
bool	draggingSlider	draggingSlider
Orientation	orientation	orientation	setOrientation

---

Detailed Description

The QScrollBar widget provides a vertical or horizontal scroll bar.

A scroll bar allows the user to control a value within a program-definable range, and to give the user visible indication of the current value of a range control.

Scroll bars include four separate controls:

• The line-up and line-down controls are little button with which the user can move one line up or down. The meaning of "line" is configurable. In editors and list boxes it means one line of text, while an image viewer it might mean 20 pixels.
• The slider is the handle that indicates the current value of the scroll bar, and which the user can drag to change the value. This part of the scroll bar is sometimes called the "thumb".
• The page-up/down control is the area on which the slider slides (the scroll bar's background). Clicking here moves the scroll bar towards the click. The meaning of page is also configurable - in editors and list boxes it means as many lines as there is space for in the widget.

QScrollBar has not much of an API of its own; it mostly relies on QRangeControl. The most useful functions are setValue() to set the scroll bar directly to some value; addPage(), addLine(), subtractPage() and subtractLine() to simulate the effects of clicking (useful for accelerator keys; setSteps() to define the values of pageStep() and lineStep(); and setRange() to set the minValue() and maxValue() of the scroll bar. QScrollBar has a convenience constructor with which you can set most of these properties.

Some GUI styles, for example the provided Windows and Motif styles, also use the pageStep() value to calculate the size of the slider.

In addition to the access functions from QRangeControl, QScrollBar has a comprehensive set of signals:

• valueChanged() - emitted when the scroll bar's value has changed. The tracking() determines whether this signal is emitted during interaction.
• sliderPressed() - emitted when the user starts to drag the slider
• sliderMoved() - emitted when the user drags the slider
• sliderReleased() - emitted when the user releases the slider
• nextLine() - emitted when the scroll bar has moved one line down/rightwards. Line is defined in QRangeControl.
• prevLine() - emitted when the scroll bar has moved one line up/leftwards.
• nextPage() - emitted when the scroll bar has moved one page down/rightwards.
• prevPage() - emitted when the scroll bar has moved one page up/leftwards.

QScrollBar only offers integer ranges. Note that while QScrollBar handles very large numbers, scroll bars on today's screens cannot usefully control ranges above about 100,000 pixels. Beyond that, it becomes difficult for the user to control the scroll bar using either keyboard or mouse.

A scroll bar can be controlled by the keyboard, but it has a default focusPolicy() of NoFocus. Use setFocusPolicy() to enable keyboard focus. See keyPressEvent() for a list of key bindings.

If you need to add scrollbars to an interface, consider using the QScrollView class which encapsulates the common uses for scrollbars.

See also QSlider, QSpinBox, QScrollView and GUI Design Handbook: Scroll Bar

---

Member Function Documentation

QScrollBar::QScrollBar ( Orientation orientation, QWidget * parent, const char * name=0 )

Constructs a scroll bar.

The orientation must be QScrollBar::Vertical or QScrollBar::Horizontal.

The parent and name arguments are sent to the QWidget constructor.

QScrollBar::QScrollBar ( QWidget * parent, const char * name=0 )

Constructs a vertical scroll bar.

The parent and name arguments are sent to the QWidget constructor.

QScrollBar::QScrollBar ( int minValue, int maxValue, int lineStep, int pageStep, int value, Orientation orientation, QWidget * parent, const char * name=0 )

Constructs a scroll bar.

Arguments:

• minValue is the minimum scroll bar value.
• maxValue is the maximum scroll bar value.
• lineStep is the line step value.
• pageStep is the page step value. It is also used to calculate the size of the slider.
• value is the initial value.
• orientation must be QScrollBar::Vertical or QScrollBar::Horizontal.

The parent and name arguments are sent to the QWidget constructor.

bool QScrollBar::draggingSlider () const

Returns TRUE if the user has clicked the mouse on the slider and is currently dragging it, or FALSE if not.

void QScrollBar::keyPressEvent ( QKeyEvent * e ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

int QScrollBar::lineStep () const

Reimplemented for internal reasons; the API is not affected.

int QScrollBar::maxValue () const

Reimplemented for internal reasons; the API is not affected.

int QScrollBar::minValue () const

Reimplemented for internal reasons; the API is not affected.

void QScrollBar::mouseMoveEvent ( QMouseEvent * e ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::mousePressEvent ( QMouseEvent * e ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::mouseReleaseEvent ( QMouseEvent * e ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::nextLine () [signal]

This signal is emitted when the scroll bar scrolls one line down/right.

void QScrollBar::nextPage () [signal]

This signal is emitted when the scroll bar scrolls one page down/right.

Orientation QScrollBar::orientation () const

Returns the orientation of the scroll bar; QScrollBar::Vertical or QScrollBar::Horizontal.

See also setOrientation().

int QScrollBar::pageStep () const

Reimplemented for internal reasons; the API is not affected.

void QScrollBar::paintEvent ( QPaintEvent * ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::prevLine () [signal]

This signal is emitted when the scroll bar scrolls one line up/left.

void QScrollBar::prevPage () [signal]

This signal is emitted when the scroll bar scrolls one page up/left.

void QScrollBar::resizeEvent ( QResizeEvent * ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::setLineStep ( int i )

Sets the line step to i.

Calls the virtual stepChange() function if the new line step is different from the previous setting.

See also lineStep(), QRangeControl::setSteps(), setPageStep() and setRange().

void QScrollBar::setMaxValue ( int i )

A convenience function which just calls setRange( minValue(), i )

See also setRange().

void QScrollBar::setMinValue ( int i )

A convenience function which just calls setRange( i, maxValue() )

See also setRange().

void QScrollBar::setOrientation ( Orientation orientation ) [virtual]

Sets the scroll bar orientation. The orientation must be QScrollBar::Vertical or QScrollBar::Horizontal.

See also orientation().

void QScrollBar::setPageStep ( int i )

Sets the page step to i.

Calls the virtual stepChange() function if the new page step is different from the previous setting.

See also pageStep(), QRangeControl::setSteps(), setLineStep() and setRange().

void QScrollBar::setPalette ( const QPalette & p ) [virtual]

Reimplements the virtual function QWidget::setPalette().

Sets the background color to the mid color for Motif style scroll bars.

void QScrollBar::setTracking ( bool enable ) [virtual]

Enables scroll bar tracking if enable is TRUE, or disables tracking if enable is FALSE.

If tracking is enabled (the default), the scroll bar emits the valueChanged() signal while the slider is being dragged. If tracking is disabled, the scroll bar emits the valueChanged() signal only when the user releases the mouse button after moving the slider.

See also tracking().

void QScrollBar::setValue ( int i )

Reimplemented for internal reasons; the API is not affected.

QSize QScrollBar::sizeHint () const [virtual]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

QSizePolicy QScrollBar::sizePolicy () const [virtual]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::sliderMoved ( int value ) [signal]

This signal is emitted when the slider is moved by the user, with the new scroll bar value as an argument.

This signal is emitted even when tracking is turned off.

See also tracking(), valueChanged(), nextLine(), prevLine(), nextPage() and prevPage().

void QScrollBar::sliderPressed () [signal]

This signal is emitted when the user presses the slider with the mouse.

QRect QScrollBar::sliderRect () const [protected]

Returns the scroll bar slider rectangle.

See also sliderStart().

void QScrollBar::sliderReleased () [signal]

This signal is emitted when the user releases the slider with the mouse.

int QScrollBar::sliderStart () const [protected]

Returns the pixel position where the scroll bar slider starts.

It is equivalent to sliderRect().y() for vertical scroll bars or sliderRect().x() for horizontal scroll bars.

void QScrollBar::styleChange ( QStyle & old ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

bool QScrollBar::tracking () const

Returns TRUE if tracking is enabled, or FALSE if tracking is disabled.

Tracking is initially enabled.

See also setTracking().

int QScrollBar::value () const

Reimplemented for internal reasons; the API is not affected.

void QScrollBar::valueChanged ( int value ) [signal]

This signal is emitted when the scroll bar value has changed, with the new scroll bar value as an argument.

void QScrollBar::wheelEvent ( QWheelEvent * e ) [virtual protected]

Reimplemented for internal reasons; the API is not affected.

Reimplemented from QWidget.

void QScrollBar::rangeChange () [virtual protected]

For internal use only.

Reimplemented from QRangeControl.

void QScrollBar::stepChange () [virtual protected]

For internal use only.

Reimplemented from QRangeControl.

void QScrollBar::valueChange () [virtual protected]

For internal use only.

Reimplemented from QRangeControl.

---

Search the documentation, FAQ, qt-interest archive and more (uses www.trolltech.com):

---

This file is part of the Qt toolkit, copyright © 1995-2005 Trolltech, all rights reserved.