QPen Class
La clase QPen define cómo debe dibujar un « QPainter » las líneas y los contornos de las figuras. Más...
| Encabezado: | #include <QPen> |
| 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
- QPen forma parte de las clases de pintura y de las clases compartidas implícitamente.
Funciones públicas
| QPen() | |
| QPen(Qt::PenStyle style) | |
| QPen(const QColor &color) | |
| QPen(const QBrush &brush, qreal width, Qt::PenStyle style = Qt::SolidLine, Qt::PenCapStyle cap = Qt::SquareCap, Qt::PenJoinStyle join = Qt::BevelJoin) | |
| QPen(const QPen &pen) | |
| QPen(QPen &&pen) | |
| ~QPen() | |
| QBrush | brush() const |
| Qt::PenCapStyle | capStyle() const |
| QColor | color() const |
| qreal | dashOffset() const |
| QList<qreal> | dashPattern() const |
| bool | isCosmetic() const |
| bool | isSolid() const |
| Qt::PenJoinStyle | joinStyle() const |
| qreal | miterLimit() const |
| void | setBrush(const QBrush &brush) |
| void | setCapStyle(Qt::PenCapStyle style) |
| void | setColor(const QColor &color) |
| void | setCosmetic(bool cosmetic) |
| void | setDashOffset(qreal offset) |
| void | setDashPattern(const QList<qreal> &pattern) |
| void | setJoinStyle(Qt::PenJoinStyle style) |
| void | setMiterLimit(qreal limit) |
| void | setStyle(Qt::PenStyle style) |
| void | setWidth(int width) |
| void | setWidthF(qreal width) |
| Qt::PenStyle | style() const |
| void | swap(QPen &other) |
| int | width() const |
| qreal | widthF() const |
| operator QVariant() const | |
| bool | operator!=(const QPen &pen) const |
| QPen & | operator=(QPen &&other) |
| QPen & | operator=(const QPen &pen) |
(since 6.9) QPen & | operator=(QColor color) |
(since 6.9) QPen & | operator=(Qt::PenStyle style) |
| bool | operator==(const QPen &pen) const |
Elementos no miembros relacionados
| QDataStream & | operator<<(QDataStream &stream, const QPen &pen) |
| QDataStream & | operator>>(QDataStream &stream, QPen &pen) |
Descripción detallada
Un lápiz tiene las funciones « style()», « width()», « brush()», « capStyle()» y « joinStyle()».
El estilo de pluma define el tipo de línea. El pincel se utiliza para rellenar los trazos generados con la pluma. Utiliza la clase QBrush para especificar los estilos de relleno. El estilo de remate determina los remates de las líneas que se pueden dibujar utilizando QPainter, mientras que el estilo de unión describe cómo se dibujan las uniones entre dos líneas. El ancho del lápiz se puede especificar tanto con precisión entera (width()) como de coma flotante (widthF()). Un ancho de línea igual a cero indica un lápiz decorativo. Esto significa que el ancho del lápiz siempre se dibuja con un ancho de un píxel, independientemente del valor de « transformation » establecido en el pintor.
Los distintos ajustes se pueden modificar fácilmente utilizando las funciones correspondientes setStyle(), setWidth(), setBrush(), setCapStyle() y setJoinStyle() (tenga en cuenta que hay que restablecer el lápiz del pintor al modificar las propiedades del mismo).
Por ejemplo:
QPainter painter(this);
QPen pen(Qt::green, 3, Qt::DashDotLine, Qt::RoundCap, Qt::RoundJoin);
painter.setPen(pen);lo cual equivale a
QPainter painter(this);
QPen pen; // creates a default pen
pen.setStyle(Qt::DashDotLine);
pen.setWidth(3);
pen.setBrush(Qt::green);
pen.setCapStyle(Qt::RoundCap);
pen.setJoinStyle(Qt::RoundJoin);
painter.setPen(pen);El lápiz predeterminado es un pincel negro sólido con un ancho de 1, estilo de punta cuadrada (Qt::SquareCap) y estilo de unión biselada (Qt::BevelJoin).
Además, QPen proporciona las funciones de conveniencia color() y setColor() para extraer y establecer el color del pincel del trazo, respectivamente. Los trazos también se pueden comparar y transmitir.
Para obtener más información sobre la pintura en general, consulta la documentación del sistema de pintura.
Estilo de lápiz
Qt proporciona varios estilos integrados representados por la enumeración Qt::PenStyle:
Basta con utilizar la función ` setStyle()` para convertir el estilo del lápiz a cualquiera de los estilos integrados, excepto el estilo ` Qt::CustomDashLine `, al que volveremos en breve. Al establecer el estilo en ` Qt::NoPen `, se indica al pintor que no dibuje líneas ni contornos. El estilo predeterminado del lápiz es ` Qt::SolidLine`.
Desde Qt 4.1 también es posible especificar un patrón de trazos personalizado mediante la función setDashPattern(), que convierte implícitamente el estilo del lápiz a Qt::CustomDashLine. El argumento «pattern», un QList, debe especificarse como un número par de entradas de qreal, donde las entradas 1, 3, 5... son los trazos y 2, 4, 6… son los espacios. Por ejemplo, el patrón personalizado que se muestra arriba se crea utilizando el siguiente código:
QPen pen;
QList<qreal> dashes;
qreal space = 4;
dashes << 1 << space << 3 << space << 9 << space
<< 27 << space << 9 << space;
pen.setDashPattern(dashes);Ten en cuenta que el patrón de guiones se especifica en unidades del ancho de los trazos; por ejemplo, un guión de longitud 5 y ancho 10 mide 50 píxeles de largo.
El patrón de trazos establecido actualmente se puede recuperar mediante la función dashPattern(). Utiliza la función isSolid() para determinar si el trazo tiene un relleno sólido o no.
Estilo de remate
El estilo de remate define cómo se dibujan los extremos de las líneas mediante QPainter. El estilo de remate solo se aplica a líneas anchas, es decir, cuando el ancho es 1 o superior. La enumeración Qt::PenCapStyle ofrece los siguientes estilos:
El estilo « Qt::SquareCap » consiste en un extremo de línea cuadrado que cubre el punto final y se extiende más allá de este en la mitad del ancho de la línea. El estilo « Qt::FlatCap » consiste en un extremo de línea cuadrado que no cubre el punto final de la línea. Y el estilo « Qt::RoundCap » consiste en un extremo de línea redondeado que cubre el punto final.
El valor predeterminado es « Qt::SquareCap ».
Que se dibujen o no los puntos finales cuando el ancho del trazo es 0 o 1 depende del estilo de remate. Si se utiliza « Qt::SquareCap » o « Qt::RoundCap », se dibujan; si se utiliza « Qt::FlatCap », no se dibujan.
Estilo de unión
El estilo de unión define cómo se dibujan las uniones entre dos líneas conectadas utilizando QPainter. El estilo de unión solo se aplica a líneas anchas, es decir, cuando el ancho es 1 o superior. La enumeración Qt::PenJoinStyle ofrece los siguientes estilos:
El estilo « Qt::BevelJoin » rellena el hueco triangular entre las dos líneas. El estilo « Qt::MiterJoin » prolonga las líneas para que se unan en ángulo. Y el estilo « Qt::RoundJoin » rellena un arco circular entre las dos líneas.
El valor predeterminado es « Qt::BevelJoin ».

