QCursor类

QCursor类提供了一个具有任意形状的鼠标光标。更多...

头文件	#include <QCursor>
CMake	find_package(Qt6 REQUIRED COMPONENTS Gui) target_link_libraries(mytarget PRIVATE Qt6::Gui)
qmake	QT += gui

公共函数

	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 &c)
	QCursor(QCursor &&other)
	~QCursor()
QBitmap	bitmap() const
QPoint	hotSpot() const
QBitmap	mask() const
QPixmap	pixmap() const
void	setShape(Qt::CursorShape shape)
Qt::CursorShape	shape() const
void	swap(QCursor &other)
QVariant	operator QVariant() const
QCursor &	operator=(const QCursor &c)
QCursor &	operator=(QCursor &&other)

静态公共成员

QPoint	pos()
QPoint	pos(const QScreen *screen)
void	setPos(int x, int y)
void	setPos(QScreen *screen, int x, int y)
void	setPos(const QPoint &p)
void	setPos(QScreen *screen, const QPoint &p)

bool	operator!=(const QCursor &lhs, const QCursor &rhs)
QDataStream &	operator<<(QDataStream &stream, const QCursor &cursor)
bool	operator==(const QCursor &lhs, const QCursor &rhs)
QDataStream &	operator>>(QDataStream &stream, QCursor &cursor)

详细描述

此类主要用于创建与特定小部件相关联的鼠标光标，以及获取和设置鼠标光标的位置。

Qt 有许多标准的光标形状，但您也可以基于一个 QBitmap、一个遮罩和一个热区来创建自定义光标形状。

要将光标与小部件关联，请使用 QWidget::setCursor()。要将光标与所有小部件关联（通常是一段时间），请使用 QGuiApplication::setOverrideCursor()。

要设置光标形状，可以使用 QCursor::setShape()，或者使用接受形状作为参数的 QCursor 构造函数，或者您可以使用在 Qt::CursorShape 枚举中定义的预定义光标之一。

如果您想创建具有您自己的位图的游标，可以使用接受位图和遮罩的 QCursor 构造函数，或者使用接受像素图作为参数的构造函数。

要设置或获取鼠标光标的当前位置，请使用静态方法 QCursor::pos() 和 QCursor::setPos()。

注意：可以在创建 QGuiApplication 之前创建一个 QCursor，但除了作为创建于 QGuiApplication 之后的真正 QCursor 的占位符之外，它并没有什么用处。尝试使用在 QGuiApplication 之前创建的 QCursor 将导致崩溃。

针对 X11 用户的注意事项

在 X11 上，Qt 支持 Xcursor 库，允许使用全色图标主题。下表显示了每个 Qt::CursorShape 值所使用的光标名称。如果无法使用以下显示的名称找到光标，将使用标准 X11 光标。注意：X11 并不为所有可能的 Qt::CursorShape 值提供适当的游标。某些游标可能来自 Xcursor 主题，而其他则使用内部位图游标。

Qt::CursorShape 值	光标名称	Qt::CursorShape 值	光标名称
Qt::ArrowCursor	`left_ptr`	Qt::SizeVerCursor	`size_ver`
Qt::UpArrowCursor	`up_arrow`	Qt::SizeHorCursor	`size_hor`
Qt::CrossCursor	`cross`	Qt::SizeBDiagCursor	`size_bdiag`
Qt::IBeamCursor	`ibeam`	Qt::SizeFDiagCursor	`size_fdiag`
Qt::WaitCursor	`wait`	Qt::SizeAllCursor	`size_all`
Qt::BusyCursor	`left_ptr_watch`	Qt::SplitVCursor	`split_v`
Qt::ForbiddenCursor	`forbidden`	Qt::SplitHCursor	`split_h`
Qt::PointingHandCursor	`pointing_hand`	Qt::OpenHandCursor	`openhand`
Qt::WhatsThisCursor	`whats_this`	Qt::ClosedHandCursor	`closedhand`
Qt::DragMoveCursor	`dnd-move` 或 `move`	Qt::DragCopyCursor	`dnd-copy` 或 `copy`
Qt::DragLinkCursor	`dnd-link` 或 `link`

另请参阅 QWidget.

成员函数文档

QCursor::QCursor()

创建一个具有默认箭头形状的游标。

QCursor::QCursor(Qt::CursorShape 形状)

创建一个具有指定形状的游标。

有关形状列表，请参阅 Qt::CursorShape。

另请参阅 setShape().

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

构建一个自定义位图光标。

bitmap 和 mask 构成了位图。 hotX 和 hotY 定义了光标的热点。

如果 hotX 为负值，则将其设置为 bitmap().width()/2。如果 hotY 为负值，则将其设置为 bitmap().height()/2。

光标的位图 bitmap（B）和 mask（mask）位按照以下方式进行组合

B=1 和 M=1 表示黑色。
B=0 和 M=1 表示白色。
B=0 和 M=0 表示透明。
B=1 和 M=0 在 Windows 下给出异或结果，在其他所有平台上结果未定义。

