En esta página

QFontMetrics Class

La clase QFontMetrics proporciona información sobre las métricas de las fuentes. Más información...

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

Nota: Todas las funciones de esta clase son reentrantes.

Funciones públicas

QFontMetrics(const QFont &font)
QFontMetrics(const QFont &font, const QPaintDevice *paintdevice)
QFontMetrics(const QFontMetrics &fm)
QFontMetrics(QFontMetrics &&)
~QFontMetrics()
int ascent() const
int averageCharWidth() const
QRect boundingRect(QChar ch) const
QRect boundingRect(const QString &text) const
(since 6.3) QRect boundingRect(const QString &text, const QTextOption &option) const
QRect boundingRect(const QRect &rect, int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const
QRect boundingRect(int x, int y, int width, int height, int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const
int capHeight() const
int descent() const
QString elidedText(const QString &text, Qt::TextElideMode mode, int width, int flags = 0) const
qreal fontDpi() const
int height() const
(since 6.3) int horizontalAdvance(const QString &text, const QTextOption &option) const
int horizontalAdvance(const QString &text, int len = -1) const
int horizontalAdvance(QChar ch) const
bool inFont(QChar ch) const
bool inFontUcs4(uint ucs4) const
int leading() const
int leftBearing(QChar ch) const
int lineSpacing() const
int lineWidth() const
int maxWidth() const
int minLeftBearing() const
int minRightBearing() const
int overlinePos() const
int rightBearing(QChar ch) const
QSize size(int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const
int strikeOutPos() const
void swap(QFontMetrics &other)
QRect tightBoundingRect(const QString &text) const
(since 6.3) QRect tightBoundingRect(const QString &text, const QTextOption &option) const
int underlinePos() const
int xHeight() const
bool operator!=(const QFontMetrics &other) const
QFontMetrics &operator=(QFontMetrics &&other)
QFontMetrics &operator=(const QFontMetrics &fm)
bool operator==(const QFontMetrics &other) const

Descripción detallada

Las funciones de QFontMetrics calculan el tamaño de los caracteres y las cadenas para una fuente determinada. La clase es una versión basada en números enteros de QFontMetricsF y redondeará todos los números al entero más cercano. Esto significa que sus resultados serán inexactos para cualquier fuente con métricas fraccionarias. En la mayoría de los casos, se debería utilizar en su lugar QFontMetricsF.

Hay tres formas de crear un objeto QFontMetrics:

  1. Al llamar al constructor de `QFontMetrics` con un ` QFont `, se crea un objeto de métricas de fuente para una fuente compatible con pantalla; es decir, la fuente no puede ser una fuente de impresora. Si la fuente se cambia posteriormente, el objeto de métricas de fuente no se actualiza.

    (Nota: Si se utiliza una fuente de impresora, los valores devueltos pueden ser inexactos. No siempre se puede acceder a las fuentes de impresora, por lo que, si se proporciona una fuente de impresora, se utiliza la fuente de pantalla más similar.)

  2. QWidget::fontMetrics() devuelve las métricas de fuente de un widget. Esto equivale a QFontMetrics(widget->font()). Si posteriormente se cambia la fuente del widget, el objeto de métricas de fuente no se actualiza.
  3. QPainter::fontMetrics() devuelve las métricas de la fuente actual de un «painter». Si la fuente del «painter» se cambia posteriormente, el objeto de métricas de fuente no se actualiza.

Una vez creado, el objeto proporciona funciones para acceder a las métricas individuales de la fuente, a sus caracteres y a las cadenas representadas con dicha fuente.

Existen varias funciones que operan sobre la fuente: ascent(), descent(), height(), leading() y lineSpacing() devuelven las propiedades básicas de tamaño de la fuente. Las funciones underlinePos(), overlinePos(), strikeOutPos() y lineWidth() devuelven las propiedades de la línea que subraya, sobrelinea o tacha los caracteres. Todas estas funciones son rápidas.

También hay algunas funciones que operan sobre el conjunto de glifos de la fuente: minLeftBearing(), minRightBearing() y maxWidth(). Estas son, por necesidad, lentas, por lo que recomendamos evitarlas en la medida de lo posible.

Para cada carácter, puedes obtener su horizontalAdvance(), leftBearing() y rightBearing(), y averiguar si está presente en la fuente mediante inFont(). También puedes tratar el carácter como una cadena y aplicar las funciones de cadena sobre él.

Entre las funciones de cadena se incluyen horizontalAdvance(), que devuelve el ancho de avance de una cadena en píxeles (o puntos, en el caso de una impresora); boundingRect(), que devuelve un rectángulo lo suficientemente grande como para contener la cadena renderizada; y size(), que devuelve el tamaño de dicho rectángulo.

QFontMetrics dispone de dos funciones diferentes para calcular los límites de una cadena, cada una con múltiples sobrecargas: boundingRect() y tightBoundingRect(). Si se necesita un rectángulo delimitador preciso, se debe dar preferencia a tightBoundingRect(). Esta función medirá cada glifo individualmente para devolver un rectángulo delimitador que se ajuste perfectamente al texto renderizado. Dependiendo de la plataforma, la función boundingRect() puede devolver límites aproximados, pero requiere menos cálculo.

Nota: El ancho de avance puede diferir del ancho del texto renderizado real. Se refiere a la distancia desde el origen de la cadena hasta el punto en el que se añadirían caracteres adicionales. Dado que el texto puede presentar salientes (en el caso de una fuente en cursiva, por ejemplo) o espaciado entre caracteres, el ancho de avance puede ser menor o mayor que el ancho real del texto renderizado. A esto se le denomina «desplazamiento a la derecha» del texto.

Ejemplo:

QFont font("times", 24);
QFontMetrics fm(font);
int pixelsWide = fm.horizontalAdvance("What's the advance width of this text?");
int pixelsHigh = fm.height();

Véase también QFont, QFontInfo y QFontDatabase.

Documentación de las funciones de miembro

[explicit] QFontMetrics::QFontMetrics(const QFont &font)

Crea un objeto de métricas de fuente para font.

Las métricas de la fuente serán compatibles con el dispositivo de dibujo utilizado para crear font.

El objeto de métricas de fuente contiene la información de la fuente que se pasa al constructor en el momento de su creación, y no se actualiza si los atributos de la fuente se modifican posteriormente.

Utiliza QFontMetrics(const QFont &, QPaintDevice *) para obtener las métricas de fuente compatibles con un dispositivo de dibujo concreto.

QFontMetrics::QFontMetrics(const QFont &font, const QPaintDevice *paintdevice)

Crea un objeto de métricas de fuente para font y paintdevice.

Las métricas de la fuente serán compatibles con el dispositivo de dibujo (paintdevice) pasado. Si paintdevice es nullptr, las métricas serán compatibles con la pantalla, es decir, las métricas que se obtienen al utilizar la fuente para dibujar texto en un widgets o un pixmaps, no en un QPicture o un QPrinter.

El objeto de métricas de la fuente contiene la información de la fuente que se pasa al constructor en el momento de su creación, y no se actualiza si los atributos de la fuente se modifican posteriormente.

QFontMetrics::QFontMetrics(const QFontMetrics &fm)

Crea una copia de fm.

[constexpr noexcept default] QFontMetrics::QFontMetrics(QFontMetrics &&)

Crea una instancia de ` QFontMetrics` mediante el operador `move`.

[noexcept] QFontMetrics::~QFontMetrics()

Destruye el objeto de métricas de fuente y libera todos los recursos asignados.

int QFontMetrics::ascent() const

Devuelve la altura de ascensor de la fuente.

La altura de ascenso de una fuente es la distancia desde la línea de base hasta la posición más alta a la que llegan los caracteres. En la práctica, algunos diseñadores de fuentes se saltan esta regla, por ejemplo, cuando colocan más de un acento encima de un carácter o para dar cabida a un carácter concreto, por lo que es posible (aunque poco frecuente) que este valor sea demasiado pequeño.

Véase también descent().

int QFontMetrics::averageCharWidth() const

Devuelve el ancho medio de los glifos de la fuente.

QRect QFontMetrics::boundingRect(QChar ch) const

Devuelve el rectángulo que quedaría cubierto por tinta si se dibujara el carácter ch en el origen del sistema de coordenadas.

Ten en cuenta que el rectángulo delimitador puede extenderse a la izquierda de (0, 0) (por ejemplo, en el caso de las fuentes en cursiva) y que el texto resultante puede cubrir todos los píxeles del rectángulo delimitador. En el caso de un carácter de espacio, el rectángulo suele estar vacío.

Ten en cuenta que el rectángulo suele extenderse tanto por encima como por debajo de la línea de base.

Advertencia: La anchura del rectángulo devuelto no es la anchura de avance del carácter. Utilice en su lugar `boundingRect(const QString &)` o ` horizontalAdvance()`.

Véase también horizontalAdvance().

QRect QFontMetrics::boundingRect(const QString &text) const

Devuelve el rectángulo delimitador de los caracteres de la cadena especificada por ` text`. El rectángulo delimitador siempre abarca, como mínimo, el conjunto de píxeles que cubriría el texto si se dibujara en (0, 0).

Ten en cuenta que el rectángulo delimitador puede extenderse a la izquierda de (0, 0), por ejemplo, en el caso de las fuentes en cursiva, y que la anchura del rectángulo devuelto puede ser diferente de la que devuelve el método horizontalAdvance().

Si quieres conocer el ancho de avance de la cadena (para maquetar un conjunto de cadenas una al lado de otra), utiliza en su lugar horizontalAdvance().

Los caracteres de nueva línea se procesan como caracteres normales, no como saltos de línea.

La altura del rectángulo delimitador es, como mínimo, igual al valor devuelto por height().

Véase también horizontalAdvance(), height(), QPainter::boundingRect() y tightBoundingRect().

[since 6.3] QRect QFontMetrics::boundingRect(const QString &text, const QTextOption &option) const

Devuelve el rectángulo delimitador de los caracteres de la cadena especificada por ` text `, maquetada mediante ` option`. El rectángulo delimitador siempre abarca, como mínimo, el conjunto de píxeles que cubriría el texto si se dibujara en (0, 0).

Ten en cuenta que el rectángulo delimitador puede extenderse a la izquierda de (0, 0), por ejemplo, en el caso de las fuentes en cursiva, y que la anchura del rectángulo devuelto puede ser diferente de la que devuelve el método horizontalAdvance().

Si quieres conocer el ancho de avance de la cadena (para maquetar un conjunto de cadenas una al lado de otra), utiliza en su lugar horizontalAdvance().

Los caracteres de nueva línea se procesan como caracteres normales, no como saltos de línea.

La altura del rectángulo delimitador es, como mínimo, igual al valor devuelto por height().

Esta función se introdujo en Qt 6.3.

Véase también horizontalAdvance(), height(), QPainter::boundingRect() y tightBoundingRect().

QRect QFontMetrics::boundingRect(const QRect &rect, int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const

Devuelve el rectángulo delimitador de los caracteres de la cadena especificada por ` text`, que es el conjunto de píxeles que cubriría el texto si se dibujara en (0, 0). El dibujo, y por lo tanto el rectángulo delimitador, está limitado al rectángulo ` rect`.

El argumento flags es la operación OR bit a bit de los siguientes indicadores:

Qt::Horizontal La alineación por defecto es « Qt::AlignLeft » y la alineación vertical por defecto es « Qt::AlignTop ».

Si se establecen varios indicadores de alineación horizontal o varios de alineación vertical, la alineación resultante no está definida.

Si se establece « Qt::TextExpandTabs » en « flags », entonces: si « tabArray » no es nulo, especifica una secuencia terminada en 0 de posiciones de píxeles para las tabulaciones; de lo contrario, si « tabStops » es distinto de cero, se utiliza como espaciado entre tabulaciones (en píxeles).

Tenga en cuenta que el rectángulo delimitador puede extenderse a la izquierda de (0, 0), por ejemplo, en el caso de las fuentes en cursiva, y que el texto resultante puede cubrir todos los píxeles del rectángulo delimitador.

Los caracteres de nueva línea se procesan como saltos de línea.

A pesar de las diferentes alturas reales de los caracteres, las alturas de los rectángulos delimitadores de «Yes» y «yes» son iguales.

Esta es una función sobrecargada.

Véase también horizontalAdvance(), QPainter::boundingRect() y Qt::Alignment.

QRect QFontMetrics::boundingRect(int x, int y, int width, int height, int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const

Devuelve el rectángulo delimitador del elemento « text » indicado, dentro del rectángulo especificado por las coordenadas « x » y « y », « width » y « height ».

Si se establece Qt::TextExpandTabs en flags y tabArray no es nulo, especifica una secuencia de posiciones de píxeles, terminada en 0, para las pestañas; de lo contrario, si tabStops es distinto de cero, se utiliza como espaciado entre pestañas (en píxeles).

Esta es una función sobrecargada.

int QFontMetrics::capHeight() const

Devuelve la altura de mayúscula de la fuente.

La altura de mayúscula de una fuente es la altura que tiene una letra mayúscula por encima de la línea de base. Concretamente, es la altura de las letras mayúsculas planas —como la H o la I—, a diferencia de las letras redondeadas, como la O, o las puntiagudas, como la A, que pueden presentar un saliente.

Véase también ascent().

int QFontMetrics::descent() const

Devuelve el descenso de la fuente.

El descenso es la distancia desde la línea de base hasta el punto más bajo al que llegan los caracteres. En la práctica, algunos diseñadores de fuentes se saltan esta regla, por ejemplo, para adaptarse a un carácter concreto, por lo que es posible (aunque poco frecuente) que este valor sea demasiado pequeño.

Véase también ascent().

QString QFontMetrics::elidedText(const QString &text, Qt::TextElideMode mode, int width, int flags = 0) const

Si la cadena « text » ocupa más espacio que « width », devuelve una versión abreviada de la cadena (es decir, una cadena que contiene «...»). En caso contrario, devuelve la cadena original.

El parámetro mode especifica si el texto se trunca por la izquierda (p. ej., «...tech»), por el centro (p. ej., «Tr...ch») o por la derecha (p. ej., «Trol...»).

El valor de « width » se especifica en píxeles, no en caracteres.

El argumento ` flags ` es opcional y, actualmente, solo admite ` Qt::TextShowMnemonic ` como valor.

La marca de elisión sigue a la « layoutdirection ». Por ejemplo, aparecerá a la derecha del texto en diseños de derecha a izquierda si la « mode » es « Qt::ElideLeft », y a la izquierda del texto si la « mode » es « Qt::ElideRight ».

qreal QFontMetrics::fontDpi() const

Devuelve los DPI de la fuente.

int QFontMetrics::height() const

Devuelve la altura de la fuente.

Este valor es siempre igual a ` ascent()` + `descent()`.

Véanse también leading() y lineSpacing().

[since 6.3] int QFontMetrics::horizontalAdvance(const QString &text, const QTextOption &option) const

Devuelve el avance horizontal, en píxeles, de « text », maquetado mediante « option ».

El avance es la distancia adecuada para dibujar un carácter posterior tras text.

Esta función se introdujo en Qt 6.3.

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

int QFontMetrics::horizontalAdvance(const QString &text, int len = -1) const

Devuelve el avance horizontal en píxeles de los primeros len caracteres de text. Si len es negativo (valor por defecto), se utiliza la cadena completa. Se analiza toda la longitud de text, incluso si len es considerablemente más corta.

Esta es la distancia adecuada para dibujar un carácter posterior a text.

Véase también boundingRect().

int QFontMetrics::horizontalAdvance(QChar ch) const

Rodamientos

Devuelve el avance horizontal del carácter ch en píxeles. Se trata de una distancia adecuada para dibujar el carácter siguiente tras llamar a ch.

Algunas de las métricas se describen en la imagen. Los rectángulos oscuros centrales abarcan el avance horizontal lógico (horizontalAdvance()) de cada carácter. Los rectángulos claros exteriores abarcan el avance de espaciado ( leftBearing()) y el avance de espaciado de los caracteres adyacentes ( rightBearing()) de cada carácter. Obsérvese que los valores de los márgenes de la «f» en esta fuente concreta son ambos negativos, mientras que los de la «o» son ambos positivos.

Advertencia: Esta función producirá resultados incorrectos para los caracteres árabes o los signos no espaciadores situados en medio de una cadena, ya que no se puede tener en cuenta la configuración de los glifos y el posicionamiento de los signos que se produce al procesar las cadenas. Al implementar un control de texto interactivo, utiliza en su lugar QTextLayout.

Esta es una función sobrecargada.

Véase también boundingRect().

bool QFontMetrics::inFont(QChar ch) const

Devuelve « true » si el carácter « ch » es un carácter válido en la fuente; en caso contrario, devuelve « false ».

bool QFontMetrics::inFontUcs4(uint ucs4) const

Devuelve « true » si el carácter ucs4, codificado en UCS-4/UTF-32, es un carácter válido en la fuente; en caso contrario, devuelve « false ».

int QFontMetrics::leading() const

Devuelve el interlineado superior de la fuente.

Se trata del interlineado natural.

Véase también height() y lineSpacing().

int QFontMetrics::leftBearing(QChar ch) const

Devuelve la coordenada de acentuación izquierda del carácter ch en la fuente.

El desplazamiento hacia la izquierda es la distancia hacia la derecha que hay entre el píxel más a la izquierda del carácter y el origen lógico del mismo. Este valor es negativo si los píxeles del carácter se extienden hacia la izquierda del origen lógico.

Consulta horizontalAdvance() para ver una descripción gráfica de esta métrica.

Véanse también rightBearing(), minLeftBearing() y horizontalAdvance().

int QFontMetrics::lineSpacing() const

Devuelve la distancia entre una línea base y la siguiente.

Este valor es siempre igual a leading() +height().

Véanse también height() y leading().

int QFontMetrics::lineWidth() const

Devuelve el ancho de las líneas de subrayado y tachado, ajustado al tamaño en puntos de la fuente.

Véase también underlinePos(), overlinePos() y strikeOutPos().

int QFontMetrics::maxWidth() const

Devuelve la anchura del carácter más ancho de la fuente.

int QFontMetrics::minLeftBearing() const

Devuelve el ángulo mínimo hacia la izquierda de la fuente.

Se trata del valor más pequeño de « leftBearing » (char) de todos los caracteres de la fuente.

Ten en cuenta que esta función puede ser muy lenta si la fuente es grande.

Véanse también minRightBearing() y leftBearing().

int QFontMetrics::minRightBearing() const

Devuelve el ángulo mínimo a la derecha de la fuente.

Se trata del « rightBearing » (carácter) más pequeño de todos los caracteres de la fuente.

Ten en cuenta que esta función puede ser muy lenta si la fuente es grande.

Véanse también minLeftBearing() y rightBearing().

int QFontMetrics::overlinePos() const

Devuelve la distancia desde la línea de base hasta el punto en el que debe trazarse una línea superior.

Véase también underlinePos(), strikeOutPos() y lineWidth().

int QFontMetrics::rightBearing(QChar ch) const

Devuelve el desplazamiento hacia la derecha del carácter ch en la fuente.

El desplazamiento hacia la derecha es la distancia hacia la izquierda que separa el píxel más a la derecha del carácter del origen lógico del carácter siguiente. Este valor es negativo si los píxeles del carácter se extienden hacia la derecha del horizontalAdvance() del carácter.

Consulte « horizontalAdvance()» para obtener una descripción gráfica de esta métrica.

Véanse también leftBearing(), minRightBearing() y horizontalAdvance().

QSize QFontMetrics::size(int flags, const QString &text, int tabStops = 0, int *tabArray = nullptr) const

Devuelve el tamaño en píxeles de ` text`.

El argumento ` flags ` es el OR bit a bit de los siguientes indicadores:

Si se establece « Qt::TextExpandTabs » en « flags », entonces: si « tabArray » no es nulo, especifica una secuencia terminada en 0 de posiciones de píxeles para las tabulaciones; de lo contrario, si « tabStops » es distinto de cero, se utiliza como espaciado de tabulación (en píxeles).

Los caracteres de nueva línea se procesan como saltos de línea.

A pesar de las diferentes alturas reales de los caracteres, las alturas de los rectángulos delimitadores de «Sí» y «sí» son iguales.

Véase también boundingRect().

int QFontMetrics::strikeOutPos() const

Devuelve la distancia desde la línea de base hasta el punto en el que debe trazarse la línea de strikeout.

Véase también underlinePos(), overlinePos() y lineWidth().

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

Sustituye esta instancia de métricas de fuente por other. Esta operación es muy rápida y nunca falla.

QRect QFontMetrics::tightBoundingRect(const QString &text) const

Devuelve un rectángulo delimitador ajustado alrededor de los caracteres de la cadena especificada por ` text`. El rectángulo delimitador siempre abarca, como mínimo, el conjunto de píxeles que cubriría el texto si se dibujara en (0, 0).

Ten en cuenta que el rectángulo delimitador puede extenderse a la izquierda de (0, 0), por ejemplo, en el caso de las fuentes en cursiva, y que la anchura del rectángulo devuelto podría ser diferente de la que devuelve el método horizontalAdvance().

Si quieres conocer el ancho de avance de la cadena (para maquetar un conjunto de cadenas una al lado de otra), utiliza en su lugar horizontalAdvance().

Los caracteres de nueva línea se procesan como caracteres normales, no como saltos de línea.

Véanse también horizontalAdvance(), height() y boundingRect().

[since 6.3] QRect QFontMetrics::tightBoundingRect(const QString &text, const QTextOption &option) const

Devuelve un rectángulo delimitador ajustado alrededor de los caracteres de la cadena especificada por ` text `, maquetada mediante ` option`. El rectángulo delimitador siempre abarca, como mínimo, el conjunto de píxeles que cubriría el texto si se dibujara en (0, 0).

Ten en cuenta que el rectángulo delimitador puede extenderse a la izquierda de (0, 0), por ejemplo, en el caso de las fuentes en cursiva, y que la anchura del rectángulo devuelto puede ser diferente de la que devuelve el método horizontalAdvance().

Si quieres conocer el ancho de avance de la cadena (para maquetar un conjunto de cadenas una al lado de otra), utiliza en su lugar horizontalAdvance().

Los caracteres de nueva línea se procesan como caracteres normales, no como saltos de línea.

Esta función se introdujo en Qt 6.3.

Véase también horizontalAdvance(), height() y boundingRect().

int QFontMetrics::underlinePos() const

Devuelve la distancia desde la línea de base hasta el punto en el que debe trazarse un guión bajo.

Véase también overlinePos(), strikeOutPos() y lineWidth().

int QFontMetrics::xHeight() const

Devuelve la altura «x» de la fuente. A menudo, aunque no siempre, esta coincide con la altura del carácter «x».

bool QFontMetrics::operator!=(const QFontMetrics &other) const

Devuelve ` true ` si ` other ` no es igual a este objeto; en caso contrario, devuelve ` false`.

Dos métricas de fuente se consideran iguales si se han construido a partir del mismo QFont y los dispositivos de pintura para los que se han construido se consideran compatibles.

Véase también operator==().

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

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

QFontMetrics &QFontMetrics::operator=(const QFontMetrics &fm)

Asigna las métricas de fuente « fm ».

bool QFontMetrics::operator==(const QFontMetrics &other) const

Devuelve ` true ` si ` other ` es igual a este objeto; en caso contrario, devuelve ` false`.

Dos métricas de fuente se consideran iguales si se han creado a partir del mismo QFont y los dispositivos de dibujo para los que se han creado se consideran compatibles.

Véase también operator!=().

© 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.