QLabel Class
El widget QLabel permite mostrar texto o imágenes. Más información...
| Encabezado: | #include <QLabel> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS Widgets) target_link_libraries(mytarget PRIVATE Qt6::Widgets) |
| qmake: | QT += widgets |
| Heredado de: | QFrame |
Propiedades
|
|
Funciones públicas
| QLabel(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| QLabel(const QString &text, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags()) | |
| virtual | ~QLabel() |
| Qt::Alignment | alignment() const |
| QWidget * | buddy() const |
| bool | hasScaledContents() const |
| bool | hasSelectedText() const |
| int | indent() const |
| int | margin() const |
| QMovie * | movie() const |
| bool | openExternalLinks() const |
(since 6.0) QPicture | picture() const |
| QPixmap | pixmap() const |
(since 6.1) QTextDocument::ResourceProvider | resourceProvider() const |
| QString | selectedText() const |
| int | selectionStart() const |
| void | setAlignment(Qt::Alignment) |
| void | setBuddy(QWidget *buddy) |
| void | setIndent(int) |
| void | setMargin(int) |
| void | setOpenExternalLinks(bool open) |
(since 6.1) void | setResourceProvider(const QTextDocument::ResourceProvider &provider) |
| void | setScaledContents(bool) |
| void | setSelection(int start, int length) |
| void | setTextFormat(Qt::TextFormat) |
| void | setTextInteractionFlags(Qt::TextInteractionFlags flags) |
| void | setWordWrap(bool on) |
| QString | text() const |
| Qt::TextFormat | textFormat() const |
| Qt::TextInteractionFlags | textInteractionFlags() const |
| bool | wordWrap() const |
Funciones públicas reimplementadas
| virtual int | heightForWidth(int w) const override |
| virtual QSize | minimumSizeHint() const override |
| virtual QSize | sizeHint() const override |
Ranuras públicas
| void | clear() |
| void | setMovie(QMovie *movie) |
| void | setNum(int num) |
| void | setNum(double num) |
| void | setPicture(const QPicture &picture) |
| void | setPixmap(const QPixmap &) |
| void | setText(const QString &) |
Señales
| void | linkActivated(const QString &link) |
| void | linkHovered(const QString &link) |
Funciones protegidas reimplementadas
| virtual void | changeEvent(QEvent *ev) override |
| virtual void | contextMenuEvent(QContextMenuEvent *ev) override |
| virtual bool | event(QEvent *e) override |
| virtual void | focusInEvent(QFocusEvent *ev) override |
| virtual bool | focusNextPrevChild(bool next) override |
| virtual void | focusOutEvent(QFocusEvent *ev) override |
| virtual void | keyPressEvent(QKeyEvent *ev) override |
| virtual void | mouseMoveEvent(QMouseEvent *ev) override |
| virtual void | mousePressEvent(QMouseEvent *ev) override |
| virtual void | mouseReleaseEvent(QMouseEvent *ev) override |
| virtual void | paintEvent(QPaintEvent *) override |
Descripción detallada

QLabel se utiliza para mostrar texto o una imagen. No ofrece ninguna funcionalidad de interacción con el usuario. El aspecto visual de la etiqueta se puede configurar de diversas formas, y se puede utilizar para especificar una tecla mnemónica de foco para otro widget.
Un QLabel puede contener cualquiera de los siguientes tipos de contenido:
| Contenido | Configuración |
|---|---|
| Texto sin formato | Pasa un objeto ` QString ` a la función ` setText()`. |
| Texto con formato | Pasa un objeto ` QString ` que contenga texto enriquecido a ` setText()`. |
| Un mapa de píxeles | Pasa un ` QPixmap ` a ` setPixmap()`. |
| Una película | Pasa un objeto ` QMovie ` a la función ` setMovie()`. |
| Un número | Pasa un int o un double a ` setNum()`, que convierte el número en texto sin formato. |
| Nada | Equivale a un texto sin formato vacío. Es el valor por defecto. Lo establece clear(). |
Advertencia: Al pasar un ` QString ` al constructor o al llamar a ` setText()`, asegúrate de depurar la entrada, ya que `QLabel` intenta adivinar si debe mostrar el texto como texto sin formato o como texto enriquecido, un subconjunto del marcado HTML 4. Es posible que desee llamar explícitamente a setTextFormat() (), por ejemplo, en caso de que espere que el texto esté en formato sin formato pero no pueda controlar la fuente del texto (por ejemplo, al mostrar datos cargados desde la web).
Cuando se modifica el contenido mediante cualquiera de estas funciones, se borra cualquier contenido anterior.
Por defecto, las etiquetas muestran texto e imágen left-aligned, vertically-centered es, en los que las tabulaciones del texto que se va a mostrar son automatically expanded. Sin embargo, el aspecto de un QLabel se puede ajustar y perfeccionar de varias formas.
La posición del contenido dentro del área del widget QLabel se puede ajustar con ` setAlignment()` y ` setIndent()`. El contenido de texto también puede ajustar las líneas según los límites de las palabras con ` setWordWrap()`. Por ejemplo, este código configura un panel hundido con un texto de dos líneas en la esquina inferior derecha (ambas líneas alineadas con el lado derecho de la etiqueta):
QLabel *label = new QLabel(this);
label->setFrameStyle(QFrame::Panel | QFrame::Sunken);
label->setText("first line\nsecond line");
label->setAlignment(Qt::AlignBottom | Qt::AlignRight);Las propiedades y funciones que QLabel hereda de QFrame también pueden utilizarse para especificar el marco del widget que se utilizará para cualquier etiqueta dada.
A menudo se utiliza un QLabel como etiqueta para un widget interactivo. Para este uso, QLabel proporciona un mecanismo útil para añadir un mnemónico (véase QKeySequence) que establecerá el foco del teclado en el otro widget (denominado «compañero» del QLabel). Por ejemplo:
QLineEdit *phoneEdit = new QLineEdit(this);
QLabel *phoneLabel = new QLabel("&Phone:", this);
phoneLabel->setBuddy(phoneEdit);En este ejemplo, el foco del teclado se transfiere al «compañero» de la etiqueta (el QLineEdit) cuando el usuario pulsa Alt+P. Si el «compañero» fuera un botón (que heredara de QAbstractButton), al activar el mnemónico se emularía un clic en el botón.
Véase también QLineEdit, QTextEdit, QPixmap y QMovie.
Documentación de propiedades
alignment : Qt::Alignment
Esta propiedad determina la alineación del contenido de la etiqueta.
Por defecto, el contenido de la etiqueta está alineado a la izquierda y centrado verticalmente.
Funciones de Access:
| Qt::Alignment | alignment() const |
| void | setAlignment(Qt::Alignment) |
Véase también text.
[read-only] hasSelectedText : bool
Esta propiedad indica si hay algún texto seleccionado
hasSelectedText() devuelve « true » si el usuario ha seleccionado parte o la totalidad del texto; en caso contrario, devuelve « false ».
Por defecto, esta propiedad tiene el valor « false ».
Nota: La propiedad « textInteractionFlags » establecida en la etiqueta debe incluir «TextSelectableByMouse» o «TextSelectableByKeyboard».
Funciones de acceso:
| bool | hasSelectedText() const |
Véase también ` selectedText()` ().
indent : int
Esta propiedad establece la sangría del texto de la etiqueta en píxeles.
Si una etiqueta muestra texto, la sangría se aplica al borde izquierdo si alignment() es Qt::AlignLeft, al borde derecho si alignment() es Qt::AlignRight, al borde superior si alignment() es Qt::AlignTop y al borde inferior si alignment() es Qt::AlignBottom.
Si la sangría es negativa, o si no se ha establecido ninguna, la etiqueta calcula la sangría efectiva de la siguiente manera: si frameWidth() es 0, la sangría efectiva pasa a ser 0. Si frameWidth() es mayor que 0, la sangría efectiva pasa a ser la mitad del ancho del carácter «x» del font() actual del widget.
Por defecto, la sangría es -1, lo que significa que la sangría efectiva se calcula de la forma descrita anteriormente.
Funciones de acceso:
| int | indent() const |
| void | setIndent(int) |
Véase también «alignment», « margin », « frameWidth()» y « font()».
margin : int
Esta propiedad define la anchura del margen.
El margen es la distancia entre el píxel más interno del marco y el píxel más externo del contenido.
El margen predeterminado es 0.
Funciones de acceso:
| int | margin() const |
| void | setMargin(int) |
Véase también indent.
openExternalLinks : bool
Especifica si QLabel debe abrir automáticamente los enlaces utilizando QDesktopServices::openUrl() en lugar de emitir la señal linkActivated().
Nota: El valor de « textInteractionFlags » establecido en la etiqueta debe incluir «LinksAccessibleByMouse» o «LinksAccessibleByKeyboard».
El valor por defecto es «false».
Funciones de acceso:
| bool | openExternalLinks() const |
| void | setOpenExternalLinks(bool open) |
Véase también textInteractionFlags().
pixmap : QPixmap
Esta propiedad contiene el mapa de píxeles de la etiqueta.
Al establecer el mapa de píxeles, se borra cualquier contenido anterior. El atajo de «buddy», si lo hay, queda desactivado.
Funciones de acceso:
| QPixmap | pixmap() const |
| void | setPixmap(const QPixmap &) |
scaledContents : bool
Esta propiedad determina si la etiqueta ajustará el tamaño de su contenido para ocupar todo el espacio disponible.
Cuando está habilitada y la etiqueta muestra un mapa de píxeles, escalará dicho mapa para ocupar todo el espacio disponible.
El valor predeterminado de esta propiedad es «false».
Funciones de acceso:
| bool | hasScaledContents() const |
| void | setScaledContents(bool) |
[read-only] selectedText : QString
Esta propiedad contiene el texto seleccionado.
Si no hay texto seleccionado, el valor de esta propiedad es una cadena vacía.
Por defecto, esta propiedad contiene una cadena vacía.
Nota: La propiedad « textInteractionFlags » establecida en la etiqueta debe incluir «TextSelectableByMouse» o «TextSelectableByKeyboard».
Funciones de acceso:
| QString | selectedText() const |
Véase también hasSelectedText().
text : QString
Esta propiedad contiene el texto de la etiqueta.
Si no se ha establecido ningún texto, devolverá una cadena vacía. Al establecer el texto, se borra cualquier contenido anterior.
El texto se interpretará como texto sin formato o como texto enriquecido, dependiendo de la configuración del formato de texto; véase setTextFormat(). La configuración predeterminada es Qt::AutoText; es decir, QLabel intentará detectar automáticamente el formato del texto establecido. Véase «Subconjunto de HTML admitido» para la definición de texto enriquecido.
Si se ha configurado un contacto, la tecla mnemónica del contacto se actualiza con el nuevo texto.
Ten en cuenta que « QLabel » es ideal para mostrar documentos pequeños de texto enriquecido, como aquellos que obtienen su configuración específica (fuente, color del texto, color de los enlaces) de la paleta de la etiqueta y de las propiedades de la fuente. Para documentos grandes, utiliza en su lugar « QTextEdit » en modo de solo lectura. « QTextEdit » también puede proporcionar una barra de desplazamiento cuando sea necesario.
Nota: Esta función habilita el seguimiento del ratón si text contiene texto enriquecido.
Funciones de Access:
| QString | text() const |
| void | setText(const QString &) |
Véase también setTextFormat(), setBuddy() y «alignment».
textFormat : Qt::TextFormat
Esta propiedad contiene el formato del texto de la etiqueta.
Consulta la enumeración « Qt::TextFormat » para obtener una explicación de las opciones posibles.
El formato predeterminado es « Qt::AutoText ».
Funciones de acceso:
| Qt::TextFormat | textFormat() const |
| void | setTextFormat(Qt::TextFormat) |
Véase también ` text()`.
textInteractionFlags : Qt::TextInteractionFlags
Especifica cómo debe interactuar la etiqueta con las entradas del usuario si muestra texto.
Si los indicadores contienen « Qt::LinksAccessibleByKeyboard », la política de foco también se establece automáticamente en « Qt::StrongFocus ». Si se establece « Qt::TextSelectableByKeyboard », la política de foco se establece en « Qt::ClickFocus ».
El valor por defecto es « Qt::LinksAccessibleByMouse ».
Funciones de acceso:
| Qt::TextInteractionFlags | textInteractionFlags() const |
| void | setTextInteractionFlags(Qt::TextInteractionFlags flags) |
wordWrap : bool
Esta propiedad define la política de ajuste de texto de la etiqueta.
Si esta propiedad tiene el valor « true », el texto de la etiqueta se ajustará en los saltos de línea cuando sea necesario; de lo contrario, no se ajustará en absoluto.
Por defecto, el ajuste de línea está desactivado.
Funciones de acceso:
| bool | wordWrap() const |
| void | setWordWrap(bool on) |
Véase también text.
Documentación de funciones de miembro
[explicit] QLabel::QLabel(QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
Crea una etiqueta vacía.
Los argumentos « parent » y el indicador de widget « f » se pasan al constructor « QFrame ».
Véase también setAlignment(), setFrameStyle() y setIndent().
[explicit] QLabel::QLabel(const QString &text, QWidget *parent = nullptr, Qt::WindowFlags f = Qt::WindowFlags())
Crea una etiqueta que muestra el texto « text ».
Los argumentos « parent » y el indicador de widget « f » se pasan al constructor « QFrame ».
Véanse también setText(), setAlignment(), setFrameStyle() y setIndent().
[virtual noexcept] QLabel::~QLabel()
Elimina la etiqueta.
QWidget *QLabel::buddy() const
Devuelve el «buddy» de esta etiqueta o `nullptr` si actualmente no hay ningún «buddy» establecido.
Véase también setBuddy().
[override virtual protected] void QLabel::changeEvent(QEvent *ev)
Reimplementa: ` QFrame::changeEvent(QEvent *ev)`.
[slot] void QLabel::clear()
Borra el contenido de cualquier etiqueta.
[override virtual protected] void QLabel::contextMenuEvent(QContextMenuEvent *ev)
Reimplementa: QWidget::contextMenuEvent(QContextMenuEvent *event).
[override virtual protected] bool QLabel::event(QEvent *e)
Reimplementa: QFrame::event(QEvent *e).
[override virtual protected] void QLabel::focusInEvent(QFocusEvent *ev)
Reimplementa: QWidget::focusInEvent(QFocusEvent *event).
[override virtual protected] bool QLabel::focusNextPrevChild(bool next)
Reimplementa: ` QWidget::focusNextPrevChild` (bool next).
[override virtual protected] void QLabel::focusOutEvent(QFocusEvent *ev)
Reimplementa: QWidget::focusOutEvent(QFocusEvent *event).
[override virtual] int QLabel::heightForWidth(int w) const
Reimplementa: ` QWidget::heightForWidth(int w) const`.
[override virtual protected] void QLabel::keyPressEvent(QKeyEvent *ev)
Reimplementa: ` QWidget::keyPressEvent(QKeyEvent *event)`.
[signal] void QLabel::linkActivated(const QString &link)
Esta señal se emite cuando el usuario hace clic en un enlace. La URL a la que hace referencia el enlace se transmite en link.
Véase también linkHovered().
[signal] void QLabel::linkHovered(const QString &link)
Esta señal se emite cuando el usuario pasa el cursor por encima de un enlace. La URL a la que hace referencia el enlace se transmite en ` link`.
Véase también linkActivated().
[override virtual] QSize QLabel::minimumSizeHint() const
Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.
[override virtual protected] void QLabel::mouseMoveEvent(QMouseEvent *ev)
Reimplementa: ` QWidget::mouseMoveEvent(QMouseEvent *event)`.
[override virtual protected] void QLabel::mousePressEvent(QMouseEvent *ev)
Reimplementa: ` QWidget::mousePressEvent(QMouseEvent *event)`.
[override virtual protected] void QLabel::mouseReleaseEvent(QMouseEvent *ev)
Reimplementa: QWidget::mouseReleaseEvent(QMouseEvent *event).
QMovie *QLabel::movie() const
Devuelve un puntero a la película de la etiqueta o `nullptr` si no se ha establecido ninguna película.
Véase también setMovie().
[override virtual protected] void QLabel::paintEvent(QPaintEvent *)
Reimplementa: QFrame::paintEvent(QPaintEvent *).
[since 6.0] QPicture QLabel::picture() const
Devuelve la imagen de la etiqueta.
Esta función se introdujo en Qt 6.0.
Véase también ` setPicture()`.
[since 6.1] QTextDocument::ResourceProvider QLabel::resourceProvider() const
Devuelve el proveedor de recursos para el texto con formato de esta etiqueta.
Esta función se introdujo en Qt 6.1.
Véase también ` setResourceProvider()`.
int QLabel::selectionStart() const
selectionStart() devuelve el índice del primer carácter seleccionado en la etiqueta o -1 si no hay ningún texto seleccionado.
Nota: La propiedad « textInteractionFlags » de la etiqueta debe incluir «TextSelectableByMouse» o «TextSelectableByKeyboard».
Véase también selectedText().
void QLabel::setBuddy(QWidget *buddy)
Establece el «buddy» de esta etiqueta en buddy.
Cuando el usuario pulsa la tecla de acceso rápido indicada por esta etiqueta, el foco del teclado se transfiere al widget asociado a la etiqueta.
El mecanismo de «buddy» solo está disponible para las QLabels que contengan texto en el que un carácter vaya precedido de un símbolo «&». Este carácter se establece como tecla de acceso rápido. Consulta la documentación de QKeySequence::mnemonic() para obtener más detalles (para mostrar un símbolo «&» real, utiliza «&&»).
En un cuadro de diálogo, se pueden crear dos widgets de introducción de datos y una etiqueta para cada uno, y configurar la disposición geométrica de modo que cada etiqueta se sitúe justo a la izquierda de su widget de introducción de datos (su «compañero»), por ejemplo:
QLineEdit *nameEdit = new QLineEdit(this);
QLabel *nameLabel = new QLabel("&Name:", this);
nameLabel->setBuddy(nameEdit);
QLineEdit *phoneEdit = new QLineEdit(this);
QLabel *phoneLabel = new QLabel("&Phone:", this);
phoneLabel->setBuddy(phoneEdit);
// (layout setup not shown)Con el código anterior, el foco salta al campo «Nombre» cuando el usuario pulsa Alt+N, y al campo «Teléfono» cuando pulsa Alt+P.
Para desactivar un compañero establecido previamente, llama a esta función con ` buddy ` establecido en `nullptr`.
Véase también buddy(), setText(), QShortcut y setAlignment().
[slot] void QLabel::setMovie(QMovie *movie)
Establece el contenido de la etiqueta en « movie ». Se borra cualquier contenido anterior. La etiqueta NO adquiere la propiedad de la película.
El acceso directo al amigo, si lo hay, se desactiva.
Véase también movie() y setBuddy().
[slot] void QLabel::setNum(int num)
Establece el contenido de la etiqueta como texto sin formato que contiene la representación textual del número entero num. Se borra cualquier contenido anterior. No realiza ninguna acción si la representación como cadena del número entero es igual al contenido actual de la etiqueta.
El atajo de «buddy», si lo hay, queda desactivado.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
label, qOverload(&QLabel::setNum));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
label, [receiver = label](int num) { receiver->setNum(num); }); Véase también setText(), QString::setNum() y setBuddy().
[slot] void QLabel::setNum(double num)
Establece el contenido de la etiqueta como texto sin formato que contiene la representación textual de un número de tipo double num. Se borra cualquier contenido anterior. No realiza ninguna acción si la representación como cadena del número de tipo double es igual al contenido actual de la etiqueta.
El atajo de «buddy», si lo hay, queda desactivado.
Nota: Esta ranura está sobrecargada. Para conectarse a esta ranura:
// Connect using qOverload:
connect(sender, &SenderClass::signal,
label, qOverload(&QLabel::setNum));
// Or using a lambda as wrapper:
connect(sender, &SenderClass::signal,
label, [receiver = label](double num) { receiver->setNum(num); }); Véase también setText(), QString::setNum() y setBuddy().
[slot] void QLabel::setPicture(const QPicture &picture)
Establece el contenido de la etiqueta en « picture ». Se borra cualquier contenido anterior.
El atajo de «buddy», si lo hay, se desactiva.
Véase también ` picture()` y ` setBuddy()`.
[since 6.1] void QLabel::setResourceProvider(const QTextDocument::ResourceProvider &provider)
Establece el provider de los recursos de texto enriquecido de esta etiqueta.
Nota: La etiqueta no asume la propiedad de la propiedad « provider ».
Esta función se introdujo en Qt 6.1.
Véase también resourceProvider().
void QLabel::setSelection(int start, int length)
Selecciona el texto desde la posición start y de un length s de caracteres.
Nota: El valor de textInteractionFlags establecido en la etiqueta debe incluir TextSelectableByMouse o TextSelectableByKeyboard.
Véase también selectedText().
[override virtual] QSize QLabel::sizeHint() const
Reimplementa: ` QFrame::sizeHint()` const.
© 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.