Contents

• Public Types
• Properties
• Public Functions
• Reimplemented Public Functions
• Public Slots
• Signals
• Protected Functions
• Reimplemented Protected Functions
• Detailed Description
• Using One Big Widget
• Using a Very Big View with Some Widgets
• Using a Very Big View with Many Widgets
• Details Relevant for All Views

Detailed Description

TheQ3ScrollView widget provides a scrolling area with on-demand scroll bars.

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

To provide content for the widget, inherit fromQ3ScrollView, reimplementdrawContents() and useresizeContents() to set the size of the viewed area. UseaddChild() andmoveChild() to position widgets on the view.

To useQ3ScrollView effectively it is important to understand its widget structure in the three styles of use: a single large child widget, a large panning area with some widgets and a large panning area with many widgets.

Using One Big Widget

The first, simplest usage ofQ3ScrollView (depicted above), is appropriate for scrolling areas that are never more than about 4000 pixels in either dimension (this is about the maximum reliable size on X11 servers). In this usage, you just make one large child in theQ3ScrollView. The child should be a child of theviewport() of the scrollview and be added withaddChild():

Q3ScrollView* sv=newQ3ScrollView(...);QWidget*widget=newQWidget(sv->viewport());QVBoxLayout*layout=newQVBoxLayout(widget);addChild(widget);

You can go on to add arbitrary child widgets to the single child in the scrollview as you would with any widget:

QLabel* child1=newQLabel("CHILD", widget);QLabel* child2=newQLabel("CHILD", widget);QLabel* child3=newQLabel("CHILD", widget);layout->addWidget(child1);layout->addWidget(child2);layout->addWidget(child3);...

Here theQ3ScrollView has four children: theviewport(), theverticalScrollBar(), thehorizontalScrollBar() and a smallcornerWidget(). Theviewport() has one child: theQWidget. TheQWidget has the threeQLabel objects as child widgets. When the view is scrolled, theQWidget is moved; its children move with it as child widgets normally do.

Using a Very Big View with Some Widgets

The second usage ofQ3ScrollView (depicted above) is appropriate when few, if any, widgets are on a very large scrolling area that is potentially larger than 4000 pixels in either dimension. In this usage you callresizeContents() to set the size of the area and reimplementdrawContents() to paint the contents. You may also add some widgets by making them children of theviewport() and adding them withaddChild() (this is the same as the process for the single large widget in the previous example):

Q3ScrollView* sv=newQ3ScrollView(...);QLabel* child1=newQLabel("CHILD", sv->viewport());sv->addChild(child1);QLabel* child2=newQLabel("CHILD", sv->viewport());sv->addChild(child2);QLabel* child3=newQLabel("CHILD", sv->viewport());sv->addChild(child3);

Here, theQ3ScrollView has the same four children: theviewport(), theverticalScrollBar(), thehorizontalScrollBar() and a smallcornerWidget(). Theviewport() has the threeQLabel objects as child widgets. When the view is scrolled, the scrollview moves the child widgets individually.

Using a Very Big View with Many Widgets

The final usage ofQ3ScrollView (depicted above) is appropriate when many widgets are on a very large scrolling area that is potentially larger than 4000 pixels in either dimension. In this usage you callresizeContents() to set the size of the area and reimplementdrawContents() to paint the contents. You then callenableClipper(true) and add widgets, again by making them children of theviewport(), and adding them withaddChild():

Q3ScrollView* sv=newQ3ScrollView(...);sv->enableClipper(true);QLabel* child1=newQLabel("CHILD", sv->viewport());sv->addChild(child1);QLabel* child2=newQLabel("CHILD", sv->viewport());sv->addChild(child2);QLabel* child3=newQLabel("CHILD", sv->viewport());sv->addChild(child3);

