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 |
- Lista de todos los miembros, incluidos los miembros heredados
- Miembros obsoletos
- QCursor forma parte de las clases compartidas implícitamente.
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) |
Elementos no miembros relacionados
| 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.
| Forma | Qt::CursorShape Valor | Nombre del cursor | Forma | Qt::CursorShape Valor | Nombre del cursor |
|---|---|---|---|---|---|
![]() | 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 o move | Qt::DragCopyCursor | dnd-copy o copy | ||
| Qt::DragLinkCursor | dnd-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.

















