# The &kgraphviewer; Handbook

Gaël
de Chalendar

    kleag@free.fr

Federico
Zenith

    federico.zenith@member.fsf.org

2006
Gaël de Chalendar
&FDLNotice;
2006-10-22
1.0.3

&kgraphviewer; is a &graphviz; &dot; graph viewer for &kde;. The &graphviz; programs are free-software layout engines for graphs. Graphs are commonly used in scientific domains and particularly in computer science. Until now, there was a lack of a modern &GUI; to look at the graphs. The programs that come with &graphviz; are in my opinion out-of-date &X11; or &tcltk; applications with few features.

The &kgraphviewer; project aims to replace these tools with a modern, user-friendly &GUI; with all the power of a well integrated &kde; application.

KDE
kgraphviewer
graphviz
dot
neato
viewer

## Introduction

&kgraphviewer; is a &graphviz; &dot; graph viewer for &kde;. The &graphviz; programs are free-software layout engines for graphs. &kgraphviewer; displays the graphs in a modern, user-friendly &GUI; with all the power of a well integrated &kde; application. It has the following features: Here is a screenshot of &kgraphviewer; The main &kgraphviewer; window displaying one of the &graphviz; examples

- Zooming;

- Loading of several graphs in tabs at the same time;

- Storage of a list of recent files;

- A bird's eye view of the graph;

- Graph panning by mouse dragging;

- Full-featured printing;

- Perfect drawing of all &graphviz; example graphs;

- Node and edge colors and all node shapes are supported;

- Automatic choice of &dot; for directed graphs and &neato; for undirected ones;

- Manual or automatic reloading with user confirmation of (externally) modified files (configurable);

- Opening of new program instances as new tabs in an existing instance (configurable);

- Help system;

- Internationalization.

Planned features are:

- Port to &kde; 4

- Eventual use of the &qanava; library to support internal graphs representation;

- Save session data about graphs (layout program used, zoom factor, &etc;)

