QuickGraphLib 0.1.0a8__tar.gz → 0.1.0a9__tar.gz

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/CMakeLists.txt

@@ -24,6 +24,6 @@ if(NOT INSTALL_SUBPATH)
 endif()
 
 find_package(Qt6 REQUIRED COMPONENTS Quick Svg)
-qt_standard_project_setup(REQUIRES 6.5)
+qt_standard_project_setup(REQUIRES 6.8)
 
 add_subdirectory(QuickGraphLib)

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: QuickGraphLib
-Version: 0.1.0a8
+Version: 0.1.0a9
 Summary: A scientific graphing library for QtQuick
 Author-Email: Matthew Joyce <matthew.joyce@refeyn.com>
 License: MIT License
@@ -38,8 +38,9 @@ Project-URL: Homepage, https://github.com/refeyn/QuickGraphLib
 Project-URL: Issues, https://github.com/refeyn/QuickGraphLib/issues
 Project-URL: Documentation, https://refeyn.github.io/QuickGraphLib
 Project-URL: Source, https://github.com/refeyn/QuickGraphLib
-Requires-Dist: PySide6
+Requires-Dist: PySide6==6.8.0.2
 Requires-Dist: contourpy
+Requires-Dist: numpy<2
 Requires-Dist: black; extra == "analyse"
 Requires-Dist: pylint; extra == "analyse"
 Requires-Dist: mypy; extra == "analyse"
@@ -48,8 +49,7 @@ Requires-Dist: lxml; extra == "analyse"
 Requires-Dist: pytest; extra == "analyse"
 Requires-Dist: pytest-cov; extra == "analyse"
 Requires-Dist: scikit-build-core; extra == "analyse"
-Requires-Dist: shiboken6_generator==6.5.3; extra == "analyse"
-Requires-Dist: PySide6==6.5.3; extra == "analyse"
+Requires-Dist: shiboken6_generator==6.8.0.2; extra == "analyse"
 Requires-Dist: setuptools_scm; extra == "analyse"
 Provides-Extra: analyse
 Description-Content-Type: text/markdown