使用全局 Qt 颜色 Qt::color0 在位图中绘制 0 像素，并使用 Qt::color1 绘制 1 像素。

有效的光标大小取决于显示硬件（或底层窗口系统）。我们建议使用 32 x 32 光标，因为所有平台都支持这个大小。一些平台还支持 16 x 16，48 x 48 和 64 x 64 光标。

另请参阅QBitmap::QBitmap() 和 QBitmap::setMask。

`[显式构造函数]` QCursor::QCursor(const QPixmap &pixmap, int hotX = -1, int hotY = -1)

构建一个自定义图标光标。

pixmap 是图像。通常给出一个掩码（使用 QPixmap::setMask 设置）。hotX 和 hotY 定义光标的焦点。

如果 hotX 为负值，则将其设置为 pixmap().width()/2。如果 hotY 为负值，则将其设置为 pixmap().height()/2。

另请参阅QPixmap::QPixmap() 和 QPixmap::setMask。

QCursor::QCursor(const QCursor &c)

构建光标 c 的副本。

`[无异常构造函数]` QCursor::QCursor(QCursor &&other)

移动构造函数从 other 构建光标。移动后，对 other 的唯一有效操作是析构和（移动和复制）赋值。调用任何其他成员函数对已移动实例的影响是未定义的。

`[无异常析构函数]` QCursor::~QCursor()

销毁光标。

QBitmap QCursor::bitmap() const

返回光标位图，如果是标准光标之一，则返回空位图。

QPoint QCursor::hotSpot() const

返回光标焦点，如果是标准光标之一，则返回 (0, 0)。

QBitmap QCursor::mask() const

返回光标位图掩码，如果是标准光标之一，则返回空位图。

QPixmap QCursor::pixmap() const

返回光标位图。只有当光标是位图光标时，此信息才有效。

`[静态]` QPoint QCursor::pos()

返回主屏幕光标（热区）在全局屏幕坐标中的位置。

您可以使用QWidget::mapFromGlobal()将其转换为窗口坐标。

注意： 此位置从窗口系统中查询。如果通过其他方式生成鼠标事件（例如，通过单元测试中的QWindowSystemInterface），则这些伪造的鼠标移动将不会反映在返回值中。

注意： 在没有窗口系统或有光标不可用的平台上，返回的位置基于通过QWindowSystemInterface生成的鼠标移动事件。

另请参阅：setPos()，QWidget::mapFromGlobal()，QWidget::mapToGlobal()和QGuiApplication::primaryScreen()。

`[静态]` QPoint QCursor::pos(const QScreen **screen*)

返回全局屏幕坐标中屏幕的光标（热区）位置。

您可以使用QWidget::mapFromGlobal()将其转换为窗口坐标。

另请参阅：setPos()，QWidget::mapFromGlobal()和QWidget::mapToGlobal()。

`[静态]` void QCursor::setPos(int x, int y)

将主屏幕的光标（热区）移动到全局屏幕位置（x，y）。

您可以使用QWidget::mapToGlobal()将窗口坐标转换为全局屏幕坐标。

另请参阅：pos()，QWidget::mapFromGlobal()，QWidget::mapToGlobal()和QGuiApplication::primaryScreen()。

`[静态]` void QCursor::setPos(QScreen **screen*, int x, int y)

将屏幕的光标（热区）移动到全局屏幕位置（x，y）。

您可以使用QWidget::mapToGlobal()将窗口坐标转换为全局屏幕坐标。

注意： 调用此函数将通过窗口系统改变光标位置。窗口系统通常会通过向应用程序窗口发送鼠标事件来做出响应。这意味着此函数应避免在单元测试和通过QWindowSystemInterface注入伪造鼠标事件的地方使用，因为窗口系统的鼠标状态（例如按钮状态）可能与应用程序生成的事件状态不匹配。

注意： 在没有窗口系统或有光标不可用的平台上，此函数可能无任何作用。

另请参阅：pos()，QWidget::mapFromGlobal()和QWidget::mapToGlobal()。

`[静态]` void QCursor::setPos(const QPoint &p)

这是一个重载函数。

将光标（热区）移动到全局屏幕位置点p。

`[静态]` void QCursor::setPos(QScreen **screen*, const QPoint &p)

这是一个重载函数。

将光标（热点）移动到全局屏幕上点 p 的位置。

void QCursor::setShape(Qt::CursorShape shape)

将光标设置为通过 shape 识别的形状。

关于光标形状的列表，请参阅 Qt::CursorShape。

另请参阅shape()。

Qt::CursorShape QCursor::shape() const

返回光标形状标识符。

另请参阅 setShape().

`[noexcept]` void QCursor::swap(QCursor &other)

与 other 光标交换。

QVariant QCursor::operator QVariant() const

将光标作为 QVariant 返回。

QCursor &QCursor::operator=(const QCursor &c)

将 c 分配给此光标并返回对光标(this cursor)的引用。

`[noexcept]` QCursor &QCursor::operator=(QCursor &&other)

将 other 搬运到此 QCursor 实例。

QCursor类

公共函数

静态公共成员