|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Objectcom.trolltech.qt.QSignalEmitter
com.trolltech.qt.QtJambiObject
com.trolltech.qt.core.QObject
com.trolltech.qt.gui.QWidget
com.trolltech.qt.gui.QFrame
com.trolltech.qt.gui.QAbstractScrollArea
public class QAbstractScrollArea
The QAbstractScrollArea
widget provides a scrolling area with on-demand scroll bars. QAbstractScrollArea
is a low-level abstraction of a scrolling area. The area provides a central widget called the viewport, in which the contents of the area is to be scrolled (i.e, the visible parts of the contents are rendered in the viewport).
Next to the viewport is a vertical scroll bar, and below is a horizontal scroll bar. When all of the area contents fits in the viewport, each scroll bar can be either visible or hidden depending on the scroll bar's Qt::ScrollBarPolicy
. When a scroll bar is hidden, the viewport expands in order to cover all available space. When a scroll bar becomes visible again, the viewport shrinks in order to make room for the scroll bar.
It is possible to reserve a margin area around the viewport, see setViewportMargins()
. The feature is mostly used to place a QHeaderView
widget above or beside the scrolling area. Subclasses of QAbstractScrollArea
should implement margins.
When inheriting QAbstractScrollArea
, you need to do the following:
viewportEvent()
- notably resize events.update()
as all painting operations take place on the viewport.Qt::ScrollBarAsNeeded
(the default), QAbstractScrollArea
shows scroll bars when they provide a non-zero scrolling range, and hides them otherwise. The scroll bars and viewport should be updated whenever the viewport receives a resize event or the size of the contents changes. The viewport also needs to be updated when the scroll bars values change. The initial values of the scroll bars are often set when the area receives new contents.
We give a simple example, in which we have implemented a scroll area that can scroll any QWidget
. We make the widget a child of the viewport; this way, we do not have to calculate which part of the widget to draw but can simply move the widget with QWidget::move()
. When the area contents or the viewport size changes, we do the following:
QSize areaSize = viewport().size(); QSize widgetSize = widget.size(); verticalScrollBar().setPageStep(widgetSize.height()); horizontalScrollBar().setPageStep(widgetSize.width()); verticalScrollBar().setRange(0, widgetSize.height() - areaSize.height()); horizontalScrollBar().setRange(0, widgetSize.width() - areaSize.width()); updateWidgetPosition();When the scroll bars change value, we need to update the widget position, i.e., find the part of the widget that is to be drawn in the viewport:
int hvalue = horizontalScrollBar().value(); int vvalue = verticalScrollBar().value(); QPoint topLeft = viewport().rect().topLeft(); widget.move(topLeft.x() - hvalue, topLeft.y() - vvalue);In order to track scroll bar movements, reimplement the virtual function
scrollContentsBy()
. In order to fine-tune scrolling behavior, connect to a scroll bar's QAbstractSlider::actionTriggered()
signal and adjust the QAbstractSlider::sliderPosition
as you wish. For convenience, QAbstractScrollArea
makes all viewport events available in the virtual viewportEvent()
handler. QWidget
's specialized handlers are remapped to viewport events in the cases where this makes sense. The remapped specialized handlers are: paintEvent()
, mousePressEvent()
, mouseReleaseEvent()
, mouseDoubleClickEvent()
, mouseMoveEvent()
, wheelEvent()
, dragEnterEvent()
, dragMoveEvent()
, dragLeaveEvent()
, dropEvent()
, contextMenuEvent()
, and resizeEvent()
.
QScrollArea
, which inherits QAbstractScrollArea
, provides smooth scrolling for any QWidget
(i.e., the widget is scrolled pixel by pixel). You only need to subclass QAbstractScrollArea
if you need more specialized behavior. This is, for instance, true if the entire contents of the area is not suitable for being drawn on a QWidget
or if you do not want smooth scrolling.
QScrollArea
.
Nested Class Summary |
---|
Nested classes/interfaces inherited from class com.trolltech.qt.gui.QFrame |
---|
QFrame.Shadow, QFrame.Shape, QFrame.StyleMask |
Nested classes/interfaces inherited from class com.trolltech.qt.gui.QWidget |
---|
QWidget.RenderFlag, QWidget.RenderFlags |
Nested classes/interfaces inherited from class com.trolltech.qt.QSignalEmitter |
---|
QSignalEmitter.Signal0, QSignalEmitter.Signal1, QSignalEmitter.Signal2, QSignalEmitter.Signal3, QSignalEmitter.Signal4, QSignalEmitter.Signal5, QSignalEmitter.Signal6, QSignalEmitter.Signal7, QSignalEmitter.Signal8, QSignalEmitter.Signal9 |
Field Summary |
---|
Fields inherited from class com.trolltech.qt.gui.QWidget |
---|
customContextMenuRequested |
Constructor Summary | |
---|---|
QAbstractScrollArea()
Constructs a viewport. |
|
QAbstractScrollArea(QWidget parent)
Constructs a viewport. |
Method Summary | |
---|---|
void |
addScrollBarWidget(QWidget widget,
Qt.Alignment alignment)
Adds widget as a scroll bar widget in the location specified by alignment. |
void |
addScrollBarWidget(QWidget widget,
Qt.AlignmentFlag[] alignment)
Adds widget as a scroll bar widget in the location specified by alignment. |
QWidget |
cornerWidget()
Returns the widget in the corner between the two scroll bars. |
static QAbstractScrollArea |
fromNativePointer(QNativePointer nativePointer)
|
QScrollBar |
horizontalScrollBar()
Returns the horizontal scroll bar. |
Qt.ScrollBarPolicy |
horizontalScrollBarPolicy()
This property holds the policy for the horizontal scroll bar. |
QSize |
maximumViewportSize()
Returns the size of the viewport as if the scroll bars had no valid scrolling range. |
java.util.List |
scrollBarWidgets(Qt.Alignment alignment)
Returns a list of the currently set scroll bar widgets. |
java.util.List |
scrollBarWidgets(Qt.AlignmentFlag[] alignment)
Returns a list of the currently set scroll bar widgets. |
protected void |
scrollContentsBy(int dx,
int dy)
This virtual handler is called when the scroll bars are moved by dx, dy, and consequently the viewport's contents should be scrolled accordingly. |
void |
setCornerWidget(QWidget widget)
Sets the widget in the corner between the two scroll bars to be widget. |
void |
setHorizontalScrollBar(QScrollBar scrollbar)
Replaces the existing horizontal scroll bar with scrollBar, and sets all the former scroll bar's slider properties on the new scroll bar. |
void |
setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy arg__1)
This property holds the policy for the horizontal scroll bar. |
protected void |
setupViewport(QWidget viewport)
This slot is called by QAbstractScrollArea after setViewport (viewport) has been called. |
void |
setVerticalScrollBar(QScrollBar scrollbar)
Replaces the existing vertical scroll bar with scrollBar, and sets all the former scroll bar's slider properties on the new scroll bar. |
void |
setVerticalScrollBarPolicy(Qt.ScrollBarPolicy arg__1)
This property holds the policy for the vertical scroll bar. |
void |
setViewport(QWidget widget)
Sets the viewport to be the given widget. |
protected void |
setViewportMargins(int left,
int top,
int right,
int bottom)
Sets the margins around the scrolling area to left, top, right and bottom. |
QScrollBar |
verticalScrollBar()
Returns the vertical scroll bar. |
Qt.ScrollBarPolicy |
verticalScrollBarPolicy()
This property holds the policy for the vertical scroll bar. |
QWidget |
viewport()
Returns the viewport widget. |
protected boolean |
viewportEvent(QEvent arg__1)
The main event handler for the scrolling area (the viewport() widget). |
Methods inherited from class com.trolltech.qt.gui.QFrame |
---|
frameRect, frameShadow, frameShape, frameStyle, frameWidth, lineWidth, midLineWidth, setFrameRect, setFrameShadow, setFrameShape, setFrameStyle, setLineWidth, setMidLineWidth |
Methods inherited from class com.trolltech.qt.core.QObject |
---|
childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, event, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, indexOfProperty, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, properties, property, removeEventFilter, setObjectName, setParent, setProperty, startTimer, timerEvent, toString, userProperty |
Methods inherited from class com.trolltech.qt.QtJambiObject |
---|
dispose, disposed, equals, finalize, reassignNativeResources, tr, tr, tr |
Methods inherited from class com.trolltech.qt.QSignalEmitter |
---|
blockSignals, disconnect, disconnect, signalsBlocked, signalSender, thread |
Methods inherited from class java.lang.Object |
---|
clone, getClass, hashCode, notify, notifyAll, wait, wait, wait |
Methods inherited from interface com.trolltech.qt.QtJambiInterface |
---|
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership |
Constructor Detail |
---|
public QAbstractScrollArea()
The parent arguments is sent to the QWidget
constructor.
public QAbstractScrollArea(QWidget parent)
The parent arguments is sent to the QWidget
constructor.
Method Detail |
---|
public final void addScrollBarWidget(QWidget widget, Qt.AlignmentFlag[] alignment)
Scroll bar widgets are shown next to the horizontal or vertical scroll bar, and can be placed on either side of it. If you want the scroll bar widgets to be always visible, set the scrollBarPolicy
for the corresponding scroll bar to AlwaysOn.
alignment must be one of Qt::Alignleft
and Qt::AlignRight
, which maps to the horizontal scroll bar, or Qt::AlignTop
and Qt::AlignBottom
, which maps to the vertical scroll bar.
A scroll bar widget can be removed by either re-parenting the widget or deleting it. It's also possible to hide a widget with QWidget::hide()
The scroll bar widget will be resized to fit the scroll bar geometry for the current style. The following describes the case for scroll bar widgets on the horizontal scroll bar:
The height of the widget will be set to match the height of the scroll bar. To control the width of the widget, use QWidget::setMinimumWidth
and QWidget::setMaximumWidth
, or implement QWidget::sizeHint()
and set a horizontal size policy. If you want a square widget, call QStyle::pixelMetric
(QStyle::PM_ScrollBarExtent
) and set the width to this value.
scrollBarWidgets()
.
public final void addScrollBarWidget(QWidget widget, Qt.Alignment alignment)
Scroll bar widgets are shown next to the horizontal or vertical scroll bar, and can be placed on either side of it. If you want the scroll bar widgets to be always visible, set the scrollBarPolicy
for the corresponding scroll bar to AlwaysOn.
alignment must be one of Qt::Alignleft
and Qt::AlignRight
, which maps to the horizontal scroll bar, or Qt::AlignTop
and Qt::AlignBottom
, which maps to the vertical scroll bar.
A scroll bar widget can be removed by either re-parenting the widget or deleting it. It's also possible to hide a widget with QWidget::hide()
The scroll bar widget will be resized to fit the scroll bar geometry for the current style. The following describes the case for scroll bar widgets on the horizontal scroll bar:
The height of the widget will be set to match the height of the scroll bar. To control the width of the widget, use QWidget::setMinimumWidth
and QWidget::setMaximumWidth
, or implement QWidget::sizeHint()
and set a horizontal size policy. If you want a square widget, call QStyle::pixelMetric
(QStyle::PM_ScrollBarExtent
) and set the width to this value.
scrollBarWidgets()
.
public final QWidget cornerWidget()
By default, no corner widget is present.
setCornerWidget()
.
public final QScrollBar horizontalScrollBar()
setHorizontalScrollBar()
, horizontalScrollBarPolicy
, and verticalScrollBar()
.
public final Qt.ScrollBarPolicy horizontalScrollBarPolicy()
Qt::ScrollBarAsNeeded
. verticalScrollBarPolicy
.
public final QSize maximumViewportSize()
public final java.util.List scrollBarWidgets(Qt.AlignmentFlag[] alignment)
addScrollBarWidget()
.
public final java.util.List scrollBarWidgets(Qt.Alignment alignment)
addScrollBarWidget()
.
public final void setCornerWidget(QWidget widget)
You will probably also want to set at least one of the scroll bar 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 scroll area when it is destroyed unless you separately reparent 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.
cornerWidget()
, horizontalScrollBarPolicy
, and horizontalScrollBarPolicy
.
public final void setHorizontalScrollBar(QScrollBar scrollbar)
QAbstractScrollArea
already provides horizontal and vertical scroll bars by default. You can call this function to replace the default horizontal scroll bar with your own custom scroll bar.
horizontalScrollBar()
, and setVerticalScrollBar()
.
public final void setHorizontalScrollBarPolicy(Qt.ScrollBarPolicy arg__1)
Qt::ScrollBarAsNeeded
. verticalScrollBarPolicy
.
public final void setVerticalScrollBar(QScrollBar scrollbar)
QAbstractScrollArea
already provides vertical and horizontal scroll bars by default. You can call this function to replace the default vertical scroll bar with your own custom scroll bar.
verticalScrollBar()
, and setHorizontalScrollBar()
.
public final void setVerticalScrollBarPolicy(Qt.ScrollBarPolicy arg__1)
Qt::ScrollBarAsNeeded
. horizontalScrollBarPolicy
.
public final void setViewport(QWidget widget)
QAbstractScrollArea
will take ownership of the given widget. If widget is 0, QAbstractScrollArea
will assign a new QWidget
instance for the viewport.
viewport()
.
protected final void setViewportMargins(int left, int top, int right, int bottom)
Note that this function is frequently called by QTreeView
and QTableView
, so margins must be implemented by QAbstractScrollArea
subclasses. Also, if the subclasses are to be used in item views, they should not call this function.
By default all margins are zero.
protected void setupViewport(QWidget viewport)
QAbstractScrollArea
after setViewport
(viewport) has been called. Reimplement this function in a subclass of QAbstractScrollArea
to initialize the new viewport before it is used. setViewport()
.
public final QScrollBar verticalScrollBar()
setVerticalScrollBar()
, verticalScrollBarPolicy
, and horizontalScrollBar()
.
public final Qt.ScrollBarPolicy verticalScrollBarPolicy()
Qt::ScrollBarAsNeeded
. horizontalScrollBarPolicy
.
public final QWidget viewport()
Use the QScrollArea::widget()
function to retrieve the contents of the viewport widget.
setViewport()
, and QScrollArea::widget()
.
protected void scrollContentsBy(int dx, int dy)
The default implementation simply calls update()
on the entire viewport()
, subclasses can reimplement this handler for optimization purposes, or - like QScrollArea
- to move a contents widget. The parameters dx and dy are there for convenience, so that the class knows how much should be scrolled (useful e.g. when doing pixel-shifts). You may just as well ignore these values and scroll directly to the position the scroll bars indicate.
Calling this function in order to scroll programmatically is an error, use the scroll bars instead (e.g. by calling QScrollBar::setValue() directly).
protected boolean viewportEvent(QEvent arg__1)
viewport()
widget). It handles the event specified, and can be called by subclasses to provide reasonable default behavior. Returns true to indicate to the event system that the event has been handled, and needs no further processing; otherwise returns false to indicate that the event should be propagated further.
You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.
Specialised handlers for viewport events are: paintEvent()
, mousePressEvent()
, mouseReleaseEvent()
, mouseDoubleClickEvent()
, mouseMoveEvent()
, wheelEvent()
, dragEnterEvent()
, dragMoveEvent()
, dragLeaveEvent()
, dropEvent()
, contextMenuEvent()
, and resizeEvent()
.
public static QAbstractScrollArea fromNativePointer(QNativePointer nativePointer)
|
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | ||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |