QCursor Class Reference

#include <qcursor.h>

Collaboration diagram for QCursor:

[legend]List of all members.

---

Detailed Description

The QCursor class provides a mouse cursor with an arbitrary shape.

This class is mainly used to create mouse cursors that are associated with particular widgets and to get and set the position of the mouse cursor.

Qt has a number of standard cursor shapes, but you can also make custom cursor shapes based on a QBitmap, a mask and a hotspot.

To associate a cursor with a widget, use QWidget::setCursor(). To associate a cursor with all widgets (normally for a short period of time), use QApplication::setOverrideCursor().

To set a cursor shape use QCursor::setShape() or use the QCursor constructor which takes the shape as argument, or you can use one of the predefined cursors defined in the Qt::CursorShape enum.

If you want to create a cursor with your own bitmap, either use the QCursor constructor which takes a bitmap and a mask or the constructor which takes a pixmap as arguments.

To set or get the position of the mouse cursor use the static methods QCursor::pos() and QCursor::setPos().

On X11, Qt supports the \link http://www.xfree86.org/4.3.0/Xcursor.3.html Xcursor\endlink library, which allows for full color icon themes. The table below shows the cursor name used for each Qt::CursorShape value. If a cursor cannot be found using the name shown below, a standard X11 cursor will be used instead. Note: X11 does not provide appropriate cursors for all possible Qt::CursorShape values. It is possible that some cursors will be taken from the Xcursor theme, while others will use an internal bitmap cursor. \table \header \o Shape \o Qt::CursorShape Value \o Cursor Name \o Shape \o Qt::CursorShape Value \o Cursor Name \row \o \inlineimage cursor-arrow.png \o Qt::ArrowCursor \o \c left_ptr \o \inlineimage cursor-sizev.png \o Qt::SizeVerCursor \o \c size_ver \row \o \inlineimage cursor-uparrow.png \o Qt::UpArrowCursor \o \c up_arrow \o \inlineimage cursor-sizeh.png \o Qt::SizeHorCursor \o \c size_hor \row \o \inlineimage cursor-cross.png \o Qt::CrossCursor \o \c cross \o \inlineimage cursor-sizeb.png \o Qt::SizeBDiagCursor \o \c size_bdiag \row \o \inlineimage cursor-ibeam.png \o Qt::IBeamCursor \o \c ibeam \o \inlineimage cursor-sizef.png \o Qt::SizeFDiagCursor \o \c size_fdiag \row \o \inlineimage cursor-wait.png \o Qt::WaitCursor \o \c wait \o \inlineimage cursor-sizeall.png \o Qt::SizeAllCursor \o \c size_all \row \o \inlineimage cursor-busy.png \o Qt::BusyCursor \o \c left_ptr_watch \o \inlineimage cursor-vsplit.png \o Qt::SplitVCursor \o \c split_v \row \o \inlineimage cursor-forbidden.png \o Qt::ForbiddenCursor \o \c forbidden \o \inlineimage cursor-hsplit.png \o Qt::SplitHCursor \o \c split_h \row \o \inlineimage cursor-hand.png \o Qt::PointingHandCursor \o \c pointing_hand \o \inlineimage cursor-openhand.png \o Qt::OpenHandCursor \o \c openhand \row \o \inlineimage cursor-whatsthis.png \o Qt::WhatsThisCursor \o \c whats_this \o \inlineimage cursor-closedhand.png \o Qt::ClosedHandCursor \o \c closedhand \endtable \sa QWidget, {fowler}{GUI Design Handbook: Cursors} Definition at line 63 of file qcursor.h.

Public Member Functions
	QCursor ()
	QCursor (Qt::CursorShape shape)
	QCursor (const QBitmap &bitmap, const QBitmap &mask, int hotX=-1, int hotY=-1)
	QCursor (const QPixmap &pixmap, int hotX=-1, int hotY=-1)
	QCursor (const QCursor &cursor)
	~QCursor ()
QCursor &	operator= (const QCursor &cursor)
	operator QVariant () const
Qt::CursorShape	shape () const
void	setShape (Qt::CursorShape newShape)
const QBitmap *	bitmap () const
const QBitmap *	mask () const
QPixmap	pixmap () const
QPoint	hotSpot () const
Static Public Member Functions
static QPoint	pos ()
static void	setPos (int x, int y)
static void	setPos (const QPoint &p)
Private Attributes
QCursorData *	d
Related Functions
(Note that these are not member functions.)
QDataStream &	operator<< (QDataStream &stream, const QCursor &cursor)
QDataStream &	operator>> (QDataStream &stream, QCursor &cursor)

---

Constructor & Destructor Documentation

QCursor::QCursor

(

)

Constructs a cursor with the default arrow shape.

Definition at line 335 of file qcursor.cpp.

References c, d, QCursorData::initialize(), QCursorData::initialized, qApp, and qt_cursorTable.

{
    if (!QCursorData::initialized) {
        if (qApp->startingUp()) {
            d = 0;
            return;
        }
        QCursorData::initialize();
    }
    QCursorData *c = qt_cursorTable[0];
    c->ref.ref();
    d = c;
}

Here is the call graph for this function:

QCursor::QCursor

(

Qt::CursorShape

shape

)

Constructs a cursor with the specified shape.

See Qt::CursorShape for a list of shapes.

See also:

setShape()

Definition at line 356 of file qcursor.cpp.

References QCursorData::initialize(), QCursorData::initialized, and setShape().

    : d(0)
{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    setShape(shape);
}

Here is the call graph for this function:

QCursor::QCursor	(	const QBitmap &	bitmap,
		const QBitmap &	mask,
		int	hotX = -1,
		int	hotY = -1
	)

Constructs a custom bitmap cursor.

bitmap and mask make up the bitmap. hotX and hotY define the cursor's hot spot.

If hotX is negative, it is set to the {bitmap().width()/2}. If hotY is negative, it is set to the {bitmap().height()/2}.

The cursor bitmap (B) and mask (M) bits are combined like this: B=1 and M=1 gives black. B=0 and M=1 gives white. B=0 and M=0 gives transparent. B=1 and M=0 gives an XOR'd result.

Use the global Qt color Qt::color0 to draw 0-pixels and Qt::color1 to draw 1-pixels in the bitmaps.

Valid cursor sizes depend on the display hardware (or the underlying window system). We recommend using 32 x 32 cursors, because this size is supported on all platforms. Some platforms also support 16 x 16, 48 x 48, and 64 x 64 cursors.

See also:

QBitmap::QBitmap(), QBitmap::setMask()

Definition at line 297 of file qcursor.cpp.

References bitmap(), d, mask(), and QCursorData::setBitmap().

    : d(0)
{
    d = QCursorData::setBitmap(bitmap, mask, hotX, hotY);
}

Here is the call graph for this function:

QCursor::QCursor	(	const QPixmap &	pixmap,
		int	hotX = -1,
		int	hotY = -1
	)

Constructs a custom pixmap cursor.

pixmap is the image. It is usual to give it a mask (set using QPixmap::setMask()). hotX and hotY define the cursor's hot spot.

If hotX is negative, it is set to the {pixmap().width()/2}. If hotY is negative, it is set to the {pixmap().height()/2}.

Valid cursor sizes depend on the display hardware (or the underlying window system). We recommend using 32 x 32 cursors, because this size is supported on all platforms. Some platforms also support 16 x 16, 48 x 48, and 64 x 64 cursors.

See also:

QPixmap::QPixmap(), QPixmap::setMask()

Definition at line 242 of file qcursor.cpp.

References Qt::AvoidDither, Qt::color1, QImage::convertToFormat(), d, QPixmap::fill(), QImage::Format_Indexed8, QBitmap::fromImage(), QPixmap::isNull(), QPixmap::mask(), pixmap(), QCursorData::pixmap, QCursorData::setBitmap(), QPixmap::setMask(), QPixmap::size(), Qt::ThresholdDither, and QPixmap::toImage().

    : d(0)
{
    QImage img = pixmap.toImage().convertToFormat(QImage::Format_Indexed8, Qt::ThresholdDither|Qt::AvoidDither);
    QBitmap bm = QBitmap::fromImage(img, Qt::ThresholdDither|Qt::AvoidDither);
    QBitmap bmm = pixmap.mask();
    if (!bmm.isNull()) {
        QBitmap nullBm;
        bm.setMask(nullBm);
    }
    else if (!pixmap.mask().isNull()) {
        QImage mimg = pixmap.mask().toImage().convertToFormat(QImage::Format_Indexed8, Qt::ThresholdDither|Qt::AvoidDither);
        bmm = QBitmap::fromImage(mimg, Qt::ThresholdDither|Qt::AvoidDither);
    }
    else {
        bmm = QBitmap(bm.size());
        bmm.fill(Qt::color1);
    }

    d = QCursorData::setBitmap(bm, bmm, hotX, hotY);
    d->pixmap = pixmap;
}

Here is the call graph for this function:

QCursor::QCursor

(

const QCursor &

c

)

Constructs a copy of the cursor c.

Definition at line 453 of file qcursor.cpp.

References c, d, QCursorData::initialize(), QCursorData::initialized, QBasicAtomic::ref(), and QCursorData::ref.

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    d = c.d;
    d->ref.ref();
}

Here is the call graph for this function:

QCursor::~QCursor

(

)

Destroys the cursor.

Definition at line 465 of file qcursor.cpp.

References d, QBasicAtomic::deref(), and QCursorData::ref.

{
    if (d && !d->ref.deref())
        delete d;
}

Here is the call graph for this function:

---

Member Function Documentation

QCursor & QCursor::operator=

(

const QCursor &

c

)

Assigns c to this cursor and returns a reference to this cursor.

Definition at line 477 of file qcursor.cpp.

References c, d, QCursorData::initialize(), QCursorData::initialized, and qAtomicAssign().

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    qAtomicAssign(d, c.d);
    return *this;
}

Here is the call graph for this function:

QCursor::operator QVariant

(

)

const

Returns the cursor as a QVariant.

Definition at line 488 of file qcursor.cpp.

References QVariant::Cursor.

{
    return QVariant(QVariant::Cursor, this);
}

Qt::CursorShape QCursor::shape

(

)

const

Returns the cursor shape identifier. The return value is one of the Qt::CursorShape enum values (cast to an int).

See also:

setShape()

Definition at line 371 of file qcursor.cpp.

References QCursorData::cshape, d, QCursorData::initialize(), and QCursorData::initialized.

Referenced by QTextBrowserPrivate::_q_highlightLink(), qdesigner_internal::CursorProperty::decoration(), Q3TableHeader::mouseMoveEvent(), Q3TableHeader::mousePressEvent(), QWidget::setCursor(), qdesigner_internal::CursorProperty::toString(), qdesigner_internal::CursorProperty::updateEditorContents(), and qdesigner_internal::CursorProperty::updateValue().

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    return d->cshape;
}

Here is the call graph for this function:

void QCursor::setShape

(

Qt::CursorShape

shape

)

Sets the cursor to the shape identified by shape.

See Qt::CursorShape for the list of cursor shapes.

See also:

shape()

Definition at line 385 of file qcursor.cpp.

References c, d, QCursorData::initialize(), QCursorData::initialized, Qt::LastCursor, qAtomicSetPtr(), and qt_cursorTable.

Referenced by QCursor().

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    QCursorData *c = uint(shape) <= Qt::LastCursor ? qt_cursorTable[shape] : 0;
    if (!c)
        c = qt_cursorTable[0];
    c->ref.ref();
    if (!d) {
        d = c;
    } else {
        c = qAtomicSetPtr(&d, c);
        if (!c->ref.deref())
            delete c;
    }
}

Here is the call graph for this function:

const QBitmap * QCursor::bitmap

(

)

const

Returns the cursor bitmap, or 0 if it is one of the standard cursors.

Definition at line 406 of file qcursor.cpp.

References QCursorData::bm, d, QCursorData::initialize(), and QCursorData::initialized.

