En esta página

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

Gráfico de dispersión en 3D con puntos naranjas y etiquetas amarillas en los ejes que se pueden arrastrar

Ejecución del ejemplo

Puede ejecutar el ejemplo desde:

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 &copy) 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 &copy) const
{
    QValue3DAxisFormatter::populateCopy(copy);

    CustomFormatter *customFormatter = static_cast<CustomFormatter *>(&copy);
    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: dateAxis

El 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

Proyecto de ejemplo en code.qt.io

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