Q3DSurfaceWidgetItem Class
La clase Q3DSurfaceWidgetItem proporciona métodos para la representación de gráficos 3D de superficie. Más...
| Cabecera: | #include <Q3DSurfaceWidgetItem> |
| 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
- Q3DSurfaceWidgetItem es parte de Qt Graphs C++ Classes for Widgets.
Propiedades
|
Funciones públicas
| Q3DSurfaceWidgetItem(QObject *parent = nullptr) | |
| virtual | ~Q3DSurfaceWidgetItem() override |
| void | addAxis(QValue3DAxis *axis) |
| void | addSeries(QSurface3DSeries *series) |
| QList<QValue3DAxis *> | axes() const |
| QValue3DAxis * | axisX() const |
| QValue3DAxis * | axisY() const |
| QValue3DAxis * | axisZ() const |
| bool | flipHorizontalGrid() const |
| void | releaseAxis(QValue3DAxis *axis) |
| void | removeSeries(QSurface3DSeries *series) |
(since 6.10) void | renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType) |
| QSurface3DSeries * | selectedSeries() const |
| QList<QSurface3DSeries *> | seriesList() const |
| void | setAxisX(QValue3DAxis *axis) |
| void | setAxisY(QValue3DAxis *axis) |
| void | setAxisZ(QValue3DAxis *axis) |
| void | setFlipHorizontalGrid(bool flip) |
Señales
| void | axisXChanged(QValue3DAxis *axis) |
| void | axisYChanged(QValue3DAxis *axis) |
| void | axisZChanged(QValue3DAxis *axis) |
| void | flipHorizontalGridChanged(bool flip) |
| void | selectedSeriesChanged(QSurface3DSeries *series) |
(since 6.10) void | sliceImageChanged(const QImage &image) |
Descripción detallada
Esta clase permite a los desarrolladores renderizar superficies 3D y visualizarlas rotando la escena libremente. Las propiedades visuales de la superficie, como el modo de dibujo y el sombreado, pueden controlarse a través de QSurface3DSeries.
El Q3DSurfaceWidgetItem soporta la selección mostrando una bola resaltada sobre el punto de datos en el que el usuario ha hecho clic con el botón izquierdo del ratón (cuando se utiliza el manejador de entrada por defecto) o seleccionado a través de QSurface3DSeries. El puntero de selección va acompañado de una etiqueta, que en el caso por defecto muestra el valor del punto de datos y las coordenadas del punto.
El rango de valores y el formato de la etiqueta mostrada en el eje pueden controlarse a través de QValue3DAxis.
Para girar el gráfico, mantenga pulsado el botón derecho del ratón y mueva el ratón. El zoom se realiza utilizando la rueda del ratón. Ambas acciones asumen que el manejador de entrada por defecto está en uso.
Si no se establecen ejes explícitamente para Q3DSurfaceWidgetItem, 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 es destruido.
Cómo construir un gráfico mínimo Q3DSurfaceWidgetItem
En primer lugar, construye Q3DSurfaceWidgetItem. Dado que en este ejemplo estamos ejecutando el gráfico como una ventana de nivel superior, necesitamos borrar la bandera Qt::FramelessWindowHint, que está establecida por defecto:
QQuickWidget quickWidget; Q3DSurfaceWidgetItem surface; surface.setWidget(&quickWidget); surface.widget()->setMinimumSize(QSize(256, 256));
Ahora Q3DSurfaceWidgetItem está listo para recibir datos para ser renderizados. Crear elementos de datos para recibir valores:
Nota: En la nueva relación proxy-serie, los datos se mantienen en serie. Por lo tanto, para que el proxy pueda añadir, eliminar o editar los datos, es un requisito previo crear primero una serie.
QSurfaceDataArray data; QSurfaceDataRow dataRow1; QSurfaceDataRow dataRow2;
En primer lugar, introduzca los datos en los elementos de fila y, a continuación, añada sus punteros al elemento de datos:
dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f); dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f); data << dataRow1 << dataRow2;
Cree una nueva serie y añádale datos:
QSurface3DSeries series; series.dataProxy()->resetArray(data); surface.addSeries(&series);
Por último, deberá hacerla visible:
surface.widget()->show();
El código completo necesario para crear y mostrar este gráfico es:
#include <QtGraphs> #include <QtGraphsWidgets/q3dsurfacewidgetitem.h> #include <QtWidgets/qapplication.h> int main(int argc, char **argv) { QApplication app(argc, argv); QQuickWidget quickWidget; Q3DSurfaceWidgetItem surface; surface.setWidget(&quickWidget); surface.widget()->setMinimumSize(QSize(256, 256)); QSurfaceDataArray data; QSurfaceDataRow dataRow1; QSurfaceDataRow dataRow2; dataRow1 << QSurfaceDataItem(0.0f, 0.1f, 0.5f) << QSurfaceDataItem(1.0f, 0.5f, 0.5f); dataRow2 << QSurfaceDataItem(0.0f, 1.8f, 1.0f) << QSurfaceDataItem(1.0f, 1.2f, 1.0f); data << dataRow1 << dataRow2; QSurface3DSeries series; series.dataProxy()->resetArray(data); surface.addSeries(&series); surface.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 un punto de la superficie para ver su posición, pero no se incluyen otras interacciones en este ejemplo de código mínimo. Puedes aprender más familiarizándote con los ejemplos proporcionados, como la Galería de gráficos de superficie.
Vea también Q3DBarsWidgetItem, Q3DScatterWidgetItem, y Qt Graphs C++ Classes for 3D.
Documentación de propiedades
axisX : QValue3DAxis*
Esta propiedad mantiene el eje x activo.
Establece axis como eje x activo. 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 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 * | axisX() const |
| void | setAxisX(QValue3DAxis *axis) |
Señal del notificador:
| void | axisXChanged(QValue3DAxis *axis) |
Véase también addAxis() y releaseAxis().
axisY : QValue3DAxis*
Esta propiedad mantiene el eje y activo.
Establece axis como el eje y activo. 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 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 * | axisY() const |
| void | setAxisY(QValue3DAxis *axis) |
Señal del notificador:
| void | axisYChanged(QValue3DAxis *axis) |
Véase también addAxis() y releaseAxis().
axisZ : QValue3DAxis*
Esta propiedad mantiene el eje z activo.
Establece axis como el eje z activo. 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 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 * | axisZ() const |
| void | setAxisZ(QValue3DAxis *axis) |
Señal del notificador:
| void | axisZChanged(QValue3DAxis *axis) |
Véase también addAxis() y releaseAxis().
flipHorizontalGrid : bool
Esta propiedad determina si la rejilla del eje horizontal se muestra en la parte superior del gráfico en lugar de en la parte inferior.
En algunos casos de uso, la rejilla del eje horizontal está cubierta en su mayor parte por la superficie, por lo que puede ser más útil mostrar la rejilla del eje horizontal en la parte superior del gráfico que en la parte inferior. Un caso típico es la visualización de espectrogramas 2D mediante proyección ortográfica con un punto de vista descendente.
Si false, la rejilla del eje horizontal y las etiquetas se dibujan sobre el fondo horizontal del gráfico. Si true, la rejilla del eje horizontal y las etiquetas se dibujan en el lado opuesto del gráfico respecto al fondo horizontal. Por defecto es false.
Funciones de acceso:
| bool | flipHorizontalGrid() const |
| void | setFlipHorizontalGrid(bool flip) |
Señal del notificador:
| void | flipHorizontalGridChanged(bool flip) |
[read-only] selectedSeries : QSurface3DSeries*
Esta propiedad contiene la serie seleccionada o null.
Si selectionMode tiene MultiSeries, esta propiedad contiene la serie a la que pertenece el punto seleccionado.
Funciones de acceso:
| QSurface3DSeries * | selectedSeries() const |
Señal del notificador:
| void | selectedSeriesChanged(QSurface3DSeries *series) |
Documentación de Funciones Miembro
[explicit] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)
Construye un nuevo gráfico de superficie 3D con la dirección opcional parent.
[override virtual noexcept] Q3DSurfaceWidgetItem::~Q3DSurfaceWidgetItem()
Destruye el gráfico de superficie 3D.
void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *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(), setAxisX(), setAxisY(), y setAxisZ().
void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)
Añade series al gráfico. Un gráfico puede contener múltiples series, pero sólo tiene un conjunto de ejes. Si la serie recién añadida ha especificado un elemento seleccionado, 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 Q3DGraphsWidgetItem::hasSeries().
QList<QValue3DAxis *> Q3DSurfaceWidgetItem::axes() const
Devuelve la lista de todos los ejes añadidos.
Véase también addAxis().
void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *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(), setAxisX(), setAxisY() y setAxisZ().
void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)
Elimina la dirección series del gráfico.
Véase también Q3DGraphsWidgetItem::hasSeries().
[since 6.10] void Q3DSurfaceWidgetItem::renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
Exporta la vista en rodajas solicitada a una imagen. El resultado rebanado es la serie de index. Para exportar todas las series, establezca index en -1. La rebanada exportada es una línea de fila o columna, que se define mediante sliceType, en un requestedIndex dado.
La señal sliceImageChanged se emite cuando la imagen está lista:
connect(item, &Q3DSurfaceWidgetItem::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<QSurface3DSeries *> Q3DSurfaceWidgetItem::seriesList() const
Devuelve la lista de series añadidas a este gráfico.
Véase también Q3DGraphsWidgetItem::hasSeries().
[signal, since 6.10] void Q3DSurfaceWidgetItem::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.