Referenced by QCursor().

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    return d->bm;
}

Here is the call graph for this function:

const QBitmap * QCursor::mask

(

)

const

Returns the cursor bitmap mask, or 0 if it is one of the standard cursors.

Definition at line 418 of file qcursor.cpp.

References QCursorData::bmm, d, QCursorData::initialize(), and QCursorData::initialized.

Referenced by QCursor().

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    return d->bmm;
}

Here is the call graph for this function:

QPixmap QCursor::pixmap

(

)

const

Returns the cursor pixmap. This is only valid if the cursor is a pixmap cursor.

Definition at line 430 of file qcursor.cpp.

References d, QCursorData::initialize(), QCursorData::initialized, and QCursorData::pixmap.

Referenced by QCursor().

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    return d->pixmap;
}

Here is the call graph for this function:

QPoint QCursor::hotSpot

(

)

const

Returns the cursor hot spot, or (0, 0) if it is one of the standard cursors.

Definition at line 442 of file qcursor.cpp.

References d, QCursorData::hx, QCursorData::hy, QCursorData::initialize(), and QCursorData::initialized.

{
    if (!QCursorData::initialized)
        QCursorData::initialize();
    return QPoint(d->hx, d->hy);
}

Here is the call graph for this function:

QPoint QCursor::pos

(

)

[static]

Returns the position of the cursor (hot spot) in global screen coordinates.

You can call QWidget::mapFromGlobal() to translate it to widget coordinates.

See also:

setPos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal()

Definition at line 128 of file qcursor_x11.cpp.

References QX11Info::appRootWindow(), i, and X11.

Referenced by Q3AccelPrivate::activate(), QDialog::adjustPosition(), Q3TextEdit::autoScrollTimerDone(), QGraphicsViewPrivate::centerView(), QApplicationPrivate::dispatchEnterLeave(), Q3ListView::doAutoScroll(), QAbstractItemView::doAutoScroll(), Q3TableHeader::doAutoScroll(), Q3IconView::doAutoScroll(), Q3Table::doAutoScroll(), Q3ScrollView::doDragAutoScroll(), QWidgetResizeHandler::doMove(), QWidgetResizeHandler::doResize(), QDragManager::drag(), qdesigner_internal::FormWindowManager::dragItems(), qdesigner_internal::ConnectionEdit::endConnection(), qdesigner_internal::BuddyEditor::endConnection(), QShortcut::event(), QDragManager::eventFilter(), QPixelTool::grabScreen(), qdesigner_internal::WidgetBoxTreeView::handleMousePress(), QMenu::internalDelayedPopup(), Q3DockWindowTitleBar::keyPressEvent(), QWidgetResizeHandler::keyPressEvent(), Q3DockWindowHandle::keyPressEvent(), Q3DockWindowHandle::keyReleaseEvent(), Q3DockWindowTitleBar::keyReleaseEvent(), QApplicationPrivate::leaveModal_sys(), QGraphicsScenePrivate::leaveScene(), QDragManager::move(), Q3TextEdit::optimDoAutoScroll(), Q3TitleBar::paintEvent(), QWorkspaceTitleBar::paintEvent(), QMenu::popup(), Q3FileDialog::popupContextMenu(), QVFb::popupMenu(), QContextMenuEvent::QContextMenuEvent(), QMouseEvent::QMouseEvent(), QWhatsThisPrivate::QWhatsThisPrivate(), QWheelEvent::QWheelEvent(), QGraphicsItem::setCursor(), QHeaderView::setOffset(), QTextBrowserPrivate::setSource(), Q3TextBrowser::setSource(), MainWindow::setupPuzzle(), QAbstractItemView::startDrag(), QDragManager::timerEvent(), QTextEdit::timerEvent(), QDragManager::updatePixmap(), and QMessageBoxPrivate::updateSize().

{
    Window root;
    Window child;
    int root_x, root_y, win_x, win_y;
    uint buttons;
    Display* dpy = X11->display;
    for (int i = 0; i < ScreenCount(dpy); ++i) {
        if (XQueryPointer(dpy, QX11Info::appRootWindow(i), &root, &child, &root_x, &root_y,
                          &win_x, &win_y, &buttons))

            return QPoint(root_x, root_y);
    }
    return QPoint();
}

