Back to Qt.io
Contact Us Blog Download Qt
En esta página

Q3DBars Class

La clase Q3DBars proporciona métodos para representar gráficos de barras en 3D. Más...

Cabecera: #include <Q3DBars>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
Desde: QtDataVisualization 1.0
Hereda: QAbstract3DGraph

Propiedades

Funciones públicas

Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)
virtual ~Q3DBars()
void addAxis(QAbstract3DAxis *axis)
void addSeries(QBar3DSeries *series)
QList<QAbstract3DAxis *> axes() const
QSizeF barSeriesMargin() const
QSizeF barSpacing() const
float barThickness() const
QCategory3DAxis *columnAxis() const
float floorLevel() const
void insertSeries(int index, QBar3DSeries *series)
bool isBarSpacingRelative() const
bool isMultiSeriesUniform() const
QBar3DSeries *primarySeries() const
void releaseAxis(QAbstract3DAxis *axis)
void removeSeries(QBar3DSeries *series)
QCategory3DAxis *rowAxis() const
QBar3DSeries *selectedSeries() const
QList<QBar3DSeries *> seriesList() const
void setBarSeriesMargin(const QSizeF &margin)
void setBarSpacing(const QSizeF &spacing)
void setBarSpacingRelative(bool relative)
void setBarThickness(float thicknessRatio)
void setColumnAxis(QCategory3DAxis *axis)
void setFloorLevel(float level)
void setMultiSeriesUniform(bool uniform)
void setPrimarySeries(QBar3DSeries *series)
void setRowAxis(QCategory3DAxis *axis)
void setValueAxis(QValue3DAxis *axis)
QValue3DAxis *valueAxis() const

Señales

void barSeriesMarginChanged(const QSizeF &margin)
void barSpacingChanged(const QSizeF &spacing)
void barSpacingRelativeChanged(bool relative)
void barThicknessChanged(float thicknessRatio)
void columnAxisChanged(QCategory3DAxis *axis)
void floorLevelChanged(float level)
void multiSeriesUniformChanged(bool uniform)
void primarySeriesChanged(QBar3DSeries *series)
void rowAxisChanged(QCategory3DAxis *axis)
void selectedSeriesChanged(QBar3DSeries *series)
void valueAxisChanged(QValue3DAxis *axis)

Descripción detallada

Esta clase permite a los desarrolladores renderizar gráficos de barras en 3D y visualizarlos rotando la escena libremente. La rotación se realiza manteniendo pulsado el botón derecho del ratón y moviendo el ratón. El zoom se realiza mediante la rueda del ratón. La selección, si está activada, se realiza con el botón izquierdo del ratón. La escena se puede restablecer a la vista de cámara predeterminada pulsando la rueda del ratón. En dispositivos táctiles, la rotación se realiza pulsando y moviendo, la selección pulsando y manteniendo pulsado y el zoom pellizcando.

Si no se establecen ejes explícitamente en Q3DBars, se crean ejes temporales por defecto sin etiquetas. Estos ejes por defecto pueden ser modificados a través de accesores de eje, pero tan pronto como cualquier eje se establece explícitamente para la orientación, el eje por defecto para esa orientación se destruye.

Q3DBars admite más de una serie visible al mismo tiempo. No es necesario que todas las series tengan la misma cantidad de filas y columnas. Las etiquetas de filas y columnas se toman de la primera serie añadida, a menos que se definan explícitamente ejes de filas y columnas.

Cómo construir un gráfico Q3DBars mínimo

En primer lugar, construya una instancia de Q3DBars. Dado que en este ejemplo estamos ejecutando el gráfico como ventana de nivel superior, necesitamos borrar la bandera Qt::FramelessWindowHint, que se establece por defecto:

Q3DBars bars;
bars.setFlags(bars.flags() ^ Qt::FramelessWindowHint);

Después de construir Q3DBars, puede establecer la ventana de datos cambiando el rango en los ejes de fila y columna. No es obligatorio, ya que la ventana de datos mostrará por defecto todos los datos de la serie. Si la cantidad de datos es grande, suele ser preferible mostrar sólo una parte. Para el ejemplo, establezcamos la ventana de datos para mostrar las primeras cinco filas y columnas:

bars.rowAxis()->setRange(0, 4);
bars.columnAxis()->setRange(0, 4);

Ahora Q3DBars está listo para recibir datos para ser renderizados. Cree una serie con una fila de 5 valores:

QBar3DSeries *series = new QBar3DSeries;
QBarDataRow *data = new QBarDataRow;
*data << 1.0f << 3.0f << 7.5f << 5.0f << 2.2f;
series->dataProxy()->addRow(data);
bars.addSeries(series);

Nota: Hemos configurado la ventana de datos a 5 x 5, pero sólo estamos añadiendo una fila de datos. Esto está bien, el resto de las filas estarán en blanco.

Finalmente necesitarás configurarla como visible:

bars.show();

El código completo necesario para crear y mostrar este gráfico es:

#include <QtDataVisualization>

