En esta página

QProgressBar Class

El widget QProgressBar ofrece una barra de progreso horizontal o vertical. Más información...

Encabezado: #include <QProgressBar>
CMake: find_package(Qt6 REQUIRED COMPONENTS Widgets)
target_link_libraries(mytarget PRIVATE Qt6::Widgets)
qmake: QT += widgets
Heredado de: QWidget

Tipos públicos

enum Direction { TopToBottom, BottomToTop }

Propiedades

Funciones públicas

QProgressBar(QWidget *parent = nullptr)
virtual ~QProgressBar()
Qt::Alignment alignment() const
QString format() const
bool invertedAppearance() const
bool isTextVisible() const
int maximum() const
int minimum() const
Qt::Orientation orientation() const
void resetFormat()
void setAlignment(Qt::Alignment alignment)
void setFormat(const QString &format)
void setInvertedAppearance(bool invert)
void setTextDirection(QProgressBar::Direction textDirection)
void setTextVisible(bool visible)
virtual QString text() const
QProgressBar::Direction textDirection() const
int value() const

Funciones públicas reimplementadas

virtual QSize minimumSizeHint() const override
virtual QSize sizeHint() const override

Ranuras públicas

void reset()
void setMaximum(int maximum)
void setMinimum(int minimum)
void setOrientation(Qt::Orientation)
void setRange(int minimum, int maximum)
void setValue(int value)

Señales

void valueChanged(int value)

Funciones protegidas

virtual void initStyleOption(QStyleOptionProgressBar *option) const

Funciones protegidas reimplementadas

virtual bool event(QEvent *e) override
virtual void paintEvent(QPaintEvent *) override

Descripción detallada

Barra de progreso que muestra un 42 %

Una barra de progreso se utiliza para indicar al usuario el avance de una operación y para asegurarle de que la aplicación sigue en ejecución.

La barra de progreso utiliza el concepto de pasos. Se configura especificando los valores mínimo y máximo posibles de los pasos, y mostrará el porcentaje de pasos completados cuando posteriormente se le proporcione el valor actual del paso. El porcentaje se calcula dividiendo el progreso (value() - minimum()) entre maximum() - minimum().

Puedes especificar el número mínimo y máximo de pasos con setMinimum() y setMaximum. El número actual de pasos se establece con setValue(). La barra de progreso se puede rebobinar hasta el principio con reset().

Si tanto el mínimo como el máximo se establecen en 0, la barra muestra un indicador de actividad en lugar del porcentaje de pasos. Esto resulta útil, por ejemplo, al utilizar QNetworkAccessManager para descargar elementos cuando no es posible determinar el tamaño del elemento que se está descargando.

Véase también QProgressDialog.

Documentación sobre tipos de miembro

enum QProgressBar::Direction

Especifica la dirección de lectura del elemento ` text ` para las barras de progreso verticales.

ConstanteValorDescripción
QProgressBar::TopToBottom0El texto se gira 90 grados en el sentido de las agujas del reloj.
QProgressBar::BottomToTop1El texto se gira 90 grados en sentido antihorario.

Ten en cuenta que el hecho de que el texto se dibuje o no depende del estilo. Actualmente, los estilos «CleanLooks» y «Plastique» dibujan el texto. Los estilos «Mac», «Windows» y «Windows Vista» no lo hacen.

Véase también textDirection.

Documentación de la propiedad

alignment : Qt::Alignment

Esta propiedad determina la alineación de la barra de progreso

Funciones de Access:

Qt::Alignment alignment() const
void setAlignment(Qt::Alignment alignment)

format : QString

Esta propiedad contiene la cadena utilizada para generar el texto actual

%p: se sustituye por el porcentaje completado. %v: se sustituye por el valor actual. %m: se sustituye por el número total de pasos.

El valor por defecto es «%p%».

Funciones de acceso:

QString format() const
void setFormat(const QString &format)
void resetFormat()

Véase también text().

invertedAppearance : bool

Esta propiedad determina si la barra de progreso muestra su avance invertido o no

Si esta propiedad tiene el valor « true », la barra de progreso avanza en la dirección opuesta (por ejemplo, de derecha a izquierda). Por defecto, la barra de progreso no está invertida.

Funciones de acceso:

bool invertedAppearance() const
void setInvertedAppearance(bool invert)

Véase también « orientation » y « layoutDirection ».

maximum : int

Esta propiedad contiene el valor máximo de la barra de progreso

Al establecer esta propiedad, se ajusta el valor « minimum » si es necesario para garantizar que el rango siga siendo válido. Si el valor actual queda fuera del nuevo rango, la barra de progreso se restablece con la función « reset()».

