En esta página

QCursor Class

La clase QCursor permite crear un cursor de ratón con una forma arbitraria. Más información...

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

Funciones públicas

QCursor()
QCursor(Qt::CursorShape shape)
QCursor(const QPixmap &pixmap, int hotX = -1, int hotY = -1)
QCursor(const QBitmap &bitmap, const QBitmap &mask, 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)
operator QVariant() const
QCursor &operator=(QCursor &&other)
QCursor &operator=(const QCursor &c)

Miembros públicos estáticos

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)

Descripción detallada

Esta clase se utiliza principalmente para crear cursores de ratón asociados a widgets concretos, así como para obtener y establecer la posición del cursor del ratón.

Qt dispone de varias formas de cursor estándar, pero también se pueden crear formas de cursor personalizadas basadas en un ` QBitmap`, una máscara y un punto activo.

Para asociar un cursor a un widget, utiliza ` QWidget::setCursor()`. Para asociar un cursor a todos los widgets (normalmente durante un breve periodo de tiempo), utiliza ` QGuiApplication::setOverrideCursor()`.

Para establecer una forma de cursor, utiliza ` QCursor::setShape()` o el constructor de `QCursor`, que toma la forma como argumento; también puedes utilizar uno de los cursores predefinidos en la enumeración ` Qt::CursorShape `.

Si desea crear un cursor con su propio mapa de bits, utilice el constructor de QCursor que toma un mapa de bits y una máscara, o bien el constructor que toma un mapa de píxeles como argumentos.

Para establecer u obtener la posición del cursor del ratón, utiliza los métodos estáticos QCursor::pos() y QCursor::setPos().

Nota: Es posible crear un `QCursor` antes de llamar a ` QGuiApplication`, pero no resulta útil salvo como marcador de posición para un `QCursor` real creado tras llamar a ` QGuiApplication`. Intentar utilizar un `QCursor` creado antes de llamar a ` QGuiApplication ` provocará un fallo del sistema.

Nota para usuarios de X11

En X11, Qt es compatible con la biblioteca Xcursor, que permite utilizar temas de iconos a todo color. La tabla siguiente muestra el nombre del cursor utilizado para cada valor de ` Qt::CursorShape `. Si no se encuentra un cursor con el nombre que se indica a continuación, se utilizará en su lugar un cursor estándar de X11. Nota: X11 no proporciona cursores adecuados para todos los valores posibles de ` Qt::CursorShape `. Es posible que algunos cursores se tomen del tema Xcursor, mientras que otros utilicen un cursor de mapa de bits interno.

FormaQt::CursorShape ValorNombre del cursorFormaQt::CursorShape ValorNombre del cursor
Cursor de flechaQt::ArrowCursorleft_ptrCursor de cambio de tamaño verticalQt::SizeVerCursorsize_ver
Cursor de flecha hacia arribaQt::UpArrowCursorup_arrowCursor de cambio de tamaño horizontalQt::SizeHorCursorsize_hor
Cursor en forma de cruzQt::CrossCursorcrossCursor de cambio de tamaño diagonalQt::SizeBDiagCursorsize_bdiag
Cursor en forma de viga en IQt::IBeamCursoribeamCursor de redimensionamiento diagonalQt::SizeFDiagCursorsize_fdiag
Cursor de esperaQt::WaitCursorwaitMover el cursorQt::SizeAllCursorsize_all
Cursor de actividadQt::BusyCursorleft_ptr_watchCursor con división verticalQt::SplitVCursorsplit_v
Cursor prohibidoQt::ForbiddenCursorforbiddenCursor de división horizontalQt::SplitHCursorsplit_h
Cursor en forma de mano que señalaQt::PointingHandCursorpointing_handCursor de mano abiertaQt::OpenHandCursoropenhand
¿Qué es este cursor?Qt::WhatsThisCursorwhats_thisCursor de mano cerradaQt::ClosedHandCursorclosedhand
Qt::DragMoveCursordnd-move o moveQt::DragCopyCursordnd-copy o copy
Qt::DragLinkCursordnd-link o link

