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 funciones personalizadas diferentes relacionadas con los ejes. Estas funciones 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 esferas y ejes basados en fechas

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 entrada predeterminado

Para desactivar el mecanismo predeterminado de gestión de entradas, desactive el controlador de entrada predeterminado de « Scatter3D »:

unsetDefaultInputHandler();
    ...

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, detecta las pulsaciones del ratón y, cuando se detecte una, envía una consulta de selección al gráfico:

onPressed: (mouse)=> {
               scatterGraph.doPicking(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 >= Graphs3D.ElementType.AxisXLabel
            && selectedElement <= Graphs3D.ElementType.AxisZLabel) {
        selectedAxisLabel = selectedElement;
    } else {
        selectedAxisLabel = -1;
    }
}

A continuación, de vuelta en el onPositionChanged de inputArea, comprueba si se ha pulsado un botón del ratón y si tienes una selección de etiqueta de eje actual. 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 Graphs3D.ElementType.AxisXLabel:
        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 Graphs3D.ElementType.AxisYLabel:
        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 Graphs3D.ElementType.AxisZLabel:
        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 = Graphs3D.ShadowQuality.Medium
        } else {
            text = "Display Perspective";
            scatterGraph.orthoProjection = true;
        }
    }
}

Para los elementos personalizados, añada uno a la propiedad « customItemList » de « scatterGraph »:

customItemList: [
    Custom3DItem {
        id: qtCube
        meshFile: ":/qml/axishandling/cube.mesh"
        textureFile: ":/qml/axishandling/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 un « QScatter3DSeries » no pueden convertirse directamente en valores de « QDateTime » debido a una 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» del « QScatter3DSeries » como desplazamientos de fecha respecto a ese valor de origen. La fecha de origen se proporciona como una propiedad:

Q_PROPERTY(QDate originDate READ originDate WRITE setOriginDate NOTIFY originDateChanged)

Para la correspondencia entre el valor y QDateTime, utilice el método valueToDateTime():

QDateTime CustomFormatter::valueToDateTime(qreal value) const
{
    return m_originDate.startOfDay().addMSecs(qint64(oneDayMs * value));
}

Para funcionar como formateador de ejes, ` CustomFormatter ` debe reimplementar algunos métodos virtuales:

QValue3DAxisFormatter *createNewInstance() const override;
void populateCopy(QValue3DAxisFormatter &copy) override;
void recalculate() override;
QString stringForValue(qreal value, const QString &format) override;

Los dos primeros métodos 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é de formateadores 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)
{
    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 el formateador calcula las posiciones de la cuadrícula, la subcuadrícula 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 medianoche. El recuento de subsegmentos y el posicionamiento de las etiquetas se gestionan de forma normal:

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;

    QList<float> gridPositions;
    QList<float> subGridPositions;
    QList<float> labelPositions;
    QStringList labelStrings;

    // 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;
            }
        }
    }
    setGridPoitions(gridPositions);
    setSubGridPositions(subGridPositions);
    setlabelPositions(labelPositions);
    setLabelStrings(labelStrings);
}

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)
{
    Q_UNUSED(format);

    return valueToDateTime(value).toString(m_selectionFormat);
}

Para hacer que nuestro nuevo formateador personalizado esté disponible 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 « Value3DAxis » normal:

Value3DAxis {
    id: valueAxis
    segmentCount: 5
    subSegmentCount: 2
    labelFormat: "%.2f"
    min: 0
    max: 10
}

Para el eje Y, define un eje logarítmico. Para que ` Value3DAxis ` muestre una escala logarítmica, especifica ` LogValue3DAxisFormatter ` para la propiedad ` formatter ` del eje:

Value3DAxis {
    id: logAxis
    formatter: LogValue3DAxisFormatter {
        id: logAxisFormatter
        base: 10
        autoSubGrid: true
        edgeLabelsVisible: true
    }
    labelFormat: "%.2f"
}

Y, por último, para el eje X, utiliza el nuevo CustomFormatter:

Value3DAxis {
    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.