QCursor Class
La clase QCursor proporciona un cursor de ratón con una forma arbitraria. Más...
| Cabecera: | #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 heredados
- Miembros obsoletos
- QCursor es parte de Clases Implícitamente Compartidas.
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) |
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 que se asocian con widgets particulares y para obtener y establecer la posición del cursor del ratón.
Qt tiene una serie de formas de cursor estándar, pero también puedes hacer formas de cursor personalizadas basadas en un QBitmap, una máscara y un hotspot.
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 la forma del cursor utilice QCursor::setShape() o utilice el constructor QCursor que toma la forma como argumento, o puede utilizar uno de los cursores predefinidos definidos en el enum Qt::CursorShape.
Si quieres crear un cursor con tu propio bitmap, usa el constructor QCursor que toma un bitmap y una máscara o el constructor que toma un pixmap 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 QGuiApplication, pero no es útil excepto como marcador de posición para un QCursor real creado después de QGuiApplication. Intentar usar un QCursor que fue creado antes de QGuiApplication resultará en un fallo.
Nota para usuarios de X11
En X11, Qt soporta la librería Xcursor, que permite temas de iconos a todo color. La siguiente tabla muestra el nombre del cursor utilizado para cada valor de Qt::CursorShape. Si no se puede encontrar un cursor utilizando el nombre que se muestra a continuación, se utilizará en su lugar un cursor X11 estándar. Nota: X11 no proporciona cursores apropiados para todos los valores posibles de Qt::CursorShape. Es posible que algunos cursores se tomen del tema Xcursor, mientras que otros utilizarán 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 las funciones miembro
QCursor::QCursor()
Construye un cursor con la forma de flecha por defecto.
QCursor::QCursor(Qt::CursorShape shape)
Construye un cursor con la forma especificada shape.
Véase Qt::CursorShape para una lista de formas.
Véase también setShape().
[explicit] QCursor::QCursor(const QPixmap &pixmap, int hotX = -1, int hotY = -1)
Construye un cursor pixmap personalizado.
pixmap es la imagen. Es habitual darle una máscara (que se define con QPixmap::setMask()). hotX y hotY definen el punto caliente 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). Se recomienda 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 QPixmap::QPixmap() y QPixmap::setMask().
QCursor::QCursor(const QBitmap &bitmap, const QBitmap &mask, int hotX = -1, int hotY = -1)
Construye un cursor de mapa de bits personalizado.
bitmap y mask forman el mapa de bits. hotX y hotY definen el punto caliente del cursor.
Si hotX es negativo, se establece en bitmap().width()/2. Si hotY es negativo, se establece en bitmap().height()/2.
Los bits del cursor bitmap (B) y mask (M) se combinan así:
- B=1 y M=1 da negro.
- B=0 y M=1 da blanco.
- B=0 y M=0 da transparente.
- B=1 y M=0 da un resultado XOR bajo Windows, resultados indefinidos en el resto de plataformas.
Utilice el color global de Qt Qt::color0 para dibujar 0 píxeles y Qt::color1 para dibujar 1 píxel 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 está soportado en 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)
Construye una copia del cursor c.
[noexcept] QCursor::QCursor(QCursor &&other)
Mover-construye un cursor a partir de other. Después de ser movido desde, las únicas operaciones válidas en other son la destrucción y la asignación (mover y copiar). Los efectos de llamar a cualquier otra función miembro en una instancia movida desde son indefinidos.
[noexcept] QCursor::~QCursor()
Destruye el cursor.
QBitmap QCursor::bitmap() const
Devuelve el mapa de bits del cursor, o un mapa de bits nulo si se trata de uno de los cursores estándar.
QPoint QCursor::hotSpot() const
Devuelve el punto caliente del cursor, o (0, 0) si es 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 pixmap del cursor. Esto sólo es válido si el cursor es un cursor pixmap.
[static] QPoint QCursor::pos()
Devuelve la posición del cursor (punto caliente) de la pantalla primaria en coordenadas globales de pantalla.
Puede llamar a QWidget::mapFromGlobal() para traducirla a coordenadas del widget.
Nota: La posición se consulta al sistema de ventanas. Si se generan eventos de ratón por otros medios (por ejemplo, a través de QWindowSystemInterface en una prueba unitaria), esos movimientos falsos del ratón no se reflejarán en el valor devuelto.
Nota: En plataformas donde no hay sistema de ventanas o los cursores no están 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 caliente) de screen en coordenadas globales de pantalla.
Puede llamar a QWidget::mapFromGlobal() para traducirla 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 caliente) de la pantalla primaria a la posición de pantalla global (x, y).
Puedes llamar a QWidget::mapToGlobal() para traducir las coordenadas del widget a coordenadas globales de pantalla.
Ver también pos(), QWidget::mapFromGlobal(), QWidget::mapToGlobal(), y QGuiApplication::primaryScreen().
[static] void QCursor::setPos(QScreen *screen, int x, int y)
Mueve el cursor (punto caliente) de screen a la posición de pantalla global (x, y).
Puede llamar a QWidget::mapToGlobal() para traducir las coordenadas del widget a coordenadas globales de pantalla.
Nota: Llamar a esta función resulta en cambiar la posición del cursor a través del sistema de ventanas. El sistema de ventanas responderá normalmente enviando eventos de ratón a la ventana de la aplicación. Esto significa que el uso de esta función debe evitarse en pruebas unitarias y en cualquier lugar donde se inyecten eventos de ratón falsos a través de QWindowSystemInterface porque el estado del ratón del sistema de ventanas (con respecto a los botones, por ejemplo) puede no coincidir con el estado en los eventos generados por la aplicación.
Nota: En plataformas donde no hay sistema de ventanas o los cursores no están disponibles, esta función puede no hacer nada.
Véase también pos(), QWidget::mapFromGlobal(), y QWidget::mapToGlobal().
[static] void QCursor::setPos(const QPoint &p)
Mueve el cursor (punto caliente) a la posición global de la pantalla en el punto p.
Se trata de una función sobrecargada.
[static] void QCursor::setPos(QScreen *screen, const QPoint &p)
Mueve el cursor (punto caliente) a la posición global de la pantalla de screen en el punto p.
Se trata de una función sobrecargada.
void QCursor::setShape(Qt::CursorShape shape)
Establece el cursor en la forma identificada por shape.
Véase Qt::CursorShape para 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 QVariant.
[noexcept] QCursor &QCursor::operator=(QCursor &&other)
Mover-asigna other a esta instancia QCursor.
QCursor &QCursor::operator=(const QCursor &c)
Asigna c a este cursor y devuelve una referencia a este cursor.
No miembros relacionados
[noexcept] bool operator!=(const QCursor &lhs, const QCursor &rhs)
Operador de desigualdad. Devuelve el equivalente de !(lhs == rhs).
Véase también operator==(const QCursor &lhs, const QCursor &rhs).
QDataStream &operator<<(QDataStream &stream, const QCursor &cursor)
Escribe cursor en stream.
Véase también Serializar tipos de datos 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 los mismos bitmap() y mask().
Nota: Cuando se comparan cursores de mapas de bits, esta función sólo compara los cache keys de los mapas de bits, no cada píxel.
Ver también operator!=(const QCursor &lhs, const QCursor &rhs).
QDataStream &operator>>(QDataStream &stream, QCursor &cursor)
Lee el cursor del stream.
Véase también Serializar tipos de datos 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.