Véase también QWidget.

Documentación de funciones de miembro

QCursor::QCursor()

Crea un cursor con la forma de flecha predeterminada.

QCursor::QCursor(Qt::CursorShape shape)

Crea un cursor con el « shape » especificado.

Consulta Qt::CursorShape para ver una lista de formas.

Véase también setShape().

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

Crea un cursor de mapa de píxeles personalizado.

pixmap es la imagen. Lo habitual es asignarle una máscara (que se establece mediante ` QPixmap::setMask()`). ` hotX ` y ` hotY ` definen la zona activa del cursor.

Si hotX es negativo, se establece en pixmap().width()/2. Si hotY es negativo, se establece en pixmap().height()/2.

Los tamaños de cursor válidos dependen del hardware de visualización (o del sistema de ventanas subyacente). Recomendamos utilizar cursores de 32 x 32, ya que este tamaño es compatible con todas las plataformas. Algunas plataformas también admiten cursores de 16 x 16, 48 x 48 y 64 x 64.

Véanse también QPixmap::QPixmap() y QPixmap::setMask().

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

Crea un cursor de mapa de bits personalizado.

bitmap y ` mask ` conforman el mapa de bits. ` hotX ` y ` hotY ` definen el área activa del cursor.

Si hotX es negativo, se establece en bitmap().width()/2. Si hotY es negativo, se establece en bitmap().height()/2.

Los bits « bitmap » (B) y « mask » (M) del cursor se combinan de la siguiente manera:

  • B=1 y M=1 dan negro.
  • B=0 y M=1 da blanco.
  • B=0 y M=0 dan como resultado transparente.
  • B=1 y M=0 da un resultado XOR en Windows; en el resto de plataformas, el resultado es indefinido.

Utiliza el color global de Qt Qt::color0 para dibujar píxeles de 0 y Qt::color1 para dibujar píxeles de 1 en los mapas de bits.

Los tamaños de cursor válidos dependen del hardware de visualización (o del sistema de ventanas subyacente). Recomendamos utilizar cursores de 32 x 32, ya que este tamaño es compatible con todas las plataformas. Algunas plataformas también admiten cursores de 16 x 16, 48 x 48 y 64 x 64.

Véase también QBitmap::QBitmap() y QBitmap::setMask().

QCursor::QCursor(const QCursor &c)

Crea una copia del cursor « c ».

[noexcept] QCursor::QCursor(QCursor &&other)

Crea un cursor a partir de ` other`. Una vez que se ha realizado el traslado, las únicas operaciones válidas sobre ` other ` son la destrucción y la asignación (tanto por traslado como por copia). Los efectos de llamar a cualquier otra función miembro sobre una instancia de la que se ha realizado el traslado son indefinidos.

[noexcept] QCursor::~QCursor()

Elimina el cursor.

QBitmap QCursor::bitmap() const

Devuelve el mapa de bits del cursor o, si se trata de uno de los cursores estándar, un mapa de bits nulo.

QPoint QCursor::hotSpot() const

Devuelve la posición del cursor o (0, 0) si se trata de uno de los cursores estándar.

QBitmap QCursor::mask() const

Devuelve la máscara de mapa de bits del cursor o un mapa de bits nulo si se trata de uno de los cursores estándar.

QPixmap QCursor::pixmap() const

Devuelve el mapa de píxeles del cursor. Esto solo es válido si el cursor es un cursor de mapa de píxeles.

[static] QPoint QCursor::pos()

Devuelve la posición del cursor (punto activo) de la pantalla principal en coordenadas globales de pantalla.

Puedes llamar a QWidget::mapFromGlobal() para traducirla a coordenadas de widget.

Nota: La posición se obtiene del sistema de ventanas. Si los eventos del ratón se generan por otros medios (por ejemplo, a través de `QWindowSystemInterface` en una prueba unitaria), esos movimientos ficticios del ratón no se reflejarán en el valor devuelto.