Funciones de acceso:

int maximum() const
void setMaximum(int maximum)

minimum : int

Esta propiedad establece el valor mínimo de la barra de progreso

Al establecer esta propiedad, se ajusta el valor « maximum » si es necesario para garantizar que el rango siga siendo válido. Si el valor actual queda fuera del nuevo rango, la barra de progreso se restablece con « reset()».

Funciones de acceso:

int minimum() const
void setMinimum(int minimum)

orientation : Qt::Orientation

Esta propiedad define la orientación de la barra de progreso

La orientación debe ser « Qt::Horizontal » (valor predeterminado) o « Qt::Vertical ».

Funciones de acceso:

Qt::Orientation orientation() const
void setOrientation(Qt::Orientation)

Véase también invertedAppearance y textDirection.

[read-only] text : QString

Esta propiedad contiene el texto descriptivo que se muestra junto a la barra de progreso

El texto devuelto es el mismo que el que se muestra en el centro (o, en algunos estilos, a la izquierda) de la barra de progreso.

El progreso que se muestra en el texto puede ser inferior al valor mínimo, lo que indica que la barra de progreso se encuentra en estado «reiniciado» antes de que se haya establecido ningún progreso.

En la implementación predeterminada, el texto contiene un valor porcentual que indica el progreso alcanzado hasta el momento, o bien está en blanco porque la barra de progreso se encuentra en estado de reinicio.

Funciones de Access:

virtual QString text() const

textDirection : Direction

Esta propiedad define la dirección de lectura de la propiedad « text » para las barras de progreso verticales

Esta propiedad no afecta a las barras de progreso horizontales. Por defecto, la dirección de lectura es « QProgressBar::TopToBottom ».

Funciones de acceso:

QProgressBar::Direction textDirection() const
void setTextDirection(QProgressBar::Direction textDirection)

Véase también « orientation » y « textVisible ».

textVisible : bool

Esta propiedad determina si se debe mostrar el porcentaje de finalización actual

El estilo puede ignorar esta propiedad (por ejemplo, QMacStyle nunca muestra el texto).

Funciones de acceso:

bool isTextVisible() const
void setTextVisible(bool visible)

Véase también textDirection.

value : int

Esta propiedad contiene el valor actual de la barra de progreso

Intentar cambiar el valor actual por uno que se encuentre fuera del rango mínimo-máximo no tiene ningún efecto sobre el valor actual.

Funciones de acceso:

int value() const
void setValue(int value)

Señal de notificación:

void valueChanged(int value)

Documentación de funciones de miembro

[explicit] QProgressBar::QProgressBar(QWidget *parent = nullptr)

Crea una barra de progreso con el valor de « parent » indicado.

Por defecto, el valor mínimo del paso se establece en 0 y el máximo en 100.

Véase también setRange().

[virtual noexcept] QProgressBar::~QProgressBar()

Destructor.

[override virtual protected] bool QProgressBar::event(QEvent *e)

Reimplementa: QWidget::event(QEvent *event).

[virtual protected] void QProgressBar::initStyleOption(QStyleOptionProgressBar *option) const

Inicializa ` option ` con los valores de esta página: QProgressBar. Este método resulta útil para las subclases cuando necesitan un ` QStyleOptionProgressBar`, pero no quieren introducir toda la información ellas mismas.

Véase también QStyleOption::initFrom().

[override virtual] QSize QProgressBar::minimumSizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::minimumSizeHint.

[override virtual protected] void QProgressBar::paintEvent(QPaintEvent *)

Reimplementa: ` QWidget::paintEvent` (`QPaintEvent *event)`.

[slot] void QProgressBar::reset()

Restablecer la barra de progreso. La barra de progreso «retrocede» y no muestra ningún avance.

[slot] void QProgressBar::setRange(int minimum, int maximum)

Establece los valores mínimo y máximo de la barra de progreso en minimum y maximum, respectivamente.

Si maximum es menor que minimum, minimum se convierte en el único valor válido.

Si el valor actual queda fuera del nuevo rango, la barra de progreso se restablece con reset().

El valor de QProgressBar puede establecerse en un estado indeterminado utilizando setRange(0, 0).

Véase también minimum y maximum.

[override virtual] QSize QProgressBar::sizeHint() const

Reimplementa una función de acceso para la propiedad: QWidget::sizeHint.

[signal] void QProgressBar::valueChanged(int value)

Esta señal se emite cuando cambia el valor que se muestra en la barra de progreso. value es el nuevo valor que muestra la barra de progreso.

Nota: Señalde notificación para la propiedad value.

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