Here, theQ3ScrollView has four children: theclipper() (not theviewport() this time), theverticalScrollBar(), thehorizontalScrollBar() and a smallcornerWidget(). Theclipper() has one child: theviewport(). Theviewport() has the same three labels as child widgets. When the view is scrolled theviewport() is moved; its children move with it as child widgets normally do.

Details Relevant for All Views

Normally you will use the first or third method if you want any child widgets in the view.

Note that the widget you see in the scrolled area is theviewport() widget, not theQ3ScrollView itself. So to turn mouse tracking on, for example, useviewport()->setMouseTracking(true).

To enable drag-and-drop, you wouldsetAcceptDrops(true) on theQ3ScrollView (because drag-and-drop events propagate to the parent). But to work out the logical position in the view, you would need to map the drop co-ordinate from being relative to theQ3ScrollView to being relative to the contents; use the functionviewportToContents() for this.

To handle mouse events on the scrolling area, subclass scrollview as you would subclass other widgets, but rather than reimplementingmousePressEvent(), reimplementcontentsMousePressEvent() instead. The contents specific event handlers provide translated events in the coordinate system of the scrollview. If you reimplementmousePressEvent(), you'll get called only when part of theQ3ScrollView is clicked: and the only such part is the "corner" (if you don't set acornerWidget()) and the frame; everything else is covered up by the viewport, clipper or scroll bars.

When you construct aQ3ScrollView, some of the window flags apply to theviewport() instead of being sent to theQWidget constructor for theQ3ScrollView.

• An image-manipulation widget would useWNoAutoErase|WStaticContents because the widget draws all pixels itself, and when its size increases, it only needs a paint event for the new part because the old part remains unchanged.
• A scrolling game widget in which the background scrolls as the characters move might useWNoAutoErase (in addition toWStaticContents) so that the window system background does not flash in and out during scrolling.
• A word processing widget might useWNoAutoErase and repaint itself line by line to get a less-flickery resizing. If the widget is in a mode in which no text justification can take place, it might useWStaticContents too, so that it would only get a repaint for the newly visible parts.

Child widgets may be moved usingaddChild() ormoveChild(). UsechildX() andchildY() to get the position of a child widget.

A widget may be placed in the corner between the vertical and horizontal scroll bars withsetCornerWidget(). You can get access to the scroll bars usinghorizontalScrollBar() andverticalScrollBar(), and to the viewport withviewport(). The scroll view can be scrolled usingscrollBy(),ensureVisible(),setContentsPos() orcenter().

The visible area is given byvisibleWidth() andvisibleHeight(), and the contents area bycontentsWidth() andcontentsHeight(). The contents may be repainted using one of therepaintContents() orupdateContents() functions.

Coordinate conversion is provided bycontentsToViewport() andviewportToContents().

ThecontentsMoving() signal is emitted just before the contents are moved to a new position.

Warning:Q3ScrollView currently does not erase the background when resized, i.e. you must always clear the background manually in scrollview subclasses. This will change in a future version of Qt and we recommend specifying theWNoAutoErase flag explicitly.

Member Type Documentation

enum Q3ScrollView::ResizePolicy

This enum type is used to control aQ3ScrollView's reaction to resize events.

enum Q3ScrollView::ScrollBarMode

This enum type describes the various modes ofQ3ScrollView's scroll bars.

(The modes for the horizontal and vertical scroll bars are independent.)

Property Documentation

contentsHeight : constint

This property holds the height of the contents area.

Access functions:

contentsWidth : constint

This property holds the width of the contents area.

Access functions:

contentsX : constint

This property holds the X coordinate of the contents that are at the left edge of the viewport.

Access functions:

contentsY : constint

This property holds the Y coordinate of the contents that are at the top edge of the viewport.

Access functions:

dragAutoScroll :bool

This property holds whether autoscrolling in drag move events is enabled.

If this property is set to true (the default), theQ3ScrollView automatically scrolls the contents in drag move events if the user moves the cursor close to a border of the view. Of course this works only if the viewport accepts drops. Specifying false disables this autoscroll feature.

