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

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 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 ©) 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 ©)
{
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 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: dateAxisEl 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
© 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.