En esta página

Q3DBarsWidgetItem Class

La clase Q3DBarsWidgetItem proporciona métodos para representar gráficos de barras en 3D. Más información...

Encabezado: #include <Q3DBarsWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake: QT += graphswidgets
Heredan: Q3DGraphsWidgetItem

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
QValue3DAxis *valueAxis() const

Ranuras públicas

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)

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 realiza manteniendo pulsado el botón derecho del ratón y moviendo el ratón, mientras que el zoom se controla con la rueda del ratón. Si está habilitada, la selección se realiza con el botón izquierdo del ratón. La escena se puede restablecer a la vista predeterminada de la cámara haciendo clic con la rueda del ratón. En dispositivos táctiles, la rotación se realiza tocando y desplazando, la selección tocando y manteniendo pulsado, y el zoom pellizcando.

Si no se definen ejes de forma explícita para Q3DBarsWidgetItem, se crean ejes predeterminados temporales sin etiquetas. Estos ejes predeterminados pueden modificarse mediante los accesores de ejes, pero tan pronto como se defina explícitamente cualquier eje para la orientación, el eje predeterminado para esa orientación se elimina.

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 admite la transparencia. Esta característica permite ajustar la opacidad de las barras, haciéndolas parcialmente translúcidas, totalmente transparentes u opacas.

Cómo crear un gráfico mínimo con Q3DBarsWidgetItem

En primer lugar, crea una instancia de Q3DBarsWidgetItem:

QQuickWidget quickWidget;
Q3DBarsWidgetItem bars;
bars.setWidget(&quickWidget);
bars.widget()->setMinimumSize(QSize(256, 256));

Tras crear Q3DBarsWidgetItem, puede configurar la ventana de datos modificando el rango de los ejes de filas y columnas. No es obligatorio, ya que, por defecto, la ventana de datos mostrará todos los datos de la serie. Si la cantidad de datos es grande, suele ser preferible mostrar solo una parte de ellos. Por ejemplo, configuremos la ventana de datos para que muestre las primeras cinco filas y columnas:

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

Ahora, Q3DBarsWidgetItem está listo para recibir los datos que se van a representar. 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 en 5 x 5, pero solo vamos a añadir una fila de datos. No pasa nada; el resto de las filas simplemente quedarán en blanco.

Por último, tendrás que configurarlo para que sea 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:

Gráfico de barras en 3D con barras verdes de diferentes alturas

La escena se puede girar, ampliar y se puede seleccionar una barra para ver su valor, pero en este ejemplo de código mínimo no se incluyen otras interacciones. Puedes obtener más información familiarizándote con los ejemplos proporcionados, como el «Gráfico de barras sencillo».

Véase también Q3DScatterWidgetItem, Q3DSurfaceWidgetItem y Qt Graphs : clases de C++ para 3D.

Documentación de propiedades

barSeriesMargin : QSizeF

Margen entre las columnas de las series en las dimensiones X y Z. Los valores recomendados se encuentran en el intervalo [0,1).

El valor predeterminado es « (0.0, 0.0) ». Esta propiedad permite mostrar barras de diferentes series una al lado de otra, pero con espacio entre las columnas.

Funciones de acceso:

QSizeF barSeriesMargin() const
void setBarSeriesMargin(QSizeF margin)

Señal de notificación:

void barSeriesMarginChanged(QSizeF margin)

Véase también barSpacing.

barSpacing : QSizeF

Espaciado entre barras en las dimensiones X y Z.

El valor predeterminado es « (1.0, 1.0) ». El espaciado se ve afectado por la propiedad « barSpacingRelative ».

Funciones de acceso:

QSizeF barSpacing() const
void setBarSpacing(QSizeF spacing)

Señal de notificación:

void barSpacingChanged(QSizeF spacing)

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

barSpacingRelative : bool

Esta propiedad se aplica tanto si el espaciado es absoluto como si es relativo al grosor de la barra.

Si se establece en « true », el valor « 0.0 » significa que las barras se colocan una al lado de la otra; « 1.0 » significa que se deja un espacio entre las barras del mismo ancho que el grosor de una barra, y así sucesivamente. El valor predeterminado es « true ».

Funciones de acceso:

bool isBarSpacingRelative() const
void setBarSpacingRelative(bool relative)

Señal de notificación:

void barSpacingRelativeChanged(bool relative)

barThickness : float

Esta propiedad establece la relación entre el grosor de la barra en las dimensiones X y Z.

El valor « 1.0 » significa que las barras tienen la misma anchura que profundidad, mientras que « 0.5 » hace que sean el doble de profundas que anchas. El valor predeterminado es « 1.0 ».

Funciones de acceso:

float barThickness() const
void setBarThickness(float thicknessRatio)

Señal de notificación:

void barThicknessChanged(float thicknessRatio)

columnAxis : QCategory3DAxis*

Esta propiedad contiene el eje asociado 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 predeterminado temporal sin etiquetas. Este eje temporal se elimina si se establece explícitamente otro eje con la misma orientación.

Funciones de acceso:

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

Señal de notificador:

void columnAxisChanged(QCategory3DAxis *axis)

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

floorLevel : float

Esta propiedad establece el nivel mínimo del gráfico de barras en las coordenadas de datos del eje Y.

El nivel de base real estará limitado por los valores mínimo y máximo del eje Y. El valor por defecto es cero.

Funciones de acceso:

float floorLevel() const
void setFloorLevel(float level)

Señal de notificación:

void floorLevelChanged(float level)

multiSeriesUniform : bool

Esta propiedad se mantiene independientemente de si las barras se van a escalar con las proporciones establecidas para una sola barra de serie, incluso si se muestran varias series.

Si se establece en « true », la opción « bar spacing » se aplicará correctamente solo al eje X. El valor predeterminado es « false ».

Funciones de acceso:

bool isMultiSeriesUniform() const
void setMultiSeriesUniform(bool uniform)

Señal de notificación:

void multiSeriesUniformChanged(bool uniform)

primarySeries : QBar3DSeries*

Esta propiedad contiene la serie principal del gráfico.

Establece « series » como la serie principal del gráfico. La serie principal determina las etiquetas de los ejes de filas y columnas cuando estas no se han establecido explícitamente en los ejes.

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

Si la propia serie principal se elimina del gráfico, esta propiedad se restablece a su valor por defecto.

Si series es nulo, esta propiedad se restablece a su valor predeterminado. El valor predeterminado es la primera serie añadida o cero si no se ha añadido ninguna serie al gráfico.

Funciones de acceso:

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

Señal de notificación:

void primarySeriesChanged(QBar3DSeries *series)

rowAxis : QCategory3DAxis*

Esta propiedad contiene el eje asociado 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 de 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 la opción «selectionMode» tiene activada la bandera « SelectionMultiSeries », esta propiedad contiene la serie a la que pertenece la barra seleccionada.

Funciones de acceso:

QBar3DSeries *selectedSeries() const

Señal de notificador:

void selectedSeriesChanged(QBar3DSeries *series)

valueAxis : QValue3DAxis*

Establece el eje de valores 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 elimina si se establece explícitamente otro eje con la misma orientación.

Funciones de acceso:

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

Señal de notificador:

void valueAxisChanged(QValue3DAxis *axis)

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

Documentación de funciones de miembro

[explicit] Q3DBarsWidgetItem::Q3DBarsWidgetItem(QObject *parent = nullptr)

Crea un nuevo gráfico de barras en 3D con la opción « parent ».

[override virtual noexcept] Q3DBarsWidgetItem::~Q3DBarsWidgetItem()

Elimina el gráfico de barras en 3D.

void Q3DBarsWidgetItem::addAxis(QAbstract3DAxis *axis)

Añade axis al gráfico. Los ejes añadidos mediante addAxis aún no se consideran en uso; addAxis se utiliza simplemente para asignar la propiedad de axis al gráfico. 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 la serie « series » al gráfico. Un gráfico puede contener varias series, pero solo 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 varias series visibles, solo la serie principal generará las etiquetas de fila o columna en los ejes en los casos en que dichas etiquetas no se hayan establecido explícitamente para los ejes. Si la serie recién añadida ha especificado una barra seleccionada, esta se resaltará y se borrará cualquier selección existente. Solo una de las series añadidas 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 el series ya se ha añadido a la lista, se desplaza a la nueva index.

Nota: Al mover una serie a una nueva index que se encuentra después de su antiguo índice, la nueva posición en la lista se calcula como si la serie siguiera en su antiguo índice, por lo que el índice final es, en realidad, el index decrementado en uno.

Véanse también addSeries(), seriesList() y Q3DGraphsWidgetItem::hasSeries().

void Q3DBarsWidgetItem::releaseAxis(QAbstract3DAxis *axis)

Devuelve la propiedad del « axis » al llamante, 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 predeterminado se libera y se vuelve a añadir más tarde, se comportará como cualquier otro eje.

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

void Q3DBarsWidgetItem::removeSeries(QBar3DSeries *series)

Elimina el « 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 corte exportado está formado por barras de fila o columna, definidas por ` sliceType`, en una ` requestedIndex` determinada.

La señal sliceImageChanged se emite cuando la imagen está lista y puede capturarse de la siguiente manera:

connect(item, &Q3DBarsWidgetItem::sliceImageChanged, this, [](const QImage &image) {
    // ~~~
});

item->renderSliceToImage(sliceType, index);

La imagen se renderiza con la configuración actual de suavizado.

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