int main(int argc, char **argv)
{
    qputenv("QSG_RHI_BACKEND", "opengl");
    QGuiApplication app(argc, argv);

    Q3DBars bars;
    bars.setFlags(bars.flags() ^ Qt::FramelessWindowHint);
    bars.rowAxis()->setRange(0, 4);
    bars.columnAxis()->setRange(0, 4);
    QBar3DSeries *series = new QBar3DSeries;
    QBarDataRow *data = new QBarDataRow;
    *data << 1.0f << 3.0f << 7.5f << 5.0f << 2.2f;
    series->dataProxy()->addRow(data);
    bars.addSeries(series);
    bars.show();

    return app.exec();
}

Y esto es lo que producen esas pocas líneas de código:

La escena se puede rotar, hacer zoom, y se puede seleccionar una barra para ver su valor, pero no se incluye ninguna otra interacción en este ejemplo de código mínimo. Puedes aprender más familiarizándote con los ejemplos proporcionados, como el Gráfico de Barras.

Véase también Q3DScatter, Q3DSurface, y Qt Data Visualization C++ Classes.

Documentación de propiedades

[since 6.3] barSeriesMargin : QSizeF

Margen entre las columnas de la serie en las dimensiones X y Z. Los valores sensibles están en el rango [0,1).

Preestablecido en (0.0, 0.0) por defecto. Esta propiedad permite mostrar barras de diferentes series una al lado de la otra, pero con espacio entre columnas.

Esta propiedad se introdujo en Qt 6.3.

Funciones de acceso:

QSizeF barSeriesMargin() const
void setBarSeriesMargin(const QSizeF &margin)

Señal Notifier:

void barSeriesMarginChanged(const QSizeF &margin)

Véase también barSpacing.

barSpacing : QSizeF

Espacio entre barras en las dimensiones X y Z.

Preestablecido en (1.0, 1.0) por defecto. El espaciado se ve afectado por la propiedad barSpacingRelative.

Funciones de acceso:

QSizeF barSpacing() const
void setBarSpacing(const QSizeF &spacing)

Señal del notificador:

void barSpacingChanged(const QSizeF &spacing)

Véase también barSpacingRelative, multiSeriesUniform, y barSeriesMargin.

barSpacingRelative : bool

Esta propiedad indica si el espaciado es absoluto o relativo al grosor de las barras.

Si es true, el valor de 0.0 significa que las barras se colocan de lado a lado, 1.0 significa que se deja entre las barras un espacio tan ancho como el grosor de una barra, y así sucesivamente. Preajuste a true.

Funciones de acceso:

bool isBarSpacingRelative() const
void setBarSpacingRelative(bool relative)

Señal de aviso:

void barSpacingRelativeChanged(bool relative)

barThickness : float

Esta propiedad contiene la relación de grosor de las barras entre las dimensiones X y Z.

El valor 1.0 significa que las barras son tan anchas como profundas, mientras que 0.5 las hace el doble de profundas que anchas. El valor por defecto es 1.0.

Funciones de acceso:

float barThickness() const
void setBarThickness(float thicknessRatio)

Señal de aviso:

void barThicknessChanged(float thicknessRatio)

columnAxis : QCategory3DAxis*

Esta propiedad contiene el eje adjunto a la columna activa.

Funciones de acceso:

QCategory3DAxis *columnAxis() const
void setColumnAxis(QCategory3DAxis *axis)

Señal del notificador:

void columnAxisChanged(QCategory3DAxis *axis)

floorLevel : float

Esta propiedad contiene el nivel del suelo para el gráfico de barras en coordenadas de datos del eje Y.

El nivel real del suelo estará restringido por los valores mínimo y máximo del eje Y. Por defecto es cero.

Funciones de acceso:

float floorLevel() const
void setFloorLevel(float level)

Señal del notificador:

void floorLevelChanged(float level)

multiSeriesUniform : bool

Esta propiedad mantiene si las barras deben ser escaladas con proporciones establecidas a una sola barra de serie incluso si hay múltiples series mostradas.

Si se establece a true, bar spacing se aplicará correctamente sólo al eje X. Preestablecido a false por defecto.

Funciones de acceso:

bool isMultiSeriesUniform() const
void setMultiSeriesUniform(bool uniform)

Señal de aviso:

void multiSeriesUniformChanged(bool uniform)

primarySeries : QBar3DSeries*

Esta propiedad contiene la serie primaria del gráfico.

Funciones de acceso:

QBar3DSeries *primarySeries() const
void setPrimarySeries(QBar3DSeries *series)

Señal del notificador:

void primarySeriesChanged(QBar3DSeries *series)

rowAxis : QCategory3DAxis*

Esta propiedad contiene el eje adjunto a la fila activa.

Funciones de acceso:

QCategory3DAxis *rowAxis() const
void setRowAxis(QCategory3DAxis *axis)

Señal del notificador:

void rowAxisChanged(QCategory3DAxis *axis)

[read-only] selectedSeries : QBar3DSeries*

Esta propiedad contiene la serie seleccionada o un valor nulo.

Si selectionMode tiene el indicador SelectionMultiSeries, esta propiedad contiene la serie a la que pertenece la barra seleccionada.