Access functions:

hScrollBarMode :ScrollBarMode

This property holds the mode for the horizontal scroll bar.

The default mode isQ3ScrollView::Auto.

Access functions:

See alsovScrollBarMode.

resizePolicy :ResizePolicy

This property holds the resize policy.

The default isDefault.

Access functions:

See alsoResizePolicy.

vScrollBarMode :ScrollBarMode

This property holds the mode for the vertical scroll bar.

The default mode isQ3ScrollView::Auto.

Access functions:

See alsohScrollBarMode.

visibleHeight : constint

This property holds the vertical amount of the content that is visible.

Access functions:

visibleWidth : constint

This property holds the horizontal amount of the content that is visible.

Access functions:

Member Function Documentation

Q3ScrollView::Q3ScrollView(QWidget * parent = 0, constchar * name = 0,Qt::WindowFlags f = 0)

Constructs aQ3ScrollView calledname with parentparent and widget flagsf.

The widget flagsWStaticContents,WNoAutoErase andWPaintClever are propagated to theviewport() widget. The other widget flags are propagated to the parent constructor as usual.

Q3ScrollView::~Q3ScrollView()

Destroys theQ3ScrollView. Any children added withaddChild() will be deleted.

[virtual]void Q3ScrollView::addChild(QWidget * child,int x = 0,int y = 0)

Inserts the widget,child, into the scrolled area positioned at (x,y). The position defaults to (0, 0). If the child is already in the view, it is just moved.

You may want to callenableClipper(true) if you add a large number of widgets.

int Q3ScrollView::bottomMargin() const

Returns the bottom margin.

See alsosetMargins().

[slot]void Q3ScrollView::center(int x,int y)

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

[slot]void Q3ScrollView::center(int x,int y,float xmargin,float ymargin)

This is an overloaded function.

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

For example:

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

int Q3ScrollView::childX(QWidget * child)

Returns the X position of the givenchild widget. Use this rather thanQWidget::x() for widgets added to the view.

This function returns 0 ifchild has not been added to the view.

int Q3ScrollView::childY(QWidget * child)

Returns the Y position of the givenchild widget. Use this rather thanQWidget::y() for widgets added to the view.

This function returns 0 ifchild has not been added to the view.

QWidget * Q3ScrollView::clipper() const

Returns the clipper widget. Contents in the scrollview are ultimately clipped to be inside the clipper widget.

You should not need to use this function.

See alsovisibleWidth() andvisibleHeight().

[virtual protected]void Q3ScrollView::contentsContextMenuEvent(QContextMenuEvent * e)

This event handler is called whenever theQ3ScrollView receives acontextMenuEvent() ine: the mouse position is translated to be a point on the contents.

[virtual protected]void Q3ScrollView::contentsDragEnterEvent(QDragEnterEvent * event)

This event handler is called whenever theQ3ScrollView receives adragEnterEvent(): the drag position is translated to be a point on the contents.

The default implementation does nothing. Theevent parameter is ignored.

[virtual protected]void Q3ScrollView::contentsDragLeaveEvent(QDragLeaveEvent * event)

This event handler is called whenever theQ3ScrollView receives adragLeaveEvent(): the drag position is translated to be a point on the contents.

The default implementation does nothing. Theevent parameter is ignored.

[virtual protected]void Q3ScrollView::contentsDragMoveEvent(QDragMoveEvent * event)

This event handler is called whenever theQ3ScrollView receives adragMoveEvent(): the drag position is translated to be a point on the contents.

The default implementation does nothing. Theevent parameter is ignored.

[virtual protected]void Q3ScrollView::contentsDropEvent(QDropEvent * event)

This event handler is called whenever theQ3ScrollView receives adropEvent(): the drop position is translated to be a point on the contents.

The default implementation does nothing. Theevent parameter is ignored.

[virtual protected]void Q3ScrollView::contentsMouseDoubleClickEvent(QMouseEvent * e)

