Manejo de ejes
Implementación del arrastre de ejes con un controlador de entrada personalizado en QML y creación de un formateador de ejes personalizado.
El manejo de ejes muestra dos características personalizadas diferentes relacionadas con los ejes. Estas características tienen sus propias pestañas en la aplicación.
Las siguientes secciones se centran únicamente en esas funciones y omiten la explicación de la funcionalidad básica; para obtener documentación más detallada con ejemplos de QML, consulta «Gráfico de dispersión sencillo».

Ejecución del ejemplo
Puede ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde « Command Palette » y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
Arrastrar ejes
En la pestaña « Axis Dragging », implementa un controlador de entrada personalizado en QML que te permita arrastrar las etiquetas de los ejes para cambiar sus rangos. Además, utiliza la proyección ortográfica y actualiza dinámicamente las propiedades de un elemento personalizado.
Sobrescritura del manejo de entradas predeterminado
Para desactivar el mecanismo predeterminado de gestión de entradas, configura el controlador de entrada activo del gráfico Scatter3D en « null »:
Scatter3D {
id: scatterGraph
inputHandler: null
...A continuación, añade un « MouseArea » y configúralo para que ocupe todo el espacio del elemento padre, que es el mismo « Item » en el que se encuentra nuestro « scatterGraph ». Además, configúralo para que solo acepte pulsaciones del botón izquierdo del ratón, ya que en este ejemplo no se necesitan los demás botones:
MouseArea {
anchors.fill: parent
hoverEnabled: true
acceptedButtons: Qt.LeftButton
...A continuación, escucha las pulsaciones del ratón y, cuando se detecte una, envía una consulta de selección al gráfico:
onPressed: (mouse)=> {
scatterGraph.scene.selectionQueryPosition = Qt.point(mouse.x, mouse.y);
}El controlador de la señal « onPositionChanged » detecta la posición actual del ratón, que será necesaria para calcular la distancia de desplazamiento:
onPositionChanged: (mouse)=> {
currentMouseX = mouse.x;
currentMouseY = mouse.y;
...Al final de ` onPositionChanged`, guarda la posición anterior del ratón para el cálculo de la distancia de desplazamiento que se introducirá más adelante:
...
previousMouseX = currentMouseX;
previousMouseY = currentMouseY;
}Traducir el movimiento del ratón en un cambio en el rango de los ejes
En ` scatterGraph`, escucha la señal ` onSelectedElementChanged`. Esta señal se emite después de que se haya realizado la consulta de selección en el ` onPressed ` del ` inputArea`. Establece el tipo de elemento en una propiedad que hayas definido (property int selectedAxisLabel: -1) en el componente principal, ya que es del tipo que te interesa:
onSelectedElementChanged: {
if (selectedElement >= AbstractGraph3D.ElementAxisXLabel
&& selectedElement <= AbstractGraph3D.ElementAxisZLabel) {
selectedAxisLabel = selectedElement;
} else {
selectedAxisLabel = -1;
}
}A continuación, de vuelta en el método ` onPositionChanged ` de inputArea, comprueba si se ha pulsado un botón del ratón y si hay una selección de etiqueta de eje activa. Si se cumplen las condiciones, llama a la función que realiza la conversión del movimiento del ratón a la actualización del rango del eje:
...
if (pressed && selectedAxisLabel != -1)
axisDragView.dragAxis();
...La conversión es sencilla en este caso, ya que la rotación de la cámara es fija. Puedes utilizar algunos valores precalculados, calcular la distancia de desplazamiento del ratón y aplicar los valores al rango del eje seleccionado:
function dragAxis() {
// Do nothing if previous mouse position is uninitialized
if (previousMouseX === -1)
return;
// Directional drag multipliers based on rotation. Camera is locked to 45 degrees, so we
// can use one precalculated value instead of calculating xx, xy, zx and zy individually
var cameraMultiplier = 0.70710678;
// Calculate the mouse move amount
var moveX = currentMouseX - previousMouseX;
var moveY = currentMouseY - previousMouseY;
// Adjust axes
switch (selectedAxisLabel) {
case AbstractGraph3D.ElementAxisXLabel:
var distance = ((moveX - moveY) * cameraMultiplier) / dragSpeedModifier;
// Check if we need to change min or max first to avoid invalid ranges
if (distance > 0) {
scatterGraph.axisX.min -= distance;
scatterGraph.axisX.max -= distance;
} else {
scatterGraph.axisX.max -= distance;
scatterGraph.axisX.min -= distance;
}
break;
case AbstractGraph3D.ElementAxisYLabel:
distance = moveY / dragSpeedModifier;
// Check if we need to change min or max first to avoid invalid ranges
if (distance > 0) {
scatterGraph.axisY.max += distance;
scatterGraph.axisY.min += distance;
} else {
scatterGraph.axisY.min += distance;
scatterGraph.axisY.max += distance;
}
break;
case AbstractGraph3D.ElementAxisZLabel:
distance = ((moveX + moveY) * cameraMultiplier) / dragSpeedModifier;
// Check if we need to change min or max first to avoid invalid ranges
if (distance > 0) {
scatterGraph.axisZ.max += distance;
scatterGraph.axisZ.min += distance;
} else {
scatterGraph.axisZ.min += distance;
scatterGraph.axisZ.max += distance;
}
break;
}
}Para una conversión más sofisticada del movimiento del ratón a la actualización del rango de los ejes, consulta la Galería de gráficos.
Otras características
El ejemplo también muestra cómo utilizar la proyección ortográfica y cómo actualizar las propiedades de un elemento personalizado sobre la marcha.
La proyección ortográfica es muy sencilla. Solo tendrás que cambiar la propiedad « orthoProjection » de « scatterGraph ». El ejemplo incluye un botón para activarla y desactivarla:
Button {
id: orthoToggle
width: axisDragView.portraitMode ? parent.width : parent.width / 3
text: "Display Orthographic"
anchors.left: axisDragView.portraitMode ? parent.left : rangeToggle.right
anchors.top: axisDragView.portraitMode ? rangeToggle.bottom : parent.top
onClicked: {
if (scatterGraph.orthoProjection) {
text = "Display Orthographic";
scatterGraph.orthoProjection = false;
// Orthographic projection disables shadows, so we need to switch them back on
scatterGraph.shadowQuality = AbstractGraph3D.ShadowQualityMedium
} else {
text = "Display Perspective";
scatterGraph.orthoProjection = true;
}
}
}Para los elementos personalizados, añade uno a la propiedad ` customItemList ` de ` scatterGraph`:
customItemList: [
Custom3DItem {
id: qtCube
meshFile: ":/qml/qmlaxishandling/cube.obj"
textureFile: ":/qml/qmlaxishandling/cubetexture.png"
position: Qt.vector3d(0.65, 0.35, 0.65)
scaling: Qt.vector3d(0.3, 0.3, 0.3)
}
]Implementa un temporizador para añadir, eliminar y rotar todos los elementos del gráfico, y utiliza el mismo temporizador para rotar el elemento personalizado:
onTriggered: {
rotationAngle = rotationAngle + 1;
qtCube.setRotationAxisAndAngle(Qt.vector3d(1, 0, 1), rotationAngle);
...Formateadores de ejes
En la pestaña « Axis Formatter », crea un formateador de ejes personalizado. También se ilustra cómo utilizar formateadores de ejes predefinidos.
Formateador de ejes personalizado
Para personalizar los formateadores de ejes es necesario crear una subclase de QValue3DAxisFormatter, lo cual no se puede hacer únicamente con código QML. En este ejemplo, el eje interpreta los valores de tipo float como marcas de tiempo y muestra la fecha en las etiquetas del eje. Para lograrlo, introduce una nueva clase llamada ` CustomFormatter`, que es una subclase de `QValue3DAxisFormatter`:
class CustomFormatter : public QValue3DAxisFormatter
{
...Dado que los valores de tipo float de una QScatter3DSeries no pueden convertirse directamente en valores de QDateTime debido a la diferencia en el ancho de datos, se necesita algún tipo de mapeo entre ambos. Para realizar el mapeo, especifica una fecha de origen para el formateador e interpreta los valores de tipo float de la QScatter3DSeries como desplazamientos de fecha respecto a ese valor de origen. La fecha de origen se indica como una propiedad:
Q_PROPERTY(QDate originDate READ originDate WRITE setOriginDate NOTIFY originDateChanged)Para la correspondencia entre un valor y un ` QDateTime`, utilice el método ` valueToDateTime() `:
QDateTime CustomFormatter::valueToDateTime(qreal value) const
{
return m_originDate.startOfDay().addMSecs(qint64(oneDayMs * value));
}Para que funcione como formateador de ejes, ` CustomFormatter ` debe reimplementar algunos métodos virtuales:
virtual QValue3DAxisFormatter *createNewInstance() const;
virtual void populateCopy(QValue3DAxisFormatter ©) const;
virtual void recalculate();
virtual QString stringForValue(qreal value, const QString &format) const;Los dos primeros son sencillos: basta con crear una nueva instancia de ` CustomFormatter ` y copiar en ella los datos necesarios. Utiliza estos dos métodos para crear y actualizar una caché del formateador con fines de representación. Recuerda llamar a la implementación de la superclase de ` populateCopy()`:
QValue3DAxisFormatter *CustomFormatter::createNewInstance() const
{
return new CustomFormatter();
}
void CustomFormatter::populateCopy(QValue3DAxisFormatter ©) const
{
QValue3DAxisFormatter::populateCopy(copy);
CustomFormatter *customFormatter = static_cast<CustomFormatter *>(©);
customFormatter->m_originDate = m_originDate;
customFormatter->m_selectionFormat = m_selectionFormat;
}CustomFormatter realiza la mayor parte de su trabajo en el método ` recalculate() `, donde nuestro formateador calcula las posiciones de la cuadrícula, las subcuadrículas y las etiquetas, además de dar formato a las cadenas de las etiquetas. En el formateador personalizado, ignora el recuento de segmentos del eje y dibuja una línea de cuadrícula siempre a las doce de la noche. El recuento de subsegmentos y el posicionamiento de las etiquetas se gestionan con normalidad:
void CustomFormatter::recalculate()
{
// We want our axis to always have gridlines at date breaks
// Convert range into QDateTimes
QDateTime minTime = valueToDateTime(qreal(axis()->min()));
QDateTime maxTime = valueToDateTime(qreal(axis()->max()));
// Find out the grid counts
QTime midnight(0, 0);
QDateTime minFullDate(minTime.date(), midnight);
int gridCount = 0;
if (minFullDate != minTime)
minFullDate = minFullDate.addDays(1);
QDateTime maxFullDate(maxTime.date(), midnight);
gridCount += minFullDate.daysTo(maxFullDate) + 1;
int subGridCount = axis()->subSegmentCount() - 1;
// Reserve space for position arrays and label strings
gridPositions().resize(gridCount);
subGridPositions().resize((gridCount + 1) * subGridCount);
labelPositions().resize(gridCount);
labelStrings().reserve(gridCount);
// Calculate positions and format labels
qint64 startMs = minTime.toMSecsSinceEpoch();
qint64 endMs = maxTime.toMSecsSinceEpoch();
qreal dateNormalizer = endMs - startMs;
qreal firstLineOffset = (minFullDate.toMSecsSinceEpoch() - startMs) / dateNormalizer;
qreal segmentStep = oneDayMs / dateNormalizer;
qreal subSegmentStep = 0;
if (subGridCount > 0)
subSegmentStep = segmentStep / qreal(subGridCount + 1);
for (int i = 0; i < gridCount; i++) {
qreal gridValue = firstLineOffset + (segmentStep * qreal(i));
gridPositions()[i] = float(gridValue);
labelPositions()[i] = float(gridValue);
labelStrings() << minFullDate.addDays(i).toString(axis()->labelFormat());
}
for (int i = 0; i <= gridCount; i++) {
if (subGridPositions().size()) {
for (int j = 0; j < subGridCount; j++) {
float position;
if (i)
position = gridPositions().at(i - 1) + subSegmentStep * (j + 1);
else
position = gridPositions().at(0) - segmentStep + subSegmentStep * (j + 1);
if (position > 1.0f || position < 0.0f)
position = gridPositions().at(0);
subGridPositions()[i * subGridCount + j] = position;
}
}
}
}Las etiquetas de los ejes se formatean para mostrar únicamente la fecha. Sin embargo, para aumentar la resolución de la marca de tiempo de la etiqueta de selección, especifica otra propiedad para el formateador personalizado que permita al usuario personalizarla:
Q_PROPERTY(QString selectionFormat READ selectionFormat WRITE setSelectionFormat NOTIFY selectionFormatChanged)Esta propiedad de formato de selección se utiliza en el método « stringToValue » reimplementado, donde se ignora el formato enviado y se sustituye por el formato de selección personalizado:
QString CustomFormatter::stringForValue(qreal value, const QString &format) const
{
Q_UNUSED(format);
return valueToDateTime(value).toString(m_selectionFormat);
}Para integrar nuestro nuevo formateador personalizado en QML, hay que declararlo y convertirlo en un módulo QML. Para obtener información sobre cómo hacerlo, consulta la galería de gráficos de superficie.
QML
En el código QML, define un eje diferente para cada dimensión:
axisZ: valueAxis
axisY: logAxis
axisX: dateAxisEl eje Z es simplemente un ValueAxis3D normal:
ValueAxis3D {
id: valueAxis
segmentCount: 5
subSegmentCount: 2
labelFormat: "%.2f"
min: 0
max: 10
}Para el eje Y, define un eje logarítmico. Para que ValueAxis3D muestre una escala logarítmica, especifica LogValueAxis3DFormatter para la propiedad « formatter » del eje:
ValueAxis3D {
id: logAxis
formatter: LogValueAxis3DFormatter {
id: logAxisFormatter
base: 10
autoSubGrid: true
showEdgeLabels: true
}
labelFormat: "%.2f"
}Y, por último, para el eje X, utiliza el nuevo CustomFormatter:
ValueAxis3D {
id: dateAxis
formatter: CustomFormatter {
originDate: "2023-01-01"
selectionFormat: "yyyy-MM-dd HH:mm:ss"
}
subSegmentCount: 2
labelFormat: "yyyy-MM-dd"
min: 0
max: 14
}El resto de la aplicación consiste en una lógica bastante intuitiva para modificar los ejes y mostrar el gráfico.
Contenido del ejemplo
© 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.