qscrollview.3qt

tmark1.11:用于生成QT/EMBEDDED应用工程的Markfile文件

.ti -1c
.BI "virtual void \fBsetHBarGeometry\fR ( QScrollBar & " "hbar" ", int " "x" ", int " "y" ", int " "w" ", int h )"
.br
.ti -1c
.BI "virtual void \fBsetVBarGeometry\fR ( QScrollBar & " "vbar" ", int " "x" ", int " "y" ", int " "w" ", int h )"
.br
.in -1c
.SH DESCRIPTION
The QScrollView widget provides a scrolling area with on-demand scrollbars.
.PP
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).
.PP
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() to position widgets on the view. For large numbers of such child widgets, consider using packChildWidgets() to improve performance.
.PP
To use QScrollView effectively, it is important to understand its widget structure in the three styles of usage: a single large child widget, a large panning area with some widgets, a large panning area with many widgets.
.IP "\fBOne Big Widget\fR" 1c
.PP
<img src=qscrollview-vp2.png>
.PP
The first, simplest usage of QScrollView depicated above is appropriate for scrolling areas which are \fInever\fR 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 the QScrollView. The child should be a child of the viewport() of the scrollview, and be added with addChild():
.PP
.nf
.br
    QScrollView* sv = new QScrollView(...);
.br
    QVBox* big_box = new QVBox(sv->viewport());
.br
    sv->addChild(big_box);
.fi
.PP
You may go on to add arbitrary child widgets to the single child in the scrollview, as you would with any widget:
.PP
.nf
.br
    QLabel* child1 = new QLabel("CHILD", big_box);
.br
    QLabel* child2 = new QLabel("CHILD", big_box);
.br
    QLabel* child3 = new QLabel("CHILD", big_box);
.br
    ...
.fi
.PP
Here, the QScrollView has 4 children - the viewport(), the verticalScrollBar(), the horizontalScrollBar(), and a small cornerWidget(). The viewport() has 1 child, the big QVBox. The QVBox has the three labels as child widgets. When the view is scrolled, the QVBox is moved, and its children move with it as child widgets normally do.
.IP "\fBVery Big View, some Widgets\fR" 1c
.PP
<img src=qscrollview-vp.png>
.PP
The second usage of QScrollView depicated 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 call resizeContents() to set the size of the area, and override drawContents() to paint the contents. You may also add some widgets, by making them children of the viewport() and adding them with addChild() (this is the same as the process for the single large widget in the previous example):
.PP
.nf
.br
    QScrollView* sv = new QScrollView(...);
.br
    QLabel* child1 = new QLabel("CHILD", sv->viewport());
.br
    sv->addChild(child1);
.br
    QLabel* child2 = new QLabel("CHILD", sv->viewport());
.br
    sv->addChild(child2);
.br
    QLabel* child3 = new QLabel("CHILD", sv->viewport());
.br
    sv->addChild(child3);
.fi
.PP
Here, the QScrollView has the same 4 children - the viewport(), the verticalScrollBar(), the horizontalScrollBar(), and a small cornerWidget(). The viewport() has the three labels as child widgets. When the view is scrolled, the scrollview moves the child widgets individually.
.IP "\fBVery Big View, many Widgets\fR" 1c
.PP
<img src=qscrollview-cl.png>
.PP
The final usage of QScrollView depicated 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 call resizeContents() to set the size of the area, and override drawContents() to paint the contents. You then call enableClipper(TRUE) and add widgets, again by making them children of the viewport() and adding them with addChild():
.PP
.nf
.br
    QScrollView* sv = new QScrollView(...);
.br
    sv->enableClipper(TRUE);
.br
    QLabel* child1 = new QLabel("CHILD", sv->viewport());
.br
    sv->addChild(child1);
.br
    QLabel* child2 = new QLabel("CHILD", sv->viewport());
.br
    sv->addChild(child2);
.br
    QLabel* child3 = new QLabel("CHILD", sv->viewport());
.br
    sv->addChild(child3);
