doc/manual/manual.tex

   1 \documentclass[11pt,a4paper,oneside]{article}
   2 \usepackage[latin1]{inputenc}
   3 \usepackage{color}
   4 \usepackage{listings}
   5
   6 \ifx\pdftexversion\undefined % Check if we are compiling under latex or pdflatex
   7   \usepackage[dvips]{graphics}
   8 \else
   9   \usepackage[pdftex]{graphics}
  10 \fi
  11
  12 \definecolor{mycitecolor}{rgb}{0.25, 0.65, 0.15}
  13 \usepackage[pdfkeywords={Qanava, Manual},
  14     pdfsubject={Qanava Manual v0.1.0},
  15     pdfauthor={Benoit Autheman},
  16     pdftitle={Qanava Manual v0.1.0},
  17     citecolor=mycitecolor,
  18     pagebackref,
  19     bookmarksnumbered=true,
  20     colorlinks=true,
  21     bookmarksopen=true]{hyperref}
  22
  23 \definecolor{keywordscolor}{rgb}{0.0, 0.0, 1.0}
  24 \definecolor{commentscolor}{rgb}{0.0, 0.50, 0.0}
  25
  26
  27 % Put the figure were I want
  28 \usepackage{float}
  29 \restylefloat{figure}
  30
  31 \oddsidemargin 0cm
  32 \evensidemargin 0cm
  33
  34 \pagestyle{myheadings}
  35 \markboth{{\small Qanava User Manual}}{{\small Qanava User Manual}}
  36
  37 \textwidth 15.5cm
  38 \topmargin -1cm
  39 \parindent 0cm
  40 \textheight 24cm
  41 \parskip .4cm
  42
  43 \begin{document}
  44
  45 \title{Qanava Manual v0.1.0}
  46 \author{Benoit A.\\benoit@libqanava.org}
  47 \date{December 2006}
  48 \maketitle
  49
  50 \begin{abstract}
  51         This document is the Qanava library user manual. Qanava is a graph visualisation c++ library for Trolltech QT.
  52 \end{abstract}
  53
  54 \section{Introduction}
  55
  56         Qanava\footnote{ Qanava originally stands for Qt Canvas Avancé} (also known as libqanava) is a c++ graph visualisation library for the trolltech QT framework.
  57
  58 \section{Using Qanava}
  59
  60 \subsection{Installation}
  61
  62         To report problems and to look for information on , please consult the mailing list archive:
  63
  64
  65
  66
  67 \subsection{Configuring qmake to use Qanava}
  68
  69 There is two way to use libqanava in your project :
  70
  71 \begin{itemize}
  72         \item Embedding the library in your source tree: You can keep only the 'src' and 'build' subdirectory, as long as the file keep their original GPL header and copyright notice.
  73
  74         \item Using the library for multiple projects in a separate directory trought an environment variable (QANAVADIR usually).
  75 \end{itemize}
  76
  77         Configuring qmake consists in setting correct paths for header and library and configuring linkage and custom macro variables.
  78
  79 \begin{lstlisting}[frame=single,language=Make]
  80 MYQANAVADIR =$$(QANAVADIR)   # Can't test an envvar directly
  81 isEmpty(MYQANAVADIR ) {
  82         # Path to the local Qanava directory (for example
  83         # '../lib/qanava' if you are in the project source directory
  84         MYQANAVADIR="../lib/libqanava"
  85 }
  86 osx | unix {
  87 LIBS += -L$( MYQANAVADIR)/build/ -lqanava
  88 DEFINES += QANAVA_UNIX
  89 }
  90 win32:LIBS        = $(QANAVADIR)/build/qanava.lib
  91 QT += xml       # QT XML module is necessary for xml graph IO
  92 \end{lstlisting}
  93
  94 (pasting from this pdf file can lead to space characters corruption causing various qmake errors)
  95
  96 \section{Architecture}
  97 \subsection{Overview}
  98 \label{sec:arch_overview}
  99
 100 \begin{figure}[H]
 101   \begin{center}
 102         \resizebox{14.5cm}{!}{\includegraphics{qan-graph_model_overview}}
 103     \caption{\label{fig:qan-graph_model_overview} Graph Model View Overview}
 104   \end{center}
 105 \end{figure}
 106
 107         Qanava library has a data model to store topology of directed graphs and control their rendering in a QT GraphicsView. Graph can be created programatically or imported from an XML file in the GML format, see section \ref{sec:arch_graph}. Attributes of different types can be mapped to a graph node an accessed later in an application or in one of the ready to use visualisation widgets (see section \ref{sec:ui}). Graphic rendering is controlled by applying styles on every nodes in the GraphItemView. Finally, a layout algorithm set the position of nodes in space according to the graph topology and specific node attributes (for example, their date and time).
 108
 109
 110 \subsection{Qanava Graph Item View}
 111 \label{sec:arch_graphicsview}
 112
 113 \begin{figure}[H]
 114   \begin{center}
 115         \resizebox{10.5cm}{!}{\includegraphics{arch-graphitemview_tools.png}}
 116     \caption{\label{fig:arch-graphitemview_tools.png} Graph item view tool bar}
 117   \end{center}
 118 \end{figure}
 119
 120 \lstset{language=C++, keywordstyle=\color{keywordscolor},commentstyle=\color{commentscolor}}
 121
 122 \begin{lstlisting}[frame=single,language=C++]
 123 {
 124   qan::GraphicsView* graphicsView = graphItemView->getGraphicsView( );
 125
 126   QToolBar* zoomBar = addToolBar( "Zooming" );
 127   QSlider* sldZoom = new QSlider( Qt::Horizontal, zoomBar );
 128   sldZoom->setMinimum( 1 );
 129   sldZoom->setMaximum( 99 );
 130   sldZoom->setPageStep( 10 );
 131   sldZoom->setSliderPosition( 50 );
 132   sldZoom->setMinimumWidth( 190 );
 133   zoomBar->addWidget( sldZoom );
 134   connect( sldZoom, SIGNAL( valueChanged(int) ), graphicsView, SLOT( setZoomPercent(int) ) );
 135
 136   QToolBar* navigationBar = addToolBar( "Navigation" );
 137   navBar->setIconSize( QSize( 16, 16 ) );
 138   if ( graphicsView->getAction( "zoom_in" ) != 0 )
 139     navBar->addAction( graphicsView->getAction( "zoom_in" ) );
 140   if ( graphicsView->getAction( "zoom_out" ) != 0 )
 141     navBar->addAction( graphicsView->getAction( "zoom_out" ) );
 142   navBar->addSeparator( );
 143   if ( graphicsView->getAction( "pan_controller" ) != 0 )
 144     navBar->addAction( graphicsView->getAction( "pan_controller" ) );
 145   if ( graphicsView->getAction( "zoom_window_controller" ) != 0 )
 146     navBar->addAction( graphicsView->getAction( "zoom_window_controller" ) );
 147 }
 148 \end{lstlisting}
 149
 150         Once the view is correctly configured, a graph can be visualized using the view setModel() method.
 151
 152
 153 \subsection{Graph Definition}
 154 \label{sec:arch_graph}
 155
 156         Graphs in Qanava (class qan::Graph) are modelled with directed graph using a node and edge list structure. Node and edge must be created trough the qan::Graph interface, and the topology is available to the user via read-only accessors in the qan::Node and qan::Edge classes.
 157
 158         Graph can be modified in two modes:
 159
 160 \begin{enumerate}
 161 \item {\bf Offline:} This mode is the most efficient and should be used to initialize large graph only if there is no view connected to the graph. Offline methods are prefixed with
 162
 163 \item {\bf Online:} When a graph is actually visualized in a graphic view, node and edge must be created online to ensure that topology changes are reflected graphically in real time. The online mode can be quite inefficient for large graph since it use the QT Interview system to notify the view about  topology modifications.
 164 \end{enumerate}
 165
 166
 167 \begin{figure}[H]
 168   \begin{center}
 169         \resizebox{4.5cm}{!}{\includegraphics{graph-simple_topology}}
 170     \caption{\label{fig:graph-simple_topology} Example graph topology}
 171   \end{center}
 172 \end{figure}
 173
 174         To encode this simple topology in a Qanava graph, the following code should be used for static offline initialization:
 175
 176 \lstset{
 177         basicstyle=\small
 178 }
 179 \begin{lstlisting}[frame=single,language=C++]
 180 {
 181   qan::Graph* graph = new qan::Graph( );
 182   qan::Node* n1 = graph->addNode( "1" );
 183   qan::Node* n2 = graph->addNode( "2" );
 184   qan::Node* n3 = graph->addNode( "3" );
 185   qan::Node* n4 = graph->addNode( "4" );
 186   graph->addEdge( *n1, *n2 );
 187   graph->addEdge( *n1, *n3 );
 188   graph->addEdge( *n2, *n4 );
 189   graph->addEdge( *n3, *n4 );
 190 }
 191 \end{lstlisting}
 192
 193         Once the graph has been passed to a view setModel() method, insertNode() and insertEdge() must be used instead of addNode() and addEdge() to use online mode.
 194
 195 \subsection{Attributes}
 196 \label{sec:arch_attributes}
 197
 198
 199 \subsection{Styles}
 200 \label{sec:arch_styles}
 201
 202         As explained in section \ref{sec:arch_overview}, there is a strict separation between a graph topology and its node appearance. Rendering of graphic primitives (nodes, edges) is controlled at the view level by mapping styles to graph elements. A style is basically a stylesheet with a set of attributes with different types (color, integer, boolean, etc.) which is used by a primitive graphic element to customize its drawing.
 203
 204         A simple style with only a background color specification can be created and applyied to a graph node with the following code:
 205
 206 \begin{lstlisting}[frame=single,language=C++]
 207 {
 208   qan::Graph* graph = new qan::Graph( );
 209   qan::Node* node = graph->addNode( "n" );
 210   qan::GraphItemView* graphItemView =
 211                                 new qan::GraphItemView( this, graph );
 212
 213   Style* green = new Style( "greennode" );
 214   green->addColor( "backcolor", 164, 206, 57 );
 215   graphItemView->applyStyle( node, green );
 216
 217   graphItemView->setModel( graph );
 218 }
 219 \end{lstlisting}
 220
 221
 222 \subsection{Layouts}
 223 \label{sec:arch_layout}
 224
 225 \subsection{Using custom graphic nodes}
 226 \label{sec:arch_custom}
 227
 228         Qanava provide a factory mecanism to controll how a graphic element is mapped to graph nodes. The default factory provide a rectangular graphic item wich is able to interpret all the styling parameters detailled in section \ref{sec:arch_styles}. This default graphic element can be changed by registering a new factory that will provide a custom QGraphicsItem object able to draw itself on a QGraphicsView.
 229
 230 \begin{figure}[H]
 231   \begin{center}
 232         \resizebox{10.5cm}{!}{\includegraphics{06_09_29-qanava_custom-x11}}
 233     \caption{\label{fig:06_09_29-qanava_custom-x11} Using custom graphic nodes}
 234   \end{center}
 235 \end{figure}
 236
 237
 238 \subsection{Model and View}
 239 \label{sec:arch_mvc}
 240
 241         Qanava architecture strongly rely on the model/view pattern and understand the two following scenarios:
 242
 243 \begin{itemize}
 244         \item {\bf Viewing a user defined graph (usual way):} The standard way of displaying a graph is to pass an instance of qan::Graph to a GraphItemView setModel() method. Coherency between the graph and its view is managed automatically thanks to Interview, as long as you use the online mode to update the graph model. Contrary to the strict separation between model and view that is mandatory in the MVC pattern, the view must have a reference to the model graph to avoid costly caching and data duplication to take place (however, most of the collaboration goes trought the Interview interface).
 245
 246         \item {\bf Viewing an existing standard model:} qan::GraphItemView can display any model based on QT QAbstractItemModel interface (not only graph, but all Interview based models). The 'dirmodel' sample show how to display a QDirModel in a qan::GraphItemView with support for both model icon and text.
 247
 248                         \begin{figure}[H]
 249                           \begin{center}
 250                                 \resizebox{11.5cm}{!}{\includegraphics{06_06_07-qanava-qtmodelx11}}
 251                             \caption{\label{fig:06_06_07-qanava-qtmodelx11} Displaying an existing QT model (QDirModel)}
 252                           \end{center}
 253                         \end{figure}
 254
 255 \end{itemize}
 256
 257
 258 \section{Utility Widgets}
 259 \label{sec:ui}
 260
 261         Qanava provide ready to use widgets to visualize and modify the content of a graph:
 262
 263         \begin{itemize}
 264                 \item Node list: The ui::NodesItemModel transform a standard (hierarchical) graph item model into a list of nodes that can be viewed in a QT QListView of QTableView. Attributes registered in the graph (See section \ref{sec:arch_attributes}) are also available in the model column and shown thanks to the standard QT delegates. Example code for displaying a list of nodes in a table view:
 265
 266 \begin{lstlisting}[frame=single,language=C++]
 267 {
 268   ui::NodesItemModel* nodesItemModel =
 269                                                                 snew ui::NodesItemModel( *graph, this );
 270
 271   QTableView* tableView = new QTableView( this );
 272   tableView->setAlternatingRowColors( true );
 273   tableView->horizontalHeader( )->resizeSections( QHeaderView::Fixed );
 274   tableView->horizontalHeader( )->setStretchLastSection( true );
 275   tableView->verticalHeader( )->resizeSections( QHeaderView::Fixed );
 276   tableView->verticalHeader( )->setDefaultSectionSize( 20 );
 277   tableView->verticalHeader( )->hide( );
 278   tableView->setModel( nodesItemModel );
 279   tableView->adjustSize( );
 280 }
 281 \end{lstlisting}
 282
 283 A screenshot from the "terror" sample:
 284
 285                         \begin{figure}[H]
 286                           \begin{center}
 287                                 \resizebox{11.5cm}{!}{\includegraphics{ui-nodes_list}}
 288                             \caption{\label{fig:ui-nodes_list} Node list widget}
 289                           \end{center}
 290                         \end{figure}
 291
 292                 \item Style editor:
 293                         \begin{figure}[H]
 294                           \begin{center}
 295                                 \resizebox{5.5cm}{!}{\includegraphics{ui-style_editor}}
 296                             \caption{\label{fig:ui-style_editor} Style editor widget}
 297                           \end{center}
 298                         \end{figure}
 299         \end{itemize}
 300
 301 \section{Samples}
 302
 303         Most library features are demonstrated in the samples and the following example/feature matrix to explore the code in the "tests" subdirectory:
 304
 305 \begin{tabular}{|c||c|c|c|c|c|c|}
 306 \hline
 307                                 & Topology      & Layout & Styles & Interview & Custom Nodes & UI Widgets \\ \hline\hline
 308 basic                   & X             &                & X      &               &                      &                        \\ \hline
 309 styles                  &                       &                & X      &               &                      & X              \\ \hline
 310 layout                  & X             & X              &                &               &                      &                        \\ \hline
 311 qtmodel                 &                       &                &                & X             &                      &                        \\ \hline
 312 simpleqtmodel   &                       &                &                & X             &                      &                        \\ \hline
 313 terror                  & X             & X              & X      &               &                      & X              \\ \hline
 314 customnodes             &                       & X              &                &               & X                    &                        \\ \hline
 315 \end{tabular}
 316
 317
 318 \end{document}
 319