Up to now, we have used a \gviz\ context \gvc\ without
considering its purpose. As suggested earlier, this value is used
to store various layout information that is independent of a particular
-graph and its attributes. In particular, it maintains lists of the
+graph and its attributes.
+It holds the data associated with plugins, parsed-command lines,
+script engines, and anything else with a scope potentially larger
+than one graph, up to the scope of the application.
+In addition, it maintains lists of the
available layout algorithms and renderers; it also records the most recent
layout algorithm applied to a graph. It can be used to specify multiple
renderings of a given graph layout into different associated files.
It is also used to store various global information used during
rendering.
+There should be just one \gvc\ created for the entire
+duration of an application.
A single \gvc\ value can be used with multiple graphs, though
with only one graph at a time. In addition, if {\tt gvLayout()}
was invoked for a graph and \gvc, then {\tt gvFreeLayout()} should
\subsection{Application-specific data}
\label{sec:info}
-When possible, the code generators in the library log how an image file
-was created in the output file. To do this, they rely on
+It is sometimes useful to supply version information.
+For example, some renderers in \gviz\ the library version used
+to create the output file. To do this, they rely on
the application providing an array
\begin{verbatim}
extern char* Info[3];
char *Info[] = {
"dot", /* Program */
"1.8.10", /* Version */
- "16 Dec 2006" /* Build Date */
+ "16 Dec 2006" /* Build Date */
};
\end{verbatim}
The fields have the following meanings.
\begin{description}
\item[{\tt id}]
-Unique identifier for a given plug-in within a given package and with
-a given API kind.
+Identifier for a given plug-in within a given package and with
+a given API kind. Note that the {\tt id} need only be unique within
+its plug-in package, as these packages are assumed to be independent.
\item[{\tt type}]
Name for a given plug-in, used during plug-in lookup.
\item[{\tt quality}]
An arbitrary integer used for ordering plug-ins with the same {\tt type}.
-Plug-ins with smaller values will be chosen before plug-ins with larger
+Plug-ins with larger values will be chosen before plug-ins with smaller
values.
\item[{\tt engine}]
Points to the related engine structure.
Finally, the library must be installed in the \gviz\ library directory,
and {\tt dot -c} must be run to add the package to the \gviz\ configuration.
+Note that both of these steps typically assume that one has installer
+privileges.\footnote{
+Normally, for builds intended for local installation {\tt dot -c} is run
+during {\tt make install}.
+It may be necessary to run this manually if cross-compiling or otherwise
+manually moving binaries to a different system.
+}
In the remainder of this section, we shall look at the first
three types of plug-in APIs in more detail.
{\tt GVRENDER\_DOES\_TRUECOLOR} & Supports a truecolor color model \\
{\tt GVRENDER\_Y\_GOES\_DOWN} & Output coordinate system has the origin in
the upper left corner \\
-{\tt GVRENDER\_X11\_EVENTS} & {\bf ASK} \\
+{\tt GVRENDER\_X11\_EVENTS} & For GUI plug-ins, defers actual rendering until
+the GUI event loop invokes {\tt job->callbacks->refresh()} \\
{\tt GVRENDER\_DOES\_TRANSFORM} & Can handle transformation (scaling,
translation, rotation) from universal
to device coordinates. If false, the library will do the transformation
before passing any coordinates to the renderer \\
{\tt GVRENDER\_DOES\_LABELS} & Wants an object's label, if any, provided
-as text during rendering {\bf ASK} \\
+as text during rendering \\
{\tt GVRENDER\_DOES\_MAPS} & Supports regions to which URLs can be attached.
If true, URLs are provided to the renderer,
either as part of the {\tt job->obj} or via the renderer's {\tt begin\_anchor}
projects / graphviz / commitdiff