.fi
.PP
Here, the QScrollView has 4 children - the clipper() (\fInot\fR the viewport() this time), the verticalScrollBar(), the horizontalScrollBar(), and a small cornerWidget(). The clipper() has 1 child - the viewport(). The viewport() has the three labels as child widgets. When the view is scrolled, the viewport() is moved, and its children move with it as child widgets normally do.
.PP
Normally you will use the first or third method if you want any child widgets in the view.
.PP
Note that the widget you see in the scrolled area is the viewport() widget, not the QScrollView itself. So, to turn mouse tracking on for example, use viewport()->setMouseTracking(TRUE).
.PP
To enable drag-and-drop, you would setAcceptDrops(TRUE) on the QScrollView (since drag-and-drop events propagate to the parent), but to work out what logical position in the view, you would need to map the drop co-ordinate from being relative to the QScrollView to being relative to the contents - use the function mapToContents() for this.
.PP
To handle mouse events on the scrolling area, subclass scrollview as you would subclass other widgets, but rather than overriding mousePressEvent(), override viewportMousePressEvent() instead (if you override mousePressEvent() you'll only get called when part of the QScrollView is clicked - and the only such part is the "corner" (if you don't set a cornerWidget()) and the frame, everything else being covered up by the viewport, clipper, or scrollbars.
.PP
<img src=qscrollview-m.png> <img src=qscrollview-w.png>
.PP
Examples:
.(l
scrollview/scrollview.cpp
.)l
.SS "Member Type Documentation"
.SH "QScrollView::ResizePolicy"
This enum type is used to control QScrollView's reaction to resize events. There are three possible settings:
.IP
.TP
\fCDefault\fR - QScrollView selects one of the other settings automatically when it has to. At the time of writing, QScrollView changs to \fCManual\fR if you resize the contents with <a href="qscrollview.html#e4cb2e">resizeContents(), and to \fCAutoOne\fR if a child is added.
.IP
.TP
\fCManual\fR - the view stays the size set by resizeContents().
.IP
.TP
\fCAutoOne\fR - if there is only only child widget, the view stays the size of that widget. Otherwise, the behaviour is undefined.
.IP
.SH MEMBER FUNCTION DOCUMENTATION
.SH "QScrollView::QScrollView ( QWidget * parent=0, const char * name=0, WFlags f=0 )"
Constructs a QScrollView.
.PP
If you intend to add child widgets, you may see improved refresh if you include \fCWPaintClever\fR in the widgets flags, \fIf.\fR \fCWPaintClever\fR as well as \fCWNorthWestGravity\fR is propagated to the viewport() widget.
.SH "QScrollView::~QScrollView ()"
Destructs the QScrollView. Any children added with addChild() will be destructed.
.SH "void QScrollView::addChild ( QWidget * child, int x=0, int y=0 ) \fC[virtual]\fR"
Inserts \fIchild\fR into the scrolled area positioned at (\fIx, y).\fR The position defaults to (0,0). If the child is already in the view, it is just moved.
.PP
You may want to call packChildWidgets() after a large number of such additions is complete.
.PP
Examples:
.(l
scrollview/scrollview.cpp
.)l
.SH "int QScrollView::bottomMargin () const \fC[protected]\fR"
Returns the current bottom margin.
.PP
See also: setMargins().
.SH "void QScrollView::center ( int x, int y ) \fC[slot]\fR"
Scrolls the content so that the point (x,y) is in the center of visible area.
.SH "void QScrollView::center ( int x, int y, float xmargin, float ymargin ) \fC[slot]\fR"
Scrolls the content so that the point (x,y) is visible, with the given margins (as fractions of visible area).
.PP
eg.
.TP
Margin 0.0 allows (x,y) to be on edge of visible area.
.TP
Margin 0.5 ensures (x,y) is in middle 50% of visible area.
.TP
Margin 1.0 ensures (x,y) is in the center of the visible area.
.SH "bool QScrollView::childIsVisible ( QWidget * child )"
\fBThis function is obsolete.\fR It is provided to keep old programs working. We strongly advise against using it in new code.
.PP
Returns TRUE if \fIchild\fR is visible. This is equivalent to child->isVisible().
.SH "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.
.SH "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.
.SH "QWidget* QScrollView::clipper () const"
Returns the clipper widget. Contents in the scrollview is ultimately clipped to be inside the clipper widget.
.PP
You should not need to access this.
.PP
See also: visibleWidth() and visibleHeight().
.SH "void QScrollView::contentsDragEnterEvent ( QDragEnterEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a dragEnterEvent() - the drag position is translated to be a point on the contents.
.SH "void QScrollView::contentsDragLeaveEvent ( QDragLeaveEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a dragLeaveEvent() - the drag position is translated to be a point on the contents.
.SH "void QScrollView::contentsDragMoveEvent ( QDragMoveEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a dragMoveEvent() - the drag position is translated to be a point on the contents.
.SH "void QScrollView::contentsDropEvent ( QDropEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a dropEvent() - the drop position is translated to be a point on the contents.
.SH "int QScrollView::contentsHeight () const"
Returns the height of the contents area.
.SH "void QScrollView::contentsMouseDoubleClickEvent ( QMouseEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a mouseDoubleClickEvent() - the click position is translated to be a point on the contents.
.PP
Reimplemented in QListView.
.SH "void QScrollView::contentsMouseMoveEvent ( QMouseEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a mouseMoveEvent() - the mouse position is translated to be a point on the contents.
.PP
Reimplemented in QListView.
.SH "void QScrollView::contentsMousePressEvent ( QMouseEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a mousePressEvent() - the press position is translated to be a point on the contents.
.PP
Reimplemented in QListView.
.SH "void QScrollView::contentsMouseReleaseEvent ( QMouseEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a mouseReleaseEvent() - the release position is translated to be a point on the contents.
.PP
Reimplemented in QListView.
.SH "void QScrollView::contentsMoving ( int x, int y ) \fC[signal]\fR"
This signal is emitted just before the contents is moved to the given position.
.PP
See also: contentsX() and contentsY().
.SH "QPoint QScrollView::contentsToViewport ( const QPoint & p )"
Returns the point \fIp\fR translated to a point on the viewport() widget.
.SH "void QScrollView::contentsToViewport ( int x, int y, int & vx, int & vy )"
Translates a point (\fIx, y)\fR in the contents to a point (\fIvx, vy)\fR on the viewport() widget.
.SH "void QScrollView::contentsWheelEvent ( QWheelEvent * ) \fC[virtual protected]\fR"
This event handler is called whenever the QScrollView receives a wheelEvent() - the mouse position is translated to be a point on the contents.
.SH "int QScrollView::contentsWidth () const"
Returns the width of the contents area.
.SH "int QScrollView::contentsX () const"
Returns the X coordinate of the contents which is at the left edge of the viewport.
.SH "int QScrollView::contentsY () const"
Returns the Y coordinate of the contents which is at the top edge of the viewport.
.SH "QWidget* QScrollView::cornerWidget () const"
Returns the widget in the corner between the two scrollbars.
.PP
By default, no corner widget is present.
.PP
Examples:
.(l
scrollview/scrollview.cpp
.)l
.SH "void QScrollView::drawContents ( QPainter * p, int clipx, int clipy, int clipw, int cliph ) \fC[virtual protected]\fR"
Reimplement this method if you are viewing a drawing area rather than a widget.
.PP
The function should draw the rectangle (\fIclipx, clipy, clipw, cliph\fR ) of the contents, using painter \fIp.\fR The clip rectangle is in the scroll views's coordinates.
.PP
For example:
.PP
.nf
.br
  {
.br
    // Fill a 40000 by 50000 rectangle at (100000,150000)
.br
.br
    // Calculate the coordinates... (don't use QPoint, QRect, etc!)
.br
    int x1 = 100000, y1 = 150000;
.br
    int x2 = x1+40000-1, y2 = y1+50000-1;
.br
.br
    // Clip the coordinates so X/Windows will not have problems...
.br
    if (x1 < clipx) x1=clipx;
.br
    if (y1 < clipy) y1=clipy;
.br
    if (x2 > clipx+clipw-1) x2=clipx+clipw-1;
.br
    if (y2 > clipy+cliph-1) y2=clipy+cliph-1;
.br
.br
    // Paint using the small coordinates...
.br
    if ( x2 >= x1 && y2 >= y1 )
.br
        p->fillRect(x1, y1, x2-x1+1, y2-y1+1, red);
.br
  }
