Q3DBarsWidgetItem Class
La clase Q3DBarsWidgetItem proporciona métodos para representar gráficos de barras en 3D. Más...
| Cabecera: | #include <Q3DBarsWidgetItem> |
| CMake: | find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets) |
| qmake: | QT += graphswidgets |
| Hereda: | Q3DGraphsWidgetItem |
- Lista de todos los miembros, incluyendo los heredados
- Q3DBarsWidgetItem es parte de Qt Graphs C++ Classes for Widgets.
Propiedades
|
|
Funciones públicas
| Q3DBarsWidgetItem(QObject *parent = nullptr) | |
| virtual | ~Q3DBarsWidgetItem() override |
| 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) |
(since 6.10) void | renderSliceToImage(int requestedIndex, QtGraphs3D::SliceCaptureType sliceType) |
| QCategory3DAxis * | rowAxis() const |
| QBar3DSeries * | selectedSeries() const |
| QList<QBar3DSeries *> | seriesList() const |
| void | setBarSeriesMargin(QSizeF margin) |
| void | setBarSpacing(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(QSizeF margin) |
| void | barSpacingChanged(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) |
(since 6.10) void | sliceImageChanged(const QImage &image) |
| void | valueAxisChanged(QValue3DAxis *axis) |
Descripción detallada
Esta clase permite a los desarrolladores renderizar gráficos de barras en 3D y visualizarlos girando libremente la escena. La rotación se consigue manteniendo pulsado el botón derecho del ratón y moviendo el ratón, mientras que el zoom se realiza utilizando la rueda del ratón. Si está activada, la selección se realiza con el botón izquierdo del ratón. La escena puede restablecerse a la vista de cámara predeterminada pulsando la rueda del ratón. En dispositivos táctiles, la rotación se consigue pulsando y moviendo, la selección pulsando y manteniendo pulsado, y el zoom pellizcando.
Si no se establecen ejes explícitamente para Q3DBarsWidgetItem, 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.
Q3DBarsWidgetItem admite más de una serie visible al mismo tiempo. No es necesario que todas las series tengan el mismo número 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 para los ejes de filas y columnas.
Q3DBarsWidgetItem tiene soporte para transparencia. Esta característica permite ajustar la opacidad de las barras, haciéndolas parcialmente transparentes, totalmente transparentes u opacas.
Cómo construir un gráfico mínimo de Q3DBarsWidgetItem
En primer lugar, construye una instancia de Q3DBarsWidgetItem:
QQuickWidget quickWidget; Q3DBarsWidgetItem bars; bars.setWidget(&quickWidget); bars.widget()->setMinimumSize(QSize(256, 256));
Después de construir Q3DBarsWidgetItem, puedes configurar la ventana de datos cambiando el rango en los ejes de filas y columnas. 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, normalmente es preferible mostrar sólo una parte. Por ejemplo, configuremos la ventana de datos para que muestre las cinco primeras filas y columnas:
bars.rowAxis()->setRange(0, 4); bars.columnAxis()->setRange(0, 4);
Ahora, Q3DBarsWidgetItem está listo para recibir datos para ser renderizados. Crea una serie con una fila de 5 valores:
QBar3DSeries series; QBarDataRow data; data << QBarDataItem(1.0f) << QBarDataItem(3.0f) << QBarDataItem(7.5f) << QBarDataItem(5.0f) << QBarDataItem(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.widget()->show();
El código completo necesario para crear y mostrar este gráfico es:
#include <QtGraphs> #include <QtGraphsWidgets/q3dbarswidgetitem.h> #include <QtWidgets/qapplication.h> int main(int argc, char **argv) { QApplication app(argc, argv); QQuickWidget quickWidget; Q3DBarsWidgetItem bars; bars.setWidget(&quickWidget); bars.widget()->setMinimumSize(QSize(256, 256)); bars.rowAxis()->setRange(0, 4); bars.columnAxis()->setRange(0, 4); QBar3DSeries series; QBarDataRow data; data << QBarDataItem(1.0f) << QBarDataItem(3.0f) << QBarDataItem(7.5f) << QBarDataItem(5.0f) << QBarDataItem(2.2f); series.dataProxy()->addRow(data); bars.addSeries(&series); bars.widget()->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 incluyen otras interacciones en este ejemplo de código mínimo. Puede aprender más familiarizándose con los ejemplos proporcionados, como el Gráfico de barras simple.
Vea también Q3DScatterWidgetItem, Q3DSurfaceWidgetItem, y Qt Graphs C++ Classes for 3D.
Documentación de Propiedades
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.
Funciones de acceso:
| QSizeF | barSeriesMargin() const |
| void | setBarSeriesMargin(QSizeF margin) |
Señal del notificador:
| void | barSeriesMarginChanged(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(QSizeF spacing) |
Señal del notificador:
| void | barSpacingChanged(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.
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.
Funciones de acceso:
| QCategory3DAxis * | columnAxis() const |
| void | setColumnAxis(QCategory3DAxis *axis) |
Señal del notificador:
| void | columnAxisChanged(QCategory3DAxis *axis) |
Véase también addAxis() y releaseAxis().
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.
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.
Funciones de acceso:
| QBar3DSeries * | primarySeries() const |
| void | setPrimarySeries(QBar3DSeries *series) |
Señal de notificador:
| void | primarySeriesChanged(QBar3DSeries *series) |
rowAxis : QCategory3DAxis*
Esta propiedad contiene el eje adjunto a la fila activa.
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.
Funciones de acceso:
| QCategory3DAxis * | rowAxis() const |
| void | setRowAxis(QCategory3DAxis *axis) |
Señal del notificador:
| void | rowAxisChanged(QCategory3DAxis *axis) |
Véase también addAxis() y releaseAxis().
[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] Q3DBarsWidgetItem::Q3DBarsWidgetItem(QObject *parent = nullptr)
Construye un nuevo gráfico de barras 3D con la opción parent.
[override virtual noexcept] Q3DBarsWidgetItem::~Q3DBarsWidgetItem()
Destruye el gráfico de barras 3D.
void Q3DBarsWidgetItem::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 Q3DBarsWidgetItem::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 se hayan establecido explícitamente para los ejes. Si la serie recién añadida ha especificado una barra seleccionada, ésta 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 Q3DGraphsWidgetItem::hasSeries().
QList<QAbstract3DAxis *> Q3DBarsWidgetItem::axes() const
Devuelve la lista de todos los ejes añadidos.
Véase también addAxis().
void Q3DBarsWidgetItem::insertSeries(int index, QBar3DSeries *series)
Inserta el series en la posición index de la lista de series. Si la series ya se ha añadido 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 Q3DGraphsWidgetItem::hasSeries().
void Q3DBarsWidgetItem::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 Q3DBarsWidgetItem::removeSeries(QBar3DSeries *series)
Elimina la dirección series del gráfico.
Véase también Q3DGraphsWidgetItem::hasSeries().
[since 6.10] void Q3DBarsWidgetItem::renderSliceToImage(int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
Exporta la vista de corte solicitada a una imagen. El slice exportado son barras de fila o columna, que se define por sliceType, en un determinado requestedIndex.
La señal sliceImageChanged se emite cuando la imagen está lista:
connect(item, &Q3DBarsWidgetItem::sliceImageChanged, this, [](const QImage &image) { // ~~~ }); item->renderSliceToImage(sliceType, index);
La imagen se renderiza con la configuración actual de antialiasing.
Esta función se introdujo en Qt 6.10.
Véase también QQuickItem::grabToImage() y sliceImageChanged().
QList<QBar3DSeries *> Q3DBarsWidgetItem::seriesList() const
Devuelve la lista de series añadidas a este gráfico.
Véase también Q3DGraphsWidgetItem::hasSeries().
[signal, since 6.10] void Q3DBarsWidgetItem::sliceImageChanged(const QImage &image)
Se emite cuando renderSliceToImage ha preparado la image.
Esta función se introdujo en Qt 6.10.
© 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.