Qt Toolkit - QScrollView Class

# QScrollView Class Reference

The QScrollView widget provides a scrolling area with on-demand scrollbars. More...

`#include <qscrollview.h>`

Inherits QFrame.

Inherited by QListView.

List of all member functions.

## Public Members

- QScrollView ( QWidget * parent=0, const char * name=0, WFlags f=0 )
- ~QScrollView ()
- enum ResizePolicy { Default, Manual, AutoOne }
- virtual void setResizePolicy ( ResizePolicy )
- ResizePolicy resizePolicy () const
- void addChild ( QWidget * child )
- void removeChild ( QWidget * child )
- virtual void addChild ( QWidget * child, int x, int y )
- virtual void moveChild ( QWidget * child, int x, int y )
- int childX ( QWidget * child )
- int childY ( QWidget * child )
- bool childIsVisible ( QWidget * child )
- void showChild ( QWidget * child, bool yes=TRUE )
- enum ScrollBarMode { Auto, AlwaysOff, AlwaysOn }
- ScrollBarMode vScrollBarMode () const
- virtual void setVScrollBarMode ( ScrollBarMode )
- ScrollBarMode hScrollBarMode () const
- virtual void setHScrollBarMode ( ScrollBarMode )
- QWidget* cornerWidget () const
- virtual void setCornerWidget ( QWidget * )
- QScrollBar* horizontalScrollBar ()
- QScrollBar* verticalScrollBar ()
- QWidget* viewport ()
- int contentsWidth () const
- int contentsHeight () const
- int contentsX () const
- int contentsY () const
- void resize ( int w, int h )
- void resize ( const QSize & )
- virtual void show ()

## Public Slots

- virtual void resizeContents ( int w, int h )
- void scrollBy ( int dx, int dy )
- void setContentsPos ( int x, int y )
- void ensureVisible ( int x, int y )
- void ensureVisible ( int x, int y, int xmargin, int ymargin )
- void center ( int x, int y )
- void center ( int x, int y, float xmargin, float ymargin )
- void updateScrollBars ()

## Signals

- void contentsMoving ( int x, int y )

## Protected Members

- virtual void resizeEvent ( QResizeEvent * )
- virtual bool eventFilter ( QObject *, QEvent * e )
- virtual void viewportPaintEvent ( QPaintEvent * )
- virtual void viewportMousePressEvent ( QMouseEvent * )
- virtual void viewportMouseReleaseEvent ( QMouseEvent * )
- virtual void viewportMouseDoubleClickEvent ( QMouseEvent * )
- virtual void viewportMouseMoveEvent ( QMouseEvent * )
- virtual void drawContentsOffset ( QPainter *, int ox, int oy, int cx, int cy, int cw, int ch )
- virtual void frameChanged ()
- void setMargins ( int left, int top, int right, int bottom )
- int leftMargin () const
- int topMargin () const
- int rightMargin () const
- int bottomMargin () const
- virtual bool focusNextPrevChild ( bool next )

## Detailed Description

The QScrollView widget provides a scrolling area with on-demand scrollbars.

The QScrollView is a large canvas - potentially larger than the coordinate system normally supported by the underlying window system. This is important, as is is quite easy to go beyond such limitations (eg. many web pages are more than 32000 pixels high). Additionally, the QScrollView can have QWidgets positioned on it that scroll around with the drawn content. These subwidgets can also have positions outside the normal coordinate range (but they are still limited in size).

Note that the scrolled area is the viewport() widget, not the QScrollView itself. So, to turn mouse tracking on for example, use viewport()->setMouseTracking(TRUE). The only part of the QScrollView that is visible is the "corner" and the frame.

To provide content for the widget, inherit from QScrollView and override drawContentsOffset(), and use resizeContents() to set the size of the viewed area. Use addChild(), moveChild(), and showChild() to position widgets on the view.

Note also the effect of resizePolicy().

## Member Function Documentation

### QScrollView::QScrollView ( QWidget * parent=0, const char * name=0, WFlags f=0 )

Constructs a QScrollView.

If you intend to add child widgets, you may see improved refresh if you include WPaintClever in the widgets flags, f. WPaintClever will be propagated to the viewport() widget.

### QScrollView::~QScrollView ()

Destructs the QScrollView. Any children added with addChild() will be destructed.

### void QScrollView::addChild ( QWidget * child )

Inserts child into the scrolled area. It is equivalent to addChild(child,0,0).

### void QScrollView::addChild ( QWidget * child, int x, int y ) `[virtual]`

Inserts child into the scrolled area positioned at (x, y). If the child is already in the view, it is just moved.

### int QScrollView::bottomMargin () const `[protected]`

Returns the current bottom margin.

See also: setMargins().

### void QScrollView::center ( int x, int y ) `[slot]`

Scrolls the content so that the point (x,y) is in the center of visible area.

### void QScrollView::center ( int x, int y, float xmargin, float ymargin ) `[slot]`

Scrolls the content so that the point (x,y) is visible, with the given margins (as fractions of visible area).

eg.

- Margin 0.0 allows (x,y) to be on edge of visible area.
- Margin 0.5 ensures (x,y) is in middle 50% of visible area.
- Margin 1.0 ensures (x,y) is in the center of the visible area.