@@ -61,6 +61,7 @@ A scientific graphing library for [QtQuick](https://doc.qt.io/qt-6/qtquick-index
 Links:
  - [Online documentation](https://refeyn.github.io/QuickGraphLib)
  - [PyPI page](https://pypi.org/project/QuickGraphLib/)
+ - [Pre-built artefacts](https://github.com/refeyn/QuickGraphLib/releases/latest)
 
 Key advantages:
 
@@ -75,7 +76,17 @@ Key advantages:
 The example gallery can be run using (provided the Python environment has [PySide6](https://pypi.org/project/PySide6/) and [contourpy](https://pypi.org/project/contourpy/) installed):
 
 ```bash
-python examples\gallery.py
+python examples/gallery.py
 ```
 
 <p align="center"><img src="https://github.com/refeyn/QuickGraphLib/assets/103422031/56fdff62-ef77-4184-9f43-59a76b92d728" width="80%"></p>
+
+## Qt version compatibility
+
+This version of QuickGraphLib is compatible with Qt and PySide6 6.8.0. If you use this module from C++, then Qt's ABI stability guarantees means the compiled binaries will work for any Qt version >= 6.8 and < 7.0. If you use this module from Python, there are some additional features that rely on the PySide6 library version. Therefore the PySide6 version must be 6.8.0.2 exactly. Other 6.8 versions of PySide6 may work, but there are no guarantees.
+
+The pre-built wheels aim to be compatible with the most recent recent Qt LTS version, which is currently 6.8. Pre-built wheels for higher non-LTS Qt versions will likely be available once Qt 6.9 is released.
+
+## Python version compatibility
+
+QuickGraphLib is compatible with the same Python versions and glibc versions that PySide6 is. For PySide6 6.8, the minimum Python version is 3.9.

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/Axis.qml

@@ -11,6 +11,8 @@ import QuickGraphLib as QuickGraphLib
     \inqmlmodule QuickGraphLib
     \inherits QtQuick::Item
     \brief Displays an Axis.
+
+    \sa {Basic sin graph (without prefabs)}, {Graph with all four axes}
 */
 
 Item {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/ColorMaps.cpp

@@ -11,6 +11,8 @@
     \inqmlmodule QuickGraphLib
     \inherits QObject
     \brief Utility functions for color maps.
+
+    \sa {ImageView}, {Builtin color maps}, {Color mapped images}
 */
 
 extern const std::map<ColorMaps::ColorMapName, QList<QRgb>> DEFAULT_COLORMAPS;

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphArea.qml

@@ -9,6 +9,8 @@ import QtQuick.Shapes as QQS
     \inqmlmodule QuickGraphLib
     \inherits QtQuick::Shapes::Shape
     \brief An area that graphs can be added to.
+
+    \sa {Basic sin graph (without prefabs)}, {Inverted axes}
 */
 
 QQS.Shape {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/AxHLine.qml

@@ -9,6 +9,8 @@ import QtQuick.Shapes as QQS
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Shapes::ShapePath
     \brief Displays a horizontal line.
+
+    \sa {Spans and lines}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/AxHSpan.qml

@@ -9,6 +9,8 @@ import QtQuick.Shapes as QQS
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Shapes::ShapePath
     \brief Displays a horizontal span.
+
+    \sa {Spans and lines}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/AxVLine.qml

@@ -9,6 +9,8 @@ import QtQuick.Shapes as QQS
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Rectangle
     \brief Displays an vertical line.
+
+    \sa {Spans and lines}, {Draggable region}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/AxVSpan.qml

@@ -9,6 +9,8 @@ import QtQuick.Shapes as QQS
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Shapes::ShapePath
     \brief Displays an vertical span.
+
+    \sa {Spans and lines}, {Basic histogram}, {Draggable region}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/BasicLegend.qml

@@ -10,6 +10,8 @@ import QtQuick
     \brief Displays a simple legend.
 
     \note This graph item does not inherit from ShapePath, unlike other graph items.
+
+    \sa {Basic sin graph}
 */
 
 Rectangle {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/BasicLegendItem.qml

@@ -8,6 +8,8 @@ import QtQuick
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Row
     \brief An single entry in a simple legend.
+
+    \sa {Basic sin graph}
 */
 
 Row {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/CMakeLists.txt

@@ -16,6 +16,7 @@ set(QGL_GI_QML_FILES
     Line.qml
     ColorMesh.qml
 )
+set_source_files_properties(Line.qml PROPERTIES QT_QML_SKIP_CACHEGEN True)
 qt_add_qml_module(QuickGraphLibGraphItems
     URI QuickGraphLib.GraphItems
     SHARED

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/ColorMesh.qml

@@ -11,6 +11,8 @@ import QuickGraphLib as QuickGraphLib
     \brief Display a colorized image from a 2D array.
 
     \note This graph item does not inherit from ShapePath, unlike other graph items.
+
+    \sa {Color mesh}, {Color mapped images}
 */
 
 QuickGraphLib.ImageView {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/Contour.qml

@@ -10,6 +10,8 @@ import QuickGraphLib as QuickGraphLib
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Shapes::ShapePath
     \brief Draw a contour line or fill.
+
+    \sa {Contours}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/GraphItemDragHandler.qml

@@ -8,6 +8,8 @@ import QtQuick
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::MouseArea
     \brief Assists converting mouse drags into data positions.
+
+    \sa {Draggable region}
 */
 
 MouseArea {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/Grid.qml

@@ -10,6 +10,8 @@ import QuickGraphLib.GraphItems as QGLGraphItems
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Shapes::ShapePath
     \brief Displays a grid in the background of a graph.
+
+    \sa {Basic sin graph (without prefabs)}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/Histogram.qml

@@ -10,6 +10,8 @@ import QuickGraphLib.GraphItems as QGLGraphItems
     \inqmlmodule QuickGraphLib.GraphItems
     \inherits QtQuick::Shapes::ShapePath
     \brief Displays a histogram.
+
+    \sa {Basic histogram}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/Line.qml

@@ -13,19 +13,7 @@ import QuickGraphLib as QuickGraphLib
 
     Graph a line using a list of X,Y points. The style of the line can be adjusted using the \l {ShapePath::strokeColor} {strokeColor} and \l {ShapePath::strokeWidth} {strokeWidth} properties.
 
-    \qml
-        GraphArea {
-            id: grapharea
-            viewRect: Qt.rect(-20, -1.1, 760, 2.2)
-
-            Line {
-                dataTransform: grapharea.dataTransform
-                path: Helpers.linspace(0, 720, 100).map(x => Qt.point(x, Math.sin(x / 180 * Math.PI)))
-                strokeColor: "red"
-                strokeWidth: 2
-            }
-        }
-    \endqml
+    \sa {Basic sin graph}
 */
 
 QQS.ShapePath {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/GraphItems/Marker.qml

@@ -10,6 +10,8 @@ import QtQuick
     \brief Displays a circular marker.
 
     \note This graph item does not inherit from ShapePath, unlike other graph items. This is for performance reasons.
+
+    \sa {Scatter graph}
 */
 
 Rectangle {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/ImageView.cpp

@@ -13,6 +13,8 @@
     \inqmlmodule QuickGraphLib
     \inherits QtQuick::Item
     \brief Display a colorized image from a 2D array.
+
+    \sa {Builtin color maps}, {Color mapped images}, {Image alignment}
 */
 
 /*!

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/PreFabs/ImageAxes.qml

@@ -11,6 +11,8 @@ import QuickGraphLib.GraphItems as QGLGraphItems
     \inqmlmodule QuickGraphLib.PreFabs
     \inherits QuickGraphLib::AntialiasingContainer
     \brief Displays an image with axes and a colorbar.
+
+    \sa {Color mesh}
 */
 
 QuickGraphLib.AntialiasingContainer {
@@ -149,9 +151,9 @@ QuickGraphLib.AntialiasingContainer {
                         property var colors: QuickGraphLib.ColorMaps.colors(root.colorMesh.colormap)
 
                         stops: colors.map((color, i) => gradStop.createObject(grad, {
-                                        "color": color,
-                                        "position": i / (colors.length - 1)
-                                    }))
+                                "color": color,
+                                "position": i / (colors.length - 1)
+                            }))
                     }
                 }
                 QuickGraphLib.Axis {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/PreFabs/XYAxes.qml

@@ -11,6 +11,8 @@ import QuickGraphLib.GraphItems as QGLGraphItems
     \inqmlmodule QuickGraphLib.PreFabs
     \inherits QuickGraphLib::AntialiasingContainer
     \brief Displays an XY axis with a grid.
+
+    \sa {Basic sin graph}, {Dark theme sin graph}, {Subgraphs}
 */
 
 QuickGraphLib.AntialiasingContainer {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/ScalingContainer.qml

@@ -10,6 +10,8 @@ import QtQuick
     \brief Scales its contents while preserving the aspect ratio.
 
     This container applies a scaling factor to its content item that preserves its aspect ratio.
+
+    \sa {Scaled graph}
 */
 
 AntialiasingContainer {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/ShapeRepeater.qml

@@ -9,6 +9,8 @@ import QtQuick.Shapes as QQS
     \inqmlmodule QuickGraphLib
     \inherits QtQml::Models::Instantiator
     \brief A \l{Repeater}-like component that works with \l{ShapePath}s.
+
+    \sa {Scatter graph}
 */
 
 QQM.Instantiator {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/TickLabel.qml

@@ -11,6 +11,8 @@ import QtQuick
 
     This is the default implementation of a tick label. To customise how labels are shown,
     you can subclass this and override the \l Text::text property.
+
+    \sa {Axis}
 */
 
 Text {

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/ZoomPanHandler.qml

@@ -8,13 +8,15 @@ import QtQuick
     \inqmlmodule QuickGraphLib
     \inherits QtQuick::PinchArea
     \brief Pinch/drag handling for graph or image zoom/pan interactions.
+
+    \sa {Zoomable as image}, {Zoomable axes}
 */
 
 PinchArea {
     id: root
 
     /*!
-        The view transform, but in a pixel-independant form.
+        The view transform, but in a pixel-independent form.
 
         \sa GraphArea::baseTransformFromRect
     */

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/__init__.py

@@ -6,18 +6,19 @@ import os
 import pathlib
 from typing import ContextManager
 
-from PySide6 import QtCore, QtGui, QtQml
+from PySide6 import QtCore, QtGui, QtQml, QtQuick, QtSvg
 
 from ._version import __version__, __version_tuple__
 
 QML_IMPORT_PATH = str(pathlib.Path(__file__).parent.parent)
 
 _dll_path = pathlib.Path(__file__).parent
-os.environ["PATH"] = os.fspath(_dll_path) + os.pathsep + os.environ["PATH"]
 if hasattr(os, "add_dll_directory"):
     cm: ContextManager = os.add_dll_directory(os.fspath(_dll_path))
 else:
     cm = contextlib.nullcontext()
+if os.name == "nt":
+    os.environ["PATH"] = os.fspath(_dll_path) + os.pathsep + os.environ["PATH"]
 with cm:
     from QuickGraphLib._QuickGraphLib import (  # pylint: disable=import-error,no-name-in-module
         QGLDoubleList,

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/_version.py

@@ -12,5 +12,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.1.0a8'
+__version__ = version = '0.1.0a9'
 __version_tuple__ = version_tuple = (0, 1, 0)

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/bindings/CMakeLists.txt

@@ -31,21 +31,21 @@ find_path(
 )
 find_library(
     shiboken_shared_libraries
-    NAMES shiboken6 shiboken6.abi3 libshiboken6.abi3.so.6.5
+    NAMES shiboken6 shiboken6.abi3 libshiboken6.abi3.so.6.8
     PATH_SUFFIXES shiboken6
     PATHS "${Python_SITELIB}"
     REQUIRED
 )
 find_library(
     pyside_shared_library
-    NAMES pyside6 pyside6.abi3 libpyside6.abi3.so.6.5
+    NAMES pyside6 pyside6.abi3 libpyside6.abi3.so.6.8
     PATH_SUFFIXES PySide6
     PATHS "${Python_SITELIB}"
     REQUIRED
 )
 find_library(
     pyside_qml_shared_library
-    NAMES pyside6qml pyside6qml.abi3 libpyside6qml.abi3.so.6.5
+    NAMES pyside6qml pyside6qml.abi3 libpyside6qml.abi3.so.6.8
     PATH_SUFFIXES PySide6
     PATHS "${Python_SITELIB}"
     REQUIRED
@@ -145,7 +145,7 @@ python_add_library(
     ShibokenHelpers.cpp
     WITH_SOABI
     USE_SABI
-    3.7
+    3.9
 )
 
 # Apply relevant include and link flags.

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/bindings/pyigen.py

@@ -22,6 +22,7 @@ else:
     cm = contextlib.nullcontext()
 with cm:
     pyi_generator.PySide6 = PySide6
+    pyi_generator.os = os
     pyi_generator.main()
 
 # Fixup

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/contours.py

@@ -1,7 +1,7 @@
 # SPDX-FileCopyrightText: Copyright (c) 2024 Refeyn Ltd and other QuickGraphLib contributors
 # SPDX-License-Identifier: MIT
 
-from typing import Sequence
+from typing import Sequence, Tuple
 
 from PySide6 import QtCore, QtQml
 
@@ -27,13 +27,16 @@ def contour_line(
     z: Sequence[Sequence[float]],
     height: float,
 ) -> Sequence[QGLPolygonF]:
+    if not CONTOURPY_AVAILABLE:
+        print("contourpy is not installed, contourLine will not work")
+        return []
+
     gen = contourpy.contour_generator(
         x=x, y=y, z=z, line_type=contourpy.LineType.Separate
     )
     result = []
     for loop in gen.lines(height):
-        assert isinstance(loop, np.ndarray), "Loop is not an array"  # For mypy
-        result.append(QGLPolygonF.fromNDArray(loop))
+        result.append(QGLPolygonF.fromNDArray(loop))  # type: ignore[arg-type]
     return result
 
 
@@ -41,8 +44,12 @@ def contour_fill(
     x: Sequence[Sequence[float]],
     y: Sequence[Sequence[float]],
     z: Sequence[Sequence[float]],
-    heights: tuple[float, float],
+    heights: Tuple[float, float],
 ) -> Sequence[QGLPolygonF]:
+    if not CONTOURPY_AVAILABLE:
+        print("contourpy is not installed, contourFill will not work")
+        return []
+
     gen = contourpy.contour_generator(
         x=x, y=y, z=z, fill_type=contourpy.FillType.OuterOffset
     )

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/doc/graphstructure.qdoc

@@ -129,12 +129,93 @@ Tick positions are also important for grids, normally you can just feed in the t
 
 \section1 Drawing a line
 
+To draw a line between two points, use a \l Line:
+
+\qml
+QGLGraphItems.Line {
+    dataTransform: grapharea.dataTransform
+    path: [Qt.point(0, 0), Qt.point(10, 10)]
+}
+\endqml
+
+This code snippet will draw a line between the point (0, 0) and (10, 10). The \l Line item will convert these data coordinates into pixel coordinates for you. To change the color of the line, set the \l {ShapePath::strokeColor}{strokeColor} property:
+
+\qml
+QGLGraphItems.Line {
+    // ...
+    strokeColor: "red"
+}
+\endqml
+
+\l Line inherits from ShapePath, so any of the properties of ShapePath can be used. This includes line thickness, dashing, line end styles, etc.
+
+The recommended way to generate data for a \l Line or other graph items is to generate it in C++ or Python, since it is much more efficient. However, JavaScript arrays also work, so data can be constructed in the QML code using helper functions like \l {Helpers::linspace}{linspace} and \c map:
+
+\qml
+QGLGraphItems.Line {
+    dataTransform: grapharea.dataTransform
+    path: QuickGraphLib.Helpers.linspace(0, 720, 100).map(x => Qt.point(x, Math.sin(x / 180 * Math.PI)))
+    strokeColor: "red"
+    strokeWidth: 2
+}
+\endqml
+
 \section1 A simple legend
 
+QuickGraphLib provides a basic legend type, which can be used to label the different data sets in use in a graph. Since legends come in many styles, it is quite basic. If you have specific needs, the best option is to implement your own using standard QML types, as you will have maximum flexibility. However, if you need something simple, you can use BasicLegend and BasicLegendItem:
+
+\qml
+QGLGraphItems.BasicLegend {
+    anchors.margins: 10
+    anchors.right: parent.right
+    anchors.top: parent.top
+
+    QGLGraphItems.BasicLegendItem {
+        strokeColor: "red"
+        text: "Sin(θ)"
+    }
+}
+\endqml
+
+Anchors are used to position the legend (since this is purely a UI component, we don't need to care about data coordinates - the legend is not representing any data). BasicLegendItem can be used to add rows to the legend, and it's properties can be used to set the name and indicator color.
+
 \section1 Full example
 
 The full code for this example can be seen in the \l {Basic sin graph (without prefabs)} example.
 
 \section1 Prefabs
 
+QuickGraphLib comes with a set of prefab components, so make common tasks like simple X/Y axes simpler. XYAxes sets up a graph area with two axes, one on the left and one on the bottom. When using XYAxes, you only need to add the graph items, the axes, grid and graph area are already created:
+
+\qml
+QGLPreFabs.XYAxes {
+    id: axes
+
+    viewRect: Qt.rect(-20, -1.1, 760, 2.2)
+    xLabel: "Angle (°)"
+    yLabel: "Value"
+
+    QGLGraphItems.Line {
+        id: sinLine
+
+        dataTransform: axes.dataTransform
+        path: QuickGraphLib.Helpers.linspace(0, 720, 100).map(x => Qt.point(x, Math.sin(x / 180 * Math.PI)))
+        strokeColor: "red"
+        strokeWidth: 2
+    }
+    QGLGraphItems.BasicLegend {
+        anchors.margins: 10
+        anchors.right: parent.right
+        anchors.top: parent.top
+
+        QGLGraphItems.BasicLegendItem {
+            strokeColor: sinLine.strokeColor
+            text: "Sin(θ)"
+        }
+    }
+}
+\endqml
+
+XYAxes can be customized to some extent (see \l {Dark theme sin graph} for a theming example), the components of the graph are exposed though properties. However, if a more flexibly layout is needed, then prefabs should not be used.
+
 */

quickgraphlib-0.1.0a9/QuickGraphLib/doc/interaction.qdoc

@@ -0,0 +1,43 @@
+// SPDX-FileCopyrightText: Copyright (c) 2024 Refeyn Ltd and other QuickGraphLib contributors
+// SPDX-License-Identifier: MIT
+
+/*!
+\page interaction.html
+\title Interaction
+\brief How to construct interactive graphs
+
+\section1 Zooming and panning
+
+Zooming and panning can be handled using a ZoomPanHandler, which combines a PinchHandler and a MouseArea into one type that translates touch and mouse inputs into a transformation. The ZoomPanHandler has two outputs:
+
+\list
+    \li \l{ZoomPanHandler::viewTransform}{viewTransform}, which can be provided to a Matrix4x4 transform, and used on any \l Item, or passed to \l {GraphArea::viewTransform} to scale a graph
+    \li \l{ZoomPanHandler::baseTransform}{baseTransform}, which is a more size-independent version of viewTransform which can be translated into a view rect using ZoomPanHandler's utility methods
+\endlist
+
+With these properties, two sorts of interaction can be implemented:
+
+\list
+    \li Zooming into a graph as if it's an image. This can be useful for large or complex figures, where the user may not be able to see the details. This can be achieved by applying the viewTransform to the \l Item which contains the graph (e.g. the GridLayout or XYAxes). See the \l {Zoomable as image} example for more details.
+    \li Using zooming and panning to change the axes limits. This can be used when the data itself is has complex detail that is not visible when all of the data is shown. This can be achieved by passing the viewTransform to the GraphArea, and optionally providing a set of spin boxes for precise control of the limits. See the \l {Zoomable axes} example for more details.
+\endlist
+
+\section1 Interactive graph items
+
+There is a huge amount of interaction possible in a graph, so here we'll stick to the basics. Things you might want to add to your graph include:
+
+\list
+    \li Draggable regions
+    \li Hover text / tooltips
+    \li Read out of where the cursor is
+    \li Buttons over particular data points
+\endlist
+
+All of this can be implemented using MouseArea, or using a control, and using the \l{Item::x}{x} and \l{Item::y}{y} properties to position the \l Item (this is because graph items usually inherit from ShapePath, which is not an Item, and so anchors do not work).
+
+The \l {Readout line} example demonstrates using a MouseArea to monitor the position of the mouse and translate it into data coordinates, a similar arrangement can be used for tooltips.
+
+The \l {Draggable region} example uses a GraphItemDragHandler (another MouseArea helper) to implement a draggable and resizable region.
+
+In general, because QML already provides so many interactive items, adding interactivity to a graph is easy and just uses standard QML items, with a bit of extra maths to do positioning since it often needs to be done in data coordinates instead of purely using pixel coordinates.
+*/

{quickgraphlib-0.1.0a8 → quickgraphlib-0.1.0a9}/QuickGraphLib/doc/python_helpers.qdoc

@@ -31,6 +31,8 @@ Visit the \l {QuickGraphLib} module documentation and examples (in particular th
     \inqmlmodule QuickGraphLib.PythonHelpers
     \inherits QObject
     \brief Produces contour lines and fills from XYZ data.
+
+    The contourpy package must be installed to use these methods. See \l {https://contourpy.readthedocs.io/} for installation instructions and algorithm details.
 */
 
 /*!

quickgraphlib-0.1.0a9/README.md

@@ -0,0 +1,36 @@
+# QuickGraphLib
+
+A scientific graphing library for [QtQuick](https://doc.qt.io/qt-6/qtquick-index.html) using Qt6.
+
+Links:
+ - [Online documentation](https://refeyn.github.io/QuickGraphLib)
+ - [PyPI page](https://pypi.org/project/QuickGraphLib/)
+ - [Pre-built artefacts](https://github.com/refeyn/QuickGraphLib/releases/latest)
+
+Key advantages:
+
+ - Written in C++ and QML (with some optional Python helpers), so it can be used in both C++ and Python projects
+ - QtQuick's hardware-based rendering makes this library render very fast
+ - Support for line graphs, histograms, contour plots and more
+ - Interactivity supported natively though declarative bindings and QtQuick
+ - Support for PNG and SVG export
+
+## Examples
+
+The example gallery can be run using (provided the Python environment has [PySide6](https://pypi.org/project/PySide6/) and [contourpy](https://pypi.org/project/contourpy/) installed):
+
+```bash
+python examples/gallery.py
+```
+
+<p align="center"><img src="https://github.com/refeyn/QuickGraphLib/assets/103422031/56fdff62-ef77-4184-9f43-59a76b92d728" width="80%"></p>
+
+## Qt version compatibility
+
+This version of QuickGraphLib is compatible with Qt and PySide6 6.8.0. If you use this module from C++, then Qt's ABI stability guarantees means the compiled binaries will work for any Qt version >= 6.8 and < 7.0. If you use this module from Python, there are some additional features that rely on the PySide6 library version. Therefore the PySide6 version must be 6.8.0.2 exactly. Other 6.8 versions of PySide6 may work, but there are no guarantees.
+
+The pre-built wheels aim to be compatible with the most recent recent Qt LTS version, which is currently 6.8. Pre-built wheels for higher non-LTS Qt versions will likely be available once Qt 6.9 is released.
+
+## Python version compatibility
+
+QuickGraphLib is compatible with the same Python versions and glibc versions that PySide6 is. For PySide6 6.8, the minimum Python version is 3.9.