Gruff version 8.1.4

Introduction

Gruff is an interactive tool for browsing, querying, and editing triple-stores (which are also known as graph databases or repositories). It works with AllegroGraph from Franz Inc. and to a somewhat lesser extent with any SPARQL endpoint. Information can be browsed as visual graphs of nodes and link lines that are laid out automatically, and also as tables of properties for particular nodes. Queries can be written textually as SPARQL or Prolog code, or designed graphically as diagrams of nodes and link lines. When using AllegroGraph, triples can be created and edited by filling in tables of property values or by connecting visual nodes with link lines, and paths can be found between any two end nodes, with the intervening nodes and links added to the visual graph automatically. The various views and features are tightly integrated to facilitate a smooth and rapid workflow.

Gruff Installation

As of AllegroGraph 7.0.0, Gruff is now part of the AllegroGraph server installation and has been integrated into AGWebView. And Gruff itself can now run in a web browser on any platform. So altogether there are now three different ways you can run Gruff:

For WebView Gruff and GruffJS, the officially supported web browsers are Chrome, Firefox, Safari, Edge, Opera, Vivaldi and Brave, though any Chromium-based browser is expected to work. Internet Explorer cannot be supported because its JavaScript support is too out-of-date. One limitation of Safari is that File | Save Layout as Pixmap and File | Display Layout in New Browser Tab are not working.

For macOS and Linux, GruffJS looks much nicer and is more convenient to use than Desktop Gruff, since the latter uses GTK and the former only requires a supported browser. It also allows zooming the entire Gruff interface in or out, by using the browser's usual keystrokes.

Using WebView Gruff

To start WebView Gruff, simply click on a Gruff icon in WebView. Gruff then runs on the same server machine where AllegroGraph is running, but displays in the web browser where you are using WebView on a client machine. So nothing needs to be installed on the client machine, other than a web browser. Files that you save will be stored on the server machine where Gruff is running, rather than on the machine where you are using Gruff (as with stanadlone Gruff). To protect the server machine, there are certain restrictions such as all files getting saved into a particular directory that's provided for each user, without being able to generally browse the file system of the server machine.

Standalone Gruff Downloads

A free, standalone version of Gruff for Mac, Windows or Linux is availabe from our website.

See the appropriate section below for installation on your operating system.

Installing and Running GruffJS on macOS

The process of downloading the Gruff .dmg via a web browser quarantines the download so it does not appear to be code signed. To remove the quarantine attribute, you can do this: 

$ xattr -d com.apple.quarantine macosx86-64.64/gruff-8.1.4-AG7.0.0-macosx86-64.64-ACL10.1.dmg

in a Terminal window.

To install, double-click on the downloaded .dmg file and then drag the Gruff application icon to the /Applications folder. If you are not logged in as an administrator, then you will need to authenticate to copy the application to /Applications/. Once there, you can run GruffJS by double-clicking on the newly available icon. Be careful not to run the application from the Finder window opened on the .dmg. We recommend you eject the volume which was mounted when you opened the .dmg file, after the application has been copied.

Now that Gruff runs in a web browser on the Mac, you may also see an entry for Gruff in the Command+Tab ring of applications. That is just an artifact of installing Gruff as a standard Mac application, and its boilerplate menu commands are not the Gruff functionality at all. Please just ignore this artifact and find Gruff in your web browser. An exception is that you will probably need to exit from this dummy Gruff interface if Gruff should fail to exit in the usual way for some reason, before you can run Gruff again.

Desktop Gruff has been deprecated on macOS. GruffJS is easier to install and use than the GTK version.

Installing and Running Gruff on Windows

The installation package on Windows is delivered as a signed .exe. Just run the executable to install. Once installed, there are different shortcuts on the Start menu for the desktop and browser versions.

Installing and Running Gruff on Linux

After you un-tar the download, run the gruff binary in the extracted directory.

By default, Gruff on Linux uses the browser. See the --run-as-web-browser-server command line argument for starting the GTK version of Gruff, at Running Gruff in a Web Browser.

Using Gruff with AllegroGraph or SPARQL Endpoints

Any Gruff installation will work with AllegroGraph and any SPARQL endpoint. Using Gruff with AllegroGraph requires an AllegroGraph server that's running on a 64-bit Linux machine (which can be a virtual machine on other types of hardware). Using Gruff with a SPARQL endpoint requires access to that endpoint (some are public while others are private) as well as a password that's provided by Franz. Contact [email protected] for a SPARQL endpoints password.

Some commands are not available with SPARQL endpoints, either because there's no way to do them using only SPARQL queries (which is the only interface to a SPARQL endpoint), or because they modify the database (which Gruff generally does not support with SPARQL endpoints even though some servers may allow that), or because they are specific to AllegroGraph in some other way. This includes the commands for finding paths between two end nodes (except with Stardog servers).

See File | Connect to SPARQL Endpoint for details.

Getting Started

Here are some general steps for getting started. In this document, an expression like File | New Triple-Store refers to the New Triple-Store command on the drop-down File menu on the menu bar at the top of the Gruff window.

When using Gruff with AllegroGraph, first use File | New Triple-Store to create a new AllegroGraph repository, followed by File | Load Triples | Load N-Triples (or other format) to load triples from a standard N-Triples file or web page into the new store. Alternately use File | Open Triple-Store to open an AllegroGraph repository that has already been created.

When using Gruff with a SPARQL endpoint, instead begin with File | Connect to SPARQL Endpoint.

Using the Various Gruff Views

Gruff starts up in the graph view that displays a network of nodes connected by link lines. This diagram (which is empty initially) is called a visual graph to differentiate it from the actual dataset, which is also called a graph. The View Menu lets you switch to a different view, and it can useful to begin a Gruff session in any of the available views, depending on the desired task. The various views are:

Using Gruff Menus

Gruff commands can found both on the global menu bar at the top of the window and in context-sensitive right-click pop-up menus. Many of the menu bar commands are applicable in multiple views, and the menu bar will contain only those commands that are applicable in the current view. Right-click pop-up menus contain a mixture of commands that are also on the menu bar with more specialized commands for the particular object that you click on.

The commands on the menu bar are described in the reference section called The Menu Bar Commands, whereas the right-click pop-up menu commands are described in the section for each Gruff view in which they appear.

In both drop-down and pop-up menus, be sure to notice the help strings that are displayed in the status bar at the bottom of the Gruff window as you highlight each menu command. You can also press F1 while highlighting a menu command to view the documenation for that particular command.

Gruff can be used more efficiently when using the keyboard shortcuts that are shown on the right of many menu commands. Many of the shortcuts are single keys for using them extra quickly.

Below is a guide to each of the Gruff views, followed by a reference section for the menu bar commands.

The Graph View

The graph view displays a visual graph of a subset of the nodes and links that are in the store that you are currently browsing. The nodes are automatically arranged (or "laid out") to make the relationships readable. The layout algorithms specialize in cyclic graphs that are common in triple-stores, which often express many relationships between various objects.

There are two layout algorithms: a constraint-based algorithm that's used for smaller visual graphs, and a spring-based algorithm that's used for larger graphs. The constraint-based algorithm avoids link lines that pass through unrelated nodes, so that it is easy to spot all of the nodes that are linked with any other node. The spring-based algorithm does not do that, but handles larger sets of nodes and links much more quickly.

A node in the graph view is a labeled box that represents a resource or literal in the store. A link is a straight line segment between two nodes that represents one or more of the triples that link those nodes.

The legend pane at the left displays a sample link for each predicate that's used in the triples that are currently displayed in the graph view, and a sample node for each type of node in those triples. These sample links and nodes indicate the color and line style that are used for each predicate and node type. For more information see View | Optional Graph View Panes | Show Legend, which is the menu command that toggles the legend on and off.

At the bottom of the legend is the overview pane that shows an overview of all of the nodes and links that are in view and scrolled out of view. The overview pane can be used to scroll the graph view quickly. For more information see View | Optional Graph View Panes | Show Overview.

Using Menu Commands in the Graph View

You can build a visual graph incrementally by using commands on The Display Menu and The Link Menu for selecting particular nodes to display. Or you can graph large sets of nodes at once by using commands such as Display | Display Some Sample Triples or the Create Visual Graph button in the query view (see Generating Visual Graphs from Query Results).

The commands on the Display menu offer alternative way to select an arbitrary node to display. The commands on the Link menu are options for displaying nodes that are linked with nodes that are already displayed. You typically begin by using a Display menu command to place a "starter" node onto the display. Then typically you will use commands on the Link menu multiple times to add linked nodes and build a visual graph. If too many nodes accumulate, you can remove some of them from the display with commands on the Remove menu.

The Display menu provides various alternatives for selecting an initial node, where particular commands may or may not be useful depending on the particular triple-store that you are browsing. The first command, Display | Display a Node by URI or Literal, can be used in any triple-store, but it requires that you enter a complete URI or literal string, which might be unknown or tedious to enter. Just type or paste the URI or literal string into the dialog that this command shows. (You can use namespace abbreviations if they are defined in Global Options | Namespace Abbreviations.) Display | Display a Node by Label is more convenient because it allows you to enter the more human-readable skos:prefLabel or rdfs:label property of the node, but it only works for nodes that have one or both of those properties in the triple-store. Display | Display an Instance Node by Class Hierarchy is a convenient place to start if the triple-store contains rdfs:subClassOf triples. Otherwise Display | Display an Instance Node by Type is handy if the store contains rdf:type triples. If you've already browsed this store in Gruff, then Display | Display a Recently Selected Node may be the most convenient way to get started, by simply selecting a node that you were browsing in the previous Gruff session. You may need to experiment with these commands to find the most convenient one for a particular store.

Once you have used the Display menu to place a starter node into the graph view, you can add nodes that are linked to nodes that are already displayed. There are several ways to do this, but here are just two:

(1) Click a node to select it and then Use View | Table View to display a table of all resources and literals that are linked with that node in the triple-store. (Alternately just double-click the node.) Browsing to related nodes by left-clicking values in the righthand column of the table will add the chain of browsed nodes to the visual graph, which you will discover when you next use View | Graph View to switch back to the graph view. (To display several nodes that are linked with the node that's in the table, shift-left-click each one).

(2) Or use Global Options | Select Current Predicates to choose a set of interesting predicates. Then repeatedly do the following: click a node to select it and then use Link | Display Linked Nodes for the Current Predicates to quickly build a visual graph of the relationships between a set of nodes for the predicates that you selected. See Using Current Predicates to Quickly Build a Graph below for details.

An alternative for building a visual graph quickly is to use View | Query View to jump to the view for queries, then do a query, and finally use the Create Visual Graph button (see Generating Visual Graphs from Query Results). Another approach is to build a store (or an ntriples file) outside of Gruff that contains only the triples that you want to display in a visual graph, then load that data into Gruff and use Display | Display Some Sample Triples.

The Layout Menu contains miscellaneous commands for updating the layout (meaning how the nodes are arranged for readability), making the scrollable canvas into which the layout is fitted larger or smaller, zooming in and out, and so on. These commands can be used at most any time.

When adding nodes to the display, the layout will be updated automatically as needed. The automatic update uses the Layout | Update Layout Incrementally command, and so you may occasionally want to use the Layout | Redo Layout from Scratch command to get a cleaner layout. Keep in mind that if there is a selected node then a layout will not move it (when the constraint-based algorithm is used), so sometimes you may want to click the background (or press the spacebar) to deselect any selected node just before doing a layout.

Special Mouse Clicks in the Graph View

In addition to The Menu Bar Commands, there are some special mouse clicks in the graph view.

Using Current Predicates to Quickly Build a Graph

One handy way to build a visual graph quickly is to select a set of predicates that are currently of interest, and then to repeatedly display nodes that are linked with already-visible nodes by those predicates. Here are the general steps to do that:

Interrupting a Long-Running Layout

If you continue adding nodes to the display, before long you will reach a point where a layout operation fails to reach a satisfactory state where it can stop. Typically you will see nodes jumping about rather wildly (thrashing). When this happens, you have a few choices:

Select | Deselect the Selected Node and/or Link). Then use the View | Go Back command to return to the previous good state, where you can choose a different operation that would add fewer nodes and/or links to the display. In particular, if Link | Display Linked Nodes for the Current Predicates adds too many nodes, then you can instead use Link | Display Linked Nodes from an Outline to choose an explicit subset of the nodes that the other command had tried to add by default. Or use View | Table View to select individual nodes to add from the table, and then toggle back to the graph view to see them.

The Selected Node

Some commands are applied to the selected node, if there is one. You can click on a node to select it before applying a command to it, or click the background (anywhere but on a node or link) to deselect the selected node. Certain commands may reselect the previously selected node automatically. The selected node will be drawn with a thick red border to distinguish it.

The layout procedure will keep the selected node in place, if there is one, so for a more general layout you may want to deselect the selected node before using a layout command. The selected node can be deselected with the keyboard by pressing the spacebar, which is the keyboard shortcut for Select | Deselect the Selected Node and/or Link.

You can also click a link to select it, though the selected link is not used for a lot. There can be a selected node and a selected link at the same time, and clicking the background deselects both. The selected link line will be red.

Visual Indicators in the Graph View

The background color of a node reflects one of the type properties of the node (by default), and the various types for which there currently are displayed nodes will be shown in the legend pane to the left. Random colors will be assigned to types initially, but you can assign your own colors with Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type. Alternately right-click a node in the legend pane and choose Set Background Color for Type from the pop-up menu.

Node background color can alternately indicate whether the node has additional linked nodes in the database that are not currently displayed, and which you could therefore add to the display. Briefly, yellow (by default) means it has additional linked nodes for the current predicates, green that it has additional linked nodes for other predicates, and cyan that it has no additional linked nodes. See About Node Background Color for Unseen Links in the middle of the documentation for The Link Menu for details. You can choose the current color mode on The Visual Graph Options Menu.

The color and dashing style of a link are initially chosen automatically so that there is a different line style for each predicate. You can assign your own colors and dashing styles with Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate, or by right-clicking a link line in the legend pane. A single color will be used for all link lines that represent multiple predicates; in this case the tooltip for the link line will list all of the predicates that the link line represents.

The selected node (if any) will have a thick red border, and the selected link (if any) will be red. Any highlighted nodes (see Select | Toggle Highlighting of the Selected Node or Link) will have a thick blue border, while any pinned nodes see Select | Toggle Pinning of the Selected Node) will have small black triangles drawn in their corners.

Moving the mouse cursor over the corner of a node will display an icon that represents a menu bar command that you can invoke by clicking while the icon is present. This can be disabled, and you can assign a different command to any corner. See Visual Graph Options | Node Corner Clicks | Enable Node Corner Clicks.

Tooltips will appear when holding the mouse cursor over a node or link, and status bar messages will appear at the bottom of the application. For a node, the tooltip will be the rdfs:comment property of the node's resource, if any, while the status bar will display the full URI of the resource. For a link, the tooltip will be a short version of the predicate URI, with the complete URI appearing in the status bar; if a link represents multiple predicates, then a summary of those predicates is displayed. A number in parentheses after a predicate name indicates multiple triples in the database for that predicate and the nodes of the link.

Displaying Images for Nodes

If the IRI or literal of a node names an image file on the local machine (such as a png or jpg file) or an image page on the web, then its node in the graph view will display the image rather than a text label. Gruff often refers to these images as "pixmaps", which is short for "pixel maps".

Downloading a pixmap from the web will be skipped if it takes longer than Global Options | Timeouts | Image-Fetching Timeout.

A file reference can be either an absolute path or a relative path that will be merged with Global Options | Miscellaneous | Document Base Folder to find the actual file to use. For example, if the value of that option is c:/documents/ and a node in the graph view is for the literal pretty-picture.png (or for the IRI file:///pretty-picture.png), then Gruff will look for the file c:/documents/pretty-picture.png. If it finds that file and successfully loads a pixmap from it, then the graph view will display the pixmap for the node rather than the usual text label.

When an IRI references a file, it may either contain the file:/// prefix or not.

You can also specify one or more predicates that provide pixmaps to display for other nodes whose own values are not pixmap file names. By adding triples for that predicate to your store, you can display pixmaps in the graph view for any nodes that you like. See Global Options | Node Label Predicates | Custom Predicates for Node Pixmaps.

The size of a pixmap node will initially be limited to Visual Graph Options | Node Labels | Maximum Initial Node Pixmap Size.

You can resize a pixmap node by left-clicking down in its lower right corner and dragging (as opposed to moving the node when clicking on it elsewhere). But re-opening the store will revert all nodes to their standard sizes.

The Time Bar in the Graph View

An optional pane in the graph view that's not shown initially is the time bar, which is useful for exploring nodes that have date-time properties. The full reference is at View | Optional Graph View Panes | Show Time Bar, and here is a mini-tutorial for trying it out.

This example uses triples from crunchbase.com that contain a history of corporate acquistions and funding events over several years. The time bar allows you to examine those events chronologically, and also to display only the nodes that have events within a specified date range.

For further help on the rather cryptic buttons and date fields, see the hints in the status bar at the bottom as you move the mouse cursor over them, and see View | Optional Graph View Panes | Show Time Bar.

The Graph View Node Pop-Up Menu

This menu appears when you right-click a node in the graph view, or press the M key after selecting the desired node (such as by clicking on it). The commands are copies of commands on the menu bar that apply to the selected node. Right-clicking a node will first select that node and then apply a command to it (if you select a command).

Graph View Node | Display the Nodes and Link of This Triple

This command will be present if the node is a triple ID typed literal node. A triple ID node represents a triple and is typically used for reifying that triple. The command will also be present if the node is used as the graph part of a single triple in the store, for a similar type of reification that uses the graph part instead of the triple-id part of each triple.

This command removes the triple ID node (or graph node) from the display and replaces it with the nodes and link of the triple that the triple ID node (or graph node) represents. See Reification Support in Gruff.

Graph View Node | Display a Linked Node from Menus

Lets you select a node from a series of menus that offer all of the nodes that are linked with the selected node in the store, and then displays that node along with a link line for the predicate that connects them.

This command is a copy of the menu bar command Link | Display a Linked Node from Menus. See that command for more information.

Graph View Node | Display Linked Nodes from an Outline

Lets you select a set of nodes from an outline widget that offers all of the nodes that are linked with the selected node in the store, and then displays those nodes along with link lines for the predicates that link them.

This command is a copy of the menu bar command Link | Display Linked Nodes from an Outline. See that command for more information.

Graph View Node | Display Linked Nodes for the Current Predicates

Displays any nodes that are linked with the selected node by the current predicates that were selected with Global Options | Select Current Predicates.

This command is a copy of the menu bar command Link | Display Linked Nodes for the Current Predicates. See that command for more information.

Graph View Node | Display Only Linked Nodes

Displays any nodes that are linked with the selected node by the current predicates, and removes all other nodes from the display.

This command is a copy of the menu bar command Link | Display Only Linked Nodes for the Current Predicates. See that command for more information.

Graph View Node | Display Paths Between Two Nodes

Displays any nodes and links that lie on paths between two specified nodes that are already on the display. The only paths that will be found are ones whose links use only the current predicates (see Global Options | Select Current Predicates).

This command is a copy of the menu bar command Link | Display Paths Between Two Nodes. See that command for more information.

Graph View Node | Display Only Paths Between Two Nodes

Displays any nodes and links that lie on paths between two specified nodes that are already on the display, removing all other nodes from the display.

This command is a copy of the menu bar command Link | Display Only Paths Between Two Nodes. See that command for more information.

Graph View Node | Create a Triple by Linking with Another Node

Creates a new triple if you drag the rubber band line that appears and click on a second node or on a link line. Connecting to another node will create a "regular" triple, whereas connecting to a link line will create a triple that reifies the triple of that link line. See Reification Support in Gruff.

This command will not appear on the menu if the store was opened in read-only mode.

This command is a copy of the menu bar command Edit | Create a Triple by Linking Nodes. See that command for more information.

Graph View Node | Create a Triple Using Most Recent Predicate

This is the same as Graph View Node | Create a Triple by Linking Nodes, except that it will automatically use the most recently used predicate rather than asking you to select a predicate in two pop-up menus.

This command is a copy of the menu bar command Edit | Create a Triple Using Most Recent Predicate. See that command for more information.

Graph View Node | Delete a Triple from Store

Deletes (from the triple-store) a triple that is represented by one of the link lines that are connected to the selected node. A pop-up menu will first ask which triple to delete, unless there is only a single connected link line that represents a single triple. If the link line of the selected triple no longer represents any triples, then the link line will be removed from the display.

This command will not appear on the menu if the store was opened in read-only mode.

This command is basically a copy of the menu bar command Edit | Delete Triple of Selected Link or Node, except that it will be applied to the node that you clicked on even if there is also a selected link. See that command for more information.

Graph View Node | Edit Node by Type

Lets you add property values in the table view for properies of the selected node that other nodes of the same type have.

This command will not appear on the menu if the store was opened in read-only mode.

This command is a copy of the menu bar command Edit | Edit Selected Node by Type. See that command for more information.

Graph View Node | Select Preferred Type for Node Colors

If the selected node has multiple types, then this command lets you select one to prefer for coloring this node and other nodes that also have the selected type. This is a shortcut for adding a type to the list of all preferred types for node color that can be edited with Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color. You can use that command later to reposition the select type within the list, or to remove it.

This command itself does not exist on the menu bar.

Graph View Node | Copy Node URI to Clipboard

Copies the URI of the selected node to the clipboard.

This command is a copy of the menu bar command View | Copy. See that command for more information.

Graph View Node | Invoke Web Browser on Node Value

Invokes your third-party web browser or other program on the IRI or literal string of the selected node, if any. See View | Web Interaction | Invoke Web Browser on Node Value for more information.

Graph View Node | Highlight the Node

Toggles whether the node is drawn in a different way to highlight it. (If the node is currently highlighted, then this command will appear as Unhighlight the Node in the menu.)

This command is a copy of the menu bar command Select | Toggle Highlighting of the Selected Node or Link. See that command for more information.

Graph View Node | Pin the Node

Toggles whether the node is pinned so that it doesn't move during a layout. (If the node is currently pinned, then this command will appear as Unpin the Node in the menu.)

This command is a copy of the menu bar command Select | Toggle Pinning of the Selected Node. See that command for more information.

The Graph View Link Pop-Up Menu

This menu appears when you right-click a link line in the graph view, or press the M key after selecting the desired link (such as by clicking on it) when there is not also a selected node. The commands are copies of commands on the menu bar that apply to the selected link. Right-clicking a link will first select that link and then apply a command to it (if you select a command).

Graph View Link | Remove Link from Display

Removes the link line from the display.

This command is a copy of the menu bar command Remove | Remove Selected Link. See that command for more information.

Graph View Link | Delete Triple from Store

Deletes the triple that the link line represents from the store, and removes the link line from the display. If the link line represents multiple triples, a pop-up menu will first ask which triple to delete.

This command will not appear on the menu if the store was opened in read-only mode.

This command is basically a copy of the menu bar command Edit | Delete Triple of Selected Link or Node. See that command for more information.

Graph View Link | Reverse Triple Direction in Store

Deletes the triple that the link line represents from the store, and creates a similar new triple whose subject is the object of the old triple and whose object is the subject of the old triple. The arrowhead of the link line will move to the other end of the line to show this change.

This command will not appear on the menu if the store was opened in read-only mode.

This command is a copy of the menu bar command Edit | Reverse Triple of Selected Link. See that command for more information.

Graph View Link | Drag to Replace Triple

Lets you drag the link line at one end to a different node. If you release the mouse button over a different node, then it deletes the triple of the node that you disconnected the link from, and creates a replacement triple for the node that you connected it to.

A shortcut for this menu command is to simply left-click down on the link line and begin dragging.

The link line will disconnect from the node that's closest to the original click point. The new triple will use the same predicate and other node as the deleted triple, replacing only the disconnected node with the node that you connect the line to.

If the link line that you drag represents multiple triples, then you will be asked at the end of the drag which triple you want to replace. Only one of the triples may be replaced on a particular drag.

You can alternately release the mouse button over a link line rather than over a node, to create a reifying triple. This would usually not be appropriate if the link had been connected to a node, though, because a particular predicate is usually suitable either for regular triples or for reifying triples, but this operation always uses the same predicate for the replacement triple. See Reification Support in Gruff.

This command does not appear on the menu bar.

Graph View Link | Create a Reifying Triple

Lets you drag a line from the link line to a node, to create a triple that reifies the triple of the link line. See Reification Support in Gruff.

The other node that you connect the link line to will be the object of the reifying triple. This is backwards from standard reification, and so it may be better to instead right-click a node and select its command for creating a new triple, and drag to the link line to reify its triple. Creating a new triple in the graph view always uses the first thing that you clicked on as the subject of the new triple.

Graph View Link | Display a Reifying Triple

This command will be present only if the triple of the link line has any reifying triples in the store that are not already displayed. If so, then this command will let you select one of the reifying triples to display.

This works for either triple-id reification or graph-part reification, but not for RDF reification. For graph-part reification, Global Options | Miscellaneous | Display Graph-Part Reification must also be enabled. See Reification Support in Gruff.

Graph View Link | Copy Predicate URI to Clipboard

Copies the URI of the predicate of the triple that the link line represents to the clipboard. If the link line represents multiple triples, a pop-up menu will first ask which triple to copy.

This command is a copy of the menu bar command View | Copy. See that command for more information.

Graph View Link | Copy Triple ID to Clipboard

Copies the triple ID of the triple that the link line represents to the clipboard, and pushes the triple ID node onto an internal stack of all triple ID nodes that have been copied in the current Gruff session. You could later use Table View Value Column Editing | Select a Different Node (selecting the Triple ID Node (for reification) option) to create a triple that reifies the triple of the triple ID node that you had copied earlier. See Reification Support in Gruff.

Graph View Link | Highlight the Link

Toggles whether the link is drawn in a different way to highlight it. (If the link is currently highlighted, then this command will appear as Unhighlight the Link in the menu.)

This command is a copy of the menu bar command Select | Toggle Highlighting of the Selected Node or Link. See that command for more information.

The Graph View Background Pop-Up Menu

This menu appears when you right-click the background in the graph view (that is, anywhere in the main pane other than on a node or a link line), or press the M key when no node or link is selected. The commands are copies of commands on the menu bar.

Graph View Background | Redo Layout from Scratch

Rearranges the nodes to make a more readable layout, beginning with all nodes either at the center position or at random positions to remove any bias that the current node positions might otherwise cause in the layout algorithm.

This command is a copy of the menu bar command Layout | Redo Layout from Scratch. See that command for more information.

Graph View Background | Update Layout Incrementally

Rearranges the nodes as needed to make a more readable layout, beginning from the current node positions.

This command is a copy of the menu bar command Layout | Update Layout Incrementally. See that command for more information.

Graph View Background | Make Canvas Larger

Makes the scrollable canvas one notch larger to better fit all of the nodes that are currently in the visual graph when a layout is done.

This command is a copy of the menu bar command Layout | Make Canvas Larger. See that command for more information.

Graph View Background | Make Canvas Smaller

Makes the scrollable canvas one notch smaller to squeeze the nodes that are in the visual graph into a smaller area when possible when a layout is done.

This command is a copy of the menu bar command Layout | Make Canvas Smaller. See that command for more information.

Graph View Background | Minimize Canvas Size

Makes the scrollable canvas be the same size as the window pane, to force layouts to squeeze everything into the visible area.

This command is a copy of the menu bar command Layout | Minimize Canvas Size. See that command for more information.

Graph View Background | Go Back

Returns to an earlier version of the visual graph.

This command is a copy of the menu bar command View | Go Back. See that command for more information.

Graph View Background | Go Forward

Returns to a later version of the visual graph after you've returned to an earlier version.

This command is a copy of the menu bar command View | Go Forward. See that command for more information.

Graph View Background | Search the Current View

Lets you search for any currently-displayed node by typing a substring of the label that's printed on the node.

This command is a copy of the menu bar command Text Search | Search the Current View. See that command for more information.

Graph View Background | Remove All Nodes

Removes all nodes and links from the display, to allow building a new visual graph from scratch. If done accidentally, use View | Go Back to see the nodes again.

This command is a copy of the menu bar command Remove | Remove All Nodes. See that command for more information.

Graph View Background | Eraser Mode

Allows quickly removing an arbitrary subset of the displayed nodes and links by moving the mouse cursor over them. Exit by pressing Escape or Q or clicking the mouse.

This command is a copy of the menu bar command Remove | Eraser Mode. See that command for more information.

Graph View Background | Remove All Node and Link Highlighting

Unhighlights all currently highlighted nodes, if any.

This command is a copy of the menu bar command Select | Remove All Node and Link Highlighting. See that command for more information.

Graph View Background | Remove All Node Pinning

Unpins any nodes that were pinned to prevent them from moving during a layout.

This command is a copy of the menu bar command Select | Remove All Node Pinning. See that command for more information.

The Graph View Legend Node Pop-Up Menu

This menu appears when you right-click a node in the legend that's on the lefthand side of the graph view, or when you press the M key while the legend has the keyboard focus if a node is currently focused (where it has a thin red rectangle around it). You can use the TAB key to switch the keyboard focus between the main part of the graph view and the legend. You can use the up and down arrow keys to focus on different items in the legend, or the Escape key to focus on the legend background.

Graph View Legend Node | Set Background Color for Type

This is a shortcut for Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type. Except that rather than setting the color to use for one of the types of the selected node, it directly sets the color for the type that's represented by the selected legend node.

Graph View Legend Node | Remove Background Color for Type

This is a shortcut for Visual Graph Options | Node and Link Color for Types | Remove Color Mapping for Selected Node's Type. It directly removes the mapping from the type that is represented by the selected legend node to the color that was used for it.

Graph View Legend Node | Show Table for Type

Invokes the table view on the type that the selected legend node represents.

Graph View Legend Node | Avoid This Type for Node Colors

This is a shortcut for Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color. It directly adds the type that's represented by the selected legend node to the list of types that will be avoided when selecting the type of each node to use for its background color.

Graph View Legend Node | Prefer This Type for Node Colors

This is a shortcut for Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color. It directly adds the type that's represented by the selected legend node to the list of types that will be preferred when selecting the type of each node to use for its background color.

Graph View Legend Node | Remove Matching Nodes

Removes from the display any nodes that are colored for the type that's represented by the selected legend node.

Graph View Legend Node | Highlight Matching Nodes

Highlights any nodes that are colored for the type that's represented by the selected legend node. See Select | Toggle Highlighting of the Selected Node or Link.

Graph View Legend Node | Unhighlight Matching Nodes

Unhighlights any nodes that are colored for the type that's represented by the selected legend node. See Select | Toggle Highlighting of the Selected Node or Link.

Graph View Legend Node | Copy URI to Clipboard

Copies to the clipboard the URI of the type that's represented by the selected legend node.

The Graph View Legend Link Pop-Up Menu

This menu appears when you right-click a link line in the legend that's on the lefthand side of the graph view, or when you press the M key while the legend has the keyboard focus if a link is currently focused (where it has a thin red rectangle around it). You can use the TAB key to switch the keyboard focus between the main part of the graph view and the legend. You can use the up and down arrow keys to focus on different items in the legend, or the Escape key to focus on the legend background.

Graph View Legend Link | Set Line Color

Lets you specify the color to use for link lines that represent the same predicate as the selected legend link line. This is a shortcut for Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate.

Graph View Legend Link | Set Line Width

Lets you specify the width to use for link lines that represent the same predicate as the selected legend link line. This is a shortcut for Visual Graph Options | Node and Link Color for Types | Specify Line Width for Selected Link's Predicate.

Graph View Legend Link | Set Line Dashing

Lets you specify the dashing style to use for link lines that represent the same predicate as the selected legend link line. This is a shortcut for Visual Graph Options | Node and Link Color for Types | Specify Dashing for Selected Link's Predicate.

Graph View Legend Link | Specify Layout Direction

Lets you specify a direction for constraing how links for the predicate of the selected legend link line are oriented in a layout. This is a shortcut for Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate.

Graph View Legend Link | Change Layout Direction

Lets you change the layout direction constraint for the predicate of a legend link line when it's already got one.

Graph View Legend Link | Clear Layout Direction

Removes the layout direction constraint for the predicate of a legend link line when it has one.

Graph View Legend Link | Use as Custom Predicate

Specifies the selected predicate as one that will provide labels, comments, pixmaps, or web pages for nodes. This is a quick alternative for Global Options | Node Label Predicates | Custom Predicates for Node Labels and the three similar options, which require you to enter the URIs of the desired predicates. This shortcut works just like Table View Property Column | Use as Custom Predicate.

Graph View Legend Link | Remove Matching Link Lines

Removes from the display any link lines that are colored for the predicate that's represented by the selected legend link line.

Graph View Legend Link | Copy URI to Clipboard

Copies to the clipboard the URI of the predicate that's represented by the selected legend link line.

The Table View

The table view displays a table of all of the properties of a single node, which is known as the displayed node. You can browse from that node to linked nodes in the usual hyperlink way by clicking on the linked nodes that are shown in the righthand column. You can also edit the displayed triples with commands that are on a right-click pop-up menu.

Each row of the table represents a single triple that's in the store. The lefthand column of the table is called the property column, and shows each predicate (or property) of the displayed node. The righthand column is called the value column, and shows each node (or property value) that is linked with the displayed node by each predicate. A thick horizontal line separates the triples where the displayed node is the subject of the triples (in the upper section) from the triples where the displayed node is the object of the triples (in the lower section).

If some predicates of the displayed node have more triples than Table Options | Maximum Triples Per Predicate in Table, then not all of the triples will be shown initially, and the Show All Triples button at the upper right will be available for showing the rest of the triples. Text such as show the other 37 will also appear below each predicate whose triples were limited, and you can click that text to show the additional triples for particular predicates.

The displayed node's triples will still not all be shown if the total number of triples for the node exceeds Global Options | General Triple-Fetching Limit. In that case, the text fetch more triples will appear below each predicate that might have more triples on the server. Clicking that text will fetch more triples from the server for that predicate of the displayed node (if any), and then text will indicate how many additional triples were downloaded. If that's not more triples than you would like to add to the table, then clicking that text will show the additional triples.

Using the View | Table View command in another view will not only switch over to the table view, but also display the properties of the node that was selected in the other view (if any). Alternately, commands on The Display Menu can be used to directly select a node to display in the table.

Text Search | Search the Current View works in the table view to locate cells that contain a word or phrase that you type. When there are multiple matches, the tab key will move among the various matches.

Other commands that are applicable only to the table view can be found only on the table view's right-click pop-up menu. This menu can be shown by right-clicking in a cell to which you would like to apply a command. That will select the clicked table cell, and then apply a command to the selected cell (if you do select a command). A simple right-click shows a menu of triple-editing commands, while a shift-right-click shows a menu of navigation commands.

To invoke the pop-up menu by using the keyboard rather than the mouse, press the J and K keys to move the keyboard focus to the next or previous row, respectively, and the L key to leap to the other column. Then press M to show the editing pop-up menu for the selected table cell, or Shift-M to show the navigation pop-up menu. Reminders about these keystrokes are always printed in the header cell of the value column.

Once you've shown the pop-up menu, you can press a letter key that's mentioned at the left of a desired command to run that command. To the right of the commands are the mouse and keyboard shortcuts that can be used to run the commands without showing the pop-up menu at all. You will probably want to generally use the keyboard shortcuts at least for the commands on the navigation menu, because using the menus themselves would be unwieldy; the navigation menu exists mostly to provide reminders of the keyboard shortcuts.

Commands on the editing pop-up menu will modify the store by creating and deleting triples. To avoid inadvertently modifying a store, select read-only mode when opening the store in Gruff.

There are several ways to return to the node that was previously displayed in the table. The official way is with the menu bar's command View | Go Back, and with the copy of that command on the pop-up menu, or to press the Z key (the command's keyboard shortcut). But you can alternately use the back button on your mouse if there is one, or left-click the header cell of the value column, or press the left-arrow button widget at the upper right of the table view. To return to a later displayed node, either use View | Go Forward, or press the Y key, or use the forward button on your mouse, or left-click the header cell of the property column, or press the right-arrow button widget at the upper right.

The navigation menu shows that D is an alternative shortcut for going back (like Z), and F is an alternative for visiting the selected node (like the spacebar). Along with the J, K, and L shortcuts described above, this is a scheme that's used in the various Gruff views for using the "inner home keys" to navigate quickly.

Left-clicking a property in the lefthand column (or navigating there and pressing the spacebar) will collapse that property to a single row, or re-expand it to show all of its values.

Several options that determine how information is displayed in the table can be found on the Table Options menu, which is on the menu bar whenever the table view or the query view is selected. An option that you may want to toggle frequently is Table Options | Show Full URIs in Tables. That option switches between short pretty labels for readability, and the full URIs for complete information. That option's keyboard shortcut is the 8 key.

If the displayed node is a triple-id node, then the usual table rows will represent the triples that reify the triple of that triple-id node. There will also be three special rows at the top of the table for the subject, predicate, and object of the triple for the display triple-id node. See Reification Support in Gruff.

For each row in the table, if the row's triple is in a graph other than the default graph, then the name of that graph is displayed at the righthand edge of the table (unless Table Options | Display Graph Names is not enabled). Clicking the graph name will display the table for that graph node, which (as usual in the table view) will display all triples where that node is either the subject or the object. Typically there will not be any such triples for a graph node, but the page is displayed anyway in case you would like to create such triples there. If your store uses graph-part reification, where a reified triple uses a unique graph part in order to reify that triple by using the graph part as the subject or object of reifying triples, then the table will include three special rows at the top for the subject, predicate, and object of the single triple that is in that graph.

If the triple of a row was borrowed from another store or endpoint, either by using the option to retain triples when opening a store or by using a SERVICE clause in a SPARQL query, then the name of the store or endpoint that the triple is from will be mentioned at the right side of the row. The name will be enclosed in square brackets to distinguish it from the name of a non-default graph that's displayed in the same area. See [Building an Ad Hoc Federation from Multiple Stores and Endpoints] (#BuildinganAdHocFederationfromMultipleStoresandEndpoints).

When browsing a reasoning store, any triples that were created by the reasoning will say [inferred] in the value column. Those triples exist only in the temporary reasoning store that encapsulates the base store. They cannot be deleted because there is no permanent store to delete them from.

The Revisit button may be used to select an object that's in the table view's history of recently-viewed objects. The menu that appears will list the objects in alphabetical order. The buttons showing left and right arrows, on the other hand, will invoke the View | Go Back and View | Go Forward commands to revisit history items in the order in which they were browsed.

Special Colors in the Table View

There are a few special colors in the table view, in addition to the two arbitrary colors that are used to shade alternate rows. A cyan cell (by default) in the righthand column indicates a node that is currently in the graph view (though the link between the nodes of this row's triple may not be). A yellow cell (by default) in the left column indicates that it is one of the current predicates that are used by commands in the upper section of the Link menu.

A node that has been explicitly excluded with Remove | Exclude Selected Node will have a red background in the table. Adding nodes to the graph view from the value column will still do so and unmark the nodes as excluded, but adding the nodes from the property column will not do so (see the table column pop-up menus below).

Fine points: The cyan color that indicates that the node is currently in the visual graph is actually the Visual Graph Options | Node Color for Unseen Links | Node Color for No Unseen Links color doing double duty. The yellow color for current predicates is actually the Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Current Links color.

The Table View Value Column Editing Pop-Up Menu

This menu appears when you right-click a cell in the righthand column of the table view, or press the M key after moving the keyboard focus to the desired cell. It contains commands to apply to the node that's in the table cell that was clicked.

(If the store was opened in read-only mode, then the gestures for this menu will actually show the navigation menu instead. See The Table View Value Column Navigation Pop-Up Menu.)

Table View Value Column Editing | Enter a Different Node

Lets you replace the URI or literal that's in the selected cell by typing or pasting. This conceptually "edits the triple" by replacing one of its parts, though it will actually delete the triple that the table row represents and create a new triple with a different subject or object node.

(The object of the triple is replaced if the cell is in the upper section of the table for triples where the displayed node is the subject, and the subject is replaced if the cell is in the lower section for triples where the displayed node is the object.)

A small text-editing pane will appear in the selected table cell to let you edit the old string in place. Typically just a portion of the old value will be initially selected, to allow you to quickly replace the typically-modified part of the value by simply beginning to type without first clicking in the string or otherwise moving the mouse cursor. This allows quickly replacing the fragment but not the namespace of a URL, or just the value portion of a typed literal.

While you're in text-editing mode in a value cell, the keyboard shortcut reminders in the header cell of the value column change to reflect the special keyboard shortcuts that are available during text-editing. These include the Enter key to finish an edit, Escape to cancel, Shift-Enter to add a newline to a multiline literal, and Control-A to select all text. The TAB key will finish the current edit and begin text-editing the value in the row just below; Shift-TAB does the same for the row just above. (A subtle feature of this tabbing is that any menus of alternate namespaces will be bypassed, instead inserting the most recently-used namespace to speed up text entry.) Control-Z and Control-Y will undo and redo text edits rather than undoing and redoing triple addition and deletion as they do otherwise. Control-X, Control-C, and Control-V can be used to cut, copy and paste text. You can also use basic Emacs keystrokes for moving around and deleting text, though for cut/copy/paste and undo/redo you must use those Windows-style keystrokes.

If you are filling in the empty value cell of a new table row, and Edit | Show Menus of Recent Namespaces is enabled, then a pop-up menu may first appear to let you select a recently-used namespace to facilitate entering an IRI. This is not done if other nodes that have the same property all use literals for the property values. If you select a namespace, it will be pasted into the table cell with the text cursor placed after it for adding a fragment to the namespace. To enter a literal or an IRI with some other namespace, select the choice at the top of the menu for Other Namespace (or None).

If the URI that you type or paste is the URI of a node that exists in the store, then the new triple will use that existing node. Otherwise it will use a newly-created node.

If you have are currently browsing a single graph (see View | Browse a Single Graph), then any triples that you create in Gruff will be created in that graph, and otherwise they will be created in the default graph.

Gruff attempts to parse most any syntax that you enter, and to determine whether to create a resource or a literal. You can always enter a URI or literal in n-triples format, with angle brackets around a URI or double-quotes around a literal (with or without a preceeding exclamation point for AllegroGraph's special reader). Or enter a URI using a namespace abbreviation by using the namespace-abbreviation:fragment syntax. You can also exclude the angle brackets around a URI or the double-quotes around a simple literal except in the special case where a simple literal contains a colon but no spaces or newlines.

Note that if other triples use the node that is being replaced in the triple of the selected table row, those triples will continue to use the old value node, whereas the edited triple will use a different node, and so the triple will no longer "share" a node with the other triples. And so this command actually replaces the value rather than "editing" it. To instead "edit the URI", replacing all of its triples to use an updated URI, use Table View Value Column Editing | Rename the Node.

If this table row already represented a triple (that is, its value cell is not blank), then the undo command to reverse this action will begin with the word Restore, and it will both recreate the deleted triple and delete the replacement triple. See Table View Value Column Editing | Undo. If the value cell had been blank, then the Undo command will begin with the word Delete, and will only delete the new triple.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Select a Different Node

Lets you select a different existing node to replace the current one. This conceptually "edits the triple" by replacing one of its parts, though it will actually delete the triple that the table row represents, and create a new triple with a different subject or object.

A menu will first appear where you select one of the ways in which to select an existing node. (The large number of nodes that can be in a store can make finding one problematic, and so Gruff offers various alternative ways to select one.) Most of these alternatives correspond to the commands on the menu bar's Display menu. If you select one, then further menus or other prompts will appear for selecting an existing node in the way that you choose, as described under the commands on The Display Menu.

There may be one or more options at the top of the menu that do NOT correspond to commands on the pull-down Display menu. One is an option to select a subject or object of the predicate of the table row that's being edited. For example, if the table row is for a Director property, then one option on the menu will be Object of Director, and selecting that option will present a series of menus of other nodes that are objects of the director predicate, allowing you to select a different known director.

Another unique option will appear only if the row's property predicate defines an rdfs:range or rdfs:domain type (depending on which section of the table the row is in). In this case an option will appear for selecting any instance of that domain or range type. For example, if the row's predicate is Has Color (for a wine), and that property declares its range to be the "Wine Color" type, then an Instance of Wine Color option will appear on the menu.

A third unique option will appear if you have copied any triple-id nodes in the current Gruff session, either by using Table View Value Column Navigation | Copy Triple ID to Clipboard, or by copying a triple-id node directly. In this case a Triple ID Node (for reification) option will appear at the top of the menu. Selecting it will present a further menu of the triple ID nodes that you have copied, and selecting one of those will perform reification by making a new triple that has the ID of the selected triple as its object. See Reification Support in Gruff.

If this table row already represented a triple (that is, its value cell is not blank), then the undo command to reverse this action will begin with the word Restore, and it will both recreate the deleted triple and delete the replacement triple. See Table View Value Column Editing | Undo. If the value cell had been blank, then the Undo command will begin with the word Delete, and will only delete the new triple.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Enter a Typed Literal

Lets you enter a new typed literal to replace the current value. A pop-up menu will first ask which XML Schema datatype to use for the new value. Only a subset of the XML datatypes are offered at this time. If you select one, then type-in will be initiated in the table cell for the value to be replaced. A sample value such as "1.23e0"^^<http://www.w3.org/2001/XMLSchema#double> for a double float will be shown in the table cell, with the value part such as 1.23e0 initially selected for replacement.

If you change the value and press Enter, then the triple that the row had represented will be deleted from the triple-store, and a new triple will be created with the new typed literal in place of the old node.

Table View Value Column Editing | Rename the Node

Allows you to edit the URI in the selected cell by typing or pasting. This command conceptually modifies the selected node in all of the triples that use it, though it actually deletes all of the triples that use the selected node, and creates new triples to replace them, where the new triples all use a different node whose URI or literal string is the new string that you enter.

This command is intended for fixing errors in URI strings. For example, if you have created more than a few triples that all use a particular new node, and only later notice a typo in the node's URI, then this command lets you replace all of those triples with ones that use a corrected URI.

An exception is that if the node that's being is a blank node, then this command will actually just replace the rdfs:label of the blank node with a literal for the string that you enter. This makes it easy to edit the labels of blank nodes.

The undo action for this command will appear on the undo menu as a string beginning with Restore URI. See Table View Value Column Editing | Undo.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard shortcut will do nothing.

Table View Value Column Editing | Reverse Triple Direction

Deletes the triple that's represented by the table row that has the keyboard focus, and replaces it with a triple that has the same parts except with the subject and object switched. The table will be redisplayed, showing that the triple has "moved" to the other section of the table, where the two sections are for triples where the displayed node is either the subject or the object of the triples.

This command is useful when you inadvertently create a triple where the predicate goes in the wrong direction.

This command is also useful when creating a new triple when the table does not yet have the section that the new triple belongs in, because the command Table View Value Column Editing | Create Row for a New Triple will always create the new row in the section that the selected row is in. To create the desired triple in that case, you can create a triple in the section that the table has already, even though the predicate will be in the wrong direction, and then use this command to correct the direction.

If this table row already represented a triple (that is, its value cell is not blank), then the undo command to reverse this action will begin with the word Restore, and it will both recreate the deleted triple and delete the replacement triple. See Table View Value Column Editing | Undo. If the value cell had been blank, then this command will not do anything (except show a warning dialog).

Table View Value Column Editing | Create Row for a New Triple

Adds a row to the table for a new triple for the node whose properties are currently displayed in the table, and then prompts for you for the information that's needed to specify a new triple.

A pop-up menu will first ask whether the new node that you will specify will be the object or the subject of the new triple. Then a series of pop-up menus will guide you through selecting a predicate for the new triple. If you cancel any of those pop-up menus, then the new table row will be removed. Otherwise another pop-up menu will ask which way you would like to create the other node for a new triple. The choices correspond to the commands Table View Value Column Editing | Enter a Different Node, Table View Value Column Editing | Select a Different Node, and Table View Value Column Editing | Enter a Typed Literal. If you specify the node, then a triple is added to the store (note the status bar message). If you do not specify the node, then the new table row will remain in place, and you can still use one of those commands later to complete the creation of a triple.

The prompts for selecting a predicate begin with a menu for selecting one of several alternate ways of selecting a predicate. (The large number of predicates that can be in a store can make finding one problematic, and so Gruff provides alternate ways to select one.) For the meanings of the different groups of predicates from which you can select, see Graphical Query Link | Specify Predicate.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Create Row for the Same Predicate

This command is just like Table View Value Column Editing | Create Row for a New Triple, except that you are not prompted for the triple direction or the predicate for the new triple, and the values for the currently-focused table row are used instead.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Delete the Triple

Deletes the triple that is represented by the currently selected table row.

By default, a confirmation dialog will appear to ensure that you really want to delete the triple. This is a safety measure especially in case you inadvertently type the keyboard shortcut for this command. (Whereas other store-editing commands would require further action before you could inadvertently modify the store.) To delete triples more rapidly, you can disable the confirmation dialog by toggling off Edit | Confirm Triple Deletion.

The undo command for this action will begin with the word Recreate.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Undo

This command is simply a copy of the menu bar command Edit | Undo. It presents a menu of commands that will undo the most recent changes to the triple-store.

This command will not appear on the table view's right-click pop-up menu if you have not yet used a store-modifying command that provides an undo action. It also will not appear if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Redo

Shows a menu of commands to redo a recent edit that was undone by using Table View Value Column Editing | Undo.

This command will appear on the table view's right-click menu only if you have done one or more undo commands. It will also not appear on the menu if the store was opened in read-only mode, and its keyboard shortcut will do nothing.

This command is simply a copy of the menu bar command Edit | Redo.

Table View Value Column Editing | Edit Displayed Node by Type

Adds rows to the table for additional properties that you may want to fill in to create triples for the currently displayed node. The added properties are ones for which other nodes that have the same rdf:type(s) as the displayed node have values, but for which the displayed node does not.

This command is simply a copy of the menu bar command Edit | Edit Selected Node by Type, though in the table view the command applies to the already-displayed node rather than to the node in the selected table row.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Table View Value Column Editing | Rename the Displayed Node

Lets you edit the URI of the currently displayed node by typing or pasting. This conceptually modifies the selected node in all of the triples that use it, though it actually deletes all of the triples that use the displayed node, and creates new triples to replace them, where the new triples all use a different node whose URI is the new string. This command is chiefly for fixing errors in URI strings while effectively retaining all of the triples that use the URI.

This is just like Table View Value Column Editing | Rename the Node, except that it is applied to the currently displayed node rather than to the node that's in the selected table cell.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard shortcut will do nothing.

Table View Value Column Editing | Show the Navigation Menu

Shows the pop-up menu of commands for navigating around the table view. This menu can be shown more directly with its own keyboard or mouse shortcut that appears at the right of this menu item, though this command is included in case you don't spot the reminders about those gestures in the table's header.

The Table View Value Column Navigation Pop-Up Menu

This menu appears when you shift-right-click a cell in the righthand column of the table view (or type shift-M). It contains mostly commands for navigating around the table view. You will probably want to normally use mouse or keyboard shortcuts for these commands, which are shown at the right of each command on the menu.

Table View Value Column Navigation | Visit Node in Table

Displays the selected node in the table, replacing the currently displayed node. This is the familiar hyperlink way to browse from one node to nodes that are linked with it.

Table View Value Column Navigation | Add Node to Visual Graph

Adds the selected node to the visual graph in the graph view, along with a link line for the triple that the table row represents. (If the displayed node is not already in the visual graph, it is added as well.) This command can be used multiple times while displaying a single node in the table, to add several things that are linked with it to the visual graph.

Table View Value Column Navigation | Visit Node and Add to Visual Graph

Displays the selected node in the table, AND adds the node to the visual graph along with a link line that connects the displayed node with the selected node. In other words, this command does what both of the previous two commands do.

This command is the typical one to use for browsing in the table view, and its mouse shortcut is a simple left click. As you browse through a tree of linked nodes in the table, the paths that you've browsed are formed with nodes and links over in the graph view. You can then switch to the graph view for a picture of the paths that you've browsed, and access any of the browsed nodes from there.

The mouse cursor will be an hourglass while the (unseen) graph view is busy laying out the nodes that are added to the visual graph in this way, but you can continue to use the table view while the layout is being done in the background.

Table View Value Column Navigation | Show Reifying Triples in Table

This command will be present only if there are triples in the store that reify the triple for the selected table row, using Triple-ID reification.

Using this command will then display the triple ID node for the triple of the table row. This will include rows for triples that reify the original triple, showing what subject nodes make statements about that triple. You could then display any of those subject nodes as usual by clicking on them.

A shortcut for this command is to left-click the reification icon that will be drawn on the left side of the vertical border between the property and value columns for any row that has reifying triples, though only when Table Options | Display Links to Reifying Triples is enabled. That icon also mentions the number of reifying triples that exist for that table row's triple.

When using graph-part reification rather than triple-id reification, you can see the reifying triples by clicking on the graph name that's displayed at the right edge of the row.

See Reification Support in Gruff.

Table View Value Column Navigation | Copy URI to Clipboard

Copies the URI string or literal string of the selected node to the clipboard. This command is simply a copy of the menu bar command View | Copy.

Table View Value Column Navigation | Copy Triple ID to Clipboard

Copies the ID of the triple of the selected table row to the clipboard, and pushes the triple ID node onto an internal stack of the triple IDs that you've copied in the current Gruff session. The triple ID's that you've copied can later be used for reification by replacing the object of some other triple with the one of the triple ID nodes that you've copied. You can do that by using the command Table View Value Column Editing | Select a Different Node on some other triple, then selecting the Triple ID Node (for reification) option that will be at the top of the menu of ways to select a replacement object node, and then selecting one of the triple ID nodes that you've copied. See Reification Support in Gruff.

This probably warrants an example: Say you first display Terry Jones in the table view. You could then show the table view's navigation menu by shift-right-clicking on the table row for the triple that says that Terry Jones directed the film Monty Python and the Holy Grail, and select the command Copy Triple ID to Clipboard. Some time later you could then display another node such as Michael Palin in the table view (perhaps by clicking on the Holy Grail film and then on Michael). You could then give Michael a row for a new predicate called Believes by using Table View Value Column Editing | Create Row for a New Triple (selecting the Typed URI or Literal option to make up a new URI for a Believes predicate). Then you would right-click in the new blank table cell for something that Michael believes, and select Select a Different Node, then select the Triple ID Node (for reification) option, and then select the triple that you had copied about Terry Jones being the director of Holy Grail. That will create a reifying triple that says that Michael Palin believes that Terry Jones directed Monty Python and the Holy Grail.

A more direct way to create a reifying triple is to use Graph View Node | Create a Triple by Linking with Another Node in the graph view.

Table View Value Column Navigation | Invoke Web Browser on Node Value

Invokes your third-party web browser or other program on the IRI or literal string of the currently selected node, if any. See View | Web Interaction | Invoke Web Browser on Node Value for more information.

Table View Value Column Navigation | Go Back

Displays the node that was previously displayed in the table. This command can be used any number of times to return to nodes that are further back in the linear history of displayed nodes.

Nodes from which you backed up before proceeding down other branches will not be in the linear Go Back stack. But they will still be available in the menu that's shown by the Revisit button widget at the upper right of the table view, if they are recent enough.

This command is simply a copy of the menu bar command View | Go Back.

Table View Value Column Navigation | Go Forward

Displays the next node from which you returned with the Go Back command, if any.

This command is simply a copy of the menu bar command View | Go Forward.

Table View Value Column Navigation | Refresh Table

Regenerates the current table in case it is out-of-date. Typically you will not need to use this command because Gruff usually updates the table automatically when needed. But there are cases where you might need it:

Table View Value Column Navigation | Scroll Down Most of a Page

Scrolls the table downward by most of the window height. This command exists to provide a keyboard shortcut for scrolling that uses the main part of the keyboard.

Table View Value Column Navigation | Scroll Up Most of a Page

Scrolls the table upward by most of the window height. This command exists to provide a keyboard shortcut for scrolling that uses the main part of the keyboard.

The Table View Property Column Pop-Up Menu

This menu appears when you right-click a cell in the lefthand column of the table view. It contains commands to apply to the predicate that's in the table cell that was clicked.

Table View Property Column | Collapse or Expand Property Values

Either collapses all of the rows for the property to a single row, or re-expands it to display a row for every value of the property. When collapsed to a single row, the value column will display the usual value if there is only a single value for the property, and otherwise will simply mention how many values there are for that property.

A shortcut for this command is to simply left-click the table cell for the property (predicate).

Alternately, all properties can be collapsed or expanded together by using Table Options | Show Multiple Property Values.

Table View Property Column | Add Triples of Predicate to Graph View

Adds nodes and links to the visual graph over in the graph view for all of the triples that are represented by the table rows in the section for the selected predicate.

Table View Property Column | Toggle as Current Predicate

Toggles whether the selected predicate is one of the current predicates, which are useful in the graph view when using the commands in the upper section of the Link menu for adding linked nodes to the visual graph. See Global Options | Select Current Predicates.

Table View Property Column | Use as Custom Predicate

Specifies the selected predicate as one that will provide labels, comments, pixmaps, or web pages for nodes. This is a quick alternative to the option command Global Options | Node Label Predicates | Custom Predicates for Node Labels and the three similar options, which require you to enter the URIs of the desired predicates.

First a dialog will ask which application of the predicate you would like, such as supplying labels to display on nodes or comments to display in tooltips. If there are already any custom predicates for that application, then another dialog will ask whether you want to replace those predicates or prepend the new one to them. (For node labels, multiple predicates can be used to concatenate multiple values into a single label.) Finally, if the selected predicate is already assigned to the specified application, then a dialog will ask if you want to remove it.

Table View Property Column | Copy URI to Clipboard

Copies the URI string of the selected predicate to the clipboard. This command is simply a copy of the menu bar command View | Copy.

Table View Property Column | Go Back

Displays the node that was previously displayed in the table. See Table View Value Column Navigation | Go Back.

Table View Property Column | Go Forward

Displays the next node from which you had returned with the Go Back command, if any.

This command is simply a copy of the menu bar command View | Go Forward.

Table View Property Column | Rename the Predicate

Allows you to edit the URI in the selected cell by typing or pasting. This command conceptually modifies the selected predicate in all of the triples that use it, though it actually deletes all of the triples that use the selected predicate, and creates new triples to replace them, where the new triples all use a different predicate whose URI is the new string.

This command is intended for fixing errors in URI strings. For example, if you have created more than a few triples that all use a particular new predicate, and only later notice a typo in the predicate's URI, then this command lets you replace all of those triples with ones that use a corrected URI.

The undo action for this command will appear on the undo menu as a string beginning with Restore URI. See Table View Value Column Editing | Undo.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard shortcut will do nothing.

Table View Property Column | Refresh Table

See Table View Value Column Navigation | Refresh Table.

The Outline View

The outline view displays parts of a graph as an indented outline. You can "open" an item in the outline to reveal other nodes that are linked with that item's node, showing them as indented "children" of the opened item. You can also create and delete triples by creating and deleting outline items that link their nodes to their parent outline items. You can also shift an outline item around so that it is indented under a different parent, which will create a triple for the new parent and delete a triple for the old parent.

The only nodes that will be revealed by opening outline items will be the ones that are linked by the current predicates, so you will need to first use Global Options | Select Current Predicates to set them up.

The outline view is most useful for browsing or building a hierarchy of nodes that are linked by a hierarchical predicate such as rdfs:subClassOf or skos:narrower. That's where the indented outline format is most intuitive.

Left-click the node value toward the right of an outline item to select it, in order to apply commands to it. Left-click the arrow at the left to open or close an item. Left-click the predicate value toward the left to hide the other triples for the same predicate under the same parent item, or click the note that appears to the right when some triples are hidden to show them (see Outline View Navigation | Display Sibling Triples for the Same Predicate).

Right-click a node in the outline for a pop-up menu of editing commands, or shift-right-click for a menu of navigation commands. This is similar to the table view. The menu bar commands that are present in the outline view can be used in addition to the pop-up menus. The commands on the Remove menu on the menu bar are useful for clearing items that have accumulated, for example (without modifying the triple-store).

To invoke the pop-up menus by using the keyboard rather than the mouse, first move to the outline item of interest by pressing the J and K keys to move the keyboard focus to the next or previous row, respectively, and the L key to leap to the parent item of the selected item. Then press M to show the editing pop-up menu for the selected node, or Shift-M to show the navigation pop-up menu.

Once you've shown a pop-up menu, you can press a letter key that's mentioned at the left of a desired command to run that command. To the right of the commands are the mouse and keyboard shortcuts that can be used to run the commands without showing the pop-up menu at all. You will probably want to generally use the keyboard shortcuts at least for the commands on the navigation menu, because using the menus themselves would be unwieldy; the navigation menu exists mostly to provide reminders of the keyboard shortcuts.

Commands on the editing pop-up menu will modify the store by creating and deleting triples. To avoid inadvertently modifying a store, select read-only mode when opening the triple-store in Gruff. The editing commands will then not be available.

The Outline View Editing Pop-Up Menu

This menu appears when you right-click in the outline view or press the M key.

Outline View Editing | Enter a Different Node

Lets you replace the node that's in the selected outline item by typing or pasting. This conceptually "edits the triple" by replacing one of its parts, though it will actually delete one triple and create another. The triple that is replaced is the one that links the node of the selected item with the node of its parent item. The same predicate will always be used for the new triple.

While editing the string, you can use Control-C to copy selected text, Control-X to cut it, and Control-V to paste whatever is on the clipboard. Control-Z will undo a text edit and Control-Y will redo it. Control-Shift-A will select all text. Basic Emacs editing keystrokes will work as well. When done editing, press Enter to make the change or Escape to cancel.

If you are filling in a new outline item that doesn't have a node yet, and Edit | Show Menus of Recent Namespaces is enabled, then a pop-up menu may first appear to let you select a recently-used namespace to facilitate entering an IRI. This is not done if other nodes that have the same property all use literals for the property values. If you select a namespace, it will be pasted into the outline item with the text cursor placed after it for adding a fragment to the namespace. To enter a literal or an IRI with some other namespace, select the choice at the top of the menu for Other Namespace (or None).

If the URI that you type or paste is the URI of a node that exists in the store, then the new triple will use that existing node. Otherwise it will use a newly-created node.

Gruff attempts to parse most any syntax that you enter, and to determine whether to create a resource or a literal. You can always enter a URI or literal in n-triples format, with angle brackets around a URI or double-quotes around a literal (with or without a preceeding exclamation point for AllegroGraph's special reader). Or enter a URI using a namespace abbreviation by using the namespace-abbreviation:fragment syntax. You can also exclude the angle brackets around a URI or the double-quotes around a simple literal except in the special case where a simple literal contains a colon but no spaces.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

For some additional points, see the similar table view command Table View Value Column Editing | Enter a Different Node.

Outline View Editing | Select a Different Node

Lets you select a different existing node to replace the one that's in the selected outline item. This conceptually "edits the triple" by replacing one of its parts, though it will actually delete one triple and create another one. The triple that is replaced is the one that links the node of the selected item with the node of its parent item. The same predicate will always be used for the new triple.

A menu will first appear where you select one of the ways in which to select an existing node. Most of these alternatives correspond to the commands on the menu bar's Display menu. If you select one, then further menus or other prompts will appear for selecting an existing node in the way that you choose, as described under the commands on The Display Menu.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

For additional information, see the similar table view command Table View Value Column Editing | Select a Different Node.

Outline View Editing | Enter a Typed Literal

Lets you enter a new typed literal to replace the current value. A pop-up menu will first ask which XML Schema datatype to use for the new value. Only a subset of the XML datatypes are offered at this time. If you select one, then type-in will be initiated in the outline item for the value to be replaced. A sample value such as "1.23e0"^^<http://www.w3.org/2001/XMLSchema#double> for a double float will be shown in the outline item, with the value part such as 1.23e0 initially selected for replacement.

If you change the value and press Enter, then the triple that links the node of the parent outline item with the node of the selected outline item will be deleted from the triple-store, and a new triple will be created with the new typed literal in place of the old node.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Rename the Node

Allows you to edit the URI or literal string for the node that's in the selected outline item, by typing or pasting. This command conceptually modifies the selected node in all of the triples that use it, though it actually deletes all of the triples that use the selected node, and creates new triples to replace them, where the new triples all use a different node whose URI or literal string is the new string.

This command is intended for fixing errors in URI strings. For example, if you have created more than a few triples that all use a particular new node, and only later notice a typo in the node's URI, then this command lets you replace all of those triples with ones that use a corrected URI.

An exception is that if the node that's being renamed is a blank node, then this command will actually just replace the rdfs:label of the blank node with a literal for the string that you enter. This makes it easy to edit the labels of blank nodes.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard shortcut will do nothing.

Outline View Editing | Reverse Triple Direction

Deletes the triple that links the node of the parent item with the node of the selected item, and replaces it with a triple that has the same parts except with the subject and object switched. The only visible change in the outline is that the predicate string such as Type will switch to is Type of or vice versa.

This command is useful when you inadvertently create a triple where the predicate goes in the wrong direction.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Create Item for a New Triple

Creates a new outline item just below the selected item, and then prompts you for the information that's needed to create a new triple.

The first pop-up menu has the two choices Create Child Item and Create Sibling Item. Create a child item if the new triple should use the node of the selected item as one of its nodes, or create a sibling item (of the selected item) if the new triple should use the node of the parent item instead. A child item will appear indented under the selected item, while a sibilng item will appear directly under the selected item at the same level of indentation.

The next menu will ask which direction the triple should have, specifically whether the node of the new item should be the object or the subject of the triple that links it with the node of its parent item. The parent/child relationship of outline items has no meaning since the node of the child item can be either the subject or object of the triple. The predicate string will be either of the form Type or is Type of to indicate the direction. (In particular, if the string is sub Class Of of is confusing when building a subClassOf hierarchy, try turning on Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass".

The next menu will ask you which group of predicates you would like to select a predicate from. For the meanings of the different sets of predicates from which you can select, see Graphical Query Link | Specify Predicate. If you cancel from any of the pop-up menus so far, then the new outline item will be removed.

Once you have selected a predicate, the next pop-up menu will ask you which way you would like to specify the other node for a new triple. These choices correspond to the commands Outline View Editing | Enter a Different Node, Outline View Editing | Select a Different Node, and Outline View Editing | Enter a Typed Literal. If you specify the node, then a new triple will be added to the store (note the status bar message). Otherwise the new outline item will remain in place, and you can use one of those commands later to complete the specification for a new triple.

Some shortcuts are available for skipping some of these steps. See Outline View Editing | Create Sibling for Same Predicate and Outline View Editing | Create Child for Same Predicate for more quickly creating items that reuse the same predicate and direction. And when using blank nodes rather than RDF, see Outline Options | Create All Nodes as Blank Nodes.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Create Sibling for Same Predicate

This is a shortcut version of the command Outline View Editing | Create Item for a New Triple. It will always create a sibling item rather than asking you to create a sibling or child, and will always use the same predicate and direction as the selected item. This allows you to create items for new triples more quickly when you are creating a number of them for the same predicate.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Create Child for Same Predicate

This is a shortcut version of the command Outline View Editing | Create Item for a New Triple. It works the same as Outline View Editing | Create Sibling for Same Predicate except that it creates a child item of the selected item rather than a sibling item.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Delete the Triple

Deletes the triple that links the node of the selected item with the node of its parent item.

By default, a confirmation dialog will appear to ensure that you really want to delete the triple. To delete triples more rapidly, you can disable the confirmation dialog by toggling off Edit | Confirm Triple Deletion.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Shift Downward

Shifts the selected outline item below the item that is just below it. This does not make any change to the store. It is useful only for positioning the item just beneath an item that you would like to indent it under with Outline View Editing | Shift Rightward.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Shift Upward

Shifts the selected outline item above the item that is just above it. This does not make any change to the store. It is useful only for positioning the item just beneath an item that you would like to indent it under with Outline View Editing | Shift Rightward.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Shift Downward to Next Parent

Shifts the selected outline item so that it is a child of the next (downward) sibling of its parent item. This deletes the triple that links the node of the selected item with the node of the parent item, and creates a triple that links the node of the selected item with the node of its new parent item.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Shift Upward to Previous Parent

Shifts the selected outline item so that it is a child of the previous (upward) sibling of its parent item. This deletes the triple that links the node of the selected item with the node of the parent item, and creates a triple that links the node of the selected item with the node of its new parent item.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Shift Rightward

Indents the selected outline item under the sibling item that is just above it. This deletes the triple that links the node of the selected item with the node of its parent item, and creates a triple that links the node of the selected item with the node of the sibling item that's just above the selected item, which becomes the selected item's new parent.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Shift Leftward

Unindents the selected outline item so that it is at the same indentation level as its parent, becoming a sibling of its former parent. This deletes the triple that links the node of the selected outline item with the node of its parent, and creates a triple that links the node of the selected item with the node of its grandparent item, which becomes the item's parent.

This command will not appear on the menu if the store was opened in read-only mode, and its keyboard and mouse shortcuts will do nothing.

Outline View Editing | Show the Navigation Menu

Shows the navigation menu. This command is mostly a reminder that you can invoke the navigation menu directly with a shift-right-click or by typing Shift-M.

Drag and Drop in the Outline View

Another way to move an item to a different parent is to use drag and drop. Specifically, left-click down on an outline item, then drag to another outline item whose node you would like to link the dragged node with, and finally release the mouse button. The mouse cursor will be a plus sign to indicate that you are dragging. To cancel the edit while the mouse button is still down, press the Escape key.

If you drop onto a valid item, the triple between the dragged node and the node of the old parent item will be deleted from the store, and a triple will be created between the dragged node and the node of the item that you dropped it onto. The dragged item will then show as a child of the dropped-onto item, and it will no longer appear under the old parent item.

To copy the dragged item rather than move it, hold down the control key when clicking down on the outline item to drag it. Then it will still create a triple with the node of the dropped-on outline item, but will not delete the triple with the node of the original parent item.

If the drop is not allowed for some reason, then a brief explanation will appear in the status bar.

The Outline View Navigation Pop-Up Menu

This menu appears when you shift-right-click in the outline view or press Shift-M. You will probably usually want to use the keyboard and mouse shortcuts that are shown on the right side of this menu rather than the menu itself, but the menu is always handy to remind you what those shortcuts are.

Outline View Navigation | Move Down to Next Node

Selects the node that is immediately beneath the currently selected node.

Outline View Navigation | Move Up to Previous Node

Selects the node that is immediately above the currently selected node.

Outline View Navigation | Leap to Parent

Selects the parent item of the currently selected outline item.

Outline View Navigation | Move Down to Next Sibling

Selects the next outline item that's a sibling of the currently selected outline item, if any. If the item has any child nodes displayed, then this command jumps over those children to the next sibling.

Outline View Navigation | Move Up to Previous Sibling

Selects the previous outline item that's a sibling of the currently selected outline item, if any.

Outline View Navigation | Display Linked Nodes for the Current Predicates

Shows linked nodes of the currently selected node as indented child items of the selected item. The only nodes that will be shown are those that are linked by the current predicates, so you would first need to use Global Options | Select Current Predicates to set them up.

This command can alternately be performed by clicking the small arrow icon at the left end of a node title in the outline, when the arrow is pointing the right to indicate that it is not "fully open" already, and when the arrow is solid rather than hollow to indicate that it does have linked nodes by the current predicates. Note that the linked node that happens to be displayed as the parent outline item will not be displayed again as a child item.

This command is a copy of the menu bar command Link | Display Linked Nodes for the Current Predicates. See that command for more information.

Outline View Navigation | Hide Children (or jump to parent)

If the currently selected outline item is currently "open" to reveal linked nodes as indented child items, then this command will "close" the selected outline item so that it no longer shows any linked items indented beneath it. If the selected item is already closed, then this command will jump to the parent item.

This command can alternately be performed by clicking the small blue arrow icon at the left end of a node title.

Outline View Navigation | Display Sibling Triples for the Same Predicate

Displays the other triples for the same predicate and parent node as the selected item. Whenever there are more triples for a predicate and parent node than Outline Options | Maximum Triples per Predicate in Outline, and Outline Options | Honor Maximum Triples per Predicate is enabled, then only one of the triples is initally displayed when the parent item is opened. To show the rest of the triples, you can either use this command or click the note that says click here to see the other xxx.

Outline View Navigation | Hide Sibling Triples for the Same Predicate

Hides the other triples for the same predicate and parent node as the selected item. This can be handy when there are many triples for a single predicate that otherwise require lots of scrolling to get past them.

A shortcut for this command is to click the predicate name.

Outline View Navigation | Display a Linked Node from Menus

This command allows you to display any node that's linked to the currently selected node, showing it as an indented child item in the outline. The choices are NOT limited to nodes that are linked by the current predicates.

This is a copy of the menu bar command Link | Display a Linked Node from Menus. See that command for more information.

Outline View Navigation | Display a Linked Node from an Outline

This commands lets you select any subset of the nodes that are linked with the selected node, and then adds child items for them to the selected node.

This is a copy of the menu bar command Link | Display Linked Nodes from an Outline. See that command for more information.

Outline View Navigation | Add to Graph View

Adds the currently selected node to the graph view, with a link line for the triple that links it with the node of the parent outline item. The graph view is not selected, though, allowing you to add any number of nodes from the outline to the graph view before switching to the graph view to see them.

Outline View Navigation | Display in Table View

Displays all of the triples of the currently selected node in the table view. This is simply the View | Table View menu bar command, which always displays the properties of the selected node, if any.

Outline View Navigation | Copy to Top Level

Creates a new top-level outline item for the currently selected node, placing it at the very top of the outline. That item can then be opened to show a hierarchy that has it at the top level.

Outline View Navigation | Move to Top Level

Replaces the entire tree of items that contains the selected outline item with the sub-tree whose top is the selected outline item. This "moves" the selected sub-tree to the top level by throwing away everything that's in the tree except for that sub-tree of it.

This is useful when you have browsed down through a hierarchy, and have arrived at the node that you were looking for, in order to begin browsing a tree with it at the top level.

This command is similar to using Outline View Navigation | Copy to Top Level and then Remove | Remove Selected Node on the top-level node of the old tree.

Outline View Navigation | Copy URI to Clipboard

Copies the URI string or literal string of the currently selected node to the clipboard, for pasting anywhere. This is a copy of the View | Copy command.

Outline View Navigation | Copy Triple ID to Clipboard

Copies to the clipboard the ID integer of the triple that links the currently selected node with the node of the parent outline item.

This works like Table View Value Column Navigation | Copy Triple ID to Clipboard in the table view; see that command for more information.

Outline View Navigation | Invoke Web Browser on Node Value

Invokes your third-party web browser or other program on the IRI or literal string of the currently selected node, if any. See View | Web Interaction | Invoke Web Browser on Node Value for more information.

Outline View Navigation | Scroll Down Half a Page

Scrolls the outline downward by one-half of the window height. This command exists to provide a keyboard shortcut for scrolling that uses the main part of the keyboard.

Outline View Navigation | Scroll Up Half a Page

Scrolls the outline upward by one-half of the window height. This command exists to provide a keyboard shortcut for scrolling that uses the main part of the keyboard.

Building a Hierarchy from Scratch in the Outline View

Here is a step-by-step tutorial for building an arbitrary hierarchy of linked nodes from scratch in the outline view. This could be done in a new store that you've just created, or in an existing store (as long as it's OK to modify it). Make sure that the store is opened in read/write mode rather in read-only mode, as needed for creating triples. Also make sure that the option Outline Options | Create All Nodes as Blank Nodes is not on.

You may want to resize Gruff and the window that's displaying this tutorial text, so that you can refer back to the text while pop-up menus are being displayed by Gruff.

Outline Options | Show Full URIs in Outline. Shift+8 (on the main part of the keyboard) is the keyboard shortcut for that menu bar command, so you could frequently press Shift+8 to toggle between showing full URIs and showing more easily readable "pretty" labels. For now, press Shift+8 as needed to show the shorter labels.

The Query View

The query view allows you to write and run any SPARQL or Prolog query and see the results in a table. Nodes in the results table can then be viewed in detail in the table view, or added to the graph view.

To do a query, first decide whether you want to do a SPARQL query or a Prolog query, and select the corresponding radio button at the upper left. The very first time you go into each mode, a basic skeleton expression for that particular mode will be shown in the query text widget.

Next, type or paste a query into the text-editing widget at the upper left. Then press the Run Query button. If the query is valid and it returns any results before timing out, then the results will be displayed in the table in the lower part of the window. The timeout limit can be set with Query Options | Query Timeout.

A SPARQL query can be canceled when using AllegroGraph, though not at a SPARQL endpoint. The Run Query button will show Cancel Query while a query is running to indicate that it will do that. It may take a few seconds for the server to check for a cancel and respond to it, and the button will say Canceling ... during that time to let you know that you don't need to try the cancel again. Should the cancel not work, the query will still time out at some point. You can also cancel by pressing the Escape key, but only if the query text widget or the query results widget has the keyboard focus.

All registered namespace abbreviations will be in effect for any query, so you do not need to include PREFIX statements in the query string for any namespace abbreviations that have been registered. You can edit a global set of registered namespace abbreviations with Global Options | Namespace Abbreviations.

An alternative to writing text queries in this view is to develop them graphically as diagrams in The Graphical Query View.

If the Use Planner check box is checked, then a query planner is first invoked that attempts to speed up the query by first analyzing it and reordering some clauses and doing other transformations to the query. This usually works well, but in some cases may not.

For Allegrograph triple-stores, SPARQL mode supports SELECT, DESCRIBE, and CONSTRUCT queries, along with SPARQL/Update requests that contain INSERT and DELETE forms. For SPARQL/Update requests, there are no results to list in the table, and a simple status bar message will be shown that mentions how the store's triple count has changed, or that the request failed. For SPARQL endpoints, only SELECT and UPDATE queries are supported.

In SPARQL mode, if you use SERVICE clauses to fetch some information from SPARQL endpoints, then Gruff will deduce from the query results some triples that must exist at those endpoints. You can then continue to browse those triples in Gruff alongside all of the triples of the store or endpoint that you are currently using. See Building an Ad Hoc Federation from Multiple Stores and Endpoints. Similarly, a CONSTRUCT query will add triples to what Gruff is browsing, but not add them to the store itself.

In Prolog mode, the text can actually be any set of lisp forms, which will simply be evaluated. Results will be shown in the table only if one of the forms is a Prolog select or select0 call. (If there are multiple such calls, the results of only the last one will appear in the table.) This is typically useful for including lisp forms that define rules for Prolog functors, or lisp functions that are used in Prolog queries.

In Prolog mode, the Reindent button may be used to reindent the lisp forms in the usual way that clarifies the nesting of parenthetical expressions. This may not be needed while typing in queries, though, because pressing Enter to move to a new line will always indent the new line at that time. Matching parentheses are also highlighted with a green block when the text cursor is just outside a parenthesis.

The Select All button will select all text in the query text widget to make it easy to begin typing in a new query or pasting copied query text over the old text. This button will also move the keyboard focus to the query text widget. So typing its keyboard shortcut (alt-A) is a quick way to set things up for entering new query text.

See View | Copy and View | Paste for a way to insert URIs into the query text widget without typing them.

In Prolog mode, you can use the ! (bang) notation in a query, though if you are using the Gruff fasl in a development lisp (rather than the standalone Gruff application), then you will need to first call enable-!-reader yourself.

You can name a query to allow revisiting it in the current Gruff session. Pressing the Name Query button will ask for an arbitrary name for the query that was performed most recently. The name may contain spaces and any other special characters. Pressing the Revisit button any time later in the current session will allow selecting a named query from an alphabetized menu. Both the query text and its results table will then be redisplayed. Alternately, the buttons showing left and right arrows may be used to invoke the View | Go Back and View | Go Forward commands to revisit queries in the order in which they were performed. Whenever a query that was named is revisited, its name will be shown under the Name Query and Revisit buttons.

If your query text sometimes contains URIs or literals that contain non-ASCII characters, then see Query Options | Percent-Encode Non-ASCII in Queries.

Mouse Clicks and Keyboard Shortcuts in the Query View

Mouse clicks in the table are similar to those in the table view, except that rather than having one dedicated predicate column and one dedicated node column, any column may hold either predicates or nodes depending on its role in the query.

Right-click any cell in the results table to show a pop-up menu of commands that can be applied to that table cell. When the menu appears, you can press the letter key that's mentioned at the left of the desired command to run that command. To the right of each command name are the keyboard and mouse shortcuts that may be used to run that command without first showing the pop-up menu.

The commands that will appear in the pop-up menu for a node cell are described in the documentation for The Table View Value Column Editing Pop-Up Menu and for the Table View Value Column Navigation Pop-Up Menu, and the commands for a predicate cell are described under The Table View Property Column Pop-Up Menu. Only some of those commands are included in the query view menus though.

Click a column header cell to sort the table by that column.

There are also some handy keystrokes in the query results table, once you have given the table the keyboard focus by tabbing to it if needed. The TAB moves between the three tables and the query text widget. The arrow keys will move the focus to various cells, and will scroll the table automatically to move the focused cell into view as needed. Alternately, F moves downward, D upward, A rightward, and Shift-A leftward. The spacebar will act like a left mouse click in the focused cell. The PageUp and PageDown keys will scroll the table vertically by most of a page, and Control-PageUp and Control-PageDown will scroll it horizontally.

Two small grids at the bottom of the query view hold the nodes and predicates that were explicitly specified in the query text. These grids use the same mouse clicks as the main grid, and can be useful for accessing the explicitly specified nodes and predicates individually. If a query did not produce the expect results and it's unclear why, it may be a good idea to check that every explicit URI in the query text that should be represented in the store is present in one of the two lower grids; if not, then perhaps there is a typo in the query text for a URI that does not appear there.

In the query text widget, you can use basic Emacs keystrokes for moving around and deleting text. An exception is that for cutting, copying, and pasting text you must use the Windows keystrokes Control-X, Control-C, and Control-V. And for undo and redo you must use Control-Z and Control-Y.

A note about the menu shortcuts for the drop-down menus on the menu bar: When the keyboard focus is in the query text widget, you cannot use the keyboard shortcuts for any drop-down menus that use graphical characters as shortcuts (that is, without the control key or alt key), because those shortcuts will type characters into the text-editing query text widget instead. This includes the commands on the View menu for switching to another view. For this reason, the query view has dedicated button widgets for switching to each of the other views. These buttons have keyboard shortcuts as well, though they require the alt key. Alternately you can tab out of the query text widget and then use any pull-down menu keyboard shortcuts.

Generating Visual Graphs from Query Results

You can generate a visual graph of nodes and links in the graph view from the query results by pressing the Create Visual Graph button widget. The Add to Visual Graph button widget is similar except that it does not first clear the graph view. It adds to the existing nodes and links, and also will connect any new nodes to any existing nodes that are connected by predicates from the new query.

A visual graph displays triples, but the results of a SELECT query are not triples. So Gruff must use an arbitrary approach to derive triples that are related to the query results. You can choose from two different approaches using Query Options | Include More Triples in Visual Graphs.

If little or no output is generated into the graph view, this may be because the body of the query in the WHERE clause uses variables that are not selected in the SELECT clause. Gruff then doesn't have enough information in the query results (along with the query itself) to find related triples to display.

Sometimes the Create (or Add to) Visual Graph button may include many more nodes in the visual graph than you would like. If this happens, you could remove some of the nodes afterward, perhaps using Remove | Exclude Selected Node to prevent the nodes from being added to the graph view again on subsequent uses of these buttons. Alternately, you could use some of the special mouse clicks for the query results table that are described above for adding individual nodes to the graph view. Typically you would first control-click some predicate cells in the query results table to make those predicates be current predicates, and then shift-click some node cells in the table to add those nodes to the graph view, which will also link them to other nodes by the current predicates that you selected first. (Show the right-click pop-up menu to see all of the mouse click shortcuts.)

Writing Query Results to Files

The Write Text Report button will write the query along with its table of results to a plain-text file, after prompting you for where to save the file. The format of the table will depend on the option Query Options | Query Text Report Show FullURIs along with Query Options | Query Text Report One Line per Value. To automatically write this report for a series of queries rather than using this command and selecting a file for each one, see Query Options | Query Logging Enabled.

The Save as CSV button will save the query results as a plain-text file, after prompting you for where to save the file. The file will be in the CSV format, with a newline after the data for each row and commas between the values within a row. Each value will be printed in ntriples format with double-quote characters around the value. Any double-quote characters that are embedded in a printed value will be doubled in the file, as specified by the CSV format. A CSV-format file can be imported into Microsoft Excel, for example. See also File | Export Displayed Data As | NodeURIs.

The Graphical Query View

The graphical query view allows devising a query visually as a diagram. This is done by arranging node boxes and link lines that represent triple patterns in the query, where the triple patterns can contain variables as well as actual objects that are in the store. A hierarchy of group graph patterns can also be specified be wrapping nested grouper boxes around sets of nodes. General and specialized filters can be specified as well. A SPARQL or Prolog query can then be automatically generated from the diagram and executed as usual in the query view.

Use the View | Graphical Query View command on the menu bar to select the view. Then right-click on the background, on nodes, and on links to see pop-up menus of commands that are applicable to the clicked object in the current context. Some commands will appear only when they applicable. Each command will have a letter on the left that can be typed to invoke the command with the keyboard once the menu appears. Some of the commands also have shortcuts printed on the right, which can be used without showing the menu at all.

The pop-up menu command for the currently selected object (or for the background when no object is selected) can also be invoked by pressing the M key. If both a node and a link are selected, then shift-M can be used to invoke the menu for the selected link. The selected objects can also be deselected and reselected with the keyboard by using the keyboard shortcuts for the menu bar commands Select | Deselect the Selected Node and/orLink and Select | Reselect Previous Node and Link.

Some other menu bar commands are still useful in this view that emphasizes pop-up menus. For example, View | Go Back and View | Go Forward can be used to return to earlier stages of a graphical query.
File | Save Graphical Query and File | Load Graphical Query can be used to save a query diagram to a file and reload it any time later. The Copy and Paste commands on the View menu can be used to make copies of nodes in a query, or to paste nodes from other views into a query. Some of the other menu bar commands are applicable as well; trying one will tell you if it's not applicable.

As with the menu-bar, if you highlight a command on one of these pop-up menus and then press the F1 key, help will be shown for that particular command.

The Graphical Query Background Pop-Up Menu

This menu will appear when you right-click the background of the graphical query view, which means anywhere in the window interior except on a node or a link.

Graphical Query Background | Add Variable Node

Adds a node to the display that represents a query variable for nodes. The new node will appear where the mouse cursor was when invoking the menu that contains this command. The node will then prompt you to edit the name of the variable. Simply type in the desired variable name, without the question mark at the beginning.

If there are already any node variables in the query, then a menu will first appear asking whether to create a new variable or to reuse one of the existing variables. In a complex query, it may be necessary (or simply convenient) to use multiple nodes that represent the same variable. An alternate way to create another copy of a variable node is to use View | Copy followed by View | Paste.

Graphical Query Background | Add Non-Variable Node

Adds a node to the display that represents an actual subject or object that's in the store, rather than a query variable for nodes. A second pop-up menu will appear that contains most of the commands from the Display menu on the menu bar, for selecting the node to display. These commands could alternately be used from The Display Menu itself, but they are duplicated here to be with related functionality that is mostly on pop-up menus in this view. These commands behave just as they do in the graph view. A node that is added will appear where the mouse cursor was when right-clicking to invoke the initial menu.

Graphical Query Background | Remove Nodes and/or Links

Shows a menu of the commands from The Remove Menu on the menu bar that are applicable in the graphical query view. These are duplicated here to group them with related functionality that is mostly in pop-up menus in this view.

Use the Remove All Nodes command to begin a new query from scratch.

Graphical Query Background | Convert Highlighted to Variable Nodes

Converts every non-variable node that is currently highlighted into a variable node. This is like using Graphical Query Non-Variable Node | Convert to Variable Node on each node, except that instead of prompting you for a name for each variable, a unique name that's based on the most specific type of each node will be created automatically.

The simple way to first highlight a set of nodes is to control-left-click each one. To unhighlight all nodes, control-left-click the background. (On the Mac use the command key here rather than the control key.) See Select | Toggle Highlighting of the Selected Node or Link.

Graphical Query Background | Convert Highlighted to Variables with Types

Converts every non-variable node that is currently highlighted into a variable node, and adds node filters to each one that require any variable matches to have all of the types that each of the original nodes have. This is like using Graphical Query Non-Variable Node | Convert to Variable with Types, except that instead of prompting you for a name for each variable, a unique name that's based on the most specific type of each node will be created automatically.

Graphical Query Background | Add a Grouper | Add a Regular Grouper

Adds a regular grouper (called an AND grouper in Prolog mode) to the display. For a regular grouper, any set of variable bindings must be a match for all of the triple patterns and groupers that are inside the grouper in order for it to be a match for the grouper itself.

The nodes in a graphical query that are not inside a visible grouper are basically inside an implicit regular grouper, so this type of gouper is mostly useful inside other types of groupers.

In a SPARQL query, the contents of a regular grouper will become a plain Group Graph Pattern enclosed in braces, with no additional keywords. In a Prolog query, the contents will become arguments to the Prolog and predicate.

In general, a grouper is a box that can surround groups of triple patterns and other groupers. You can resize any grouper by left-clicking and dragging it from any edge or corner. Or move a grouper by clicking more toward the middle of the grouper and dragging. When you move (but not resize) a grouper, all of the triple patterns and other groupers that are inside it will move along with it. (You could even add a grouper temporarily just to move some set of nodes.)

In order for the diagram to be interpretable as a query, the outside edge of a grouper box must not intersect another grouper or a connected set of nodes. This constraint is enforced automatically by expanding groupers when needed to remove any such intersections. Specifically, whenever a grouper surrounds or intersects a node, it will be expanded as needed to surround that node as well as all of the nodes that are connected by links (either directly or indirectly) with that node. And when any two groupers intersect each other, the larger of those groupers will be expanded to surround the smaller one. Note that when a grouper is expanded to surround one thing, that can cause further intersections that lead to more grouper expansion. If you inadvertently cause groupers to surround things that they shouldn't, then as usual you can undo the change with View | Go Back.

The automatic enlarging of grouper boxes is done primarily to enforce consistency, but it also sometimes makes it easier to arrange groupers. For example, when adding a new grouper, you don't need to stretch the grouper yourself all of the way around the contents that it needs to surround, because it will be stretched farther automatically when needed. Or say you would like to move one grouper into a second grouper. If the first grouper is smaller, then you just need to drag it so that overlaps the second grouper a bit (but not to where either grouper overlaps with any nodes in the other grouper), and then larger grouper will expand to surround the smaller one automatically; that removes the need to first make the second grouper large enough for the first grouper to fit into it.

When query text is generated, groupers whose upper edges are higher in the diagram will appear earlier in the query text than sibling groupers.

Graphical Query Background | Add a Grouper | Add a Union Grouper

Adds a union grouper (called an OR grouper in Prolog mode) to the display. For a union grouper, any set of variable bindings that is a match for any of the triple patterns or groupers that are inside the union grouper is also a match for the union grouper itself. In other words, all of the matches for the things inside a union grouper are combined to produce the matches of the union grouper.

In a SPARQL query, the contents of a regular grouper will become a Group Graph Pattern enclosed in braces, with the keyword UNION inserted between successive triple patterns and group graph patterns that are inside the union pattern. (Any triple patterns within the group that are not in subgroups will actually be turned into group graph patterns themselves, as required by a union pattern.) In a Prolog query, the contents will become arguments to the Prolog or predicate.

Graphical Query Background | Add a Grouper | Add an Optional Grouper

Adds an optional grouper to the display. An optional grouper does not change the set of matches that are found for a query, but will provide additional variable bindings to the matches whenever the variables in the optional grouper also happen to match.

In a SPARQL query, the contents of an optional grouper will become a Group Graph Pattern enclosed in braces, with the keyword OPTIONAL inserted just before the group graph pattern. This makes the contents be an optional part of the surrounding group. In a Prolog query, the contents will become arguments to the Prolog function optional.

If you only need to make the triple patterns of a single link line be optional, then a quicker alternative is to right-click the link line and use Graphical Query Link | Toggle Optional. That does not require making copies of the end nodes when they have other links for non-optional triple patterns.

Graphical Query Background | Add a Grouper | Add a Graph Node Grouper

Adds a graph grouper to the display for one of the named graphs that exist in the triple-store. You will be asked for which graph to use, and the name of that graph will appear on the grouper. This will generate a group graph pattern in SPARQL that matches only on triples that are in that graph.

Graphical Query Background | Add a Grouper | Add a Graph Variable Grouper

Adds a graph grouper to the display for a variable that will match on the graphs that triples are in, when they match on triple patterns inside that grouper. You will be asked for the name of the variable to use for the matching graphs.

Graphical Query Background | Add a Grouper | Add a Minus Grouper

(This also applies to the similar commands for Filter Exists and Filter Not Exists.)

These groupers work syntactically just like an optional grouper, except substituting those other strings in place of optional in the generated SPARQL query. These are described by the W3C at https://www.w3.org/TR/sparql11-query/ .

Graphical Query Background | Change Grouper Type

Lets you select a different grouper type for the grouper that was under the mouse when the menu containing this command was invoked. (This command is not included when the mouse is not over a grouper.)

A pop-up menu will appear with choices for the three kinds of groupers. Selecting one will change the type of the already-existing grouper.

Graphical Query Background | Remove Grouper

Removes the grouper that was under the mouse when the menu containing this command was invoked. (This command is not included when the mouse is not over a grouper.)

Only the grouper itself is removed. Any nodes, links, and other groupers that are inside the grouper will remain in place. To restore an accidentally-removed grouper, use View | Go Back as usual.

Graphical Query Background | Tighten Up Groupers

Reduces the size of all groupers to the minimum size that surrounds their current contents, with the usual minimum margins. This can make a graphical query diagram look more consistent by having the same margins everywhere between grouper edges and content.

When multiple levels of groupers are tightly nested, such as after using this command, there may not be many positions at which you can click and drag an outer grouper in order to move it, because the exposed edges of the outer grouper are the clickable areas for resizing rather than moving. But you should always be able to click in the lower half of the top margin of a grouper to move it. (The top margin is kept thicker to avoid crowding the grouper label, and for this reason as well.)

This command will not appear if there currently are no groupers in the diagram.

Graphical Query Background | Add a Comment Node

Adds a node that simply displays a comment somewhere inside the graphical query diagram, and has no effect on the textual query that gets generated. You can add any number of comment nodes to a query, where you might position some of them near the parts of the diagram that they discuss, while another one might describe what the whole query is about.

Right-clicking a comment node will show the The Graphical Query Comment Node Pop-Up Menu.

Graphical Query Background | Add Filter to Grouper

Adds a text line for a filter expression at the bottom of the grouper that was under the mouse cursor when the menu that contains this command was invoked. In the textual query that is generated later, the expression for this filter will be part of the text for the Group Graph Pattern that this grouper represents.

In Prolog mode, this command is called Add Predicate Form to Grouper. This command will not appear if there currently are no groupers in the diagram.

To remove a filter from a grouper, left-click the filter text to edit it and replace the text with no text or all white space.

For more information, see Graphical Query Background | Add Top-Level Filter

Graphical Query Background | Add Top-Level Filter

Adds a text line at the bottom of the window for entering an arbitrary SPARQL filter expression, or a predicate lisp expression when in Prolog mode. When you see the flashing text cursor appear at the bottom of the Gruff window, simply type in the expression (not including the word FILTER itself). It will be included in the generated query "as is". To modify the filter later, left-click on the filter text to initiate editing it.

In Prolog mode, this command is called Add Top-Level Predicate Form. You need to enter a lisp expression that will work in the Prolog query as an argument to a call to lispp.

While you're editing the text of a filter, a special feature is invoked by typing control-V to do a paste. Rather than simply pasting whatever is on the clipboard as usual, a pop-up menu first appears with choices on what to paste. The first choice in this menu is Clipboard Text, which will paste the clipboard value (which is shown on the menu), but the remaining choices show further menus. The second choice is Operator, which shows a menu of standard SPARQL operators that can be pasted (though very short operators like <= are exclude). The remaing choices are Node, Node Variable, Predicate, and Predicate Variable, each of which will appear only when applicable. Each of these will show a further menu containing instances that currently exist in the graphical query, such as all of the query's node variables; this makes it easy to paste objects from the query into a general filter expression.

To remove a top-level filter, right-click the top-level filter area at the bottom of the window, select Remove a Filter from the menu that appears, and select the filter to remove from the next menu that appears. Or left-click a particular filter to edit its string, and replace the text with the empty string or whitespace. In either case, the row for that filter will be removed.

When switching between SPARQL and Prolog modes (with the radio buttons at the upper left), no attempt is made to automatically convert these expressions from one language to the other. This is one part of the query that needs to be specified for the desired mode only.

As an alternative to these general filters, specialized filters that apply to individual nodes can be added from the pop-up menus for nodes and links. See Graphical Query Variable Node | Specify Node Filter and Graphical Query Link | Specify Link Filter. Those special filters will generate appropriate code in either SPARQL or Prolog mode, unlike this facility for arbitrary filters.

Graphical Query Background | Specify Variables to Select

Lets you specify which of the node and predicate variables will be selected in the query (meaning which ones will have columns in the table of results), and the left-to-right order of the variables in the results table.

The mouse cursor will change to a cross to indicate that it is waiting for you to click on the desired variables. Left-click on each node or link that represents a query variable, in the desired left-to-right order. When you have selected all of the desired variables, left-click the background to signal that you are done. Or press the Escape key to cancel the selection, which will restore the previous set of selected variables. To specify no variables after some have been selected, invoke this command and then click the background.

When no variables are specified, the query will default to selecting all variables, in some arbitrary order. The variables will still be listed explicitly in the generated query text, in case you'd like to edit the list textually in the query view.

An explicitly selected variable is indicated visually with a short string in the label of the node or link, beginning with s (for select) and followed by the index in the selection order. As you click on a series of nodes and links, you will see these strings such as s1 and s2 appear in the labels as immediate feedback.

There is no way to add or remove a single variable to or from the list. You must specify the complete sequence in order to change it.

Graphical Query Background | Specify Variables to Order By

This is similar to Graphical Query Background | Specify Variables to Select, except that it specifies the order in which rows of the results table will be sorted. In SPARQL mode this will generate an ORDER BY clause, and in Prolog mode this information is not used. The visual indicator will be a short string beginning with o (for order by).

If a link line represents multiple predicate variables, at this time only the first of those variables can be added to the list of variables to order by. You would need to copy the nodes and use a separate link line between them to add additional predicate variables from the original link line to the list of variables to order by.

The Graphical Query Variable Node Pop-Up Menu

This menu appears when you right-click a node that represents a variable rather than an actual subject or object. Such nodes are created with Add Variable Node on the background menu. Variable nodes are distinguished by the question mark character that is prepended to the variable name in the node's label.

Graphical Query Variable Node | Add Predicate Link

Creates a link between the node that you clicked originally and a second node that you click after selecting this command. The link will initially represent a predicate, rather than a predicate variable or a filter, though you can later change what any link represents with commands on the link's own menu.

A rubber band line will appear between the first node and the mouse cursor to prompt you to click on the second node. To cancel the command, click somewhere other than on a node, or press the Escape key.

If you do click on a second node, then menus will appear for selecting the predicate for the new link to represent, as when using Graphical Query Link | Specify Predicate from the link's menu later.

A related non-obvious feature is that you can drag either end of any link to a different node. Do this by left-clicking down on a link line toward the desired end of it, and then dragging the rubber band line that appears and releasing the mouse over a different node.

Graphical Query Variable Node | Add Predicate Variable Link

Creates a link as with Graphical Query Variable Node | Add Predicate Link, except that the link will initially represent a query variable for predicates. You will then be prompted to type in a name for the variable, as when using Graphical Query Link | Specify Predicate Variable from the link's menu later.

Graphical Query Variable Node | Add Filter Link

Creates a link as with Graphical Query Variable Node | Add Predicate Link, except that the link will initially represent a special filter that applies only to the two nodes that are connected by the link, as when using Specify Link Filter from the link's menu later.

Graphical Query Variable Node | Specify Node Filter

Lets you specify a special filter that applies only to the variable that's represented by this node. The selected filter will be indicated by a line of text in the node's box, below the name of the node variable.

This command will replace any filters that were on the node previously. To add an additional filter instead, use Graphical Query Variable Node | Add Node Filter. (If you accidentally remove filters with this command, you can get them back as usual with View | Go Back.)

A menu of filter types will appear, where the choices mostly correspond to standard SPARQL filter operators. Any of these will generate a SPARQL filter expression when the query is generated. When in Prolog mode, lisp code that corresponds to the SPARQL operators will be generated instead. Some filter types are not supported in Prolog mode, and so the generated query will not work in Prolog mode when they are used; these include ends with, bound, is an IRI, is literal, and the corresponding not filters.

The choices in the middle section of the menu (such as bound and is blank) are unary operators that will simply take the node as their single argument. The choices in the lower section (such as not = and <=) are binary operators that will further prompt you to enter a static value (a string or number) to which to compare the node variable's value.

The binary operators in set and not in set work a little differently than the others. When you select one of these, you will be asked to select just the first value for the set of values for that filter (which becomes an IN or a NOT IN filter in the generated SPARQL). Then to add each additional value to the set (or to remove a value), you can thereafter use commands that appear on the top-level pop-up menu for variable nodes when they have an in set or not in set filter already. These commands are Add to In Set Filter, Remove from In Set Filter, Add to Not In Set Filter, and Remove from Not In Set Filter. This approach allows you to use the usual sequence of pop-up menus to select each node or other value interactively, rather than for example typing them into a single widget that holds the entire list as text.

The single choice in the upper section is Type. This choice does not generate an actual filter expression, and instead generates a triple pattern that declares that the value of the node variable has a particular rdf:type property. Further pop-up menus will appear for choosing the particular type. (The first time the menus of all types are requested, Gruff will first search for and cache all rdf:type object nodes that are in the store.) Alternately, you can specify a type constraint in the usual way by adding a node to the display for the type and a link to it for the predicate rdf:type; that more general approach may be desirable for showing multiple links to that same type.

Graphical Query Variable Node | Add Node Filter

This works like Graphical Query Variable Node | Specify Node Filter except that it does not remove any of the filters that the node already has.

This command will appear only if the node already has one or more filters.

Graphical Query Variable Node | Remove Node Filter

This command will appear only if the node already has one or more filters. If the node has only one filter, it will remove that filter. Otherwise it will show a menu of the filters that it has so that you can choose which filter to remove. An All choice at the top of the menu allows removing all of the node's filters at once.

Graphical Query Variable Node | Rename Node Variable

Prompts you to edit the name (without the leading question mark) of the query variable that this node represents. Note that if multiple nodes in the diagram represent the same variable, then this command renames the single variable that all of those nodes represent.

Graphical Query Variable Node | Specify a Different Variable

Lets you specify a different node variable for this node to represent. If any other nodes in the diagram represent variables, then a menu will appear where you can select a variable that's represented by other nodes, so that this node will represent that same variable in the query. If you select the New Node Variable option, or if there are not any other variable nodes in the diagram, then you will be prompted to type in a name (without the leading question mark) for the new variable.

If this node represented the same variable as other nodes in the diagram, then this command can be used to make it represent a distinct variable instead.

Graphical Query Variable Node | Reverse Order-By Direction

Toggles the order-by direction of this node's variable between an increasing sort and a decreasing sort. A character in the node's label indicates the current order, where a greater-than character indicates a decreasing order (because the height of the character decreases from left to right), and a less-than character indicates an increasing order.

This command will appear only if the node is in the list of variables by which to order results, which is established with Graphical Query Background | Specify Variables to Order By.

Graphical Query Variable Node | Convert to Non-Variable

Changes the node from one that represents a query variable into one that represents an actual subject or object that's in the store. You specify the object just as when using Graphical Query Background | Add Non-Variable Node on the background menu, though it reuses the existing node (retaining any links to it) rather than creating a new one.

If there is a link line for a non-variable predicate connected to the node, then the menu of ways to select the node will contain a special choice at the top for choosing a subject or object of that predicate (depending on the direction of the link line). Since you can't first create the link line and then the node, a trick for selecting the node only after you've selected the predicate is to first create the node as a variable node, then create a link line that's connected to that node, giving it a non-variable predicate, and then use this command to convert the node to a non-variable node and select a subject or object of that predicate for the node.

Graphical Query Variable Node | Remove Node

Removes the node from the diagram along with any links that are connected to it. This is simply the Remove | Remove Selected Node command from the menu bar, duplicated here to be with related pop-up menu commands.

The Graphical Query Non-Variable Node Pop-Up Menu

This menu appears when you right-click on a node that represents an actual subject or object that's in the store, rather than a node variable. Such nodes are created with Graphical Query Background | Add Non-Variable Node.

Graphical Query Non-Variable Node | Add Predicate Link

Creates a link between the node that you clicked originally and a second node that you click after selecting this command. The link will initially represent a predicate, rather than a predicate variable or a filter, though you can later change what any link represents with commands on the link's own menu.

A rubber band line will appear between the first node and the mouse cursor to prompt you to click on the second node. To cancel the command, click somewhere other than on a node, or press the Escape key.

If you do click on a second node, then menus will appear for selecting the predicate for the new link to represent, as when using Graphical Query Link | Specify Predicate from the link's menu later.

A related non-obvious feature is that you can drag either end of any link to a different node. Do this by left-clicking down on a link line toward the desired end of it, and then dragging the rubber band line that appears and releasing the mouse over a different node.

Graphical Query Non-Variable Node | Add Predicate Variable Link

Creates a link as with Graphical Query Non-Variable Node | Add Predicate Link, except that the link will initially represent a query variable for predicates. You will then be prompted to type in a name for the variable, as when using Graphical Query Link | Specify Predicate Variable from the link's menu later.

Graphical Query Non-Variable Node | Add Filter Link

Creates a link as with Graphical Query Non-Variable Node | Add Predicate Link, except that the link will initially represent a special filter that applies only to the two nodes that are connected by the link, as when using Specify Link Filter from the link's menu later.

Graphical Query Non-Variable Node | Select a Different Node

Lets you specify a different subject or object in the store for this node to represent. You specify the object just as when using Graphical Query Background | Add Non-Variable Node, though it reuses the existing node (retaining any links to it) rather than creating a new one.

Graphical Query Non-Variable Node | Convert to Variable Node

Changes the node from one that represents an actual subject or object that's in the store into one that represents a query variable for nodes. It will prompt you to either select an already-used node variable or to type in the name of a new one, just as when using Add Variable Node on the background menu, though it will reuse the existing node (retaining any links to it) rather than creating a new one.

Graphical Query Non-Variable Node | Convert to Variable with Types

This does what Graphical Query Non-Variable Node | Convert to Variable Node does, and then also adds node filters that require the variable's value to have each of the rdf:type properties that the original non-variable node had. This is a shortcut alternative to using Add Node Filter and selecting the Type option to specify each type explicitly.

For example, if you first used Graphical Query Background | Add Non-Variable Node to add Paul Newman to the diagram, and Paul had rdf:type properties for Academy Award winners and Emmy Award winners, you could then use this command on the node and name the new variable like Paul. The variable node would then have two constraints shown in the node's box that require any value of the variable to similarly be both an Academy Award winner and an Emmy Award winner.

Graphical Query Non-Variable Node | Remove Node

Removes the node from the diagram along with any links that are connected to it.

The Graphical Query Comment Node Pop-Up Menu

This menu appears when you right click a comment node in a graphical query. Comment nodes are created by Graphical Query Background | Add a Comment Node.

Graphical Query Comment Node | Edit Comment

Lets you edit the text that a comment node displays. Just edit the text and then press the Enter key to accept the change or the Cancel key to cancel it. The node will then be resized automatically to fit the new text.

Graphical Query Comment Node | Resize Node

Lets you resize a comment node arbitrarily. This allows you to choose your own width and height, such as to fit optimally among the other nodes, rather than letting Gruff choose the width and height automatically for a fairly square node, as it does after editing the text.

The Graphical Query Link Pop-Up Menu

This menu appears when you right-click on a link line in a graphical query. These link lines are created when you choose one of the Add ... Link commands at the top of the menu for a node, such as Graphical Query Variable Node | Add Predicate Link. Unlike the separate types of graphical query nodes for node variables as opposed to actual nodes in the store, there is a single kind of link in a graphical query, which can represent multiple predicate variables and/or actual predicates that are in the store.

Graphical Query Link | Specify Predicate

Lets you specify a single predicate for the link to represent. If you select one, then that predicate will replace everything that the link was representing previously. Use Graphical Query Link | Add Predicate instead to make the link represent the specified predicate in addition to everything that it represented already.

A menu will first appear for selecting which technique to use for selecting a predicate. There may be many predicates in a store, and so choosing one quickly can be problematic. So this menu provides alternatives for selecting from various subsets of predicates that are likely to be of interest. Here are the choices:

Graphical Query Link | Specify Predicate Variable

Lets you specify a single predicate variable for the link to represent. If you select one, then that predicate variable will replace everything that the link was representing previously. Use Graphical Query Link | Add Predicate Variable instead to make the link represent the specified variable in addition to everything that it represented already.

If any other link lines already represent predicate variables, then a menu will first appear to let you select one of those variables, to make this link line represent the same predicate variable as one or more other link lines. Otherwise (or if you select the New Predicate Variable option) you will be prompted to type in a name (without the leading question mark) for a new predicate variable.

Graphical Query Link | Specify Link Filter

Lets you select a special filter that compares the two nodes that are connected by the link. If you select one, then that filter will replace everything that the link was representing previously. Use Graphical Query Link | Add Link Filter to instead make the link represent the selected filter in addition to everything that it represented already.

The filter choices are simple binary operators such as not =, <=, and language matches. For a directional operator like <=, the filter will declare that the value of the subject node, which is at the non-arrowhead end of the link line, must be less than or equal to the value of the object node, which is at the arrowhead end of the link line.

Graphical Query Link | Add Predicate

This is like Graphical Query Link | Specify Predicate except that it does not remove anything that the link line already represented.

This command appears only if the link line already represents at least one predicate, predicate variable, or link filter.

Graphical Query Link | Add Predicate Variable

This is like Graphical Query Link | Specify Predicate Variable except that it does not remove anything that the link line already represented.

This command appears only if the link line already represents at least one predicate, predicate variable, or link filter.

Graphical Query Link | Rename Predicate Variable

Lets you edit the name of one of the predicate variables that it represents. If the link line represents multiple predicate variables, a menu will first let you select which predicate variable to rename. If multiple link lines represent the renamed variable, then the single variable that is represented by the multiple link lines is renamed for all of the link lines.

This command appears only if the link line currently represents one or more predicate variables.

Graphical Query Link | Reverse Order-By Direction

Toggles the order-by direction of a predicate variable that the link represents between an increasing sort and a decreasing sort. A character in the link's label indicates the order, where a greater-than character indicates a decreasing order (because the height of the character decreases from left to right), and a less-than character indicates an increasing order.

This command appears only if the link line currently represents one or more predicate variables, and one of those variables is in the list of variables by which to order results. (That order is established with with Graphical Query Background | Specify Variables to Order By.)

Graphical Query Link | Add Link Filter

This is like Graphical Query Link | Specify Link Filter except that it does not remove anything that the link line already represented.

This command appears only if the link line already represents at least one predicate, predicate variable, or link filter.

Graphical Query Link | Toggle Optional

Toggles whether the triple patterns of this link line are optional. When turned on, the line is drawn in a dotted style rather than solid, and an OPTIONAL pattern will be generated into the textual query for each triple pattern that the the link line represents.

If this link line represents only filters, then this command will not appear because filters cannot be optional.

To make a group of triple patterns be optional, use Graphical Query Background | Add Optional Grouper.

Graphical Query Link | Reverse Link Direction

Reverses the direction of the link line, so that the object of the triple pattern becomes the subject and vice versa. (The arrowhead on one end of the link line points to the object.)

A related non-obvious feature is that you can drag either end of any link to a different node. Do this by left-clicking down on a link line toward the desired end of it, and then dragging the rubber band line that appears and releasing the mouse over a different node.

Graphical Query Link | Remove Link

Removes the link line from the graphical query.

The Widgets on the Left Side of the Graphical Query View

Most of the widgets in the column on the left side of the graphical query view are used to perform a query after you've created the diagram for it. A few of the widgets are used for naming queries on the fly so that you can return to them easily in the current session.

The SPARQL and Prolog Radio Buttons

These buttons determine whether a SPARQL query or a Prolog query is generated by the Show Text Query and Run Query buttons. A graphical query is always translated into one of these languages before the query is performed.

A diagram in the graphical query view is not specific to either language, and so you can switch this option at any time and generate a textual query from the same diagram. One exception is that when using Graphical Query Background | Add Top-Level Filter (this is called Add a Lisp Form in Prolog mode), the general SPARQL or Prolog expression that you enter must be specific to the target language. These expressions are inserted "as is" into the query text, and no attempt is made to translate them when switching between SPARQL mode and Prolog mode.

The Name Query Button and the Revisit Button

The Name Query button can be used to quickly name a graphical query, or some stage of a query while constructing it. Pressing this button will prompt you to type in an arbitrary name for the current state of the graphical query. At any time later in the current Gruff session, you can press the Revisit button and select a named query from the menu that appears.

Alternately, you can revisit recent states with View | Go Back. Or to save a graphical query state more permanently to a file, use File | Save Graphical Query. Saving a query to a file or loading one from a file will automatically add that query to the list of named queries for the current Gruff session, using the file name as the name.

The Show Text Query Button and the Run Query Button

Once you have constructed a graphical query, you can use one of these buttons to generate the textual SPARQL or Prolog query for it, which will appear in the query view (see View | Query View). The Show Text Query button only generates the text so that you can proofread it or edit it before actually performing the query as usual in the query view. The Run Query button generates the textual query as well, and then also tells the query view to go ahead and perform the query; this is simply a shortcut to do both operations with a single gesture.

The Full Cardinality, REDUCED, and DISTINCT Radio Buttons

Selecting the REDUCED option or the DISTINCT option will add the corresponding SPARQL clause to the generated query. The Full Cardinality choice is simply the option to generate neither of those. These options are not used when generating a Prolog query.

The Limit and Offset Widgets

These widgets are used to include a LIMIT clause and/or an OFFSET clause in a generated SPARQL or Prolog query. (Prolog will not use the Offset option.) Each clause will be generated only when its check box is checked, in which case it will use the number that you have entered into the corresponding text field.

A limit is especially useful for avoiding a huge number of results that may take a long time to find or to display. An offset may be used along with a limit to retrieve distinct batches of results one at a time. For example, a limit of 30 and an offset of 0 would retrieve the first 30 rows of results, and then a limit of 30 and an offset of 30 would retrieve the next 30 (in a SPARQL query only).

Controlling the Order of the Generated Query Text

You can partially control the order of the generated query text via the positioning of nodes and groupers in the graphical query. (And this can be important for generating a more efficient query.) Specifically, a grouper whose upper edge is higher on the screen than the upper edge of a sibling grouper will come before it in the generated query text. Within a particular grouper (or at the top level), a subject node that is higher in the graphical query than a sibling subject node will have its triple patterns generated earlier in the query text. And among the link lines of a single subject node, the ones whose object nodes are higher in the diagram will have their tripple patterns generated first.

On the other hand, the query text for a grouper will always be generated after the text for any sibling nodes that are not in sibling groupers. If that order needs to be reversed for better efficiency, then you could place a regular grouper around silbing nodes that are not yet in a grouper, and then position that regular grouper below the other one so that its generated text will come later.

Any filter expressions will always be generated after the triple patterns that are in the same grouper. If additional control over ordering in the generated query is needed, then let us know.

The Lisp Evaluation View

This is an advanced view for users who are comfortable writing Common Lisp code (though you could potentially load code that others have written and evaluate it). It allows controlling Gruff programmatically in arbitrary ways.

The code can contain calls to Gruff functions that are documented in the section The Programmatic Lisp API to Gruff, as well as calls to functions in the AllegroGraph lisp client for performing most any Allegrograph functionality. Franz also could potentially send code for you to load for debugging purposes.

To evaluate a lisp form (expression), just enter the form into the Input text pane. If Evaluation Options | Evaluate on Enter is enabled, the form will be evaluated when you press the Enter key at the end of a complete form (where the parentheses are balanced). If that option is turned off, then you will need to use either the Evaluate One button or the Evaluate All button to do the actual evaluation.

Each top-level form should begin in the leftmost column, and other lines of text that are in the middle of forms should have at least one space at the beginning. Automatic indentation that's done will normally ensure that. Several basic Emacs keystrokes are implemented for moving around in the text.

Anything that's printed by evaluated forms, as well as the returned values, will appear in the Output text pane. The order of the output depends on Evaluation Options | Add Output at the Top.

To enter and evaluate single forms one at a time, it may be most convenient to enable Evaluation Options | Clear on Eval One, though that option would need to be disabled to enter multiple forms, if you want to evaluate them all at once or save them into a file for loading later.

Each time an evaluation is done, the one or more forms that were evaluated are added to the History drop-down widget. They can be selected from there later for further editing and evaluation. If multiple forms are evaluated at once, then they are saved as a single entry in the history.

You can save a set of forms into a file with File | Save Lisp Code, then later load them back for further work with File | Load Lisp Code.

The code will be read in the gruff package that holds all gruff symbols, so even internal gruff symbols could be used without package qualifiers. The gruff package uses various other packages, and so their exported symbols may be used as well without package qualifiers; these packages include the common-lisp package, the cg package that contains code for windowing and graphics, and the triple-store package that contains the lisp client API.

The Lisp Evaluation Buttons

Evaluate One - Evaluates the lisp form that the text cursor is inside, if any, or else the next lisp form after the text cursor position, if any, or else the lisp form that's just before the text cursor.

Also moves the text cursor to the end of the form that was evaluated. This allows you to evaluate a series of forms one after the other by pressing this button repeatedly or using its keyboard shortcut, which is Alt-U. (Alt-Enter is an alternate shortcut.)

If Evaluation Options | Evaluate on Enter is enabled, then this button's behavior is performed automatically whenever you press the Enter key after a complete form (one whose parentheses are balanced).

Evaluate All - Evaluates all of the forms that are in the Input text pane, one after the other.

Clear Input - Removes all of the text from the Input text pane, to allow entering new forms from scratch. This avoids re-evaluating forms that you're done with. If Evaluation Options | Clear on Eval One is enabled, then this is done automatically whenever you evaluate a single form.

Back - Replaces the contents of the Input text pane with the previous form (or set of forms) that was saved into the History drop-down widget. The keyboard shortcut is Alt-J, which could be typed repeatedly until the form that you're looking for appears.

Forward - Replaces the contents of the Input text pane with the next form (or set of forms) that was saved into the History drop-down widget. The keyboard shortcut is Alt-K.

Reindent - Reindents the form that the text cursor is inside, according the nesting of parentheses. This may not often be needed, since lines are indented automatically as you enter them, though when editing a form in the middle of it, it may be useful. Seeing proper indentation helps to gauge whether parentheses are balanced as intended.

Clear Output - Removes all text from the Output text pane, which may be convenient when it is no longer of interest.

Copy Output - Copies the current contents of the Output text pane to the clipboard, for pasting into another application.

Scroll Output Up - Scrolls the Output text pane upward by about a half page. Using the keyboard shortcut (Alt-S) may be convenient for scrolling to see more of the output without moving the keyboard focus from the Input text pane where you will enter more text.

Scroll Output Down - Scrolls the Output text pane downward by about half a page.

Graph View - Selects the graph view. Using these buttons to select another view is the only way to get out of the lisp evaluation view, because the usual View menu with its commands for switching views is not present in this view. The usual commands for switching view would not be so handy in this view, where the keyboard focus is normally in a text-editing pane, and so the unshifted letter shortcuts from the View menu could not be used.

Query View - Selects the query view.

Table View - Selects the table view.

Embedding Gruff In a Web Page

Gruff can be embedded in any web page to use Gruff inside your own web site or web application. The file embedding.html in the Gruff installation folder provides a complete example of this. Display that file in a web browser to see the complete instructions for setting everything up. That same file serves as an example web page, with buttons at the bottom for embedding Gruff into that web page after doing the setup.

A Gruff feature allows a single launcher instance of Gruff to be running as a server and listening for requests from web browsers. It will launch a separate instance of Gruff for each web page that requests one, up to a specified limit. It can optionally use the launcher instance itself for one client, to minimize the number of Gruff executables that are running. Running Gruff as a server uses various command line options that are described under Running Gruff in a Web Browser.

Your web page needs to include an HTML iframe where Gruff will be placed, plus a link or button that asks a remote Gruff server to launch an instance of Gruff for the reader to use in that iframe. You will need to adapt the JavaScript code that's in embedding.html to make your link or button handle the reply from the Gruff server.

Simply embedding Gruff in an HTML iframe allows a reader to use Gruff by itself as usual inside your web page. A more advanced feature is that your web application can also send custom commands to Gruff. For example, your application could derive a set of triples that it wants Gruff to display, and then send those triples to Gruff. The code in embedding.html also demonstrates this abiliy. The complete documentation for sending commands to Gruff is at The HTTP Interface to Gruff.

Building an Ad Hoc Federation from Multiple Stores and Endpoints

Gruff allows you to build a temporary federation on the fly as you browse a series of AllegroGraph stores and/or SPARQL endpoints. At any time, the set of triples that you are currently browsing will consist of everything that's in the single AG store that you have open or the single endpoint to which you are connected, plus any triples that Gruff downloaded while you were browsing earlier stores and/or endpoints. You can continue to browse the triples that were downloaded earlier along with triples that you're fetching from the current store or endpoint.

You can set this up when using either File | Open Triple-Store or File | Connect to SPARQL Endpoint. To do so, check the check box that's labeled Retain the triples that were downloaded from the previous store or endpoint.

The check box for retaining triples will initially be selected if you selected it when opening the previous store or connecting to the previous endpoint. This allows quickly reopening recent stores or endpoints to continue building an ad hoc federation, without reselecting the option every time. For example, you can reselect recently-used stores and endpoints from the File menu whenever you want to resume fetching triples from particular sources. That process is also faster when Global Options | Miscellaneous | Confirm Closing Stores is disabled, by avoiding the dialog that it shows.

When retaining triples, the information from the previous store or endpoint that's displayed in Gruff's various views is not cleared. In the table view, for example, you can then still use View | Go Back to review nodes from the previous store. In particular, in the graph view you can continue building a single visual graph from multiple sources, where a node that exists in two or more of those sources can display links to nodes from different sources.

Similar borrowing of triples from an endpoint can be done by using SERVICE clauses in SPARQL queries in the query view. Though SELECT queries do not return actual triples, Gruff will use the query results to deduce some triples that must exist at the SPARQL endpoints that were accessed, and include those in the ad hoc federation that it is browsing. CONSTRUCT queries also add triples to the ad hoc federation that Gruff is browsing, without modifying the AllegroGraph store or SPARQL endpoint.

Usually Gruff will fetch triples only from the store or endpoint that you are currently browsing, and display only "leftover" triples from earlier sources. One exception to that is when using SERVICE clauses in SPARQL queries. The other exception is that if you click on an object in the righthand column in the table view to display that object's triples, and that table row's triple had been fetched from a SPARQL endpoint, and that endpoint is not the store or endpoint that you are currently browsing, then Gruff will fetch triples from BOTH that triple's endpoint AND from the store or endpoint that you're currently browsing (unless it has already fetched them from those sources, as usual). This is one way to continue browsing an earlier endpoint after switching to browsing another store or endpoint.

In the table view, any row that represents a triple that was fetched from a different store or endpoint than the one that you're currently browsing will show the name of that store or endpoint on the right. It will be shown in square brackets to differentiate it from the name of the triple's graph, which is shown in the same location whenever it's not the default graph.

If triples are fetched from multiple sources where the triples are in the default graphs of those sources and they have the same subject, predicate, and object, then by default Gruff will treat them as distinct triples. In the table view, for example, there will be a separate row for each one, with the source shown on the right except for the one that's from the current store or endpoint. This shows which sources contain each triple. Alternately, Gruff will merge these equivalent triples into a single one if you enable Global Options | Miscellaneous | Merge Retained Triples.

This procedure never creates triples in any stores. It only builds a temporary collection of triples in memory for browsing. If you would like to add triples to an AllegroGraph store from other stores and/or endpoints, a way to do that in Gruff would be to browse the source store or endpoint and use File | Export Displayed Data As | N-Triples or one of the other commands on that same child menu. Then open the destination store and use File | Load Triples | Load N-Triples (or one of its sibling commands) to load the file of saved triples into the AG store.

When browsing multiple AllegroGraph triple-stores, an alternative is to use File | Miscellaneous | Federate Recent Stores, or to select multiple stores in the same catalog when using File | Open Triple-Store. That will federate ALL of the triples from the multiple stores together, and then you can browse all of them as a single AG store, including doing user queries over the whole federation.

Reification Support in Gruff

Gruff has some functionality that is specific to reification, where a reifying triple can make a statement about a reified triple, as in "Alice believes that [ Bob likes Cindy ]". The most special feature represents a reifying triple in the graph view as a link line that extends from a node to the middle of the link line for the reified triple. And so there could be a regular link line for the triple "Bob likes Cindy", and then a reifying link line from Alice to the middle of the "Bob likes Cindy" link line. This is an intuitive representation of the reification. There are additional features in the graph view as well as the table view for navigating the relationships between reified and reifying triples.

This reification support in Gruff applies mainly to reifications that are made using triple-id reification, as the AllegroGraph documentation suggests, or a similar style that uses the graph part rather than the triple-id part. These reification styles are specific to AllegroGraph due to using these additional fields of each triple, which turn them into quints rather than simple triples. Standard RDF-style reification is handled by Gruff as well, though mostly only in the usual way that Gruff handles all triples rather than in the specialized ways that are described here. The AllegroGraph-specific styles require fewer triples, and so may be less cumbersome, though less standard.

In reification, one or more triples can make statements about a single triple by referring to that triple. In triple-id or graph-part reification, this is done by using the triple-id part or the graph part of the reified triple as the identifier for the triple itself. Then other triples can refer to that triple by using that triple-id or graph part as their subject or object parts. For this to work, the identifier must be used uniquely as the triple-id or graph part of only a single triple, so that the referenced triple is unambiguous. This is always the case with the triple-id field, because by definition every triple has a unique triple-id part. Graph parts, on the other hand, typically are not unique, but Gruff can still interpret the same kind of reification for any graph parts that are unique, when the store is designed that way.

A disadvantage of using the triple-id part for reification is that AllegroGraph assigns unpredictable triple-id values itself. So you can't create reifying triples until the reified triples are already in the store, and then you look up their triple-ids to use in the reifying triples. Graph-part reification avoids this problem because you can devise your own unique URIs or encoded IDs to use for the graph parts. Then you could specify the reified and reifying triples together in an nquads file to be loaded into a store at once, for example.

Reifying triples can use the triple-id or graph part of the reified triple as either their subject or object part, depending on the interpretation. In the "Alice believes that [ Bob likes Cindy ]" example of making a statement about a triple, the reifying triple would typically use its object part to refer to the reified triple. But in an example of attaching a property to a triple, as in "[ Dave flew to Fargo ] on November 24, 2015", the subject part might be used instead to refer to the reified triple. Gruff will handle either design in the same way.

Note that Gruff will look for and interpret graph-part reification only if Global Options | Miscellaneous | Display Graph-Part Reification is enabled, for efficiency reasons since most stores do not specify graph-part reification.

Browsing Reified Triples

Here are some features for browsing any reified triples that exist in a store:

When using graph-part reification instead of triple-id reification, the reifying triples can be seen by clicking on the name of the graph that's drawn at the right edge of the table row. The graph part is always displayed whenever it is not the default graph.

Creating Reified Triples

A reifying triple may be created in the table view by using Table View Value Column Navigation | Copy Triple ID to Clipboard. That command is on the table view's pop-up navigation menu (Shift-Right-Click or Shift-M). Then some time later use Table View Value Column Editing | Select a Different Node (selecting the Triple ID Node (for reification) option) to create a triple that reifies the triple that you had copied with the first command.

A reifying triple may be created in a more direct way in the Graph View by right-clicking a node and selecting Graph View Node | Create a Triple by Linking with Another Node, and then clicking on a link to reify the triple that that link represents.

The Menu Bar Commands

Most of the commands on the menu bar are applicable in some views but not others. To reduce clutter, some menus are removed from the menu bar when none of their commands are applicable in the current view, and some commands are removed from the remaining menus when they are not applicable. Other inapplicable commands may remain, though if you attempt to use one of them then a dialog will appear telling you the views in which that command is applicable.

To find the documentation for a particular menu command, show the menu and highlight the desired command, and then press the F1 key. (You can highlight a menu command by moving the mouse over it or by using the up and down arrow keys.) If Help | Use Web Browser for Menu Help is enabled, then this will visit the single web page for Gruff documentation and scroll down to the selected command; otherwise it will show only the entry for the selected command in a modal dialog.

The File Menu

These commands are for opening a triple-store to browse, or for creating a new store and loading triples into it.

File | New Triple-Store

Creates an AllegroGraph triple-store at a location that you specify. You can then populate the new triple-store by using triple-loading commands such as File | Load Triples | Load N-Triples, or by using Gruff's various editing commands to create individual triples.

A dialog will prompt you to specify the server machine, port, catalog, triple-store name, user name, and password as documented under File | Open Triple-Store. See that command for more information about those widgets. The main difference is that when creating a new triple-store you will need to type in a name for it rather than selecting an existing triple-store from a list.

After creating a triple-store with this command, you can re-open it in future Gruff sessions with File | Open Triple-Store, which is much faster than loading triples. To re-open the triple-store extra quickly, simply select it from the list of recently-used triple-stores that will appear on the File menu.

File | Open Triple-Store

Opens an existing AllegroGraph triple-store that you select. You can specify a triple-store that you created earlier with File | New Triple-Store followed by File | Load Triples | Load N-Triples, for example, or any other triple-store that you have access to.

A quicker alternative to this command, which is recommended when applicable, is to simply select the name of a triple-store from the list of recently-used triple-stores that appears at the bottom of the File menu.

You can also open a triple-store at startup time by specifying command line arguments. See Opening a Store with Command Line Arguments.

If there is an open triple-store already, you will first be asked to confirm that it's OK to close it, unless Global Options | Miscellaneous | Confirm Closing Stores is disabled. If there are unsaved changes to the triple-store, you will also be prompted to commit the changes.

Then a dialog will appear with a set of widgets to fill out to specify which triple-store to open and in what manner.

In the Server Machine widget, enter the name or IP address of the machine (or host) on which the AllegroGraph server is running. In the Port Number widget, enter the port at which to connect to the server. This should be the port number that is specified in the .cfg configuration file of the server. In the Scheme drop-down widget, select whether all messages to the server should use the HTTP or the HTTPS protocol; this must match the way that the server is configured.

If you are behind a firewall that uses an HTTP proxy, then you can first set up the proxy information with Global Options | Communications | HTTP Proxy. Then the machine name and port that you specify in this dialog should reflect how the proxy machine sees the AllegroGraph server machine.

The next two widgets are for a user name and a password. This could be the super user that's specified in the server's configuration file, or another user that was set up using AGWebView. If you have set up an anonymous user, then you can specify the anonymous user by entering nothing for the user name and password (though entering anonymous for the user name also works).

The Use HTTP Proxy check box will be available if you currently have a proxy setup in Global Options | Communications | HTTP Proxy. Check it if you are currently behind that proxy. Note that this check box needs to have the appropriate state before catalogs and triple-stores can be listed.

In the Catalog list widget, select the catalog that contains the desired triple-store, from a list of all of the catalogs that are on the server that's running on the specified server machine at the specified port. Once you have chosen the catalog, you will be able to select a triple-store from a list of the triple-stores that are in that catalog. (The lists of catalogs and triple-stores will not be available if the server does not allow anonymous access to the lists, in which case you will need to type in the names.)

Multiple triple-stores from the same catalog may be federated (to browse the combined triple-stores) by control-left-clicking to select multiple triple-stores in the list of triple-store names.

A pair of radio buttons let you specify whether the triple-store should be opened in Read-Only mode or in Read / Write mode. You will need to select Read / Write mode if you want to load more triples into the triple-store, or to create or modify any text search indexes, or to use Gruff's editing functionality for creating and deleting triples. Otherwise you could open the triple-store in Read-Only mode, which prevents you from inadvertently modifying the triple-store, and avoids an error when you don't have write permission for the triple-store.

Other radio buttons allow you to request reasoning. When using a remote server, it is much more efficient to request reasoning at this time than later with File | Miscellaneous | Apply RDFS++ Reasoner, because doing it now will add the reasoner on the server side whereas the separate command applies it on the client side. This server-side option requires using dedicated sessions, though, and so it will have no effect if Global Options | Communications | Use Dedicated Sessions is off.

There are check boxes for whether the triple-store be warmed up, which will copy as much internal data as possible into physical memory for fast access. Alternately, you can do this later with Global Options | Miscellaneous | Warm Up the Store.

If you were already browsing a triple-store or a SPARQL endpoint, then a check box will appear in the lower right corner of the dialog with the label Retain the triples that were downloaded from the previous store or endpoint. If you check this option, then Gruff will effectively be browsing a federation of everything that's in the triple-store that you're opening plus any triples that Gruff had downloaded as you browsed the previous triple-store or endpoint. See See [Building an Ad Hoc Federation from Multiple Stores and Endpoints] (#BuildinganAdHocFederationfromMultipleStoresandEndpoints).

Gruff normally communicates with the server using the HTTP or HTTPS protocol. But if the server is running on the same machine and Global Options | Communications | Use Direct Access When Possible is enabled, then direct access will be used instead.

A Note About Dedicated Session Ports and Firewalls

If an error occurs when opening a triple-store on a remote server, it may be because you are using a firewall that is not allowing the use of the arbitrary session port that AllegroGraph decides to use for the dedicated session for that open triple-store. The simplest way to handle that problem is to turn off Global Options | Communications | Use Dedicated Sessions so that the main server port is used for the open triple-store. Another way is to allow the use of a particular small range of session ports, as described here.

When you open a triple-store and specify the port that the AllegroGraph server is listening on (which is specified in the .cfg configuration file), the server normally will decide on a different port to be used only by the process that's used for that particular session. The server then tells the client what the session port is, and then further interaction uses that port for that session.

This can be a problem if you are behind a firewall that allows access only through certain ports that you have told it to allow, such as the one that you specified for the AllegroGraph server. If that's the problem, then a workaround is to define a small range of ports that the AllegroGraph server can use for sessions by adding a line such as this one to your .cfg configuration file for AllegroGraph: 

SessionPorts 8080-8083

And then tell your firewall to allow the use of all of the ports in that range.

A third alternative is to use an anonymous user when creating or opening the triple-store, if an anonymous user has been set up, because then session ports are never used.

On a related matter, if you are using port forwarding to access a remote server, then you will probably need to turn off both Global Options | Communications | Use Dedicated Sessions as well as Global Options | Communications | Use Direct Access When Possible.

File | Close Triple-Store

Closes the currently open triple-store, if there is one and you confirm when a dialog appears. Typically you don't need to use this command because opening another store will prompt you to close the current one, and exiting the standalone Gruff application will always close the currently open store. But you may need to use this command if you are about to regenerate the store that Gruff is now browsing, and you don't want to exit Gruff in the meantime, for example.

File | Connect to Gruff Demo Server

Opens an example triple-store on a public AllegroGraph server that's provided by Franz Inc. This allows you to try out Gruff after downloading it for free from https://allegrograph.com/products/gruff/ when you don't have an AllegroGraph server yourself. The single triple-store that's currently available is the extended actors database that features the many tangled links between actors and movies. (That dataset is also available from the Gruff web page.)

File | Connect to SPARQL Endpoint

This command lets you browse a SPARQL endpoint, regardless of which brand of SPARQL server it's running, instead of browsing an AllegroGraph store. Some Gruff functionality will not be available because it's not feasible to implement it for SPARQL endpoints, but most of the usual functionality will still be there. In particular, the functionality for finding paths between two nodes is not supported, except on Stardog servers because they offer a path-finding API. Some things may be slower, such as looking up types for coloring nodes in the graph view, but you can escape out of coloring the nodes if desired.

A monthly password is required for browsing SPARQL endpoints. Contact Franz at [email protected] for more information.

Invoking this command shows a dialog for specifying the endpoint to browse. Enter the complete URL of the endpoint in the top widget. If this is a public endpoint, then that is all that is needed. For a private endpoint, also enter the user name and password for that endpoint.

Be sure to specify the entire URL of the endpoint, including the HTTP:// or HTTPS:// scheme, which must match what the server expects.

If you were already browsing an AllegroGraph store or another SPARQL endpoint, then a check box will appear in the dialog with the label Retain the triples that were downloaded from the previous store or endpoint. If you check this option, then Gruff will effectively be browsing a federation of everything that's at the endpoint to which you're now connecting plus any triples that Gruff had downloaded as you browsed the previous store or endpoint. See [Building an Ad Hoc Federation from Multiple Stores and Endpoints] (#BuildinganAdHocFederationfromMultipleStoresandEndpoints).

Note that Gruff doesn't actually remain "connected" to the endpoint throughout a session. It connects only briefly whenever it needs to retrieve more data from the endpoint. And so there is no corresponding command to disonnect. Gruff does, however, try a test query when you use this command, so that it can tell you quickly whether it can successfully connect at the specified URL. If the test query exceeds Global Options | Timeouts | Endpoint-Testing Timeout, then Gruff will not proceed to set things up for browsing the endpoint.

When using a SPARQL endpoint, see the options on the Global Options | SPARQL Endpoints child menu. They generally correspond to other options that are used for AllegroGraph stores, but they're disabled by default to avoid undue slowness that may be nore of an issue with an endpoint than with an AllegroGraph store. In particular, Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels is off by default because it may slow down browsing to look up label properties with SPARQL queries, though the labels that are otherwise derived from URIs may not be meaningful, depending on the data. If label properties are important at a particular endpoint, then you can test turning that option on to see how much it slows down browsing.

If you are behind a firewall that uses an HTTP proxy, then you can first set up the proxy information with Global Options | Communications | HTTP Proxy.

The dialog initially suggests the DBPedia endpoint. If this endpoint is down for maintenance or not reasonably responsive, here are the three different DBPedia endpoint URLs that we're aware of, where usually at least one of them is working well when the others may not be: 

http://live.dbpedia.org/sparql  
http://dbpedia.org/sparql  
http://dbpedia-live.openlinksw.com/sparql

When DBPedia is being browsed, there is an Example button in the query view that pastes one of several example queries into the query text widget, which you can then run. The graphical query view also has an Example button for DBPedia. Some of the commands on the Display menu also suggest initial values to use.

Whenever an AllegroGraph server is running, Gruff can alternately connect to it as a SPARQL endpoint rather than directly as usual, though as usual with endpoints some Gruff functionality such as path-finding will not be available. Here is how you would specify the endpoint for an AllegroGraph triple-store named "foo" that's on a server machine named myserver at port 10088, either in the main catalog or in a catalog named bar: 

http://myserver:10088/repositories/foo  
http://myserver:10088/catalogs/bar/repositories/foo

Some commands are not available with SPARQL endpoints, either because there's no way to do them using only SPARQL queries (which is the only interface to a SPARQL endpoint), or because they modify the database (which Gruff generally does not support with SPARQL endpoints even though some servers may allow that), or because they are specific to AllegroGraph in some other way. Here is the list of commands that are not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store:

The two path-finding commands on the Link menu ARE available at Stardog endpoints, because they provide an extended SPARQL API for path-finding that's similar to AllegroGraph's path-finding API, and so Gruff uses that.

Here are a few other smaller things that can't be done when browsing a SPARQL endpoint:

File | Commit

Finalizes any changes that you have made to the store, generally by adding, editing, and deleting triples in the table view and/or the graph view.

If there are uncommitted changes when you attempt to exit Gruff, then by default you will be prompted for whether a commit should be done first. So you could rely on that prompt rather than using this command, though that prompt will not appear if you have turned off Edit | Prompt for Commit on Exit, and no automatic commit will be done.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Roll Back and Refresh

When you're browsing an AllegroGraph store (rather than a SPARQL endpoint), this command backs out any triple additions and deletions that you've done since your most recent commit, thereby rolling back to that commit. Also updates the currently open store to reflect any commits that others have done since you last opened, committed, or rolled back.

This command may be useful for discarding any mistaken edits that you've made to the store. If you're only browsing the store, rather than modifying it by creating and deleting triples, then this command is useful only for synchronizing to the commits that others have made to the same store.

If any triples that are currently displayed were deleted by updating to the commits of others, then Gruff may be left displaying nonexistent triples, with unpredictable results. If this happens, then you may want to use File | Miscellaneous | Clear and Uncache Everything.

If you're browsing a SPARQL endpoint, then this command just uncaches information so that if the data at the SPARQL endpoint has changed since you connected to it, then further browsing in Gruff will reflect those changes rather than using out-of-date cached information.

File | Load Triples | Load N-Triples

Loads a standard N-Triples file into the current triple-store, by calling the AllegroGraph function load-ntriples. A dialog will first ask whether the triples are in a file or on the web. If in a file, it will show the file-browsing dialog for selecting the file. The file dialog will initially display only files whose file type is ntriples, but any file whose contents are in N-Triples format may be specified. If loading from the web instead, then a simple string-entry dialog is shown for typing in or pasting the URI of the web page that holds the triples.

A further dialog will ask for an optional graph in which to place the triples. In AllegrGraph, every "triple" actually has a fourth component known as a graph, which can be used to group related triples together by giving them the same graph component. By default, Gruff will load all triples into the store's default graph. If you do specify a graph name and you may later want to refer to the graph name in the text of a SPARQL query, then the graph name should be a full IRI such as http://foo.com/graph-one. Other commands that make use of multiple graphs in a store include Display | Display Triples of One Graph and View | Browse a Single Graph.

You generally need to load triples only a single time. Thereafter you can simply re-open the store into which you've already loaded the triples, which is much faster than reloading triples into another new store. Note that loading the same set of triples again into the same store would create duplicate triples in the store.

This command automatically does a commit at the end.

If an error occurs while loading n-triples, see Global Options | Miscellaneous | Relax Syntax When Loading Triples and Global Options | Miscellaneous | Continue on Error When Loading Triples. Also see Global Options | Miscellaneous | Commit Frequency When Loading Triples.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store. The same is true for the other commands on the "File | Load Triples" menu as well.

File | Load Triples | Load N-Quads

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the N-Quads format.

If an error occurs while loading n-quads, see Global Options | Miscellaneous | Relax Syntax When Loading Triples and Global Options | Miscellaneous | Continue on Error When Loading Triples.

File | Load Triples | Load N-Quads Extended

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the N-Quads Extended format.

This command will load triples only if triple attributes have been specified for the triple-store. Gruff does not have a facility for doing that at this time.

File | Load Triples | Load RDF/XML

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the RDF / XML format.

See also File | Load Triples | Base URI for RDF/XML and Turtle.

File | Load Triples | Load TriX

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the TriX format.

File | Load Triples | Load TriG

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the TriG format.

File | Load Triples | Load Turtle

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the Turtle format.

See also File | Load Triples | Base URI for RDF/XML and Turtle.

File | Load Triples | Load JSON-LD

Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the JSON-LD format.

When a node's value is a JSON literal, Gruff will often display the value as multi-line indented text for better readability. This is true in node boxes in the graph view, in cells of the table view, and in the tooltip that appears in the outline view when hovering over the value.

File | Load Triples | Base URI for RDF/XML and Turtle

This is the base URI that will be passed to AllegroGraph whenever loading triples from RDF/XML files with File | Load Triples | Load RDF/XML or turtle files with File | Load Triples | Load Turtle.

File | Extract Microformat/RDFa Data from Web Page

Extracts triples from a specified web page that uses the RDFa specification to embed triples that correspond to human-readable content, and then adds the extracted triples to the store that is being browsed.

If Global Options | Communications | Use any23.org for RDFa is enabled, then this command can alternately extract microdata, if that is what the web page contains. If that option is NOT enabled, then some types of triples can be excluded from the collection by using Global Options | Communications | Ignored RDFa Relationships to select particular HTML relationship attributes to skip.

If you are behind a firewall that uses an HTTP proxy, then you can first set up the proxy information with Global Options | Communications | HTTP Proxy.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Miscellaneous | Prune Saved Files

When running Gruff from AGWebView (or otherwise in secure mode), Gruff will be running on an AllegroGraph server machine. For security reasons in that case, you do not have general access to the server's file system. Because of that, when Gruff asks you where to save a new file it will simply ask for a file name and then create the file in a single directory that is allocated for you on the server machine.

This command allows you delete selected files from your single directory on the server machine, so that files do not accumulate there indefinitely. First it will ask which category of files to select from, and then list all of the files for that category. You can select any subset of those files, which will be deleted if you confirm when prompted.

File | Miscellaneous | Display a Saved File

When running Gruff from AGWebView (or otherwise in secure mode), this command lets you select one of the files that have been saved into your single directory on the server, and then Gruff will display that file in a new browser tab.

This may be useful for saving the file on the client machine where you are viewing Gruff, by using the browser's usual Save File As command (on the right-button pop-up menu). Or you could use the browser's commands for selecting all text and copying it to the clipboard, as a workaround for the JavaScript restrictions on accessing the clipboard programmatically, such as with Gruff commands.

If you select from the Layout Images category, then Gruff will display the saved image in a new tab. This allows seeing layout images that you saved in earlier Gruff sessions. And even an image could be copied to the clipboard with the browser's usual copy command, and then perhaps pasted into an email message.

File | Miscellaneous | Federate Recent Stores

Lets you browse a federation of recently-opened stores. A federation is simply a temporary collection of all of the triples in a set of stores.

A dialog will be shown that lists the stores that have been opened most recently in this or earlier Gruff sessions. This is the list of recent stores that appears on the File menu. If you select two or more stores from this list, then Gruff will browse a federation of those stores. The store name that appears in the title bar will be a concatenation of the individual store names, as a reminder that you are now browsing a federation of those stores.

If you save the state of any views such as a layout or query, then those saved states will be available for reloading in the current and future Gruff sessions whenever you federate the same set of stores.

If all of the selected stores had been opened remotely, and on the same server, then the federation will be done on the server, and otherwise the federation will be done on the client. Federating on the server is more efficient, and allows queries to be done on the federation.

If all of the stores to federate are in the same catalog, then an alternative to this command is to simply specify multiple stores when asked for the store to open in File | Open Triple-Store. You can select multiple triple-stores in the store-opening dialog by control-clicking the store names in the list of stores for the currently selected catalog.

File | Miscellaneous | Apply RDFS++ Reasoner

Adds reasoning capability to the store that is currently being browsed by encapsulating it with a reasoning store, and then begins browsing the reasoning store. This causes queries to sometimes return additional triples that are implied by the triples that exist explicitly in the store.

After invoking this command, the reasoner will include reasoning about owl:hasValue, owl:someValuesFrom, and owl:allValuesFrom whenever Global Options | Miscellaneous | Reasoner Enables Restriction Reasoning is enabled.

This command applies reasoning on the client side after a triple-store has already been opened. It's more efficient to select RDFS++ Reasoning on the File | Open Triple-Store dialog, because that applies reasoning on the server side. That alternative requires using dedicated sessions, though, and so it will have no effect if Global Options | Communications | Use Dedicated Sessions is off.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Miscellaneous | Clear and Uncache Everything

This command is needed only in a couple of uncommon situations where Gruff does not realize that information that it has displayed or cached is not up-to-date. Using this command will clear everything from the display and from Gruff's internal cache in order to start fresh from the current state of the store.

One situation where this command may be needed is if you use File | Roll Back and Refresh to synchronize with any commits that others have done, and this leaves Gruff still displaying some triples that others have deleted. The only indication that this has happened may be unexpected Gruff behavior.

Another situation is if you are using Gruff in a development lisp rather than using the standalone Gruff application. If you open a different store in the development lisp or add and delete triples there, then Gruff will not be aware of those changes. Using this command is equivalent to calling the lisp function uncache-for-new-triple-store, as needed after opening a different store in the development lisp. This command could also be used after only adding and deleting triples in the development lisp, though it may be preferable to instead call uncache-for-modified-triple-store because that function uncaches less information and does not clear everything from the display.

File | Miscellaneous | Load and Evaluate Lisp Code

Evaluates the Common Lisp code that's in a file that you select. This allows you to control Gruff programmatically. The code can contain calls to Gruff functions that are documented in the section The Programmatic Lisp API to Gruff, as well as calls to functions in the AllegroGraph lisp client that Gruff generally uses to talk to the AllegroGraph server. Franz also could potentially send code for you to load for debugging purposes.

See also View | Lisp Evaluation View, where you can enter, edit, evaluate, and save lisp code interactively.

By convention, the file type would be one of cl, lisp, or lsp, though it doesn't have to be. The file selection dialog will initially show only those types of files, though.

The File Menu's List of Recent Stores to Re-Open

This middle section of the File menu lists the stores that have most recently been opened in Gruff. Selecting one of them is a quicker way to open a recently-used store. These menu items will begin with a numeral that you can type as a shortcut once you have shown the File menu, followed by the name and so on of the store.

File | Save Layout State

This command appears only in The Graph View.

Saves the current state of the visual graph, including node positions, to a file that you select with the file dialog. This file can be loaded any time in the future with File | Load Layout State to redisplay the saved state and allow further browsing from there. By default, the saved file's extension will be layout, though this is not required.

A layout file could be passed to a colleague who has the same triple-store, to allow them to view a visual graph that you prepared.

In the lisp interface, the corresponding function is save-layout.

File | Load Layout State

This command appears only in The Graph View.

Loads a visual graph that was saved at some earlier time with File | Save Layout State. The state will be redisplayed and allow further browsing from the point at which it was saved.

See The Dialog for Selecting Queries and Layouts to Load.

When using this command, you should first have the same triple-store open as when you saved the layout, or possibly another store that contains most or all of the triples that are in the saved layout. If any of the saved triples are not found in the currently-open store, then those particular triples will simply not be displayed in the visual graph.

When in the graph view, a bottom section of the View menu will list the layout files that were most recently saved or loaded for the currently open store. Selecting one of these choices is a quicker way to load a recently-used layout than using this command to select from a larger list of all layout files.

In the lisp interface, the corresponding function is load-layout.

The Dialog for Selecting Queries and Layouts to Load

When loading a query, graphical query, or layout that you have saved, a dialog will appear that allows you to select a query or layout from the current folder for saved queries and layouts. This dialog provides a variety of options for filtering the set of files that are listed, to make it easier to find the file of interest. The dialog is used by the commands File | Load Layout State, File | Load Query Text, and File | Load Graphical Query.

If Global Options | Miscellaneous | Filter Loadable Queries and Layouts has been turned off, then this special dialog will not appear, and instead the standard file selection dialog will appear, as in earlier versions of Gruff.

If you haven't yet specified the current folder for saved queries and layouts when you use a load command for a particular triple-store, then the standard folder selection dialog will prompt you for the folder before this dialog for selecting a query or layout will appear. The save and load dialogs have a button for changing this folder at any time. This default folder for each triple-store will be saved in the options file, so that you can quickly find saved files in the future.

On the left side of the dialog is a list of the files in the current folder that pass the filters that are currently specified in the filter section in the lower right of the dialog. You can change the filter options at any time to update the set of files that are listed.

When a left-pointing blue triangle appears to the left of a name in the list, that means that that file was created before the Gruff enhancement that writes descriptive information into each file, especially which triple-store the query or layout works with. If you load the file and then save it to the same place, then it will contain the new information that may help in finding it in the future.

The upper right of the dialog displays information about the file that is currently selected in the list, to help you determine whether the selected file is the one that you want. This information includes the author of the file, when the file was last written (either created or updated), and a potentially long description to fully explain the query or layout. Below the description are other attributes that are specific to the particular Gruff view, such as query length, number of results, and execution time for the query view.

When it's clear that you no longer want a file that's selected, you can press the Delete button to delete the file.

Once you have found the desired file, load it by pressing the OK button or double-clicking it in the list.

Here are descriptions of the various filter options in the lower right area of the dialog:

Words In the Info: If you enter a set of words (or parts of words) here separated by spaces, then a query or layout will appear in the list only if either (1) each of the words is contained in either its name (as seen in the list on the left) or its longer description, or (2) the file is an older one from before descriptions were saved, and the "Include Older Files from Unknown Triple-Stores" option is selected.

Max Days Old: A query or layout will appear in the list only if the file was most recently written (created or updated) no more than this many days ago. If this widget is blank or zero, then there is no limit.

Author: A query or layout will appear in the list only if either (1) "All Authors" is selected, (2) the selected author is the one that was specified when saving the file, or (3) the file is an older one from before authors were saved, and the "Include Older Files from Unknown Triple-Stores" option is selected.

Catalog: This is the catalog of the currently selected triple-store. Select a different catalog if you want to select a triple-store from it.

Triple-Store: A file will be listed only if either (1) "All Triple-Stores" is selected here, (2) the file was saved while browsing the selected triple-store in Gruff, or (3) the file was saved in a triple-store whose name at the time is in the Global Options | Miscellaneous | Borrow Queries and Layouts list for the current triple-store. When you use this dialog for the first time after opening a store, this widget will initially be set to that store, for selecting files that were created for that store as usual.

Note that the choices in the catalog and triple-store widgets are not all of the stores that are on the server. Instead they are all of the store names that were found in query or layout files in the current folder and for the current Gruff view (query, graphical query, or layout files). So if the folder still contains files that were created in a store that was later renamed or deleted, then they will still show up as choices when you select that old store name or "All Triple-Stores", or you use Global Options | Miscellaneous | Borrow Queries and Layouts. Similarly, the author choices are the ones that were found for that Gruff view in the current folder.

Include Older Files from Unknown Triple-Stores: When this is checked, query and layout files that existed before the enhancement to save the triple-store that they are from are included in the list. These files are marked with blue left-pointing triangles on the left. They are included even when browsing only the files for a single store because it is not known what stores they are from. If you update all of the files that are still of interest by loading them and then saving them to the same place, then you could uncheck this option to remove the remaining older files from the list.

Include Descendent Folders: When checked, the list will include files in child folders and grandchild folders (and so on) of the current folder. Otherwise only files that are in the current folder itself are listed.

File | Save Layout as Pixmap

This command appears only in The Graph View.

Creates a pixmap from the image of the current graph and saves it to a pathname that you select in the file selection dialog. The pixmap will automatically encompass all of the displayed nodes in the visual graph, even if they are scrolled out of view, adding a bit of margin around them all. The margin is equal to Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing. A png file will be saved by default, though if you specify a path that has the type jpg or bmp then that format will be saved instead.

The legend will be included in the saved image if Visual Graph Options | Layout Options | Include Legend in Saved Pixmaps is enabled, and not otherwise.

If Visual Graph Options | Layout Options | Show Saved Layout Pixmaps is enabled, then a third-party program will be invoked to display the pixmap file that was created.

An error dialog may appear if the graph image is too large to handle, because a single pixmap must be created in memory before saving it to a file.

In the lisp interface, the corresponding function is save-layout-as-pixmap.

File | Display Layout in New Browser Tab

Draws the current layout (with its legend) into a new tab of the web browser (when Gruff itself is running in the browser). This allows temporarily saving the images of different layouts into multiple browser tabs, and then comparing them quickly by switching between those tabs.

And there's another more subtle use for this command: If Gruff is being displayed in a web browser on a different machine than where the Gruff server lisp is running, then File | Save Layout as Pixmap will save an image file on the server machine. This alternate command allows saving the file on the client machine where the web browser is running instead. It's not possible to programmatically write a file on the client machine (in JavaScript) for security reasons, so this command just displays the current layout in a new browser tab. You could then right-click the image to get the browser's standard pop-up menu, and then use its Save Image As command to save the file on the client machine.

This command appears only in The Graph View, and only when Gruff is running in a web browser.

File | Save Table Object URI

This command appears only in The Table View.

Saves the URI of the object that is currently displayed in the Table View to a file that you select with the file dialog. This file can be loaded any time in the future with File | Load Table Object URI to redisplay the object in the table. By default, the saved file's extension will be uri, though this is not required.

File | Load Table Object URI

This command appears only in The Table View.

Loads a URI that was saved at some earlier time with File | Save Table Object URI. The object for that URI will be redisplayed in the table and allow further browsing from that object.

When using this command, you should first have the same triple-store open as when you saved the object, or possibly another store that contains triples for the same URI.

When in the table view, a bottom section of the View menu will list the table object URI files that were most recently saved or loaded for the currently open store. Selecting one of these choices is a quicker way to load a recently used object than using this command to select it with the file dialog.

File | Save Query Text

This command appears only in The Query View.

Saves the string that currently appears in the query text widget to a file that you select with the file dialog. This file can be loaded any time in the future with File | Load Query Text to reload the query text into the query text widget. By default, the saved file's extension will be query, though this is not required.

You could alternately use the Name Query button to quickly name a query for possibly revisiting it in the current session, without saving it to a file for use in future sessions.

File | Load Query Text

This command appears only in The Query View.

Loads query text that was saved at some earlier time with File | Save Query Text. The query text will be reloaded into the query string widget, allowing you to optionally edit the string and then to perform the query.

See The Dialog for Selecting Queries and Layouts to Load.

When using this command, you should first have the same triple-store open as when you saved the object, or possibly another store that contains triples to which the same query would apply.

When in the query view, a bottom section of the View menu will list the query text files that were most recently saved or loaded for the currently open store. Selecting one of these choices is a quicker way to load a recently used query text than using this command to select from a larger list of all query files.

File | Save Graphical Query

This command appears only in The Graphical Query View.

Saves the current state of the graphical query, including node and grouper positions, to a file that you select with the file dialog. This file can be loaded any time in the future with File | Load Graphical Query to redisplay the saved state. By default, the saved file's extension will be gq, though this is not required.

File | Load Graphical Query

This command appears only in The Graphical Query View.

Loads a graphical query that was saved at some earlier time with File | Save Graphical Query. The state will be redisplayed and allow further editing of the query from the point at which it was saved.

See The Dialog for Selecting Queries and Layouts to Load.

When using this command, you should first have the same triple-store open as when you saved the query, or possibly another store that contains most or all of the objects that are in the saved query.

When in the graphical query view, a bottom section of the View menu will list the graphical query files that were most recently saved or loaded for the currently open store. Selecting one of these choices is a quicker way to load a recently-used query than using this command to select from a larger list of all graphical queries.

File | Save Lisp Code

This command appears only in The Lisp Evaluation View.

Saves the Common Lisp source code that's now in the Input text pane to a file that you select. You could later load this code back into the lisp evaluation view for further editing and testing by using File | Load Lisp Code, or you could simply load and evaluate the whole file with File | Miscellaneous | Load and Evaluate Lisp Code.

File | Load Lisp Code

This command appears only in The Lisp Evaluation View.

Loads Common Lisp source code from a file that you select into the Input text pane. You can then evaluate the code, perhaps after editing it. Typically this file will be one that you created with File | Save Lisp Code after editing the code in the lisp evaluation view.

File | Export Displayed Data As | N-Triples

Writes the triples that are currently displayed in the currently selected view to a file that you specify. The file will be written in N-Triples format. This is typically useful for exporting the data to some other program that knows how to read N-Triples format.

In the graph view, triples will be written for all of the displayed nodes and links. In the table view, all of the triples that have the currently displayed node as their subject or object will be written (even if they are not all displayed in the table).

The query view will export triples that are derived from query results, since the results of a SELECT query are not triples. These are the same triples that are used to generate a visual graph with the Create Visual Graph button (see Generating Visual Graphs from Query Results). See also Query Options | Include More Triples in Visual Graphs for the two different ways that triples are derived from query results.

File | Export Displayed Data As | N-Quads

This is like File | Export Displayed Data As | N-Triples except that the file format will be N-Quads.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Export Displayed Data As | N-Quads Extended

This is like File | Export Displayed Data As | N-Triples except that the file format will be N-Quads Extended.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Export Displayed Data As | RDF/XML

This is like File | Export Displayed Data As | N-Triples except that the file format will be RDF/XML.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Export Displayed Data As | TriX

This is like File | Export Displayed Data As | N-Triples except that the file format will be TriX.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Export Displayed Data As | TriG

This is like File | Export Displayed Data As | N-Triples except that the file format will be TriG.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Export Displayed Data As | Turtle

This is like File | Export Displayed Data As | N-Triples except that the file format will be Turtle.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

File | Export Displayed Data As | Node URIs

Writes out all of the subject and object nodes that are currently displayed in the currently selected view to a file that you specify. Each node is written as a simple URI, one to a line.

In the graph view, if any nodes are currently highlighted (see Select | Toggle Highlighting of the Selected Node or Link), then only those nodes will be written. Otherwise all displayed nodes will be written.

File | Export Displayed Data As | GML (Graph Modeling Language)

Writes the triples that are currently displayed in the selected Gruff view to a file in GML (Graph Modeling Language) format. Additional information about how to draw the nodes and links is also written to the file. The GML file could then be loaded into various other software tools that can handle GML, such as Cytoscape and Gephi. This allows exploring the layout algorithms and stylistic options of other software, using triples that you gathered using Gruff.

A dialog is first shown that lets you specify several options for how the data is written. The rest of this entry describes the various widgets on the dialog.

The File widget is where you enter the name of the GML file to write. The default value that is initially shown includes the .gml file type, but you can exclude the file type to default it to .gml. The file will be written into the folder (directory) that's shown above this widget.

The Browse button lets you select a directory and filename using the system's file selection dialog. This is needed if you want to write the file into a different folder (directory) than the one that's shown above the File widget. You may also want to use this button to help avoid specifying a file that already exists.

If Allow Overwrite is checked and you specify a file that already exists, then the operation will be canceled to avoid overwriting the existing file. If it is not checked, then the existing file will be replaced. When using the Browse button, the file selection dialog will also warn if you specify an existing file while this option is checked.

Node Labels and Edge Labels specify what sort of labels are written to the GML file. The none choice will write no labels at all (though you could tell other tools later not to display labels even if they were written to the GML file). The label choice will write the labels that Gruff is currently displaying for the nodes and links, as derived according to various user options. For nodes by default this may include labels that are supplied by label predicates. The short choice will write out values that are always derived from the URIs and literal values of the nodes, where the namespace portion of URIs will be removed and only the value portion of typed and language literals is included.

Node Width & Height specify the size at which to draw nodes, though the actual sizes that will be drawn depends on how the software that renders the GML file interprets the values.

If Multiply by Gruff Nodes Sizes is checked, then the width and height that's written for a node will be the specified width and height multiplied by the pixel width and height of the node picture for the node, if the node has been displayed in the graph view. This option is probably suitable only when you plan to display the information in a tool that draw labels inside node boxes as Gruff does, since Gruff's nodes are sized to fit the labels. The Node Width & Height values typically should be much smaller when this option is checked. This option takes precedence over Multiply by Size Property when both are applicable.

Size Property allows using triples in the store to specify different sizes for nodes. Its value should be the URI of a predicate that supplies numeric values. Whenever an included node is the subject of a triple that has this predicate and a numeric object, then the base Node Size will be multiplied by that numeric object value to produce the size to write for that node. This will be done only when Multiply by Size Property is also checked. Node Size then lets you specify the general scale at which the varying property values are drawn. The Select button beside Size Property lets you select a predicate from pop-up menus in one of several ways, rather than typing or pasting the URI text.

Node Color specifies the default fill color to write out for each node. Its value should always be a six-digit hexadecimal number, where the first two digits are for red, the next two for green, and the last two for blue. So FF8800 would be an orangy color.

If Use Gruff Node Type Colors is checked, then the fill color that's written for any node that's been displayed in the graph view will be the color that Gruff used to indicate one of the node's types. (This does not apply when Visual Graph Options | Color Nodes for Node Type is not in effect.) This option takes precedence over Assign by Color Property when both are applicable.

Color Property allows using triples in the store to differentiate groups of nodes by color. Its value should be the URI of a predicate that supplies the same value for each node that should be drawn in the same color. Gruff will assign a random color to each unique value. This will be done only when Assign by Color Property is also checked. The Select button beside Color Property lets you select a predicate from pop-up menus in one of several ways.

Edge Weight specifies a number for the thickness or boldness with which to draw the link lines.

If Multiply by Link Widths is checked, then any predicate that has been displayed in the graph view will multiply the Edge Weight value by the line width that the graph view used for that predicate. By default this is always 2 for all predicates, but you could specify other widths for some predicates by right-clicking the line for the predicate in the graph view's legend and selecting the Set Line Width command.

Edge Color specifies the default color for drawing edge (link) lines. Its value is always a six-digit hexadecimal value as with Node Color.

If Use Gruff Link Colors is checked, then the edge color that's written for any predicate will be the one that was used in the graph view whenever that predicate has been displayed there.

Directedness specifies whether to export the same directedness that the triples have in the AllegroGraph store or SPARQL endpoint that Gruff is browsing. The directed choice means to use the same directedness, the reversed choice means to reverse all of the link directions, and the undirected choice means to not write any directedness at all to the GML file.

Node Attributes and Edge Attributes allow specifying further GML attributes that are not individually covered. The value should be alternating attribute names and values, with spaces to delimit them. The same values will be written for all nodes or edges. For example, you might enter type ellipse outlineWidth 3.

File | Exit

Exits Gruff if you confirm when asked in a dialog (or if you have turned off Global Options | Miscellaneous | Confirm Exit). Your current options are saved at this time as well.

The View Menu

These commands switch to different views that show information in different ways. The usual Copy and Paste commands at the bottom of the menu allow copying a URI from one view to another.

View | Graph View

Displays a set of nodes and links that are automatically arranged to make the relationships readable. The main pane that displays a visual graph is known as the node pane, and the optional smaller panes at the left are the legend pane and the overview pane.

Many of the commands on the menu bar apply primarily to this view, and so the documentation for this view consists of the entries for the individual menu bar commands (in this section of the document for The Menu Bar Commands).

This view is documented in the main section called The Graph View.

View | Optional Graph View Panes | Show Time Bar

Toggles whether the time bar is displayed at the bottom of the graph view. The time bar is used to compare nodes that have date (or date-time) properties, such as events that happen on particular days. The time bar displays a row of markers in chronological order for the date properties of all of the nodes that are currently displayed, which you can examine to see how nodes follow each other in time. It also offers a larger chart that more clearly displays how nodes overlap in time.

The time bar also allows you to temporarily filter some nodes from the visual graph when their date properties do not lie within a specified range. As you interactively change the boundaries of the time filter range, different sets of nodes will appear in the visual graph. This lets you see how various nodes in the triple-store come into play over time.

This is the full time bar reference. Also see The Time Bar in the Graph View for a mini-tutorial and where to find an example set of triples that include date properties.

Showing the Time Bar: The time bar is not shown by default, so you need to use this command to show it if your triple-store has nodes with date properties. It will appear at the bottom of the graph view, whenever the graph view is selected.

Setting Up the Time Bar: To use the time bar in a particular triple-store, you first need to do two things: (1) Specify the predicates that supply date or date-time properties in that triple-store, and (2) display some triples that use those predicates. For the first step, see the options Visual Graph Options | Time Bar | Start Time Predicate (along with End Time Predicate) and Visual Graph Options | Time Bar | Momentary Time Predicates. (If you try to use the time bar without first completing these steps, then a dialog will tell you what you need to do next.)

Valid Date Values: The time bar will use any triple where the predicate is one of the specified ones and the object is either a typed date or date-time literal (and not a time literal) or a simple literal string that can be parsed as a date or date-time according to certain standard formats, including W3C (for example 2017-06-30 or 2017-06-30T15:16:17-08:00). Other triples will simply be ignored.

Time Ranges: The time bar actually represents TWO separate time ranges. This may be somewhat confusing, so it's important to remember that the two ranges are the time bar range and the time filter range. The time bar range is represented by the entire length of the time bar, while the time filter range is represented by the portion that's between the two yellow-orange rectangles on the upper row, which are the time filter sliders. The sliders can be dragged inward to make the time filter range smaller than the time bar range, but the time filter range never extends outside of the time bar range. The time bar range covers the entire time period that you are currently looking at, while the time filter range determines which nodes are currently hidden (temporarily removed) in the visual graph.

Time Range Boundaries: The boundaries of the two time ranges are indicated by the dates that are displayed in the lower row of the time bar in the format 2017-06-30. The two gray outer dates are the time bar range, while the two inner black dates are the time filter range, with the start dates on the left and the end dates on the right.

Initial Time Ranges: Once you have displayed the time bar and some triples that use your specified date predicates, the time bar range and time filter range will both initially be set to surround all of the date properties of the displayed nodes. Thereafter, the time bar range will be updated automatically as needed to continue to surround all date properties as long as the option Visual Graph Options | Time Bar | Update Time Bar Range Automatically is enabled (as it is by default).

Time Bar Gadgets: The time bar contains a variety of gadgets that are used for adjusting the boundaries of the time ranges. Each one is described further below. Typically you may not need to adjust the time bar range yourself, and you will instead use the various gadgets on the time bar to adjust the time filter range.

Date Property Markers: All of the date properties that lie within the time bar range are indicated by short vertical lines in the upper row of the time bar. These lines are known as date property markers. If there is a selected node in the visual graph then its markers will be red, and the markers of the node that's under the mouse in the visual graph (if any) plus any highlighted nodes will be blue. This lets you see how the dates of two nodes compare, for example, by selecting one node and moving the mouse over another. If you move the mouse over a date property marker, then its node will be highlighted in the visual graph (and the overview pane at the lower left), and all of the markers for that node will be highlighted in the time bar. And if the option Visual Graph Options | Time Bar | Show Tooltips for Date Property Markers is enabled, as it is by default, then a tooltip will also appear just above the time bar, displaying the label of the node that has that date property along with the property name and value. By moving the mouse cursor horizontally across the date property markers, you can see how nodes follow each other and overlap in time. You can also left-click a date property marker to select its node in the visual graph, or control-left-click it to scroll it into view in the graph pane. (To jump ahead a bit, a larger chart displays how date properties overlap more completely when you press the middle blue button, whose icon is a square.)

Adjusting the Time Filter Range: You can adjust the time filter range to temporarily remove nodes from the visual graph. Whenever a node has date properties and all of those date properties lie outside of the time filter range, that node will be removed from the visual graph while the time bar is present. And if the option Visual Graph Options | Time Bar | Hide Orphans of Time Filtering is enabled, then any nodes that become orphaned (left with no linked nodes) by time filtering will also be temporarily removed from the visual graph.

The Time Filter Sliders: You can left-click down on either of the yellow-orange time filter sliders in the upper row of the time bar and drag it horizontally to adjust one end of the time filter range. As you do that, nodes will appear and disappear in the visual graph as they come into play (or out of play) over time. Alternately, you can click and drag anywhere else in the upper row of time bar to drag both sliders together.

You can also shift-left-click-and-drag in the upper row to select a new time filter range, or control-left-clck-and-drag to select a new time bar range. In the first case, a yellow-orange bar will be drawn as you drag over the date property markers that will remain in the time filter range (where the time filter sliders will move to surround the range over which you dragged). In the second case, a blue bar will be drawn over the date property markers that will be stretched apart to fill the entire time bar.

The < and > (Less Than and Greater Than) Buttons: The buttons whose icons are the < and > symbols are another way to adjust the time filter range. Each click on these buttons moves one end of the range in a single jump, which may be faster than dragging the filter sliders. The amount by which each click changes the range is controlled by the option Visual Graph Options | Time Bar | Range Expansion Percentage. Control-clicking these buttons will adjust the time bar range rather than the time filter range.

The [] (Brackets) Button: This button sets the time bar range to surround all of the date properties of all of the nodes that are currently displayed. "Currently displayed" means all of the nodes that are visible in the visual graph plus all of the nodes that are temporarily removed by time filtering. This is also done automatically whenever Gruff commands add nodes to (or remove nodes from) the visual graph as long as the option Visual Graph Options | Time Bar | Update Time Bar Range Automatically is enabled (as it is by default), so you likely won't need this button if you leave that option on and do not adjust the time bar range yourself.

The || (Vertical Bars) Button: This button sets the time bar range to surround all of the date properties of just the nodes that are visible in the visual graph (ignoring ones that have been temporarily removed by time filtering).

The >< (Inward) Button: This button narrows the time bar range to be what the time filter range is. Another way to think of this is that it stretches the current time filter range out to span the entire time bar. Narrowing the time bar range spreads the date property markers farther apart so that it's easier to pinpoint each one with the mouse.

The <> (Outward) Button: This button expands the time filter range to be what the time bar range is. This is the same as dragging both of the time filter sliders all the way outward, but faster.

The Time Chart (Square Icon) Button: This button in the middle displays a large chart that takes the place of the visual graph. The chart contains one row for each node that has date properties, displaying those dates along a horizontal time axis alongside the date properties of other nodes. This shows most clearly how the nodes overlap in time. The chart goes away along with the time bar when you toggle the time bar off, or when you once again press the chart button (which will be purple in the meantime as a reminder). The chart includes only the displayed nodes that are not currently hidden by time filtering, and it responds dynamically as you change the time filter range. Radio buttons at the lower left allow sorting the node rows either alphabetically by node labels, or timewise by the earliest or latest date property of each node or the mean of all of the date values, or by the "middle" of the date values (which is the mean of the minimum and maximum values). A different icon is displayed for each date property predicate, as noted in a legend at the bottom, and the icons will be larger for the node that's currently selected in the visual graph. Clicking a predicate in the legend will hide all of the icons for that predicate in the chart, and the chart rows will be re-sorted according to the predicates that are still displayed. A horizontal line is drawn between the Visual Graph Options | Time Bar | Start Time Predicate and the Visual Graph Options | Time Bar | End Time Predicate (if those are used). When not all of the nodes fit into the chart at once, the chart can be scrolled by clicking down inside the chart body and dragging vertically, or by using the PageUp, PageDown, and up and down arrow keys.

Using the Date Text Fields to Adjust the Date Ranges: The text fields that display the boundary dates in the 2017-06-30 format can also be used to modify the boundary dates. This can be done either by clicking a field and editing the date text, or by clicking and dragging the date horizontally. In each case, the behavior differs with what part of the date you click on. A regular click to edit the date text always edits the entire date, but it initially selects one portion of it to allow you to quickly re-type just that portion of the date. Specifically, clicking on the year initially selects just the four digits of the year, allowing you to quickly type in a different year, whereas clicking on the month selects just the month digits, clicking the day selects the day digits, clicking the dash between the year and month selects all of the year and month digits, and clicking the dash between the month and the day selects all of the month and day digits. If you instead click down and drag horizontally, then clicking on the year will increment (or decrement) the date by one year for every several pixels that you drag the mouse, while clicking the month will increment by one month, and clicking the day will increment by one day. This allows incrementing the date either rapidly, moderately, or slowly.

Pulling a Time Filter Boundary Along with a Time Bar Boundary: A subtle point is that whenever you stretch a time bar boundary date outward by any means, if the corresponding time filter boundary date is at the same date then it will be pulled outward as well to remain the same as the time bar boundary date, and otherwise it will remain where it is.

Recovering: If you accidentally change a boundary date to an undesirable value and are not sure how to recover, you can always use View | Go Back to return to the previous state with its boundaries. Or click the [] button followed by the <> button to include all of the date properties of the displayed nodes in the time filter range, making all nodes visible once again in the visual graph.

View | Optional Graph View Panes | Show Time Chart

Toggles whether the time chart is displayed. The time chart will be displayed only if the time bar is present and has a date range; see View | Optional Graph View Panes | Show Time Bar.

This command does the same thing as the middle button on the time bar. But you can toggle the time chart more quickly with the keyboard shortcut for this command than by moving the mouse to the time bar button.

The time chart covers the visual graph, though the visual graph is actually still active and will reveal its current state once again when the time chart is toggled back off.

View | Optional Graph View Panes | Show Legend

Toggles whether a legend pane is shown in the graph view. The legend displays the meaning of each predicate line style and each node type background color that is currently represented in the graph layout. The predicate line styles are shown at the top, with the name of each predicate shown just above a sample line that shows the line color and dashing style that's used for that predicate. The node type colors are shown below the line styles, with a sample node drawn for each node type with the name of the type displayed in the sample node that shows the background color for that type.

If Visual Graph Options | Node and Link Flashing | Flash Legend Matches is enabled, then clicking an item in the legend will flash matching nodes or links in the graph layout to point them out. Pressing the spacebar when the legend pane has the keyboard focus will flash the matching nodes or links of the legend item that's already selected, if any. The matching nodes or links will also flash in the overview pane, which indicates where you need to scroll to in order to see the matches in the main graph pane (for example, you can simply click in the overview pane where it is flashing to scroll the matching nodes or links into view).

You can right-click an item in the legend to get a pop-up menu with a few commands for changing the link line style or node type background color for that legend item. These commands invoke particular options on the Visual Graph Options menu, which can alternately be used after left-clicking a legend item to select it. The menu for a node type also includes a command to display the properties of that type in the table view; you can also do this by double-clicking the item. Both menus include an item for copying the URI of that item to the clipboard; the URI could then be pasted into a query or into the node pane.

One command on the legend right-click menu that's not also available on the menu bar is Remove Matching Link Lines (or Nodes). This command will remove from the visual graph any nodes or link lines that match the selected legend item. These are the same nodes or links that flash when that legend item is selected. If Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal is active, then any remaining orphans will also be removed; this may be useful, for example, to remove all nodes for label properties after generating a visual graph for a DESCRIBE query, simply by right-clicking the legend item for the label property and selecting Remove Matching Link Lines.

The width of the legend pane can be modified by dragging the thick border between the legend and the graph layout.

The up and down arrow keys can be used to select legend items when the legend pane has been given the keyboard focus by clicking on it. The Escape key will de-select any selected legend item (as will clicking the legend background).

The TAB key will shift the keyboard focus between the legend pane and the node pane. A blue rectangle will be drawn just inside the legend pane's border when it has the keyboard focus.

The node types in the legend include ones whose background color you have set explicitly, along with others whose colors were chosen automatically. Colors are chosen automatically when there are displayed nodes that have no types for which you have explicitly set the color. Displayed nodes may have other types as well, and you can't set the colors for those types in the legend if they are not displayed there already. Instead, you would need to select the node in the graph layout and then use Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type. When you right-click a node type item in the legend, the pop-up menu will include a command for removing its mapping to a color if and only if you have explicitly specified a color for that type.

The Optional Graph View Panes child menu is present only in the graph view.

View | Optional Graph View Panes | Show Overview

Toggles whether an overview pane appears at the bottom of the legend. It will appear only if View | Optional Graph View Panes | Show Legend is also currently toggled on.

The overview pane displays the entire canvas that can be scrolled into the node pane, which shows how the currently-visible part of the displayed graph fits into the entire displayed graph. A red view box is drawn in the overview pane around the part of the visible graph that is currently scrolled into view in the node pane.

The overview pane also allows you to scroll the node pane. Left-clicking the overview pane will immediately scroll the node pane so that the clicked position is centered in the node pane. (And therefore the view box in the overview pane will be centered about the clicked position as well.) If you proceed to drag the mouse after clicking down, the node pane will scroll incrementally from the clicked position.

If you right click inside the view box, then the node pane will not immediately scroll, and will only scroll incrementally relative to the clicked position if you drag the mouse. This allows scrolling by a small amount more accurately, though that is probably done more easily by clicking and dragging in the node pane itself instead, or using the arrow keys in the node pane.

The node that is currently selected in the visual graph will be drawn in red in the overview pane. Control-left-clicking a node in the overview pane will select that node.

Stretching the legend wider by dragging the border on its right side will also make this overview pane larger (in both directions, so that it maintains the same aspect ratio as the canvas). Using View | Optional Graph View Panes | Pop Up Overview is a way to use a larger overview without making the whole legend wider.

The Optional Graph View Panes child menu is present only in the graph view.

View | Optional Graph View Panes | Pop Up Overview

Displays a floating overview window, which is a top-level window that is owned by the main Gruff window. This window can be positioned and sized arbitrarily, and will reappear wherever you last left it (during the current Gruff session).

By default, this window will disappear as soon as you click in its interior to scroll. But if View | Optional Graph View Panes | Retain Pop-Up Overview is toggled on, then it will stay around until you dismiss it. In either case, you can dismiss it with the Escape key if it has the keyboard focus (as indicated by a darker title bar).

The Optional Graph View Panes child menu is present only in the graph view.

View | Optional Graph View Panes | Retain Pop-Up Overview

Toggles whether using View | Optional Graph View Panes | Pop Up Overview will leave the pop-up overview window present once you've done a scroll with it.

X11 note: On GTK/X11 platforms (Linux and Mac OS X), this option probably will not work well, because most window managers will bring the main Gruff window in front of the overview window when you click on the main Gruff window. And an alt-tab would select the overview window rather than another application, and so on.

The Optional Graph View Panes child menu is present only in the graph view.

View | Table View

Displays a table of all of the properties of a particular node (meaning all of its triples). If there is a selected node in the view that you are in when you invoke this command, then a new table for that node will be generated; otherwise the table view is simply shown in its current state. If you accidentally generate a new table when you intended to simply switch back to the table view to continue viewing the node that had been displayed there, then use View | Go Back to return to the previous displayed node.

You can browse to linked nodes in the table view in the usual hyperlink way by clicking on nodes in the righthand column. You can also edit the triples of the displayed node, using commands on the right-click pop-up menu.

This view is documented in the main section called The Table View.

View | Outline View

Displays a set of linked nodes as an indented outline.

This command simply shows the outline view in its current state. To also create a new top-level outline item for the node that's selected in the view that you are switching from, use View | Add Selected Node to Outline instead.

This view is documented in the main section called The Outline View.

View | Query View

Displays a view where you can do a SPARQL or Prolog query and see the results in a table. Nodes in the results table can then be viewed in detail in the table view, or added as nodes to the graph view.

This view is documented in the main section called The Query View.

View | Graphical Query View

Displays a view where you can construct a query visually by arranging nodes and links into a diagram.

This view is documented in the main section called The Graphical Query View.

View | Lisp Evaluation View

Displays an advanced view where you can evaluate arbitrary Common Lisp expressions to control Gruff programmatically.

This view is documented in the main section called The Lisp Evaluation View.

View | Go Back

Returns to the previous state of the display. You may apply this command multiple times to return to earlier states up to a certain maximum.

In the graph view, this command returns to the previous state of the layout. In the table view it returns to the previously displayed node. In the query view it returns to the previous query. In the graphical query view it returns to the previous state of the query diagram.

In the graph view, this command allows you to freely experiment with adding nodes to the visual graph even when the new nodes turn out to be uninteresting or where too many nodes make the layout unwieldy. If that happens, you can use this command to return to the most recent desirable state.

View | Go Forward

Returns to the next state from which you returned to the current state with View | Go Back. You can apply this command multiple times until you return to the state from which you began going back.

An exception is that if you Go Back and then do an operation that changes the display (other than Go Back and Go Forward), then the Go Back stack is truncated and you cannot Go Forward from that state.

View | Copy

Extracts a URI or literal text from the selected object and posts it onto the clipboard. In the graph view this will be the URI of the selected node, if any, or else the URI of the selected link line, if any. In the table view (or the table in the query view), this will be the URI of the table cell that has the keyboard focus, which is indicated by a black border around the cell. You can use the arrow keys to move the focus to a different cell (or J, K, and L), and then use this command to copy the object in that cell. In the query text widget of the query view, this command will copy the selected text if any, and otherwise it will copy the "word" (such as a URI) that surrounds the text cursor.

A node that is copied in one view can then be pasted into any other view with View | Paste.

Sometimes a web browser may disallow the copy for security reasons, because the browser did not directly handle the copy keystroke itself. When this happens, a modal dialog will appear that asks you to type Control+C or Command+C again to allow the web browser copy the value directly from a text-editing widget in the dialog. This is then needed for posting to the system clipboard for pasting into other applications (rather than into other Gruff views).

Perhaps the most useful application of the copy and paste commands is to copy a node or table cell and then paste its URI into the query string widget of the query view. This allows entering a URI into query text without remembering or typing its long value.

If there is no selected node or link in the graph view or the graphical query view, but there are one or more highlighted nodes (see Select | Toggle Highlighting of the Selected Node or Link), then this command will copy all of the highlighted nodes. Then doing a paste into any view will paste all of the copied nodes there.

An advanced feature for editing reification: If a table cell node or graph view node represents a triple ID node, then that node will also be pushed onto an internal stack of all triple ID nodes that have been copied in the current Gruff session. You could later use Table View Value Column Editing | Select a Different Node (selecting the Triple ID Node (for reification) option) to create a triple that reifies the triple of the triple ID node that you had copied earlier. See Reification Support in Gruff.

View | Paste

Pastes the string that is on the clipboard into the selected view, if possible. If a node was copied in Gruff (typically in another view), then that node will always be pasted into the current view. Otherwise Gruff will find or make a node from whatever text happens to be on the clipboard and paste that node.

To paste the system clipboard value from another application when Gruff is running in a web browser, you will need to use the keyboard shortcut directly (Command+V on a Mac or Control+V elsewhere), rather than showing the View menu and then selecting its Paste command with the mouse or keyboard. This is due to security restrictions in JavaScript for the system clipboard.

In the query text widget of the query view, the text may get modified before pasting, generally converting it to n-triples format, and then converting it to a shorter namespace:fragment form if a namespace abbrevation is found for the first part of a URI (see Global Options | Namespace Abbreviations).

If multiple highlighted nodes were copied in the graph view or the graphical query view, then a paste in any view will paste all of the copied nodes there. In the graph view or graphical query view, this will display a node picture for each one. In the outline view it will add a top-level item for each node. In the query text widget of the query view it will paste each node onto a different line of text. In the table view it will display one node at a time, and then you could use View | Go Back to view the properties of each of the pasted nodes.

View | Add Selected Node to Outline

Creates a top-level outline item in the outline view for the node that's currently selected in whichever view you are in, and then switches over to the outline view to allow you to browse to linked nodes in outline format. If there is no selected node when you issue this command, then it does nothing.

View | Web Interaction | Invoke Web Browser on Node Value

Invokes a third-party web browser or other program to display the web page or document file that is assumed to be named by the IRI or literal of the currently selected node.

If the values of nodes in a particular store are not themselves web URLs or file paths, but some nodes have triples that specify web URLs or files for those nodes, then you can use Global Options | Node Label Predicates | Custom Predicates for Web Pages to specify the predicates that supply the actual values to pass to the third-party programs.

If the value appears to be either a URL for a web page or the path of an HTML file, then Gruff will attempt to display it in your preferred web browser (the program that's registered for displaying HTML files). If the node value instead appears to name a local file, then Gruff will look for the program that is registered for displaying documents that have the file type of the node value (if it has one). If such a program is found, then it will be run, passing the node value as an argument, presumably to display that file. Except if Global Options | Miscellaneous | Use Web Browser for All Documents is enabled, then your web browser will be used for all types of documents. If the node value appears to be a relative pathname, it will be merged with Global Options | Miscellaneous | Document Base Folder to find the full pathname of the file to look for.

A mouse shortcut for this command is control-shift-left click, which works on nodes in the various Gruff views.

View | Web Interaction | Do Google Search on Node Label

Invokes your preferred web browser to tell Google to search for the label that the selected node is displaying, and to display its list of search matches in the web browser.

View | Web Interaction | Search Wikipedia on Node Label

Invokes your preferred web browser to tell Wikipedia to search for the label that the selected node is displaying, and to display a relevant page in the web browser.

View | Web Interaction | Fetch DBpedia Descriptions from Node Label

This command can be used to find descriptions of things in the DBpedia database on the web, and to display the descriptions as nodes in Gruff.

It first does a DBpedia search on the label text of the selected node in the graph view, or of the displayed node in the table view. This uses DBpedia's search facility that takes a query URL of the form http://lookup.dbpedia.org/api/search/KeywordSearch?QueryString=foo, where foo is the percent-encoded node label.

If DBpedia returns XML that contains one or more search matches, this command then creates a Gruff triple for each search match where the subject is the selected node, the predicate is the arbitrary predicate http://franz.com/DBpediaDescription, and the object is a literal for the Description field of that search match in the XML from DBpedia.

Typically, one or two of the search matches will be descriptions of the thing that's named by the node label itself, and other matches will be only tangentially related. You likely will want to display only the former.

In the graph view, a pop-up menu will then let you select one of those triples (or all of them) to display, as if you had used the command Link | Display a Linked Node from Menus and then selected the DBpediaDescription predicate. In the table view, rows will be added for all of the new Gruff triples.

The created node and triple objects are in Gruff only, and so this does not add nodes or triples to the AllegroGraph database or SPARQL endpoint that you are browsing at the time. In effect, Gruff is then browsing an ad hoc federation of the created triples on top of the main database that you are browsing. This is similar to retaining triples from the previous database when you open a new one, as described in See [Building an Ad Hoc Federation from Multiple Stores and Endpoints] (#BuildinganAdHocFederationfromMultipleStoresandEndpoints).

This command is available only in the graph view and the table view.

View | Web Interaction | Fetch Wikipedia Pixmap from Node Label

This command can be used to find an image (pixmap) for a node on the Wikipedia web site, and to display the image on a node in Gruff's graph view.

It first does a Wikipedia search on the label text of the selected node in the graph view, using Wikipedia's search facility that takes a query URL of the form https://en.wikipedia.org/wiki/Special:Search?search=foo, where foo is the percent-encoded node label.

If a Wikipedia page is found and returned, then the returned HTML is searched for the first linked image page whose type is jpg or jpeg. If one is found, then a Gruff triple is created where the subject is the selected node, the predicate is the arbitrary predicate http://franz.com/WikipediaImage, and the object is a new Gruff resource node for the image page on the web.

That triple is then displayed in the graph view. As usual when the value of a node is the URL of an actual image page on the web, displaying the new object node in the graph view will cause Gruff to download the image from the web page and display the image on the node. Typically this command will display the new node for the image itself, but in the special case where http://franz.com/WikipediaImage is one of the Global Options | Node Label Predicates | Custom Predicates for Node Pixmaps the new image node will not be displayed, and instead the node itself will be updated to display the image.

The created node and triple object are in Gruff only, and so this does not add nodes or triples to the AllegroGraph database or SPARQL endpoint that you are browsing at the time.

This command is available only in the graph view.

View | View Current Store in AGWebView

Shows AGWebView in a web browser tab, open on the triple-store that Gruff is now browsing. WebView is another interface for browsing AllegroGraph triple-stores, and includes administrative functionality.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

View | Browse a Single Graph

Lets you browse only a single graph that's in the store, or to revert to browsing the entire store after browsing a single graph. A dialog will appear that lists the graphs that are in the store. Selecting one will place Gruff into a mode where all commands that look for triples to display will find only triples that are in that graph. Selecting the first choice for the entire store some time later will return to browsing the entire store.

If the only choices in the dialog are for the entire store and for the default graph, then the store does not contain multiple graphs, and using this command has no real effect.

Using this command will clear everything that Gruff is currently displaying (and uncache data that it has collected), as when opening a different store. To instead display a visual graph of all of the triples in a particular graph without clearing other Gruff views and uncaching data, see Display | Display Triples of One Graph.

Using various editing commands to create triples will create the triples in the graph that is currently being browsed, if any, and otherwise will create them in the default graph. Using this command is the only way in Gruff to create triples in a graph other than the default graph.

Using this command could lead to confusion if you forget that you are browsing a single graph and wonder why other triples are not appearing. The single graph that is being browsed is mentioned in the title bar as a reminder.

This command can fail if Global Options | Timeouts | Finding All Graphs Timeout is exceeded.

The View Menu's List of Recent States to Redisplay

The bottom section of the View menu lists states that were saved for the particular view that is currently shown. A state may be loaded and redisplayed by selecting it in this list.

The states in this list (if it appears at all) were saved with the Save command on the File menu, which is either File | Save Layout State, File | Save Table Object URI, File | Save Query Text, or File | Save Graphical Query, depending on the view that was displayed at the time. Those states can be loaded with the corresponding Load commands on the File menu, while this bottom section of the View menu is a quicker alternative for loading the states that were saved or loaded most recently for the particular store that is being browsed.

Up to nine states will appear in this list. These menu items will begin with a numeral that you can type as a shortcut once you have shown the View menu, followed by the name of the layout file. To see the full pathname of the layout file, highlight the menu item and check the status bar at the bottom of the application.

The Text Search Menu

These commands allow searching for triples in the store textually, and then displaying some or all of the matches. You can specify a simple word or phrase to search for, to find literals or even URIs that contain the word or phrase. More complex searches can be done by specifying pattern-matching and/or logical expressions.

The command at the bottom of this menu, Search the Current View, searches for a word or phrase in the text that's currently displayed on the screen in the selected view, rather than searching through the triple-store as the other commands do.

Text Search | Find and Display Nodes

Displays the subject nodes of triples that match a text search. First a dialog appears for entering a word, phrase, or expression to search for in the triple-store. If any triples are found that match the expression, then a second dialog appears listing the subject nodes of those triples.

You can then select multiple matching nodes to display in the graph view or the graphical query view. In the table view you can select a single node to display a table of its properties; in the outline view you can select a single node to add to the outline; and in the query view you can select a single node to paste its text into the query text widget. (In the query view it will work only if the query text widget currently has the keyboard focus to indicate where the insertion point is.)

The number of matching subject nodes that will be listed for selection is limited to Global Options | Maximum Choices When Selecting a Subset.

The text search dialog mentions a few examples of the types of search expressions that can be used. Here is the meaning of each of those examples. 

one two three

This search expression will match any triple part whose value contains the word "one" and also contains the word "two" and the word "three", though those words do not need to be connected in the triple part value. 

"one more time" two three

The quotation marks here indicate that the entire phrase one more time must exist in the triple part value. The other words indicate that the word two and the word three must also exist somewhere in the value. 

(or soccer (and ????ball* "team sport"))

This more complex example combines pattern-matching strings and a logical expression. The pattern-matching string ????ball* will match any word that begins with any four characters followed by the four characters "ball", followed by any number of additional characters. The logical expression that's defined by the parentheses and the special terms or and and says that the entire expression will match any triple part whose value contains the word "soccer", or if the value both matches the ????ball* expression and contains the complete phrase "team sport" (without the quotation marks).

When using a SPARQL endpoint rather than an AllegroGraph store, a text search expression cannot use logical operators, and will be used directly as a REGEX filter string in a SPARQL query.

Text Search | Find and Display Triples

This is like Text Search | Find and Display Nodes except that the second dialog lists the complete triples that were found rather than their subjects only. And selecting some of the matching triples will add nodes and links to the graph view for all parts of the selected triples.

This command is present only in the graph view.

Text Search | Select or Create a Text Index

Lets you select a different current text index to search, or to create a new index. This menu command also displays the currently selected index in brackets, so that you can see whether the desired text index is already the current one.

Invoking this command will show a pop-up menu for selecting the current text index. A special New Index choice at the top allows you to create a new text index, and this will be the only choice if the store does not yet have any text indexes. If there are any indexes to choose from, they will be listed below a separator bar, and a second special All Indexes choice in the upper section allows searching all of the store's indexes at once.

A special Delete an Index option at the bottom of the menu allows removing a text index from the store, if you select an index from the menu that will appear next.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Text Search | Edit the Current Text Index

Shows a dialog that lets you specify what parts of the triple-store will be searched by the current text index.

The dialog primarily features a list of all of the predicates that are in the currently open store, with the ones that are currently indexed already selected. You can select a number of additional predicates to index them as well. You can also deselect any that are already selected in order to remove them from the index.

The dialog contains additional widgets for specifying various alternate ways to do the indexing, such as whether to index resources (rather than only literals, which is more typical), which triple parts to index, the minimum character length for indexed words, and common short stop words that should never be indexed. When you press the OK button, the index is updated to match the specified predicates and options. Subsequent text searches for the modified index will find matches only in the places that were specified when you last edited that index.

To select multiple predicates in the list of all predicates, on Windows you can simply click each predicate (or use the arrow keys to move to it and then press the spacebar) to toggle that item on or off. On Linux and Mac you will need to control-click each predicate, or click one item and shift-click another to turn on the range of items in between. The Select All and Deselect All buttons may be used to quickly select or deselect all predicates.

If there are many predicates in the store, then it may be cumbersome to scroll the long list of predicates to the desired ones, and so it may be more convenient to use Text Search | Add a Single Predicate when adding only a few. That command does not indicate whether each predicate is already indexed, though.

If the current text index is All Indexes (for searching all of the indexes that are defined in the store at once), then invoking this dialog will first show a pop-up menu to ask which index you would like to modify.

This command always commits the triple-store at the end.

The first time this command is used during the session for a particular store, Gruff must ask the server for all of the unique predicates to list, which can take significant time. See Global Options | Timeouts | Finding All Predicates Timeout.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Text Search | Add a Single Predicate

Lets you select a predicate on which you would like to perform text searches. It will then update the current text index to search the triples of that predicate, in addition to the triples of any predicates that were already specified for that index.

A series of menus will appear to let you select any predicate in the store, using sorted lists that discriminate on successive characters in the predicate names until there is no ambiguity. (That should make sense once you see it.)

The first time this command is used for a particular open store, there will first be a pause to collect and sort all predicates that are in the store. A yellow message window appears during the pause. See Global Options | Timeouts | Finding All Predicates Timeout.

If the current text index is All Indexes (for searching all indexes at once), then a pop-up menu will first appear to ask which index you would like to modify.

This command always commits the triple-store at the end.

To set up more than a few predicates, it may be more convenient to use Text Search | Edit the Current Text Index to select them all at once.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Text Search | Text Search Timeout

This is the number of seconds before a text search will give up and return no results. Otherwise a text search might take an indefinite amount of time and hang Gruff.

Text Search | Search the Current View

Lets you search for any currently-displayed node in the graph view or the graphical query view, or any table cell in the table view, by typing a portion of the label that's printed on a node or in a table cell. A small window will appear that displays the search text as you've typed it so far. Initially the window will be at the lower left corner of the main Gruff window, but you can drag it elsewhere if you like. When you see the small window, just start typing characters. Use the Backspace or Delete key or Control-H to erase the most recently typed characters as needed.

The search is an incremental one that updates the state of any matching nodes or table cells as you enter or erase each character of the search text. One of the currently matching nodes or cells (if there are any) will be selected at each step, and a status-bar message will indicate how many matches there are. The background color of the search window will also indicate whether there are matches for the current search text: It will be gray when there are no characters in the search text, blue when there are multiple matches, green when there is a single match, and red when there are no matches.

When there are multiple matches, you can press the Tab key to select a different matching node or table cell. When the search text is at least three characters long, all matching nodes or cells will be highlighted with a red background (for nodes) or orange background (for table cells), and the currently selected matching node or cell will be scrolled toward the center of the window as far as possible to make it easy to spot the matching node or cell. (Tabbing to a match will scroll it toward the center even when the search text is less than three characters long.)

To accept a match and leave it selected and scrolled toward the middle of the window, press the Enter key. To cancel the search and scroll the window back to where it was and reselect the previously selected node or cell (if any), press the Escape key.

The selected matching node will flash momentarily if Visual Graph Options | Node and Link Flashing | Flash Selected Search Matches is enabled, as it is by default.

The Display Menu

These commands offer a variety of ways for adding an arbitrary node to the display, especially an initial node to which linked nodes can then be added with commands on the Link menu.

These commands are typically used when you're in the graph view, to add a node to the set of nodes that is already displayed there. But they can also be used to display a node's properties in the table view, or to add a top-level node to the outline view, or to add a non-variable node to the query view, or even to insert the URI of the specified node into the query text in the query view.

In the graph view, a newly added node will be placed at the mouse cursor. The node will also flash briefly if Visual Graph Options | Node and Link Flashing | Flash Newly Added Nodes is enabled.

An alternatives to these Display menu commands is to use View | Paste to paste a node whose URI is on the clipboard.

Display | Display a Node by URI or Literal

Displays a node that has the URI or literal string that you type or paste into a text-edit box in a dialog. The string should be a complete URI for a resource, such as http://www.cyc.com/2002/04/08/cyc#Balloon, or else a complete literal string (without quote marks). Displaying a literal is useful only if Global Options | Miscellaneous | Treat Literals as Objects is enabled, which will allow you to display nodes that are linked with literals.

This tecnhique works in any triple-store, though it requires specifying an actual URI or literal.

If a namespace abbreviation is applicable to a URI, then you can enter the abbreviated form with a colon after the abbreviation. Use Global Options | Namespace Abbreviations to define namespace abbreviations (or call register-namespace if you are using Gruff in a development lisp).

If no resource is found in the store for the string that was entered, then a search for a string literal is done. The literal search will first be done using the current language for literals (see Global Options | Miscellaneous | Preferred Language), and if one is not found then another literal search is done using no language.

If no such resource or literal exists in the triple-store, and the triple-store was opened in read-only mode, then a dialog will inform you that no resource or literal was found. If instead the store was opened in read/write mode, then a new node will be created and displayed. That can be useful for creating new triples in the graph view, by first creating a new node with a specified URI, and then using Edit | Create a Triple by Linking Nodes.

If you are entering non-ASCII characters that are percent-encoded in the store, then see Edit | Percent-Encode Non-ASCII After Editing.

Display | Display a Node by Label

This command is useful only if the triple-store being browsed contains resources that have skos:prefLabel or rdfs:label properties, or properties for custom label predicates as set up with Global Options | Node Label Predicates | Custom Predicates for Node Labels. It lets you simply type in a label string, then finds the resource whose skos:prefLabel or rdfs:label property (or custom label property) is that string, and then displays it. If no such resource can be found, then a dialog informs you of that. Note that the spelling must exactly match the label property string, and the strings are case-sensitive.

When using custom label predicates, this will find the node when the typed string matches the value of a single custom predicate, but not when it matches a string that's formed by concatenating the values of multiple custom predicates, even though such concatenated labels are displayed for nodes.

Display | Display a Recently Selected Node

Presents a menu of nodes that you have selected recently in the store that you are browsing, and displays the one that you select, if any. The most recently selected nodes will appear toward the top of the menu.

The list of nodes will include nodes that you selected in recent Gruff sessions. That makes this command useful for getting started in a new Gruff session by locating and displaying nodes that you were using in the previous Gruff session for the same store.

Display | Display an Instance Node by Type

This command is useful in any store that contains triples that use the rdf:type predicate. It finds all of the objects of those triples and presents them as a series of alphabetized pop-up menus, for selecting any rdf:type object in the store. After selecting a type, a further series of pop-up menus let you select an instance of the selected type, meaning the subject of some rdf:type triple whose object is the selected type.

The first time you use this command, it may take a while to find all of the types. You can interrupt the search at any time by pressing the Q key or the Escape key; if you do that while it is still collecting nodes (before it begins to sort them), then it will proceed to sort the ones that it's found so far and then let you select from that subset of all types.

To display a node for a type itself, rather than one of its instances, use Display | Display a Type Node by Type instead.

Display | Display a Sample Instance Node by Type

This is like Display | Display an Instance Node by Type except if it needs to find the instances of the selected type then it will only ask the server for 25 instances that it will present as choices to display. This avoids the long delay that can occur for a type that has many instances, in cases where you just want to display some typical sample instance of the type. (Any later command that needs to find all of the instances will still do so.)

Display | Display a Type Node by Type

This is like Display | Display an Instance Node by Type, except that it displays a node for a selected type itself, rather than further asking for an instance of that type to display.

Display | Display an Instance Node by Class Hierarchy

This command presents a dialog for browsing the class hierarchy of the store, to selet an instance of a class to display. To display a node for a class itself, rather than one of its instances, use Display | Display a Class Node by Class Hierarchy instead.

Begin by selecting one or more predicates like subClassOf or narrower in the list of predicates that are used in class hierarchies. This will display the root nodes of the hierarchy for each selected predicate in the main outline widget. When no triples are found for a predicate, that predicate will then be grayed out to indicate that. You can use the Add button to add a choice for a predicate that behaves similarly, or the Remove button to remove a choice that has no triples in the store. The currently selected predicates for each store, along with the predicate choices for each store, will be saved in your options file.

The first time you select a predicate for a particular store, Gruff will query the server for the root nodes to list for that predicate. Thereafter Gruff will save the root nodes for each predicate in your options file so that they will be listed more quickly in future sessions.

Each root node (top-level class) in the outline can be opened by clicking the icons on the left to reveal successive levels of subclasses, or by using the arrow keys on the keyboard. If you select a class in the outline and exit the dialog, Gruff will then display a series of pop-up menus for selecting an instance of the selected class to display. In the graph view, multiple classes can be selected by simply left-clicking each one, or by using the up and down arrow keys to move to each one and then pressing the space bar; pop-up menus would then let you select one instance of each of those classes.

If Global Options | Class Outline | Automatically Indicate Childless Classes is enabled, then classes that have no subclasses will automatically show a hollow arrow to indicate that you can't open them. And if Global Options | Class Outline | Automatically Indicate Instanceless Classes is enabled, then classes that have no instances will automatically be grayed out to indicate that they would offer no instances to display if you selected them. Otherwise you can press the Update Annotations button to update this information only when you desire it. In either case, you can press the Q key to interrupt the updating of these annotations (the Escape key is not supported for this because that will exit the modal dialog entirely).

Gruff caches the root nodes for each class predicate in the options file to avoid spending time re-fetching them from the server each time the store is opened. If the store is modified, these lists can become out-of-date. If you think that this may have happened, then you can press the Update Root Nodes button to re-fetch the root nodes from the server.

Keys on the main part of the keyboard can be used in the outline widget as a quick alternative to the arrow keys and Home and End keys. These keystrokes work in some other outline widgets in Gruff as well. Here are the key mappings: 

J   DownArrow      selects the next outline item  
K   UpArrow        selects the previous outline item  
F   RightArrow     opens the selected outline item  
D   LeftArrow      closes the selected outline item if it is open,  
                   or else selects the parent item  
T   Home           scrolls to the top and selects the first item  
B   End            scrolls to the bottom and selects the last item

Display | Display a Sample Instance Node by Class Hierarchy

This is like Display | Display an Instance Node by Class Hierarchy except if it needs to find the instances of the selected type then it will only ask the server for 25 instances that it will present as choices to display. This avoids the long delay that can occur for a type that has many instances, in cases where you just want to display some typical sample instance of the type. (Any later command that needs to find all of the instances will still do so.)

Display | Display a Class Node by Class Hierarchy

This is like Display | Display an Instance Node by Class Hierarchy, except that it displays a node for a class that you select from the class hierarchy, rather than further asking for an instance of the class to display.

Display | Display Some Sample Triples

Adds nodes and links to the graph view for some triples in the current triple-store, up to a limit that's defined by Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display. The graph view is first cleared of all other nodes and links, though you can always use View | Go Back to retrieve them.

This command uses several SPARQL queries to try to find some chains of linked nodes in most any triple-store, because that is what the graph is good as illustrating. If you are currently browsing a single graph (see View | Browse a Single Graph), then it will search only that graph for the sample triples to display.

This command is present only in the graph view.

In the lisp interface, the corresponding function is display-store.

Display | Display Triples of One Graph

Adds nodes and links to the graph view for all of the triples of one particular graph that you first select from a list. The graph view is first cleared of all other nodes and links. The number of triples that are added is limited to Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display.

This command may be especially useful in a store that contains many graphs, where one graph is used for each "thing" of some kind, and where not all of the triples for a thing are linked with each other via shared nodes.

This command can fail if Global Options | Timeouts | Finding All Graphs Timeout is exceeded.

To cause all Gruff commands to browse only a single graph, see View | Browse a Single Graph.

This command is present only in the graph view.

In the lisp interface, the corresponding function is display-store when passing a :graph argument to it.

The Link Menu

These commands are for adding nodes to the visual graph that are linked (in the database) to nodes that are already displayed. Before using these commands you need to use a command on the Display menu to add an initial node.

The menu is present only in the graph view.

Link | Display Linked Nodes for the Current Predicates

Adds any nodes to the display that are linked with the currently selected node by any of the current predicates. First you need to select the current predicates with Global Options | Select Current Predicates.

This is useful for quickly building a visual graph, by alternately selecting different nodes and then using this command to see what's linked with them. If this adds too many nodes or undesired nodes, use View | Go Back to revert to the previous state.

Triples will be included where the selected node is either the subject or the object, unless either Link | Triples to Include | Include Triples as Subject Only or Link | Triples to Include | Include Triples as Object Only is enabled.

Link lines will also be added to display between any newly-added nodes and any already-displayed nodes to which they are linked by the current predicates. Though for efficiency reasons this is not done for larger stores, specifically any store that contains more triples than Global Options | Miscellaneous | Minimum Triples for Individual Property Lookup.

If there is no selected node but there are one or more highlighted nodes, then this command will be applied to all of the highlighted nodes simultaneously. This is an even faster way to display lots of linked nodes, though it may usually display more than desired. See Select | Toggle Highlighting of the Selected Node or Link.

If this operation would cause the entire visual graph to contain more links than Visual Graph Options | Inclusion Options | Number of Total Links for Abort, then it will stop looking for additional links at that point. If that happens, or otherwise if the total number of links would exceed Visual Graph Options | Inclusion Options | Number of Total Links for Warning, then a warning dialog will be shown. The dialog will offer options to either display all of the linked nodes, or to let select a subset from a list of them, or to cancel. If you use the option to select a subset of the linked nodes, then the number of nodes that will be listed for selection will be limited to Global Options | Maximum Choices When Selecting a Subset.

When using the alternative node-coloring scheme Visual Graph Options | Color Nodes for Unseen Links, this command will have an effect only on nodes whose background color is yellow (by default), which indicates that they have undisplayed linked nodes for the current predicates.

See also the introductory section Using Current Predicates to Quickly Build a Graph.

In the lisp interface, the corresponding function is display-linked-nodes.

Link | Display Non-Leaf Linked Nodes

This is the similar to Link | Display Linked Nodes for the Current Predicates, except that it avoids displaying any new nodes that would be leaf nodes if they were displayed. When there is a single selected node, this will only add links between that node and any other nodes that are already displayed.

This command is probably more useful when there is a group of highlighted nodes (see Select | Toggle Highlighting of the Selected Node or Link), where it will also display new nodes that are linked with more than one of the highlighted nodes. In that case, this command is similar to Link | Display Paths Between Two Nodes when Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length for Highlighted Group is 2. This command is probably faster, but does not show incremental progress for each pair of highlighted nodes as that command does.

Link | Display Only Linked Nodes

This is the similar to Link | Display Linked Nodes for the Current Predicates, except that it first removes all nodes from the display except for the selected node. This is useful for starting a new visual graph with one of the currently displayed nodes. It is also useful for browsing through a sequence of nodes without retaining everything that you pass through, by repeatedly selecting a leaf node and then using this command to see only that node and the ones that are linked with it.

In addition, if Visual Graph Options | Inclusion Options | Show 2 Levels of Nodes on Display Only Linked Nodes has been selected, then this command will display not only the selected node and the ones that are immediately linked with it, but also any nodes that are immediately linked with any of those linked nodes (by the current predicates). If that does not display too many nodes at one time, it allows you to more quickly browse through a sequence of nodes by repeatedly selecting a node that is either one or two links away from the previously selected node.

Link | Fill In All Links for the Current Predicates

Adds any "missing" links to the display for the nodes that are already on the display and the current predicates. It will also update any existing link lines to represent any additional current predicates that they do not already represent. This is useful after selecting additional current predicates, to show where the newly-selected predicates connect any nodes that were already on the display. It is also useful after adding individual nodes from the table view or with Link | Display Linked Nodes from an Outline, because those approaches do not fill in additional links among the displayed nodes.

This command may not often be needed because it is done automatically by various commands that add nodes to the display. But the automatic filling in is limited by Global Options | Timeouts | Filling In Links Timeout, while this explicit command is limited only by Global Options | Timeouts | Path-Finding Timeout which typically will be much longer, and so this command may find links to add that were not added automatically due to the shorter timeout.

There is a another subtle case where this command will add link lines to the display: If you add a node for which there are many triples, some of the triples may be dropped due to Global Options | General Triple-Fetching Limit. If one of these triples connects to an already-displayed node, then that link will not get filled in. But the connected object will typically have fewer triples and will NOT have dropped its triple pointing back to the new node. This command will see that triple and add the missing link line.

Link | Triples to Include | Include Triples as Subject Only

Causes Link | Display Linked Nodes for the Current Predicates to show only triples where the selected node is the subject. This includes when opening items in the outline view.

This will also make Link | Display a Linked Node from Menus skip its initial menu asking for triples as subject or as object.

Link | Triples to Include | Include Triples as Object Only

Causes Link | Display Linked Nodes for the Current Predicates to show only triples where the selected node is the object. This includes when opening items in the outline view.

This will also make Link | Display a Linked Node from Menus skip its initial menu asking for triples as subject or as object.

Link | Triples to Include | Include Triples as Either

Causes Link | Display Linked Nodes for the Current Predicates to show triples where the selected node is either the subject or the object.

Link | Split Node into One Copy per Link

Creates additional copies of the node picture for the selected node, and links each node that is linked with the selected node to its own copy. That allows each linked node to be near its copy rather than stretching long link lines to the single copy of the selected node. This may be useful for making a neater-looking layout for presentation.

Link | Merge Multiple Copies of Node

Replaces the multiple copies of the selected node picture (if any) with a single copy, where the single copy will have all of the link lines of the former multiple copies.

About Node Background Color for Unseen Links

Related to the above commands, here is a note about using node background color to facilitate adding linked nodes for the current predicates. This applies only when the Visual Graph Options | Color Nodes for Unseen Links option is in effect, which it is not by default.

When using Color Nodes for Unseen Links, the background color of a node will indicate whether it is linked with other resources in the database that aren't currently displayed. This tells you whether particular commands in this section of the Link menu will do anything when applied to the selected node.

If a node is yellow (by default), then there are undisplayed resources in the database that are linked to this node by the current predicates (see Global Options | Select Current Predicates). Therefore the Display Linked Nodes for the Current Predicates command will do something when a yellow node is the selected node, and not otherwise. If you are building a graph with that command, then the yellow nodes are the ones that are worth selecting.

If a node is green (by default), then it does NOT have any undisplayed linked nodes for the current predicates, but it DOES have undisplayed linked nodes for other predicates. Therefore Display Linked Nodes for the Current Predicates will do nothing when a green node is the selected node, but Display Linked Nodes from an Outline WILL show additional linked nodes that you could add to the display. And the table view will similarly show the additional nodes that could be added.

A cyan node (by default) has no linked resources in the database that are not currently displayed, and so there is no point in selecting it for adding linked nodes to the display.

Those three special colors may be changed on the Visual Graph Options menu.

Link | Display Paths Between Two Nodes

Adds to the display any nodes and links that lie on paths between two specified nodes that are already on the display. The only paths that will be found are ones whose links use only the current predicates (see Global Options | Select Current Predicates), and which are no longer than Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length. The results are also affected by Visual Graph Options | Finding Paths Between Nodes | Find Only Shortest Paths.

The currently selected node will be used as one of the end nodes of the path, so you should click a node to select it just before using this command (unless the desired node is already selected). The command will then draw a rubber-band line from the selected node to indicate that you need to click on the other end node. If you do click on another node, then the triple-store will be searched for paths between the two nodes, and any nodes and links for the found paths that are not already displayed will be added to the display.

Alternately, you can first highlight two or more nodes and deselect the selected node (if there is one), and then this command will find paths between every pair of nodes in the group of highlighted nodes. Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length for Highlighted Group will then limit the path lengths, typically to a smaller length to avoid a long operation. Nodes can be highlighted individually with Select | Toggle Highlighting of the Selected Node or Link or by control-left-clicking each one. A group of nodes can be highlighted at once with a control-left-click-and-drag to drag a box around them. )(On the Mac use the command key here rather than the control key.) If there is a selected node (with a red border), it can be deselected by clicking the background.

If the number of found paths is equal to or greater than Visual Graph Options | Finding Paths Between Nodes | Number of Found Paths for Warning, then a confirmation dialog will appear before the nodes and links are added to the display. If you select the option on that dialog to select a subset of the found paths to display, then the number of paths that are listed for selection is limited to Global Options | Maximum Choices When Selecting a Subset.

If Visual Graph Options | Node and Link Flashing | Flash End Nodes of Found Paths is enabled, then the end nodes will flash at the end to help you spot them after they likely moved when the layout was updated. (This is not done for a group of highlighted nodes, because they are already highlighted with blue borders to point them out.)

Path-finding is not available when using a SPARQL endpoint rather than an AllegroGraph store, because it uses optimized functionality that's built into AllegroGraph which is not feasible to emulate efficiently using SPARQL queries. An exception is Stardog servers, because they offer a custom API for doing path-finding on the server with a single SPARQL query, and Gruff now hooks into that.

In the lisp interface, the corresponding function is find-and-display-paths.

Link | Display Only Paths Between Two Nodes

This is like Link | Display Paths Between Two Nodes except that it also removes all nodes and links that are not part of the paths that were found.

It may be useful to use View | Go Back along with this command, to display only the paths between two nodes of a large layout, and then to return to the large layout to select two other nodes to display their paths, and so on.

The placement of the selected nodes that lie at the ends of the found paths is affected by whether Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Left and Right or one of its alternatives is currently selected.

Path-finding is not available when using a SPARQL endpoint rather than an AllegroGraph store, except for Stardog servers.

Link | Display a Linked Node from Menus

Lets you select a node that is linked to the currently selected node in the store, and adds that node to the display, with a link line connecting the two nodes. You select the linked node in a series of pop-up menus, first selecting whether the selected node is the subject or the object of the triples to select from, then selecting a predicate, and finally selecting a node that is linked by the selected predicate in the selected direction. On each menu there is an "All" choice for displaying all of the remaining choices instead of a single one.

The menus are prepared in a way that allows making the next selection by pressing a single character on the main part of the keyboard. The first menu is always the choice for the set of triples where the selected node is either the subject or the object; you can type S or O to make this selection. (This menu is skipped if either Link | Triples to Include | Include Triples as Subject Only or Link | Triples to Include | Include Triples as Object Only is enabled.)

The next menus allow choosing a particular predicate for which there are triples with the selected node as the subject or object. If there are no more than 25 predicates from which to choose, then all of the choices will appear on a single menu that uses the letters A through Y as keyboard shortcuts. Otherwise the predicates will be divided into a series of pop-up menus that allow refining your choice by typing single letters.

After choosing a predicate, a node that's linked by that predicate can then be chosen in the same way that the predicate was chosen. That node will then be added to the display. If there are no more than 25 linked nodes for the predicate that you selected, then the menu of linked nodes will have a special "All" item at the top; selecting this choice will add all of the linked nodes for that predicate to the display.

The menus will exclude choices for nodes and links that are already in the visual graph.

A subtle rule for excluding redundant labels: If you choose "All" in the menu of predicates, and Global Options | Node Label Predicates | Use Label Predicates for Node Labels is on, then node label properties will not be added to the display as separate nodes because those labels appear on the node itself, and so showing them as separate nodes as well would be redundant clutter. (A label property is defined as one where the predicate is a member of Global Options | Node Label Predicates | Custom Predicates for Node Labels if there are any, and otherwise is skos:prefLabel or else rdfs:label.) Except that nodes for label properties will still be added to the display if all of the unshown linked nodes are label properties.

Link | Display Linked Nodes from an Outline

Lets you select any subset of the nodes that are linked to the currently selected node in the store, and then adds those nodes to the display, with link lines connecting them to the seleted node. A dialog is shown that lists all of the linked nodes of the selected node. These are arranged into an outline, first by whether the selected node is the subject or the object of any triples that link the nodes, and second by the predicates that link the nodes. Any nodes that you select will be added to the display.

The outline items for the linked nodes are not visible in the outline initially to save space, so typically you would first click the icons at the left of one or more predicates at the second level in the outline to see which nodes are linked by each predicate. If you want to add some of those nodes to the graph view, you can either select the individual node names in the outline, or alternately select the predicate name to add all of the nodes that are listed under it. (Selecting one of the two top-level items for "As Subject" or "As Object" has no effect.)

You can select multiple items by simply left-clicking each one. To select a contiguous series of items, left-click the item at one end of the series and then shift-left-click the item at the other end.

To accept the values that you've selected, either press the OK button or press the Enter key or right-click anywhere in the outline. To cancel, either press the Cancel button or press the Escape key. You can also cancel quickly by simply moving the mouse cursor out of the dialog if you enable Global Options | Miscellaneous | Cancel Linked Nodes Outline on Mouse Out.

A predicate name in the outline will have a yellow background if it is one of the "current predicates" whose nodes could alternately be added with the Link | Display Linked Nodes for the Current Predicates command. A node name in the outline will have a cyan background if it is already on the display (though the link line between the nodes may not exist yet). A node name will have a red background if you have explicitly excluded that node with the Remove | Exclude Selected Node command; but you can still add that node to the display with this command, which also removes it from the set of excluded nodes.

A rather similar technique for adding nodes is to toggle over to the table view and select them there. And the Link | Display a Linked Node from Menus command is also similar when adding a single linked node at a time.

The Remove Menu

These commands offer various ways to prune some of the nodes and links in a visual graph. In the graph view, the nodes and links tend to accumulate until the visual graph becomes unwieldy.

This menu is present only in the graph view and the graphical query view, and only some of these commands are present in the graphical query view.

Remove | Remove Selected Node

Removes the currently selected node from the display. Any orphan nodes that remain will also be removed if the Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal option is active.

If there are any highlighted nodes (see Select | Toggle Highlighting of the Selected Node or Link) but no single selected node, then all of the highlighted nodes will be removed.

In the lisp interface, the corresponding function is remove-node-of-upi.

Remove | Exclude Selected Node

This is like Remove Selected Node, but it also marks the removed node so that it will not be added to the display again during the current browser session by any of the commands that add nodes for the current predicates. This is useful for removing a node that is clearly not of interest and to prevent it from popping back up again and again. This helps to remove clutter that only makes the layout more difficult. It may be especially useful for nodes that have many links (assuming that they are not of interest).

Link | Display Linked Nodes from an Outline or the table view can still be used to add excluded nodes back to the display. The node names will have a red background in those windows to indicate that they have been explicitly excluded. If an excluded node is added to the display in one of those ways, it will no longer have excluded status.

This command is present only in the graph view.

In the lisp interface, the corresponding function is remove-node-of-upi.

Remove | Remove Selected Link

Removes the currently select link (if any) from the display.

Any orphan nodes that remain will also be removed if the Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal option is active.

Remove | Remove All Nodes

Clears all nodes and links from the display, for a fresh start. If done accidentally, you can return to the previous state as usual with View | Go Back.

Remove | Eraser Mode

Allows quickly removing an arbitrary subset of the displayed nodes and links. It puts the graph view into a mode where any node or link that the mouse cursor touches will immediately be removed, along with any links to any removed nodes as usual. The mouse cursor will change to warn you that you are in eraser mode.

Eraser mode can be turned off in several ways. You can either invoke the Eraser Mode command again, or press Escape or Q to invoke Layout | Abort the Layout or Command, or click the mouse anywhere, or move to another pane or application.

This command may make it rather easy to inadvertently delete nodes or links that you would like to remain. If that happens, just use View | Go Back to revert to the state before eraser mode was turned on.

Remove | Remove All Orphan Nodes

Removes all orphan nodes from the display. An orphan node is one that has no link lines attached to it on the display (though it may have triples in the database).

This command is present only in the graph view and the graphical query view.

In the lisp interface, the corresponding function is remove-orphans.

Remove | Remove All Leaf Nodes

Removes all leaf and orphan nodes from the display. This includes any node that has no more than one link line attached to it on the display.

This command can be useful when you are primarily interested in cycles in the displayed graph. All nodes that are not a part of a cycle can be removed by applying this command multiple times as needed (since removing some leaves can turn other nodes into leaves). You can even view the cycles temporarily by using this command (and then perhaps updating the layout), and then using View | Go Back to return to the earlier state with leaf nodes intact.

One paradigm for building a graph with lots of cycles is to continue adding linked nodes until there are many more nodes on the display than you would care to see at one time. (This process can be sped up by pressing Q or Escape or the spacebar to interrupt each incremental layout after adding each set of new nodes.) Then use this Remove All Leaf Nodes command a few times to prune out all nodes that are not in cycles, and then update the layout to see all of the interesting cycles between the remaining nodes.

This command is present only in the graph view and the graphical query view.

In the lisp interface, the corresponding function is remove-orphans, when passing the leaves-too argument as true.

Remove | Remove All Unhighlighted Nodes

Removes all nodes from the display except for those that you've highlighted with Select | Toggle Highlighting of the Selected Node or Link. A mouse shortcut for that command is Control-Left-Click (or Command-Left-Click on the Mac).

To quickly remove everything from the display except several nodes of interest and the links between them, first Control-Left-Click each of the desired nodes to highlight it with a blue border (or Control-Left-Click the background and drag down and to the right to draw a box around a group of nodes to highlight), then use this command to remove everything else. Then you could Control-Left-Click the background to remove all highlighting. (On the Mac use the command key here rather than the control key.)

This command is present only in the graph view and the graphical query view.

In the lisp interface, the corresponding function is remove-orphans, when passing the unhighlighted argument as true.

The Layout Menu

These commands modify the arrangement of nodes in the visual graph, using layout algorithms that attempt to make the graph easily readable, and manage your view of the layout.

This menu is present only in the graph view and the graphical query view, and only some of these commands are present in the graphical query view.

Layout | Redo Layout from Scratch

Rearranges the displayed nodes and links to make a more readable layout, by moving nodes near to other nodes that they are linked with and reducing overlapping.

Gruff implements two different layout algorithms: A constraint-based algorithm that's used for smaller graphs and a spring algorithm that's used for larger graphs. The option Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout determines which is used. The constraint-based algorithm specializes in avoiding overlapping between nodes and links, to make it as clear as possible which nodes are linked by each link line. But that algorithm doesn't scale well, and so a spring algorithm is used for larger graphs to make them fast enough for interactive use.

The nodes do not start out at their current positions, as with Layout | Update Layout Incrementally. Instead, the constraint-based algorithm begins with all nodes at the center of the canvas, to remove any bias that the current node positions might otherwise cause in the layout algorithm. This usually achieves a cleaner layout than a series of incremental updates to the layout. The spring algorithm begins with nodes scattered at random positions around the canvas (and so will the constraint-based algorithm if Visual Graph Options | Constraint-Based Layout Options | Begin Full Layout at Random Positions is enabled).

If a tree layout is present when this command is used, an incremental layout will actually be done on all of the nodes from their current positions, because Layout | Update Layout Incrementally never moves nodes that are in a tree. Using this command again after that will then do a full layout from scratch.

The layout will be animated if Visual Graph Options | Layout Options | Animate Layouts is enabled. Otherwise the display will be updated only once at the end of the layout computation. Animation slows down the layout, but shows you how it is progressing.

When there are many nodes and animation is enabled, the layout will be faster if you first use Layout | Zoom Out All the Way, because then the nodes will be drawn more simply and the overview pane will not be present and so will not be drawn.

The layout will stop if the number of iterations reaches Visual Graph Options | Layout Options | Maximum Iterations for Full Layout. The constraint-based algorithm may stop before then if it sees that the important constraints have been satisified. The spring layout does not know if it has reached a reasonable solution, though, and so it will always proceed toward this maximum, then slow down and typically stop some time before the limit is reached. If the layout is not judged good enough when it stops, then proceed to use Layout | Update Layout Incrementally one or more times to make the layout go further. If it looks good enough before reaching the limit, then you can interrupt the layout by pressing Escape, Q, or the spacebar (which are shortcuts for menu bar commands).

If a layout fails to achieve a decent arrangement because there is not enough room, then first use Layout | Make Canvas Larger. Or use Layout | Zoom Out, which effectively makes a larger canvas after the scrollbars have gone away, because the canvas is always at least as large as the node pane.

The cleanest possible layout is usually achieved by first unpinning any pinned nodes (see Select | Remove All Node Pinning) and then using this command, followed by Layout | Update Layout Incrementally if more work is needed.

This menu command corresponds to the lisp function update-the-layout.

This command is present only in the graph view.

Layout | Update Layout Incrementally

Rearranges the nodes as needed to make a more readable layout, beginning from the current node positions. This leaves nodes at or near their current positions when feasible, so that you don't lose track of the current context. This command can be used one or times in succession to improve a layout that is not yet satisfactory. You can issue this command (typically using its keyboard shortcut) while a layout is being done to speed the layout back up.

If there is a selected node and the constraint-based layout is being used, then that node will remain fixed in its current position. A cleaner layout might be achieved by first clicking the background (or pressing the spacebar) to deselect the current node, which gives more freedom to the layout algorithm.

This command is performed automatically by various commands that add or remove nodes, unless Visual Graph Options | Layout Options | Do Automatic Incremental Layouts is deselected. But it can still be useful to invoke explicitly at other times, such as after you have dragged nodes around. In particular, if you spot a case where the layout can be improved, you can drag nodes to better spots yourself. Using this command after that may make further adjustments to where you dragged the nodes. When you do drag nodes, try to leave the usual minimum spacing between the dragged node and other nodes and links if you want this incremental layout command to take your hint and retain your explicit changes. To ensure that the nodes that you dragged do not simply snap back to where they were, first use Select | Toggle Pinning of the Selected Node to force particular nodes to stay where you've placed them when a layout is later done.

The layout will stop if it the number of iterations reaches Visual Graph Options | Layout Options | Maximum Iterations for Incremental Layout.

If a layout fails to achieve a decent arrangement because there is not enough room, then first use Layout | Make Canvas Larger or Layout | Zoom Out.

This command is present only in the graph view.

In the lisp interface, the corresponding function is update-the-layout.

Layout | Update Layout Vigorously

Performs an incremental layout that "shakes things up" more during the first part of the layout. This may be useful if the regular incremental layout is failing to untangle any crossed chains of nodes, and you'd like to untangle those without undoing the progress that layouts have made so far.

This works internally by making linked nodes pull harder on each other in the early stages of the layout. An alternative may be to reduce Visual Graph Options | Spring Layout Options | Velocity Divisor, which would make layouts both push and pull harder all the time.

This command always uses the spring layout algorithm, even when the visual graph contains fewer nodes than Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

Layout | Update Layout Conservatively

Performs an incremental layout that mainly tries to moves any nodes off of link lines that they are sitting on, without disturbing the layout a lot. This can be useful after a spring layout, because the spring layout algorithm does not try to keep nodes off of link lines for speed reasons.

This command always uses the constraint-based layout algorithm, even when the visual graph contains more nodes than Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout. This command is mostly like Layout | Update Layout Incrementally when that command uses the constraint-based algorithm, except that this one disallows nodes from jumping very far away, to avoid disrupting the layout much.

Because the constraint-based algorithm does not scale well, this command can take a long time when there are more than around 100 nodes. But to achieve the neatest layout with a larger graph, the best approach is probably to first use Layout | Redo Layout from Scratch once, then Layout | Update Layout Incrementally zero or more times as needed until the spring layout appears to have taken things as far as it will, and finally (when you're ready to have lunch or go to sleep) to use this command once and leave it running for a while.

You can always interrupt this command in the usual way by pressing Escape, Q, or the spacebar.

Layout | Do Tree Layout from Selected Node

Creates a traditional tree layout from the nodes and links that are currently displayed. The currently selected node will serve as the root node of the tree (and so you need to first select a node if one is not selected already).

If Visual Graph Options | Tree Layout Options | Remove Unconnected Nodes is enabled, then any nodes that are not in the conencted set of nodes and links of the root node will be removed from the display (though as usual you could use View | Go Back to return to them).

The level of each other node in the tree is determined by the length of its shortest path from the root node. Cycles in the graph continue to be displayed as links to multiple parents in the tree. Heuristics similar to kerning are used to reduce the overall breadth of the graph, to reduce the amount of scrolling that's needed.

Unlike other layout commands, this one will make the scrolling canvas larger if needed to fit the layout into it, rather than trying to squeeze the layout into the canvas at its current size.

The nodes that are in the tree will remain fixed in their relative positions as you add more nodes to the display and do incremental updates to the layout (which will affect only the newer nodes). Nodes will be freed from their tree arrangement only by the commands Layout | Redo Layout from Scratch or Layout | Do Tree-Like Spring Layout, or by another use of this tree layout command, or by removing nodes from the display.

This command is affected by all of the options on the Visual Graph Options | Tree Layout Options child menu. These commands include Visual Graph Options | Tree Layout Options | Orient Tree Layouts Vertically, Visual Graph Options | Tree Layout Options | Center Parent Nodes by Children, Visual Graph Options | Tree Layout Options | Minimize Link Lengths, Visual Graph Options | Tree Layout Options | Spacing Breadthwise, and Visual Graph Options | Tree Layout Options | Spacing Lengthwise.

Layout | Update Tree Layout

Does a tree layout from the same root node as the most recent tree layout that was done. Using the keyboard shortcut allows you to quickly update the current tree after doing other commands, especially ones that add more nodes to the display that you want to work into the tree.

Layout | Do Tree-Like Spring Layout

This does a general spring layout while constraining each node to be farther away from the selected node than nodes that have shorter paths from the selected node. The orientation of the layout will be determined by Visual Graph Options | Tree Layout Options | Orient Tree Layouts Vertically.

This is similar to using Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate for the predicates of all links.

Layout | Abort the Layout or Command

Aborts a layout that is in progress, or certain other time-consuming activities such as searching for all top-level classes (or all nodes) in the triple-store. At any time you can press either the Q key or the Escape key to invoke this command.

You can also abort a layout simply by executing some other command, which will abort the layout and then proceed with the new command. This includes pressing the spacebar to invoke Select | Deselect the Selected Node and/or Link, and so the spacebar is a handy way to abort a layout as long as it's OK to also deselect the selected node.

See also the introductory section Interrupting a Long-Running Layout.

Layout | Make Canvas Larger

Increases the size of the scrollable canvas (into which the layout must fit) by one "notch", which by default is around one fifth of the current canvas size in each direction. This can be useful to make a layout succeed after it failed at a smaller canvas size. Typically you would notice a layout attempt thrashing about, then use this command to abort the layout and make the canvas larger, and then try the layout again.

The factor by which this command increases the canvas size each time can be set with Visual Graph Options | Layout Options | Canvas Resize Factor.

In case the keyboard shortcut that's shown on the menu item for this command is not clear, it is a period. That key was chosen because the greater-than symbol (or right angle bracket) is typically on the same key, as a mnemonic for a larger canvas.

If the Visual Graph Options | Node and Link Spacing | Limit Outward Stretching option is off, then the layout tends to fill the available canvas, requiring more scrolling to see everything, and so it's best to reduce the canvas size later if the larger size is no longer necessary. The size of the scrollbar sliders provides a clue about the current canvas size, and so does the size of the content in the overview pane at the lower left.

If the Visual Graph Options | Node and Link Spacing | Limit Outward Stretching option is on (as it is by default), then the layout will still tend to stretch things out somewhat more than necessary, so if you want to fit the layout into the smallest area possible then you would still need to make the canvas smaller in order to constrain the layout further. For example, if a layout extends just a little ways outside of the visible window when the canvas is large, it will likely fit entirely in the window if you first use Layout | Make Canvas Smaller repeatedly until the scrollbars turn off entirely.

Layout | Make Canvas Smaller

Reduces the size of the scrollable canvas by one "notch", which is around one fourth the current canvas size in each direction. This can reduce the size of future layouts so that you don't have to scroll as far to see everything, but can also make a layout less likely to succeed.

The keyboard shortcut for this command is the comma key because the less-than symbol (or left angle bracket) is typically on the same key, as a mnemonic for a smaller canvas.

If the canvas is already at its minimum size, which means that the scrollbars are turned off, and you are not currently zoomed in all the way, then this command will actually zoom in by one notch, as with Layout | Zoom In, and then also reduce the canvas size again so that the scrollbars are still turned off. This can be a handy way to zoom in when you are zoomed out farther then necessary, but without making the canvas larger than the window.

Layout | Minimize Canvas Size

Makes the scrollable canvas be the same size as the window pane, to force layouts to squeeze everything into the visible area. This is a shortcut to using Layout | Make Canvas Smaller several or more times when the canvas is very large.

Layout | Zoom Out

Zooms the visual graph outward so that more nodes and links can be seen at once. Labels will not be drawn in node boxes or on link lines when zoomed out by any amount, but they will appear in tooltips when hovering over nodes and links.

Layout | Zoom In

Zooms the visual graph inward to display more detail or to make nodes easier to click on. Node and link labels will be drawn only when zoomed in all the way.

If you are zoomed out farther than necessary, then see Layout | Make Canvas Smaller as a way to zoom in without making the canvas larger than the window.

Layout | Zoom Out All the Way

Zooms the visual graph outward far enough that all of the nodes and links fit into the node pane at the same time. This provides a complete picture of a larger graph.

Animated layouts may be more interesting when zoomed out all the way, because you can see how the entire graph is being rearranged. Animated layouts will also be faster, because the nodes are drawn more simply when zoomed out, and the overview pane will not be drawn as well because it is turned off whenever all nodes and links fit into the node pane.

The mouse shortcut is Control-Alt-Right Click, which can be handy just after using Control-Alt-Left Click for Layout | Zoom In Around the Mouse.

Layout | Zoom In All the Way

Zooms the visual graph inward to the normal size where node labels are drawn (and link labels as well when enabled). The graph will be centered around the same nodes and links that it was centered around before zooming in.

Layout | Zoom In Around the Mouse

Zooms the visual graph inward all the way, centering on the nodes and links that were near the mouse cursor when the command was issued.

When you're already zoomed in all the way, this command can still be used to quickly scroll the mouse position to the center.

It is most convenient to invoke this command with its mouse shortcut, which is Control-Alt-Left Click (or Command-Alt-Click on a Mac).

Layout | Center the Graph

Moves the entire set of displayed nodes as a whole so that they are centered within the scrolling canvas, and then scrolls the window to the center of the canvas. This is typically useful to bring all of the graph (or else the middle of it) into view after a layout has inadvertently shifted everything over toward one side. It can also increase the likelihood of success of future incremental layouts by increasing the minimum amount of space that's available off any one side of the window.

By default, nodes are moved to the center of the canvas automatically after either type of layout. See Visual Graph Options | Layout Options | Center After Full Layout and Visual Graph Options | Layout Options | Center After Incremental Layout. But the window is scrolled to the center automatically only for a full layout.

In the lisp interface, the corresponding function is center-the-graph.

The Select Menu

These commands allowing selecting, highlighting, and pinning nodes.

This menu is present only in the graph view and the graphical query view, and only some of these commands are present in the graphical query view.

Select | Toggle Pinning of the Selected Node

Pins the selected node so that it will not be moved whenever a layout is done. (Pinned nodes may get shifted around as a block in certain cases, but should always remain in the same positions relative to each other.) A node will be drawn with black triangles at its four corners while it is pinned. Applying this command to a node that is already pinned will unpin it.

Two commands that do layouts are exceptions to this rule, and will move and unpin nodes because the relative positions of all of the nodes within the layout is important. Those commands are Layout | Do Tree Layout from Selected Node and Link | Display Only Paths Between Two Nodes.

A shortcut for pinning multiple nodes is to shift-left-click each one (without needing to first select each one). You can also drag the node as usual while the mouse button is down, to pin the node and drag it in one gesture; the node will remain pinned where you drop it. Multiple nodes can be pinned with a single gesture by shift-left-clicking down on the background and then dragging a box downward and to the right that completely surrounds the set of nodes to pin (though without the drag it unpins all nodes).

This command is useful for constraining a layout so that it keeps certain nodes in particular desired places. It can also be useful for influencing how an incremental layout behaves, especially to improve a layout that has a few problems. For example, if you simply drag a node to a new location (especially a node that has multiple links) and then do an incremental layout, the node that you dragged will typically jump back near to its linked nodes. If instead you pin the node after dragging it, that will prevent it from jumping back near to where it had been, and instead will cause its linked nodes to tend to move nearer to the dragged node. In this way you can influence where a group of linked nodes is likely to end up by dragging and pinning only one of them (or perhaps a few of them).

This command is present only in the graph view and the graphical query view.

Select | Remove All Node Pinning

Unpins all currently pinned nodes. A shortcut is to shift-left-click the background (that is, the window interior where there is no node or link line).

This command is present only in the graph view and the graphical query view.

Select | Toggle Highlighting of the Selected Node or Link

Highlights the selected node or link, or unhighlights it if it is already highlighted. A node is highlighted by drawing it with a thick blue border, similar to the thick red border of the single selected node. A link is highlighted by drawing it in red. A node or link will remain highlighted when it is no longer the single selected node or link. You can therefore highlight multiple nodes by selecting various nodes and using this command on each one.

A shortcut for highlighting multiple nodes and links is to control-left-click each one (without needing to first select each one). And you can remove all highlighting by control-left-clicking the background. Multiple nodes can be highlighted with a single gesture by control-left-clicking down on the background and then dragging a box downward and to the right that completely surrounds the set of nodes to highlight. (On the Mac use the command key here rather than the control key.)

This command is useful for marking nodes and links that are of interest so that you can spot them easily again after the layout changes (especially after doing a Layout | Redo Layout from Scratch, which totally rearranges all of the nodes).

You can also drag all of the highlighted nodes as a group by dragging any one of them. Just left-click down on any highlighted node and move the mouse while the left mouse button is still down to drag them all. (An exception is that if the dragged node is also the single selected node (as indicated by a thick red border), then only the selected node will be dragged.)

Some commands will be applied to all highlighted nodes whenever there are any (though in some cases only when there is also no selected node). These commands include Link | Display Linked Nodes for the Current Predicates, Link | Display Paths Between Two Nodes, Remove | Remove Selected Node, Remove | Exclude Selected Node, View | Copy, and File | Export Displayed Data As | NodeURIs.

This command will highlight the selected link line only if there is one and there is not also a selected node at the time, or if you control-left-click the link directly. (On the Mac use the command key here rather than the control key.)

The current highlight state of a node or link will still be shown in all View | Go Back and View | Go Forward states that you revisit. If you lose track of a node or link after a layout, you could go back to a previous state where you remember the position of the node, then highlight it and go forward to the newer state to spot it by its highlighting.

See also Graph View Legend Node | Highlight Matching Nodes.

This menu command corresponds to the lisp function highlight-node-by-upi.

This command is present only in the graph view and in the graphical query view.

Select | Remove All Node and Link Highlighting

Unhighlights all currently highlighted nodes and links. A shortcut is to control-left-click the background (that is, the window interior where there is no node or link line). (On the Mac use the command key here rather than the control key.)

This menu command corresponds to the lisp function remove-all-highlighting.

This command is present only in the graph view and in the graphical query view.

Select | Highlight All Nodes

Highlights all of the nodes that are currently displayed, and deselects the single selected node if there is one. You could then use one of the commands that get applied to all highlighted nodes (see Select | Toggle Highlighting of the Selected Node or Link) to apply that command to all of the displayed nodes.

Select | Copy Highlighted to Graphical Query View

Copies any currently highlighted nodes, along with any link lines that connect two highlighted nodes, over to the graphical query view. You can then turn those nodes and links into a graphical query by converting some of the copied nodes and links into variables. (Two non-variable nodes that are linked with a non-variable link will produce no results in a query other than the single triple that those objects explicitly represent.)

The nodes will initially be placed near the mouse cursor, and then shifted as needed to avoid overlapping with nodes that were already in the graphical query view.

The copied nodes and links will be added to any nodes and links that are already in the graphical query view, so if you want to start another query then you may want to first use the command Remove | Remove All Nodes in the graphical query view to clear it for a new query.

When copying additional nodes, you may want to first use Select | Remove All Node and Link Highlighting to clear all currently highlighted nodes and links, which you can do by control-left-clicking the background. Then control-left-click each node to be copied, or control-left-click-down-and-drag to highlight a group of nodes, and then use this command to copy them over to the graphical query view. (On the Mac use the command key here rather than the control key.)

After copying nodes and links to the graphical query view, you will probably want to turn some of them into variables. You can do that by right-clicking a node or link and selecting one of the commands for that. See Graphical Query Non-Variable Node | Convert to Variable Node, Graphical Query Non-Variable Node | Convert to Variable with Types, and Graphical Query Link | Specify Predicate Variable. The node command to convert it to a variable "with types" may be especially useful, for example turning the node for a particular film into a variable that matches any node of type film.

An alternative is to use View | Copy in the graph view to copy the set of highlighted nodes, and then View | Paste in the graphical query view to paste the copied nodes there. But that approach will never copy links (even if they are highlighted), whereas this approach will copy any links between highlighted nodes (and you don't need to first highlight them).

Select | Deselect the Selected Node and/or Link

Deselects the currently selected node if there is one, and also the selected link if there is one. Altenately you can click the background, though this command's keyboard shortcut (the spacebar) may be more convenient when you don't have a hand on the mouse.

Like many of the commands, this one interrupts the layout if one is currently being done. Therefore, pressing the spacebar can be a convenient way to interrupt the current layout and deselect the selected node. In particular, if an incremental update is being done automatically at the end of some command, then you could press the spacebar and then R (the shortcut for Layout | Redo Layout from Scratch) to interrupt the incremental layout and do a full layout instead.

If the keyboard focus is in a table rather than in the graph view, then the keyboard shortcut for this command, which is the spacebar, does not invoke this command and instead emulates a mouse click in the table cell that has the keyboard focus.

This command is present only in the graph view.

Select | Reselect Previous Node and Link

Reselects the node and link that were most recently selected, if any, and otherwise selects an arbitrary node and/or link. This provides a keyboard way of selecting a node or link as required by various other commands.

This command also scrolls the selected node into view, and so it could be used when a node is already selected to bring it into view.

Select | Reselect a Recent Node

Lets you reselect a recently-selected node by choosing it from a pop-up menus that appears. This may be handy for quickly reselecting a node and then applying a command to it with a keyboard shortcut.

The 25 most recently selected nodes will be listed, with the most recently selected ones first. The one that you choose will get scrolled into view if needed.

Select | Rotate to Next Link Clockwise

Selects the next link clockwise from the currently selected link extending from the selected node. If no node is currently selected, then the previously selected node (or an arbitrary node if none) is first selected. If no link is currently selected, or the selected link is not connected to the selected node, then this command selects an arbitrary link that's connected to the selected node.

This command is typically useful for selecting a link across which to jump to another node with the Leap Across Selected Link command below.

If the legend pane has the keyboard focus (as when you press Tab to move it there), then this command will select the next item in the legend.

Select | Rotate to Next Link Counterclockwise

Selects the next link counterclockwise from the currently selected link.

If the legend pane has the keyboard focus (as when you press Tab to move it there), then this command will select the previous item in the legend.

Select | Leap Across Selected Link

Selects the node that is on the other end of the currently selected link from the currently selected node. If no link is currently selected, then the previously selected link (or an arbirary link if none) is first selected. If no node is currently selected, or that node is not connected to the selected link, then this command arbitrarily selects one of the nodes that are connected to the selected link.

This command and the Rotate to Next Link commands just above provide a way of selecting various nodes with the keyboard rather than the mouse. When working with nearby nodes and/or using a laptop without a mouse, this could perhaps be faster than using the mouse or laptop touchpad, with practice.

If the legend pane has the keyboard focus (as when you press Tab to move it there), then this command will leap from the list of node types to the list of predicates or vice versa.

The Edit Menu

These commands allow you to edit the triple-store by adding and removing triples. They work in conjunction with commands that are on the right-click pop-up menu in the table view.

Edit | Create Node by Type

Creates a new object that has a specified rdf:type, then lets you fill in the values of properties that nodes of that type have. A triple will be created in the store for the type that you select, and other triples will be created if you fill in other suggested property values in the form that appears in the table view.

A pop-up menu will first ask you to select one of the various ways to select a type, and then further prompts will ask you to select the actual type for a new node.

You will next be prompted to specify a URI for the new node. A pop-up menu will likely appear with a set of suggested namespaces, followed by a dialog for entering an IRI string. If you chose one of the suggested namespaces, it will appear in the text-editing widget to facilitate entering the IRI.

Next the new node for the specified URI will be shown in the table view, just as when you use Edit | Edit Selected Node by Type on a node that already exists. The table will show the triple that was created for the selected type, and typically also a set of table rows for predicates that are associated with the type that you specified. Supplying a value for an empty cell in one of these rows will create a triple.

See Edit | Edit Selected Node by Type for information on how the suggested predicates are chosen for the type that you specified.

Right-click an empty cell (or move the keyboard focus to it and press the M key) to see the pop-up menu of editing commands for that cell. In particular, Table View Value Column Editing | Enter a Different Node will let you type in a URI for an empty cell, while Table View Value Column Editing | Select a Different Node will let you select a node that already exists in the store.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Edit Selected Node by Type

Displays the selected node in the table view, and then adds table rows for additional properties that you may want to fill in. Supplying a value in one of these rows will create a triple in the store.

The suggested properties that are offered in the table are found in two ways. One way is collecting a sample of triples for the type that you specified, and seeing what properties the subjects of those triples have. (And also what properties the objects of the triples are values of.) The other way is looking for any predicates that define their rdfs:domain or rdfs:range to be the type that you specified, or any superclass of it. Rows with blank values are added to the table for any such predicates that are found for which the object does not yet have values.

In the graph view and the graphical query view, this command is applied to the currently-selected node, if any. In the query view it is applied to the node cell that has the keyboard focus, if any. In the table view it is applied to the currently displayed object (rather than the node in the table row that has the keyboard focus), and so it will simply add table rows for the node that is already displayed there. This command also appears on the right-click pop-up menu of the table view.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Create a Triple by Linking Nodes

Lets you create a new triple in the store by connecting the selected node to either another node or to a link. Connecting to a second node will create a "regular" triple, while connecting to a link line will create a triple that reifies the triple of that link line.

If there is a selected node when this command is used, then a rubber band line will appear between that node and the mouse cursor to indicate that it is waiting for you to click on a second node or on a link line. If you do click on a second object, then you will be asked to select a predicate. If you select a predicate, then a new triple will be created using the two nodes and predicate that you have sprecified. A new link line will appear that represents the new triple (unless there was already a link line connecting the two nodes, in which case that existing link line will represent the new triple as well).

When asking for a predicate, a first pop-up menu will offer various ways of selecting a predicate from various subgroups of all of the predicates that are in the store. Then further menus will let you select a particular predicate from the subgroup that you selected.

When the second object is a link, the new triple will have the first node as its subject and a triple ID typed node for the object, where the integer value of the triple ID node is the ID of the triple that the selected link line represents. (Except if the link's triple is the only one in its graph, then the object of the new triple will be the graph part of the link's triple rather than its triple-ID part.) If the link line represents multiple triples, a pop-up menu will ask which of the triples should be used. See Reification Support in Gruff.

No automatic layout is done when the new link line is displayed, to avoid disruption as you add a series of triples. This may leave the new link lines overlapping other objects, and so you may want to use Layout | Update Layout Incrementally or Layout | Redo Layout from Scratch when you are done createing triples.

This command is present only in the graph view.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Create a Triple Using Most Recent Predicate

This is the same as Edit | Create a Triple by Linking Nodes, except that it will automatically use the most recently used predicate rather than asking you to select a predicate in two pop-up menus.

This is handy when creating a number of triples that use the same predicate, to avoid reselecting the same predicate every time.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Reverse Triple of Selected Link

Deletes the triple that the selected link line represents, and creates a similar triple whose subject is the object of the old triple and whose object is the subject of the old triple. The arrowhead of the link line will move to the other end of the line to show this change.

This command is present only in the graph view.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Delete Triple of Selected Link or Node

Deletes the triple that the selected link line represents from the store, and removes the link line from the display. If the link line represents multiple triples, a pop-up menu will first ask which triple to delete, and the link line will remain to represent the other triples that are not deleted.

You can use Edit | Undo to re-create a triple that you've deleted. It will not recreate the link line in the graph view, though, because the displayed nodes and links may have partially or fully changed by the time that you undo the triple deletion, and it's not clear in the general case when it might be intuitive to recreate the link line.

This command is present only in the graph view.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Undo

Shows a menu of commands to undo recent triple creation, editing, or deletion. The most recent edits appear toward the top of the menu, with the most recent at the very top.

The commands will undo changes to the store that were done using the right-click pop-up menu in the table view, though an undo can be done in any view or after browsing to a different object in the table. If an undo happens to affect the currently displayed node in the table, then the table will update itself automatically.

Each command briefly indicates what it will do. If the command begins with the word "Recreate", then it will create a triple to replace one that was individually deleted. If it begins with "Restore", then it will create the triple that it mentions as well as deleting another triple that had replaced the deleted triple (see Table View Value Column Editing | Enter a Different Node). If it begins "Delete", then it simply deletes a triple that was individually created. If it begins with "Restore URI", then it creates and deletes a number of triples to restore a URI that was edited with Table View Value Column Editing | Rename the Node.

Once an undo action is performed, it will no longer appear on the undo menu, though a new command to redo the modification that was undone will then appear on the redo menu.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Redo

Shows a menu of commands to redo a recent edit that was undone by using Edit | Undo (or Table View Value Column Editing | Undo).

Once a redo action is performed, it will no longer appear on the redo menu, though a new command to once again undo the edit that was redone will then appear on the undo menu.

This command is not available when browsing a SPARQL endpoint rather than an AllegroGraph triple-store.

Edit | Confirm Triple Deletion

If this option is enabled, as it is by default, then any attempt to delete triples from the store will first display a modal dialog that asks you to confirm the deletion.

Edit | Prompt for Commit on Exit

If this option is enabled, as it is by default, and you attempt to exit Gruff when there are uncommitted edits to the store, then you will prompted for whether to commit the changes before exiting. Alternately you could use File | Commit to commit changes explicitly. If this option is disabled, then the prompt will not appear and no automatic commit will be done.

Unsaved changes generally result from adding, editing, and deleting triples in the table view. Gruff will do a commit automatically, on the other hand, when you use its commands to load triples or create text search indexes.

Edit | Show Menus of Recent Namespaces

When you specify a new node or predicate by typing or pasting its URI, if this option is enabled then you will first be prompted to select a recently-used namespace to facilitate enterying the URI. When it is disabled, the namespace that would have been the first choice in the menu is used automatically.

If the namespace choices are in two groups with a separator line between them, then the upper group are namespaces that are used by other values of the same predicate, with more frequently-used namespaces (in the small sample that is taken) appearing toward the top of the menu. The lower group are other namespaces of nodes that have been browsed recently. The upper group that applies to the same predicate may be more likely to include the desired namespace.

If you don't want to use any of the suggested namespaces, then select the choice at the top for "Other Namespace (or None)". This allows entering a literal or an IRI with some other namespace from scratch.

No namespaces will be suggested or pasted when entering a new value for a property when other nodes that have that property all use literals for the property value.

This option is used by Edit | Create Node by Type and by Table View Value Column Editing | Enter a Different Node.

Edit | Prompt for Label for New Blank Node

If true, then whenever you create a new blank node, you will be further prompted to type in a string for the rdfs:label property of the new blank node. This is a handy shortcut when you are using rdfs:label properties for all blank nodes to make them easily identifiable.

See also Outline Options | Create All Nodes as Blank Nodes for another convenience option when creating blank nodes in the outline view.

Edit | Percent-Decode Characters for Editing

When enabled, editing a URI textually will first convert any non-ASCII characters that are percent-encoded as hexadecimal values using the %xx notation will first be converted to the actual characters to facilitate editing the string. (Percent-encoding is also called URI-encoding.)

This option might be removed in the future in favor of a new utility program for converting percent-encoded non-ASCII characters in triples files. This will allow normalizing triples before adding them to a store, removing the need for Gruff to accomodate irregular data.

Edit | Percent-Encode Non-ASCII After Editing

When enabled, editing a URI textually will convert any non-ASCII characters in the edited URI will be percent-encoded using the %xx format before storing them.

The trend appears to be toward storing non-percent-encoded Unicode characters directly in stores, and so this option is off by default. Turning this option on could result in edited values becoming percent-encoded in the store when they were not before.

When this option is on, a URI that is entered when using Display | Display a Node by URI or Literal will also have its non-ASCII characters percent-encoded to match percent-encoded characters that are in the store.

This option might be removed in the future in favor of a new utility program for converting percent-encoded non-ASCII characters in triples files. This will allow normalizing triples before adding them to a store, removing the need for Gruff to accomodate irregular data.

The Global Options Menu

Options that may affect all Gruff views.

Global Options | Node Label Predicates | Use Label Predicates for Node Labels

When enabled, the label that is displayed for a resource node in various Gruff views and menus will be the skos:prefLabel property of the resource, if it has one, or else the rdfs:label, if it has one. More generally, if you have set up any custom label predicates with Global Options | Node Label Predicates | Custom Predicates for Node Labels, and the resource has any of those properties, then they will be used instead of the resource's skos:prefLabel or rdfs:label property.

When this option is disabled or no label property is found, then a label will instead be derived from a resource's URI according to the options on the Global Options | Derived Node and Link Labels menu. (All of these options will be overridden if the current view's option to display full URIs in that view is enabled.)

It may save time to turn this option off because that will avoid looking up label properties, though the labels that are then derived from URIs may be less meaningful.

Looking up label properties to display will be slower if the user does not have permission on the server to evaluate arbitrary code.

This option is not used when browsing a SPARQL endpoint rather than an AllegroGraph store. Instead, the corresponding option Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels will be used.

Global Options | Node Label Predicates | Use Label Predicates for Predicate Labels

When enabled, the label that is displayed for a predicate in various Gruff views and menus will be the skos:prefLabel or else the rdfs:label property of the predicate, if it has one. More generally, if you have set up any custom label predicates with Global Options | Node Label Predicates | Custom Predicates for Node Labels, and the predicate has any of those properties, then they will be used instead of the predicate's skos:prefLabel or rdfs:label property.

Otherwise this option works like Global Options | Node Label Predicates | Use Label Predicates for Node Labels, except that label properties will be displayed for predicates only when they are also being displayed for nodes.

Predicates are displayed on link lines in the graph view (when Visual Graph Options | Link Labels | Draw Link Labels is enabled), and in the lefthand column of the table view and other places.

Global Options | Node Label Predicates | Custom Predicates for Node Labels

Determines which properties are used for providing values that are displayed as labels to represent nodes.

If a store does not contain skos:prefLabel or rdfs:label properties but it does use some other predicate to specify labels for resources, then you can set this option to be that predicate. Just type or paste the complete URI of the predicate in the dialog that appears for this option. Then any resource that has that custom label property in the triple-store will show that property's value on the node for that resource. (This requires Global Options | Node Label Predicates | Use Label Predicates for Node Labels to be enabled as well.)

You can specify multiple predicates here, one on each line. If a particular node has triples for more than one of the specified predicates, then a label will be formed from the values of all of those properties, with a space between successive values and in the order that the predicates are specified in the dialog. For example, if you specified these two predicates in this order: 

http://franz.com/simple#first-name  
http://franz.com/simple#last-name

then a node that has a first-name property of "Hazel" and a last-name property of "Dickens" would be represented by the label "Hazel Dickens" in various Gruff views.

An alternative to this command that doesn't require you to enter URIs is to right-click a particular predicate in the property column of the table view or in the legend of the graph view, and select "Use as Custom Predicate" from the pop-up menu that appears. See Table View Property Column | Use as Custom Predicate.

If the current store does not define any of your custom label predicates for a particular node, then the skos:prefLabel or else the rdfs:label property will be used instead when present, and otherwise labels will be derived from the node URIs as when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is unchecked.

This option is saved separately for each store, so that Gruff does not spend time looking for triples of predicates that are not used in a store. If you use the same custom predicate in multiple stores, then you will need to specify it in each store.

If you insert a hash/pound/scratch character (#) at the beginning of a line in the dialog, then that predicate will not be used. So you could temporarily comment out some of the predicates in that way, and then remove the hash characters later to use those predicates again.

Global Options | Node Label Predicates | Custom Predicates for Node Comments

Determines which properties are used for providing strings that are displayed as comments in tooltips when you hover over nodes in the graph view or over outline items in the outline view. When no predicates are specified here, rdfs:comment is used by default.

This works like Global Options | Node Label Predicates | Custom Predicates for Node Labels. When multiple predicates are being used, the name of each predicate will be displayed just before its value in the tooltip to tell you which property each value goes with. When there are multiple properties for a node, each one is displayed on a separate line unless any of the values are too long for that, in which case all of the text is wrapped, with a * between properties.

Global Options | Node Label Predicates | Custom Predicates for Node Pixmaps

Determines which properties (if any) are used for providing images to display on some nodes in the graph view. When provided, the images will be displayed instead of the usual label strings.

When a particular node is displayed in the graph view, if there is a triple in the store where that node is the subject, and the predicate is one of the predicates that you specify for this property, and the object's URI or literal string is the name of a pixmap file or is the URL of a pixmap file on the web, then a pixmap will be loaded from that file or web page and displayed for that node.

For example, if you specify the predicate http://franz.com/simple#pixmap_file for this option, and the store contains the following triple: 

http://dbpedia.org/resource/Terry_Jones  
http://franz.com/simple#pixmap_file  
file:///c:/pixmaps/seaside.png

and the file c:/pixmaps/seaside.png contains a valid pixmap, then that pixmap will be displayed in the node box for Terry Jones in the graph view.

The file type may be either png, jpg, or bmp.

The string can be either an absolute path string or a relative path string that will be merged with Global Options | Miscellaneous | Document Base Folder to find the actual file to use. A node that specifies a pixmap file can be either a resource or a literal, and the string can either include a file:/// scheme or not.

Note that the image would be displayed for the seaside.png object node itself even without setting up this option for pixmap predicates. But this option lets you display pixmaps on meaningful nodes themselves rather than on separate linked nodes.

This option is saved separately for each store, so that Gruff does not spend time looking for triples of predicates that are not used in a store. If you use the same custom predicate in multiple stores, then you will need to specify it in each store.

If you insert a hash/pound/scratch character (#) at the beginning of a line in the dialog, then that predicate will not be used. So you could temporarily comment out some of the predicates in that way, and then remove the hash characters later to use those predicates again.

A quick way to find pixmaps to display for nodes is to use View | Web Interaction | Fetch Wikipedia Pixmap from Node Label.

See Displaying Images for Nodes for more information.

Global Options | Node Label Predicates | Custom Predicates for Web Pages

Determines which predicates are used for providing URLs of web pages to visit for nodes in a third-party web browser program.

When you use the command View | Web Interaction | Invoke Web Browser on Node Value, by default Gruff will use the selected node's own IRI (or literal) as the URL of a web page to tell the browser to display. This works only when the values of nodes are actual web URLs. If that's not true for some or all of your nodes, but the nodes have triples that do specify web pages, then you can use this option to point Gruff to those triples. This will work as long as those triples use the same predicate or a small set of predicates. For example, if your store uses a webURL predicate to specify web pages for nodes, and contains triples something like this: 

http://foo.com/tree37   http://foo.com/webURL   http://foo.com/birch.html  
_:b123456               http://foo.com/webURL   http://foo.com/the_larch.html

then you can use this command to specify http://foo.com/webURL as a predicate that supplies web pages. Just enter the full URI http://foo.com/webURL in the dialog that appears.

When you use View | Web Interaction | Invoke Web Browser on Node Value thereafter, Gruff will first check for any webURL triples where that node is the subject, and if it finds one then it will tell your web browser to visit the URL that's supplied as the object of that triple. If there are no such triples for that node, then Gruff will revert to the default behavior of passing the node's own value to the web browser.

You can specify multiple predicates in the dialog, one on each line. If a particular node has triples for more than one of the specified predicates, then the triple for the first matching predicate in this list will be used.

This option is saved separately for each store, so that Gruff does not spend time looking for triples of predicates that are not used in a store. If you use the same custom predicate in multiple stores, then you will need to specify it in each store.

If you insert a hash/pound/scratch character (#) at the beginning of a line in the dialog, then that predicate will not be used. So you could temporarily comment out some of the predicates in that way, and then remove the hash characters later to use those predicates again.

Global Options | Derived Node and Link Labels | Exclude Namespaces from Labels

When checked, the string that appears for a resource in a node or a menu will be only the final descriptive part (local name) of the resource's URI.

When unchecked, a string that indicates the full URI will be shown, though it will always use a namespace abbreviation (as defined by a call to register-namespace) for the first part of the URI. If there is an existing namespace abbreviation mapping that is applicable to the URI, then that one will be used, and otherwise a namespace mapping will be created automatically. The name of an automatically created namespace will be brX, where X is an integer that specifies a unique namespace name. The "br" stands for "browser".

So nodes will always display abbreviations of URIs to save space, and using this option abbreviates URIs further by excluding the namespace abbreviation prefix. Using this option makes the labels more easily readable but may also lead to ambiguities. To see the full URI of a resource, glance at the status bar at the bottom of the window when holding the mouse cursor over a node in the graph view or over a table cell in the table view. Or turn on Visual Graph Options | Node Labels | Show Full URIs on Nodes to display complete URIs directly on nodes themsleves. To see full URIs in the cells of a table, enable Table Options | Show Full URIs in Tables.

This option is ignored for objects that have skos:prefLabel or rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

Global Options | Derived Node and Link Labels | Add Spaces to Labels

When checked, spaces will be added in certain cases to node label strings to make them more easily readable. Additional spaces also allow long node labels to be wrapped to multiple lines at more places within the string (since wrapping is done only at spaces); this may save space in the layout by reducing the maximum dimension of some nodes.

When this option is used, a space will be inserted after any lowercase character that is followed by an uppercase character, which would change "fooBar" to "foo Bar", for example. In addition, any underscore character will be replaced by a space, and a space will be inserted after any colon.

This option is ignored for objects that have skos:prefLabel or rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

Global Options | Derived Node and Link Labels | Collapse Contiguous Spaces in Labels

When checked, any sequence of two or more space characters in a node label string will be replaced by a single space.

This option is ignored for objects that have skos:prefLabel or rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

Global Options | Derived Node and Link Labels | Capitalize First Word

When checked, the first character of any node label is uppercased. This may make labels nicer for human reading if the words in the label are capitalized except for the first word, as in fooBarBaz. Using this option along with Global Options | Derived Node and Link Labels | Add Spaces to Labels would convert fooBarBaz to Foo Bar Baz.

This option is ignored for objects that have skos:prefLabel or rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

Global Options | Derived Node and Link Labels | Convert Percent Encoding in Labels

When checked, any percent-encoded characters in a URI will be converted into the single Unicode characters that they represent when deriving pretty labels to display.

This option is ignored for objects that have skos:prefLabel or rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass"

This is a special hack to cause the rdfs:subClassOf predicate to be printed by Gruff as "Superclass". This may make it easier to recognize the direction of subclass links, especially to avoid the expression "is Sub Class Of of" in the predicate labels that are displayed when [Visual Graph Options | Link Labels | Draw Link Labels] (#VisualGraphOptionsLinkLabelsDrawLinkLabels) is in effect.

Specifically, what would normally appear as "subClassOf" will appear as "Superclass", and what would normally appear as "is subClassOf of" will appear as "Subclass".

Global Options | Namespace Abbreviations

Shows a dialog that contains all registered abbreviations for namespaces. You can edit the mapping of abbreviations to namespaces here. Then you can use the abbreviations in query text in The Query View, or with Display | Display a Node by URI or Literal.

The abbreviations are saved with other options for use in future Gruff sessions. The mappings are global across all stores, rather than specific to each store that Gruff browses.

The mappings that are shown in the static list at the bottom of the dialog are standard mappings that are always defined, and so you don't need to add them to your own list.

Global Options | Select Current Predicates

Allows you to modify the set of "current predicates". This set of predicates primarily determines which nodes are displayed by Link | Display Linked Nodes for the Current Predicates in the graph view or the outline view. In the graph view, the current predicates are also used by Link | Display Paths Between Two Nodes. And in the graphical query view, selecting a predicate from the set of current predicates will be one choice when using Graphical Query Link | Specify Predicate.

A dialog is shown that contains a list of predicates. The list contains all of the predicates of the triples of the nodes that have been displayed so far for the current triple-store during the current Gruff session. Except if you have enabled Global Options | Include All Predicates as Choices for the current store, then all predicates are listed.

You can toggle multiple predicate names on and off by simply left-clicking each one on the Windows platform, or by control-left-clicking on any platform. You can select a contiguous series of predicates by left-clicking the one at one end of the series and then shift-left-clicking the one at the other end. The "Select All" and "Deselect All" buttons below each outline can be used to either select or deselect all of the predicates in either list.

Selecting all predicates typically causes many nodes and links to be added by Link | Display Linked Nodes for the Current Predicates, so it's usually better to select only particular predicates of interest to reduce clutter in the layout.

In the table view and in the results table of the query view, current predicates are indicated with a yellow background. In the outline view, the arrow icon of a node will be solid if there are other nodes that are linked with that node by the current predicates, and which can be shown by "opening" that outline item; otherwise the arrow icon will be hollow.

In the lisp interface, the corresponding function is set-current-predicates.

Global Options | Use a Recent Set of Current Predicates

Lets you reselect a set of current predicates that you have used recently in the currently open store. A pop-up menu will appear that lists the most recently used sets of predicates. This allows quickly reselecting frequently used sets of predicates without needing to select each individual predicate in the Global Options | Select Current Predicates dialog every time.

Global Options | Include All Predicates as Choices

This option determines how many choices will be shown by Global Options | Select Current Predicates in the dialog for selecting current predicates. When disabled, the choices are limited to the predicates of the triples of the nodes that you have browsed over so far. When enabled, all predicates that are in the store are listed as choices.

This option is off by default, to avoid listing many choices for a store that uses many predicates, when typically you would care only about a smaller subset of predicates that are used by the nodes that you are browsing at the time. But if a store does not use a large number of predicates, then it may be best to turn this option on.

Turning this option on may cause a small delay the first time you invoke Global Options | Select Current Predicates, as Gruff asks the server for all predicates that are in the store. But it can avoid repeated small delays when Gruff otherwise often asks the server for the predicates of triples of nodes that you display, to accumulate predicate choices as you browse.

This option value is remembered separately for each store that you browse. So you can enable it for some stores but not others, and the value for each store will be remembered whenever you reopen it later.

Global Options | Pop-Up Menus | Maximum Menu Label Length

This is the maximum number of characters that will appear in any string that appears on a pull-down or pop-up menu. If a string is longer than this, then it will be truncated and an ellipsis will be shown at the end to indicate that it has been truncated. The purpose is to prevent menus from being overly wide.

Global Options | Pop-Up Menus | Show Full URIs in Pop-Up Menus

When checked, any pop-up menus that list nodes or predicates will display the complete URIs for those objects rather than short labels. This also affects the list of predicates in the dialog that's shown by Text Search | Edit the Current Text Index (and by Text Search | Select or Create a Text Index when creating a new text index).

Global Options | Pop-Up Menus | Case-Sensitive Sorting for Menus

When checked, lists of nodes and predicates that are presented in menus and dialogs will be sorted in a case-sensitive way, and otherwise will be sorted in a case-insenstive way. The case-sensitive option would sort information that's being cached more quickly, thereby reducing delays, but would make some menus longer by causing them to have separate sections for items that begin with uppercase or lowercase letters.

Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

Global Options | Class Outline | Automatically Indicate Childless Classes

When enabled, showing additional subclasses in the outline that's displayed by Display | Display an Instance Node by Class Hierarchy will automatically show a hollow arrow for classes that have no subclasses. This helps you avoid wasting time by trying to open outline items that will not open, but it takes extra time to fetch this information from the server. When disabled, you can press the Update Annotations button to show these hints only you choose.

When multiple predicates are selected, hollow versus solid arrows are not shown because other icons are used instead to show which triples use which predicates. But the plus/minus icons will go away for classes that have no subclasses, in place of showing hollow arrows.

Global Options | Class Outline | Automatically Indicate Instanceless Classes

When enabled, showing additional classes in the outline that's displayed by Display | Display an Instance Node by Class Hierarchy will automatically gray out classes that have no instances. This helps you avoid wasting time by selecting a class that will offer no instances to display, but it takes extra time to fetch this information from the server. When disabled, you can press the Update Annotations button to show these hints only you choose.

Global Options | Maximum Choices When Selecting a Subset

When a command asks you to select a subset of the matches that it has found for possible display, this is the maximum number of choices that it will present in a dialog that lists the choices in alphanumeric order and lets you select any portion of them. Additional choices will not be included in the list. Such dialogs are typically shown when the number of found choices exceeds some other option value that triggers a warning dialog, where the warning dialog has an option for selecting a subset.

This can arise when using Link | Display Linked Nodes for the Current Predicates, Link | Display Paths Between Two Nodes, Text Search | Find and Display Nodes, and similar commands, as well as when generating a visual graph from query results in the query view.

Global Options | General Triple-Fetching Limit

This is the maximum number of triples that will be found whenever Gruff asks for all of the triples where a particular node is either the subject or the object. Gruff generally asks for that set of triples whenever it first needs to find any of the triples for a node, and then uses that set of triples for the node thereafter. If the node has more triples than this limit allows, then Gruff will behave as if there are fewer triples for the node than there really are. This limit is also used for other calls to the server for fetching triples.

Specifically, when this limit is hit when fetching all of the triples for a node, Gruff will then individually fetch triples for each predicate of the node's triples, so that all of the predicates are represented in the set of triples that Gruff browses for the node. The set of triples for each predicate will then be limited by Table Options | Maximum Triples Per Predicate in Table. If there may be more triples than that on the server, then the text fetch more triples will appear just under the predicate name in the table view, and you can click that text to fetch and display any additional triples for that predicate of the displayed node.

Ideally you would always want all triples to be returned and considered, but that might take an unacceptable amount of time when there are a huge number of triples, especially when using a remote server. To ensure that all triples are always found, you could set this option to a very large number.

Changing the value of this option will cause much of the cached information that has been collected about triples that exist in the store to be uncached (by calling uncache-for-modified-triple-store), and so for efficiency reasons the value shouldn't be changed needlessly while browsing a store.

This option is not used when you are browsing a SPARQL endpoint rather than an AllegroGraph store. Instead, the option Global Options | SPARQL Endpoints | General Triple-Fetching Limit will be used.

Global Options | Node Label Type | Use Label Predicates for Node Labels

This is a copy of Global Options | Node Label Predicates | Use Label Predicates for Node Labels, to group all node label type options on a single menu.

Global Options | Node Label Type | Use Label Predicates at SPARQL Endpoints

This is a copy of Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels, to group all node label type options on a single menu.

Global Options | Node Label Type | Show Full URIs in the Table View

This is a copy of Table Options | Show Full URIs in Tables, to group all node label type options on a single menu.

Global Options | Node Label Type | Show Full URIs in the Outline View

This is a copy of Outline Options | Show Full URIs in Outline, to group all node label type options on a single menu.

Global Options | Node Label Type | Show Full URIs on Nodes

This is a copy of Visual Graph Options | Node Labels | Show Full URIs on Nodes, to group all node label type options on a single menu.

Global Options | Node Label Type | Show Full URIs in Pop-Up Menus

This is a copy of Global Options | Pop-Up Menus | Show Full URIs in Pop-Up Menus, to group all node label type options on a single menu.

Global Options | Fonts | Increase Font Size

Increments the size of the fonts that are being used in the currently selected view.

When running Gruff in a web browser, an alternative is to use the usual browser commands to zoom (scale) everything in the interface, rather than just the fonts. The keystrokes for those commands are typically Control+Plus, Control+Minus, and Control+Zero, which make everything larger, smaller, or the canonical size respectively.

Global Options | Fonts | Decrease Font Size

Decrements the size of the fonts that are being used in the currently selected view.

Global Options | Fonts | Status Bar Font

This is the font that is used for status messages at the bottom of the window. A larger font is easier to read but fits less text into the single text line of the status bar.

Global Options | Fonts | Widget Font

This is the font that is used in miscellaneous widgets and the hints in tables. This generally includes any text that is not covered by more specific font options such as Visual Graph Options | Node Labels | Node Label Font, Visual Graph Options | Link Labels | Link Label Font, Global Options | Fonts | Status Bar Font, Visual Graph Options | Tooltips | Tooltip Font, Table Options | Table Property Name Font, Table Options | Table Property Value Font, and Query Options | Query Text Font.

Changing this font may not take effect in modal dialogs that have already been created, until you restart Gruff.

Global Options | Fonts | Node Label Font

This is a copy of Visual Graph Options | Node Labels | Node Label Font, to group all of the font options on a single menu.

Global Options | Fonts | Link Label Font

This is a copy of Visual Graph Options | Link Labels | Link Label Font, to group all of the font options on a single menu.

Global Options | Fonts | Tooltip Font

This is a copy of Visual Graph Options | Tooltips | Tooltip Font, to group all of the font options on a single menu.

Global Options | Fonts | Boundary Date Font

This is a copy of Visual Graph Options | Time Bar | Boundary Date Font (for the time bar), to group all of the font options on a single menu.

Global Options | Fonts | Table Property Name Font

This is a copy of Table Options | Table Property Name Font, to group all of the font options on a single menu.

Global Options | Fonts | Table Property Value Font

This is a copy of Table Options | Table Property Value Font, to group all of the font options on a single menu.

Global Options | Fonts | Query Text Font

This is a copy of Query Options | Query Text Font, to group all of the font options on a single menu.

Global Options | Fonts | Outline Font

This is a copy of Outline Options | Outline Font, to group all of the font options on a single menu.

Global Options | Fonts | Input Font

This is a copy of Evaluation Options | Input Font (for the lisp evaluation view), to group all of the font options on a single menu.

Global Options | Fonts | Output Font

This is a copy of Evaluation Options | Output Font (for the lisp evaluation view), to group all of the font options on a single menu.

Global Options | Timeouts | Query Timeout

This is a copy of Query Options | Query Timeout, to group all of the timeout options on a single menu.

Global Options | Timeouts | Text Search Timeout

This is a copy of Text Search | Text Search Timeout, to group all of the timeout options on a single menu.

Global Options | Timeouts | Path-Finding Timeout

This is a copy of Visual Graph Options | Finding Paths Between Nodes | Path-Finding Timeout, to group all of the timeout options on a single menu.

Global Options | Timeouts | Filling In Links Timeout

This is the number of seconds that Gruff will allow for filling in additional links when new nodes are added to the display, giving up if it doesn't finish within that time. This is similar to the command Link | Fill In All Links for the Current Predicates, where Gruff looks for any triples where the subject and object nodes are already displayed, and the predicates are in the current predicates. When it finds such triples, it adds link lines to the display for them.

This is done automatically at the end of other commands that add nodes to the display, mainly to show links that exist between the newly-displayed nodes and the already-displayed nodes (by the current predicates). To prevent this automatic filling in of additional links altogether, set the value of this option to zero.

Global Options | Timeouts | Image-Fetching Timeout

This is the number of seconds that Gruff will allow for fetching an image from the web, typically for displaying on a node. See Displaying Images for Nodes.

Global Options | Timeouts | General Triple-Fetching Timeout

This is the number of seconds that Gruff will wait for the server to reply to any request that's not covered by more specific (and normally shorter) timeouts.

If this timeout is exceeded, Gruff will quietly behave as if there were no triples on the server for the request. This can be misleading, and so this option normally should be a relatively long time whose sole purpose is to prevent Gruff from hanging indefinitely when the server is not responding adequately.

User queries in the query view are not subject to this timeout, and are subject only to Query Options | Query Timeout instead. So if you set that timeout to a large value for complex user queries, you do not need to also set this timeout to a large value.

Global Options | Timeouts | Bulk Property-Fetching Timeout

To save time, Gruff sometimes uses a single query to ask the server for the label properties or types of a group of nodes. This option is the number of seconds that Gruff will wait for the server to reply. If this time is exceeded, then Gruff will abandon that query and revert to looking up those properties individually later as needed.

Since the information is retrieved in other ways if this timeout is exceeded, it is safe to set it to a relatively low value. That will prevent what is usually an optimization from using up excessive time if it turns out not be efficient in some cases.

The problem is that you are not told when this timeout is exceeded, because Gruff silently reverts to more basic approaches, and so the value of this option could be optimized only by trial and error. Normally the default value shoud be fine.

Global Options | Timeouts | Endpoint-Testing Timeout

This is the number of seconds that Gruff will wait for a SPARQL endpoint to reply to a trivial test query when you are connecting to a SPARQL endpoint with File | Connect to SPARQL Endpoint.

The test query should not take much time, so this option can be a relatively short time to avoid hanging up Gruff for a little while when the requested endpoint does not really exist or is currently unresponsive.

Global Options | Timeouts | Finding All Types Timeout

This is the number seconds before Gruff's initial attempt to find and cache all types in the store will give up and display a warning dialog about a timeout. This search will be done automatically the first time you use the command Display | Display an Instance Node by Type or Display | Display a Type Node by Type, and perhaps at other times.

An error dialog will be shown if this timeout is exceeded. If it is worth waiting longer for the commands that are affected by this timeout, then you can set this particular option to a longer time and try again.

Global Options | Timeouts | Finding All Predicates Timeout

This is the number seconds before Gruff's initial attempt to find and cache all predicates in the store will give up and display a warning dialog about a timeout. This search will done you edit a text search index, to provide a list of all predicates that allows you to chose which ones to index. It will also be done when adding a non-variable link in the graphical query view and choosing the option to select a predicate from all predicates, or if you create a triple and choose the similar option.

Finding all predicates may be slower if the user does not have permission on the server to evaluate arbitrary code.

An error dialog will be shown if this timeout is exceeded. If it is worth waiting longer for the commands that are affected by this timeout, then you can set this particular option to a longer time and try again.

Global Options | Timeouts | Finding All Graphs Timeout

This is the number of seconds before Gruff's attempt to find all of the graphs in the store will give up and display a warning message. Gruff will look for all of the graphs whenever you View | Browse a Single Graph or Display | Display Triples of One Graph.

An error dialog will be shown if this timeout is exceeded. If it is worth waiting longer for the commands that are affected by this timeout, then you can set this particular option to a longer time and try again.

Global Options | SPARQL Endpoints | General Triple-Fetching Limit

This option applies only when browsing a SPARQL endpoint rather than an AllegroGraph store.

This is the maximum number of results that Gruff will ask for when it internally queries a SPARQL endpoint as you browse. It does not apply to the SPARQL queries that you write yourself in the query view or graphical query view, where you need to specify the limit in your query.

When browsing an AllegroGraph store, the option Global Options | General Triple-Fetching Limit is roughly equivalent to this option for SPARQL endpoints.

This separate option is provided in case you want to use a smaller limit with SPARQL endpoints where turnaround may be slower.

Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels

This option applies only when browsing a SPARQL endpoint. When browsing an AllegroGraph store instead, see Global Options | Node Label Predicates | Use Label Predicates for Node Labels.

When enabled, the labels that are displayed for nodes in the various Gruff views will be the rdfs:label and/or skos:prefLabel properties for any nodes that have them. More generally, if you have set up any custom label predicates with Global Options | Node Label Predicates | Custom Predicates for Node Labels, and the resource has any of those properties, then they will be used instead of the resource's rdfs:label property. This overrides the options for deriving labels directly from URIs and literal strings.

This option is off by default because looking up label properties typically increases the browsing time significantly with SPARQL endpoints. The corresponding option for AllegroGraph stores is on by default because there are optimized ways for retrieving the label properties of a group of nodes at once. This separate option is supplied so that it can remain off while the other option remains on, though you may want to test turning this one on to see if browsing is still fast enough. It may be needed at a SPARQL endpoint that contains nodes whose URIs do not contain meaningful names.

Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color

This option applies only when browsing a SPARQL endpoint rather than an AllegroGraph store.

When this option is enabled, and a node has multiple rdf:type properties, then Gruff will attempt to find the "most specific" type of the node and then color the node to indicate that type. When this option is disabled, Gruff will arbitrarily choose one of the node's types. The most specific type is defined as the one that has the longest chain of superclasses above it, using the subClassOf predicate.

This option is off by default because it typically requires more additional time than it is worth when using a SPARQL endpoint. But the corresponding option that's used with AllegroGraph stores is on by default because the added time is typically not very significant. That option is Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color.

Another option for controlling which types are used for node colors is Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color. That technique should not have a significant time cost.

Global Options | SPARQL Endpoints | Maximum Sample Triples to Display

When browsing a SPARQL endpoint rather than an AllegroGraph store, this is the maximum number of triples that will be displayed by Display | Display Some Sample Triples and by Display | Display Triples of One Graph. The default is rather small for SPARQL endpoints due to the number of round trips to the endpoint that are required.

When browsing an AllegroGraph store the option Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display is used instead.

Global Options | SPARQL Endpoints | Search Only the Default Graph

This option applies only when browsing a SPARQL endpoint rather than an AllegroGraph store.

When various commands fetch triples to display from the endpoint server, if this option is enabled then only the default graph will be searched, rather than also all named graphs as usual.

If the particular endpoint server includes the triples of all graphs in the default dataset for SPARQL queries, then all triples will still be browsed and so this option will have no effect. That behavior appears to be atypical.

If View | Browse a Single Graph is being used to browse a single named graph, then this option has no effect and that single graph will still be browsed as usual.

Global Options | SPARQL Endpoints | Parameter String for All Queries

Some brands of SPARQL endpoint server allow passing various parameters in addition to the main query parameter. For example, Stardog allows passing "reasoning=true" (without the quotation marks). If you set the value of this option to be the text reasoning=true, then that will be added to all queries that are sent to SPARQL endpoints, and when you are browsing a Stardog endpoint it will make use of the value.

The value should have the general form foo=3&bar=4&baz=5, with ampersands between the parameters. But do not include an initial ampersand, because Gruff will add that one itself between the query parameter and this option value when it is not empty.

Global Options | Communications | Start HTTP Server

Starts up a server to handle requests that are made to Gruff from external software via the HTTP protocol. About 30 commands have been implemented to either perform actions such as displaying an arbitrary set of triples or doing a query, or to simply return information such as the name of the store that Gruff currently has open, if any, or the URI of the currently selected node in the graph view.

When Gruff is running as a desktop application, this menu command will ask for the port at which the server will listen for requests, where the default port is 8000. When Gruff is running in a web browser instead, Gruff's HTTP server will share the web server that Gruff itself is using, along with its port. In either case, Gruff's title bar with then say "Listening on port xxxxx", where xxxxx is the port. Thereafter, external software can control Gruff by sending HTTP requests to that port on the host where Gruff is running.

The HTTP server can alternately be started up automatically when Gruff starts up by passing an --http-server-port (or -t) command line argument with an integer value for the port to use, as follows (the .exe applies only to the Windows platform): 

gruff.exe --http-server-port 8008

Specifying 0 (zero) for the port will allow the operating system to choose a port that it knows to be free, which is safer than specifying a port that might be in use by other software.

When Gruff is running in a web browser, its HTTP server will not actually use the --http-server-port value, and will instead use Gruff's general web server port, but you still must pass this option with some arbitrary value (such as zero) to start Gruff's HTTP server automatically at startup time. Gruff's general web server port can be specified with the --browser-server-port command line option, though the safest approach is to instead use the --port-file option and then read from that file the port that the operating system chose because it knew that port to be free. See Running Gruff in a Web Browser.

For the particular HTTP requests that can be made to Gruff, see the section entitled The HTTP Interface to Gruff.

Here's another option if you want to control Gruff exclusively by HTTP commands remotely, and to prevent the user from controlling Gruff interactively. All pull-down and pop-up menu commands, including their keyboard shortcuts, can be disabled by passing the --disable-menus command line argument, with no value after it. The menu bar will then not be added to the Gruff window at all, and no pop-up menus will appear.

Global Options | Communications | Use Dedicated Sessions

When enabled, the AllegroGraph server will handle the interaction for an open triple-store in a dedicated process that is used only for that session. A dedicated session process also uses a port that is used only for that session. This is not the port that you use to connect to the AllegroGraph server, and the session port is assigned arbitrarily by the server.

This option is enabled by default because it may be more efficient, though it can be a problem if the client machine that Gruff is running on is behind a firewall that is allowing communication only on specific ports such as the main AllegroGraph server port. One solution is to turn this option off, so that all communication will be done using the main server port. An alternate solution that still allows a separate session port to be used is described under A Note About Dedicated Session Ports and Firewalls.

If you are using port forwarding to a remote server, you will probably need to turn off this option as well as Global Options | Communications | Use Direct Access When Possible.

If you use federations, then note that SPARQL queries cannot be done in a federation unless dedicated sessions are used. This includes SPARQL queries that some Gruff commands do internally.

Global Options | Communications | Use Direct Access When Possible

When enabled, if you create or open a store using a server that's running on the local machine, then the connection to the server will use direct access rather than communicating via HTTP as usual.

Sometimes direct access is referred to as "local" mode and HTTP communication as "remote" mode, though the HTTP approach can still be used when the server is the local machine.

If you are using port forwarding to a remote server, you will probably need to turn off this option as well as Global Options | Communications | Use Dedicated Sessions.

Direct Access is never used in secure mode, such as when Gruff is run from AGWebView, for security reasons when Gruff is running on an AllegroGraph server machine.

Global Options | Communications | Warn on Version Mismatch

When enabled, a warning dialog is shown if you open a triple-store on a server whose AllegroGraph version does not match the version of the lisp client on which Gruff is built. This could be turned off if a minor version difference happens to work, to avoid the nuisance.

Global Options | Communications | Use Digest Authentication

This option matters only when using a SPARQL endpoint and it requires a username and password.

When enabled, all HTTP requests to SPARQL endpoints will use digest access authentication. Otherwise the less secure basic access authentication will be used.

Global Options | Communications | HTTP Proxy

If you are behind a firewall that uses an HTTP proxy, then you can enter the proxy information in the dialog that this option command shows. Then later when you use the dialog for opening a triple-store or connecting to a SPARQL endpoint, the server and port that you specify there should reflect the way that the proxy machine sees the triple-store server machine. A "Use HTTP Proxy" check box on those dialogs allows quickly toggling whether to use the proxy that you set up with this command.

The server field should be an Internet domain name of the form franz.com. The port field should be an integer like 8000.

The server and port fields are always needed for an HTTP proxy, and the user name and password fields may or may not be needed. The server, port, and user name will be saved in your Gruff options file and reused in future Gruff sessions. The password will not saved in the options file for security reasons, though, so if you have supplied a user name then this dialog will appear in a later Gruff session whenever the information is first needed, to let you fill in the password again. If you do not supply a password at that time, then the user name will not be used thereafter either.

To remove previously-specified proxy information, edit these fields to contain no text.

Global Options | Communications | Use any23.org for RDFa

Whether the command File | Extract Microformat/RDFa Data from Web Page will use the web site any23.org for extracting triples from the web page, as opposed to a custom technique. The any23 technique alternately works on microdata. Yet each technique may find triples that the other does not.

Global Options | Communications | Ignored RDFa Relationships

This option is used only if Global Options | Miscellaneous | Use any23.org for RDFa is disabled.

This is a list of HTML relationship attributes that will be skipped by File | Extract Microformat/RDFa Data from Web Page. You can select one or more attributes here to exclude some types of triples from the set that is collected, to avoid cluttering up the graph of all of the extracted triples.

For example, selecting "stylesheet" will avoid collecting triples for HTML links to .css web pages.

Global Options | Miscellaneous | Warm Up the Store

Brings as much internal data as possible into physical memory for fast access thereafter. Alternately, this can be done when opening the store by using two check boxes on the store-opening dialog.

Warming up will be done in a background process, to allow you to proceed browsing while it is happening. The only indication that will be given when the warmup has finished will be a message in the status bar at the bottom of the window, saying something like "WARMED UP the store for triples and strings".

Global Options | Miscellaneous | Run in Web Browser

On macOS and Windows, the start up mode is hardwired based on the method of invocation (Windows) or download selected (macOS). This option is only useful on Linux.

Whether Gruff will run inside a web browser, rather than as a GTK application (on Mac or Linux) or a Windows application.

After toggling this option, you will need to restart Gruff for it to run in the new mode. The option value will be sticky thereafter as you run Gruff multiple times, until if and when you toggle this option again.

You can also pass a command line argument to override this option value. See Running Gruff in a Web Browser.

If GruffJS should fail to start after toggling this option so that Gruff no longer runs in its default mode on your platform, then you would need to revert this option to its default before you can start Gruff interactively again. You could do that by deleting the file ~/.gruff.d/gruff-startup-options.txt, which solely stores the value of this option, and then running Gruff again. Alternately, you could use a command line argument to start Gruff in the default mode, and then change this option to match that mode (so that it continues to start up in that mode in the future). To do that, pass the --run-as-web-browser-server command line argument to match the default mode, as described at Running Gruff in a Web Browser.

Global Options | Miscellaneous | Confirm Exit

If this option is enabled, as it is by default, then attempting to exit Gruff will show a dialog asking you to confirm that you really want to exit.

Global Options | Miscellaneous | Confirm Closing Stores

When enabled, if you open or create a store or connect to a SPARQL endpoint while an AllegroGraph store is open, Gruff you first show a dialog asking whether it's OK to first close that store. If you agree, then Gruff will close that store and proceed. Otherwise the new operation will be canceled. Gruff can browse only a single open store at any time.

Global Options | Miscellaneous | Preferred Language

Gruff uses this option to select which literals to display when a node has multiple values in different languages for a particular property, but not all languages are being displayed. Not all languages are displayed either when certain options for displaying all languages are turned off or when only a single value can be displayed as a label or tooltip.

The value is typically a standard two-character language tag such as "en" for English or "jp" for Japanese, but it can be any text value at all. Several common languages can be chosen directly from this child menu. If the desired language is not in the menu, then select the "Other" choice at the bottom of the menu and enter the desired language tag into the dialog that appears.

In the graph view, commands in the Link menu will not display literals that have language tags other than the selected one unless Visual Graph Options | Inclusion Options | Include Literals of All Languages is on.

The table view will not show literals that have language tags other than the selected one unless Table Options | Display Literals of All Languages is on.

When Global Options | Node Label Predicates | Use Label Predicates for Node Labels is on, then the labels that are displayed for nodes are the skos:prefLabel properties or else the rdfs:label properties (by default) of the nodes when they exist. Gruff will use a skos:prefLabel or an rdfs:label property for a node label only if the value is a literal that either has no language tag or has the language tag that is currently selected here.

Similarly, when Gruff displays a tooltip for a node or link, it uses the rdfs:comment property (by default) to provide the tooltip text, and it will use only an rdfs:comment property that has either no language tag or this language tag. See Global Options | Node Label Predicates | Custom Predicates for Node Comments.

If Global Options | Miscellaneous | Preferred Language for This Store in a particular triple-store is a language tag rather than Default, then that language will be used instead of this global one for that triple-store.

Global Options | Miscellaneous | Preferred Language for This Store

If a language tag is selected here, rather then the initial "Default" value, then it will be used for this particular triple-store, overriding the global Global Options | Miscellaneous | Preferred Language. Specifying a language here for an occasional triple-store that does not use the usual preferred language avoids needing to set the global option value each time you open that triple-store.

[Global Options | Miscellaneous | Borrow from Related Languages]

When this option is on and a node does not have a label property for the Global Options | Miscellaneous | Preferred Language for This Store but it does have one for a language that's related to that one, then that label for a related language will be displayed for that node when Global Options | Node Label Predicates | Use Label Predicates for Predicate Labels is also on.

Related languages are ones whose language tags begin with the same characters up to the first dash, if any, such as "en" and "en-us" and "en-uk". This option increases the chances of meaningful labels being shown for nodes, without displaying labels for languages that are unrelated to the user's preferred language, which the user would likely not know how to read.

Global Options | Miscellaneous | Treat Literals as Objects

When enabled, Gruff will treat any literal node as an object that is linked with every node that has that literal as a property value. Otherwise, multiple nodes that have a same literal property value are not considered to be related to each other.

This has a special effect in the graph view. For example, if you display the nodes for two people and also the nodes for their ages (where the age values are literals), and the people are both 37 years old, then Gruff will use separate node boxes for the two age 37 literals when this option is disabled. But if this option is enabled, then a single age 37 node box will be displayed, with two link lines connecting that single node box to the ones for the two people.

Enabling this option is also needed in order to apply certain other commands to a literal node, such as displaying all of the triples for a literal in the table view, or using Link | Display Linked Nodes on a literal in the graph view.

Changing the value of this option while a store is open requires Gruff to clear everything that is currently displayed, and to uncache internal information that may then need to be refetched from the server. A dialog box will warn you about this before the change is made.

Global Options | Miscellaneous | Display Graph-Part Reification

When enabled, Gruff will sometimes automatically display reification relationships that use graph-part reification. In that style of reification, a graph that contains only a single triple can reify that triple with other triples that use the graph part of the reified triple as their subject or object parts.

This option is turned off by default because it takes significant time to look for these special relationships, and most stores do not have them at all. And it may take a long time to look for them in a large store that does not have a triple index for the graph part. The option value is saved separately for each store so that you can turn it on only for stores that actually contain graph-part reification relationships.

See Reification Support in Gruff.

Global Options | Miscellaneous | Merge Retained Triples

This option is used if you select the option to retain the triples that were downloaded from the previous store or endpoint when you open a new store or connect to a new endpoint. See File | Open Triple-Store. This option may also come into play when using a SERVICE clause in a SPARQL query in the query view to borrow information from a separate endpoint. It is also used for CONSTRUCT queries.

This option determines how to treat two triples that have the same subject, predicate, and object, where one of the triples is being retained from the default graph of the previous store or endpoint (or is being fetched by a SERVICE clause, or created by a CONSTRUCT query), while the other is in the default graph of the new store or endpoint.

If this option is disabled, then Gruff will treat the two triples as separate triples. Displaying the subject node of the triples in the table view, for example, will show separate rows for the two triples, where one of them will indicate on the right side of the table that it is from a different store or endpoint or CONSTRUCT query. If this option is enabled instead, then Gruff will merge the two triples into a single one, to reflect the idea that they are "logically" the same triple.

When used for retaining triples from the previous store or endpoint, toggling this option will behave as needed only if it is toggled before opening the first store (or connecting to the first endpoint) and then opening additional stores or connecting to additional endpoints while selecting the option to retain earlier triples.

Global Options | Miscellaneous | Filter Loadable Queries and Layouts

Whether the commands on the File menu for loading saved queries and layouts will show a special dialog for selecting the file to load based on the triple-store in which it works and various descriptive information that was saved into the files. When off, the standard file selection dialog is used instead, as in earlier Gruff versions.

This affects the commands File | Load Layout State, File | Load Query Text, and File | Load Graphical Query.

Global Options | Miscellaneous | Borrow Queries and Layouts

This option can be used for loading queries or layouts from related triple-stores or from the same store when it had a different name. To do that, specify the value as a list of triple-store names, separated by spaces. (A separate value is remembered for each triple-store.) Then when you use a load command on the file menu to browse the saved queries or layouts of this triple-store, the files that were saved in stores that have those alternate names will also be listed.

This affects the commands File | Load Layout State, File | Load Query Text, and File | Load Graphical Query.

Global Options | Miscellaneous | Cancel Linked Nodes Outline on Mouse Out

When enabled, moving the mouse cursor out of the dialog that's shown by Link | Display Linked Nodes from an Outline will cancel the dialog and hide it. This provides a quick way to cancel that dialog when invoking it often, but it may be annoying if done accidentally.

Global Options | Miscellaneous | Minimum Triples for Individual Property Lookup

This is a somewhat obscure option that could be adjusted to optimize how efficiently Gruff retrieves triples from the server and caches them for later use. You could try setting the value to two numbers where one is greater than the number of triples in the store that you're browsing and one is less, and use whichever setting results in general faster browsing (if there is any noticable difference). For the most accurate experiment, when you begin testing each value you should re-open the store or use File | Miscellaneous | Clear and Uncache Everything.

Here's the background: In a smaller store, it's nearly as fast to ask the server for all triples where a particular node is the subject as it is to ask for that node's triples for a particular predicate. So when a particular property of a node such as rdfs:label is needed, Gruff retrieves all of the triples where that node is the subject and caches them. Then later when Gruff needs another property of that node, it can find it quickly in the cached triples for that node rather than making an additional server request.

But in a larger store it can take much longer to retrieve all of the triples where a node is the subject than to retrieve just the triples for a particular predicate. So when Gruff needs certain properties such as type, label, comment, and pixmap, which it often needs for nodes for which it does need most properties, it does NOT retrieve and cache all triples where the node is the subject, and instead asks the server only for the triples for that property.

This option sets the number of triples at which Gruff switches to the second strategy for larger stores. If the store that Gruff is currently browsing contains fewer triples than this number, then it will use the first strategy above for caching all triples where a node is the subject. But if the store contains more triples than this number, then it will use the second strategy for fetching individual properties from the server instead.

One other effect of this option is that in stores with more triples than the option value, Link | Display Linked Nodes for the Current Predicates will not add links to the display between newly-added nodes and any already-displayed nodes to which they are linked by the current predicates. This is done to make that command faster in larger stores.

Global Options | Miscellaneous | Localization Language

This is the language that is used in some menu commands and help text. It is not well supported, though. The only non-English language that's supported is Mandarin (the zh choice), and even it is quite out-of-date because many commands and options have been added since the translations were done.

Changing this option's value requires restarting Gruff to see the alternate text.

Global Options | Miscellaneous | Use Web Browser for All Documents

When checked, View | Web Interaction | Invoke Web Browser on Node Value will use your preferred web browser to display all types of document files that are the values of nodes. Otherwise, for non-html local files, Gruff will invoke the program that's registered for displaying files of that type.

Global Options | Miscellaneous | Document Base Folder

If your store contains literal nodes that refer to document files that are stored on the local machine, then you can use View | Web Interaction | Invoke Web Browser on Node Value (or control-shift-left-click a node anywhere) to invoke a program to display the document. If a literal appears to be a relative pathname then it will be merged with this base folder to form a complete pathname at which to look for the document file.

This may be useful for building a store containing relative pathnames of documents, and then passing the store along with the document files to colleagues or users. Those users could place the documents into a folder of their choice, and then set the value of this option to be that folder, and then the Gruff commands for displaying those documents in other programs can find the files.

For example, you could set the value of this option to be the string "c:/documents/" (on Windows), put a file called important-info.txt into that directory, and create a node in your store whose value is the literal "important-info.txt". Then if you use the "Invoke Web Browser on Node Value" command (such as by control-shift-left-clicking the node in the graph view), then Gruff will look for the file c:/documents/important-info.txt. If there is such a file, then Gruff will invoke a program to display that file.

You can also create a node whose URI or literal string names a pixmap file on the local machine, and then the graph view will display the pixmap for the node. That value can similarly be a relative path to merge with this base folder. See Displaying Images for Nodes.

Global Options | Miscellaneous | Relax Syntax When Loading Triples

When enabled and invalid RDF syntax is discovered by either File | Load Triples | Load N-Triples or File | Load Triples | Load N-Quads, then if sense can be made out of the line for the triple then it will be loaded anyway. Otherwise triple-loading is aborted.

Global Options | Miscellaneous | Continue on Error When Loading Triples

When enabled and an error occurs in either File | Load Triples | Load N-Triples or File | Load Triples | Load N-Quads, then loading will continue beyond the point of the error. Otherwise triple-loading is aborted.

Global Options | Miscellaneous | Commit Frequency When Loading Triples

When loading triples with commands such as File | Load Triples | Load N-Triples, a commit will be done automatically every time this many more triples have been loaded. Another commit will be done when all triples have been loaded. An exception is that if this value is zero then no automatic commits will be done.

Global Options | Miscellaneous | Reasoner Enables Restriction Reasoning

If you are browsing a reasoning store by having invoked the command File | Miscellaneous | Apply RDFS++ Reasoner, then the reasoner will include reasoning about owl:hasValue, owl:someValuesFrom, and owl:allValuesFrom whenever this option is enabled.

Global Options | Miscellaneous | Auto Font Switching on Text Entry

This option has an effect only on the WIndows platform.

It determines whether text-editing panes in Gruff may automatically switch fonts when needed to draw inserted characters properly. This typically may be needed when inserting Asian or other multibyte characters. Even when the official font contains the needed characters, the text-editing control may not allow enough width for them to be displayed clearly. This affects the query text widget in the query view, and when editing values in the table view.

The automatic font changing may occur unexpectedly or select an undesirable font, and so it may be preferable to instead choose fonts that are known to work well with the character sets that are needed, by using the options Query Options | Query Text Font and Table Options | Table Property Value Font.

Global Options | Miscellaneous | Remove Old Stores from Options File

This command (not really an option) allows you to clean out old no-longer-used stores from the options file that Gruff saves to remember all of your option settings. This is normally not necessary, but perhaps could avoid a small startup delay if you have used many stores. It will also remove clutter from the file, in case you ever examine or modify the options file by hand.

Some options remember distinct values for each store that you browse in Gruff. This command shows a dialog of all of those stores. If you select some old stores that you no longer use, then they will be removed from the option values that are remembered.

If any of the stores are still in the list of recently-used stores that appears on the File menu, then they will be removed from there as well.

The reduced set of option values will not be written to the options file until the usual time, when you either exit Gruff or invoke Global Options | Save All Options.

Global Options | Save All Options

Normally you shouldn't need to ever use this command, because all Gruff options are now saved to file any time you modify an option. But this command is retained from when that was not true in case it is still useful for any reason, or in case it is simply reassuring to save all options explicitly.

This command saves all user options (from all of the options menus and for certain other changes that are not on any menu) into a file. The next time you run the browser, the options will be read from that file so that you don't have to set them up again. The status bar will mention where it saved the file, which will be placed into a personal documents directory and named gruff-options.cl. Options are also saved automatically whenever you modify an option and when you exit Gruff. Newer versions of Gruff will continue to use the same options file, and there is also no problem when the current options file gets loaded if you revert to an older version of Gruff.

If you browse many different triple-stores in Gruff and are concerned about the options file growing larger, you can remove the data for selected older triple-stores with Global Options | Miscellaneous | Remove Old Stores from Options File.

You can cause options to be saved to and reloaded from a custom location by using the --options-file-path command line argument. See Loading Options from a Different Place with a Command Line Argument.

If you are using the lisp interface to Gruff, then the function gruff-options-path returns the path to which the options file will be written, and from which it will be read when the browser is started up.

Global Options | Show Non-Default Option Values

Shows a report of option values that you have changed from their default values. When Gruff is running in a web browser, the report will appear in a new browser tab. Otherwise the report will appear in a third-party program, typically Notepad on Windows or a web browser elsewhere, and so you might need to alt-tab to that program.

You could use this report to review which options you've changed, in case you'd like to change some of them back to their default values without changing all of them back with Global Options | Revert to Default Options.

You might also be able to use this report to determine which option change has triggered a Gruff bug, or we might ask you to send the report to us for that purpose. This report is automatically included in any bug report that you generate when Gruff encounters an unhandled error.

The report excludes options for stylistic things such as fonts and colors, as well as options that are really lists of recently-used values, in order to focus on options that change Gruff behavior and are therefore more useful for debugging.

One awkward thing is that when an option has multiple radio button menu items for it, the report will mention the menu item label of the default value as the name of the option.

Global Options | Revert to Default Options

Sets the value of most options (from all of the options menus) to their initial values, if you say OK when a confirmation dialog apeaars. The display should update to reflect any changes just as when you modify individual options.

The list of recently opened files that appears on the File menu is not cleared, even though it is saved in the options file, and the same is true for the most recently used host, port, and path. A few other options are not cleared because the default values are random or empty; these include the options that are set by the commands Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type, Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate, Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate, Global Options | Node Label Predicates | Custom Predicates for Node Labels, and Global Options | Namespace Abbreviations. These exceptions allow reverting from options that you may have modified temporarily, without undoing certain other preferences that are more tedious to set up.

To instead see a list of options that you have changed and may want to individually change back, use Global Options | Show Non-Default Option Values.

Global Options | Export Some Options

Lets you export some subset of all user options to a file, which other users could then import with Global Options | Import Some Options to share particular preferences. This can be more efficient than the second user specifying all of the same values interactively.

A dialog will first appear with a list of all options that are offered for export. This is nearly all options except for the boolean ones, which are excluded to avoid an excessively long list and because users can quickly toggle those themselves. You can select any number of options to export. The names that appear in the list are generally the same as the ones that appear in the menu bar, though several correspond to commands with different names.

Then the file dialog will appear to let you save the options to an arbitrary file to pass to others.

Here are the option names that appear in the list and whose names do not match in the menu bar:

Global Options | Import Some Options

Lets you import a subset of all user options that someone has selected and written to an arbitrary file with Global Options | Export Some Options, to share particular preferences.

First the file dialog will appear to let you select the file that contains the exported options. Then a dialog will appear that lists the options that will be imported, so that you can make sure that it contains the expected set and not any options whose values you do not want to overwrite.

If any of the imported options have multiple values, then this dialog will let you choose to either merge the imported values with your own, or to replace your values with the imported ones. For example, if you are importing Node Colors for Types and the import file species green for a person type and blue for a profession type, whereas you have defined blue for person and purple for company, then if you select the option to merge then you would end up with green for person, blue for profession, and purple for company. (Whenever there's a conflict, the imported value will override your own.) If you selected the option to replace instead, then your setting of purple for company would go away.

The Query Options Menu

Options that affect SPARQL and Prolog queries. This menu is present only in the query view and the graphical query view.

Query Options | Query Text Font

This is the font that is used in the query text widget of the query view.

The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when the keyboard focus is in the query text widget.

Query Options | Query Engine | Default Query Enginge

When selected, each query that's performed will use whichever query engine is the default in the version of AllegroGraph server that's currently being used for the triple-store that Gruff is browsing.

This works simply by NOT adding a prefix statement to the query, as the other choices do, which causes AllegroGraph to use the default engine.

Query Options | Query Engine | Set-Based Query Enginge (SBQE)

When selected, each query that's performed will use the Set-Based Query Engine (SBQE). This is the original query engine in AllegroGraph, and is thhe fastest query engine for many types of queries.

This works by automatically adding the following statement to the top of each query, which you could otherwise do yourself:

PREFIX franzOption_engine: <franz:sbqe>

Query Options | Query Engine | Merge Join Query Enginge (MJQE)

When selected, each query that's performed will use the Merge Join Query Engine (MJQE). This engine is better for queries that need a lot of intermediate state and are prone to combinatorial explosion.

This works by automatically adding the following statement to the top of each query, which you could otherwise do yourself:

PREFIX franzOption_engine: <franz:mjqe>

Query Options | Query Timeout

This is the number of seconds before a query that's done in the query view will give up and return no results. Otherwise a query might take an indefinite amount of time and hang Gruff.

Query Options | Displayed Results Limit

This is the maximum number of rows that will be created in the query view's results table. This is simply to save time creating the table when many results are returned.

Query Options | Allow Other Work During a Query

When enabled, Gruff will allow you to switch to other views and do work while a long query is running in the query view. For this to be safe, Gruff opens a new instance of the triple-store for doing the query. Reopening the store is normally fast by specifying the already-open instance, but if it slows down quick queries then you could turn this option off to avoid re-opening the store for queries.

WARNING: When this option is on, a commit will be done internally whenever a user query is done in the query view (unless the store was opened in read-only mode). The reason is that otherwise any INSERT or DELETE statements in the user query would be lost due to the query being performed in a temporary separate connection to the triple-store. So you should not turn this option on if it is not OK for these internal commits to be done.

Query Options | Show Explicit Nodes from Query

When enabled, two small grids will appear at the bottom of the query view that list the nodes and predicates that are explicity mentioned in the query text. This allows copying one to paste elsewhere, or clicking a node to display it in the table view, or toggling whether a predicate is a current predicate. As usual, right-click an item in a grid for a pop-up menu of commands.

These grids are probably not worth the real estate that they occupy in the query view, so they are not shown by default.

Query Options | Percent-Encode Non-ASCII in Queries

Whether all non-ASCII characters that are entered into SPARQL and Prolog query text in the query view will be percent-encoded to match URIs that are percent-encdoed in the store. Triple parts in AllegroGraph can be non-percent-encoded IRIs (which are URI references but not actual URIs), and so you would not need or want to enable this option if any non-ASCII characters in IRIs in the store itself are not percent-encoded.

(Percent-encoding is also called URI-encoding, though here we are dealing with the encoding of only the non-ASCII characters in an IRI, rather than encoding the entire IRI as is done when embedding an IRI in a larger piece of HTML or XML.)

URIs may contain only ASCII characters, and other characters in URIs are percent-encoded with strings that look like %37%B6, where the numbers are the hexadecimal UTF8 octets for the characters. If a store contains percent-encoded URIs and you need to reference them in queries, you could enter the percent-encoded strings yourself, though that would be rather tedious. In that situation you may want to turn on this option, which will allow you to instead enter URI references that contain actual non-ASCII characters into query text, to match percent-encoded URIs that are in the store.

If you need to create a query that references URIs and/or literals where some of them contain percent-encoded characters while others contain non-percent-encocded non-ASCII characters, then you would need to turn this option off and enter the ones that are percent-encoded as the actual percent-encoded URIs that exist in the store.

This option also affects SPARQL queries that Gruff does internally for utilitarian tasks.

Query Options | Exclude Orphans from Visual Graphs

Whether nodes that have no displayed links will be excluded from visual graphs that are generated from query results. An orphan would result when a node is in either the query results or the query itself, but it is not part of any triple whose three parts are all in either the query results or the query itself. If you are interested in seeing only triples in the visual graph, then you could select this option.

If the visual graph would contain ONLY orphan nodes, then the nodes will still be displayed to avoid confusion when the visual graph contains nothing at all.

Query Options | Include More Triples in Visual Graphs

This option determines which of two approaches is used to derive triples from query results. The triples are often used to generate a visual graph from query results, using the "Create Visual Graph" button widget in the query view, and can also be used to export triples to a file with File | Export Displayed Data As | N-Triples and related commands.

The results of a SELECT query are not triples, but triples are what a visual graph displays. So to generate a visual graph from query results, an arbitrary approach must be used to derive triples that are related to the query results. This is somewhat complex, but here is a basic description of how the two approaches that Gruff offers work internally. You can choose whichever is closest to what you're looking for.

When this option is disabled, triples are derived by plugging variable matches from the query results into triple patterns from the query. These triples directly relate to the query because each one matches a triple pattern that was the source of some of the query results. To find the most triples when this option is disabled, the query should select on all of the variables that are in the query, as in "select *" at the beginning of the query, so that Gruff has the maximum information in the query results for deriving triples.

But no triples can be derived for some triple patterns. For example, if all of the variables in a triple pattern that's inside an OPTIONAL or UNION clause are also used elsewhere in the query, then it's unknown whether matches for those variables in the query results stem from that triple pattern. So the triples that are derived with this option disabled may not completely reflect the query results.

When this option is enabled, a completely different approach is used. First Gruff finds all of the triples that are in the store for each node and predicate that's in the query results or in the query itself. It then uses any of those triples where the subject, predicate, and object are all found in the query results or the query itself. This will always find all triples that were the source of any query results, but can also include triples that are related only by having parts that are scattered throughout the query results. This approach takes longer because it typically needs to ask the server for lots of triples that Gruff hasn't yet downloaded, but it can be useful if fewer triples than expected are found when this option is disabled.

Here's an advanced note on transitive predicates, which are handled by the two approachess in very different ways. If a query uses a transitive predicate like subClassOf+ to find all of the superclasses of a node at multiple levels above it, for example, then the query results will return all of those classes with no indication how many levels away each one is or what's in the chain of classes to each one. When this option is disabled (and Query Options | Show Links for Property Paths in Visual Graphs is enabled), the generated visual graph will have link lines that represent a subClassOf+ pseudo-predicate and which connect the node directly to each of the classes, even when they are not direct superclasses. The visual graph directly reflects the query results, though some of the link lines do not represent actual triples that are in the store. When this option is enabled, the visual graph will show every subClassOf triple between any nodes that are in the query results, even though some of those triples may not be ones that were the origin of any query results.

If the query uses any "magic properties" (aka magic predicates), then this may similarly create links in the generated visual graph that do not represent actual triples in the store, when this option is disabled. The link lines will represent the magic properties directly instead.

Query Options | Show Links for Property Paths in Visual Graphs

If this option is enabled and Query Options | Include More Triples in Visual Graphs is disabled, and a query is done that has any triple patterns whose predicates are property paths such as rdfs:subClassOf* or rdf:type/rdfs:subClassOf, and the "Create Visual Graph" button is used to generate a visual graph from the query results, then link lines will be added to the visual graph between any nodes that were associated by those property paths in the query.

For example, if :class1 is a subclass of :class2 and :class2 is a subclass of :class3, and the query includes a triple pattern like "?sub rdfs:subClassOf* ?super", and a query result matches "?sub" on :class1 and "?super" on :class3, then the generated visual graph will include a link line between :class1 and :class3, and the link line will be labeled with the subClassOf* pseudo-predicate.

This is an exception to the usual case where each link line in a visual graph represents an actual triple that exists in the database between the two nodes that the line links.

Query Options | Query Logging Enabled

When checked, each SPARQL or Prolog query that is performed will be written to the log file that's specified by Query Options | Query Logging File. The query text itself will be written, followed by the table of results in textual form. The report is written in a primarily human-readable format, though in a regular way that could also be parsed by analysis software. The format of the table is affected by other options on this menu.

An alternative is to use the Write Text Report button widget in the query view to write a single query with its results to a file that you specify on the fly.

Other information will also be written to the log file when logging is enabled, including data written by commands on the File | Export Displayed Data As child menu, and notes about when a Gruff session began and ended.

Query Options | Query Logging File

This is the file to which SPARQL and Prolog queries will be logged whenever Query Options | Query Logging Enabled is currently toggled on. This option will default to a file called gruff-log.txt in your home directory on Linux or your personal documents directory on Windows.

If this file doesn't exist when a query is done, then it is created, and otherwise the new query will be appended to the end of the file. You could change the value of this option to begin writing a new sequence of queries to a different file.

Query Options | New Log File for Each Session

When checked, a different log file will be created and used for each Gruff session (when query logging is enabled). This can help prevent a single log file from growing overly long.

The name of the log file that will be used will be derived by appending a date-time string for the time at which the Gruff session began to the official log file pathname.

Query Options | Show Current Log File Now

This one is actually a command rather than an option. It invokes a third-party program to display the current log file. The program will be the one that's registered for displaying documents of the type that you specified for the log file, such as invoking Notepad to display a .txt file.

Nothing will happen if the log file is not found, which is normally when no queries have been done yet with query logging enabled.

Query Options | Query Text Report Show Full URIs

When checked, queries that are written to text report files will print the full URI of each node or predicate. Otherwise only brief names will be printed to save space. When this option is on, you may want to also turn on the One Line per Value option below to prevent the text lines from getting overly long.

This option affects files that are written by automatic query logging as well as by the Write Text Report button widget.

Query Options | Query Text Report One Line per Value

When checked, queries that are written to text report files will print each table cell value (along with its variable name) to a separate line of text, rather than printing all values of a table row to a single line of text. This option may be needed when the Show Full URIs option above is enabled, to prevent the text lines from getting overly long.

This option affects files that are written by automatic query logging as well as by the Write Text Report button widget.

Query Options | CSV File Include Full URIs

When checked, queries that are written to CSV files will print the full URI of each node or predicate. Otherwise only brief prettified node labels will be printed for readability.

This option affects files that are written by the "Save as CSV" button widget.

Query Options | CSV File Include Column Headers

When checked, queries that are written to CSV files will include an initial text line at the top that contains the names of the query results column variables. They will be enclosed in double quote characters and separated by commas, as with the variable values in other rows.

This option affects files that are written by the "Save as CSV" button widget.

The Table Options Menu

Options that affect the display of information in tables. This menu is present only in the table view and the query view, and only some of its commands are present in the query view. (In the query view it applies to the query results tables.)

Table Options | Table Property Name Font

This is the font that is used for text in the lefthand column of the table in the table view. That column displays property names, also known as predicates of triples.

The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the table view. (The value font will be adjusted along with it.)

Table Options | Table Property Value Font

This is the font that is used for text in the righthand column of the table in the table view. That column displays property values, also known as objects of triples.

The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the table view. (The name font will be adjusted along with it.)

Table Options | Show Full URIs in Tables

When checked, each table cell in the table view or the query view will display the complete URI of a node or predicate rather than a shorter label that was found or derived in some other way. This will override all other options that find or derive labels in various ways for the table view.

This option has a keyboard shortcut, which is simply the 8 numeral key on the main part of the keyboard. This shortcut is handy for for frequently toggling the table view between easily-readable short labels and complete URIs.

Table Options | Show Multiple Property Values

When checked, each property that has multiple values will display all of the values, each on their own lines. When unchecked, each property will display only a single line, which will show the property value if it has only a single value, or else will show the number of values that it has.

Using this option shows all of the triples of the displayed node, but may require lots of scrolling to see all of the properties (predicates) that the node has.

Regardless of whether this option is enabled, you can always left-click on a property cell to toggle whether that particular property displays all of its values.

Table Options | Sticky Multiple Property Values

When this option is enabled and the table is in expanded mode (meaning that Table Options | Show Multiple Property Values is currently on), clicking on a predicate to collapse it will cause that predicate to continue to be collapsed as you visit further nodes. This can be undone by later clicking that predicate again (in either expanded or collapsed mode) to re-expand it.

Similarlly, clicking a predicate to expand it while in collapsed mode will cause that predicate to continue to be initially expanded as you visit further nodes, until you click it again later to re-collapse it.

Table Options | Show Multiple Text Lines

When checked, displaying each literal in the table view will make the table row tall enough to fit the value within its table cell. When unchecked, every table row will be just tall enough to fit a single line of text.

Using this option allows seeing all of the text of long literals, but may cause fewer table rows to fit in the window at one time.

Table Options | Display Literals of All Languages

When checked, the table view will display all literals regardless of their language tags. When unchecked, the table view will display only literals that have no language and literals that have the language tag that is currently selected on the Global Options | Miscellaneous | Preferred Language child menu.

Table Options | Display Graph Names

When checked, any triple that's in a named graph (rather than the default graph) will display the name of its graph on the right end of the row for that triple. Otherwise graph names will not be displayed in the table view.

Graph names can also be displayed on link lines in the graph view with Visual Graph Options | Link Labels | Show Named Graphs on Link Labels.

Table Options | Display Links to Reifying Triples

When checked, whenever the triple for a row in the table has any reifying triples in the store that use triple-id reification, then a small icon will be displayed just to the left of the border between the two table columns. Clicking this icon will display the table for the triple-ID node of the row's triple, which will show all of the triples that reify the row's triple. See Table View Value Column Navigation | Show Reifying Triples in Table.

This option is off by default because most stores do not use much reification, and it can take significant time to check for any reifying triples for the triple of each table row.

See Reification Support in Gruff.

Table Options | Maximum Triples Per Predicate in Table

This is the maximum number of triples that will initially be displayed for any single predicate when you display a node in the table view. This avoids sometimes taking lots of time to display a node that has many triples, especially due to looking up the label properties of all of the linked nodes.

If not all of the triples are displayed, then the Show All Triples button widget at the upper right corner of the table view will become available (not grayed out) and it will mention the total number of triples for the resource. Pressing the button will regenerate the table to show all triples of the node.

Text such as show the other 37 will also appear just below the predicate name of each predicate whose triples were limited by this option. Clicking that text will include the additional triples for that predicate in the table. Typically you may want to use this for predicates that mention a small number of additional triples, but not for ones that mention thousands of additional triples. Using this feature along with a small value for this option will avoid showing an unwieldy number of triples in the table.

Table Options | Maximum Text Length in Table

Any string that is displayed in a table cell for a node will be truncated to this length if it is longer. This is to avoid attempting to display any extremely longs strings.

Table Options | Table Color One

This is one of the two background colors that are used for alternate rows in the table. These default colors are overridden by special colors in some table cells.

Table Options | Table Color Two

This is one of the two background colors that are used for alternate rows in the table. These default colors are overridden by special colors in some table cells.

Table Options | Table Cell Vertical Padding

This is the number of pixels of blank space between text in a row of the table and the border of the row. A larger value increases readability but fits fewer table rows into the window.

The Outline Options Menu

Options that affect the display of information in the outline view. This menu is present only in the outline view.

Outline Options | Outline Font

This is the font that is used for the names of nodes in the outline view.

The names of predicates will be drawn in a variant of this font, to distinguish them from the node names. If this is a bold font, then the predicate will be drawn in the non-bold version of the font. If it is a non-bold font, then the predicate will be drawn in the italicized version of the font.

The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the outline view.

Outline Options | Show Full URIs in Outline

When checked, each node and predicate in the outline view that's a resource will be displayed as the complete URI of the node or predicate, rather than as a shorter label that is found or derived in some other way. This will override all other options that find or derive pretty labels.

This option has a keyboard shortcut, which is simply the 8 numeral key on the main part of the keyboard. This shortcut is handy for for frequently toggling the outline view between easily-readable short labels and complete URIs.

Outline Options | Maximum Triples per Predicate in Outline

The maximum number of triples that the outline view will initially show for a single predicate under a parent node, whenever Outline Options | Honor Maximum Triples per Predicate is enabled. This prevents showing many triples for a single predicate that would be cumbersome to scroll past.

Whenever the limit is exceeded, only a single triple is shown for the predicate. A note like show the other 37 will appear to the right of the triple in dark red text, and you can click that note to show the other triples. Also, you can click any predicate name at any time to hide the other triples for that predicate under the same parent node. See also the keyboard shortcuts for Outline View Navigation | Display Sibling Triples for the Same Predicate and Outline View Navigation | Hide Sibling Triples for the Same Predicate.

Outline Options | Honor Maximum Triples per Predicate

Whether Outline Options | Maximum Triples per Predicate in Outline is currently being enforced. The keyboard shortcut for this option allows you to quickly enable and disable the maximum.

Toggling this option does not change what is currently displayed in the outline. It affects only what happens when you open and close outline items thereafter.

Outline Options | Show Comments When Hovering

When checked, holidng the mouse cursor briefly over an outline item will display the comment property of the node that's in the item, if it has one. The comment will be displayed as a wrapped string in a box just below the outline item. The wrapped text will go away when you move the mouse cursor off of the item.

The hovering time that is required is controlled by Outline Options | Hovering Delay. The font for the comment is controlled by Visual Graph Options | Tooltips | Tooltip Font.

The actual predicates to search for a comment to display can be customized with Global Options | Node Label Predicates | Custom Predicates for Node Comments.

Outline Options | Wrap Text When Hovering

When checked, holding the mouse cursor briefly over an outline item whose text is clipped at the right (because the text is too long to fit on one line) will display the complete text in a box as multi-line wrapped text. The wrapped text will go away when you move the mouse cursor off of the item.

The hovering time that is required is controlled by Outline Options | Hovering Delay.

If the mouse cursor gets in the way of reading the text, a rule of thumb is to hold the mouse cursor over the name of the predicate, where it will be out of the way of the text box that is displayed to the right.

Outline Options | Hovering Delay

This is the number of milliseconds that you must hold the mouse cursor over an outline item before its comment property or full text (when clipped) will appear.

Outline Options | Maximum Width for Wrapped Text

This is the maximum width for the rectangle into which text will be displayed in the outline view according to the options Outline Options | Wrap Text When Hovering and Outline Options | Hovering Delay. The value is measured in pixels.

This constraint is provided to make wrapped text easier to read in a column that is not overly wide. The value could be increased if needed to make more text fit in the available vertical space.

Outline Options | Indicate Which Items are Openable

When checked, outline items will display hollow arrows when no nodes are linked with that item's node by the current predicates, other than the node of the parent outline item. This indicates that opening the item would not show any child items (see Link | Display Linked Nodes for the Current Predicates, which is run when you open an outline item).

The arrows for a newly-revealed set of child items are not changed to hollow mode immediately because it may take a while to ask the server for the linked nodes of each node. Instead, a command is queued up to handle each one individually when nothing else is busy. But if it still bogs things down, this option could be turned off to avoid displaying hollow arrows at all; you would then need to open an item to find out if it has any children.

Outline Options | Create All Nodes as Blank Nodes

When checked, then creating a new node in the outline view will always create a blank node, rather than asking you for an RDF string or a literal.

This provides a fast way to create new nodes when you don't care that each one has an RDF name.

See also Edit | Prompt for Label for New Blank Node for another convenience option when creating blank nodes.

The Visual Graph Options Menu

Options that affect how the information in a store is displayed in a visual graph of node pictures that are connected by link lines.

This menu is present only in the graph view and in the graphical query view. Only some of its commands are present in the graphical query view.

Visual Graph Options | Node Labels | Node Label Font

This is the font that is used to draw labels on nodes in the graph view, and also in menus that are shown in the graph view. A larger font is easier to read but increases the size of the graph.

The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the graph view. (The link label font will be adjusted along with it.)

Visual Graph Options | Node Labels | Show Full URIs on Nodes

When checked, the complete URI for each node will be displayed on the node itself in the graph view. This will override all other node label options for using either label predicates or derived labels.

The nodes will be larger due to containing more text, and also less nearly square, and so a larger canvas will typically be needed to display the nodes. After turning on this option, you can use Layout | Make Canvas Larger if needed to increase the canvas size, followed by Layout | Update Layout Incrementally to rework the layout for the larger node boxes.

Visual Graph Options | Node Labels | Maximum Node Label Length

Strings that are displayed in node boxes will be truncated to this length when longer, but only when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is enabled.

Visual Graph Options | Node Labels | Enforce Maximum Node Label Length

When checked, strings that are displayed in node boxes will be truncated to Visual Graph Options | Node Labels | Maximum Node Label Length when longer. This is to keep node boxes small so that more of them will fit into a visual graph.

When not checked, strings in node boxes will still be truncated to Visual Graph Options | Node Labels | Absolute Maximum Node Label Length, to avoid attempting to display any extremely long strings.

Visual Graph Options | Node Labels | Absolute Maximum Node Label Length

Strings that are displayed in node boxes will be truncated to this length even when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is disabled. This is to avoid attempting to display any extremely long strings.

Visual Graph Options | Node Labels | Maximum Word Length in Node Boxes

When drawing labels in node boxes in the graph view, if any single word (as delimited by spaces) is more than this number of characters long, then it will be allowed to split in the middle of the word, wrapping part of the word to the next line of text. This avoids having a very wide node box that interferes with graph layout.

If this behavior is undesirable, set the value to a large number, or set Visual Graph Options | Node and Link Spacing | Preferred Node Width to a larger number.

Visual Graph Options | Node Labels | Maximum Initial Node Pixmap Size

This is the maximum pixel width or length that a newly-displayed node will initially have when it displays an image rather than the usual label text. See Displaying Images for Nodes.

If either the natural width or height of the image pixmap is larger than this, then both its width and height will be reduced proportionally so that they both are no larger than this maximum. Otherwise the pixmap will be displayed at its natural size.

In either case, you can then resize the node by left-clicking and dragging its lower right corner.

Visual Graph Options | Node Labels | Show Full Label When Selected

When checked, a node label string that would normally be truncated when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is enabled will not be truncated for the currently selected node (if any).

This allows you to click on a node that has truncated text to expand that single node to show its full text. The node will also be brought to the front so that no other nodes can partially cover it.

Visual Graph Options | Node Labels | Show Full Label When Under Mouse

When checked, a node label string that would normally be truncated when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is enabled will not be truncated for a node that's under the mouse cursor.

This allows you to move the mouse over various nodes that have truncated labels to make them momentarily expand to show their full text, until you move the mouse away. Each node that the mouse cursor enters will also be brought to the front so that no other nodes can partially cover it.

Visual Graph Options | Node Labels | Highlight Search Text in Nodes

When you use Text Search | Search the Current View to find nodes that are already displayed in the graph view, it highlights each matching node with a blue border. When this option is enabled, it will also highlight the actual search text inside each node. This makes it easier to spot the search text in nodes that contain more than a few words, such as long literals.

This might cause a node's text to wrap to multiple lines differently, because Gruff does the wrapping itself rather than letting the underlying windowing system do it, so that it can know where all of the text is placed in order to highlight it. This might slightly slow down drawing.

Visual Graph Options | Node Corner Clicks | Enable Node Corner Clicks

When enabled, moving the mouse cursor over one of the four corners of a node in the graph view will display a small icon. If you left-click the node while the icon is present, then a command that the icon represents will be run. These clicks are shortcuts for standard commands on the menu bar. To find out what command an icon stands for, check the status bar at the bottom of the main Gruff window as you hover over a node corner. Or wait for the tooltip to appear as you hover over the corner.

You can assign a different command to any corner by right-clicking the corner and selecting a command from the pop-up menu that appears.

Visual Graph Options | Node Corner Clicks | Draw Corner Icons as Letters

When enabled, the icon that's drawn to represent the command for a node corner will be a letter, and otherwise it will be a non-verbal image. Here are the letters and the commands that they represent: 

O   Link | Display Linked Nodes from an Outline  
M   Link | Display a Linked Node from Menus  
L   Link | Display Linked Nodes for the Current Predicates  
P   Link | Display Paths Between Two Nodes  
T   Layout | Do Tree Layout from Selected Node  
H   Select | Toggle Highlighting of the Selected Node or Link  
I   Select | Toggle Pinning of the Selected Node  
X   Remove | Remove Selected Node

Visual Graph Options | Node Corner Clicks | Draw Corner Icons Inside Nodes

When enabled, node corner icons will be drawn inside the node, in the area where you need to click to invoke their commands. Otherwise the icons will be drawn just outside the node. Outside is probbably easier to see, with no text underneath and not being covered by the mouse cursor, while inside lets you click directly on the icon.

Visual Graph Options | Node Corner Clicks | Specify the Command for a Node Corner

Lets you specify which command will run each time you left-click on a particular corner of any node, as long as Visual Graph Options | Node Corner Clicks | Enable Node Corner Clicks is on.

First a pop-up menu will let you select which of the four corners to modify. Then a second pop-up menu will let you select the command to assign to that corner.

Visual Graph Options | Node Corner Clicks | Enable Right-Click Corner Assignment

When enabled, you can right-click one of the corners of any node to specify which command will run when left-clicking that corner of any node.

This may be quicker than using Visual Graph Options | Node Corner Clicks | Specify the Command for a Node Corner. But it might also lead to confusion if you are trying to right-click the middle of a node and select a command to run, but you unknowingly right-click a corner and select a command that is then assigned to that corner.

Visual Graph Options | Link Labels | Draw Link Labels

When checked, text labels are drawn near link lines to indicate which predicates they represent. This is the same string that will appear in a tooltip when the mouse cursor hovers over the link line.

The layout algorithm does not make room for link labels, and so they sometimes will collide with other objects, including other link labels. For this reason, and to reduce clutter, and because there are tooltips and a legend that indicate the predicates for each line style, this option is not enabled by default. It does, however, have a simple keyboard shortcut (the M key) for toggling it on and off quickly. It may be most useful for toggling on now and then you need to check predicates.

Link labels will typically be more readable if you increase [Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing] (#VisualGraphOptionsNodeandLinkSpacingMinimumNodetoNodeSpacing) (and then redo the layout).

Another option for drawing link labels that may look neater than this approach is [Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse] (#VisualGraphOptionsLinkLabelsDrawLinkLabelsforNodeUnderMouse).

This command is present only in the graph view. (Link labels are always drawn in the graphical query view.)

Visual Graph Options | Link Labels | Draw Graph Link Labels Horizontally

When checked, all link labels in the graph view will be drawn horizontally. Otherwise most link labels will be drawn along the link lines on platforms that support text at arbitrary angles. Currently link labels are always drawn horizontally on GTK (which is used on Linux and the Mac).

Even when this option is not checked, some link labels will be drawn horizontally when heuristics suggest that the label will probably fit better that way.

This command is present only in the graph view.

Visual Graph Options | Link Labels | Draw Query Link Labels Horizontally

When checked, all link labels in the graphical query view will be drawn horizontally. Otherwise most will be drawn along the link lines on platforms that support text at arbitrary angles.

This option is separate from the one for the graph view because it may be optimal to use angled labels in the graph view where horizontal labels may not fit as well amongst the many nodes and links, but to use horizontal labels in the graphical query view where the sparser content is arranged by hand and where it is more important to be able to read all of the labels clearly.

This command is present only in the graphical query view.

Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse

When checked, moving the mouse cursor over a node in the graph view will cause labels to appear for the predicates of the triples that are currently displayed for that node. The labels will appear just over the nodes that are linked with the node that is under the mouse, where there tends to be room to fit the labels in (and so this option may look neater than Visual Graph Options | Link Labels | Draw Link Labels).

The labels will be drawn inside boxes, where the box color can be set with Visual Graph Options | Link Labels | Link Label Box Color. If the other node is the object of the triple, then the label above it will be of the form Type, whereas if the other node is the subject then the label will of the form is Type of. To avoid the awkward expression "is Sub Class Of of" for the subClassOf predicate, you may want to enable Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass".

Node tooltips will always be disabled when this option is on, because it is annoying when tooltips obscure the momentary predicate labels.

This command is present only in the graph view.

Visual Graph Options | Link Labels | Show Named Graphs on Link Labels

When checked, link labels in the graph view will include the names of the graph parts of the triples that the links represent, if any, in addition to the predicates as usual. The format will be "graph1: predicate1" rather than simply "predicate1". For triples that are in the default graph, the graph will not be mentioned.

Named graphs can also be displayed in the table view with Table Options | Display Graph Names.

Visual Graph Options | Link Labels | Link Label Font

This is the font in which all link labels are drawn, when enabled.

The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the graph view. (The node label font will be adjusted along with it.)

Visual Graph Options | Link Labels | Use Line Color for Link Labels

When checked, each link label is drawn in the same color as the link line that it goes with. Otherwise all link labels are drawn in the single color that's set with Visual Graph Options | Link Labels | Link Label Color.

This command is present only in the graph view. (The line color is always used in the graphical query view.)

Visual Graph Options | Link Labels | Link Label Color

This is the color in which all labels are drawn on link lines, when Visual Graph Options | Link Labels | Draw Link Labels is enabled.

This command is present only in the graph view. (The line color is always used in the graphical query view.)

Visual Graph Options | Link Labels | Link Label Box Color

This is the color of the background of the boxes that appear around predicate labels when [Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse] (#VisualGraphOptionsLinkLabelsDrawLinkLabelsforNodeUnderMouse) is turned on. It is green by default to make the labels stand out, allowing you to quickly spot all of the nodes that are linked with the node that is under the mouse.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Do Automatic Incremental Layouts

When checked, operations such as displaying additional nodes or removing nodes from the display will automatically run the Layout | Update Layout Incrementally command. This is usually useful for keeping all of the nodes arranged in a relatively readable layout. But if you have explicitly placed nodes at meaningful positions, then you may want turn this option off.

When unchecked, displaying additional nodes will still attempt to move only the new nodes to empty spots, though if this is not successful then they may end up on top of an existing node (when adding linked nodes) or at the mouse cursor position, and you may need to drag them elsewhere yourself.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Animate Layouts

When this option is enabled, any layout command will animate the movement of nodes to their positions in the new layout. Otherwise the layout solution will be found and then immediately displayed.

The type of animation that is done depends on Visual Graph Options | Layout Options | Slide Straight to Final State. When that option is also enabled, the solution is first found and then the nodes will slide directly to their positions in that solution. Otherwise each iteration that the layout algorithm goes through while looking for a solution is displayed.

Animating layouts will make them take longer, though it may be useful for seeing how nodes progress from their previous positions to their new ones. When Slide Straight to Final State is off, it also demonstrates how some layouts gradually converge on a solution. Animation will never be done if there are more nodes displayed than Visual Graph Options | Layout Options | Maximum Nodes for Animation.

When the spring layout algorithm is being used (see Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout), you can toggle animation on and off while the layout is being done. You can do that quickly by pressing the keyboard shortcut for this option during a layout. This allows you to let the layout run in non-animated mode for a while for speed, and then to toggle animation on to see how far the layout has progressed. If it appears to have gotten far enough, you could then interrupt the layout as usual by pressing the spacebar or Q or Escape. Or if the layout could use more work, then you can toggle animation back off to let it proceed at full speed for a while longer.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Maximum Nodes for Animation

If the total number of nodes in the visual graph exceeds this number, then layouts will not be animated even if Visual Graph Options | Layout Options | Animate Layouts is enabled.

Visual Graph Options | Layout Options | Slide Straight to Final State

This option has an effect only when Visual Graph Options | Layout Options | Animate Layouts is enabled. When this option is enabled, a layout algorithm will first find a solution and then slide each node in a straight line to its position in that solution. Otherwise the nodes will move while the algorithm is finding a solution, moving to each of the algorithm's incremental positions that gradually converge on a solution.

An exception is Layout | Do Tree Layout from Selected Node, which does not incrementally converge on a solution, and so it always behaves as if this option is enabled (whenever animation is enabled at all).

The amount of time that the sliding animation will use is determined by Visual Graph Options | Layout Options | Number of Sliding Steps along with Visual Graph Options | Layout Options | Sliding Time in Milliseconds.

Visual Graph Options | Layout Options | Number of Sliding Steps

This option has an effect only when Visual Graph Options | Layout Options | Slide Straight to Final State is enabled. It is the number of frames of animation that will be displayed to slide the currently displayed nodes directly toward a new layout. More frames will look smoother but will take longer.

Visual Graph Options | Layout Options | Sliding Time in Milliseconds

This option has an effect only when Visual Graph Options | Layout Options | Slide Straight to Final State is enabled. And it is never used when Gruff is running in a web browser, where the sliding is always done as quickly as possible.

This is the number of milliseconds that will be used to slide all nodes to their positions in a new layout. The actual time will be longer if it takes more time to redraw everything the number of times specified by Visual Graph Options | Layout Options | Number of Sliding Steps. Otherwise a timer will be used to extend the time as needed. Specifying zero for this option ensures that the animation will be done as quickly as possible without ever using the timer.

Visual Graph Options | Layout Options | Maximum Iterations for Full Layout

This is the number of iterations at which a full layout will give up if it has not reached a solution. A full layout is done by the Layout | Redo Layout from Scratch command.

If this limit is reached, the Layout | Update Layout Incrementally command can be used to continue the layout just as if this limit had been larger. Alternately, Layout | Make Canvas Larger could first be used to increase the chance of a successful layout.

The default value is rather small so that layouts that are done interactively will not go on for a long time. If you want to do large layouts without waiting for them, for example, then you may want to increase this value a lot. The spring layout in particular does not know when it has taken a layout about as far as it can, and so will always tend to continue until it approaches this limit, so you may need to experiment with this limit for optimal spring layouts.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Maximum Iterations for Incremental Layout

This is the number of iterations at which an incremental layout will give up if it has not reached a solution. An incremental layout is done by the Layout | Update Layout Incrementally command, and is also done automatically after various operations that change the displayed graph.

The default value is rather small so that layouts that are done interactively will not go on for a long time. If you want to do large layouts without waiting for them, for example, then you may want to increase this value a lot.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Center After Full Layout

When checked, the entire graph is shifted so that it is centered in the scrolling canvas after a full layout, as with the Layout | Center the Graph command. This can correct drift that tends to occur during a layout.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Center After Incremental Layout

When checked, the entire graph is shifted so that it is centered in the scrolling canvas after an incremental layout. The window will not be automatically scrolled to the center, however, as with Layout | Center the Graph.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Compress After Full Layout

When checked, an extra step is done at the end of a full layout to bring some nodes more toward the center of the graph so that the entire graph fits in a smaller area. The only drawbacks with this are that it takes a bit more time, and doing an incremental layout just afterward will not produce exactly the same result as continuing the original layout would have.

The layout algorithm tends to fill the available space in the canvas so as to provide more "holes" into which nodes can be moved, and it doesn't know when it may be nearing a satisfactory solution. Therefore, nodes may end up scattered farther apart than desired without this option.

When the spring layout algorithm is used, this option applies only to groups of nodes that are not connected with each other.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Compress After Incremental Layout

When checked, an extra step is done at the end of an incremental layout to bring some nodes more toward the center of the graph so that the entire graph fits in a smaller area.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Honor Layout Direction Constraints

This option determines whether the layout directions that have been specified for particular predicates are currently used by the layout algorithm. Once you have used Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate to specify the general directions in which some set of predicates should be laid out, you can toggle this option to quickly turn all of the layout direction constraints on or off.

Using this command will not automatically redo the layout to reflect the new constraint. You will need to use either Layout | Update Layout Incrementally or Layout | Redo Layout from Scratch yourself after this command.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate

Allows you to specify that the link lines that are displayed for a particular predicate should always be oriented in one general direction, either upward, downward, leftward, or rightward. For example, if you are displaying subClassOf links, you could specify that all subClassOf links should point upward only; that will cause all subclasses to be displayed below their superclasses.

These specifications will be in effect only when the Visual Graph Options | Layout Options | Honor Layout Direction Constraints option is toggled on.

A quicker alternative to this menu bar command is to right-click a link in the legend and use the Specify Layout Direction command on the shortcut menu there.

The term "upward" basically means "more upward than downward", and so an upward link could still point East by Northeast, for example.

It's possible to establish layout directions for multiple predicates, though each one makes the layout more difficult. In particular, the layout may not work well when any single node has many directional links. In the general case, a larger canvas or increased layout time may be required. It may also be desirable either to set Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy to a lower value, or else to set Visual Graph Options | Node and Link Spacing | Spacing Increment for Many Links to a higher value, since a directional link can be connected via only half of the circumference of a node.

This command shows two dialogs. The first dialog shows a list of all predicates that have triples in the database for nodes that have been displayed during this browser session for the current triple-store. (It's the same list as is shown by Global Options | Select Current Predicates.) If you select a predicate, then the second dialog asks which of the four layout directions should be used for that predicate.

Using this command will not automatically redo the layout to reflect the new constraint. You will need to use either Layout | Update Layout Incrementally or Layout | Redo Layout from Scratch yourself after this command.

Use Visual Graph Options | Layout Options | Clear Layout Direction for a Predicate to clear layout directions that have been set up by this command. That will return to the default behavior where nodes are placed wherever they fit best, without regard to direction.

This command is present only in the graph view.

See also Layout | Do Tree-Like Spring Layout, which constrains the direction of all link lines according to the minimum path lengths of each node from the selected node.

Visual Graph Options | Layout Options | Clear Layout Direction for a Predicate

Removes a specification for laying out all links for a particular predicate in one general direction. A dialog will show a list of all predicates that are currently being laid out in a single direction, and which are applicable to nodes that have been browsed so far. Choosing one allows the links for that predicate to once again be laid out in any direction.

A quicker alternative to this menu bar command is to right-click a link in the legend (one for which a direction has been specified) and use the Clear Layout Direction command on the shortcut menu there.

Note that the layout directions that have been set up by Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate are saved in your preferences file, and will continue to be in effect in future sessions until you remove them with this command.

This command is present only in the graph view.

Visual Graph Options | Layout Options | Canvas Resize Factor

This is the factor by which Layout | Make Canvas Larger (or Smaller) will resize the scrolling canvas each time it is invoked. A larger value allows more quickly switching between very different canvas sizes, but a smaller value allows more accuracy in choosing a canvas size that is just large for a particular graph, in order to minimize the size of the rectangle that encloses all nodes.

Visual Graph Options | Layout Options | Drag Scroll Zoom Factor

This controls how fast the canvas will scroll when you click the background and drag the mouse. The number is the factor by which the mouse movement distance is multiplied to find the distance by which to scroll the canvas. A larger value lets you reach another part of the graph more quickly, but makes it harder to stop exactly where desired.

Visual Graph Options | Layout Options | Mouse Wheel Zooms

When checked, the mouse wheel will do zooming in the graph view, and otherwise it will do scrolling.

When in zooming mode, the wheel performs the commands Layout | Zoom In (when pushed forward) and Layout | Zoom Out (when pulled backward). This is similar to using an airplane joystick. You can still scroll with the mouse by clicking on the background of the node pane and dragging in any direction while holding the mouse button down.

When in scrolling mode, the wheel will scroll the visual graph vertically when used by itself, or horizontally when the control key is held down.

Visual Graph Options | Layout Options | Include Legend in Saved Pixmaps

When checked, File | Save Layout as Pixmap will include the legend in the saved image. Otherwise it will contain only the nodes and links from the graph pane.

Visual Graph Options | Layout Options | Show Saved Layout Pixmaps

When checked, File | Save Layout as Pixmap will display the pixmap that it saved. When Gruff is running in a web browser, it will appear in a new browser tab. Otherwise it will be shown in the default program for displaying PNG files, unless Global Options | Miscellaneous | Use Web Browser for All Documents is enabled.

Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout

The number of nodes in the visual graph at which the layout will switch from a constraint-based algorithm that's used for smaller graphs to a spring algorithm that's used for larger graphs.

The constraint-based algorithm specializes in avoiding any overlapping between nodes and links, to make it clear which nodes are linked by each link line. But that algorithm does not scale well, and so a spring layout is used for larger graphs to find a solution much more quickly, though it does not attempt to prevent nodes from overlapping link lines.

This option affects the commands Layout | Redo Layout from Scratch and Layout | Update Layout Incrementally. On the other hand, Layout | Update Layout Vigorously always uses the spring algorithm and Layout | Update Layout Conservatively always uses the constraint-based algorithm.

The spring layout will be used even for fewer nodes if Visual Graph Options | Constraint-Based Layout Options | Link to Node Ratio Limit is exceeded.

Visual Graph Options | Spring Layout Options | Spacing Factor

The value of this option is a small integer, where a larger value results in a visual graph with nodes that are spaced farther apart. It's difficult to tweak the algorithm to produce a desirable spacing for any graph, and so this value may need to be adjusted to personal taste or to the types of visual graphs that are done. The value may need to be larger for graphs that are larger or have many cycles in them.

Visual Graph Options | Spring Layout Options | Velocity Divisor

The value of this option is an integer, where a larger value results in a layout that is smoother (when animated) but which takes longer. A smaller value results in a layout that is "wilder" (when animated), but which may actually untangle crossed chains of nodes more successfully.

Roughly speaking, the total of the distances from a node to its ideal positions relative to each of its linked or nearby nodes is divided by this number to find the amount by which its velocity is incremented at each iteration.

Visual Graph Options | Spring Layout Options | Slowdown Exponent

The value of this option is a small integer that affects how gradually or abruptly a spring layout will slow down before stopping. The velocities of nodes are deliberately dampened so that the layout can approach a final state and finally stopped. A lower value for this option will cause the layout to slow down more linearly (more gradually), while a larger value will cause it to maintain a speed that's closer to full speed over most of the layout, and then to slow down more abruptly toward the end.

Visual Graph Options | Spring Layout Options | Grid Cell Size

This is the width and height, in pixels, of an internal grid that's used to speed up spring layouts. A smaller value makes the spring layout faster, but as a tradeoff may degrade the layout results somewhat, especially by clumping nodes too closely together. To achieve the best feasible speed, trial and error could be used to find the smallest value that does not appear to degrade the layout quality for your layouts.

This option works by dividing the canvas into a grid of cells and keeping track of which nodes are in each cell at any given time. Then when finding nodes that are close to each to make them repel each other, it looks only in the same cell and the neighboring cells of each moving node to consider only nearby nodes, rather than looping over all of the other cells, which scales badly.

Two nodes that have many links may normally repel each other up to around 1000 pixels away (when zoomed in all the way), so the most conservative value would be around 1000. But in our tests layouts appeared not to be seriously degraded with values as low as 400, and so we set the default to a somewhat conservative value of 600.

A lower value can also cause nodes that have more than a few links to annoyingly jump back and forth during animated layouts, even when that doesn't appear to hurt the final layout.

Visual Graph Options | Spring Layout Options | Reduce Nodes Overlapping Links

When this option is enabled, the spring layout algorithm will reduce the amount of overlapping between node boxes and link lines that tend to pass through them. This makes a more readable and neater-looking layout, but it takes something like twice as long. You could turn this option off for a faster layout, though then the algorithm will not attempt to keep nodes from overlapping link lines at all.

This neater-but-slower approach will never be used when the current number of displayed nodes is greater than Visual Graph Options | Spring Layout Options | Maximum Nodes for Reducing Overlapping.

Visual Graph Options | Spring Layout Options | Maximum Nodes for Reducing Overlapping

This is the maximum number of nodes where the spring layout will attempt to reduce the amount of overlapping between node boxes and link lines when Visual Graph Options | Spring Layout Options | Reduce Nodes Overlapping Links is enabled. That option greatly increases layout time for very large graphs, where the greater clarity that it provides is no longer apparent anyway. This option allows using the neater-but-slower approach for smaller graphs but never for larger graphs were it's no longer worth the additional time.

Visual Graph Options | Spring Layout Options | Keep Nodes on Canvas

When this option is enabled, nodes that get shifted out of the range of the current canvas will be forced back onto the canvas. That avoids not being able to see all of the nodes during an animated spring layout, though the layout might be somewhat better when this option is off to allow nodes to roam freely. By default a layout that roams out of the canvas will be brought back to the center of the canvas at the end of the layout, or you can use Layout | Center the Graph explicitly if needed to bring the whole visual graph back into view.

Visual Graph Options | Constraint-Based Layout Options | Begin Full Layout at Random Positions

This option affects only the constraint-based layout algorithm that's used for smaller visual graphs.

When unchecked, Layout | Redo Layout from Scratch will begin with all nodes at the center of the visible part of the window, and it should produce the same layout every time.

When checked, Layout | Redo Layout from Scratch will begin with the nodes distributed randomly within the visible part of the window, and it will produce a different layout each time.

It may be useful to use this option to attempt several different layouts in order to choose the best one. It may also help to get a layout started more quickly if it has more than a few large leaf nodes, which can have trouble finding a place to move to from the center. In general, though, layouts may take a little longer and not be quite as good as when starting with all nodes at the center.

This command is present only in the graph view.

Visual Graph Options | Constraint-Based Layout Options | Link to Node Ratio Limit

This option lets you avoid using the constraint-based layout algorithm for highly-cyclic graphs, where it often takes a long time to find a solution where no link lines cross through unrelated nodes.

If the number of links that are currently displayed divided by the number of nodes that are currently displayed is greater than this number, then the spring layout algorithm will be used instead, even if the number of nodes is less than Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

This command is present only in the graph view.

Visual Graph Options | Tree Layout Options | Orient Tree Layouts Vertically

When enabled, the commands Layout | Do Tree Layout from Selected Node and Layout | Do Tree-Like Spring Layout will arrange the nodes downward from the selected node. Otherwise the nodes will extend rightward from the selected node.

Visual Graph Options | Tree Layout Options | Remove Unconnected Nodes

When enabled, the command Layout | Do Tree Layout from Selected Node will remove from the display any nodes and links that are not linked with the root of the tree by any paths through the currently displayed nodes and links.

Otherwise all of the current nodes and links will remain on the display. An incremental layout (as with Layout | Update Layout Incrementally) will then be done to ensure that nodes that are not in the tree will not overlap the tree or be left far away from it. If any of the nodes that are not a part of the new tree had been in a tree layout just before the new layout, they no longer will be after the new layout.

Visual Graph Options | Tree Layout Options | Center Parent Nodes by Children

When enabled, Layout | Do Tree Layout from Selected Node will attempt to position each node at the middle of its row of child nodes in the tree. Otherwise a parent node will initially be positioned at the top of its children in a horizontal tree or at the left end of them in a vertical tree, though it may later be moved toward the middle if Visual Graph Options | Tree Layout Options | Minimize Link Lengths is enabled, as part of the general shifting of nodes to reduce the lengths of their link lines.

When this option is on, the layout typically looks a little better but may take up more space in the breadthwise direction. Though sometimes one of these alternatives just happens to turn out nicer than the other.

Visual Graph Options | Tree Layout Options | Minimize Link Lengths

When enabled, an extra step is performed at the end of the traditional tree layout that's done by Layout | Do Tree Layout from Selected Node to reduce the distances between linked nodes. This is most useful when there are circularities in the displayed graph. It's probably to best to keep this option enabled unless you notice it slowing down tree layouts of large sets of nodes.

When this option is on, link lengths typically will be reduced when there are cycles in the graph, but there may be some interleaving of the children of different parents.

Visual Graph Options | Tree Layout Options | Minimum Leaves for Splitting Columns

This option specifies how aggressively to split columns or rows at each level in a tree layout to reduce the overall breadth of the layout, to reduce the amount of scrolling that's needed in the breadthwise direction. Decreasing the breadth will increase the length, though it may be more intuitive to scroll along the length. Only single-parent leaf nodes will be moved from a column or row into additional columns or rows, because moving other nodes would overly complicate the layout algorithm.

If there are at least this many single-parent leaf nodes in a column of a horizontally-oriented tree layout (or in a row of a vertically-oriented layout), then some of them will be moved into a second column, with each moved node placed beside a sibling node. Similarly, if there are at least three times this many such nodes, then some will be moved into two additional columns, and so on.

You could remove this behavior altogether by setting this option to zero or to a large integer.

Visual Graph Options | Tree Layout Options | Spacing Breadthwise

This is the minimum number of pixels between nodes that are beside each other at one level of a traditional tree graph performed by Layout | Do Tree Layout from Selected Node.

Visual Graph Options | Tree Layout Options | Spacing Lengthwise

This is the minimum number of pixels between nodes that are in successive levels of a traditional tree graph performed by Layout | Do Tree Layout from Selected Node. If there are many circularities in the graph, increasing this value may make it more readable.

Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal

When checked, any command that removes one or more nodes and/or links from the graph view will also remove any orphan nodes that remain after that operation. An orphan node is one that has no links to other nodes in the graph view.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Inclusion Options | Include Literals of All Languages

When disabled, commands on the Link menu will add literal nodes to the visual graph only when they have no language or their language tag is the Global Options | Miscellaneous | Preferred Language. Otherwise all literals will be included.

Visual Graph Options | Inclusion Options | Number of Total Links for Warning

If a command is about to add nodes and links to the graph view, and the resulting total number of links in the graph view would be greater than this number, then a confirmation dialog is first shown asking if you want to proceed. This helps you avoid adding more links to the graph view than you expected, or more than could feasibly be laid out at the desired canvas size.

If you proceed and there are more nodes and links than desired, you can still easily undo the operation with View | Go Back.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Inclusion Options | Number of Total Links for Abort

If a command is about to add nodes and links to the graph view, and the resulting total number of links in the graph view would be greater than this number, then the operation is aborted and a dialog mentions that fact. This limit is most useful to avoid waiting until all of the resources that would be added are even found, since the Total Links for Warning limit will be triggered after all of the resources are found. The wait in the meantime could be substantial if a huge number of links would have been found.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Inclusion Options | Number of Links from One Node for Warning

If a command is about to add nodes and links to the graph view, and the resulting total number of links from any single node in the graph view would be greater than this number, then a dialog is first shown asking if you want to proceed. This helps you avoid adding more links to a single node than you expected.

If many links are added to a single node, the node will be split into multiple copies of itself to avoid a layout problem.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Inclusion Options | Show 1 Level of Nodes on Display Only Linked Nodes

See Visual Graph Options | Show 2 Levels of Nodes on Display Only Linked Nodes immediately below.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Inclusion Options | Show 2 Levels of Nodes on Display Only Linked Nodes

These options determine how many levels of nodes are added to the display when you use Link | Display Only Linked Nodes. That command first removes all nodes from the display except for the currently selected node, which becomes the "starter node" of a new visual graph. The option to add 1 level of nodes will then add any nodes that are directly linked to the starter node by the current predicates. The option to add 2 levels will additionally add any nodes that are directly linked to those nodes by the current predicates.

These options allow you to quickly browse through a chain of nodes by repeatedly selecting a leaf node and then using Link | Display Only Linked Nodes to see that node along with any that are linked with it. Only the most recently displayed nodes will remain on the display, rather than retaining all nodes that have been displayed so far.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display

This is the maximum number of triples that will be displayed by Display | Display Some Sample Triples and by Display | Display Triples of One Graph. To see a larger visual graph, increase this limit and then use the Display Some Sample Triples command.

This option is used only when browsing an AllegroGraph store. When browsing a SPARQL endpoint instead, use Global Options | SPARQL Endpoints | Maximum Sample Triples to Display.

The Inclusion Options child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length

This is the maximum length of any paths that will be found by Link | Display Paths Between Two Nodes or Link | Display Only Paths Between Two Nodes. The length is measured as the number of links in the path. The value should be an integer and should be at least 2 to provide functionality not available elsewhere.

If there is a group of highlighted nodes and no selected node, then Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length for Highlighted Group is used instead.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length for Highlighted Group

This is the maximum length of any paths that will be found by Link | Display Paths Between Two Nodes whenever there is a group of highlighted nodes but no selected node. In that case, paths are found between every pair of nodes in the highlighted group, and so you may want to use this option to limit the search to shorter paths to avoid making the operation take a long time.

Nodes can be highlighted individually with Select | Toggle Highlighting of the Selected Node or Link or by control-left-clicking each one. A group of nodes can be highlighted at once with a control-left-click-and-drag to drag a box around them. If there is a selected node (with a red border), it can be deselected by clicking the background. (On the Mac use the command key here rather than the control key.)

When the value of this option is 2, the command Link | Display Non-Leaf Linked Nodes is likely a faster alternative that has a similar result, though that command does not display incremental progress for each pair of highlighted nodes.

Visual Graph Options | Finding Paths Between Nodes | Find Only Shortest Paths

If this option is enabled, as it is by default, then the commands Link | Display Paths Between Two Nodes and Link | Display Only Paths Between Two Nodes will call the function all-bidirectional-search-paths to find the paths to display, and otherwise will call all-depth-first-search-paths. The former function is guarranteed to return a list of only the shortest paths that are found, and is probably the best choice in most cases to avoid sometimes returning an unwieldy number of paths.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Path-Finding Timeout

This is the number seconds before the path-finding commands such as Link | Display Paths Between Two Nodes will give up and display a warning dialog about a timeout.

This value is also used to limit the command Link | Fill In All Links for the Current Predicates.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Number of Found Paths for Warning

If Link | Display Paths Between Two Nodes is about to add nodes and links to the graph view, and the number of found paths is greater than this number, then a dialog is first shown asking if you want to proceed. This helps you avoid inadvertently adding a huge number of nodes and links with that command.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Maximum Paths to Find

If this many paths are found, then the searching will end and return those paths, to avoid spending time finding additional paths that would not be displayed anyway.

Visual Graph Options | Finding Paths Between Nodes | Maximum Paths to Display

This is the maximum number of found paths that will be displayed. If more paths are found, then you can select the ones to display in a dialog that will appear, but no more than this number will be displayed in any case. See also Global Options | Maximum Choices When Selecting a Subset.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Left and Right

This option causes Link | Display Only Paths Between Two Nodes to pin the end nodes near the left and right edges of the window. This typically makes the paths clearer by stretching them more linearly between two edges of the window. Due to moving the end nodes, the automatic layout that's done is a full layout.

The other path-displaying command, Link | Display Paths Between Two Nodes, never pins the end nodes.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Top and Bottom

This option causes Link | Display Only Paths Between Two Nodes to pin the end nodes near the top and bottom edges of the window.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes Anywhere

This option causes Link | Display Only Paths Between Two Nodes to not pin the end nodes, allowing them to be moved about freely by the automatic incremental layout that's done after placing the new path nodes on the display.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Finding Paths Between Nodes | Path End Node Margin

This is the number of pixels between the edge of the graph pane and the end nodes of the paths that are found by Link | Display Only Paths Between Two Nodes, when that command pins the end nodes during the automatic layout.

The Finding Paths Between Nodes child menu is present only in the graph view.

Visual Graph Options | Time Bar | Start Time Predicate

The value of this option (if any) should be the IRI of a predicate that the current triple-store uses to supply beginning date or date-time values for nodes that have time ranges.

When using the time bar, a node will be temporarily removed from the visual graph if there are triples where that node is the subject, this predicate is the predicate, and the object is a date or date-time value that is later than the ending date of the time filter range. (Unless the node also has momentary date properties that are inside the time filter range; see Visual Graph Options | Time Bar | Momentary Time Predicates.)

The thing that differentiates the start and end time predicates from the momentary time predicates is that a node will be visible in the visual graph if its start date is before the beginning of the time filter range and its end date is after the end of the time filter range, even though neither of those date properties is inside the time filter range.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | End Time Predicate

The value of this option (if any) should be the IRI of a predicate that the current triple-store uses to supply ending date or date-time properties for nodes that have time ranges.

When using the time bar, a node will be temporarily removed from the visual graph if there are triples where that node is the subject, this predicate is the predicate, and the object is a date or date-time value that is earlier than the beginning date of the time filter range. (Unless the node also has momentary date properties that are inside the time filter range; see Visual Graph Options | Time Bar | Momentary Time Predicates.)

If a node has a start date property but no end date property, then the time bar considers that node's time range to extend from its start date to the end of time.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Momentary Time Predicates

The value of this option should be a set of IRIs for predicates that the current triple-store uses to supply individual date and/or date-time properties. The word "momentary" is to differentiate these individual times from the starting and ending dates that are used for time ranges. In the dialog that appears for specifying this option, place one predicate IRI on each text line.

When using the time bar, a node will be temporarily removed from the visual graph if there are any triples where that node is the subject and one of these predicates is the predicate, and the objects of all of those triples are dates that lie outside the time filter range. (Unless the node also supplies start and end dates that keep the node visible; see Visual Graph Options | Time Bar | Start Time Predicate.)

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Update Layout Automatically

When the time bar is present and this option is enabled, the visual graph layout will automatically be incrementally updated whenever you do something in the time bar that results in nodes being added to or removed from the visual graph.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Update Time Bar Range Automatically

When the time bar is present and this option is enabled, any Gruff command that results in nodes being added to or removed from the visual graph will automatically update the time bar range to surround all of the date properties of the currently displayed nodes. If the time filter range extends to the full time bar range, then it will continue to do so.

When the time bar is present and you use a Gruff command that adds nodes to the visual graph, some or all of those nodes may not appear if this option is off or the time filter range does not extend to the full time bar range. The reason is that those nodes are being filtered from the visual graph without ever being shown, though they will appear later if you remove the time bar or extend the time filter range to include those added nodes.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Show Tooltips for Date Property Markers

When the time bar is present and this option is enabled, moving the mouse cursor over a date property marker in the time bar will show a tooltip for the node that has that date property. The tooltip will appear just above the time bar in the visual graph pane (but will not appear if the time chart is present). The tooltip will contain three lines of text, where the first line is the label of the node that has the date property whose marker is under the mouse cursor, the second line is the label of the date property predicate, and the third is the date or date-time value.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Show Date Properties in Node Tooltips

When the time bar is present and this option is enabled, the tooltip for a node in the visual graph that has date properties that the time bar is using will be those date values instead of the usual tooltip for the node.

Visual Graph Options | Time Bar | Hide Orphans of Time Filtering

When the time bar is present and this option is enabled, if a time bar operation removes one or more nodes from the visual graph and that causes other nodes to no longer be linked with any other nodes in the visual graph, then those nodes that became orphaned due to time filtering will also be removed from the visual graph. They will return to the visual graph when they are no longer orphaned due to time filtering.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Range Expansion Percentage

This option affects how greatly the < and > buttons in the time bar change the time filter range (or time bar range with the Control key). When the button is extending the range, it will extend it by this percentage of the current range. When the button is narrowing the range, it will modify the range such that the old range is this percentage greater than the new range. (The latter behavior means that clicking a < button and then the > button that's next to it (or vice versa) will return the range to what it was before both of those operations.)

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Time Bar | Boundary Date Font

This is the font that's used for the date text in the time bar.

The time bar overview is at View | Optional Graph View Panes | Show Time Bar.

Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing

This is the minimum amount of space that the layout algorithm attempts to maintain between any two nodes in the displayed graph, measured in pixels. The number can be made smaller to save space, or larger for a less cluttered graph.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Minimum Link-to-Node Spacing

This is the minimum amount of space that the layout algorithm attempts to maintain between any link line in the displayed graph and any node to which it is not connected, measured in pixels. Keeping link lines clearly away from unrelated nodes makes it easier to tell which nodes are connected to which.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Node Label Margin

This is the number of pixels between the text in any node and the node's border. Use a smaller number to save space or a larger number for a cleaner look.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Preferred Node Width

When this option value is zero, Gruff will try to resize each node so that its width is similar to its height, in other words making the node as nearly square as it can. Otherwise it will make the node be as close to the specified width as it can. The width is measured in pixels.

The actual node width may vary in order to make the text fit. Gruff automatically wraps node text to fit on multiple lines so that the node is neither overly wide nor overly tall. It does this when possible by splitting the text only at space, dash, and underscore characters. But if a word is still too long, then it may be split at Visual Graph Options | Node Labels | Maximum Word Length in Node Boxes. And wrapping will be done only at space characters if Visual Graph Options | Node Labels | Highlight Search Text in Nodes is off.

Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy

This is the number of displayed links that a node may have before it is automatically split into multiple copies of itself. The multiple copies will be linked with each other by a special thicker link line.

If this number is large, then a many-linked node can use up an overly large amount of screen space. The default is rather small to conserve screen space.

When the spring layout that's used for larger graphs gets used, it uses the maximum of this option value and 64 as the effective limit. The spring layout doesn't try to prevent nodes from overlapping link lines, and so there is less need to separate a many-linked node into multiple copies.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Spacing Increment for Many Links

This is the number of additional pixels of spacing to require around a node for each of its links beyond the first four. When a node has many other nodes directly linked with it, the other nodes generally need to be positioned farther from the many-linked node in order for the layout to succeed. Otherwise some of the linked nodes will typically be placed near the many-linked node, thereby blocking a large angle through which other nodes could be linked.

When a link has a layout direction constraint (see Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate), this increment is added doubly for that link to help accomodate the additional layout requirement.

You may need to increase the value of this option if the layout is having trouble finding a solution when there are nodes with many links, especially if some of them have direction layout constraints. Or try decreasing Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy.

This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Add Spacing for Long Paths

When this option is turned on, additional spacing will be required between any two nodes where the shortest path between them is relatively long, and similarly between any node and link-line. This usually results in a cleaner layout with unrelated clusters of nodes not so close to each other, and with fewer unnecessary crossed links.

This option sometimes makes the layout require more iterations to complete. It also typically makes the layout take up a little more space.

This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Long Path Spacing Increment

This is used only when the Add Spacing for Long Paths option is enabled. This value is then the number of additional pixels of spacing to require between any two nodes for each link in the shortest path between the nodes beyond the first two links.

For example, if this value is 15 and Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing is 12 (as they are by default), then two nodes that are just two links apart can be positioned with only 12 pixels of spacing between them. But two nodes that are three links apart will require 27 pixels of spacing between them, two nodes that are four links apart will require a spacing of 42 pixels, and so on.

This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Long Path Maximum Spacing

This is used only when the Add Spacing for Long Paths option is enabled. It is then the maximum number of additional pixels of spacing that will be added between two nodes (or between a link and a node) due to the length of the shortest path between them.

This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Limit Outward Stretching

This option limits the amount by which nodes may be moved outward toward the edge of the canvas during a layout. It tends to result in a smaller visual graph, but possibly could reduce the quality of a layout otherwise.

If this option is turned off, you can still constrain the size of the layout with Layout | Make Canvas Smaller.

This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

The Node and Link Spacing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Link Line Mousing Margin

This is the distance from a link line within which the mouse cursor must be in order to be considered "on" the line. A larger value makes it easier to position the mouse on a link line (in order to see its tooltip or select it), but could lead to some ambiguity when mousable link lines are close together.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Spacing | Snap Alignment Resolution

When dragging a node in the graph view, this is how close the dragged node must be to being exactly aligned with another node before it will be snapped into exact alignment. The units are pixels.

A dragged node is snapped into alignment with other nodes to make it easier to exactly center nodes above or beside other nodes, to look as good as possible for presentation.

A light red bar will be drawn during the drag from the dragged node to the node with which it is being aligned. To continue seeing the red bar after the drag (and bars for all other aligned nodes as well), turn on Visual Graph Options | Node and Link Spacing | Show All Alignment.

To disable snap alignment altogether, set this option to zero.

Visual Graph Options | Node and Link Spacing | Snap Alignment Reach

This is how close a dragged node must be to another node before it might be snapped into alignment with it. The units are pixels.

For example, if the value of this option is 500 and the dragged node is 400 pixels to the right of another node, then it will be snapped into horizontal alignment with that node whenever it is nearly horizontally aligned with it. But if it is 600 pixels away, then no snap alignment will be done.

Visual Graph Options | Node and Link Spacing | Show All Alignment

When true, a light red bar will be drawn between every pair of nodes that are currently exactly aligned with each other vertically or horizontally, as long as the nodes are fairly close to each other as determined by Visual Graph Options | Node and Link Spacing | Snap Alignment Reach.

This is useful while dragging nodes into alignment to make sure that you left each node in alignment. It's also useful for checking all of the alignment after aligning multiple sets of nodes.

Visual Graph Options | Node and Link Flashing | Flash Legend Matches

If this option is enabled (as it is by default), then left-clicking an item in the legend pane to select it will cause any nodes or links in the graph layout that are matches for that legend item to "flash" a number of times. This makes it easier to spot the matching nodes or links.

A node is flashed by dimming its background color and then undimming it. (The degree of dimming is determined by Visual Graph Options | Node and Link Flashing | Flashing Node Color Delta.) A link is flashed by making it thicker and then restoring its normal thickness.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Flashing | Flash End Nodes of Found Paths

If this option is enabled (as it is by default) when Link | Display Paths Between Two Nodes or Link | Display Only Paths Between Two Nodes is used, then the two end nodes for the paths will flash after the nodes and links for the paths are added to the display and the layout is updated. This helps to spot the requested end nodes after the layout updating likely moved them.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Flashing | Flash Newly Added Nodes

If this option is enabled (as it is by default) when a command on the Display menu is used to add a single new node to the display, then that node will flash momentarily to help you spot it. This is useful mostly when there are already a good many nodes on the display.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Flashing | Flash Selected Search Matches

If this option is enabled (as it is by default) when you select a particular matching node with Text Search | Search the Current View, then that node will flash momentarily to help you spot it.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Flashing | Times to Flash

This is the number of times that matching items in the graph layout will flash when an item in the legend pane is left-clicked, if Visual Graph Options | Node and Link Flashing | Flash Legend Matches is enabled.

If this value is nil rather than an integer, then matching nodes or links will continue to flash indefinitely, as long as an item in the legend is selected. The only ways to deselect the selected item in the legend are to click the legend's background area or to press the Escape key when the legend pane has the keyboard focus.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Flashing | Flashing Time Interval

This is the number of milliseconds between flashing nodes or links on or off when Visual Graph Options | Node and Link Flashing | Flash Legend Matches is used.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Node and Link Flashing | Flashing Node Color Delta

This is the amount by which to alter the background color of nodes in the graph layout when Visual Graph Options | Node and Link Flashing | Flash Legend Matches is used. The value should be a positive integer, and is subtracted from each of the red, green, and blue components of a node's background color, where each component of the color is an integer between 0 and 255 inclusive.

The Node and Link Flashing child menu is present only in the graph view.

Visual Graph Options | Tooltips | Show Node Tooltips

When checked, a small informational pop-up window will appear whenever the mouse cursor lingers over a node, if that node's resource has an rdfs:comment property in the database. The comment string will appear in the tooltip window.

Node tooltips are always disabled when [Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse] (#VisualGraphOptionsLinkLabelsDrawLinkLabelsforNodeUnderMouse) is enabled.

The Tooltips child menu is present only in the graph view.

Visual Graph Options | Tooltips | Show Link Tooltips

When checked, a small informational pop-up window will appear whenever the mouse cursor lingers over a link line. The tooltip window will list all of the predicates that that link line represents. This set of predicates is not necessarily all of the predicates for which there are triples in the database connecting the two resources, but is instead the set of predicates that you have requested to see in the graph view.

If a number appears appears in parentheses at the end of the tooltip string, this indicates the number of redundant triples that are in the database for this particular subject, predicate, and object.

Similar information is always shown in the status bar, though there may not be enough room there when a link line represents multiple predicates.

The Tooltips child menu is present only in the graph view.

Visual Graph Options | Tooltips | Tooltip Font

This is the font that is used in the tooltip windows that appear in the graph view and the outline view.

The Tooltips child menu is present only in the graph view.

Visual Graph Options | Tooltips | Tooltip Background Color

This is the background that is used in the tooltip windows that appear in the graph view and the outline view.

Visual Graph Options | Tooltips | Node Tooltips Delay

This is the number of milliseconds that the mouse cursor must linger over a node before its tooltip will appear. The default value is relatively long to avoid annoying tooltips appearing when you are trying to click on a node to select it.

The Tooltips child menu is present only in the graph view.

Visual Graph Options | Tooltips | Link Tooltips Delay

This is the number of milliseconds that the mouse cursor must linger over a link line before its tooltip will appear. The default value is relatively short because there is not much other reason to linger over a link line, and because the predicates that are shown in the tooltip are not otherwise displayed in the graph view (except in the status bar, which may be some distance away).

The Tooltips child menu is present only in the graph view.

Visual Graph Options | Tooltips | Highlight Links of Node Under Mouse

When enabled, moving the mouse cursor over a node will highlight all of the link lines that are connected to it. This may clarify which other nodes are linked with the one under the mouse.

If the node is in a tree layout (see Layout | Do Tree Layout from Selected Node), then all of the links that are in paths between the node under the mouse and the root node of the tree, as well as all descendents in the tree of the node under the mouse, will also be highlighted. This illuminates all of the paths in the tree that are related to the node that's under the mouse.

Visual Graph Options | Tooltips | Highlighted Links Delay

This is the number of milliseconds that the mouse cursor must linger over a node before the link lines that are connected to it will be highlighted. There is a short delay to avoid the annoyance of lots of link line being highlighted very briefly as you move the mouse across a set of nodes.

Visual Graph Options | Antialiasing | Antialias Lines

This option has an effect only on the Windows platform.

When enabled, link lines between nodes in the graph view are drawn using multiple shades of the line color to make the lines appear smoother. Arrowheads are drawn this way as well. This slows down the drawing somewhat.

Visual Graph Options | Antialiasing | Antialias Text

This option has an effect only on the Windows platform.

When enabled, horizontal text in various places (in all views) is drawn using multiple shades of the text color to make the text appear smoother. This slows down the drawing somewhat.

Antialiased text takes up a different amount of space (usually more), and so may warrant updating the layout after turning it on or off, as with Layout | Update Layout Incrementally.

When ClearType is used on Microsoft Windows, it may be preferable to this somewhat fuzzy text antialiasing. But when ClearType is not available (such as by default when using Remote Desktop, for bandwidth reasons), this antialiased text may be preferable to non-ClearType text.

Visual Graph Options | Antialiasing | Suppress Antialiasing During Animation

This option has an effect only on the Windows platform.

When enabled, lines and text will not be drawn in a smooth, antialiased way during animated layouts when they otherwise would be. Antialiasing slows down the drawing, which is particularly noticeable during animation.

Visual Graph Options | Arrowheads | Arrowhead Length

This is length of all arrowheads that are drawn in the graph view, measured in pixels.

Visual Graph Options | Arrowheads | Arrowhead Width

This is width of all arrowheads that are drawn in the graph view, measured in pixels at the base of the arrowhead.

Visual Graph Options | Arrowheads | Draw Arrowtails

Whether a stub is drawn on the non-arrowhead end of each link line in the graph view. This is useful to differentiate a link that is connected to the node from one that merely happens to be passing under the node.

Visual Graph Options | Color Gradients | Show Node Color Gradients

This option has an effect only on the Windows platform.

When enabled, the background of each node box is drawn using multiple shades of its hue, varying the shade smoothly from lighter to darker from the top of the node to the bottom. This produces a pleasing pseudo-three-dimensional effect.

Node color cannot be as light in this mode because of the need to keep the lightest part of the node within the maximum lightness while using the same hue over the whole node.

This command is present only in the graph view.

Visual Graph Options | Color Gradients | Color Gradient Intensity

This option has an effect only on the Windows platform.

This is the difference between the lightest and darkest shade of the gradient colors for each node, where 255 is the lightest value. A larger value produces a more noticeable gradient effect.

A larger value tends to make most nodes darker, due to the need to keep the lightest shades from exceeding the maximum lightness value while using the same hue over the whole node.

This command is present only in the graph view.

Visual Graph Options | Color Gradients | Suppress Color Gradients During Animation

This option has an effect only on the Windows platform.

When enabled, node backgrounds will not be drawn with color gradients during animated layouts when they otherwise would be. This can speed up the animation somewhat.

This command is present only in the graph view.

Visual Graph Options | Color Nodes for Node Type

When this option is in effect, the background color of each node in the graph view is determined by the rdf:type property of the node's resource, if any. (Also, a single color will be used for all literals, and another single color will be used for all non-literals that have no rdf:type property.)

Initially colors will be assigned automatically for the types of any displayed nodes, but you can select the color to use for a type with Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type.

If you abort the coloring of nodes by pressing Escape or Q, you can resume the coloring by selecting this option, even if it is already in effect. Otherwise node coloring will resume whenever you invoke any command that triggers node coloring.

This command is present only in the graph view.

Visual Graph Options | Color Nodes for Unseen Links

When this option is in effect, the background color of each node in the graph view is determined by whether the node has additional linked nodes in the triple-store that are not currently displayed in the graph view. This tells you which nodes are worth selecting for use with the commands in the upper section of the Link menu for adding linked nodes.

See About Node Background Color for Unseen Links in the middle of the documentation for the Link menu for details.

If you abort the coloring of nodes by pressing Escape or Q, you can resume the coloring by selecting this option, even if it is already in effect. Otherwise node coloring will resume whenever you invoke any command that triggers node coloring.

This command is present only in the graph view.

Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color

If this option is enabled, and a node has multiple rdf:type properties, then Gruff will attempt to find the "most specific" type of the node and then color the node to indicate that type. When this option is disabled, Gruff will arbitrarily choose one of the node's types. The most specific type is defined as the one that has the longest chain of superclasses above it, using the subClassOf predicate.

This option is on by default because it typically doesn't use much time in an AllegroGraph store to find the most specific type. But the corresponding option that's used with SPARQL endpoints is off by default because the added time is typically greater with a SPARQL endpoint. That option is Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color.

Another option for controlling which types are used for node colors, and which does not have a time cost, is Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color.

Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color

This option gives you more control over the colors that are used in the graph view to indicate the type of each node. If a node has multiple types, and some of them but not all are in this list of types to avoid using for node color, then one of the node's types that are not in this list will be used to color that node.

When the dialog appears, enter the complete URIs of the types to avoid using, with one URI on each line. (It does not matter whether you include angle brackets.) It's best to place the types that should be most avoided toward the top of the list; the reason is that if all of a node's types are in this list of types to avoid, then Gruff will choose the type that comes latest in this list to use for that node's color.

The types that you enter will be used only for the particular store that's currently open. So you can set up a different set of types for each store that you browse.

An easy way to add a type to this list is to right-click the node that's shown for it in the legend (if it appears there) and select the command Avoid This Type for Node Colors from the pop-up menu.

If Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color is enabled, then Gruff may choose the most desirable types automatically in most cases. But this option may still be useful for further control, especially when a node has multiple types that are equally specific. Also, finding the most specific type for each node can be slow, especially with SPARQL endpoints, and so it may desirable for efficiency reasons to disable that option (which is actually Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color when using a SPARQL endpoint) and use this one instead.

See also Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color.

Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color

This option gives you more control over the colors that are used in the graph view to indicate the type of each node. If a node has one or more types that are in this list, then one of those types will be used to color that node.

When the dialog appears, enter the complete URIs of the types to prefer using, with one URI on each line. (It does not matter whether you include angle brackets.) It's best to place the types that should be most preferred toward the top of the list; the reason is that if more than one of the node's types are in this list, then Gruff will choose the type that comes first in this list to use for that node's color.

The types that you enter will be used only for the particular store that's currently open. So you can set up a different set of types for each store that you browse.

An easy way to add a type to this list is to right-click a node in the graph view and select Select Preferred Type for Node Colors from its pop-up menu, though that works only if the node has multiple types to choose from. You could add several types that way, and then show this dialog to arranage them into the preferred order. You can also click on a type node in the legend and use View | Copy (Control+C) to copy its URI to the clipboard, and then paste it into this dialog.

See also Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color.

Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type

Lets you specify the background color in which to draw nodes that have a particular value for their rdf:type property. This color will be used only when the Visual Graph Options | Color Nodes for Node Type option is in effect.

To use the command, first select a node and then invoke the command. A pop-up menu of all of the types of that node will appear. Select the type whose color you want to specify. A color-selecting dialog will appear.

Alternately, right-click the node for the type in the legend pane, and select the command Set Background Color for Type.

The color that is used for a node will be the color for the most specific type property of the node to which you have assigned a color, if any, and otherwise will be a randomly-generated color for the most specific type for the node. The menu will list the types with the most specific type first. Type specificity is defined as the length of the longest chain of superclasses for the type.

Visual Graph Options | Node and Link Color for Types | Remove Color Mapping for Selected Node's Type

Lets you remove a mapping from a type to a color that you had specified at some earlier time. If the selected node has any type properties for which you have specified colors, then a pop-up menu of those types will appear. Selecting one will remove the color mapping for that type.

A node's color will be determined by its most specific type for which there is a specified color mapping. Using this command on a more specific type allows the color for a less specific type property of the node to be used instead. This may be useful if too many colors are currently being used, by mapping a smaller set of more general types to node colors.

This command is present only in the graph view.

Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate

Lets you specify the color in which to draw link lines that represent a particular predicate.

To use the command, first select a link line by left-clicking on it and then invoke the command. The color dialog will appear to let you select a new color for the predicate that the link line represents.

Alternately, right-click the link for the predicate in the legend pane, and select the command for assigning its color.

A single color will be used for all link lines that represent multiple predicates. So if the selected link line represents multiple predicates, then the color that you select will be for all multiple-predicate link lines, and otherwise it will be for all link lines that represent the same single predicate as the selected link line. Another single color will be used for all bridge lines that connect multiple copies of a node that has many links.

This command is present only in the graph view.

Visual Graph Options | Node and Link Color for Types | Specify Line Width for Selected Link's Predicate

Lets you specify the line thickness with which to draw link lines that represent a particular predicate. It presents a dialog with line widths between 1 and 9 inclusive, which is measured in pixels.

Alternately, right-click the link for the predicate in the legend pane, and select the command for assigning its line width.

This command is present only in the graph view.

Visual Graph Options | Node and Link Color for Types | Specify Dashing for Selected Link's Predicate

Lets you specify the dashing style in which to draw link lines that represent a particular predicate. It presents a dialog that lists all of the available dashing styles, from which you can choose a new style.

Alternately, right-click the link for the predicate in the legend pane, and select the command for assigning its dashing style.

This command is present only in the graph view.

Visual Graph Options | Node and Link Color for Types | Suppress Link Line Styles

Causes all link lines in the graph view to be drawn in the same way, using a solid gray line having a line width of 2 pixels. The link lines section of the legend will be removed as well, since all of the entries would look the same.

Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Current Links

This is the background color for nodes that have linked nodes in the triple-store for the current predicates that are not currently displayed. This color is used only when the Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type option is in effect.

If a node is drawn with this background color, then you know that the Link | Display Linked Nodes for the Current Predicates command will add additional nodes to the display.

(This color also happens to be reused in the table and query views for cells of predicates that are in the set of current predicates.)

This command is present only in the graph view.

Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Non-Current Links

This is the background color for nodes that have linked nodes in the triple-store for non-current predicates that are not currently displayed. This color is used only when the Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type option is in effect.

(This color also happens to be reused for variable nodes in the graphical query view.)

This command is present only in the graph view.

Visual Graph Options | Node Color for Unseen Links | Node Color for No Unseen Links

This is the background color for nodes that have no linked nodes in the triple-store that are not currently displayed. This color is used only when the Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type option is in effect.

(This color also happens to be reused for a couple of other things, namely (1) cells in the table view for objects that are currently in the visual graph in the graph view, and (2) non-variable nodes in the graphical query view.)

This command is present only in the graph view.

Visual Graph Options | Window Background | Graph View Background Color

This is the color in which the general background of the graph view will be drawn. If the color is the standard light gray color (192 192 192), then it will actually use the system-wide button background color instead; this is the default.

This value is not used if a background pixmap has been specified and Visual Graph Options | Window Background | Show Background Pixmap (if any) is enabled.

This command is present only in the graph view.

Visual Graph Options | Window Background | Legend Background Color

This is the color in which the background of the legend pane in the graph view will be drawn. If the color is the standard light gray color (192 192 192), then it will actually use the system-wide button background color instead; this is the default.

Visual Graph Options | Window Background | Background Pixmap

Displays a dialog for selecting a pixmap file to provide a background image in the graph view. This should be a png, jpg, or bmp file, or perhaps other formats on Mac and Linux.

If you do select a valid image file, then this command will turn on Visual Graph Options | Window Background | Show Background Pixmap (if any) automatically. It will also turn Visual Graph Options | Window Background | Stretch Background Pixmap on for a relatively large image or off for a relatively small one; if that's not an appropriate setting then you will need to set the stretching option after choosing the pixmap file.

This command is present only in the graph view.

This command is not available on the Mac due to an unsolved problem with the GTK function for loading pixmaps.

Visual Graph Options | Window Background | Show Background Pixmap (if any)

Determines whether the background pixmap is currently displayed in the graph view, if one has been specified with Visual Graph Options | Window Background | Background Pixmap. This command allows quickly toggling the image on and off (by pressing the 7 key on the main part of the keyboard).

Using a background pixmap can slow things down, especially animation. When using remote display software such as Windows Remote Desktop, you will probably want to turn the background pixmap off.

This command is present only in the graph view.

Visual Graph Options | Window Background | Stretch Background Pixmap

When checked, the background pixmap will be stretched to fill the current scrolling canvas size of the visual graph (if a background pixmap is being used). When unchecked, the pixmap will instead be replicated (tiled) to fill the canvas.

This command is present only in the graph view.

Visual Graph Options | Window Background | Graphical Query View Background Color

This is the color of the general background in the Graphical Query View. It should be a light shade for best contrast with the content in the window.

This command is present only in the graphical query view.

Visual Graph Options | Node Border Color

This is the color in which the lines on the edges of all node boxes are drawn.

This command is present only in the graph view.

The Evaluation Options Menu

Evaluation Options | Evaluate on Enter

When enabled, pressing the Enter key just after a lisp expression where the parentheses are balanced will automatically evaluate that expression, just as if you had pressed the Evaluate One button.

You could enter newlines without doing evaluations (even when this option is enabled) by typing Shift-Enter or Control-Enter.

Evaluation Options | Clear on Eval One

When enabled, all text will be removed from the Input text pane whenever you evaluate a single expression, either by pressing the Evaluate One button or by pressing the Enter key just after a complete lisp expression when Evaluation Options | Evaluate on Enter is enabled. This allows you to more easily enter and evaluate a series of single expressions without pressing the Clear Input button after each one.

On the other hand, if you want to enter a set of expressions in order to evaluate them all at once or to collect into a file for reloading later, then you will need to turn this option off. (Or possibly edit the code elsewhere and then paste it into the Input text pane.)

Evaluation Options | Add Output at the Top

When enabled, anything that's printed by evaluated expressions and the returned values will be printed above whatever text is already in the Output text pane, rather than below it. This may help to see the output more easily, straight across from input that's at the top of the Input text pane. Turning this option off will print text to the bottom of the existing text, more like a traditional lisp listener.

When multiple expressions are evaluated at once with the Evaluate All button, the output from all of those expressions will always be printed from top to bottom, even when this option is enabled. A short line will separate the output from different expressions that are evaluated together, while a longer line separates the output from different evaluation gestures.

Evaluation Options | Input Font

The font that's used in the input pane. Usually a fixed-width font is best for code.

Evaluation Options | Output Font

The font that's used in the output pane. Usually a fixed-width font is best for code.

Evaluation Options | Evaluation Print Level

This is the value that the Common Lisp special variable print-level will have while evaluating code.

Evaluation Options | Evaluation Print Length

This is the value that the Common Lisp special variable print-length will have while evaluating code.

The Help Menu

Help | Gruff Documentation

Visits the Gruff documentation on the AllegroGraph web site.

Help | Use Web Browser for Menu Help

When checked, pressing F1 while a menu item is highlighted will visit the web page that contains all Gruff documentation, just as when you press F1 at other times to invoke Help | Gruff Documentation, and then it will scroll the browser to the help entry for the menu command that was highlighted when you pressed F1. This applies to menu bar commands as well as pop-up menu commands.

Otherwise pressing F1 while a menu command is highlighted will display just the help for the highlighted menu command in a modal dialog, as plain text.

Help | Show Warnings in Dialog

When checked, all warnings and error messages will be shown in a modal dialog. Otherwise most warnings and error messages will simply be shown in the status bar.

The modal dialog ensures that you do not miss the message, but requires a mouse click or keystroke to dismiss the dialog. When you have become very familiar with Gruff's warnings and errors, turning off this option may speed up your workflow.

Help | Quick Start

Displays a dialog with brief instructions for getting started with building visual graphs of nodes and links. This dialog is shown by default when Gruff is started up, though it has a check box at the bottom for disabling that default. You can use Gruff to follow this dialog's instructions while the dialog is present, though it may cover content that you need to see.

Help | Show Quick Start on Startup

An option for whether the Quick Start dialog will appear whenever Gruff is started up. It is on by default for new users, though typically you would disable it after working through the Quick Start once. You can disable this option either with this menu command or with the check box at the bottom of the Quick Start dialog itself.

Help | Example Store Demo

Creates a very small sample store showing some subclass relationships in the animal kingdom, along with who eats whom, and lays out the usual visual graph. This will first close the store that you currently have open, if any, though only if you confirm.

Help | Animated Demo (Actors Store)

Runs an animated demonstration of various Gruff views and commands. The demo will run indefinitely in a loop until you stop it either by invoking this command again or by pressing the Escape key or the Q key. You can press the spacebar at any time to pause and resume the demo without exiting it.

This demo requires that the actors store currently be open, or that you be connected to the dbpedia SPARQL endpoint. The triples for creating the actors store are available here: https://franz.com/agraph/gruff/download/ After downloading the actor triples you can create a new store and load the actor triples into it. Any time thereafter you can open the actors store and then run this demo.

The demo illustrates various graph view commands, including Link | Display Linked Nodes for the Current Predicates, Link | Display Only Paths Between Two Nodes, and Layout | Update Layout Incrementally. It also illustrates jumping to related nodes in the table view, which then adds the browsed path to the graph view. Another sequence shows building a query in the graphical query view, generating the SPARQL query text for it into the query view, and then creating a visual graph in the graph view from the query results.

Help | Activity Logging

Toggles activity logging on or off. Activity logging collects information into a file for debugging purposes, including the amount of time that various things take. If you have found a way to reproduce a problem, including something that takes a long time, then you could turn logging on, then reproduce the problem and turn logging back off, and then send the output to Franz to help us debug the problem. We may ask you to do this if we can't figure out a problem from a bug report that Gruff can produce when an actual error occurs.

Logging can slow things down significantly, so you should try not to leave it on accidentally. The word LOGGING will be present in the title bar when it's active, as a reminder. Logging will always be off when you first start up Gruff, even if it was still active when you last exited Gruff.

When toggling logging on, a dialog will ask whether you want to replace the leftover log file (if there is one) or append to it. Select Append if the earlier information is still relevant, or else Replace to avoid cluttering up the file with stale information otherwise. Logging can generate lots of output, so it's best to try to minimize what gets collected.

When toggling logging off, the log file will be shown in Notepad on Windows or in a web browser on other platforms. If it doesn't get shown for some reason, you can find it in a file named gruff-activity-log.txt. That file will be in your personal documents directory on Windows or in your home directory on other platforms.

The output is intended for Franz to interpret, but if you're curious about the output then here are a few pointers. The value in the leftmost column is usually the number of seconds that elapsed since the previous value was written to that column; an exception is that top appears there for the first line that's written for a new command or other gesture that the user performs, because the idle time just before that is not relevant. The value in the second column is >>> when Gruff enters a body of code that it's monitoring, and then there will be a corresponding entry later that instead shows the number of seconds that that whole body of code took; these bodies of code can be nested, which is shown by indentation of the textual information. The phrase (server access) is shown for low-level calls that may access the remote server, which is where most time is typically spent. Other lines are printed for higher level commands that surround those calls to indicate what higher-level functionality is making those calls to the server.

Help | About

Displays the About dialog with the current Gruff version number. The version number is held in the variable *gruff-version*.

Using Command Line Arguments When Starting Gruff

You can make Gruff perform various activities when it starts up by specifying certain command line arguments, as described here. In each case, you can specify either the single-letter version such as -h or the full-name version such as --host. For each option, the possible values are shown to the right of the two alternate option names.

To start Gruff using command line arguments, you first need to find the Gruff executable, then run it with the desired arguments.

On Windows, Gruff is installed in a Gruff subdirectory of Program Files (for 64-bit) or Program Files (x86) (for 32-bit). Using the path to that directory and the executable, here is an example of running Gruff with a couple of command line options: 

"C:/Program Files/Gruff 8.1.4 (64-bit)/gruff.exe" -o 9009 -l no

(The quotes around the program name are required because it contains spaces.)

On Linux, depending on where it is installed, the executable is called gruff.

On macOS, Gruff is usually installed as /Applications/Gruff 8.1.2 - AG7.0.1.app/. And a special script, in the Contents/Resources/ subdirectory, named script is used instead of the usual Contents/MacOS/ program. You can execute this script by going to the Resources subdirectory and running ./script. Options to Gruff are passed as options to script, as usual. For example, 

cd "/Applications/Gruff 8.1.4 - AG7.0.1/Contents/Resources/"  
./script -o 9009 -l no

(The quotes around the program name are required because it contains spaces.)

Running Gruff in a Web Browser

Gruff can now run on HTML5/JavaScipt inside a web browser, rather than in the native windowing system of the platform (where "native" actually means GTK version 2 on Linux and Mac). This looks nicer on Linux and Mac and allows using Gruff in a browser that's on a different machine than where the Gruff server is running. You can also use the browser's standard commands for zooming the entire application (Control+Plus, Control+Minus, and Control+Zero, or Command instead of Control on the Mac). And there is no need to install GTK and X11 (especially on the Mac).

The officially supported web browsers are Chrome, Firefox, Safari, Edge, Opera, Vivaldi and Brave, though any Chromium-based browser is expected to work. Internet Explorer cannot be supported because its JavaScript support is too out-of-date. One limitation of Safari is that File | Save Layout as Pixmap and File | Display Layout in New Browser Tab are not working.

Here are the associated command-line arguments, which are part of the Common Graphics windowing and graphics library on which Gruff is built.

-b --run-as-web-browser-server yes or no

yes means to run Gruff in a web browser and no means to run in the native windowing system. The rest of this set of options apply only when running in a web browser.

The default value for this option can be set with Global Options | Miscellaneous | Run in Web Browser, so that you can run Gruff interactively in the preferred mode, rather than running it in a terminal where you can specify command line arguments.

-l --start-local-client yes or no

Whether to automatically show Gruff in a new tab of a browser that's on the machine where the Gruff server is running. Otherwise you will need to connect a browser to the server yourself, by telling it to visit a location such as hazel:12345 (if Gruff is running on a machine named hazel, and the browser server port that it's using is 12345). The machine can be specified as localhost if the browser and Gruff are running on the same machine.

When this argument is no, it might appear that things are hung because the terminal where you run Gruff does not get a fresh prompt (unless you add an ampersand to the end of the command line to run Gruff in the background). But actually Gruff is running and waiting for you to connect from a web browser. When you close the browser tab, Gruff will exit and then the terminal will get a fresh prompt.

-k --client-timeout non-negative integer

If this is a positive integer and no client connects within that many seconds, then the server will exit. If this option is not used or the value is zero, then a default timeout of 120 seconds will still be used if the start-local-client option is yes. This ensures that the server application will not be left running invisibly if no web browser successfully connects to the server as expected.

-x --exit-server-on-client-exit yes or no

Whether the Gruff server will exit automatically when the user closes the browser tab where they are using Gruff. You will probably want to use this option (or else the server window option below) to ensure that the Gruff server exits; otherwise you would need to use some facility of the operating system to kill the Gruff server. Though when this option is no, one user could disconnect from Gruff and then another (or the same) user could connect to that same running Gruff server, perhaps from a different machine (but only one user can be connected to a particular running Gruff server at any one time).

--confirm-exit yes or no

When yes, the web browser will prompt for exit confirmation when you try to close the web browser tab for Gruff or reload the page. This may avoid accidentally losing the usaved state that you have built in Gruff.

-o --browser-server-port non-negative integer

The port at which a browser can connect to Gruff. If this option is not used or the value is zero, then Gruff will let the operating system select a port that is known to be free, and this port will be printed to the terminal where Gruff is being run when possible (probably not on Windows). If the start-local-client option is yes, then the browser will connect to this port automatically, and so you don't need to know the port number for entering it into a web browser.

When specifying a particular port, it should be between 1 and 65535, inclusive. If an attempt to use that port fails, then the OS will be asked to select a free port, as when specifying zero.

The value can alternately specify a range of ports, as in 12800-12804. Then each port in the range will be tried until one is found that does not fail. This may be needed when a firewall allows only ports that are in that range.

The following example would run Gruff in web browser mode, but not start a local client automatically, and use port 9009. The end user could then use Gruff in a web browser on the same machine by telling the browser to visit localhost:9009, or on a different machine by telling the browser to visit [machine-name]:9009. 

    gruff -b yes -l no -o 9009

Specifying a particular port is not advised because it would likely fail or lead to confusion if other software is already using that port. And specifying the same hard-coded port for multiple runs of Gruff could lead to confusion if a previous Gruff process did not actually exit for some reason, because the browser will likely attempt to connect to the old Gruff process instead of the new one. But you may need to use this option anyway when you are not starting a local client automatically and you're starting Gruff from a terminal that will not print an OS-selected port, because otherwise you would not know what port to tell a web browser to visit. Or you could specify a port if it happens to work reliably, to avoid needing to specify a different port every time in the web browser.

When running Gruff in a web browser and using The HTTP Interface to Gruff, this port (or the one in the --port-file) will be the one to use in HTTP commands as well.

-i --port-file file path

If specified, this should be either a full pathname such as /home/me/gruff-port.txt or c:\foo\free-port-for-gruff.txt, or else just a file name and type such as browser-port.txt to indicate the path ~/.gruff.d/browser-port.txt on Linux and Mac or a path like c:\Users\me\Documents\browser-port.txt on Windows. The browser server port number that was used will then be printed into the file with no other text.

This could be useful on Windows when an unknown free port was selected by the OS but it could not be written to the terminal where Gruff was run. An adminstrator who ran Gruff could then find the port in the file and pass it on to end users, for example. It might also be useful in a custom script to find the port that was used, where the script should first delete the file if it exists, then wait until the file exists again, and finally read the port from the file.

This option may also be needed when using The HTTP Interface to Gruff to find the port to send HTTP commands to.

--custom-title title bar string

Replaces the usual Gruff title bar text with an arbitrary string. This is useful mainly when embedding Gruff in a web application, where a title that makes sense in the context of that application may be more suitable. See Embedding Gruff In a Web Page.

The use-custom-title-bar-string HTTP command is an alternative when using The HTTP Interface to Gruff, but it may not be feasible with that command to make a custom title appear immediately when Gruff starts.

--launcher yes, no, or only

Whether this Gruff instance will listen for launch HTTP requests that a web page can send to request a separate instance of Gruff for use by that web page only, where typically it will embed Gruff in an HTML iframe or a new browser tab. This built-in feature allows web pages to remotely launch Gruff without using a separate application server. See Embedding Gruff In a Web Page.

When this option is used, a --max-clients option can also be used to specify the maximum number of instances of Gruff that can be running at the same time.

If the value is only, then this launcher instance of Gruff will act only as a launcher and never serve a client itself, instead always launching a new instance (up to the --max-clients limit). When the value is yes, the launcher instance itself will be used for a requesting client whenever it is not currently serving a client. Using the launcher instance will start up Gruff more quickly because it doesn't need to run a new executable, though then the launcher instance perhaps might not respond as quickly to another request for an instance if the Gruff client is busy at the moment.

In the normal case, the response that is returned to the web page for its launch request will be the port at which the web page can use its private instance of Gruff, on the same machine as the launcher instance. Typically a launcher instance is running at a known port, and a web page will first send a launch request to that port and receive the port for its own instance, and then tell an iframe or new browser tab to vist the machine at that port to display Gruff. The launch HTTP command looks simply like host:launcherPort/launch, or like host:launcherPort/launch?password=secret if the -remote-password option was also used when running the launcher instance.

If the launcher refuses to server the launch request (typically because the maximum number Gruff instances are currently running, then the response to the launch request will be zero. If a --remote-password was also specified when running the launcher, but it was not passed correctly in the launch request, then the response is -1.

When a Gruff instance was launched by another one, then it will accept an exit HTTP request to exit that Gruff executable. And a launcher Gruff will accept an exit request to exit Gruff for its current client, if it is serving one. A web page might want to send this request before it sends another launch request to restart Gruff, so that it works even when the maximum number of Gruffs are currently running. If a --remote-password was specified when running the launcher instance, then it must be passed with this request to any launcher or a launched instance.

An example of JavaScript code for using this option is in the file embedding.html in the main Gruff folder. That file also demonstrates controlling Gruff remotely (such as from a web application) by sending HTTP requests to it.

There is no corresponding project option for this command line option.

--remote-password string

When specified, this is a password that a web page must include in any launch request to remotely launch its own instance of Gruff, and in any exit request. See the --launcher option above. Alternately you could specify the CGJS_REMOTE_PASSWORD environment variable, which may be more secure.

There is no corresponding project option for this command line option.

--file-to-publish file path

This option can be used to specify an HTML file to publish as a web page that can visited on the machine where the CG/JS application is running. This could be used along with the --launcher command (for example) to publish a demo JS/HTML file that a user could visit from their web browser, where that demo file could have a button that sends a launch command to this application to embed its own instance of Gruff in an iframe.

The path of the published URL will be the name of the file, without its file type. So if the file is specified as /home/me/cool-demo.html (for example), then the path of the URL to visit will be cool-demo, and a user could visit the page by directing their web browser to host:port/cool-demo (substituting the needed values for host and port).

There is no corresponding project option for this command line option.

-a --secure [no value]

When specified, Gruff will run in a secure mode to protect the machine that Gruff is running on from possible nefarious or accidental actions that could remove files, for example. This is probably useful mainly when running Gruff in client/server mode, where an administrator runs Gruff on a server machine and then a user connects to it from a browser on a different client machine. In that case Gruff reads and writes files on the server machine. Secure mode is always used when launching Gruff from AGWebView, to protect the AllegroGraph server machine.

A general change is that the file selection dialog is never shown, because it would allow the user to browse the whole file system on the server machine. And all files will be read from and written to a single utilities directory that is in the home directory on the server machine of the adminstrator who ran Gruff there (or the personal Documents directory on Windows). When Gruff asks for an existing file, a dialog will simply list the names of the files of the apropriate type that are in this directory, and when asking for where to write a new file, Gruff will just ask for a file name to be typed in.

Some Gruff commands are removed completely in secure mode. These include View | Lisp Evaluation View, File | Miscellaneous | Load and Evaluate Lisp Code, Global Options | Communications | Start HTTP Server, Global Options | Miscellaneous | Run in WebBrowser, Global Options | Miscellaneous | Document Base Folder, and all of the commands on the Load Triples and Export Displayed Data As child menus of the File menu.

And Prolog mode is disabled in the query view, unless the user has been given the permission for evaluating arbitrary code on the server.

--debug [no value]

When running in secure mode with the --secure option above, normally the lisp evaluation view will not be available. But it will be if you also pass this option. This may be useful to specify temporarily to allow debugging that is otherwise not feasible in secure mode, especially for any problems that are unique to secure mode.

When using Gruff from WebView, there is no way to pass command line arguments to the Gruff process that it creates. But you could set the environment variable GRUFF_DEBUG to true on the AllegroGraph server machine to tell WebView to pass this option.

-y --utilities-directory file path

If specified, this should be the full pathname of a directory, for example /home/me/gruffstuff/, where the final slash is optional. Then Gruff will save certain utility files into this directory rather than into the user's home directory (or personal Documents directory on Windows).

Gruff uses this directory for various utility files such as gruff-options.cl and bug reports to avoid asking the user every time to navigate in the file dialog to some arbitrary directory. Some files that the user probably doesn't need to view (such as gruff-options.cl) will be saved into a .gruff.d subdirectory of this directory on Linux and Mac, while other files will be saved directly into this directory.

The user-visible files that Gruff saves into this directory (or else into the user's home directory) include reports that are written by the commands Global Options | Show Non-Default Option Values and Help | Activity Logging, along with bug reports. Even these files may not need to be accessed by the user from this directory, because Gruff will also display them in a web browser tab (or in Notepad on Windows when Gruff is not running in a web browser tab itself).

--limit-connections-to-same-machine yes or no

Whether a web browser will be able to connect to the Gruff server only if it's running on the same machine as the server. This would prevent, for example, anyone from connecting from elsewhere on the Internet if the server machine is not behind a firewall.

There is no single-letter alternative for this option.

-s --show-cgjs-server-window yes or no

Whether an additional browser tab should appear for the Gruff server, where you can exit Gruff by closing that tab or the window that's inside it. This is probably useful only for an administrator who is running Gruff on one machine, allowing one or more users to connect to it from browsers on other machines. Only a single user can use a particular Gruff server at any one time, though; if an additional user tries to connect at the same time, then a message will appear in their browser about the application already having the maximum number of allowed users.

-g --cgjs-logging yes or no or a file path

If yes, then the server window (if present) will have a child window that displays logging information, such as when a user connects or disconnects or uses a menu command. The --show-cgjs-server-window option must also be yes for this to take place.

If a file path, then logging information will be incrementally appended to that file. If the --launcher option was used, then any instances that are launched by this one will also append information to the same file.

Opening a Store with Command Line Arguments

An alternative to File | Open Triple-Store is to pass command line arguments when starting up Gruff. That will automatically open the specified triple-store just after Gruff starts up.

Here are the various Unix-like command-line arguments that are related to opening a particular triple-store. If all of the needed information is supplied, then the store-opening dialog will not appear, and you can proceed to browse the opened triple-store immediately. Otherwise, if the host and port specified, then the store-opening dialog will appear with the lists of catalogs and stores at that host to choose from. If the host and port are not both specified, then all of these arguments are ignored.

-h --host machine name

The name of the remote server machine that is running the AllegroGraph server.

-p --port port number

The port at which to connect to the AllegrGraph server.

-q --scheme http or https

The scheme with which to connect to the server. Defaults to http when not specified.

-c --catalog catalog name

The name of the catalog in which the store resides. If unspecified or specified as nil, it defaults to the root catalog.

-n --name repository name

The name of the triple-store to open. If this is unspecified, then you can select it on the dialog that appears.

-r --read [no value]

If specified, the store will be opened in read-only mode. Otherwise it will be opened in read/write mode.

-u --user user name

The user name. This is required unless an anonymous user has been set up on the AllegroGraph server.

-w --pass password

The password for the user that was specified.

The following example would start up a Gruff on Linux. (On Windows you would say gruff.exe rather than gruff.) It will attempt to open a store named my-store in read-only mode in the root catalog on host machine37 at port 10088. 

gruff --read -h machine37 -p 10088 -n my-store -u alice -w xxxxxx

-z --specification repository specification text

An alternative to passing the separate values above for the triple-store to open is to use this option for passing everything as a single specification value such as test:xyzzy@myhost:12345/mycatalog:myrepo, as documented here.

--endpoint URL

The URL of a SPARQL endpoint to connect to, rather than opening an AllegrGraph triple-store. The --user and --pass arguments can be used with an endpoint if the endpoint requires them.

--endpoints-password string

The general password that allows using SPARQL endpoints in Gruff. This gets saved in the user's options file, and so probably wouldn't need to be passed often.

Loading Options from a Different Place with a Command Line Argument

-f --options-file-path file path

Normally the options file is saved to and loaded from your home directory on Mac and Linux or your personal Documents directory on Windows. But you can use this command line argument to cause the options file to be loaded from (and saved back to) some custom location. For example (on Windows): 

gruff.exe -f c:/foo/gruff-options.cl

Specifying the Position and Size of Gruff with a Command Line Argument

These options are not used when running Gruff in a web browser. Gruff is always maximized within its browser tab because no other applications share that "logical screen".

-e --exterior left.top.right.bottom

This one is independent of the store-opening arguments, and specifies the initial position and size of the Gruff window. The value should be the left, top, right, and bottom of the window, with those components separated by periods. Each component is an integer indicating the pixel distance from the left or top of the screen. For example: 

gruff --exterior 200.100.900.600

If the exterior argument is the special value maximized, that ensures that Gruff comes up full-screen: 

gruff --exterior maximized

Running Gruff's HTTP Server at Startup Time

-t --http-server-port port number

Starts up Gruff's HTTP server for receiving commands remotely via HTTP from other software agents. See Global Options | Communications | Start HTTP Server.

--disable-menus [no value]

This may be useful when exclusively controlling Gruff remotely via Gruff's HTTP server, without allowing the user to interactively use Gruff commands. The menu bar will not appear, and other Gruff gestures will be disabled as well.

Using Gruff Programmatically in a Lisp Application

The documentation above describes using the standard Gruff browser as a standalone application to build a visual graph interactively and incrementally. Gruff can also be used as a fasl file that is loaded into an Allegro development lisp. And a standalone Common Graphics application can be built that uses a pane like the main pane of Gruff's graph view for laying out a visual graph of nodes and links. This allows calling Gruff functions to build a visual graph with more complete programmatic control. The fasl file is called gruff.fasl.

For example, you could use your own lisp code to collect a set of triples that you would like to display as a visual graph, and then pass them to the function display-triples to display them in a single operation.

This section of the Gruff documentation describes the lisp interface to Gruff. To instead control Gruff programmatically from applications that are written in ANY language, there is another API for sending HTTP requests to Gruff. See The HTTP Interface to Gruff.

First a few general notes, and then the actual API.

If you want, you can evaluate the example expressions in the order in which they appear below, which should work without doing anything else other than first loading AllegroGraph and the Gruff fasl file.

All Gruff symbols below are exported from the gruff package, which has the nickname uf as well as (mostly for backward compatibility) the nickname ab.

Requirements for Loading the Gruff FASL File

(1) The AllegroGraph client (and therefore Gruff) requires using a case-sensitive version of Allegro Common Lisp (ACL), which generally means using allegro.exe rather than allegro-ansi.exe.

(2) If you're loading Gruff 8.0.0 or later into ACL 10.1, then you first need to install the CG/JS patches that provide the post-10.1 version of Common Graphics that Gruff now requires. See https://franz.com/ftp/pri/acl/cgjs/.

(3) Gruff requires the AllegroGraph lisp client, which is in a file called agraph.fasl, but Gruff probably doesn't know where to find the right version of that file. So you should find and load the AllegroGraph lisp client first yourself, like this:

Using the standard full browser or a plain graph layout pane

When using Gruff programmatically, you can either create the complete standard interactive browser with all of its menu commands and alternate views, or create a plain window pane that acts like the main graph view pane.

When using the full browser, you can use its interactive commands in combination with programmatic calls to the functions documented below. The function gruff-browser will return the full browser window if it exists, and otherwise will create it and return it.

Many Gruff functions take a node-pane argument that specifies the window to which nodes and links should be added. When using the full browser, the expression (graph-node-pane (gruff-browser)) would return the proper value to pass. But that is the default value of the node-pane arguments, and so you can more simply just not pass that argument to use the full browser by default.

In short, to use the full browser after loading the Gruff fasl file, just call gruff-browser and then don't pass the node-pane argument to other Gruff functions. If you first get into the gruff package, then you won't need to use package qualifiers on symbols from Gruff, Common Graphics, or AllegroGraph. 

(in-package :gruff)  
 
(gruff-browser :expose t)

That expression works fine when using Allegro's windowized IDE. If you are instead using the base lisp's console window, or our Emacs-Lisp Interface (ELI) in Emacs, or slime in Emacs, then you probably should use the following code instead, which ensures that Gruff's events are handled in a Common Graphics event-handling loop as expected. This runs Gruff in a new CG process rather than in the process where you evaluate this form. This is actually necessary in slime, which seems to use a timeout that aborts from Gruff commands if the Gruff browser was created in the slime REPL. (The call to initialize-cg is needed only once in a lisp session, though it's OK to call it multiple times. It has already been called if you're in the IDE.) 

(initialize-cg)  
(in-cg-process (:process-name "Gruff")(gruff-browser :expose t))

When using a plain "graph view" node pane instead of the full browser, you can create it as a part of the window hierarchy of a custom Common Graphics application. The application could have additional functionality, or it could simply have its own interface to the standard Gruff commands. Create a graph view node pane by calling the CG function make-window on the graph-node-pane class. Typically the node pane should have a parent window that supplies the window frame and perhaps a menu bar and a status bar and so on. Here's an example. 

(in-package :gruff)  
 
(defvar *my-node-pane* nil)  
 
(let* ((my-frame-window (make-window :my-frame  
                         :class 'frame-window  
                         :title "Sample Raw Node Pane"  
                         :scrollbars nil  
                         :exterior (make-box-relative 100 50 900 600))))  
  (setq *my-node-pane* (make-window :my-node-pane  
                         :class 'graph-node-pane  
                         :owner my-frame-window  
                         :child-p t  
                         :scrollbars t  
                         :state :normal  
                         :exterior (visible-box my-frame-window)  
                         :right-attachment :right  
                         :bottom-attachment :bottom  
                         :handle-scrolling-keys t  
                         :background-color (system-dialog-background-color))))

You would then pass my-node-pane as the value of the node-pane argument to various other Gruff functions.

That example would make the node pane fill the interior of the parent window, and resize it along with the parent window when it is resized. It could instead have arbitrary sibiling panes.

Adjusting the size of the canvas for the layout

See the menu command Layout | Make Canvas Larger for an explanation of the need to adjust the canvas size to reasonably match the number of nodes and links in a visual graph.

When using the programmatic interface rather than the menu commands, the canvas size can be adjusted by calling the Common Graphics function set-page-size. For example, the following call will adjust the size of the scrolling canvas of a node pane to be 1000 pixels wide by 800 pixels tall. 

(set-page-size *my-node-pane* 1000 800)

It is best to set the canvas size before calling update-the-layout or other functions that do a layout automatically. Some trial and error is needed to get a feel for the appropriate canvas size.

Using the usual AllegroGraph functions to create or open a store

When using the Gruff browser in a development lisp or application (even when using the full Gruff browser window with its menu bar), you don't need to use Gruff's File menu commands to create or open stores. You can do that programmatically using the usual AllegroGraph functions such as open-triple-store or create-triple-store followed by load-ntriples.

But one issue is that if you create or open a store programmatically while the Gruff interface is viewing a previous store, then you need to either use the File | Miscellaneous | Clear and Uncache Everything menu command to clear the old store from the interface, or else call the function uncache-for-new-triple-store. Otherwise Gruff will attempt to use cached data that's no longer valid.

Here's an example of creating a new store, to allow the rest of the example expressions to work. 

(triple-store:create-triple-store  
  "test37" :server "localhost" :port 10088  
  :user "test" :password "xyzzy" :sessionp nil  
  :triple-store-class 'remote-triple-store)

The Programmatic Lisp API to Gruff

The symbols documented here are exported from the gruff package, which has the nickname uf.

display-triples

Displays node pictures and link lines in a graph-node-pane for a set of triples, and then does a layout to arrange the nodes for readability. 

(defun display-triples  
  (triples &key  
           uncache-for-new-triple-store  
           keep-old-nodes  
           (layout-from-scratch (or uncache-for-new-triple-store  
                                    (not keep-old-nodes)))  
           node-upi-for-initial-position  
           max-iterations  
           select-window  
           no-push-go-back-state  
           no-regroup  
           (node-pane (graph-node-pane (gruff-browser))))

triples should be a list of triples that exist in the currently open store. You can use whatever means you like to derive the list of triples to be displayed, such as one or more calls to get-triples-list in the AllegroGraph lisp client.

uncache-for-new-triple-store should be true if you have just programmatically created or opened a store after displaying nodes and links from a previous store. If the store was created or opened using the standard browser's File menu, then this was done automatically.

If keep-old-nodes is true, then any nodes and links that are already on the node pane will be retained, with the specified triples being added to them. If nil, then all nodes and links are first removed from the node pane.

If layout-from-scratch is true, then a "full layout" will be done with all nodes initially at the center of the node pane, to remove any bias from the current node positions that may have resulted from multiple "incremental" layouts. If nil, then an incremental layout is done with any old nodes starting out at their current positions.

If node-upi-for-initial-position is true, then it normally should be a part ID (a UPI, future-part, or string in ntriples format) of one of the nodes that are already displayed on the node pane, and keep-old-nodes should be true. Then any nodes that are added to the display will initially be positioned where the node for that UPI is currently positioned, and then moved from there as the layout is done. This is useful when adding a set of nodes that are linked in the store with the specified node, to make the incremental layout that follows disrupt the existing layout less than it would otherwise.

max-iterations is the number of iterations at which the automatic incremental layout will stop if it has not reached a stable state by that time. To suppress the layout altogether, specify 0 (because nil will default to some positive number). Suppressing the layout may be useful if you are going to modify the set of nodes and links that are added before you care to nicely arrange them, such as if you plan to remove all leaf nodes after adding the triples by calling remove-orphans.

If select-window is true, then the top-level window of the node pane will be brought to the front and given the keyboard focus.

If no-push-go-back-state is true, then the current state will not be added to the node pane's undo stack before doing the new operation. Otherwise an undo state will be added, allowing the user to return to the current state from the new state that results from this operation. A state consists of a particular set of nodes and links and the positions of all of the nodes.

If no-regroup is true, then objects that have many links will not be divided into multiple nodes according to Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy.

node-pane is the window onto which to add node pictures and link lines. It should be an instance of the graph-node-pane class. When unspecified, it will default to the node pane of the standard full Gruff browser window, which will be created automatically if it doesn't exist already. Otherwise it should a graph-node-pane instance that was created by calling the Common Graphics function make-window; see Using the standard full browser or a plain graph layoutpane.

Here's an example, which expects my-node-pane to exist from the example under Using the standard full browser or a plain graph layout pane, and for a new store to have been created.

First let's create some resources and add some triples for them to the store. The triples here will form a logical "wheel" with one node that's connected to the other nodes that are themselves connected in a loop. 

(defparameter *middle-thing* (upi (resource "MiddleThing")))  
 
(defparameter *things* (let* ((things nil))  
                         (dotimes (j 9)  
                           (push (upi (resource (format nil "Thing~a" j)))  
                             things))  
                         (nreverse things)))  
 
(defparameter *points-to* (upi (resource "PointsTo")))  
 
(let* ((count 9)  
       (triples nil))  
  (dotimes (j count)  
    (add-triple *middle-thing* *points-to* (nth j *things*))  
    (add-triple (nth j *things*) *points-to*  
                (nth (mod (1+ j) count) *things*))))

And now (this could be any time later), let's display the triples as a visual graph. This displays all triples whose predicate is PointsTo, which happens to include all of the triples we just created. 

(display-triples (get-triples-list :p *points-to*)  
                 :keep-old-nodes nil  
                 :layout-from-scratch t  
                 :node-pane *my-node-pane*  
                 :select-window t)

display-upis

Displays node pictures on a node pane for a set of subject and object UPIs, and adds link lines between them for a given set of predicate UPIs. 

(defun display-upis  
  (upi-list &key predicate-upis  
                 uncache-for-new-triple-store  
                 keep-old-nodes  
                 (layout-from-scratch (or uncache-for-new-triple-store  
                                          (not keep-old-nodes)))  
                 node-upi-for-initial-position  
                 max-iterations  
                 select-window  
                 no-push-go-back-state  
                 no-regroup  
                 (node-pane (graph-node-pane (gruff-browser))))

upi-list should be a list of subject and object part IDs of triples that exist in the currently open store. A node picture will be added to the node pane for each one. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

predicate-upis should be a list of predicate part IDs of triples that exist in the open store, or else t or nil. t means all predicates for which there are triples in the store, while nil means all current predicates, as set by calling set-current-predicates or using the Global Options | Select Current Predicates menu command in the standard browser.

Link lines will be added to the display to connect any of the new nodes with any new or already-displayed nodes that are linked by the specified predicates in the store. More specifically, a link line will be added to the node pane between two nodes whenever there are one or more triples in the currently open store where the subject or object of the triple is in the specified upi-list, the predicate of the triple is in the specified predicate-upis, and the other subject or object of the triple is either also in the upi-list or was already displayed on the node pane.

Display-upis will not work correctly with literals unless the treat-literals-as-objects option is turned on. When including literals you could either turn that option on or use display-triples instead.

See display-triples for descriptions of the other arguments.

Here's an example that would display the wheel from the example for display-triples, except excluding the middle node. 

(display-upis *things*  
              :predicate-upis (list *points-to*)  
              :keep-old-nodes nil  
              :layout-from-scratch t  
              :node-pane *my-node-pane*  
              :select-window t)

This would add the middle node to the existing nodes. The layout would probably be closer to a nice wheel-like shape if you change the :layout-from-scratch argument here to t. 

(display-upis (list *middle-thing*)  
              :predicate-upis (list *points-to*)  
              :keep-old-nodes t  
              :layout-from-scratch nil  
              :node-pane *my-node-pane*  
              :select-window t)

display-upis-from-file

Displays node pictures on a node pane for a set of subject and object UPIs that are listed in a file, and adds link lines between them for a set of predicate UPIs that are listed in the same file. This is like display-upis except that it reads the UPIs from a file instead of accepting them as arguments. 

(defun display-upis-from-file  
  (path &key keep-old-nodes  
             select-window  
             (layout-from-scratch (not keep-old-nodes))  
             (node-pane (graph-node-pane (gruff-browser))))

path is the pathname or path namestring of a file that contains the URIs of the nodes and links to display. The file should contain a list of URIs for nodes (subjects and objects), with one URI per text line, followed by a blank line, followed by a list of predicate URIs. All of the URIs should name objects that are in the currently open store.

See display-triples for descriptions of the other arguments.

Here is a small example of the contents of a file that could be passed to this function, after opening the dbpedia store. 

http://dbpedia.org/resource/Joanne_Woodward  
http://dbpedia.org/resource/Paul_Newman  
http://dbpedia.org/resource/The_Long%2C_Hot_Summer  
http://dbpedia.org/property/starring  
http://dbpedia.org/property/director

To display a set of triples from a file (rather than individual resources and predicates as with this function), you could use the usual AllegroGraph functions to create a new store and load triples into it, and then call the Gruff function display-store to display it.

find-and-display-paths

Displays nodes and links for all paths between two nodes that use certain predicates, up to a certain maximum path length. Returns the list of paths that were found. 

(defun find-and-display-paths  
    (node-upi1 node-upi2 predicate-upis  
               &key (finder-function 'triple-store:all-bidirectional-search-paths)  
               (maximum-depth 4) warn-on-many-triples  
               uncache-for-new-triple-store keep-old-nodes  
               (layout-from-scratch (or uncache-for-new-triple-store  
                                        (not keep-old-nodes)))  
               (end-node-placement (and layout-from-scratch  
                                        :left-and-right))  
               node-upi-for-initial-position  
               max-iterations select-window no-push-go-back-state  
               (timeout 30)  
               (node-pane (graph-node-pane (gruff-browser))))

node-upi1 and node-upi2 are the part IDs of the two resources and/or literals between which paths should be found. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

predicate-upis should be a list of predicate part IDs. Only paths that use only predicates from this list will be found. If this argument is nil, it will default to the current predicates (see current-predicates). If it is t, then all predicates will be used.

finder-function is the particular AllegroGraph Social Network Analysis (SNA) function to call to find the paths. The default value is triple-store:all-bidirectional-search-paths, which will find only the shortest paths even when maximum-depth is large. This argument could be any path-finding function that takes the same arguments, such as triple-store:all-depth-first-search-paths or triple-store:all-breadth-first-search-paths.

maximum-depth is the length of the longest paths that are to be found.

end-node-placement works as with display-paths.

If warn-on-many-triples is true and the number of found paths is greater than the number-of-found-paths-for-warning option of the node pane, then a confirmation dialog is shown, and the nodes and links are added to the display only if the user confirms.

If the call to a path-finding function does not return in timeout seconds, then this function gives up and returns the symbol :timeout.

The other arguments are passed straight through to display-triples.

This function corresponds to the menu command Link | Display Paths Between Two Nodes (when keep-old-nodes is true) and to Link | Display Only Paths Between Two Nodes (when keep-old-nodes is nil).

This function calls display-paths to display the paths that were found. If you are calling AllegroGraph's path-finding functions such as all-bidirectional-search-paths yourself, then you could pass the result to display-paths instead of calling this function. 

(find-and-display-paths (first *things*)(fourth *things*)  
                        (list *points-to*)  
                        :node-pane *my-node-pane*)

display-paths

Displays nodes and links for a set of paths that are specified as lists of nodes, for a particular set of predicates that link them. 

(defun display-paths (paths predicate-upis  
                            &key warn-on-many-triples  
                            uncache-for-new-triple-store keep-old-nodes  
                            (layout-from-scratch (or uncache-for-new-triple-store  
                                                     (not keep-old-nodes)))  
                            (end-node-placement (and layout-from-scratch  
                                                     :left-and-right))  
                            node-upi-for-initial-position  
                            max-iterations select-window no-push-go-back-state  
                            (node-pane (graph-node-pane (gruff-browser))))

paths is a list of lists of the part IDs of resources and/or literals, where each sublist should specify a sequence of nodes that are linked by the specified predicates. Typically this value would have been returned by one of AllegroGraph's social network path-finding functions such as all-depth-first-search-paths or all-bidirectional-search-paths. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

predicate-upis should be a list of predicate part IDs. Links will be shown between the displayed nodes only for the predicates in this list. If this argument is nil, it will default to the current predicates (see current-predicates). If it is t, then all predicates will be used.

If warn-on-many-triples is true and the number of triples in all of the paths is greater than the number-of-found-path-links-for-warning option of the node pane, then a confirmation dialog is shown, and the nodes and links are added to the display only if the user confirms.

end-node-placement determines whether the two end nodes are pinned near the edges of the window during the automatic incremental layout that occurs. Pinning the end nodes near the window edges typically makes the paths between them clearer by stretching them out. :left-and-right will place the node-upi1 node near the left edge of the window and the node-upi2 node near the right edge. :top-and-bottom would place them near the top and bottom edges, while nil will let the two end nodes float freely as usual during the layout. The default is :left-and-right when layout-from-scratch is true, but nil when layout-from-scratch is false (to avoid disrupting the current layout).

The other arguments are passed straight through to display-triples.

This function is called by find-and-display-paths, which first finds the paths to display from nodes that lie at the ends of the paths.

display-linked-nodes

Adds nodes to the display that are linked in the store to a particular specified node by any of the current predicates, and adds these links to the display. A link is also added to the display between any newly-displayed node and any newly-displayed or already-displayed node to which it is linked by any current predicate. 

(defun display-linked-nodes  
  (from-node-upi &key (keep-old-nodes t)  
                      (levels-to-add 1)  
                      (deselect-selected-node t)  
                      (exclude-explicitly-excluded-nodes t)  
                      (node-pane (graph-node-pane (gruff-browser))))

from-node-upi should be a part ID of a node that is already displayed on the node pane. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".) Node pictures will be added to the node pane, and link-lines will connect them to this node, for any nodes in the store that are linked with this node by any of the current predicates. Call set-current-predicates beforehand to establish the current predicates.

If keep-old-nodes is true, then nodes and links that were already on the node-pane will not be removed. If nil, all nodes and links will be removed except for the node of the specified from-node-upi.

levels-to-add should be a positive integer indicating how many links from the specified from-node-upi should be traversed to find additional nodes to add. The default is 1 to add only nodes that are directly linked to the from-node-upi by the current predicates. A value of 2 would also add any nodes that are linked to those nodes by the current predicates. Note that a higher value is likely to add more nodes than can reasonably be laid out or viewed at one time.

If deselect-selected-node is true, then the currently selected node (which in this case will be the from-node-upi node) is deselected before the layout is done. Otherwise the from-node-upi node will be fixed in place during the layout.

If exclude-explicitly-excluded-nodes is true, then no nodes that have been explicitly excluded by the user will be added to the node pane. Otherwise they will be added if they meet the other requirements. A node is excluded by calling remove-node-of-upi with the exclude argument as true.

See display-triples for a description of the node-pane argument.

This function corresponds to the menu command Link | Display Linked Nodes for the Current Predicates, except that that command always acts on the node picture that has been selected by the user.

Here's an example that uses the test objects from the preceding examples. It first displays the middle node by itself and waits a couple of seconds. Then it makes our points-to predicate be a current predicate and adds any nodes that are linked with the middle node by any current predicates. 

(progn  
 
  ;; Display the middle thing by itself.  
  (display-upis (list *middle-thing*)  
                :keep-old-nodes nil  
                :layout-from-scratch t  
                :node-pane *my-node-pane*  
                :select-window t)  
 
  ;; Add nodes to the middle node that are linked to it by  
  ;; any current predicates.  
  (sleep 2)  
  (set-current-predicates (list *points-to*) :node-pane *my-node-pane*)  
  (display-linked-nodes *middle-thing*  
                        :node-pane *my-node-pane*)  
 
  ;; For three of the nodes, add triples to connect them to  
  ;; new resources, and then display any nodes that are linked  
  ;; to the new ones by the current predicates.  
  (dotimes (node-num 3)  
    (sleep 2)  
    (dotimes (count 4)  
      (triple-store:add-triple  
       (nth node-num *things*) *points-to*  
       (triple-store:resource (format nil "Thing~a"  
                                (+ 100 (* node-num 10) count)))))  
    (uncache-for-modified-triple-store :node-pane *my-node-pane*)  
    (set-current-predicates (list *points-to*) :node-pane *my-node-pane*)  
    (display-linked-nodes (nth node-num *things*)  
                          :node-pane *my-node-pane*))  
 
  ;; The layout is probably not as nice as it could be due to  
  ;; doing multiple incremental layouts, so redo it from scratch.  
  (sleep 2)  
  (update-the-layout :layout-from-scratch t  
                     :node-pane *my-node-pane*))

display-store

Displays node pictures and link lines in a graph-node-pane for some or all of the triples in the currently open store, and then does a layout to arrange the nodes for readability. 

(defun display-store  
  (&key (limit 100)  
        graph  
        uncache-for-new-triple-store  
        keep-old-nodes  
        include-nodes-for-label-properties  
        include-nodes-for-comment-properties  
        (layout-from-scratch (or uncache-for-new-triple-store  
                                 (not keep-old-nodes)))  
        max-iterations  
        select-window  
        no-push-go-back-state  
        no-regroup  
        (node-pane (graph-node-pane (gruff-browser))))

limit is the maximum number of nodes to add to the display. When limit is less than the number of triples in the store, then an arbitrary set of triples that are found will be used, even if they are already displayed on the node pane. An effort is made to find chains of nodes and links to display, because that is what a visual can display more clearly than a simple table.

graph may be the UPI of one of the graphs of the store, to display only nodes that are in that particular graph.

Attempting to display all triples in a large store can easily overwhelm the ability of the software to do a layout in a reasonable amount of time. You can make the scrolling canvas larger to accomodate more nodes, though; see Adjusting the size of the canvas for the layout.

If include-nodes-for-label-properties is nil, then nodes that are the object of triples whose predicates are rdfs:label will be excluded from the display. If true, they will be included like any other node. Typically it is not useful to include nodes for label properties because their values are printed on the nodes for which they are the labels.

If include-nodes-for-comment-properties is nil, then nodes that are the object triples whose predicates are rdfs:comment will be excluded from the display. If true, they will be included like any other node. Typically it is not necessary to include nodes for comment properties because the comment strings are displayed in tooltips when holding the mouse over nodes for which they are the comments.

See display-triples for descriptions of the other arguments.

This function corresponds to the menu command Display | Display Some Sample Triples.

remove-node-of-upi

Removes the node picture for a UPI from the display, along with any link lines that are connected to it. 

(defun remove-node-of-upi  
  (node-upi &key exclude  
                 (node-pane (graph-node-pane (gruff-browser))))

Removes a node picture that has been added to the display at some earlier time. Any link lines that are connected directly to the node picture are also removed (because otherwise they would be left pointing to nothing).

node-upi should be a part ID of a node that is currently displayed (though if it is not found a status-bar message will simply indicate that). (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

If exclude is true, then the node will be marked as an indefinitely excluded node, and it will not be added back by functions or commands that add any nodes that are linked by the current predicates, or by display-store.

See display-triples for a description of the node-pane argument.

This function corresponds to the menu commands Remove | Remove Selected Node and Remove | Exclude Selected Node, except that those commands always act on the node that has been selected by the user.

Here's an example using the graph that was built in earlier examples. 

(remove-node-of-upi *middle-thing*  
                    :node-pane *my-node-pane*)

remove-orphans

Removes any orpan and/or leaf nodes from the display. 

(defun remove-orphans  
  (&key leaves-too unhighlighted  
        no-update no-warning  
        (node-pane (graph-node-pane (gruff-browser))))

This function removes from the display any nodes that are not connected to other displayed nodes by link lines, and optionally also any nodes that are connected to only a single other displayed node.

If leaves-too is true, then leaf nodes (ones that are linked to exactly one other displayed node) are removed in addition to orphan nodes. If nil, then only orphan nodes (ones that are not linked to any other displayed nodes) are removed. Note that removing leaves may turn some remaining nodes into leaves, and so calling this function again may remove additional nodes.

If unhighlighted is true, then a completely different thing is done, to remove all nodes except for ones that are highligted.

If no-update is true, then no layout is done after removing the nodes. If nil, then an incremental layout is done.

If no-warning is true, then no warning is shown in the status bar if there were no nodes to remove, and otherwise a warning will be shown. It may be useful to suppress the warning to avoid covering an earlier more important status bar message.

See display-triples for a description of the node-pane argument.

This function corresponds to the menu commands Remove | Remove All Orphan Nodes, Remove | Remove All Leaf Nodes, and Remove | Remove All Unhighlighted Nodes.

remove-all-nodes

Removes all nodes and links from the display. This is useful for clearing the display to begin building a new one.

This function corresponds to the menu command Remove | Remove All Nodes.

current-predicates

Returns the current predicates as UPIs. 

(defun current-predicates ()

Two values are returned, where the first is a list of UPIs of the predicates that will be used when a specified node is the subject of any triples that use those predicates, and the second being a list of UPIs of the predicates that are used when a specified node is the object of a triple.

set-current-predicates

Defines the set of predicates that are used by functions that use the current predicates. 

(defun set-current-predicates  
  (predicate-upis &key (node-pane (graph-node-pane (gruff-browser))))

Some functions and menu commands act on a set of current predicates. This is a convenience feature that allows specifying a set of predicates that are of interest a single time, and then making multiple calls to add nodes that are linked by those predicates.

For example, if you call display-upis with the predicate-upis argument as nil, then it will add link lines to the display for any triples that link displayed nodes by these current predicates. And the function display-linked-nodes always uses the current predicates.

predicate-upis should be a list of predicate part IDs. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

See the example for display-linked-nodes.

This function corresponds to the menu command Global Options | Select Current Predicates.

highlight-node-by-upi

Highlights or unhighlights a node that is on a node pane, by changing its background color. 

(defun highlight-node-by-upi  
  (node-upi &key off (node-pane (graph-node-pane (gruff-browser))))

Highlighted nodes are drawn with a light red background to make it easier to spot particular nodes. This function is like the menu command Select | Toggle Highlighting of the Selected Node or Link, except that you can specify an arbitrary node.

node-upi should be a part ID of a node picture that is currently displayed on the node pane. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

off should be nil to turn highlighting on for the node picture, or true to turn it off.

See display-triples for a description of the node-pane argument.

Alternately call remove-all-highlighting.

This function corresponds to the menu command Select | Toggle Highlighting of the Selected Node or Link.

remove-all-highlighting

Turns highlighting off for all node pictures that are currently displayed. 

(defun remove-all-highlighting  
  (&key (node-pane (graph-node-pane (gruff-browser))))

See display-triples for a description of the node-pane argument.

This function corresponds to the menu command Select | Remove All Node and Link Highlighting.

update-the-layout

Arranges the nodes that are currently displayed to make the overall layout of nodes and links relatively readable. 

(defun update-the-layout  
    (&key layout-from-scratch  
          max-iterations  
          fixed-node-upis  
          deselect-selected-node  
          compress-layout  
          center-the-graph  
          (node-pane (graph-node-pane (gruff-browser))))

fixed-node-upis may be a list of part IDs whose node pictures should remain at their current locations during the layout, forcing other nodes to arrange themselves around those fixed nodes. If nil, then no node pictures will be fixed in place. (A part ID is either a UPI, a future-part, or a string in ntriples format such as " ".)

If deselect-selected-node is true, then the currently selected node (if any) is deselected before the layout is done. Otherwise the currently selected node will be fixed in place during the layout.

If compress-layout is true, then an additional step is done after the main layout that tends to bring the nodes closer together so that the entire graph takes up less space. If nil, this is not done. See the menu command Visual Graph Options | Layout Options | Compress After Full Layout.

If center-the-graph is true, then after the layout is done, the entire set of nodes is moved to the middle of the scrollable canvas, and the window is scrolled to the middle of the canvas. If nil, this is not done. See the menu command Visual Graph Options | Layout Options | Center After Full Layout. 

(update-the-layout :node-pane *my-node-pane*  
                   :layout-from-scratch t)

See display-triples for descriptions of the other arguments.

This function corresponds to the menu commands Layout | Update Layout Incrementally and Layout | Redo Layout from Scratch.

center-the-graph

Centers the graph as a whole in the window. 

(defun center-the-graph  
  (&key (node-pane (graph-node-pane (gruff-browser))))

This function first moves the whole set of displayed nodes and links as a group to the middle of the scrollable canvas of the node pane, and then scrolls the node pane to the middle of the canvas.

The two options Visual Graph Options | Layout Options | Center After Full Layout and Visual Graph Options | Layout Options | Center After Incremental Layout cause this to be done automatically at certain times, but note that the option for centering after an incremental layout will scroll the window to the middle only if it was nearly scrolled to the middle before the layout. This function will always do it.

See display-triples for a description of the node-pane argument.

This function corresponds to the menu command Layout | Center the Graph.

gruff-browser

Returns the standard full Gruff browser, complete with its menu bar of interactive commands and its alternate views. If the browser does not exist currently, it is created automatically. 

(defun gruff-browser (&key expose exterior http-server-port disable-menus)

If expose is true, then the browser will be brought to the front and given the keyboard focus, whether or not the browser already exists. If nil, then it will come to the front only if it did not exist yet.

The exterior argument can be passed to specify the screen coordinates of the Gruff window, if it is being created. The value should be a Common Graphics box object that specifies the left, top, right, and bottom edges, as created by a call like (make-box 100 100 800 600).

The http-server-port argument may be an integer to tell Gruff to start up an HTTP server at that port, to allow controlling Gruff remotely with HTTP commands. See The HTTP Interface to Gruff.

If disable-menus is true, then no menu bar or pop-up menus will appear, and their keyboard shortcuts will be disabled as well. This may be useful for preventing the end user from controlling Gruff interactively if you want to exclusively control Gruff with HTTP commands.

The programmatic interface for graph layout can be used on the "graph view" node pane of the full browser, which is returned by this expression: 

(graph-node-pane (gruff-browser))

Alternately you can make and use a raw instance of the graph-node-pane class. See Using the standard full browser or a plain graph layoutpane.

graph-node-pane

This symbol names both a class and a function.

An instance of the class is a Common Graphics window on which node pictures and link lines are placed. Various Gruff functions take a graph-node-pane as an argument. You can use either the one in the standard full browser, which is returned by (graph-node-pane (gruff-browser)), or use a custom graph-node-pane instance that you create by calling the Common Graphics function make-window.

See Using the standard full browser or a plain graph layout pane.

This symbol also names a function, which returns the "graph view" node pane of the standard full Gruff browser. 

(defmethod graph-node-pane ((window gruff-frame))

This simply returns the descendent window of the standard full Gruff browser that is used for drawing visual graphs of nodes and links in the graph view.

This child window is the default value for functions where a node-pane argument is needed, so you likely will not need to call this function yourself. Either you will be using the full Gruff browser and letting the node-pane arguments default, or you will be using your own instance of graph-node-pane and passing that node pane instead.

The argument to this function should be the Gruff browser window that's returned by gruff-browser.

save-layout

Saves the current state of a visual graph, which can be loaded any time later with load-layout. 

(defmethod save-layout ((pane graph-node-pane) file)

pane is the graph-node-pane that is displaying a visual graph.

file is the pathname or path namestring of the file into which to save the data.

This function corresponds to the menu command File | Save Layout State.

load-layout

(defmethod load-layout ((pane graph-node-pane) file)

Loads a visual graph that was saved some time earlier with save-layout. The same store that was open when the save was done should be open when calling this function (or possibly another store that contains the same triples). Any triples in the saved state that are not found in the currently-open store will simply not be displayed.

True is returned if the load was successful, and otherwise nil is returned. A return value of nil may indicate that the file does not exist or that it is not really a gruff layout file.

pane is the graph-node-pane onto which to display the loaded visual graph.

file is the pathname or path namestring of the file from which to load the data.

This function corresponds to the menu command File | Load Layout State.

save-layout-as-pixmap

Creates a pixmap file containing an image of the currently-displayed visual graph. The pixmap will encompass all of the displayed nodes in the visual graph, even if they are scrolled out of view, adding a bit of margin around them all. 

(defun save-layout-as-pixmap (pane &key path show-saved-pixmap)

pane is the graph-node-pane that is displaying a visual graph.

path is the pathname or path namestring of the file into which to save the image. If nil or unsupplied, a dialog will ask for the path to which to save the image. The path should be of type png, jpg, or bmp, and an image in that format will be saved.

If show-saved-pixmap is true, then the saved pixmap will be displayed by another program. The other program will be either your default pixmap-viewing program or your preferred web browser, depending on the value of Global Options | Miscellaneous | Use Web Browser for All Documents.

This function corresponds to the menu command File | Save Layout as Pixmap.

uncache-for-modified-triple-store

Uncaches information as needed if the open store has been modified after displaying information from it in Gruff. 

(defun uncache-for-modified-triple-store (&key node-pane)

If you have opened a triple-store and displayed some of its nodes and links in a visual graph, and then you have modified the store (such as by adding additional triples), then you should call this function before calling any further Gruff functions. Otherwise Gruff may use out-of-date information about the nodes and links that are in the store.

This function does not remove any of the displayed information in the Gruff interface, and so you do not need to start over building a visual graph, for example. But if any currently-displayed triples have been removed from the store, then this function will not be sufficient, and uncache-for-new-triple-store should be called instead.

If node-pane is passed, it should be a graph-node-pane, and the uncaching will be more complete.

uncache-for-new-triple-store

Clears everything as needed to begin displaying a different triple-store in Gruff. 

(defun uncache-for-new-triple-store  
  (&key (node-pane (graph-node-pane (gruff-browser))))

Removes all nodes and links from the specified node pane, and clears information that has been cached about nodes and links in the current store. This is needed when creating or opening a different triple-store programmatically when the node pane is displaying objects from a previous store. This function is called automatically by the functions on the File menu of the standard browser, but otherwise needs to be called by an application that has created or opened a store in some other way after displaying information from another store.

If you have simply modified the store that's being browsed, without removing any of the currently-displayed triples, then you could instead call uncache-for-modified-triple-store to avoid clearing the currently-displayed information.

This function corresponds to the menu command File | Miscellaneous | Clear and Uncache Everything.

gruff-options-path

Returns the path of the file where your personal Gruff options are saved. 

(defun gruff-options-path ()

If the standard Gruff browser window is used by calling gruff-browser rather than by creating a custom instance of the graph-node-pane class, then Gruff will save personal preferences from the various options menus of the standard browser. The options will be saved whenever the Global Options | Save All Options command is used, and also when the browser is exited. The saved options will be loaded when the standard browser is restarted.

The expression (gruff-options-path) returns the path of the file where the option values are saved. This file could be deleted to revert all default options, including ones that are not reverted by Global Options | Revert to Default Options.

*selected-node*

A global variable whose value is the UPI of the most recently selected node in the graph view, or else nil if no node has been selected yet.

This is intended as a handy way to get a programmatic handle on a resource or literal that appears in the interface. A debugging expression using this variable could be evaluated in a lisp listener of a development lisp, for example, after selecting the desired node in the graph view.

*selected-link*

A global variable whose value is the UPI of the most recently selected link in the graph view, or else nil if no node has been selected yet.

If the selected link represents multiple predicates, then one of those predicates is chosen arbitrarily and its UPI is used.

*suppressing-gruff-messages*

A global variable that determines whether messages will appear in any ancestor window of a graph-node-pane that has a status bar at the bottom of the window. The value is nil by default, and Gruff binds it to t now and then.

An application could bind this variable to a non-nil value while executing certain code where the status bar messages would be cumbersome. Or it could set the value permanently to a non-nil value to totally suppress status bar messages.

*gruff-version*

A global variable whose value is a string indicating the current version of Gruff. This value is shown in the Help | About dialog.

Lisp Functions for Modifying User Options Programmatically

The standard interactive Gruff browser has several menus for modifying a variety of user options interactively. There are also functions for reading and writing the option values programmatically. Each option is an accessor function of the graph-node-pane class.

For example, the menu option Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing uses the accessor function min-node-to-node-spacing. Evaluating the form (min-node-to-node-spacing my-node-pane) will return the current value, while (setf (min-node-to-node-spacing my-node-pane) 10) would set the value to 10.

Here is a table of the various option menu commands and the accessor function that corresponds to each one. Refer to the documentation for each menu command for the meaning of the option. 

  View | Optional Graph View Panes | Show Legend - show-legend (boolean)  
  View | Optional Graph View Panes | Show Overview - show-overview (boolean)  
  Text Search | Text Search Timeout - text-search-timeout (integer)  
  Edit | Confirm Triple Deletion - confirm-triple-deletion (boolean)  
  Edit | Show Menus of Recent Namespaces - show-menus-of-recent-namespaces (boolean)  
  Edit | Percent-Decode Characters for Editing - percent-decode-characters-for-editing (boolean)  
  Edit | Percent-Encode Non-ASCII After Editing - percent-encode-non-ascii-after-editing (boolean)  
  Global Options | Status Bar Font - gruff-status-bar-font (font)  
  Global Options | Widget Font - gruff-widget-font (font)  
  Global Options | Node Label Predicates | Use Label Predicates for Node Labels - use-label-properties (boolean)  
  Global Options | Node Label Predicates | Custom Predicates for Node Labels - custom-predicates-for-labels-help (string)  
  Global Options | Node Label Predicates | Custom Predicates for Node Comments - custom-predicates-for-comments (string)  
  Global Options | Node Label Predicates | Custom Predicates for Node Pixmaps - custom-predicates-for-pixmaps (string)  
  Global Options | Derived Node and Link Labels | Exclude Namespaces from Labels - exclude-namespaces-from-labels (boolean)  
  Global Options | Derived Node and Link Labels | Add Spaces to Labels - add-spaces-to-labels (boolean)  
  Global Options | Derived Node and Link Labels | Collapse Contiguous Spaces in Labels - collapse-contiguous-spaces-in-labels (boolean)  
  Global Options | Derived Node and Link Labels | Capitalize First Word - capitalize-first-word (boolean)  
  Global Options | Derived Node and Link Labels | Convert Percent Encoding in Labels - convert-percent-hex-in-labels (boolean)  
  Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass" | display-subclassof-as-superclass (boolean)  
  Global Options | Maximum Menu Label Length | max-menu-item-string-length (integer)  
  Global Options | Show Full URIs in Pop-Up Menus | show-full-uris-in-pop-up-menus (boolean)  
  Global Options | Case-Sensitive Sorting for Menus | case-sensitive-sorting (boolean)  
  Global Options | Maximum Choices When Selecting a Subset | max-choices-when-selecting-a-subset (integer)  
  Global Options | General Triple-Fetching Limit - get-triples-list-limit (integer)  
  Global Options | Timeouts | Finding All Types Timeout - finding-all-types-timeout (integer)  
  Global Options | Timeouts | Finding All Predicates Timeout - finding-all-predicates-timeout (integer)  
  Global Options | SPARQL Endpoints | General Triple-Fetching Limit - get-triples-list-limit-with-endpoints (integer)  
  Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels - use-label-properties-with-endpoints (boolean)  
  Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color - use-most-specific-type-for-node-color-with-endpoints (boolean)  
  Global Options | Communications | Use Dedicated Sessions - use-session-ports (boolean)  
  Global Options | Communications | HTTP Proxy - gruff-http-proxy (list)  
  Global Options | Communications | Use any23.org for RDFa - use-any23-for-rdfa (boolean)  
  Global Options | Communications | Ignored RDFa Relationships - ignored-rdfa-relationships (list)  
  Global Options | Miscellaneous | Confirm Exit - confirm-exit (boolean)  
  Global Options | Miscellaneous | Treat Literals as Objects - treat-literals-as-objects (boolean)  
  Global Options | Miscellaneous | Preferred Language - label-property-language (string)  
  Global Options | Miscellaneous | Reasoner Enables Restriction Reasoning - reasoner-enables-restriction-reasoning (boolean)  
  Global Options | Miscellaneous | Auto Font Switching on Text Entry - auto-font-switching-on-text-entry (boolean)  
  Global Options | Miscellaneous | Use Web Browser for All Documents - use-web-browser-for-all-documents (boolean)  
  Global Options | Miscellaneous | Document Base Folder - document-base-folder (string)  
  Query Options | Query Text Font - query-string-font (font)  
  Query Options | Query Timeout - query-timeout (integer)  
  Query Options | Displayed Results Limit - query-results-limit (integer)  
  Query Options | Include More Triples in Visual Graphs - include-more-triples-in-visual-graphs (boolean)  
  Query Options | Percent-Encode Non-ASCII in Queries - percent-encode-non-ascii-in-queries (boolean)  
  Query Options | Query Logging Enabled - query-logging-enabled (boolean)  
  Query Options | Query Logging File - query-logging-file (file)  
  Query Options | New Log File for Each Session - new-log-file-for-each-session (boolean)  
  Query Options | Query Text Report Show Full URIs - query-text-report-show-full-uris (boolean)  
  Query Options | Query Text Report One Line per Value - query-text-report-one-line-per-value (boolean)  
  Table Options | Table Property Name Font - table-property-name-font (font)  
  Table Options | Table Property Value Font - table-property-value-font (font)  
  Table Options | Show Full URIs in Tables - show-full-uris-in-tables (boolean)  
  Table Options | Show Multiple Property Values - show-multiple-property-values  
  Table Options | Show Multiple Text Lines - fit-row-height-to-text (boolean)  
  Table Options | Display Literals of All Languages - display-literals-of-all-languages-in-tables (boolean)  
  Table Options | Maximum Triples Per Predicate in Table - max-triples-per-predicate (integer)  
  Table Options | Maximum Text Length in Table - max-string-length-in-table (integer)  
  Table Options | Table Color One - table-color-one (color)  
  Table Options | Table Color Two - table-color-two (color)  
  Table Options | Table Cell Vertical Padding - table-cell-vertical-padding (integer)  
  Outline Options | Outline Font - outline-node-font (font)  
  Outline Options | Show Full URIs in Outline - show-full-uris-in-outlines (boolean)  
  Outline Options | Create All Nodes as Blank Nodes | create-all-outline-nodes-as-blank-nodes (boolean)  
  Visual Graph Options | Node Labels | Node Label Font - node-font (font)  
  Visual Graph Options | Node Labels | Show Full URIs on Nodes - show-full-uris-on-nodes (boolean)  
  Visual Graph Options | Node Labels | Maximum Node Label Length - max-node-label-length (integer)  
  Visual Graph Options | Node Labels | Enforce Maximum Node Label Length - enforce-max-node-label-length (boolean)  
  Visual Graph Options | Node Labels | Absolute Maximum Node Label Length - absolute-max-node-label-length (integer)  
  Visual Graph Options | Link Labels | Draw Link Labels - draw-link-labels (boolean)  
  Visual Graph Options | Link Labels | Draw Graph Link Labels Horizontally - draw-link-labels-horizontally (boolean)  
  Visual Graph Options | Link Labels | Draw Query Link Labels Horizontally - draw-query-link-labels-horizontally (boolean)  
  Visual Graph Options | Link Labels | Use Line Color for Link Labels - use-line-color-for-link-labels (boolen)  
  Visual Graph Options | Link Labels | Link Label Color - link-label-color (color)  
  Visual Graph Options | Link Labels | Link Label Font - link-label-font (font)  
  Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse - draw-link-labels-for-node-under-mouse (boolean)  
  Visual Graph Options | Link Labels | Link Label Box Color - link-label-box-color (color)  
  Visual Graph Options | Layout Options | Do Automatic Incremental Layouts - do-automatic-incremental-layouts (boolean)  
  Visual Graph Options | Layout Options | Animate Layouts - animate-layouts (boolean)  
  Visual Graph Options | Layout Options | Maximum Nodes for Animation - max-nodes-for-animated-layout (integer)  
  Visual Graph Options | Layout Options | Maximum Iterations for Full Layout - max-iterations-for-full-layout (integer)  
  Visual Graph Options | Layout Options | Maximum Iterations for Incremental Layout - max-iterations-for-incremental-layout (integer)  
  Visual Graph Options | Layout Options | Center After Full Layout - center-after-full-layout (boolean)  
  Visual Graph Options | Layout Options | Center After Incremental Layout - center-after-incremental-layout (boolean)  
  Visual Graph Options | Layout Options | Compress After Full Layout - compress-after-full-layout (boolean)  
  Visual Graph Options | Layout Options | Compress After Incremental Layout - compress-after-incremental-layout (boolean)  
  Visual Graph Options | Layout Options | Honor Layout Direction Constraints - honor-layout-direction-constraints (boolean)  
  Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate - directional-predicates (alist)  
  Visual Graph Options | Layout Options | Clear Layout Direction for a Predicate - directional-predicates (alist)  
  Visual Graph Options | Layout Options | Canvas Resize Factor - canvas-resize-factor (real)  
  Visual Graph Options | Layout Options | Drag Scroll Zoom Factor - drag-scroll-zoom-factor (real)  
  Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout - min-nodes-for-spring-layout (integer)  
  Visual Graph Options | Spring Layout Options | Spacing Factor - spring-layout-spacing-factor (integer)  
  Visual Graph Options | Spring Layout Options | Velocity Divisor - spring-layout-velocity-divisor (integer)  
  Visual Graph Options | Spring Layout Options | Slowdown Exponent - spring-layout-slowdown-exponent (integer)  
  Visual Graph Options | Spring Layout Options | Keep Nodes on Canvas - spring-layout-keep-nodes-on-canvas (boolean)  
  Visual Graph Options | Constraint-Based Layout Options | Begin Full Layout at Random Positions | begin-with-nodes-at-random-positions (boolean)  
  Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal - remove-orphans-on-node-removal (boolean)  
  Visual Graph Options | Inclusion Options | Number of Total Links for Warning - number-of-links-for-warning-2 (integer)  
  Visual Graph Options | Inclusion Options | Number of Total Links for Abort - number-of-links-for-abort-2 (integer)  
  Visual Graph Options | Inclusion Options | Number of Links from One Node for Warning - number-of-radial-links-for-warning-2 (integer)  
  Visual Graph Options | Inclusion Options | Show 1 Level of Nodes on Display Only Linked Nodes - levels-to-add-on-display-linked-nodes (integer)  
  Visual Graph Options | Inclusion Options | Show 2 Levels of Nodes on Display Only Linked Nodes - levels-to-add-on-display-linked-nodes (integer)  
  Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display - max-triples-for-display-all-triples-2 (integer)  
  Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length - max-path-length-for-add-paths (integer)  
  Visual Graph Options | Finding Paths Between Nodes | Find Only Shortest Paths - find-only-shortest-paths (boolean)  
  Visual Graph Options | Finding Paths Between Nodes | Path-Finding Timeout - path-finding-timeout (integer)  
  Visual Graph Options | Finding Paths Between Nodes | Number of Found Paths for Warning - number-of-found-paths-for-warning (integer)  
  Visual Graph Options | Finding Paths Between Nodes | Maximum Paths to Display - max-paths-to-display (integer)  
  Visual Graph Options | Finding Paths Between Nodes | Find Paths on Server - find-remote-paths-on-server (boolean)  
  Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Left and Right - path-end-node-placement (symbol)  
  Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Top and Bottom - path-end-node-placement (symbol)  
  Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes Anywhere - path-end-node-placement (symbol)  
  Visual Graph Options | Finding Paths Between Nodes | Path End Node Margin - path-end-node-margin (integer)  
  Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing - min-node-to-node-spacing (integer)  
  Visual Graph Options | Node and Link Spacing | Minimum Link-to-Node Spacing - min-link-to-node-spacing (integer)  
  Visual Graph Options | Node and Link Spacing | Node Label Margin - label-margin (integer)  
  Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy - max-links-per-node-copy (integer)  
  Visual Graph Options | Node and Link Spacing | Spacing Increment for Many Links - spacing-increment-for-many-links (integer)  
  Visual Graph Options | Node and Link Spacing | Add Spacing for Long Paths - add-spacing-for-long-paths (boolean)  
  Visual Graph Options | Node and Link Spacing | Long Path Spacing Increment - long-path-spacing-increment (integer)  
  Visual Graph Options | Node and Link Spacing | Long Path Maximum Spacing - long-path-max-spacing (integer)  
  Visual Graph Options | Node and Link Spacing | Limit Outward Stretching - limit-outward-stretching (boolean)  
  Visual Graph Options | Node and Link Spacing | Link Line Mousing Margin - link-line-mousing-margin (integer)  
  Visual Graph Options | Node and Link Flashing | Flash Legend Matches - flash-legend-matches (boolean)  
  Visual Graph Options | Node and Link Flashing | Flash End Nodes of Found Paths - flash-end-nodes-of-found-paths (boolean)  
  Visual Graph Options | Node and Link Flashing | Flash Newly Added Nodes - flash-newly-added-nodes (boolean)  
  Visual Graph Options | Node and Link Flashing | Flash Selected Search Matches - flash-selected-search-matches (booelan)  
  Visual Graph Options | Node and Link Flashing | Times to Flash - times-to-flash (integer or nil)  
  Visual Graph Options | Node and Link Flashing | Flashing Time Interval - flashing-interval (integer)  
  Visual Graph Options | Node and Link Flashing | Flashing Node Color Delta - flashing-node-color-difference (integer)  
  Visual Graph Options | Tooltips | Show Node Tooltips - show-node-tooltips (boolean)  
  Visual Graph Options | Tooltips | Show Link Tooltips - show-link-tooltips (boolean)  
  Visual Graph Options | Tooltips | Tooltip Font - node-and-link-tooltip-font (font)  
  Visual Graph Options | Tooltips | Tooltip Background Color - node-and-link-tooltip-background-color (color)  
  Visual Graph Options | Tooltips | Node Tooltips Delay - node-tooltip-delay (integer)  
  Visual Graph Options | Tooltips | Link Tooltips Delay - link-tooltip-delay (integer)  
  Visual Graph Options | Antialiasing | Antialias Lines - antialias-lines (boolen)  
  Visual Graph Options | Antialiasing | Antialias Text - antialias-text (boolen)  
  Visual Graph Options | Antialiasing | Suppress Antialiasing During Animation - suppress-antialiasing-during-animation (boolen)  
  Visual Graph Options | Arrowheads | Arrowhead Length - default-arrowhead-length (integer)  
  Visual Graph Options | Arrowheads | Arrowhead Width - default-arrowhead-width (integer)  
  Visual Graph Options | Color Gradients | Show Node Color Gradients - show-node-color-gradients (boolean)  
  Visual Graph Options | Color Gradients | Color Gradient Intensity - color-gradient-intensity (integer)  
  Visual Graph Options | Color Gradients | Suppress Color Gradients During Animation - suppress-color-gradients-during-animation (boolean)  
  Visual Graph Options | Color Nodes for Node Type - node-color-scheme (symbol)  
  Visual Graph Options | Color Nodes for Unseen Links - node-color-scheme (symbol)  
  Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color - use-most-specific-type-for-node-color (boolean)  
  Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type - node-colors-for-types (alist)  
  Visual Graph Options | Node and Link Color for Types | Remove Color Mapping for Selected Node's Type - node-colors-for-types (alist)  
  Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate - line-styles-for-predicates (alist)  
  Visual Graph Options | Node and Link Color for Types | Specify Line Width for Selected Link's Predicate - line-styles-for-predicates (alist)  
  Visual Graph Options | Node and Link Color for Types | Specify Dashing for Selected Link's Predicate - line-styles-for-predicates (alist)  
  Visual Graph Options | Node and Link Color for Types | Suppress Link Link Styles - suppress-link-line-styles (boolean)  
  Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Current Links - node-color-for-unseen-current-links (color)  
  Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Non-Current Links - node-color-for-unseen-noncurrent-links (color)  
  Visual Graph Options | Node Color for Unseen Links | Node Color for No Unseen Links - node-color-for-no-unseen-links (color)  
  Visual Graph Options | Window Background | Graph View Background Color - color-for-window-background (color)  
  Visual Graph Options | Window Background | Legend Background Color - color-for-legend-background (color)  
  Visual Graph Options | Window Background | Background Pixmap - background-pixmap-source (file)  
  Visual Graph Options | Window Background | Show Background Pixmap (if any) - show-background-pixmap (boolean)  
  Visual Graph Options | Window Background | Stretch Background Pixmap - stretch-background-pixmap (boolean)  
  Visual Graph Options | Window Background | Graphical Query View Background Color - color-for-graphical-query-background (color)  
  Visual Graph Options | Node Border Color - node-border-color (color)  
  Help | Use Web Browser for Menu Help - use-web-browser-for-menu-help (boolean)  
  Help | Show Warnings in Dialogs - show-warnings-in-dialog (boolean)  
  Help | Show Quick Start on Startup - show-quick-start-on-startup (boolean)

Data formats of the option accessor functions

The name of each option accessor function above is followed by a type designator in parentheses. The boolean, integer, and real types correspond to those lisp types. (For the boolean type, nil means no or off, while any other value means yes or on.) Here are the data formats for the other type designators:

A color value is a list of three integers between 0 and 255 inclusive, for the red, green, and blue components of the color, such as (0 214 255).

A font value is a list of four values for font family, font face, font size, and font style. These correspond to the values passed to the Common Graphics function make-font-ex. The family is rather obscure and generally can be nil. The face should be a string such as "Arial" or "Courier New". The font size should be an integer for the height of the font in pixels. The style is a list of style flag keywords such as (:bold :italic) for a font that is both bold and italic; use nil for the standard style.

A file value is a string that names the complete path of a file.

The label-property-language string should be a two-character string such as "en" for English or "ja" for Japanese.

The directional-predicates list should be an association list that maps URIs to the four keyword symbols :upward, :downward, :leftward, and :rightward, and where each element is a proper list of two values, such as this: 

  (("http://www.w3.org/2000/01/rdf-schema#subClassOf" :upward)  
   ("PointsTo" :leftward))

The custom-property-for-node-labels string should be a list of predicate URIs. (This option initially allowed only a single property, and the original function name has been retained for backward compatibility.)

The node-color-scheme symbol should be either :node-type or :unseen-links. See the menu commands for details.

The path-end-node-placement symbol should be either :left-and-right, :top-and-bottom, or nil for no pinning.

The node-colors-for-types list should be an alist mapping URIs for types to color lists, such as this: 

  (("http://dbpedia.org/class/yago/Actor109765278" (251 244 123))  
   ("http://dbpedia.org/class/yago/Film106613686" (187 214 252)))

The line-styles-for-predicates list should an alist mapping URIs for predicates to lists of dashing style, line color, and line width, where line-dashing may be one of :solid, :dot, :dash, :dash-dot, :long-dash, and :dash-double-dot, and where line width is an integer, such as this: 

  (("http://dbpedia.org/property/director" (:solid (183 5 250) 2))  
   ("http://dbpedia.org/property/starring" (:solid (249 162 66) 2)))

The HTTP Interface to Gruff

Gruff supplies an HTTP interface that allows applications that are written in any language to invoke many of Gruff's commands externally. Gruff's HTTP server must first be started up by using the Gruff menu bar command Global Options | Communications | Start HTTP Server, or by starting Gruff with the corresponding command line argument that's described with that menu command. Thereafter any application can control Gruff by sending the HTTP requests that are described here to the host machine on which Gruff is running, sending the commands to the port that was specified when starting up Gruff's HTTP server.

The file embedding.html in the main Gruff directory is a demo of this programmatic interface. It also demonstrates embedding Gruff in an HTML/Javascript application, and shows the needed syntax for sending the commands from JavaScript. See Embedding Gruff In a Web Page.

HTTP requests should use either the GET method or the POST method of the HTTP protocol. When using the GET method, you pass the arguments as part of the URI, where a command name is followed by a question mark and then a number of arguments that are separated by ampersands, and each argument is an argument name followed by an equals character followed by an argument value. For example, if Gruff is running on a machine named hazel and has started an HTTP server on port 8008, then the following request would invoke Gruff's lay-out-triples HTTP command to display a visual graph of three triples that have the specified triple IDs: 

http://hazel:8008/lay-out-triples?triple-ids=107537-166633-166645

While that string is a valid URI as is, in general any argument value in the query portion of the URI string needs to be percent-encoded (also called URI-encoded) so that special characters are not interpreted as URI syntax characters. Percent-encoding replaces each character that may have a special meaning in a URI with a percent sign followed by two hexadecimal digits for the ASCII value of the character. Typically you would use a percent-encoding function that's in a library of HTTP utilities for the language that you are using.

If a request is too long to send all of the arguments as part of the URI string, then you can alternately send the request using the POST method. The arguments should then be sent as the body of the HTTP request and not as part of the URI. The body text should be in the same format as query text, though, with arguments separated by ampersands and an equals character joining each argument name to its argument value. Each argument value should still be percent-encoded, as with the GET method.

An action command will always return a status string that indicates success or some type of failure, while a request for information will return the answer string directly unless there is a failure, in which case it will return a status string similar to those returned by action commands. The status string for a successul action command will always begin with the characters "success - ". If an action command or information request is specified incorrectly, then a status string beginning with "error - " will be returned. And if a command is specified correctly but Gruff fails to do what was requested (for example due to not finding a specified node or predicate in the store), then a status string beginning with "failure - " will be returned.

Here are the HTTP commands that have been implemented.

open-store (HTTP command)

Opens a triple-store, as with the interactive command File | Open Triple-Store.

The arguments are store-name (required), access-mode (either local or remote, defaulting to remote), write-mode (either read-only or read-write, defaulting to read-only), host, port, catalog (defaulting to Root), user, and password.

If access-mode is remote, then host and port are required, as are user and password.

Before using this command, you could first use the store-info command to see if the desired store is already open, and in the desired manner. (If it is, this command would reopen it anyway.)

Here's an example of opening a remote store named actors on a machine named peep that's running the AllegroGraph server on port 10088, where Gruff is running on a machine named hazel and has started its HTTP server on port 8008: 

http://hazel:8008/open-store?store-name=actors&host=peep&port=10088&access-mode=remote&user=tester&password=nopeeking

A federated store can be created by specifying the store-name argument as a list of store names that are separated by commas (with no spaces) and then percent-encoded, such as "actors,cyc" (before percent-encoding). This requires that all of the stores to federate live in the same catalog.

A more general way to federate stores and/or apply reasoning is to use a specification argument instead of store-name and catalog arguments. Here are a few examples of the mini-language that can be used for the specification argument. These values must first be percent-encoded, though, before passing them as the value of the specification argument of the open-store command.

Using access-mode=remote is better for federations, because then the federation is done on the server (rather than on the client), which is more efficient and allows queries to be done on the federation.

Here is a specification argument value to federate two stores named one and two, which both live in the root catalog: 

<one>+<two>

Open the store named three in the catalog named test, and apply rdfs++ reasoning: 

<test:three>[rdfs++]

Federate all three of the above stores, and apply restriction reasoning to the federation: 

<one>+<two>+<test:three>[restriction]

Here is how that last specification argument would appear in an open-store command after percent-encoding the argument value as needed: 

&specification=%3Cone%3E%2B%3Ctwo%3E%2B%3Ctest%3Athree%3E%5Brestriction%5D

If you are starting up Gruff programmatically by running the Gruff executable in some programmatic way, then an alternate way to open a store programmatically is to pass command line arguments for a store to open when Gruff starts up. See Opening a Store with Command Line Arguments.

connect-to-endpoint (HTTP command)

Connects to a SPARQL endpoint, as with the interactive command File | Connect to SPARQL Endpoint.

The only required argument is endpoint-url, which should be the complete URL of the endpoint. Optional arguments are user and password, which are needed for private endpoints, plus endpoints-password for the general password that allows the use of SPARQL endpoints in Gruff.

Here's an example of connecting to the dbpedia SPARQL endpoint, where Gruff is running on a machine named hazel and has started its HTTP server on port 8008: 

http://hazel:8008/connect-to-endpoint?endpoint-url=http://live.dbpedia.org/sparql

That command won't actually work as written above, because the endpoint-url argument must first be percent-encoded so that its non-alphanumeric characters will not be interpreted as HTML syntax characters in the URI that it's inside. After percent-encoding that argument, the actual URI to send will look like this: 

http://hazel:8008/connect-to-endpoint?endpoint-url=http%3A%2F%2Flive.dbpedia.org%2Fsparql

-------------------------------------------------------------------------------

store-info (HTTP command)

Returns a specified attribute of the store that Gruff currently has open, if any, and otherwise returns the empty string. The only argument is attribute (required), which indicates which store attribute is being requested.

The valid values of the attribute argument are type, store-name, access-mode, write-mode, host, port, and catalog. This command can be used to determine whether the store that you want to use is already open. The type value will be ag-store for an AllegroGraph store, endpoint for a SPARQL endpoint, or the empty string if neither of those is open. 

http://hazel:8008/store-info?attribute=store-name

query (HTTP command)

Performs a SPARQL or Prolog query in Gruff, and optionally also lays out a visual graph from the results. The required arguments are language, which may be either sparql or prolog, and either a query-string argument or a query-file argument. Optional arguments are layout, keep-old-nodes, and allow-dialogs, which may be either yes or no, defaulting to no.

A query-string argument should be the percent-encoded text of a query. Alternately a query-file argument should be the path of a file on the server machine that contains only the text of a query. A query-file path can be relative to the Gruff directory, so if the file is in the Gruff directory then the value could be just the file name and type, such as query-one.txt.

If layout is yes, then after the query is done in the query view, a visual graph will be constructed in the graph view that consists of all triples whose subject, predicate, and object are all in the query results or the query text itself. (This is like pressing the Create Visual Graph button in the query view; see Generating Visual Graphs from Query Results.) If keep-old-nodes is yes, then the nodes and links that already existed in the graph view will remain there as the new content is added to it, and otherwise the graph view will first be cleared.

If allow-dialogs is yes, then any dialog windows that might appear to ask the user for further guidance will appear. Otherwise default behavior will be done instead, to allow Gruff to be controlled only by the HTTP interface with no interactive user. For example, a dialog may notify the user that there are many results, allowing the user to either display all of them, or to select a subset, or to cancel; when dialogs are not allowed, all of the results will be displayed.

A requested layout will not be done if the number of distinct nodes in the query results is greater than or equal to Visual Graph Options | Inclusion Options | Number of Total Links for Warning. (It doesn't know how many actual links would be in the graph at that point.) This limit could be changed with the option HTTP command, using the programmatic option name number-of-links-for-warning.

Here is an example of an HTTP query command string as it could exist BEFORE you percent-encode the query text argument for transmission by HTTP: 

http://hazel:8008/query?language=sparql&layout=yes&query-string=select ?a ?b ?c ?x where {  
    ?a ?x <http://dbpedia.org/resource/Jessica_Alba> .  
    ?a ?x ?b .  
    ?c ?x ?b .  
    ?c ?x <http://dbpedia.org/resource/Brad_Pitt> . }

And here is the actual percent-encoded string to transmit: 

http://hazel:8008/query?language=sparql&layout=yes&query-string=select%20%3Fa%20%3Fb%20%3Fc%20%3Fx%20where%20%7B%0A%20%20%3Fa%20%3Fx%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJessica_Alba%3E%20.%0A%20%20%3Fa%20%3Fx%20%3Fb%20.%0A%20%20%3Fc%20%3Fx%20%3Fb%20.%0A%20%20%3Fc%20%3Fx%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FBrad_Pitt%3E%20.%0A%20%20%7D

lay-out-triples (HTTP command)

Creates and lays out a visual graph from an arbitrary set of triples that you specify by their triple IDs or by their URIs and literal strings.

The only required argument is either triple-ids or ntriples. If triple-ids is passed, its value should be a set of triple ID integers that are separated by dashes. If ntriples is passed, its value should be a percent-encoded ntriples string (such as by taking the full contents of an ntriples file and then percent-encoding it). You may need to use the ntriples option if you don't have a way to find the triple IDs, which are internal to AllegroGraph.

An optional argument is keep-old-nodes, which can be either yes or no, defaulting to no. If keep-old-nodes is yes, then the triples that were already displayed in the graph view are retained while the specified triples are added to the visual graph. If keep-old-nodes is no, then the graph view is first cleared of all triples before displaying the new ones.

When passing the ntriples argument (rather than the triple-ids argument), the value will likely be too long for a GET request, in which case you should use a POST request instead, with the entire query portion of the request in the body of the request rather than after a question mark in the URI itself.

The first example here uses triple IDs. 

http://hazel:8008/lay-out-triples?keep-old-nodes=yes&triple-ids=107537-166633-166645

Here's an example that uses the ntriples alternative, BEFORE percent-encoding the ntriples argument as needed. It specifies just three triples to lay out: 

http://hazel:8008/lay-out-triples?ntriples=<http://dbpedia.org/resource/Hand_of_Death> <http://dbpedia.org/property/starring> <http://dbpedia.org/resource/Jackie_Chan> .  
<http://dbpedia.org/resource/Jackie_Chan> <http://www.w3.org/2000/01/rdf-schema#label> "Jackie Chan"@en .  
<http://dbpedia.org/resource/Dragon_Fist> <http://dbpedia.org/property/starring> <http://dbpedia.org/resource/Jackie_Chan> .

And here is that same example as you actually need to pass it, with the ntriples argument percent-encoded: 

http://hazel:8008/lay-out-triples?ntriples=%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FHand_of_Death%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan%3E%20.%0A%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan%3E%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label%3E%20%22Jackie%20Chan%22%40en%20.%0A%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FDragon_Fist%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan%3E%20.

display-all-triples (HTTP command)

Displays all triples of the store up to Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display, as with the interactive command Display | Display Some Sample Triples.

There are no required arguments. If the optional limit argument is passed, it should be a positive integer, in which case the option for the maximum number of triples to display will first be set, and then the command to display up to that many triples will be performed. 

http://hazel:8008/display-all-triples?limit=300

update-layout (HTTP command)

Updates the layout of the nodes and links that are currently displayed in the graph view, as with the interactive commands Layout | Update Layout Incrementally and Layout | Redo Layout from Scratch.

There are no required arguments. If the optional redo argument is yes, then the layout will be reworked from scratch. Otherwise the layout will be updated incrementally only as needed, starting from the current node positions. 

http://hazel:8008/update-layout?redo=yes

number-of-nodes (HTTP command)

Returns the number of nodes that are currently displayed in the graph view. Values from 0 to one less than this number could then be passed as the index argument to the node-at-index command. 

http://hazel:8008/number-of-nodes

node-at-index (HTTP command)

Returns the URI or literal string of a node that's currently displayed in the graph view. The only argument is index, which is required. The index should be between 0 and one less than the value that's returned by the number-of-nodes command, inclusive. You can find the values of all of the displayed nodes by sending this command repeatedly, once for each index in the range. A returned string could then be passed as the value of the node argument to various other HTTP commands.

The returned string will be in ntriples format, meaning that a URI will contain embedded surrounding angle brackets, and a literal will contain embedded surrounding double-quote characters. 

http://hazel:8008/node-at-index?index=3

node-position (HTTP command)

Returns the position and size of a node in the graph view, or moves the node to a specified position.

The only required argument is node, which should be the URI or literal string of the node. If the x and y arguments are not passed (and it is an error pass one of those but not the other), then the returned status string will consist of four integers separated by spaces, where the numbers are the x and y coordinates of the center of the node, followed by the width and height of the node, for example "940 378 80 36". If the x and y arguments are passed, they should be integers that specify where to move the node.

The x, y, width, and height values are all measured in pixels. The x value is the distance rightward from the left edge of the scrolling canvas to the horizontal center of the node, and y is the distance downward from the top edge of the scrolling canvas to the vertical center of the node.

Here is how a command to move a node would look if you didn't need to percent-encode the node argument value: 

http://hazel:8008/node-position?node=http://dbpedia.org/resource/Jackie_Chan&x=1400&y=800

And here is how you must actually pass it, with the node argument percent-encoded: 

http://hazel:8008/node-position?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan&x=1400&y=800

select-node (HTTP command)

Selects a specified node in the graph view, or deselects any selected node. There are no required arguments. If the optional node argument is passed, then that node is selected if it is found in the graph view. If no node argument is passed, then the selected node is deselected if there is one, as with the interactive command Select | Deselect the Selected Node and/or Link.

Whenever a layout is done, the selected node will remain pinned. To allow all nodes to move during a layout, first deselect any selected node and unpin all nodes.

When passing a node argument, it may be either a URI of a resource or else a literal string. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

Here is an example before percent-encoding the node argument as needed: 

http://hazel:8008/select-node?node=http://dbpedia.org/resource/Jackie_Chan

And here is that example as you actually need to pass it, with the node argument percent-encoded: 

http://hazel:8008/select-node?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan

selected-node (HTTP command)

Returns the IRI or literal string of the node that's currently selected in the graph view, followed by the label string that Gruff is displaying for the node. If no node is currently selected, then the empty string is returned. There are no arguments.

Only a single string can be returned from an HTTP command, so your code will need to parse the two logical strings apart. The two values will be separated by a space. The first value will be the "long" ntriples-format string for the node, which for a resource will be an IRI (which cannot contain spaces) and for a literal will be a string that contains embedded double-quote characters, such as "one two three"@en. (If the value is an IRI, the angle brackets are removed from the "long" ntriples-format string.)

Therefore, the general rule for parsing apart the two returned values is this: If the string begins with a double-quote character, then divide it at the first space character after the second double-quote character, and otherwise divide it at the first space character.

In this case, the example is the only way that this command can be specified: 

http://hazel:8008/selected-node

pin (HTTP command)

Pins or unpins a single node or all nodes in the graph view, so that they don't move during layouts while pinned, as with the interactive commands Select | Toggle Pinning of the Selected Node and Select | Remove All Node Pinning.

There are no required arguments. If a node argument is passed, then that single node will be pinned or unpinned, and otherwise all nodes that are currently displayed in the graph view will be pinned or unpinned. If the direction argument is passed as "off", then the node or nodes will be unpinned, and otherwise they will be pinned.

When passing a node argument, it may be either a URI of a resource or else a literal string. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

This example would pin Jackie Chan, after percent-encoding the node argument: 

http://hazel:8008/pin?node=http://dbpedia.org/resource/Jackie_Chan

This example would unpin all nodes: 

http://hazel:8008/pin?direction=off

highlight (HTTP command)

Highlights or unhighlights a single node or all nodes in the graph view so that they can more easily be spotted, especially when the layout changes. A highlighted node is drawn with a thick blue border. This corresponds to the interactive commands Select | Toggle Highlighting of the Selected Node or Link and Select | Remove All Node and Link Highlighting.

There are no required arguments. If a node argument is passed, then that single node will be highlighted or unhighlighted, and otherwise all nodes that are currently displayed in the graph view will be highlighted or unhighlighted. If the direction argument is passed as "off", then the node or nodes will be unhighlighted, and otherwise they will be highlighted.

When passing a node argument, it may be either a URI of a resource or else a literal string. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

This example would highlight Natalie Wood, after percent-encoding the node argument: 

http://hazel:8008/highlight?node=http://dbpedia.org/resource/Natalie_Wood

This example would unhighlight all nodes: 

http://hazel:8008/highlight?direction=off

display-node (HTTP command)

Displays a single node in the graph view, specified either by its URI or by its rdfs:label.

Either a uri argument or a label argument must be passed. If a uri argument is passed, then Display | Display a Node by URI or Literal command is run. Otherwise if a label argument is passed, then Display | Display a Node by Label is run.

If the optional keep-old-nodes argument is yes, then the new node will be added to the nodes and links that were already displayed. Otherwise all nodes and links will first be removed from the display.

remove (HTTP command)

Removes either a specified node, the selected node (if any), all orphan nodes, all leaf nodes, or all nodes from the graph view. Either a node argument or a set argument should be passed, but not both.

If the node argument is passed, it should be the percent-encoded URI or literal string of a node that is currently displayed in the graph view. If found, that node and its links will be removed from the displayed graph.

If the set argument is passed, it should be either selected, orphans, leaves, or all. The value selected will remove the selected node if any, as with Remove | Remove Selected Node; orphans will remove all orphan nodes, as with Remove | Remove All Orphan Nodes; leaves will remove all leaf nodes and all orphan nodes, as with Remove | Remove All Leaf Nodes; and all will clear all nodes and links from the displayed graph, as with Remove | Remove All Nodes. 

http://hazel:8008/remove?set=leaves  
 
http://hazel:8008/remove?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FNatasha_Henstridge

current-predicates (HTTP command)

Returns or sets the set of current predicates, which are used by various Gruff commands. This is like the interactive command Global Options | Select Current Predicates.

There are no required arguments. If the optional predicates argument is supplied, then the specified list of predicates will become the current predicates, and otherwise the set of current predicates will be returned.

When specifying a set of predicates, they should be in ntriples format, meaning that a URI will have embedded surrounding angle brackets, and a literal will have embedded surrounding double-quote characters. There should be a space character between successive predicates, and then the whole value of the predicates argument must be percent-encoded. When not specifying new predicates, the current predicates will be returned in that format as well.

Return the list of current predicates, as an ntriples string: 

http://hazel:8008/current-predicates

Set a couple of current predicates: 

http://hazel:8008/current-predicates?predicates=%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fdirector%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E

Here's the way that predicates argument value looked before percent-encoding it: 

<http://dbpedia.org/property/director> <http://dbpedia.org/property/starring>

display-linked-nodes (HTTP command)

Adds nodes and links to the graph view to display any nodes that are linked with the selected node by the current predicates. There should already be a set of current predicates and a selected node. This is like the interactive command Link | Display Linked Nodes for the Current Predicates.

There are no required arguments. If the optional keep-old-nodes argument is yes, then the new nodes and links will be added to the nodes and links that were already displayed. Otherwise all nodes and links will first be removed from the display.

The optional levels-to-add argument indicates the number of levels of surrounding nodes to add, where 1 means to add only nodes that are directly linked with the selected node, and 2 means to also add nodes that are linked with those nodes. If specified, the value should be a small positive integer. The default value is the value of the levels-to-add-on-add-linked-nodes user option when keep-old-nodes is yes, or levels-to-add-on-display-linked-nodes when keep-old-nodes is no.

If the optional allow-dialogs argument is yes, then any dialog windows that might appear to ask the user for further guidance will appear. Otherwise default behavior will be done instead, to allow Gruff to be controlled only by the HTTP interface with no interactive user. For example, a dialog may notify the user that there are many results, allowing the user to either display all of them, or to select a subset, or to cancel; when dialogs are not allowed, all of the results will be displayed. 

http://hazel:8008/display-linked-nodes?keep-old-nodes=yes

find-paths (HTTP command)

Finds paths that link two specified end nodes via a set of specified predicates, and lays out a visual graph of all of the nodes and links that are in the paths. This is like the interactive command Link | Display Paths Between Two Nodes.

The required arguments are node1 and node2, each of which should be the percent-encdoed URI or literal string of an end node to find paths between. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

An optional argument is predicates. If specified, it can be a set of predicate URIs, where the only paths that will be found are ones that use only those predicates. Otherwise it can be the string "current" to use the current predicates. If no predicates argument is passed, then paths are found using all predicates.

When the predicates argument is a list of predicates, it should be in ntriples format, with each predicate URI enclosed in angle brackets (to facilitate parsing the list), as in <http://dbpedia.org/property/starring>. There should be a space between successive predicates, and then the entire argument value must be percent-encoded.

Other optional arguments include keep-old-nodes, which may be yes or no to retain the nodes and links that are currently in the visual graph, or not (the default is no); max-path-length, which may be an integer specifying the maximum number of links that there may be in a path (the default is 4); and find-only-shortest-paths, which may be yes or no to indicate whether paths that are longer than others should be excluded (the default is yes).

If many predicates are passed, then the query text will likely be too long to pass in the URI itself after a question mark, using the GET method of the HTTP protocol (as shown in the example below). In that case you should pass the query text as the body of the request, using the POST method.

Here is a pseudo-example that shows how the request might look if you didn't need to percent-encode the argument values, and you were able to have newlines in the string. (This won't actually work.) 

http://hazel:8008/find-paths  
?node1=http://dbpedia.org/resource/Jack_Black  
&node2=http://dbpedia.org/resource/Paul_Newman  
&predicates=<http://dbpedia.org/property/starring> <http://dbpedia.org/property/director>  
&max-path-length=4&find-only-shortest-paths=yes&keep-old-nodes=no

And here is how that query must actually be passed, with percent-encoding. 

http://hazel:8008/find-paths?node1=http%3A%2F%2Fdbpedia.org%2Fresource%2FJack_Black&node2=http%3A%2F%2Fdbpedia.org%2Fresource%2FPaul_Newman&predicates=%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fdirector%3E&max-path-length=8&find-only-shortest-paths=yes&keep-old-nodes=no

Here is the predicates argument for using the current predicates: 

&predicates=current

option (HTTP command)

Returns or sets the value of one of the user options. Currently every option whose value is an integer, float, or boolean value is supported; other options could be added later if needed.

The only required argument is option, which should be one of the option command names listed below. If the value argument is also supplied, then the option will be set to that value, with the usual success/error/failure status string returned, and otherwise the current value of the option will be returned.

For a boolean option, the value argument should be yes to turn the option on, or no to turn it off (and that yes or no string will be returned when not changing the value). An integer option value should be a simple integer string like 123. A float option value can be an integer string or a decimal string like 123.4.

This first example would return the current path-finding timeout (as a number of seconds): 

http://hazel:8008/option?option=path-finding-timeout

This example would set the path-finding timeout to 12 seconds: 

http://hazel:8008/option?option=path-finding-timeout&value=12

And this would tell Gruff to start displaying link labels: 

http://hazel:8008/option?option=draw-link-labels&value=yes

To find which of the option names below is associated with a particular menu bar command title, see Lisp Functions for Modifying User Options Programmatically.

Boolean Option Names

  add-spaces-to-labels  
  add-spacing-for-long-paths  
  animate-layouts  
  antialias-lines  
  antialias-text  
  auto-font-switching-on-text-entry  
  begin-with-nodes-at-random-positions  
  capitalize-first-word  
  case-sensitive-sorting  
  center-after-full-layout  
  center-after-incremental-layout  
  collapse-contiguous-spaces-in-labels  
  compress-after-full-layout  
  compress-after-incremental-layout  
  confirm-exit  
  confirm-triple-deletion  
  convert-percent-hex-in-labels  
  create-all-outline-nodes-as-blank-nodes  
  csv-file-include-column-headers  
  csv-file-include-full-uris  
  display-literals-of-all-languages-in-tables  
  display-subclassof-as-superclass  
  do-automatic-incremental-layouts  
  draw-link-labels  
  draw-link-labels-for-node-under-mouse  
  draw-link-labels-horizontally  
  draw-query-link-labels-horizontally  
  enforce-max-node-label-length  
  exclude-namespaces-from-labels  
  find-only-shortest-paths  
  find-remote-paths-on-server  
  fit-row-height-to-text  
  flash-end-nodes-of-found-paths  
  flash-legend-matches  
  flash-newly-added-nodes  
  flash-selected-search-matches  
  honor-layout-direction-constraints  
  include-more-triples-in-visual-graphs  
  limit-outward-stretching  
  new-log-file-for-each-session  
  percent-decode-characters-for-editing  
  percent-encode-non-ascii-after-editing  
  percent-encode-non-ascii-in-queries  
  prompt-for-commit-on-exit  
  prompt-for-label-for-new-blank-node  
  query-logging-enabled  
  query-text-report-one-line-per-value  
  query-text-report-show-full-uris  
  reasoner-enables-restriction-reasoning  
  remove-orphans-on-node-removal  
  retain-pop-up-overview  
  show-background-pixmap  
  show-full-uris-in-outlines  
  show-full-uris-in-pop-up-menus  
  show-full-uris-in-tables  
  show-full-uris-on-nodes  
  show-legend  
  show-link-tooltips  
  show-menus-of-recent-namespaces  
  show-node-color-gradients  
  show-node-tooltips  
  show-overview  
  show-quick-start-on-startup  
  show-warnings-in-dialog  
  spring-layout-keep-nodes-on-canvas  
  stretch-background-pixmap  
  suppress-antialiasing-during-animation  
  suppress-color-gradients-during-animation  
  suppress-link-line-styles  
  use-label-properties  
  use-label-properties-in-tables  
  use-line-color-for-link-labels  
  use-query-planner  
  use-web-browser-for-all-documents  
  use-web-browser-for-menu-help

Integer Option Names

  color-gradient-intensity  
  default-arrowhead-length  
  default-arrowhead-width  
  finding-all-predicates-timeout  
  finding-all-types-timeout  
  flashing-interval  
  flashing-node-color-difference  
  get-triples-list-limit  
  label-margin  
  legend-width  
  link-line-mousing-margin  
  link-tooltip-delay  
  long-path-max-spacing  
  long-path-spacing-increment  
  max-choices-when-selecting-a-subset  
  max-iterations-for-full-layout  
  max-iterations-for-incremental-layout  
  max-links-per-node-copy  
  max-menu-item-string-length  
  max-node-label-length  
  max-nodes-for-animated-layout  
  max-path-length-for-add-paths  
  max-paths-to-display  
  max-triples-for-display-all-triples  
  max-triples-per-predicate  
  min-link-to-node-spacing  
  min-node-to-node-spacing  
  min-nodes-for-spring-layout  
  node-tooltip-delay  
  number-of-found-paths-for-warning  
  number-of-links-for-abort  
  number-of-links-for-warning  
  number-of-radial-links-for-warning  
  path-end-node-margin  
  path-finding-timeout  
  query-results-limit  
  query-timeout  
  spacing-increment-for-many-links  
  spring-layout-slowdown-exponent  
  spring-layout-spacing-factor  
  spring-layout-velocity-divisor  
  table-cell-vertical-padding  
  times-to-flash

Float Option Names

  animation-demo-delay  
  canvas-resize-factor  
  drag-scroll-zoom-factor

set-color-for-type (HTTP command)

Sets the color to use for the background of nodes in the graph view that are of a specified type. There are four required arguments, which are type-node, red, green, and blue.

The type-node argument should be the percent-encoded URI of a node in the store that serves as the type of other nodes (specifically, as the object of rdf:type triples).

The red, green, and blue arguments should each be an integer between 0 and 255 inclusive.

This HTTP command corresponds to the menu command Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type. 

http://hazel:8008/set-color-for-type?type-node=http%3A%2F%2Fdbpedia.org%2Fresource%2FEmmy_Award_winners&red=255&green=192&blue=0

set-line-style-for-predicate (HTTP command)

Sets the line style for drawing link lines in the graph view that represent a specified predicate. A required argument is predicate, which should be the percent-encoded URI of a predicate. You must also pass either the three arguments red, green, and blue, or one of the arguments width or dashing, or some combination of those three.

Red, green, and blue should each be an integer between 0 and 255 inclusive. Width should be a small positive integer for the pixel thickness of the link line. Dashing should be one of the words solid, dash, dot, dash-dot, or dash-double-dot. You can specify just one of those three attributes, or any two, or all three.

This HTTP command corresponds to the menu command Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate and the related two options for the line width and dashing style. 

http://hazel:8008/set-line-style-for-predicate?predicate=http%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring&red=200&green=70&blue=0&width=2&dashing=solid

set-direction-for-predicate (HTTP command)

Sets or removes the layout direction constraint for a specified predicate. A layout direction constraint causes any layout to attempt to point all link lines for the predicate in a particular direction, such as more upward than downward for subClassOf, to display a top-down hierarchy.

The two required arguments are predicate and direction. The predicate argument should be a percent-encoded URI string, without surrounding angle brackets. The direction argument should be either leftward, upward, rightward, downward, or off. When the direction is off, the layout direction constraint for the specified predicate, if any, will be removed. For the other direction values, the direction constraint for the predicate will be set to that direction.

This HTTP command corresponds to the menu bar command Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate.

Here is an example URI before percent-encoding the predicate argument as needed: 

http://hazel:8008/set-direction-for-predicate?predicate=http://www.w3.org/2000/01/rdf-schema#subClassOf&direction=upward

And here is the actual URI that you would need to use, with the predicate argument percent-encoded: 

http://hazel:8008/set-direction-for-predicate?predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23subClassOf&direction=upward

save-layout (HTTP command)

Saves the current state of the visual graph to a specified file, as with the interactive command File | Save Layout State, so that it can be loaded back in any time later. The only argument is file (required), which should be the percent-encoded path of a file to which the layout should be saved. 

http://hazel:8008/save-layout?file=c%3A%2Fgruff%2Fscary-movies.layout

load-layout (HTTP command)

Loads a visual graph that was saved earlier with File | Save Layout State, and displays it in the graph view, as with the interactive command File | Load Layout State. The only argument is file (required), which should be the percent-encoded path of a layout file.

This command could be used repeatedly to present a slideshow or animation of prepared layouts. 

http://hazel:8008/load-layout?file=c%3A%2Fgruff%2Fscary-movies.layout

save-layout-as-pixmap (HTTP command)

Saves the current state of the visual graph to a specified file as a pixmap, as with File | Save Layout as Pixmap, so that it could be viewed in other programs. A file argument is required, which should be the percent-encoded path of a file to which the image should be saved.

If the optional show argument is yes, then the saved pixmap will be displayed by another program. The other program will be either your default pixmap-viewing program or your preferred web browser, depending on the value of Global Options | Miscellaneous | Use Web Browser for All Documents. 

http://hazel:8008/save-layout-as-pixmap?file=c%3A%2Fgruff%2Fscary-movies.png&show=yes

set-canvas-size (HTTP command)

Sets the size of the scrolling canvas in the graph view. This corresponds roughly to the interactive commands Layout | Make Canvas Larger and Layout | Make Canvas Smaller.

The only arguments are x and y. When passed, they should be integers that measure the canvas in pixels. One or both of the arguments must be passed. If the canvas size is too small, then a layout is likely to fail, whereas if it much larger than needed then the layout may be spread out more than necessary.

If an argument is less than the size of the window in that direction, then the canvas size will still be as large as the window, and so passing zero for both arguments (for example) will still allow the graph to fill the window but not extend beyond it. 

http://hazel:8008/set-canvas-size?x=2000&y=3000

center-the-visual-graph (HTTP command)

Moves all nodes and links in the graph view to the center of the scrolling canvas, and then scrolls the window to the middle of the canvas, as with the interactive command Layout | Center the Graph. There are no arguments. 

http://hazel:8008/center-the-visual-graph

display-node-in-table (HTTP command)

Displays all of the triples of a specified node in Gruff's table view. The only argument is node (required), which should be the percent-encoded URI of a node that's in the currently open store. 

http://hazel:8008/display-node-in-table?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FNatalie_Wood

use-custom-title-bar-string (HTTP command)

Replaces the usual text in Gruff's title bar with custom text that may be more suitable to a web application that embeds Gruff. The only argument is string (required), which should be the text to display (with no newline characters in it). 

http://hazel:8008/use-custom-title-bar-string?string=Here%20Are%20Some%20Visualizations

The command-line argument --custom-title is an alternative that may be needed if there is no way for this HTTP command to show a custom title immediately when Gruff starts up.

Troubleshooting Common Problems

Opening a Store (Database) Fails with a Permission Error

If an error occurs when opening a store (which may result in an obscure error message), it may be because you are behind a firewall that is not allowing the use of the arbitrary session port that gets used, which is different than the port that you specify. You can either turn off Global Options | Communications | Use Dedicated Sessions or configure the AllegroGraph server and your firewall to allow the same range of ports. See A Note About Dedicated Session Ports and Firewalls.

Lots of Unknown Errors Happen in Various Gruff Commands

This usually means that Gruff is built on a version of the AllegroGraph lisp client that is incompatible with the version of the AllegroGraph server that is serving the particular triple-store that you are now browsing. Gruff's title bar will mention both versions when they are not the same, to indicate that this may be the problem. (Minor version differences are often compatible, but you can' count on that.) If this is the problem, then you would need to download a version of Gruff that's built for your version of the AllegroGraph server, or maybe update your AllegroGraph server to match a later version of Gruff.

Many Small Rectangles Appear Where Text Should Be (Mac Only)

This pertains only to running Gruff on an Apple Mac as a desktop GTK application, and not in the newer mode inside a web browser.

If you see many rectangles (empty boxes) where you expect to see text, then you probably need to install or re-install Xquartz. This problem can arise after upgrading the operating system, for example. Get the latest XQuartz version from xquartz.org and install it following the instructions there. Do this even if you have installed Xquartz before. If the problem persists, contact Franz Inc. at [email protected].

The Query View's Create Visual Graph Button Produces Little or No Output

This can happen if the body of the query in the WHERE clause uses variables that are not selected in the SELECT clause. Gruff then doesn't have enough information in the query results (along with the query itself) to find related triples to display. See Generating Visual Graphs from Query Results. It may also help to toggle on Query Options | Include More Triples in Visual Graphs.

Commits Seem to Be Happening Without Being Requested

Commits will be done internally when user queries are performed in the query view if you have turned on Query Options | Allow Other Work During a Query. See that option for the explanation.

Release Notes

Version 8.1.4

Fixed: In release 8.1.3, path-finding failed when the end nodes are blank nodes that were returned by SPARQL queries when the triple-store was opened in read-only mode.

Fixed: The keyboard shortcut for Select | Copy Highlighted to Graphical Query View failed when using WebView Gruff on a Mac.

Version 8.1.3

The new option Global Options | Miscellaneous | Preferred Language for This Store avoids needing to set the global option Global Options | Miscellaneous | Preferred Language for a triple-store that does not use the usual preferred language every time you open that triple-store.

The new option Global Options | Miscellaneous | Borrow from Related Languages causes Gruff to display node labels that are language literals for related languages when there are no language literals for that node in the Global Options | Miscellaneous | Preferred Language.

Fixed: Link | Display Linked Nodes from an Outline listed a predicate even when no linked nodes under it would get listed because they're all language literals that are not in the current Global Options | Miscellaneous | Preferred Language (when Visual Graph Options | Inclusion Options | Include Literals of All Languages is off). It also listed linked nodes that are already displayed, unlike the sibling command Link | Display a Linked Node from Menus. And predicate items in both of those commands mentioned the total number of linked nodes for those predicates, rather than the number of choices that would be shown for them because they're not already displayed and they're not other-language literals.

Fixed: File | Connect to Gruff Demo Server was failing due to specifying an http scheme, while that server now requires https.

Fixed: In remote (non-WebView) Gruff, certain operations could take a long time. This includes doing a user query that returns all of the predicates in the triple-store (when there are many), or finding all of the predicates to list when creating a text index. Apparently this could happen whenever a SPARQL query returns hundreds of different nodes and predicates that all get listed in Gruff.

Fixed: When View | Browse a Single Graph or Display | Display Triples of One Graph does not receive all of the named graphs in the store within Global Options | Timeouts | Finding All Graphs Timeout, it did not report the timeout and instead claimed that there are no named graphs in the store. And avoiding the timeout also required increasing Query Options | Query Timeout. Also, browsing another single graph required searching for all named graphs on the server again. And when there are many named graphs in the store, it could take a while to fetch the label properties (if any) of all of them.

Fixed: When Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse is enabled, node labels did not appear as tooltips when zoomed out. (That option should have disabled node tooltips only when zoomed in all the way, as intended.)

Version 8.1.2

Fixed: The graphical query view could generate a faulty SPARQL query by using a namespace abbreviation for an IRI that does not include the full namespace of the IRI.

Fixed: Doing a DESCRIBE query after turning on Query Options | Allow Other Work During a Query corrupted and crashed Gruff.

Fixed: The query view's history of query results did not append an additional entry when doing a query, then using File | Roll Back and Refresh after modifying the triple-store outside of Gruff, and then doing the same query when it then returns different results. This could also cause the "Create Visual Graph" button to display the results of the first query from before the rollback.

Fixed: Gruff could loop infinitely after loading a layout that was last saved before 2017.

Version 8.1.1

When you open a triple-store on a server whose version is different than the version of the lisp client that Gruff was built on, the dialog that warns you that unpredictable errors may result has a new button that you can press to instead connect to the AllegroGraph SPARQL endpoint for that triple-store. That avoids the version mismatch because the lisp client is not used at all, though the path-finding commands are not available at SPARQL endpoints. This does not require the usual permission to use Gruff with SPARQL endpoints.

Fixed: Various commands would break if a user that does not have write permission on a triple-store opens the store in read/write mode anyway. This was tricky to avoid when using Gruff from WebView, which either opens a store in read/write mode automatically or at least defaults the "Open Triple-Store" dialog to that mode.

Fixed: The commands Link | Display Paths Between Two Nodes and Edit | Create a Triple by Linking Nodes canceled themselves immediately if you invoke the command by clicking on the command in a pull-down menu, rather than by invoking the command with keyboard.

Fixed: When selecting a new folder from which to load queries or layouts, if you accidentally select a high-level directory that takes a long time to search for files, then there was no way to interrupt the search. Now you can interrupt it by pressing the Q key, as the status bar now mentions during the search.

Fixed: If you run Gruff in desktop mode without maximizing the window, then run in web browser mode, and then run in desktop mode again, then the window would initially be maximized, rather than remembering the non-maximized state from the previous desktop run.

Fixed: The examples in the graphical query view for the extended actors repo and dbpedia could come up initially partly scrolled out of view.

Fixed: On Linux, include the ACL SSL shared library that allows OpenSSL 3 to be used.

Version 8.1.0

When saving or loading a query, graphical query, or layout, special dialogs will now appear rather than the standard file selection dialog as before. Most of the new functionality is in the load dialog, which shows descriptive information about each file, and allows you to filter the list of choices in various ways to make it easier to locate the desired file. In particular, saved files will know which triple-store they work with, and only those will be listed by default. See The Dialog for Selecting Queries and Layouts to Load.

You can now add comment nodes in the graphical query view to explain what the whole query or particular sections of it are about. See the new command Graphical Query Background | Add a Comment Node.

The new option Visual Graph Options | Link Labels | Show Named Graphs on Link Labels will indicate the named graphs of triples in the graph view (if any), by adding the name of the graph to the link line label where the predicate is shown.

The file http-interface-demo.html in the Gruff installation folder has been renamed to embedding.html to correspond to recent enhancements to that example. The setup instructions that it displays have been improved and expanded. See Embedding Gruff In a Web Page.

Fixed: The Query Options menu in the query view and the graphical query view was not showing the usual check marks beside the boolean options that are currently enabled, and the brackets that show other current option values were empty.

Fixed: When creating triples in Gruff in certain ways, the strings for new nodes could fail to be interned in the triple-store's string dictionary, leading to breaks. Also, creating a triple with a new predicate did not cause the new predicate to be listed immediately in the menu of all predicates.

Fixed: When turning on Help | Activity Logging, canceling the dialog that appears still turned activity logging on.

The new HTTP command display-node (HTTP command) allows displaying a single node with a remote call to Gruff, specifying the node either by its URI or by its label. This simple command appeared to be missing from The HTTP Interface to Gruff.

Version 8.0.7

Fixed: Very occasionally, drawing a layout could fail midway through, leaving some or most of the link lines drawn but no nodes, and leaving the graph view in a confused state until another layout is done. This seems to have happened especially when generating a layout from query results at a slow SPARQL endpoint.

The new option Query Options | Query Engine | Merge Join Query Enginge (MJQE), along with its two new sibling options, can be used to establish which query engine will be used by the query view, without needing to add PREFIX statements to the queries themselves.

Fixed: The Table View could use the wrong row height for a value that contains embedded newline characters, sometimes not showing the whole value.

Assigning node corner commands by right-clicking a node corner is no longer enabled by default, to avoid confusion. The new commands Visual Graph Options | Node Corner Clicks | Specify the Command for a Node Corner and Visual Graph Options | Node Corner Clicks | Enable Right-Click Corner Assignment provide more options for assigning node corner commands.

Fixed: The Table View's Show All Triples button was never enabled when there are more triples to display. It was broken by the recent enhancements for displaying more triples for individual predicates.

Fixed: Selecting a different radio button menu choice did not clear the check mark from the previously-selected menu choice in the same radio button group in CG/JS mode.

Fixed: The Back and Forward buttons in The Table View and The Query View did not display their arrow images in 8.0.6.

The View Menu is now included in the The Lisp Evaluation View. This allows copying and pasting in that view for the first time (except in Windows mode, where it happened to work already). The button widgets in the lisp evaluation view for switching to other views are replaced by the usual commands for that on this menu.

Version 8.0.6

Gruff will now ONLY run in web browser mode on the Mac. An advantage is that GTK and XQuartz do not needed to be installed.

The new --launcher command line argument makes Gruff launch a copy of itself when it receives a request from a web page that will embed its personal instance of Gruff. The new --remote-password argument (or the CGJS_REMOTE_PASSWORD environment variable) can be used with that for security. The new --file-to-publish argument allows publishing an arbitrary web page, such a demo that embeds Gruff.

The file embedding.html in the main Gruff directory demonstrates remotely launching Gruff from a web page, embedding it in a frame on that web page, and even controlling it programmatically from a JavaScript application on that web page.

The Safari web browser is now supported (when running Gruff in a web browser).

The --confirm-exit command line argument can be passed as yes to make the web browser prompt for exit confirmation when you try to close the web browser tab for Gruff or reload the page.

The new --endpoint and --endpoints-password command line arguments can be passed to connect to a SPARQL endpoint automatically when Gruff starts up.

Automatic scrolling will now be done during certain dragging operations if you drag near or off one side of the pane. This includes when selecting the second end node in Link | Display Paths Between Two Nodes, when linking two nodes in the graphical query view, and when dragging to create a new triple between two nodes in the graph view.

Fixed: If you explicitly scroll during a path-finding drag, then the rubber-banding line did not get drawn in the portion of the window contents that are newly scrolled into view.

The query HTTP command can now accept the path of query text file on the server machine, rather than the actual query string.

The --limit-connections-to-same-machine command line argument no longer has a single-character alternative, because the -m that it did use conflicted with another use of it.

Version 8.0.5

Fixed: Gruff's HTTP interface (for controlling Gruff remotely) was not working when Gruff is running in a web browser. It also now has a new use-custom-title-bar-string command, with a new --custom-title command-line option as an alternative.

Fixed: The --disable-menus command-line option did not disable some kinds of interactivity, such as node corner commands.

Fixed: A query could get saved incorrectly if an IRI in the query that uses a namespace abbreviation happens to begin another IRI in the query.

Fixed: When running in a web browser, Gruff broke on literals that contain Unicode characters beyond the 16-bit range.

Fixed: Right-clicking in the graph view on a link line for a property path pseudo-predicate errored.

When running in a web browser, if the browser window is not wide enough to display a child menu beside its pull-down menu, the child menu can cover the command that you want to select on the parent menu. To help avoid this, there is now a two-thirds of a second pause before showing a child menu when moving the mouse over the parent menu.

SPARQL ASK queries are now supported in the query view.

Version 8.0.4

Graph-part reification now works with SPARQL endpoints.

Fixed: Pasting (rather than typing) into a password widget pasted the text twice.

Fixed: File | Load Layout State failed on literals that have embedded double-quotes other than at the ends, such as JSON literals.

Fixed: File | Load Layout State failed to load triples that had been saved from Display | Display Some Sample Triples when the triples are in named graphs.

Fixed: In the graphical query view, if a variable is used as both a node variable and a grouper variable (for example), then it got generated twice into the list of selected variables in the SPARQL query, which then errored.

Fixed: In the table view, clicking below the table in the predicate column broke.

Fixed: In the graph view, Select | Rotate to Next Link Clockwise broke on a reifying node.

Version 8.0.3

Better heuristics are used for preventing occasional long delays when fetching triples from the server. As part of this, the default value for "Global Options | General Triple-Fetching Limit" is now larger (5000) while the default value for "Table Options | Maximum Triples Per Predicate in Table" is much smaller (12). This prevents a sometimes long delay when displaying a node that has many triples in the table view, especially due to fetching many label properties. To remedy initially not seeing many triples for each predicate in the table view, text such as "show the other 37" will now appear below the name of any predicate that is not showing all of its triples, and you can click on that text to show the remaining triples for that individual predicate. And if the displayed triples are limited by the general triple-fetching limit, then the text "fetch more triples" will be shown instead, and you can click that to download more triples from the server. These two new default option values will initially override the values that are saved in the Gruff options file, because they work better with the new code optimizations.

Fixed: The representation of reification in Gruff's graph view, where the link line for a reifying triple is drawn connected to the middle of a link line for a reified triple, did not work when Gruff is running in a web browser.

Fixed: Creating triples that use new nodes or predicates could error in some cases, due to not interning the node values.

The new options Global Options | Timeouts | Filling In Links Timeout and Global Options | Timeouts | Image-Fetching Timeout avoid a delay or hang if those activities take inordinately long.

Fixed: Scrolling the query view results table with the mouse wheel or a two-finger trackpad drag did not work when Gruff is running in a web browser.

Fixed: Closing Gruff (when running in a web browser) and then making the web browser shorter and then running Gruff in it again could result in the divider widget in the query view being off the bottom of the window, so that the results grid is not shown, and maybe triggering an error.

Fixed: In the query view, dragging the divider between the query text widget and the results table could leave the bottom of the results table mispositioned.

Fixed: In the graphical query view on the Mac, you couldn't Command-click-and-drag to highight a group of nodes.

The previous incremental Gruff release did not indicate in the table view title when not all triples are shown due to hitting the general triple-fetching limit. And the text for that message was overly big.

More helpful (and correct) information is now shown in a dialog if finding all of the predicates that are in the triple-store times out.

Fixed: The dialog for entering a new value for an option that has a numeric value was showing the programmatic name of the option in its title bar, instead of the pretty option name.

The AllegroGraph server port is now mentioned in the title bar. This can be useful for checking which server is being used with port forwarding, where the only server machine name that Gruff knows is "localhost" for multiple servers.

Version 8.0.2

Fixed: In Gruff 8.0.1, connecting to most SPARQL endpoints errored. Browsing the endpoint would actually work after that, though some minor things did not get set up.

Fixed: In Gruff 8.0.1, clicking on a variable node in the graphical query view errored.

Fixed: In Gruff 8.0.1, the keystroke for Select | Copy Highlighted to Graphical Query View did not work because it used a keystroke that is used for another command.

Fixed: When browsing an actors repository or the DBpedia SPARQL endpoint, typing Alt+M to press the Example button in a query view would lead to one-second pauses when showing pop-up menus until the M key is pressed again.

Fixed: An error could happen when exiting Gruff, just after saying OK in the confirmation dialog.

Fixed: Gruff could crash in the graphical query view when dragging a link line to a different node than where it had been connected, if you drop the end of the line being dragged onto the link itself.

Version 8.0.1

Fixed: Gruff 8.0.0 could not list catalogs and repositories when using a proxy, preventing opening a repository.

When the number of triples for a node exceeds Global Options | General Triple-Fetching Limit, Gruff will now fetch triples for each predicate of the node's triples, so that all of the predicates are represented in the subset of triples that Gruff will browse for the node. This allows reducing the General Triple-Fetching Limit without missing some of the predicates, and switching to the new default of 1000 or even lower (the default had been 3000) is now recommended.

Copying to and pasting from the system clipboard now works anywhere in Gruff, rather than only in text-editing widgets as in Gruff 8.0.0 (when running in a web browser). The commands View | Copy and View | Paste now use the usual clipboard keystrokes, and there are no longer "two separate clipboards" for Gruff and the system. But due to JavaScript security restrictions, you will still need to use the Control+V or Command+V keystroke directly to paste from the system clipboard (rather than invoking Gruff's menu command some other way). And when doing a copy, a browser may still disallow it because it did not directly handle the copy gesture itself; in this case Gruff will show a modal dialog that allows you to directly copy to the system clipboard there.

Fixed: The Example button did not appear in the query views for the extended actors repository in certain cases, such as when connecting a web browser directly to gruff.allegrograph.com:10035.

Version 8.0.0

Gruff can now be run in a web browser, as an alternative to running it as a Windows or GTK desktop application as before. (And it runs in a web browser by default on Mac and Linux, though Safari is not supported, and so Gruff may not appear on a Mac unless you change your default web browser to be one other than Safari.) UPDATE: Safari was added later. This is now the complete Gruff, rather than the former command View | Display Gruff in a Web Browser, which provided only partial graph view functionality. The new approach looks nicer on the Mac and Linux, allows using the usual browser commands for scaling ("zooming") the entire application, allows Gruff to be used on a client machine while Gruff itself runs on a different server machine, and (especially on the Mac) doesn't require GTK and X11 (XQuartz on the Mac) to be installed. The supported browsers at this time are Chrome, Firefox, Edge, Opera, Brave, and Vivaldi. (UPDATE: Safari was added later.) See the new section Running Gruff in a Web Browser, which details command-line arguments that can be specified for running Gruff in different modes. The new option Global Options | Miscellaneous | Run in Web Browser can be used to toggle the default mode when running Gruff interactively (with no command line arguments). Gruff will now run in a web browser by default on Mac and Linux, or as a Windows app on Windows as before. On Linux, the support is included in the single download for running in a browser or starting the GTK version. On macOS, there are separate downloads for the browser and GTK versions. Gruff can also now be started from AGWebView, where Gruff itself will run on the server machine where AllegroGraph is running, but display in another tab of the web browser where AGWebView is running; see Installing and Running Gruff.

When running in a web browser, there are now TWO clipboards, due to JavaScript security restrictions that disallow accessing the system clipboard except by letting the browser's usual keystrokes do it directly: (1) The system clipboard, which you can access only when the keyboard focus is in a text-editing widget by using the usual keystrokes Control+C and Control+V (or Command+C and Command+V on a Mac). These keystrokes can be used for copying and pasting text between Gruff and other applications, such as pasting a node IRI from elsewhere. These keystrokes do not appear on any menu because only the keystrokes work. (2) The Gruff clipboard, which you can access as before with View | Copy and View | Paste. The Gruff clipboard works only within Gruff, mostly for copying nodes from one view to another. Unfortunately there is no overlap between the two clipboards, due to JavaScript security measures.

Copying and pasting text now works in more places, especially in modal dialogs.

The new command File | Display Layout in New Browser Tab (when Gruff is running in a web browser) allows you to save a layout as an image file on the client machine, when it is different from the server machine where files are normally read and written in browser mode. You could also use the browser's command to copy the image to the system clipboard, and then paste it into an email message, for example. Or you could use this command multiple times to compare different layouts on the fly without saving them to files.

The new command Layout | Update Tree Layout updates the most recent tree layout, using the same root node as before even when it is no longer the selected node.

The existing keystrokes for incrementing the font size in the current view are now on the menu bar at Global Options | Fonts | Increase Font Size and Global Options | Fonts | Decrease Font Size, to make it easier to discover them. And the keystrokes have changed to avoid conflicting with the usual web browser commands for zooming the entire application.

When doing a SPARQL query in the query view, if the SPARQL engine collects any warnings about likely unintended or inefficient code in the query, then those warnings will be shown in a dialog.

Fixed: Using predicate paths in user queries in the query view was broken.

Fixed: Path-finding would not connect literal nodes that are in found paths when Global Options | Miscellaneous | Treat Literals as Objects is off.

Fixed: The option Global Options | Fonts | Widget Font was not getting used in some dialog widgets.

Fixed: An error could result when looking up labels for types, though apparently only in atypical situations such as if you had at some time explicity removed the preset color to use for literal nodes or nodes that have no type.

The new user option Global Options | Node Label Predicates | Use Label Predicates for Predicate Labels could be turned off to display label properties for nodes but not for predicates. (Displaying label properties for predicates is new behavior.)

The command line arguments that can be passed when starting Gruff have changed somewhat, especially the ones for a triple-store to open at startup time, where the behavior is somewhat different as well. See Using Command Line Arguments When Starting Gruff.

The new --options-file-path command-line argument may now be passed to read the options file from a custom location, and to save it back there.

A new check box on the File | Open Triple-Store dialog allows you to quickly toggle whether to use the HTTP proxy (if you have set one up with Global Options | Communications | HTTP Proxy).