- Integration in &kate; and &konqueror; (so that a change in &kate;'s view of the graph would re-layout and reload the file in &kgraphviewer;);

- Menu to open the file in &kate; or to open a katepart inside the &kgraphviewer; window;

- Loading of large and huge graphs (currently, there are performance problems at around 1000 nodes, and a hack to ignore nodes above a specified limit);

- Progressive support of more and more &dot; attributes and values;

- Layout in background (with threading in order not to block the interface, with a progress bar).

Note that this program includes code from the GPL tool &kcachegrind; by Josef Weidendorfer, with his authorization.

Note also that the printing system is from the &koffice;'s &kexi; database application.

Other required software: &kgraphviewer; is a &kde; program that uses the &graphviz; tool &dot; for graph layout. Its dependencies are:

- The &qt; library 3.x (3.3.6 and above to avoid a painting bug);

- &kde; libraries (kdelibs package); the program was developed and tested with version 3.5.2;

- The &graphviz; tools as externals programs (tested with version 2.8);

- The &boost; &spirit; library (tested with version 0.32).

## Using &kgraphviewer;

### The Main Window

The main window displays the loaded graphs, each in its own tab. Initially, if you start &kgraphviewer; without arguments, its main window will be empty as in the screenshot below. In this case, the toolbar contains only the Open File and the (empty) Recently Opened Files items. Click on the first one to open the standard Open File dialog.

The initial main window when opening &kgraphviewer; for the first time
The initial main window when opening &kgraphviewer; for the first time

The initial main window when opening &kgraphviewer; for the first time

After selecting one or several &dot; files, the main window looks like the next screenshot below:

The main window of &kgraphviewer; with several files opened
The main window of &kgraphviewer; with several files opened

The main window of &kgraphviewer; with several files opened

As you can see, if the graph is larger than the available area, a bird's-eye view is shown in one corner. You can choose with the context menu whether the optimal position of this overview should be automatically computed for you, or place it where you want yourself.

#### Moving the Graph inside the Window

To move the graph, you can:

- Click and drag it;

- Use the scroll bars;

- Press the arrows keys;

- Click somewhere in the bird's-eye view;

- Use the mouse wheel (up and down with no modifier, left and right with the &Alt; key pressed);

- or click and drag in the bird's-eye view.

#### Zooming

To zoom, you can either use the and toolbar buttons to zoom in and out, or hold down the &Shift; key while rolling your mouse wheel. While zooming in, the red rectangle in the bird's-eye view that indicates the displayed zone gets smaller and smaller. If it were to get smaller than 10 pixels in its shorter side, it will be replaced by a filled red rectangle in order to stay visible. You can see that on the screenshot below.

A graph at the maximal zoom in level
A graph at the maximal zoom in level

A graph at the maximal zoom in level

Zooming is limited in both directions by a factor of 10. You can see below the maximum zoom-out factor on a graph.

A graph at the maximum zoom-out level
A graph at the maximum zoom-out level

A graph at the maximum zoom-out level

#### Graph Files Handling

##### Files Modified on Disk

If a file currently loaded in &kgraphviewer; is modified by another program, the following dialog is shown:

Dialog to reload a file modified on disk
Dialog to reload a file modified on disk

Dialog to reload a file modified on disk

You can choose to reload the graph or to ignore the change. You can also get &kgraphviewer; to remember your choice, so it will do the same thing the next time. If you later want to modify your choice, choose the Settings Configure &kgraphviewer; menu item. See .

##### Files and Windows

When you open a graph file from outside a running &kgraphviewer; instance, &eg; from a file browser or the command line, you have the choice to open a new &kgraphviewer; window or to open the graph in a new tab in the existing window. This is done with the dialog below.

Dialog to open a new window
Dialog to open a new window

Dialog to open a new window

As for the previous option, you can save your default choice and modify it later in the configuration dialog.

##### Session Handling

At start-up, you can choose to reopen the graphs that you had opened the previous time. Again, you can save your choice and change it later.

Dialog to reload the graph of the previous session at start-up
Dialog to reload the graph of the previous session at start-up

Dialog to reload the graph of the previous session at start-up

### Graph Printing

Try the Print preview or the Page setup buttons to explore the printing options.

Page setup dialog
Page setup dialog

Page setup dialog

You can setup the printing options to fit the graph on exactly one page, as below:

Page preview setup to fit on one page
Page preview setup to fit on one page

Page preview setup to fit on one page

You can also choose how to divide the graph on multiple pages. The number of horizontal and vertical pages can be chosen independently.

Page preview set up to fit on multiple pages and to fill them
Page preview set up to fit on multiple pages and to fill them

Page preview set up to fit on multiple pages and to fill them

Finally, when using multiple pages, you can choose to make the part of the graph on each page to fit its page like above, not keeping the aspect ratio, or to keep it. In the latter case, the pages will not be filled.

You can change the size of pages and the margins:

Page size and margins dialog
Page size and margins dialog

Page size and margins dialog

You can also change the font, headers and footers:

Page preview setup to fit on multiple pages without header and with a different font
Page preview setup to fit on multiple pages without header and a different font

Page preview setup to fit on multiple pages without header and a different font

### Configuring &kgraphviewer;

The Reload page allows to change the behavior of &kgraphviewer; when a file is changed on disk by another application. You can choose a default action (reload automatically or ignore changes), or to be asked each time.

Page to reload files modified on disk in the configuration dialog
Page to reload files modified on disk in the configuration dialog

Page to reload files modified on disk in the configuration dialog

The Opening page allows to change the behavior of &kgraphviewer; when a graph file is opened from outside the current session. You can choose a default action (open in an existing window or in a new one), or to be asked each time.

Page to open new files in an existing window in the configuration dialog
Page to open new files in an existing window in the configuration dialog

Page to open new files in an existing window in the configuration dialog

The Session Management page allows to change the &kgraphviewer;'s start-up behavior. You can choose a default action (reopen files of the previous session or not), or to be asked each time.

Page to reopen files of the previous session in the configuration dialog
Page to reopen files of the previous session in the configuration dialog

Page to reopen files of the previous session in the configuration dialog

### Miscellaneous Functions

The context menu, usually obtained by clicking the &RMB; in the graph view, offers some other possibilities:

Layout

  This allows to choose between various &graphviz; layout algorithms or to choose your own one. The entries, as described on the &graphviz; homepage, are the following:

  &dot;

    &dot; algorithm, default for directed graphs. It produces hierarchical or layered drawings of directed graphs. The layout algorithm lays edges in the same direction (top to bottom, or left to right), and then attempts to avoid edge crossings and to reduce edge length.

  &neato;

    &neato; algorithm, default for undirected graphs. It produces spring model layouts. It uses the Kamada-Kawai algorithm, which is equivalent to statistical multi-dimensional scaling.

  &twopi;

    &twopi; algorithm, for directed and undirected graphs. Radial layout, after Graham Wills 1997.

  &fdp;

    &fdp; algorithm, for undirected graphs. It produces spring model layouts. It implements the Fruchterman-Reingold heuristic including a multigrid solver that handles larger graphs and clustered undirected graphs.

  &circo;

    &circo; algorithm. It produces a circular layout, after Six and Tollis 1999, Kauffman and Wiese 2002. Suitable for certain diagrams of multiple cyclic structures.

  Specify layout command

    Opens a dialog allowing you to specify a layout command executed by the shell. This command should accept one parameter, the graph file name, and write its layout on stdout in the xdot language. This way, you can give specific options to one of the previous commands, or apply a filter modifying your graph before running it through &dot;.

  Reset layout command to defaults

    Determine the graph type (directed or not) and apply the default algorithm to it, currently &dot; and &neato; respectively.

Export Graph

  As Image...

    Allows to export the full graph to a &png; image.

Enable Bird's-eye View

  When checked, the Bird's-eye view is displayed when necessary. Otherwise, it is hidden and its positioning menu is disabled.

Bird's-eye View

  Configure where to place the bird's-eye view in the graph view. The possible choices are:

  Top Left

    Places the bird's-eye view at the top left corner;

  Top Right

    Places the bird's-eye view at the top right corner;

  Bottom Left

    Places the bird's-eye view at the bottom left corner;

  Bottom Right

    Places the bird's-eye view at the bottom right corner;

  Automatic

    Automatically choose the best position to hide as little of the graph as possible.

## Command Reference

### The &kgraphviewer; Menus

#### The File Menu

&Ctrl;O File Open

  Displays the Open File dialog.

File Open Recent

  Displays the list of the ten most recently opened graph files.

File Export Graph As Image...

  Allows to export the full graph to a &png; image.

&Ctrl;P File Print...

  Prints the current graph using the currently set print parameters.

File Print Preview...

  Opens the Print Preview window for the current graph.

File Page Setup

  Opens the Page Setup dialog for the current graph.

&Ctrl;Q File Quit

  Quits &kgraphviewer;.

#### The View Menu

View Redisplay

  Reloads the current graph.

&Ctrl;+View Zoom In

  Zoom in the current graph by 10%.

&Ctrl;-View Zoom Out

  Zoom out the current graph by 10%.

&Ctrl;B View Enable Bird's-eye View

  When checked, the Bird's-eye view is displayed when necessary. Otherwise, it is hidden and its positioning menu is disabled.

View Birds-eye View

  Configure where to place the bird-eye view in the graph view. Choices are:

  Top Left

    Places the bird's-eye view at the top left corner;

  Top Right

    Places the bird's-eye view at the top right corner;

  Bottom Left

    Places the bird's-eye view at the bottom left corner;

  Bottom Right

    Places the bird's-eye view at the bottom right corner;

  Automatic

    Automatically choose the best position to hide as little of the graph as possible.

#### The Help Menu

&help.menu.documentation;

### The &kgraphviewer; Toolbars

#### The Main Toolbar

  Shows the Open File dialog.

  Shows the list of recently opened files.

  Prints the graph using current setup.

  Shows the Print Preview dialog.

  Shows the Page Setup dialog.

#### The View Toolbar

  Reloads the current graph.

  Edits the layout command or shows the list of preset layout algorithms.

  Zoom in the current graph by 10%.

  Zoom out the current graph by 10%.

#### The Help Toolbar

  Displays the What's This mouse pointer. Click with it on a &GUI; element to obtain help using it (if there is such help available).

## Credits and License

### Program

#### Main Authors

Program copyright 2005-2006 Gaël de Chalendar kleag@free.fr

#### Contributors (to be completed)

- Reimar Döffinger Reimar.Doeffinger@stud.uni-karlsruhe.de

### User Guide

Documentation copyright 2006 Gaël de Chalendar kleag@free.fr

#### Contributors

- Federico Zenith federico.zenith@member.fsf.org

### Other Credits

This program contains reused code from the following Free Software projects:

&kcachegrind;

  Initial graph model and view classes;

&kexi;

  Print setup and preview classes.

### Licenses

&underFDL; &underGPL;

## Installation

### How to obtain &kgraphviewer;

&kgraphviewer; is part of the &kde; extragear package. Its Subversion repository can be found on websvn.kde.org.

Independent releases of &kgraphviewer; can be found at &kgraphviewer;'s home page.

You can find a list of changes at this link and in the `ChangeLog` file at the root of the distribution archive.

### Dependencies

&kgraphviewer; is a &kde; program that uses the &graphviz; tools for graphs layout. It requires the following programs to be installed:

- &qt; libraries 3.x (3.3.6 and above to avoid a painting bug);

- &kde; libraries (developed and tested with version 3.5.x);

- The &graphviz; tools (tested with versions up to 2.8);

- The &boost; &spirit; library (tested with version 0.32).

### Compilation and Installation

&install.compile.documentation;

### Configuration

No special configuration is necessary to use &kgraphviewer;. See the Settings menu for some options.

&documentation.index;