# The &kgraphviewer; Handbook

## Introduction

&kgraphviewer; is a &graphviz; ˙ graph viewer. The &graphviz; programs are free-software layout engines for graphs. &kgraphviewer; displays the graphs in a modern, user-friendly &GUI;. 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 ˙ 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:

- 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 ˙ 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 &calligra;'s &kexi; database application.

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

- The &Qt; and &kde-frameworks; libraries version 5.x;

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

- The &boost; library version 1.36.

## 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... and the (empty) Open Recent buttons. 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 ˙ 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 kgraphviewer-configuration.

##### Files and Windows

When you open a graph file from outside a running &kgraphviewer; instance, ⪚ 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 choice as the default 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 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 Appearance page allows to change the default background color used in &kgraphviewer; if a graph does not have its own background color.

Page to change the appearance of a graph Page to change the appearance of a graph

Page to change the appearance of a graph

The Parsing page allows to select an external command or the internal library for parsing &graphviz; ˙ files.

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 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:

  ˙

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

Reset Layout Command to Default

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

Export Graph

- As Image…

- Allows to export the full graph to all supported image formats.

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 Position

- 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;N File New

- Opens a new &kgraphviewer; window.

&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 all supported image formats.

&Ctrl;P File Print...

- Prints the current graph using the currently set print parameters.

&Ctrl;&Shift;P 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

&Ctrl;+View Zoom In

- Zoom in the current graph by 10%.

&Ctrl;-View Zoom Out

- Zoom out the current graph by 10%.

View Refresh

- Reloads the current graph.

View Layout Algorithm

- Opens a submenu with various &graphviz; layout algorithms for the current graph.

&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 Bird's-Eye View Position

- Configure where to place the Bird's-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 Settings and Help Menu

&kgraphviewer; has the common &kde; Settings and Help menu items, for more information read the sections about the Settings Menu and Help Menu of the &kde; Fundamentals.

### The &kgraphviewer; Toolbars

#### The Main Toolbar

- Shows the Open File dialog.

- Shows the list of recently opened files.

- Shows the Print Preview dialog.

#### The View Toolbar

- 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;
&documentation.index;