.fi
.PP
The clip rectangle and translation of the painter \fIp\fR is already set appropriately.
.SH "void QScrollView::drawContentsOffset ( QPainter * p, int offsetx, int offsety, int clipx, int clipy, int clipw, int cliph ) \fC[virtual protected]\fR"
For backward compatibility only. It is easier to use drawContents(QPainter*,int,int,int,int).
.PP
The default implementation translates the painter appropriately and calls drawContents(QPainter*,int,int,int,int).
.PP
Reimplemented in QListView and QTextView.
.SH "void QScrollView::enableClipper ( bool y )"
When large numbers of child widgets are in a scrollview, especially if they are close together, the scrolling performance can suffer greatly. If you call enableClipper(TRUE), the scrollview will use an extra widget to group child widgets.
.PP
Note that you may only call enableClipper() prior to adding widgets.
.PP
For a full discussion, see the overview documentation of this class.
.PP
Examples:
.(l
scrollview/scrollview.cpp
.)l
.SH "void QScrollView::ensureVisible ( int x, int y ) \fC[slot]\fR"
Scrolls the content so that the point (x, y) is visible with at least 50-pixel margins (if possible, otherwise centered).
.SH "void QScrollView::ensureVisible ( int x, int y, int xmargin, int ymargin ) \fC[slot]\fR"