Cuando se aplica el estilo « Qt::MiterJoin », es posible utilizar la función « setMiterLimit()» para especificar hasta qué distancia puede extenderse la unión en inglete desde el punto de unión. La función « miterLimit()» se utiliza para reducir los artefactos entre las uniones de líneas cuando estas son casi paralelas.
El valor « miterLimit » () debe especificarse en unidades equivalentes al ancho del trazo; por ejemplo, un límite de inglete de 5 con un ancho de 10 equivale a 50 píxeles de longitud. El límite de inglete predeterminado es 2, es decir, el doble del ancho del trazo en píxeles.
![]() | El ejemplo de trazo de trazado El ejemplo «Trazado de trazados» muestra los patrones de trazo integrados en Qt y explica cómo se pueden utilizar patrones personalizados para ampliar la gama de patrones disponibles. |
Véase también « QPainter» , « QBrush », «Ejemplo de trazo de trazado» y «Ejemplo de garabato».
Documentación de las funciones miembro
QPen::QPen()
Crea un trazo predeterminado de línea continua negra con un ancho de 1.
QPen::QPen(Qt::PenStyle style)
Crea un bolígrafo negro con un ancho de 1 y el valor dado style.
Véase también setStyle().
QPen::QPen(const QColor &color)
Crea un trazo de línea continua con un ancho de 1 y el valor dado de « color ».
Véase también setBrush() y setColor().
QPen::QPen(const QBrush &brush, qreal width, Qt::PenStyle style = Qt::SolidLine, Qt::PenCapStyle cap = Qt::SquareCap, Qt::PenJoinStyle join = Qt::BevelJoin)
Crea un lápiz con los valores especificados para « brush », « width », «pen style », « cap » y « join ».
Véanse también setBrush(), setWidth(), setStyle(), setCapStyle() y setJoinStyle().
[noexcept] QPen::QPen(const QPen &pen)
Crea un «pen» que es una copia del « pen » especificado.
[constexpr noexcept default] QPen::QPen(QPen &&pen)
Crea un lápiz que se ha trasladado desde el pen indicado.
El lápiz del que se ha realizado el desplazamiento solo puede asignarse, copiarse o destruirse. Cualquier otra operación (previa a la asignación) da lugar a un comportamiento indefinido.
[noexcept] QPen::~QPen()
Destruye el bolígrafo.
QBrush QPen::brush() const
Devuelve el pincel utilizado para rellenar los trazos generados con este lápiz.
Véase también setBrush().
Qt::PenCapStyle QPen::capStyle() const
Devuelve el estilo del capuchón del bolígrafo.
Véase también setCapStyle() y Cap Style.
QColor QPen::color() const
Devuelve el color del pincel de este rotulador.
Véase también brush() y setColor().
qreal QPen::dashOffset() const
Devuelve el desplazamiento del guión para el lápiz.
Véase también setDashOffset().
QList<qreal> QPen::dashPattern() const
Devuelve el patrón de guiones de este bolígrafo.
Véase también setDashPattern(), style() y isSolid().
bool QPen::isCosmetic() const
Devuelve ` true ` si el lápiz es «cosmético»; en caso contrario, devuelve ` false`.
Los rotuladores cosméticos se utilizan para dibujar trazos que tienen un ancho constante, independientemente de las transformaciones que se apliquen al QPainter con el que se utilicen. Dibujar una forma con un rotulador cosmético garantiza que su contorno tenga el mismo grosor con diferentes factores de escala.
Un lápiz de ancho cero es cosmético por defecto.
Véanse también setCosmetic() y widthF().
bool QPen::isSolid() const
Devuelve « true » si el lápiz tiene un relleno sólido; en caso contrario, devuelve «false».
Véase también style() y dashPattern().
Qt::PenJoinStyle QPen::joinStyle() const
Devuelve el estilo de unión del trazo.
Véase también setJoinStyle() y Join Style.
qreal QPen::miterLimit() const
Devuelve el límite de inglete del trazo. El límite de inglete solo es relevante cuando el estilo de unión está configurado como « Qt::MiterJoin ».
Véanse también « setMiterLimit()» y « Join Style ».
void QPen::setBrush(const QBrush &brush)
Establece el pincel utilizado para rellenar los trazos generados con este rotulador en el valor indicado: brush.
Véase también brush() y setColor().
void QPen::setCapStyle(Qt::PenCapStyle style)
Establece el estilo de la tapa del bolígrafo en el valor indicado: style. El valor por defecto es Qt::SquareCap.
Véase también capStyle() y Cap Style.
void QPen::setColor(const QColor &color)
Establece el color del pincel de este lápiz según la dirección de color especificada en color.
Véase también setBrush() y color().
void QPen::setCosmetic(bool cosmetic)
Establece este lápiz como «cosmético» o «no cosmético», en función del valor de ` cosmetic`.
Véase también isCosmetic().
void QPen::setDashOffset(qreal offset)
Establece el desplazamiento del guion (el punto de inicio del patrón de guiones) para este lápiz según el valor especificado en « offset ». El desplazamiento se mide en las unidades utilizadas para especificar el patrón de guiones.
![]() | Por ejemplo, un patrón en el que cada trazo tiene una longitud de cuatro unidades, seguido de un espacio de dos unidades, comenzará con el trazo cuando se dibuje como una línea. Sin embargo, si el desplazamiento del guion se establece en 4,0, cualquier línea que se dibuje comenzará por el espacio en blanco. Los valores de desplazamiento de hasta 4,0 harán que se dibuje primero parte del trazo, y los valores de desplazamiento entre 4,0 y 6,0 harán que la línea comience por parte del espacio en blanco. |
Nota: Esto convierte implícitamente el estilo del lápiz en « Qt::CustomDashLine ».
Véase también dashOffset().
void QPen::setDashPattern(const QList<qreal> &pattern)
Establece el patrón de guiones de este lápiz en el valor indicado pattern. Esto convierte implícitamente el estilo del lápiz a Qt::CustomDashLine.
El patrón debe especificarse como un número par de entradas positivas, donde las entradas 1, 3, 5... son los guiones y las 2, 4, 6... son los espacios. Por ejemplo:
![]() |
El patrón de rayas se especifica en unidades del ancho de los rotuladores; por ejemplo, una raya de longitud 5 y ancho 10 mide 50 píxeles de largo. Ten en cuenta que un rotulador con ancho cero equivale a un rotulador cosmético con un ancho de 1 píxel.
Cada guión también está sujeto a los estilos de remate, por lo que un guión de longitud 1 con el remate cuadrado se extenderá 0,5 píxeles en cada dirección, lo que da como resultado un ancho total de 2.
Ten en cuenta que el estilo de remate predeterminado es Qt::SquareCap, lo que significa que un remate cuadrado cubre el punto final y se extiende más allá de él la mitad del ancho de la línea.
Véase también setStyle(), dashPattern(), setCapStyle() y setCosmetic().
void QPen::setJoinStyle(Qt::PenJoinStyle style)
Establece el estilo de unión del trazo en el valor especificado style. El valor por defecto es Qt::BevelJoin.
Véase también joinStyle() y Join Style.
void QPen::setMiterLimit(qreal limit)
Establece el límite de inglete de este trazo en el valor indicado limit.

