=================================
graphedit - A simple graph editor
=================================

Albert Graef <aggraef@gmail.com>

graphedit is an editor for simple, undirected graphs. This little application
demonstrates the use of the Gnocl Tcl extension to create a simple but
reasonably complete GTK+ application.

Installation
============

Make sure that you have Pure (>= 0.44), the Pure Tk module, Tcl/Tk (including
the Gnocl extension) and GTK+ installed. Then run ``make`` to compile the
program, and copy the resulting graphedit binary to some directory on your
``PATH``. More details can be found at the beginning of the graphedit.pure
script.

Usage
=====

You can run graphedit with the name of a graph file on the command line::

  graphedit [filename]

Note that graphedit uses its own file format for storing graphs. There are a
number of semi-standard graph file formats out there, but they are not
supported by graphedit right now. graphedit files are plain text and thus
cross-platform.  The ``Open`` command does some sanity checking when reading a
file, but you probably shouldn't try to edit these files by hand unless you
know what your doing.

The file format should be fairly self-explanatory: a magic header line
followed by another line with the actual data as a Pure term ``(V,E)``, where
``V`` is a list with the nodes and their coordinates (and labels, if any), and
``E`` the list of edges (and labels, if any), simple as that. Thus an
application can just skip the first and parse the second line (using val) in a
file to read the data. Note that in the current implementation node and edge
labels are just plain text, so you'll need to convert them to whatever data
type is needed by the application.

Inside graphedit, you'll find a number of menu commands that should mostly be
self-explanatory. The following mouse actions let you draw a graph on the
canvas:

* Mouse-1 (`Select`): Starting in an empty spot on the canvas, you can start
  dragging the mouse with the *left* mouse button to show a rubberband which
  lets you select a subgraph. Holding the ``Ctrl`` key when releasing the
  mouse adds to the current selection, otherwise the selection is changed to
  the newly selected subgraph. To abort the selection operation, press the
  ``Esc`` key while dragging. You can also just click directly on a node or
  edge or its label with the left mouse button to select it; in this case,
  ``Ctrl`` toggles the selection, so that you can select and deselect single
  nodes and edges. Visual feedback is given by displaying the currently
  selected nodes and edges in red.

* Mouse-2 (`Move`): You can start dragging the mouse with the *middle* mouse
  button on a *selected node* (or its label) to display the bounding box of
  the selected subgraph. This allows you to drag the selected subgraph to a
  new location (with the middle mouse button still pressed). To abort the move
  operation, press the ``Esc`` key while dragging.

* Mouse-3 (`Node`/`Edge`): Clicking the *right* mouse button on an empty spot
  creates a new node. When clicking on an *existing node*, the node turns blue
  which indicates that you entered a special mode which allows you to create
  an edge starting at this node. Release the right mouse button, move the
  mouse to the desired target location and click the right mouse button again
  to actually create the edge. If you click on an existing node then the edge
  goes to that node, otherwise a new target node at the clicked position is
  automatically created for you. Clicking with any other mouse button or
  pressing ``Esc`` aborts the operation.

The ``Cut``, ``Copy``, ``Duplicate`` and ``Delete`` commands in the ``Edit``
menu operate on the current selection. Also, if a single node or edge is
selected, you can edit its label in the entry field on the toolbar. The
alignment of the labels can be changed with the commands in the ``Align``
menu. The ``View`` menu has operations to toggle the display of node and edge
labels, as well as an operation to automatically label the nodes with node
numbers (in the same order in which the nodes are written to a file). The
``Select Path`` and ``Select Subgraph`` operations in the ``Edit`` menu also
use the same node numbering. This is convenient if the graph is used in other
Pure programs, e.g., in order to interpret and visualize the results of
various graph algorithms.

The spin button on the toolbar lets you set a grid size, so that it becomes
easier to properly align nodes with each other.  A value of zero means no
grid. Otherwise the grid is shown on the canvas and newly created nodes snap
to the grid. The ``Move`` operation also warps all selected nodes to the grid,
so a quick way to get an entire graph aligned on the grid is to just select
all nodes and then do a (trivial) ``Move`` operation.

There are a number of handy keyboard shortcuts, browse the menus to learn
about those. A toolbar with the most common operations is available as well.
You can also tear off the menus and employ them as a kind of floating
toolbars; this is most useful for the ``Align`` menu for which there are no
options on the toolbar.

At this time, graphedit only supports simple undirected graphs (no loops, no
multi- or hyperedges), but I hope that it's still useful for some things. Hey,
this is just a demo, what did you expect? ;-) Of course, you're welcome to
extend graphedit and make your improved version available to other Pure
programmers!