Funciones de acceso:

QBar3DSeries *selectedSeries() const

Señal del notificador:

void selectedSeriesChanged(QBar3DSeries *series)

valueAxis : QValue3DAxis*

Establece el eje de valor activo (el eje Y) en axis. Llama implícitamente a addAxis() para transferir la propiedad de axis a este gráfico.

Si axis es nulo, se crea un eje temporal por defecto sin etiquetas y con un rango que se ajusta automáticamente. Este eje temporal se destruye si se establece explícitamente otro eje con la misma orientación.

Funciones de acceso:

QValue3DAxis *valueAxis() const
void setValueAxis(QValue3DAxis *axis)

Señal notificadora:

void valueAxisChanged(QValue3DAxis *axis)

Véase también addAxis() y releaseAxis().

Documentación de las funciones miembro

[explicit] Q3DBars::Q3DBars(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)

Construye un nuevo gráfico de barras 3D con la ventana opcional parent y la superficie format.

[virtual noexcept] Q3DBars::~Q3DBars()

Destruye el gráfico de barras 3D.

void Q3DBars::addAxis(QAbstract3DAxis *axis)

Añade axis al gráfico. Los ejes añadidos a través de addAxis aún no se toman para su uso, addAxis se utiliza simplemente para dar la propiedad de la axis al gráfico. El axis no debe ser nulo ni estar añadido a otro gráfico.

Véase también releaseAxis(), setValueAxis(), setRowAxis(), y setColumnAxis().

void Q3DBars::addSeries(QBar3DSeries *series)

Añade series al gráfico. Un gráfico puede contener múltiples series, pero sólo un conjunto de ejes, por lo que las filas y columnas de todas las series deben coincidir para que los datos visualizados tengan sentido. Si el gráfico tiene múltiples series visibles, sólo la serie primaria generará las etiquetas de fila o columna en los ejes en los casos en que las etiquetas no estén explícitamente establecidas en los ejes. Si la serie recién añadida ha especificado una barra seleccionada, se resaltará y se borrará cualquier selección existente. Sólo una serie añadida puede tener una selección activa.

Véase también seriesList(), primarySeries, y QAbstract3DGraph::hasSeries().

QList<QAbstract3DAxis *> Q3DBars::axes() const

Devuelve la lista de todos los ejes añadidos.

Véase también addAxis().

void Q3DBars::insertSeries(int index, QBar3DSeries *series)

Inserta el series en la posición index de la lista de series. Si la series ya ha sido añadida a la lista, se mueve a la nueva index.

Nota: Cuando se mueve una serie a un nuevo index que está después de su antiguo índice, la nueva posición en la lista se calcula como si la serie estuviera todavía en su antiguo índice, por lo que el índice final es en realidad el index decrementado en uno.

Véase también addSeries(), seriesList() y QAbstract3DGraph::hasSeries().

void Q3DBars::releaseAxis(QAbstract3DAxis *axis)

Devuelve la propiedad de axis a quien lo solicitó, si se ha añadido a este gráfico. Si el axis liberado está en uso, se creará un nuevo eje por defecto y se activará.

Si el eje por defecto se libera y se vuelve a añadir más tarde, se comporta como cualquier otro eje.

Véase también addAxis(), setValueAxis(), setRowAxis() y setColumnAxis().

void Q3DBars::removeSeries(QBar3DSeries *series)

Elimina la dirección series del gráfico.

Véase también QAbstract3DGraph::hasSeries().

QList<QBar3DSeries *> Q3DBars::seriesList() const

Devuelve la lista de series añadidas a este gráfico.

Véase también QAbstract3DGraph::hasSeries().

void Q3DBars::setColumnAxis(QCategory3DAxis *axis)

Establece el eje de la columna activa en axis. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje temporal por defecto sin etiquetas. Este eje temporal se destruye si se establece explícitamente otro eje con la misma orientación.

Nota: Función setter para la propiedad columnAxis.

Véase también columnAxis(), addAxis(), y releaseAxis().

void Q3DBars::setPrimarySeries(QBar3DSeries *series)

Establece series como la serie primaria del gráfico. La serie primaria determina las etiquetas de los ejes de fila y columna cuando las etiquetas no se establecen explícitamente en los ejes.

Si la serie especificada aún no se ha añadido al gráfico, al establecerla como serie primaria también se añadirá implícitamente al gráfico.

Si la serie primaria se elimina del gráfico, esta propiedad vuelve a su valor por defecto.

Si series es nulo, esta propiedad se restablece por defecto. Por defecto es la primera serie añadida o cero si no se añade ninguna serie al gráfico.

Nota: Función setter para la propiedad primarySeries.

Véase también primarySeries().

void Q3DBars::setRowAxis(QCategory3DAxis *axis)

Establece el eje de la fila activa en axis. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje temporal por defecto sin etiquetas. Este eje temporal se destruye si se establece explícitamente otro eje con la misma orientación.

Nota: Función setter para la propiedad rowAxis.

Véase también rowAxis(), addAxis(), y releaseAxis().

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