Here is the call graph for this function:

void QCursor::setPos	(	int	x,
		int	y
	)			[static]

Moves the cursor (hot spot) to the global screen position (x, y).

You can call QWidget::mapToGlobal() to translate widget coordinates to global screen coordinates.

See also:

pos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal()

Definition at line 171 of file qcursor_x11.cpp.

References QX11Info::appRootWindow(), X11, and XNone.

Referenced by QWidgetResizeHandler::keyPressEvent(), QTest::mouseEvent(), and QHeaderView::setOffset().

{
    QPoint current, target(x, y);

    // this is copied from pos(), since we need the screen number for the correct
    // root window in the XWarpPointer call
    Window root;
    Window child;
    int root_x, root_y, win_x, win_y;
    uint buttons;
    Display* dpy = X11->display;
    int screen;
    for (screen = 0; screen < ScreenCount(dpy); ++screen) {
        if (XQueryPointer(dpy, QX11Info::appRootWindow(screen), &root, &child, &root_x, &root_y,
                          &win_x, &win_y, &buttons)) {
            current = QPoint(root_x, root_y);
            break;
        }
    }

    if (screen >= ScreenCount(dpy))
        return;

    // Need to check, since some X servers generate null mouse move
    // events, causing looping in applications which call setPos() on
    // every mouse move event.
    //
    if (current == target)
        return;

    XWarpPointer(X11->display, XNone, QX11Info::appRootWindow(screen), 0, 0, 0, 0, x, y);
}

Here is the call graph for this function:

void QCursor::setPos

(

const QPoint &

p

)

[inline, static]

This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. Moves the cursor (hot spot) to the global screen position at point p.

Definition at line 85 of file qcursor.h.

References p.

{ setPos(p.x(), p.y()); }

---

Friends And Related Function Documentation

QDataStream & operator<<	(	QDataStream &	stream,
		const QCursor &	cursor
	)			[related]

Writes the cursor to the stream.

See also:

{Format of the QDataStream operators}

Definition at line 170 of file qcursor.cpp.

{
    s << (qint16)c.shape();                        // write shape id to stream
    if (c.shape() == Qt::BitmapCursor) {                // bitmap cursor
        bool isPixmap = false;
        if (s.version() >= 7) {
            isPixmap = !c.pixmap().isNull();
            s << isPixmap;
        }
        if (isPixmap)
            s << c.pixmap();
        else
            s << *c.bitmap() << *c.mask();
        s << c.hotSpot();
    }
    return s;
}

QDataStream & operator>>	(	QDataStream &	stream,
		QCursor &	cursor
	)			[related]

Reads the cursor from the stream.

See also:

{Format of the QDataStream operators}

Definition at line 197 of file qcursor.cpp.

{
    qint16 shape;
    s >> shape;                                        // read shape id from stream
    if (shape == Qt::BitmapCursor) {                // read bitmap cursor
        bool isPixmap = false;
        if (s.version() >= 7)
            s >> isPixmap;
        if (isPixmap) {
            QPixmap pm;
            QPoint hot;
            s >> pm >> hot;
            c = QCursor(pm, hot.x(), hot.y());
        } else {
            QBitmap bm, bmm;
            QPoint hot;
            s >> bm >> bmm >> hot;
            c = QCursor(bm, bmm, hot.x(), hot.y());
        }
    } else {
        c.setShape((Qt::CursorShape)shape);                // create cursor with shape
    }
    return s;
}

---

Member Data Documentation

QCursorData* QCursor::d [private]

Definition at line 109 of file qcursor.h.

Referenced by bitmap(), hotSpot(), mask(), operator=(), pixmap(), QCursor(), setShape(), shape(), and ~QCursor().

---

The documentation for this class was generated from the following files:

• src/gui/kernel/qcursor.h
• src/gui/kernel/qcursor.cpp
• src/gui/kernel/qcursor_x11.cpp

---