This event handler is called whenever theQ3ScrollView receives amouseDoubleClickEvent(): the click position ine is translated to be a point on the contents.

The default implementation generates a normal mouse press event.

[virtual protected]void Q3ScrollView::contentsMouseMoveEvent(QMouseEvent * e)

This event handler is called whenever theQ3ScrollView receives amouseMoveEvent(): the mouse position ine is translated to be a point on the contents.

[virtual protected]void Q3ScrollView::contentsMousePressEvent(QMouseEvent * e)

This event handler is called whenever theQ3ScrollView receives amousePressEvent(): the press position ine is translated to be a point on the contents.

[virtual protected]void Q3ScrollView::contentsMouseReleaseEvent(QMouseEvent * e)

This event handler is called whenever theQ3ScrollView receives amouseReleaseEvent(): the release position ine is translated to be a point on the contents.

[signal]void Q3ScrollView::contentsMoving(int x,int y)

This signal is emitted just before the contents are moved to position (x,y).

See alsocontentsX() andcontentsY().

void Q3ScrollView::contentsToViewport(int x,int y,int & vx,int & vy) const

Translates a point (x,y) in the contents to a point (vx,vy) on theviewport() widget.

QPoint Q3ScrollView::contentsToViewport(constQPoint & p) const

This is an overloaded function.

Returns the pointp translated to a point on theviewport() widget.

[virtual protected]void Q3ScrollView::contentsWheelEvent(QWheelEvent * e)

This event handler is called whenever theQ3ScrollView receives awheelEvent() ine: the mouse position is translated to be a point on the contents.

[virtual protected]void Q3ScrollView::contextMenuEvent(QContextMenuEvent * e)

Reimplemented fromQWidget::contextMenuEvent().

QWidget * Q3ScrollView::cornerWidget() const

Returns the widget in the corner between the two scroll bars.

By default, no corner widget is present.

See alsosetCornerWidget().

[virtual protected]void Q3ScrollView::drawContents(QPainter * p,int clipx,int clipy,int clipw,int cliph)

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

The function should draw the rectangle (clipx,clipy,clipw,cliph) of the contents using painterp. The clip rectangle is in the scrollview's coordinates.

For example:

