mirror of https://github.com/CGAL/cgal
115 lines
6.0 KiB
Plaintext
115 lines
6.0 KiB
Plaintext
|
|
namespace CGAL {
|
|
/*!
|
|
|
|
\mainpage User Manual
|
|
\anchor Chapter_CGAL_and_the_Qt_Graphics_View_Framework
|
|
\anchor chapterQGraphicsView
|
|
\cgalAutoToc
|
|
\authors Andreas Fabri and Laurent Rineau
|
|
|
|
<A HREF="https://doc.qt.io/qt-6/">Qt</A> is a <span class="textsc">Gui</span> toolkit for
|
|
cross-platform application development.
|
|
|
|
\section GraphicsViewIntroduction Introduction
|
|
|
|
This chapter describes classes that help to visualize two dimensional \cgal objects
|
|
with the <A HREF="https://doc.qt.io/qt-6/graphicsview.html">Qt Graphics View Framework</A>.
|
|
|
|
This framework uses the model view paradigm. <A HREF="https://doc.qt.io/qt-6/qgraphicsitem.html">`QGraphicsItem`</A>s are stored in a
|
|
<A HREF="https://doc.qt.io/qt-6/qgraphicsscene.html">`QGraphicsScene`</A>
|
|
and are displayed in a <A HREF="https://doc.qt.io/qt-6/qgraphicsview.html">`QGraphicsView`</A>. The items
|
|
have a paint method which is called when an item is in the visible area of a view.
|
|
The framework is also responsible for dispatching events from the view
|
|
via the scene to the items. The framework is extensible in the sense
|
|
that users can add classes derived from `QGraphicsItem`.
|
|
|
|
Besides visualizing `QGraphicsItem`s users want to enter geometric objects.
|
|
We provide the input generators for all 2D \cgal `Kernel` objects.
|
|
|
|
The package includes also a class for providing zooming, panning, and scrolling
|
|
to the graphics view.
|
|
|
|
The following sections describe the interaction between all these classes,
|
|
We finally describe the internals of a `QGraphicsItem`.
|
|
|
|
\subsection GraphicsViewNamingConventions Naming Conventions
|
|
|
|
As %Qt and \cgal have different naming conventions, and as this package
|
|
brings them together we adopted the following, hybrid naming conventions.
|
|
|
|
<UL>
|
|
<LI>All header files are in the directory `CGAL/Qt/`.
|
|
<LI>Class names are concatenated capitalized words, and function names are
|
|
concatenated capitalized word with the first word in lowercase. The rationale is that
|
|
these classes are related to %Qt, and that they sometimes are derived
|
|
classes that have to override member functions adhering to this naming scheme.
|
|
<LI>All classes are in the nested namespace `CGAL::Qt`.
|
|
</UL>
|
|
|
|
\section GraphicsViewOverall Overall Design
|
|
|
|
In \cgalFigureRef{graphicsviewuml} you see four classes depicted in grey,
|
|
that come from the %Qt Graphics View Framework. The <A HREF="https://doc.qt.io/qt-6/qgraphicsscene.html">`QGraphicsScene`</A>
|
|
contains <A HREF="https://doc.qt.io/qt-6/qgraphicsitem.html">`QGraphicsItem`</A>s, which get displayed in any number
|
|
of <A HREF="https://doc.qt.io/qt-6/qgraphicsview.html">`QGraphicsView`</A>s. The views are widgets, that is they take screen space
|
|
in an application.
|
|
|
|
The fourth class is the <A HREF="https://doc.qt.io/qt-6/qobject.html">`QObject`</A>. It plays an important role in %Qt for
|
|
event handling and memory management. First, it allows to add <A HREF="https://doc.qt.io/qt-6/signalsandslots.html">signals and
|
|
slots</A>, and to connect them. Second, it allows to install <A HREF="https://doc.qt.io/qt-6/eventsandfilters.html">event filters</A>.
|
|
|
|
\cgalFigureBegin{graphicsviewuml,uml-design.png}
|
|
UML Class Diagram with the %Qt classes (blue), \cgal classes for using the framework (yellow), \cgal data structures (red), and application classes (green).
|
|
\cgalFigureEnd
|
|
|
|
\subsection GraphicsViewVisualizingCGALDatastructures Visualizing CGAL Datastructures
|
|
|
|
In order to visualize for example a `CGAL::Delaunay_triangulation_2`, we
|
|
provide the graphics item class `CGAL::Qt::TriangulationGraphicsItem<T>`.
|
|
It provides a `paint` method that draws the edges and vertices of a triangulation
|
|
using the drawing primitives of the <A HREF="https://doc.qt.io/qt-6/qpainter.html">`QPainter`</A>. The color of vertices and edges,
|
|
can be chosen by setting a user defined <A HREF="https://doc.qt.io/qt-6/qpen.html">`QPen`</A>.
|
|
|
|
As this graphics item only stores a pointer to a triangulation, it
|
|
must be notified about changes like the insertion of points coming from
|
|
a file, a process or as input generated with the mouse. We
|
|
use the signal/slot mechanism of %Qt for that purpose, that is when the
|
|
triangulation changes the application emits a signal that can get connected to the
|
|
`modelChanged()` slot of the graphics item.
|
|
|
|
\subsection GraphicsViewNavigation Navigation
|
|
|
|
We provide a class `CGAL::Qt::GraphicsViewNavigation` that can be
|
|
installed as an event filter of a graphics view and its viewport. As for
|
|
all %Qt widgets, the `QGraphicsView` is derived from
|
|
`QObject`. Events like the mouse buttons pressed or released, the mouse movemed, keys pressed,
|
|
are passed to the view which first hands them over to the
|
|
event filter. The `CGAL::Qt::GraphicsViewNavigation` event filter allows to zoom, scroll, and recenter.
|
|
Finally, the class emits a signal with the mouse coordinates. This can be used
|
|
to display the current mouse position in the status bar of an application.
|
|
|
|
\subsection GraphicsViewGenerationofInput Generation of Input
|
|
|
|
Input of \cgal `Kernel` objects, polylines, etc. is generated by classes derived
|
|
from `CGAL::Qt::GraphicsViewInput`. As the navigation class, they are event handler of the
|
|
graphics view, because they have to know where the mouse is, when the user clicks
|
|
in order to enter a point.
|
|
|
|
Once the input generator has assembled the object, which can involve several mouse clicks,
|
|
it emits a `CGAL::Object` wrapping the input. The emitted input can be connected
|
|
by the application developer to a slot. In the 2D demos of \cgal, which use the
|
|
Graphics View Framework we connect it to the slot `MainWindow::processInput(CGAL::Object)`.
|
|
This method unwraps from the `CGAL::Object` and inserts it in the data structure.
|
|
It then typically emits a signal `modelChanged()` which can be
|
|
connected to the graphics item representing the data structure.
|
|
|
|
All input generators we provide use the left mouse button for entering points.
|
|
The right click terminates a sequence of entered points. 'Delete' and 'backspace'
|
|
remove the last entered point. 'Esc' resets the input generator. As the 'Ctrl' key
|
|
is used by the `CGAL::Qt::GraphicsViewNavigation` this modifier is not used.
|
|
|
|
*/
|
|
} /* namespace CGAL */
|
|
|