Qt Jambi Home

com.trolltech.qt.gui
Class QRubberBand

java.lang.Object
  extended by com.trolltech.qt.QSignalEmitter
      extended by com.trolltech.qt.QtJambiObject
          extended by com.trolltech.qt.core.QObject
              extended by com.trolltech.qt.gui.QWidget
                  extended by com.trolltech.qt.gui.QRubberBand
All Implemented Interfaces:
QPaintDeviceInterface, QtJambiInterface

public class QRubberBand
extends QWidget

The QRubberBand class provides a rectangle or line that can indicate a selection or a boundary.

A rubber band is often used to show a new bounding area (as in a QSplitter or a QDockWidget that is undocking). Historically this has been implemented using a QPainter and XOR, but this approach doesn't always work properly since rendering can happen in the window below the rubber band, but before the rubber band has been "erased".

You can create a QRubberBand whenever you need to render a rubber band around a given area (or to represent a single line), then call setGeometry, move or resize to position and size it. A common pattern is to do this in conjunction with mouse events. For example:

    void Widget::mousePressEvent(QMouseEvent *event)
    {
        origin = event->pos();
        if (!rubberBand)
            rubberBand = new QRubberBand(QRubberBand::Rectangle, this);
        rubberBand->setGeometry(QRect(origin, QSize()));
        rubberBand->show();
    }

    void Widget::mouseMoveEvent(QMouseEvent *event)
    {
        rubberBand->setGeometry(QRect(origin, event->pos()).normalized());
    }

    void Widget::mouseReleaseEvent(QMouseEvent *event)
    {
        rubberBand->hide();
        // determine selection, for example using QRect::intersects()
        // and QRect::contains().
    }

If you pass a parent to QRubberBand's constructor, the rubber band will display only inside its parent, but stays on top of other child widgets. If no parent is passed, QRubberBand will act as a top-level widget.

Call show to make the rubber band visible; also when the rubber band is not a top-level. Hiding or destroying the widget will make the rubber band disappear. The rubber band can be a Rectangle or a Line (vertical or horizontal), depending on the shape it was given when constructed.


Nested Class Summary
static class QRubberBand.Shape
          This enum specifies what shape a QRubberBand should have.
 
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<A>, QSignalEmitter.Signal2<A,B>, QSignalEmitter.Signal3<A,B,C>, QSignalEmitter.Signal4<A,B,C,D>, QSignalEmitter.Signal5<A,B,C,D,E>, QSignalEmitter.Signal6<A,B,C,D,E,F>, QSignalEmitter.Signal7<A,B,C,D,E,F,G>, QSignalEmitter.Signal8<A,B,C,D,E,F,G,H>, QSignalEmitter.Signal9<A,B,C,D,E,F,G,H,I>
 
Field Summary
 
Fields inherited from class com.trolltech.qt.gui.QWidget
customContextMenuRequested
 
Constructor Summary
QRubberBand(QRubberBand.Shape arg__1)
          Equivalent to QRubberBand(arg__1, 0).
QRubberBand(QRubberBand.Shape arg__1, QWidget arg__2)
          Constructs a rubber band of shape arg__1, with parent arg__2.
 
Method Summary
protected  void changeEvent(QEvent arg__1)
          

This event handler can be reimplemented to handle state changes.

 boolean event(QEvent e)
          

This is the main event handler; it handles event arg__1.

static QRubberBand fromNativePointer(QNativePointer nativePointer)
          This function returns the QRubberBand instance pointed to by nativePointer
protected  void initStyleOption(QStyleOptionRubberBand option)
          This is a overloaded function provided for convenience.
protected  void moveEvent(QMoveEvent arg__1)
          

This event handler can be reimplemented in a subclass to receive widget move events which are passed in the arg__1 parameter.

 void moveRubberBand(int x, int y)
          Moves the rubberband to point (x, y).
 void moveRubberBand(QPoint p)
          Moves the rubberband to point p.
protected  void paintEvent(QPaintEvent arg__1)
          

This event handler can be reimplemented in a subclass to receive paint events which are passed in the arg__1 parameter.

protected  void resizeEvent(QResizeEvent arg__1)
          