El límite de inglete describe hasta qué punto puede extenderse una unión en inglete desde el punto de unión. Se utiliza para reducir los artefactos entre uniones de líneas cuando estas son casi paralelas.
Este valor solo surte efecto cuando el estilo del trazo está configurado como « Qt::MiterJoin ». El valor se especifica en unidades equivalentes al ancho del trazo; por ejemplo, un límite de inglete de 5 con un ancho de 10 tiene una longitud de 50 píxeles. El límite de inglete predeterminado es 2, es decir, el doble del ancho del trazo en píxeles.
Véanse también « miterLimit()», « setJoinStyle()» y « Join Style ».
void QPen::setStyle(Qt::PenStyle style)
Establece el estilo del trazo según el valor especificado en « style ».
Consulta la documentación de Qt::PenStyle para ver una lista de los estilos disponibles. Desde Qt 4.1 también es posible especificar un patrón de rayas personalizado mediante la función setDashPattern(), que convierte implícitamente el estilo del trazo a Qt::CustomDashLine.
Nota: Esta función restablece el desplazamiento del guion a cero.
Véase también style() y Pen Style.
void QPen::setWidth(int width)
Establece el ancho del trazo en el valor « width » especificado en píxeles, con precisión entera.
Un ancho de línea igual a cero indica un lápiz decorativo. Esto significa que el ancho del lápiz siempre se dibuja con un ancho de un píxel, independientemente del valor de « transformation » establecido en el «painter».
No se admite establecer un ancho de trazo con un valor negativo.
Véase también setWidthF() y width().
void QPen::setWidthF(qreal width)
Establece el ancho del trazo en el valor dado width en píxeles, con precisión de punto flotante.
Un ancho de línea igual a cero indica un lápiz decorativo. Esto significa que el ancho del lápiz siempre se dibuja con un ancho de un píxel, independientemente de la configuración de « transformation » del pintor.
No se admite establecer un ancho de trazo con un valor negativo.
Véanse también « setWidth()» y « widthF()».
Qt::PenStyle QPen::style() const
Devuelve el estilo del lápiz.
Véase también setStyle() y Pen Style.
[noexcept] void QPen::swap(QPen &other)
Cambia este bolígrafo por uno de other. Esta operación es muy rápida y nunca falla.
int QPen::width() const
Devuelve el ancho del trazo con precisión entera.
Véase también setWidth() y widthF().
qreal QPen::widthF() const
Devuelve el ancho del trazo con precisión de punto flotante.
Véase también setWidthF() y width().
QPen::operator QVariant() const
Devuelve el lápiz como un objeto ` QVariant`.
bool QPen::operator!=(const QPen &pen) const
Devuelve « true » si el rotulador es diferente del indicado en « pen »; en caso contrario, devuelve «false». Dos rotuladores son diferentes si tienen estilos, grosores o colores distintos.
Véase también operator==().
[noexcept] QPen &QPen::operator=(QPen &&other)
Asigna « other » a esta instancia de « QPen ». »
[noexcept] QPen &QPen::operator=(const QPen &pen)
Asigna el ` pen ` indicado a este lápiz y devuelve una referencia a este lápiz.
[since 6.9] QPen &QPen::operator=(QColor color)
Convierte este trazo en un trazo sólido con el color indicado y los estilos predeterminados de capuchón y unión, y devuelve una referencia a este trazo.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.9.
[since 6.9] QPen &QPen::operator=(Qt::PenStyle style)
Convierte este trazo en un trazo negro sólido con los estilos predeterminados de capuchón y unión, y devuelve una referencia a este trazo.
Esta es una función sobrecargada.
Esta función se introdujo en Qt 6.9.
bool QPen::operator==(const QPen &pen) const
Devuelve ` true ` si el lápiz es igual al ` pen` indicado; en caso contrario, devuelve `false`. Dos lápices son iguales si tienen los mismos estilos, anchuras y colores.
Véase también operator!=().
Elementos no miembros relacionados
QDataStream &operator<<(QDataStream &stream, const QPen &pen)
Escribe el objeto ` pen ` especificado en el objeto ` stream ` especificado y devuelve una referencia al objeto ` stream`.
Véase también Serialización detipos de datos de Qt.
QDataStream &operator>>(QDataStream &stream, QPen &pen)
Lee un «pen» desde el « stream » indicado en el « pen » indicado y devuelve una referencia al « 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.













