Qtopia Home - Classes - Hierachy - Annotated - Functions - Licenses - Reference

QScrollBar Class Reference

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

#include <qscrollbar.h>

Inherits QWidget and QRangeControl.

List of all member functions.

Public Members

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

Signals

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

Properties

• bool draggingSlider  (read only)
• int lineStep
• int maxValue
• int minValue
• Orientation orientation
• int pageStep
• bool tracking
• int value

Protected Members

• int sliderStart () const
• QRect sliderRect () const

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 ( QWidget * parent, const char * name = 0 )

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

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

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

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 )

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

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

bool QScrollBar::draggingSlider () const

void QScrollBar::nextLine () [signal]

void QScrollBar::nextPage () [signal]

Orientation QScrollBar::orientation () const

See also setOrientation().

void QScrollBar::prevLine () [signal]

void QScrollBar::prevPage () [signal]

void QScrollBar::setLineStep ( int 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 )

See also setRange().

void QScrollBar::setMinValue ( int i )

See also setRange().

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

See also orientation().

void QScrollBar::setPageStep ( int 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]

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

Reimplemented from QWidget.

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

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::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]

QRect QScrollBar::sliderRect () const [protected]

See also sliderStart().

void QScrollBar::sliderReleased () [signal]

int QScrollBar::sliderStart () const [protected]

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

bool QScrollBar::tracking () const

Tracking is initially enabled.

See also setTracking().

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

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