diff --git a/doc/en_US/index.docbook b/doc/en_US/index.docbook index b082694..599fab6 100644 --- a/doc/en_US/index.docbook +++ b/doc/en_US/index.docbook @@ -1,789 +1,789 @@ KGraphViewer"> Graphviz"> Boost"> GUI"> Tcl/Tk"> X11"> Qanava"> KCacheGrind"> Spirit"> Kexi"> Qt"> png"> DOT"> NEATO"> TWOPI"> FDP"> CIRCO"> ]> 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; ˙ 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. +&kgraphviewer; is a &graphviz; ˙ graph viewer. It is developed in the &kde; community. 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. +The &kgraphviewer; project aims to replace these tools with a modern, user-friendly &GUI;. KDE kgraphviewer graphviz dot neato viewer
Introduction -&kgraphviewer; is a &graphviz; ˙ 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: +&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 &koffice;'s &kexi; database application. -Other required software: &kgraphviewer; is a &kde; program that uses the &graphviz; tool ˙ for graph layout. Its dependencies are: +Other required software: &kgraphviewer; is a program that uses the &graphviz; tool ˙ for graph layout. Its dependencies are: - The &qt; library and &kde; libraries (kdelibs package) version 4.x; + The &qt; and &kf5; 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 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 ˙ 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 SettingsConfigure &kgraphviewer; menu item. See . 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 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: ˙ ˙ 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 defaults 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 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;OFileOpen Displays the Open File dialog. FileOpen Recent Displays the list of the ten most recently opened graph files. FileExport GraphAs Image... Allows to export the full graph to a &png; image. &Ctrl;PFilePrint... Prints the current graph using the currently set print parameters. FilePrint Preview... Opens the Print Preview window for the current graph. FilePage Setup Opens the Page Setup dialog for the current graph. &Ctrl;QFileQuit Quits &kgraphviewer;. The View Menu ViewRedisplay Reloads the current graph. &Ctrl;+ViewZoom In Zoom in the current graph by 10%. &Ctrl;-ViewZoom Out Zoom out the current graph by 10%. &Ctrl;BViewEnable 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. ViewBirds-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 &kgraphviewer; has the common &kde; Help menu items, for more information read the section about the Help Menu of the &kde; Fundamentals. The &kgraphviewer; Toolbars The Main Toolbar Shows the Open File dialog. Shows the list of recently opened files. Prints the graph using current setup. 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;