This event handler can be reimplemented in a subclass to receive widget resize events which are passed in the arg__1 parameter.

 void resizeRubberBand(int w, int h)
          Resizes the rubberband so that its width is w, and its height is h.
 void resizeRubberBand(QSize s)
          Resizes the rubberband so that its new size is s.
 void setRubberBandGeometry(int x, int y, int w, int h)
          Sets the geometry of the rubberband to the rectangle whose top-left corner lies at the point (x, y), and with dimensions specified by w and h.
 void setRubberBandGeometry(QRect r)
          Sets the geometry of the rubber band to r, specified in the coordinate system of its parent widget.
 QRubberBand.Shape shape()
          Returns the shape of this rubber band.
protected  void showEvent(QShowEvent arg__1)
          

This event handler can be reimplemented in a subclass to receive widget show events which are passed in the arg__1 parameter.

 
Methods inherited from class com.trolltech.qt.gui.QWidget
acceptDrops, accessibleDescription, accessibleName, actionEvent, actions, activateWindow, addAction, addActions, adjustSize, autoFillBackground, backgroundRole, baseSize, childAt, childAt, childrenRect, childrenRegion, clearFocus, clearMask, close, closeEvent, contentsRect, contextMenuEvent, contextMenuPolicy, createWinId, cursor, depth, destroy, destroy, destroy, devType, dragEnterEvent, dragLeaveEvent, dragMoveEvent, dropEvent, ensurePolished, enterEvent, focusInEvent, focusNextChild, focusNextPrevChild, focusOutEvent, focusPolicy, focusPreviousChild, focusProxy, focusWidget, font, fontInfo, fontMetrics, foregroundRole, frameGeometry, frameSize, geometry, getContentsMargins, grabKeyboard, grabMouse, grabMouse, grabShortcut, grabShortcut, hasFocus, hasMouseTracking, height, heightForWidth, heightMM, hide, hideEvent, inputContext, inputMethodEvent, inputMethodQuery, insertAction, insertActions, isActiveWindow, isAncestorOf, isEnabled, isEnabledTo, isFullScreen, isHidden, isLeftToRight, isMaximized, isMinimized, isModal, isRightToLeft, isVisible, isVisibleTo, isWindow, isWindowModified, keyboardGrabber, keyPressEvent, keyReleaseEvent, layout, layoutDirection, leaveEvent, locale, logicalDpiX, logicalDpiY, lower, mapFrom, mapFromGlobal, mapFromParent, mapTo, mapToGlobal, mapToParent, mask, maximumHeight, maximumSize, maximumWidth, metric, minimumHeight, minimumSize, minimumSizeHint, minimumWidth, mouseDoubleClickEvent, mouseGrabber, mouseMoveEvent, mousePressEvent, mouseReleaseEvent, move, move, nextInFocusChain, normalGeometry, numColors, overrideWindowFlags, overrideWindowFlags, overrideWindowState, overrideWindowState, paintEngine, paintingActive, palette, parentWidget, physicalDpiX, physicalDpiY, pos, raise, rect, releaseKeyboard, releaseMouse, releaseShortcut, removeAction, render, render, render, render, render, repaint, repaint, repaint, repaint, resetInputContext, resize, resize, restoreGeometry, saveGeometry, scroll, scroll, setAcceptDrops, setAccessibleDescription, setAccessibleName, setAttribute, setAttribute, setAutoFillBackground, setBackgroundRole, setBaseSize, setBaseSize, setContentsMargins, setContentsMargins, setContextMenuPolicy, setCursor, setDisabled, setEnabled, setFixedHeight, setFixedSize, setFixedSize, setFixedWidth, setFocus, setFocus, setFocusPolicy, setFocusProxy, setFont, setForegroundRole, setGeometry, setGeometry, setHidden, setInputContext, setLayout, setLayoutDirection, setLocale, setMask, setMask, setMaximumHeight, setMaximumSize, setMaximumSize, setMaximumWidth, setMinimumHeight, setMinimumSize, setMinimumSize, setMinimumWidth, setMouseTracking, setPalette, setParent, setParent, setParent, setShortcutAutoRepeat, setShortcutAutoRepeat, setShortcutEnabled, setShortcutEnabled, setSizeIncrement, setSizeIncrement, setSizePolicy, setSizePolicy, setStatusTip, setStyle, setStyleSheet, setTabOrder, setToolTip, setUpdatesEnabled, setVisible, setWhatsThis, setWindowFlags, setWindowFlags, setWindowIcon, setWindowIconText, setWindowModality, setWindowModified, setWindowOpacity, setWindowRole, setWindowState, setWindowState, setWindowTitle, show, showFullScreen, showMaximized, showMinimized, showNormal, size, sizeHint, sizeIncrement, sizePolicy, stackUnder, statusTip, style, styleSheet, tabletEvent, testAttribute, toolTip, underMouse, unsetCursor, unsetLayoutDirection, unsetLocale, update, update, update, update, updateGeometry, updateMicroFocus, updatesEnabled, visibleRegion, whatsThis, wheelEvent, width, widthMM, window, windowFlags, windowIcon, windowIconText, windowModality, windowOpacity, windowRole, windowState, windowTitle, windowType, winId, x, y
 