Nota: En plataformas en las que no existe un sistema de ventanas o no hay cursores disponibles, la posición devuelta se basa en los eventos de movimiento del ratón generados a través de `QWindowSystemInterface`.

Véase también setPos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal() y QGuiApplication::primaryScreen().

[static] QPoint QCursor::pos(const QScreen *screen)

Devuelve la posición del cursor (punto activo) del screen en coordenadas globales de pantalla.

Puedes llamar a ` QWidget::mapFromGlobal()` para convertirla a coordenadas del widget.

Véase también ` setPos()`, ` QWidget::mapFromGlobal()` y ` QWidget::mapToGlobal()`.

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

Mueve el cursor (punto activo) de la pantalla principal a la posición global de la pantalla (x, y).

Puedes llamar a QWidget::mapToGlobal() para convertir las coordenadas de los widgets a coordenadas globales de pantalla.

Véase también pos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal() y QGuiApplication::primaryScreen().

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

Mueve el cursor (punto activo) del screen a la posición global de la pantalla (x, y).

Puedes llamar a ` QWidget::mapToGlobal()` para convertir las coordenadas del widget a coordenadas globales de pantalla.

Nota: Al llamar a esta función se modifica la posición del cursor a través del sistema de ventanas. Normalmente, el sistema de ventanas responderá enviando eventos de ratón a la ventana de la aplicación. Esto significa que se debe evitar el uso de esta función en pruebas unitarias y en cualquier lugar donde se inyecten eventos de ratón falsos a través de `QWindowSystemInterface`, ya que el estado del ratón del sistema de ventanas (por ejemplo, en lo que respecta a los botones) puede no coincidir con el estado de los eventos generados por la aplicación.

Nota: En plataformas en las que no existe un sistema de ventanas o en las que no hay cursores disponibles, es posible que esta función no realice ninguna acción.

Véase también pos(), QWidget::mapFromGlobal() y QWidget::mapToGlobal().

[static] void QCursor::setPos(const QPoint &p)

Mueve el cursor (punto activo) a la posición global en pantalla en el punto p.

Esta es una función sobrecargada.

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

Mueve el cursor (punto activo) a la posición global en pantalla del objeto « screen » en el punto p.

Esta es una función sobrecargada.

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

Establece el cursor con la forma identificada por shape.

Consulta Qt::CursorShape para ver la lista de formas de cursor.

Véase también shape().

Qt::CursorShape QCursor::shape() const

Devuelve el identificador de la forma del cursor.

Véase también ` setShape()`.

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

Cambia este cursor por other. Esta operación es muy rápida y nunca falla.

QCursor::operator QVariant() const

Devuelve el cursor como un objeto ` QVariant`.

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

Asigna « other » a esta instancia de « QCursor ». .

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

Asigna « c » a este cursor y devuelve una referencia a este cursor.

Elementos relacionados no miembros

[noexcept] bool operator!=(const QCursor &lhs, const QCursor &rhs)

Operador de desigualdad. Devuelve el equivalente a !(lhs == rhs).

Véase también operator==(const QCursor &lhs, const QCursor &rhs).

QDataStream &operator<<(QDataStream &stream, const QCursor &cursor)

Escribe el objeto ` cursor ` en el ` stream`.

Véase también «Serialización detipos de datos de Qt».

[noexcept] bool operator==(const QCursor &lhs, const QCursor &rhs)

Operador de igualdad. Devuelve ` true ` si ` lhs ` y ` rhs ` tienen el mismo ` shape()` y, en el caso de ` bitmap cursors`, el mismo ` hotSpot()` y, o bien el mismo ` pixmap()`, o bien el mismo ` bitmap()` y ` mask()`.

Nota: Al comparar cursores de mapa de bits, esta función solo compara el cache keys de los mapas de bits, no cada píxel.

Véase también operator!=(const QCursor &lhs, const QCursor &rhs).

QDataStream &operator>>(QDataStream &stream, QCursor &cursor)

Lee el documento « cursor » disponible en stream.

Véase también «Serialización detipos de datos de Qt».

© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.