### bool QScrollView::childIsVisible ( QWidget * child )

\obsolete

Returns TRUE if child is visible. This is equivalent to child->isVisible().

### int QScrollView::childX ( QWidget * child )

Returns the X position of the given child widget. Use this rather than QWidget::x() for widgets added to the view.

### int QScrollView::childY ( QWidget * child )

Returns the Y position of the given child widget. Use this rather than QWidget::y() for widgets added to the view.

### int QScrollView::contentsHeight () const

Returns the height of the contents area.

### void QScrollView::contentsMoving ( int x, int y ) `[signal]`

This signal is emitted just before the contents is moved to the given position.

See also: contentsX() and contentsY().

### int QScrollView::contentsWidth () const

Returns the width of the contents area.

### int QScrollView::contentsX () const

Returns the X coordinate of the contents which is at the left edge of the viewport.

### int QScrollView::contentsY () const

Returns the Y coordinate of the contents which is at the top edge of the viewport.

### QWidget* QScrollView::cornerWidget () const

Returns the widget in the corner between the two scrollbars.

By default, no corner widget is present.

### void QScrollView::drawContentsOffset ( QPainter * p, int offsetx, int offsety, int clipx, int clipy, int clipw, int cliph ) `[virtual protected]`

Reimplement this method if you are viewing a drawing area rather than a widget.

Draws the rectangle (clipx, clipy, clipw, cliph ) of the contents, offset by (offsetx, offsety ) using painter p. All four are given in the scroll views's coordinates. All of clipx, clipy, offsetx and offsety are typically large positive numbers.

Note that the final coordinates you give to QPainter methods must be within the range supported by the underlying window systems - about +/- 32000 at most, often much less - +/- 4000 or so is all you should really expect.

For example:

      {
        // Fill a 40000 by 50000 rectangle at (100000,150000)

        // Calculate the coordinates... (don't use QPoint, QRect, etc!)
        int x1 = 100000, y1 = 150000;
        int x2 = x1+40000-1, y2 = y1+50000-1;

        // Clip the coordinates so X/Windows will not have problems...
        if (x1 < clipx) x1=clipx;
        if (y1 < clipy) y1=clipy;
        if (x2 > clipx+clipw-1) x2=clipx+clipw-1;
        if (y2 > clipy+cliph-1) y2=clipy+cliph-1;

        // Translate to scrolled coordinates...
        x1 -= ox;
        x2 -= ox;
        y1 -= oy;
        y2 -= oy;

        // Paint using the new small coordinates...
        if ( x2 >= x1 && y2 >= y1 )
            p->fillRect(x1, y1, x2-x1+1, y2-y1+1, red);
      }

The clip rectangle of the painter p is already set appropriately.

Note that QPainter::translate() is not sufficient.

The default implementation does nothing.

Reimplemented in QListView.

### void QScrollView::ensureVisible ( int x, int y ) `[slot]`

Scrolls the content so that the point (x, y) is visible with at least 50-pixel margins (if possible, otherwise centered).

### void QScrollView::ensureVisible ( int x, int y, int xmargin, int ymargin ) `[slot]`

Scrolls the content so that the point (x, y) is visible with at least the given pixel margins (if possible, otherwise centered).

### bool QScrollView::eventFilter ( QObject * obj, QEvent * e ) `[virtual protected]`

This event filter ensures the scrollbars are updated when a single contents widget is resized, shown, hidden, or destroyed, and passes mouse events to the QScrollView.

Reimplemented from QObject.

### bool QScrollView::focusNextPrevChild ( bool next ) `[virtual protected]`

Override so that traversal moves among child widgets, even if they are not visible, scrolling to make them so.

Reimplemented from QWidget.

### void QScrollView::frameChanged () `[virtual protected]`

An override - ensures scrollbars are correct size when frame style changes.

Reimplemented from QFrame.

### QScrollView::ScrollBarMode QScrollView::hScrollBarMode() const

Returns the currently set mode for the horizontal scrollbar.

See also: setHScrollBarMode().

### QScrollBar* QScrollView::horizontalScrollBar ()

Returns the component horizontal scrollbar. It is made available to allow accelerators, autoscrolling, etc., and to allow changing of arrow scrollrates: bar->setSteps( rate, bar->pageStep() ).

It should not be otherwise manipulated.

### int QScrollView::leftMargin () const `[protected]`

Returns the current left margin.

See also: setMargins().

### void QScrollView::moveChild ( QWidget * child, int x, int y ) `[virtual]`

Repositions child to (x, y). This functions the same as addChild().

### void QScrollView::removeChild ( QWidget * child )

Removes a child from the scrolled area. Note that this happens automatically if the child is deleted.

### void QScrollView::resize ( const QSize & s )

An override - ensures scrollbars are correct size upon resize.

### void QScrollView::resize ( int w, int h )

An override - ensures scrollbars are correct size upon resize.

### void QScrollView::resizeContents ( int w, int h ) `[virtual slot]`

Set the size of the contents area to w pixels wide and h pixels high, and updates the viewport accordingly.