Methods inherited from class com.trolltech.qt.core.QObject
blockSignals, childEvent, children, connectSlotsByName, customEvent, disposeLater, dumpObjectInfo, dumpObjectTree, dynamicPropertyNames, eventFilter, findChild, findChild, findChild, findChildren, findChildren, findChildren, findChildren, installEventFilter, isWidgetType, killTimer, moveToThread, objectName, parent, property, removeEventFilter, setObjectName, setParent, setProperty, signalsBlocked, startTimer, thread, timerEvent
 
Methods inherited from class com.trolltech.qt.QtJambiObject
dispose, disposed, finalize, reassignNativeResources, tr, tr, tr
 
Methods inherited from class com.trolltech.qt.QSignalEmitter
disconnect, disconnect, signalSender
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface com.trolltech.qt.QtJambiInterface
disableGarbageCollection, nativeId, nativePointer, reenableGarbageCollection, setJavaOwnership
 

Constructor Detail

QRubberBand

public QRubberBand(QRubberBand.Shape arg__1)

Equivalent to QRubberBand(arg__1, 0).


QRubberBand

public QRubberBand(QRubberBand.Shape arg__1,
                   QWidget arg__2)

Constructs a rubber band of shape arg__1, with parent arg__2.

By default a rectangular rubber band (arg__1 is Rectangle) will use a mask, so that a small border of the rectangle is all that is visible. Some styles (e.g., native Mac OS X) will change this and call QWidget::setWindowOpacity() to make a semi-transparent filled selection rectangle.

Method Detail

moveRubberBand

public final void moveRubberBand(QPoint p)

Moves the rubberband to point p.

See Also:
resize

moveRubberBand

public final void moveRubberBand(int x,
                                 int y)

Moves the rubberband to point (x, y).

See Also:
resize

resizeRubberBand

public final void resizeRubberBand(QSize s)

Resizes the rubberband so that its new size is s.

See Also:
move

resizeRubberBand

public final void resizeRubberBand(int w,
                                   int h)

Resizes the rubberband so that its width is w, and its height is h.

See Also:
move

setRubberBandGeometry

public final void setRubberBandGeometry(int x,
                                        int y,
                                        int w,
                                        int h)

Sets the geometry of the rubberband to the rectangle whose top-left corner lies at the point (x, y), and with dimensions specified by w and h. The geometry is specified in the parent widget's coordinate system.


setRubberBandGeometry

public final void setRubberBandGeometry(QRect r)

Sets the geometry of the rubber band to r, specified in the coordinate system of its parent widget.

See Also:
QWidget::geometry

shape

public final QRubberBand.Shape shape()

Returns the shape of this rubber band. The shape can only be set upon construction.


changeEvent

protected void changeEvent(QEvent arg__1)

This event handler can be reimplemented to handle state changes.

The state being changed in this event can be retrieved through event arg__1.

Change events include: QEvent::ToolBarChange, QEvent::ActivationChange, QEvent::EnabledChange, QEvent::FontChange, QEvent::StyleChange, QEvent::PaletteChange, QEvent::WindowTitleChange, QEvent::IconTextChange, QEvent::ModifiedChange, QEvent::MouseTrackingChange, QEvent::ParentChange, QEvent::WindowStateChange, QEvent::LanguageChange, QEvent::LocaleChange, QEvent::LayoutDirectionChange.

Overrides:
changeEvent in class QWidget

event

public boolean event(QEvent e)

This is the main event handler; it handles event arg__1. You can reimplement this function in a subclass, but we recommend using one of the specialized event handlers instead.