{// Fill a 40000 by 50000 rectangle at (100000,150000)// Calculate the coordinates...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;// Paint using the small coordinates...if (x2>= x1&& y2>= y1)        p->fillRect(x1, y1, x2-x1+1, y2-y1+1, red);}

The clip rectangle and translation of the painterp is already set appropriately.

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

For backward-compatibility only. It is easier to usedrawContents(QPainter*,int,int,int,int).

The default implementation translates the painter appropriately and callsdrawContents(QPainter*,int,int,int,int). SeedrawContents() for an explanation of the parametersp,offsetx,offsety,clipx,clipy,clipw andcliph.

void Q3ScrollView::enableClipper(bool y)

When a large numbers of child widgets are in a scrollview, especially if they are close together, the scrolling performance can suffer greatly. Ify is true the scrollview will use an extra widget to group child widgets.

Note that you may only call enableClipper() prior to adding widgets.

[slot]void Q3ScrollView::ensureVisible(int x,int y)

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

[slot]void Q3ScrollView::ensureVisible(int x,int y,int xmargin,int ymargin)

This is an overloaded function.

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

[virtual protected]bool Q3ScrollView::eventFilter(QObject * obj,QEvent * e)

Reimplemented fromQObject::eventFilter().

This event filter ensures the scroll bars are updated when a single contents widget is resized, shown, hidden or destroyed; it passes mouse events to theQ3ScrollView. The event is ine and the object is inobj.

[virtual protected]bool Q3ScrollView::focusNextPrevChild(bool next)

Reimplemented fromQWidget::focusNextPrevChild().

[virtual protected]void Q3ScrollView::frameChanged()

Reimplemented fromQ3Frame::frameChanged().

bool Q3ScrollView::hasStaticBackground() const

Returns true ifQ3ScrollView uses a static background; otherwise returns false.

See alsosetStaticBackground().

QScrollBar * Q3ScrollView::horizontalScrollBar() const

Returns the component horizontal scroll bar. It is made available to allow accelerators, autoscrolling, etc.

It should not be used for other purposes.

This function never returns 0.

[signal]void Q3ScrollView::horizontalSliderPressed()

This signal is emitted whenever the user presses the horizontal slider.

[signal]void Q3ScrollView::horizontalSliderReleased()

This signal is emitted whenever the user releases the horizontal slider.

bool Q3ScrollView::isHorizontalSliderPressed()

Returns true if horizontal slider is pressed by user; otherwise returns false.

bool Q3ScrollView::isVerticalSliderPressed()

Returns true if vertical slider is pressed by user; otherwise returns false.

int Q3ScrollView::leftMargin() const

Returns the left margin.

See alsosetMargins().

[virtual]QSize Q3ScrollView::minimumSizeHint() const

Reimplemented fromQWidget::minimumSizeHint().

[virtual protected]void Q3ScrollView::mouseDoubleClickEvent(QMouseEvent * e)

Reimplemented fromQWidget::mouseDoubleClickEvent().

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

Reimplemented fromQWidget::mouseMoveEvent().

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

Reimplemented fromQWidget::mousePressEvent().

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

Reimplemented fromQWidget::mouseReleaseEvent().

[virtual]void Q3ScrollView::moveChild(QWidget * child,int x,int y)

Repositions thechild widget to (x,y). This function is the same asaddChild().

void Q3ScrollView::removeChild(QWidget * child)

Removes thechild widget from the scrolled area. Note that this happens automatically if thechild is deleted.

void Q3ScrollView::repaintContents(int x,int y,int w,int h,bool erase = true)

Callsrepaint() on a rectangle defined byx,y,w,h, translated appropriately. If the rectangle is not visible, nothing is repainted. Iferase is true the background is cleared using the background color.

See alsoupdateContents().

void Q3ScrollView::repaintContents(constQRect & r,bool erase = true)

This is an overloaded function.

Repaints the contents of rectangler. Iferase is true the background is cleared using the background color.

void Q3ScrollView::repaintContents(bool erase = true)

This is an overloaded function.

Repaints the contents. Iferase is true the background is cleared using the background color.

[virtual slot]void Q3ScrollView::resizeContents(int w,int h)

Sets the size of the contents area tow pixels wide andh pixels high and updates the viewport accordingly.

[virtual protected]void Q3ScrollView::resizeEvent(QResizeEvent * event)

Reimplemented fromQWidget::resizeEvent().

int Q3ScrollView::rightMargin() const

Returns the right margin.

See alsosetMargins().

[slot]void Q3ScrollView::scrollBy(int dx,int dy)

Scrolls the content bydx to the left anddy upwards.

[virtual slot]void Q3ScrollView::setContentsPos(int x,int y)

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

[virtual]void Q3ScrollView::setCornerWidget(QWidget * corner)

Sets the widget in thecorner between the two scroll bars.

You will probably also want to set at least one of the scroll bar modes toAlwaysOn.

Passing 0 shows no widget in the corner.

Any previouscorner widget is hidden.

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

All widgets set here will be deleted by theQ3ScrollView when it is destroyed unless you separately reparent the widget after setting some other corner widget (or 0).

Anynewly set widget should have no current parent.

By default, no corner widget is present.

See alsocornerWidget(),setVScrollBarMode(), andsetHScrollBarMode().

[virtual protected]void Q3ScrollView::setHBarGeometry(QScrollBar & hbar,int x,int y,int w,int h)

Called when the horizontal scroll bar geometry changes. This is provided as a protected function so that subclasses can do interesting things such as providing extra buttons in some of the space normally used by the scroll bars.

The default implementation simply gives all the space tohbar. The new geometry is given byx,y,w andh.

See alsosetVBarGeometry().

[virtual]void Q3ScrollView::setMargins(int left,int top,int right,int bottom)

Sets the margins around the scrolling area toleft,top,right andbottom. This is useful for applications such as spreadsheets with "locked" rows and columns. The marginal space isinside theframeRect() and is left blank; reimplementdrawFrame() or put widgets in the unused area.

By default all margins are zero.

See alsoframeChanged().

void Q3ScrollView::setStaticBackground(bool y)

Sets the scrollview to have a static background ify is true, or a scrolling background ify is false. By default, the background is scrolling.

Be aware that this mode is quite slow, as a full repaint of the visible area has to be triggered on every contents move.

See alsohasStaticBackground().

[virtual protected]void Q3ScrollView::setVBarGeometry(QScrollBar & vbar,int x,int y,int w,int h)

Called when the vertical scroll bar geometry changes. This is provided as a protected function so that subclasses can do interesting things such as providing extra buttons in some of the space normally used by the scroll bars.

The default implementation simply gives all the space tovbar. The new geometry is given byx,y,w andh.

See alsosetHBarGeometry().

[virtual]void Q3ScrollView::setVisible(bool visible)

Reimplemented fromQWidget::setVisible().

[virtual]QSize Q3ScrollView::sizeHint() const

Reimplemented fromQWidget::sizeHint().

int Q3ScrollView::topMargin() const

Returns the top margin.

See alsosetMargins().

void Q3ScrollView::updateContents(int x,int y,int w,int h)

Callsupdate() on a rectangle defined byx,y,w,h, translated appropriately. If the rectangle is not visible, nothing is repainted.

See alsorepaintContents().

void Q3ScrollView::updateContents(constQRect & r)

This is an overloaded function.

Updates the contents in rectangler

void Q3ScrollView::updateContents()

This is an overloaded function.

[slot]void Q3ScrollView::updateScrollBars()

Updates scroll bars: all possibilities are considered. You should never need to call this in your code.

QScrollBar * Q3ScrollView::verticalScrollBar() const

Returns the component vertical scroll bar. It is made available to allow accelerators, autoscrolling, etc.

It should not be used for other purposes.

This function never returns 0.

[signal]void Q3ScrollView::verticalSliderPressed()

This signal is emitted whenever the user presses the vertical slider.

[signal]void Q3ScrollView::verticalSliderReleased()

This signal is emitted whenever the user releases the vertical slider.

QWidget * Q3ScrollView::viewport() const

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

[virtual protected]void Q3ScrollView::viewportPaintEvent(QPaintEvent * pe)

This is a low-level painting routine that draws the viewport contents. Reimplement this ifdrawContents() is too high-level (for example, if you don't want to open aQPainter on the viewport). The paint event is passed inpe.

[virtual protected]void Q3ScrollView::viewportResizeEvent(QResizeEvent * event)

To provide simple processing of events on the contents, this function receives all resize events sent to the viewport.

The default implementation does nothing. Theevent parameter is ignored.

See alsoQWidget::resizeEvent().

QSize Q3ScrollView::viewportSize(int x,int y) const

Returns the viewport size for size (x,y).

The viewport size depends on (x,y) (the size of the contents), the size of this widget and the modes of the horizontal and vertical scroll bars.

This function permits widgets that can trade vertical and horizontal space for each other to control scroll bar appearance better. For example, a word processor or web browser can control the width of the right margin accurately, whether or not there needs to be a vertical scroll bar.

void Q3ScrollView::viewportToContents(int vx,int vy,int & x,int & y) const

Translates a point (vx,vy) on theviewport() widget to a point (x,y) in the contents.

QPoint Q3ScrollView::viewportToContents(constQPoint & vp) const

This is an overloaded function.

Returns the point on the viewportvp translated to a point in the contents.

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

Reimplemented fromQWidget::wheelEvent().