### void QScrollView::resizeEvent ( QResizeEvent * event ) `[virtual protected]`

An override - ensures scrollbars are correct size upon resize.

Reimplemented from QWidget.

### QScrollView::ResizePolicy QScrollView::resizePolicy() const

Returns the currently set ResizePolicy.

### int QScrollView::rightMargin () const `[protected]`

Returns the current right margin.

See also: setMargins().

### void QScrollView::scrollBy ( int dx, int dy ) `[slot]`

Scrolls the content by x to the left and y upwards.

### void QScrollView::setContentsPos ( int x, int y ) `[slot]`

Scrolls the content so that the point (x, y) is in the top-left corner.

### void QScrollView::setCornerWidget ( QWidget * corner ) `[virtual]`

Sets the widget in the corner between the two scrollbars.

You will probably also want to set at least one of the scrollbar modes to AlwaysOn.

Passing 0 shows no widget in the corner.

Any previous corner widget is hidden.

You may call setCornerWidget() with the same widget at different times.

All widgets set here will be deleted by the QScrollView when it destructs unless you seperately recreate the widget after setting some other corner widget (or 0).

Any newly set widget should have no current parent.

By default, no corner widget is present.

See also: setVScrollBarMode() and setHScrollBarMode().

### void QScrollView::setHScrollBarMode ( ScrollBarMode mode ) `[virtual]`

Sets the mode for the horizontal scrollbar.

- `Auto` (the default) shows a scrollbar when the content is too wide to fit.
- `AlwaysOff` never shows a scrollbar.
- `AlwaysOn` always shows a scrollbar.

See also: hScrollBarMode() and setVScrollBarMode().

### void QScrollView::setMargins ( int left, int top, int right, int bottom ) `[protected]`

Sets the margins around the scrolling area. This is useful for applications such as spreadsheets with `locked' rows and columns. The marginal space is inside the frameRect() and is left blank - override drawContents() or put widgets in the unused area.

By default all margins are zero.

See also: frameChanged().

### void QScrollView::setResizePolicy ( ResizePolicy r ) `[virtual]`

Sets the resize policy to r.

The policies are:

- `Default` is the initial value. It converts to `Manual` if the view is resized with resizeContents(), or to `AutoOne` if a child is added.
- `Manual` means the view stays the size set by resizeContents().
- `AutoOne` means that if there is only only child widget, the view stays the size of that widget.

### void QScrollView::setVScrollBarMode ( ScrollBarMode mode ) `[virtual]`

Sets the mode for the vertical scrollbar.

- `Auto` (the default) shows a scrollbar when the content is too tall to fit.
- `AlwaysOff` never shows a scrollbar.
- `AlwaysOn` always shows a scrollbar.

See also: vScrollBarMode() and setHScrollBarMode().

### void QScrollView::show () `[virtual]`

An override - ensures scrollbars are correct size upon showing.

Reimplemented from QWidget.

### void QScrollView::showChild ( QWidget * child, bool y=TRUE )

\obsolete

Sets the visibility of child. Equivalent to QWidget::show() or QWidget::hide().

### int QScrollView::topMargin () const `[protected]`

Returns the current top margin.

See also: setMargins().

### void QScrollView::updateScrollBars () `[slot]`

Updates scrollbars - all possibilities considered. You should never need to call this in your code.

### QScrollView::ScrollBarMode QScrollView::vScrollBarMode() const

Returns the currently set mode for the vertical scrollbar.

See also: setVScrollBarMode().

### QScrollBar* QScrollView::verticalScrollBar ()

Returns the component vertical scrollbar. It is made available to allow accelerators, autoscrolling, etc., and to allow changing of arrow scrollrates: bar->setSteps( rate, bar->pageStep() ).

It should not be otherwise manipulated.

### QWidget* QScrollView::viewport ()

Returns the viewport widget of the scrollview. This is the widget containing the contents widget or which is the drawing area.

### void QScrollView::viewportMouseDoubleClickEvent ( QMouseEvent * ) `[virtual protected]`

To provide simple processing of events on the contents, this method receives all mouse double click events sent to the viewport.

### void QScrollView::viewportMouseMoveEvent ( QMouseEvent * ) `[virtual protected]`

To provide simple processing of events on the contents, this method receives all mouse move events sent to the viewport.

### void QScrollView::viewportMousePressEvent ( QMouseEvent * ) `[virtual protected]`

To provide simple processing of events on the contents, this method receives all mouse press events sent to the viewport.

### void QScrollView::viewportMouseReleaseEvent ( QMouseEvent * ) `[virtual protected]`

To provide simple processing of events on the contents, this method receives all mouse release events sent to the viewport.

### void QScrollView::viewportPaintEvent ( QPaintEvent * pe ) `[virtual protected]`

This is a low-level painting routine that draws the viewport contents. Override this if drawContentsOffset() is too high-level. (for example, if you don't want to open a QPainter on the viewport).

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

This file is part of the Qt toolkit, copyright © 1995-99 Troll Tech, all rights reserved.

It was generated from the following files:

- qscrollview.h: 1998/10/01
- qscrollview.cpp: 1998/11/20