Key press and release events are treated differently from other events. event checks for Tab and Shift+Tab and tries to move the focus appropriately. If there is no widget to move the focus to (or the key press is not Tab or Shift+Tab), event calls keyPressEvent.

Mouse and tablet event handling is also slightly special: only when the widget is enabled, event will call the specialized handlers such as mousePressEvent; otherwise it will discard the event.

This function returns true if the event was recognized, otherwise it returns false. If the recognized event was accepted (see QEvent::accepted), any further processing such as event propagation to the parent widget stops.

Overrides:
event in class QWidget
See Also:
closeEvent, focusInEvent, focusOutEvent, enterEvent, keyPressEvent, keyReleaseEvent, leaveEvent, mouseDoubleClickEvent, mouseMoveEvent, mousePressEvent, mouseReleaseEvent, moveEvent, paintEvent, resizeEvent, QObject::event, QObject::timerEvent

moveEvent

protected void moveEvent(QMoveEvent arg__1)

This event handler can be reimplemented in a subclass to receive widget move events which are passed in the arg__1 parameter. When the widget receives this event, it is already at the new position.

The old position is accessible through QMoveEvent::oldPos().

Overrides:
moveEvent in class QWidget
See Also:
resizeEvent, event, move, QMoveEvent

paintEvent

protected void paintEvent(QPaintEvent arg__1)

This event handler can be reimplemented in a subclass to receive paint events which are passed in the arg__1 parameter.

A paint event is a request to repaint all or part of the widget. It can happen as a result of repaint or update, or because the widget was obscured and has now been uncovered, or for many other reasons.

Many widgets can simply repaint their entire surface when asked to, but some slow widgets need to optimize by painting only the requested region: QPaintEvent::region(). This speed optimization does not change the result, as painting is clipped to that region during event processing. QListView and QTableView do this, for example.

Qt also tries to speed up painting by merging multiple paint events into one. When update is called several times or the window system sends several paint events, Qt merges these events into one event with a larger region (see QRegion::united()). repaint does not permit this optimization, so we suggest using update whenever possible.

When the paint event occurs, the update region has normally been erased, so that you're painting on the widget's background.

The background can be set using setBackgroundRole and setPalette.

From Qt 4.0, QWidget automatically double-buffers its painting, so there's no need to write double-buffering code in paintEvent to avoid flicker.

Note: Under X11 it is possible to toggle the global double buffering by calling qt_x11_set_global_double_buffer(). Example usage:

    ...
    extern void qt_x11_set_global_double_buffer(bool);
    qt_x11_set_global_double_buffer(false);
    ...

Note: In general, one should refrain from calling update or repaint inside of paintEvent. For example, calling update or repaint on children inside a paintEvent results in undefined behavior; the child may or may not get a paint event.

Overrides:
paintEvent in class QWidget
See Also:
event, repaint, update, QPainter, QPixmap, QPaintEvent, Analog Clock Example

resizeEvent

protected void resizeEvent(QResizeEvent arg__1)

This event handler can be reimplemented in a subclass to receive widget resize events which are passed in the arg__1 parameter. When resizeEvent is called, the widget already has its new geometry. The old size is accessible through QResizeEvent::oldSize().

The widget will be erased and receive a paint event immediately after processing the resize event. No drawing need be (or should be) done inside this handler.

Overrides:
resizeEvent in class QWidget
See Also:
moveEvent, event, resize, QResizeEvent, paintEvent, Example

showEvent

protected void showEvent(QShowEvent arg__1)

This event handler can be reimplemented in a subclass to receive widget show events which are passed in the arg__1 parameter.

Non-spontaneous show events are sent to widgets immediately before they are shown. The spontaneous show events of windows are delivered afterwards.

Note: A widget receives spontaneous show and hide events when its mapping status is changed by the window system, e.g. a spontaneous hide event when the user minimizes the window, and a spontaneous show event when the window is restored again. After receiving a spontaneous hide event, a widget is still considered visible in the sense of isVisible.

Overrides:
showEvent in class QWidget
See Also:
visible, event, QShowEvent

fromNativePointer

public static QRubberBand fromNativePointer(QNativePointer nativePointer)
This function returns the QRubberBand instance pointed to by nativePointer

Parameters:
nativePointer - the QNativePointer of which object should be returned.

initStyleOption

protected final void initStyleOption(QStyleOptionRubberBand option)
This is a overloaded function provided for convenience.


Qt Jambi Home