These are links into the Detailed Contents.
IntroductionThese are links into the actual content.
IntroductionGruff is an interactive triple-store browser, query manager, and editor. It works on AllegroGraph from Franz Inc. and to a somewhat lesser extent on 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 stores, data can be created and edited by filling in tables of property values, or by connecting visual nodes with link lines for new triples. The various views and tools are tightly integrated to facility rapid browsing, querying, and editing.
To run the standalone Gruff application, simply run gruff.exe on Windows or "gruff" on Linux or the Mac.
(Advanced note: If you are a user of Allegro Common Lisp, then you could alternately load the file Gruff fasl file into lisp. See Using Gruff Programmatically in a Lisp Application.)
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.
First use File | New Triple-Store to create a new AllegroGraph store, 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 store that has already been created.
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:
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 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.
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 are options for selecting 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 provies 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 rdfs:label property of the node, but it only works for nodes that have rdfs:label 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.
In addition to the menu bar commands, there are some special mouse clicks in the graph view.
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:
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:
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.
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.
If the URI or literal string of a node names a pixmap file on the local machine, then the graph view will display the pixmap for the node rather than a text label. The string may either contain the "file:///" URI prefix or not.
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. For example, if the value of that option is "c:/documents/" and a node in the graph view is for the literal "pretty-picture.bmp" (or for the URI "file:///pretty-picture.bmp"), then Gruff will look for the file c:/documents/pretty-picture.bmp. 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.
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 user 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 or loading a layout will revert all nodes to their standard sizes.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Copies the URI of the selected node to the system clipboard.
This command is a copy of the menu bar command "View | Copy." See that command for more information.
Invokes your third-party web browser or other program on the IRI or literal string of the selected node, if any. See View | Invoke Web Browser or Program for more information.
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.
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.
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).
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.
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.
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.
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.
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.
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.
Copies the URI of the predicate of the triple that the link line represents to the system 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.
Copies the triple ID of the triple that the link line represents to the system 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Invokes the table view on the type that the selected legend node represents.
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.
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.
Removes from the display any nodes that are colored for the type that's represented by the selected legend node.
Copies to the system clipboard the URI of the type that's represented by the selected legend node.
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.
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.
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.
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.
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.
Lets you change the layout direction constraint for the predicate of a legend link line when it's already got one.
Removes the layout direction constraint for the predicate of a legend link line when it has one.
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.
Removes from the display any link lines that are colored for the predicate that's represented by the selected legend link line.
Copies to the system clipboard the URI of the predicate that's represented by the selected legend link line.
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).
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 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. 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.
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.
If the currently-displayed object has 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. 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.
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.
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.
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.)
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.
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.
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.
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.
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).
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.
This command is just like Table View Value Column Editing | Create Row for a New Triple, except that you are not prompeted 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Copies the URI string or literal string of the selected node to the system clipboard. This command is simply a copy of the menu bar command View | Copy.
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.
Invokes your third-party web browser or other program on the IRI or literal string of the currently selected node, if any. See View | Invoke Web Browser or Program for more information.
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.
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.
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:
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.
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.
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.
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.
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.
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.
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.
Copies the URI string of the selected predicate to the system clipboard. This command is simply a copy of the menu bar command View | Copy.
Displays the node that was previously displayed in the table. See Table View Value Column Navigation | Go Back.
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.
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.
See Table View Value Column Navigation | Refresh Table.
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 to show those triples when they are hidden (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 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 store in Gruff. The editing commands will then not be available.
This menu appears when you right-click in the outline view or press the M key.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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, 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.
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.
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.
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.
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.
Selects the node that is immediately beneath the currently selected node.
Selects the node that is immediately above the currently selected node.
Selects the parent item of the currently selected outline item.
Selects the next outline item that's a sibling of the currently selected outline item, if any.
Selects the previous outline item that's a sibling of the currently selected outline item, if any.
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.
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.
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".
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.
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.
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.
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.
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.
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.
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.
Copies the URI string or literal string of the currently selected node to the system clipboard, for pasting anywhere. This is a copy of the View | Copy command.
Copies to the system 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.
Invokes your third-party web browser or other program on the IRI or literal string of the currently selected node, if any. See View | Invoke Web Browser or Program for more information.
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.
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.
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.
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, though not at a SPARQL endpoint or on the old Allegrograph version 3. The Run Query button will show "Cancel Query" while a query is running to indicate that it will do that. It may take several 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 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 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 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.
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.
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.)
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 Full URIs 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 | Node URIs.
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 triples 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/or Link 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.
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.
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.
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.
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.
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. See Select | Toggle Highlighting of the Selected Node or Link.
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.
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.
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.
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.
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/2013/REC-sparql11-query-20130321/ .
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.
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.
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.
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
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 system 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 system 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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Removes the node from the diagram along with any links that are connected to it.
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.
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:
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.
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.
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.
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.
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.
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.)
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.
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.
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.
Removes the link line from the graphical query.
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.
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 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.
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.
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.
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).
You can partially control the order of the generated query text via the positioning of nodes and groupers in the graphical 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. To change that behavior, you could place a grouper around the sibling nodes and then place the new grouper as needed. Also, 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.
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.
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 system 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.
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 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.
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 link 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.
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.
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 sometime 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.
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.) By default this will show just the help for that command in a modal dialog, but if you toggle on the Help | Use Web Browser for Menu Help option, then it will instead show the single Gruff document in a third-party web browser and scroll down to the selected command.
These commands are for opening a triple-store to browse, or for creating a new store and loading triples into it.
Creates an AllegroGraph store at a location that you specify. You can then populate the new 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, store name, user name, and password as documented under File | Open Triple-Store. See that command for more information about those prompts.
After creating a 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 store extra quickly, simply select it from the list of recently-used stores that will appear on the File menu.
Opens an existing AllegroGraph triple-store that you select. You can specify a store that you created earlier with File | New Triple-Store followed by File | Load Triples | Load N-Triples, for example, or any other 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 store from the list of recently-used stores that appears at the bottom of the File menu.
If there is an open 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 store, you will also be prompted to commit the changes (except on AllegroGraph version 3).
Then a dialog will appear with a set of widgets to fill out to specify which store to open and in what manner.
You will be asked to type in the name or IP address of the server machine on which the AllegroGraph server is running. You will also be asked for 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. If you do not specify the correct server machine or port number, it can result in an error message saying that the store "does not appear to exist".
You will also be asked to select the catalog that contains the desired 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 then catalog, you will be able to select a store from a list of the stores that are in that catalog. (The lists of catalogs and 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 stores from the same catalog may be federated (to browse the combined stores) by control-left-clicking to select multiple stores in the list of store names.
If you're using Gruff for the much older AllegroGraph version 3, then a dialog will ask you to select the directory (folder) that contains the store to open. Opening a store on a remote machine is more like the AG4 case, though rather than selecting a catalog and a store from lists, you will need to type in the full path of the remote store's folder.
You will also be asked to enter 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).
Another prompt is for whether the 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 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 store in Read-Only mode, which prevents you from inadvertently modifying the store, and avoids an error when you don't have write permission for the store.
The dialog also allows 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.
You may also request that the 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 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 store that you're opening plus any triples that Gruff downloaded as you browsed the previous store or endpoint. See Building an Ad Hoc Federation from Multiple Stores and Endpoints.
Gruff normally communicates with the server using the HTTP 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.
If an error occurs when opening a 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 session for that open store. One way to handle that problem is to turn off Global Options | Communications | Use Session Ports so that the main server port is used for the open store. Another way is to allow the use of a particular small range of session ports, as described here.
When you open a 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 for that particular session, so as not to overload the main server port. The server then provides that port to the client, 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 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 Session Ports as well as Global Options | Communications | Use Direct Access When Possible.
An alternative to the store-opening commands on the File menu is to pass command line arguments when starting up Gruff. That will automatically open the specified store just after Gruff starts up.
An attempt will be made to open a store when Gruff starts up if and only if there is a store name argument at the end of the command line, where that argument is not the value of a "-" or "-- argument. The store name argument should be the name of the store (or the path of the store's directory on AllegroGraph version 3).
Other arguments related to the store to be opened can be passed using the following Unix-like arguments:
-h host-name, --host host-name
The name of the remote server machine that is running the AllegroGraph server. If unspecified, the store will be opened on the local machine.
-p port-number, --port port-number
The port at which to connect to the server. If unspecified, it defaults to 10035. On AllegroGraph 3, this argument is not used when opening a store non-remotely.
-r, --read
If specified, the store will be opened in read-only mode. Otherwise it will be opened in read/write mode.
-c catalog-name, --catalog catalog-name
The name of the catalog in which the store resides. If unspecified, it defaults to the root catalog. Not used in AllegroGraph 3.
-u username, --user username
The user name with which to connect to a remote server. If unspecified, Gruff will prompt for the user name if you are connecting to a remote server. Not used in AllegroGraph 3, or when opening a store non-remotely.
-w password, --pass password
The password with which to connect to a remote server. If unspecified, Gruff will prompt for the password if you are connecting to a remote server. Not used in AllegroGraph 3, or when opening a store non-remotely.
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 on host fred at port 10035. Then it will pass "alice" as the user name. Because no catalog or password is passed here, Gruff will default to the root catalog and prompt for the password.
gruff --read --host fred -u alice my-store
--exterior exterior, -e exterior
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
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.
This command lets you browse a particular SPARQL endpoint directly, 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. Some things may be slower, such as looking up types for coloring nodes in the graph view, but note that you can escape out of coloring the nodes if desired.
A monthly password is currently required for browsing SPARQL endpoints. Connect Franz at info@franz.com 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.
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 in the endpoint to which you're now connecting plus any triples that Gruff downloaded as you browsed the previous store or endpoint. See Building an Ad Hoc Federation from Multiple Stores and Endpoints.
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 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://dbpedia.org/sparql http://live.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.
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 menu command does not exist in AllegroGraph version 3.
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.
This menu command does not exist in AllegroGraph version 3.
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 (except in the much older AllegroGraph version 3, where it indexes new triples after the load instead).
If the N-Triples file contains non-ASCII characters, see Global Options | Miscellaneous | External Format for Loading Triples.
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.
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.
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.
Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the Trix format.
Loads triples from a file or web page like File | Load Triples | Load N-Triples, but the data should be in the Turtle format.
This command is not available on the old AllegroGraph version 3.
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 | Miscellaneous | 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 set up the proxy information with Global Options | Communications | HTTP Proxy.
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 (this is not applicable on AllegroGraph 3), then an alternative to this command is to simply specify multiple stores when asked for the store to open in File | Open Triple-Store.
This command will appear only in AllegroGraph version 3. In AllegroGraph 4 and beyond, indexing is done automatically.
Ensures that all triples are indexed and merged into a single index. You may not need to use this command because Gruff periodically indexes any new triples automatically to ensure that all new triples get indexed and merged together for faster lookup and queries. But this can still leave new and pre-existing triples in separate indexes, accumulating several indexes over several Gruff sessions where editing is done. So this command can be used to call index-all-triples for maximum efficiency. Gruff automatically.never indexes ALL triples automatically because it can take a while, so you may want to use this command only when you are willing to wait for it.
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 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.
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.
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.
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.
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.
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 it with the file dialog.
In the lisp interface, the corresponding function is load-layout.
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. On Windows a BMP file will be saved, while on Linux and Mac a PNG file will be saved.
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.
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.
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.
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.
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.
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 it with the file dialog.
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.
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.
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 it with the file dialog.
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.
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.
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.
This is like File | Export Displayed Data As | N-Triples except that the file format will be RDF/XML.
This is like File | Export Displayed Data As | N-Triples except that the file format will be RDF-N3.
This is like File | Export Displayed Data As | N-Triples except that the file format will be TriX.
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.
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" (without the surrounding quote marks) for Node Attributes.
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.
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.
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).
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.
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.
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.
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.
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.
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 Graph View Panes child menu is present only in the graph view.
Toggles whether an overview pane appears at the bottom of the legend. It will appear only if View | 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.
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 | Graph View Panes | Pop Up Overview is a way to use a larger overview without making the whole legend wider.
The Graph View Panes child menu is present only in the graph view.
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 | 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 Graph View Panes child menu is present only in the graph view.
Toggles whether using View | 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 Graph View Panes child menu is present only in the graph view.
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.
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.
Extracts a URI or literal text from the selected object and posts it onto the system 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.
Perhaps the most useful application of the cut 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.
Pastes the string that is on the system 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 system clipboard and paste that node.
In the query text widget of the query view, the text may be 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.
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.
On the Windows platform, 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.
On Linux and Mac, this command will always attempt to invoke the Firefox web browser, which should work if it is installed and in your path. If Gruff believes that the invocation of Firefox failed, then it will simply post the value to the clipboard for you to paste into a browser. Check the status bar for a message about that.
A mouse shortcut for this command is control-shift-left click, which works on nodes in the various Gruff views.
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.
Invokes your preferred web browser program to view the currently-open store in AGWebView, which is our web-based triple-store browser. AGWebView has various capabilities that Gruff does not, such as for performing administrative tasks.
You could instead enter the URI yourself in the web browser, though you would need to construct a URI such as http://my-machine:10035/catalogs/my-catalog/repositories/my-store. This Gruff command simply constructs that URI for you.
If this command is unable to programmatically invoke a web browser program, it will place the URI that it was attempting to display onto the system clipboard, so that you can paste it into a web browser yourself.
This command is not available on AllegroGraph version 3, or with a SPARQL endpoint.
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 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.
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.
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" (without the quotation marks) 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.
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.
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 does not appear in AllegroGraph 3, where a store can have only a single 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 (though in AllegroGraph 3 there is no way to unregister predicates that are already registered).
The dialog contains additional widgets (except on AllegroGraph 3) 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 (except on AllegroGraph 3, where it indexes all triples instead).
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.
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 does not apply to AllegroGraph 3.)
This command always commits the triple store at the end (except on AllegroGraph 3, where it indexes all triples instead).
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 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.
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.
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 system clipboard.
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). If no such resource or literal exists in the triple store, then a dialog will inform you that no resource or literal was found. 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.
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 | Node Label Predicates | Label Predicate Language), and if one is not found then another literal search is done using no language.
This tecnhique works in any triple-store, though it requires specifying an actual URI or literal.
If you are entering non-ASCII characters that are percent-encoded in the store, then see Edit | Percent-Encode Non-ASCII After Editing.
This command is useful only if the triple-store being browsed contains resources that have 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 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.
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.
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 "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.
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.)
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.
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.
In a Gruff that's built on AllegroGraph 6 or later, 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
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.)
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.
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.
Currently this command simply retrieves the first so many triples from the store to display, unless you are browsing the DBPedia SPARQL endpoint, in which case it runs one of several sample queries and displays the results. Perhaps some general sample queries will be used for other stores in the future.
This command is present only in the graph view.
In the lisp interface, the corresponding function is display-store.
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.
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.
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.
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.
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.
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.
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, 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.
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.
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.
Causes Link | Display Linked Nodes for the Current Predicates to show triples where the selected node is either the subject or the object.
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.
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. 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 will be slower if the user does not have permission on the server to evaluate arbitrary code.
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.
In the lisp interface, the corresponding function is find-and-display-paths.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
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.
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.
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.
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). 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). Only Layout | Redo Layout from Scratch (or removing nodes from the display) will free the nodes from the tree arrangement.
This command is affected by all of the options on the Visual Graph Options | Tree Layout Options child menu. These commands are 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Pins the selected node so that it will not be moved whenever a layout is done. 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.
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).
The Layout | Center the Graph command will still move pinned nodes, including when it is done automatically due to Visual Graph Options | Layout Options | Center After Full Layout (and after incremental layout). To fully pin nodes in place, you might want to turn off those options.
This command is present only in the graph view and the graphical query view.
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.
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.
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 | Node URIs.
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.
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.
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.
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).
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.
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.
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.
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).
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
This menu command does not exist in AllegroGraph version 3.
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.
If true, then whenever you create a new blank, 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.
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.
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.
Options that may affect all Gruff views.
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.
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 | 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.
When enabled, the label that is displayed for a resource node in various Gruff views and menus will be the rdfs:label property of the resource, 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 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.
Gruff uses this option to select rdfs:label and rdfs:comment properties in a particular language for displying on nodes and in tooltips in the graph view. The value is a standard two-character language tag such as "en" for English or "jp" for Japanese, and can be selected from this child menu.
When Global Options | Node Label Predicates | Use Label Predicates for Node Labels is on, then the strings that appear in node boxes are (by default) the rdfs:label properties of the nodes when they exist. Gruff will use 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 to provide the tooltip text, and it will use only an rdfs:comment property that has either no language tag or this language tag.
In addition, the table view will not show literals that have language tags other than this one unless Table Options | Display Literals of All Languages is on.
Determines which properties are used for providing values that are displayed as labels to represent nodes.
If a store does not contain 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://www.franz.com/simple#first-name http://www.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 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.
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.
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, then a pixmap will be loaded from that file and displayed for that node.
For example, if you specify the predicate http://www.franz.com/simple#pixmap_file for this option, and the store contains the following triple:
http://dbpedia.org/resource/Terry_Jones http://www.franz.com/simple#pixmap_file file:///c:/pixmaps/seaside.bmp
and the file c:/pixmaps/seaside.bmp 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. (An exception is that if Gruff is built on a version of Allegro Common Lisp earlier than 10.0, then on Windows only bmp files can be used. This is never the case for Gruff for AllegroGraph version 6.0 and beyond.)
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.bmp 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.
See Displaying Images for Nodes for more information.
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 | Invoke Web Browser or Program, 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 | Invoke Web Browser or Program 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.
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 rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.
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 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.
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 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.
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 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.
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 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.
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 for Node Under Mouse 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".
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This is a copy of Query Options | Query Timeout, to group all of the timeout options on a single menu.
This is a copy of Text Search | Text Search Timeout, to group all of the timeout options on a single menu.
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.
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.
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 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.
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.
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.
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.
When checked, any pop-up menus that list nodes or predicates will display the complete URIs for those objects. The URIs will be shown just to the right of the usual short strings, and the menus will still be sorted by the short strings.
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.
Starts up a server to handle requests that are made to Gruff from external software via the HTTP protocol. Several commands have been implemented so far 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.
This menu command will ask for the port at which the server will listen for requests. The default port is 8000. Thereafter, external software can control Gruff by sending HTTP requests to that port on the host on which 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
For the particular HTTP requests that can be made to Gruff, see the section entitled The HTTP Interface to Gruff.
All pull-down and pop-up menu commands, including their keyboard shortcuts, can be disabled by passing the --disable-menus (or -d) command line argument, with no value after it. The menu bar will not be added to the Gruff window at all, and no pop-up menus will appear. This may be useful if you want to control Gruff exclusively by HTTP commands remotely, and to prevent the user from controlling Gruff interactively.
When enabled, the AllegroGraph server will provide an arbitrary session port to Gruff whenever it opens or creates a store, and all communication for that open store will then be done using that port rather than the main server port that you specify when opening or creating the store.
This option is enabled by default because it may be more efficient, by using a separate process on the server along with the separate port, rather than sharing the same process and port with other clients of the server. This can be a problem, though, 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 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 when sessions ports are not used. This includes SPARQL queries that some Gruff commands do internally.
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.
On AllegroGraph 3, direct access is always used when the local machine is specified as the server, because running a separate server requires using a lisp to run it in.
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 Session Ports.
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.
This option matters only when the SPARQL endpoint or AllegroGraph server 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. When using AllegroGraph, this applies to direct HTTP requests that Gruff makes for listing the catalogs and stores that are on the AllegroGraph server.
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. Currently this information is used only when you are using a SPARQL endpoint. It is not used with remote AllegroGraph stores, except that it is used by File | Extract Microformat/RDFa Data from Web Page.
The server field should be an Internet domain name of the form franz.com. The port field should be an integer like 8000. If the port is left blank, it will default to 80.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
When checked, View | Invoke Web Browser or Program 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.
If your store contains literal nodes that refer to document files that are stored on the local machine, then you can use View | Invoke Web Browser or Program (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 UPI is the literal "important-info.txt". Then if you use the "Invoke Web Browser or Program" 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.
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.
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.
The value that is selected here will be passed as the value of the :external-format argument to load-ntriples whenever the File | Load Triples | Load N-Triples command is used, or to load-nquads when File | Load Triples | Load N-Quads is used. The default value should be fine for most uses, but if an ntriples file uses a non-ASCII character set then you may need to select the appropriate external format here before loading that ntriples file.
This options is not used in Gruff for AllegroGraph 3.3, which supported only ASCII triples files.
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.
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.
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.
Saves all options (from all of the options menus) to 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 when you exit the browser. Newer versions of Gruff will continue to use the same options file, and there is also no problem with loading the options file if you revert to an older version of Gruff.
If you browse many different stores in Gruff and are concerned about the options file growing larger, you can remove the data for selected older stores with Global Options | Miscellaneous | Remove Old Stores from Options File.
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.
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.
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:
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.
Options that affect SPARQL and Prolog queries. This menu is present only in the query view and the graphical query view.
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.
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.
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.
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.
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 origin of any query results, but can also include triples that are related only by having parts that are scattered throughout the query results.
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, 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.
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.
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.)
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.)
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.)
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.
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.
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.
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.
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 | Node Label Predicates | Label Predicate Language child menu.
This command is present only in the table view.
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.
This is the maximum number of triples that will be displayed under any single predicate when you display a resource in the table view. This limit avoids taking too much time to display a resource that has many triples.
If not all 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. Clicking the button will regenerate the table to show all triples of the resource.
This command is present only in the table view.
Any string that is displayed in a table cell for a UPI will be truncated to this length if it is longer. This is to avoid attempting to display any extremely longs strings.
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.
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.
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.
Options that affect the display of information in the outline view. This menu is present only in the outline view.
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.
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.
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 "click here to see 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.)
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.
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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 (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.
This command is present only in the graph view. (Link labels are always drawn in the graphical query view.)
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.
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.
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.
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.)
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.)
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.)
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 is turned on. It is yellow 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.
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.
When checked, each iteration that the layout algorithm goes through while looking for a solution is displayed on the screen, creating an animation effect. The current state is displayed each time all nodes have been moved one more time. When animation is not done, only the final state is displayed.
Animating layouts will make them take longer, though it may be useful for seeing how the layout is progressing, and it gives you something to do while waiting on the layout. For larger layouts you will probably want to toggle off animation to save time (and also increase Visual Graph Options | Layout Options | Maximum Iterations for Full Layout to allow the layout to progress longer).
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. It is recommended that you use the keyboard shortcut of this command for this purpose. 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 it 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
When checked, File | Save Layout as Pixmap will display the pixmap that was saved by invoking a third-party program on the saved file. On GTK (Linux and Mac) it will always attempt to invoke a Firefox web browser. On Windows it will invoke whatever program is registered for displaying BMP files, unless Global Options | Miscellaneous | Use Web Browser for All Documents is enabled.
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 options 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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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 options 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.
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.
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.
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.
When checked, any command that removes some nodes 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
This is the number seconds before the path-finding commands will give up and display a warning dialog about a timeout.
The Finding Paths Between Nodes child menu is present only in the graph view.
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.
This is the maximum number of found paths that will be displayed, or offered for selection of a subset.
The Finding Paths Between Nodes child menu is present only in the graph view.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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 is enabled.
The Tooltips child menu is present only in the graph view.
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.
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.
This is the background that is used in the tooltip windows that appear in the graph view and the outline view.
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.
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.
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.
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.
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.
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.
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.
This is length of all arrowheads that are drawn in the graph view, measured in pixels.
This is width of all arrowheads that are drawn in the graph view, measured in pixels at the base of the arrowhead.
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.
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.
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.
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.
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.
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.
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.
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.
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.
See also Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
Displays a dialog for selecting a pixmap file to provide a background image in the graph view. On Windows this should be a BMP file, and on Linux it should be a file that GTK knows how to read, which includes PNG, JPG, BMP, and X bitmap files.
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.
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.
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.
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.
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.
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.
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.)
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.
The font that's used in the input pane. Usually a fixed-width font is best for code.
The font that's used in the output pane. Usually a fixed-width font is best for code.
This is the value that the Common Lisp special variable *print-level* will have while evaluating code.
This is the value that the Common Lisp special variable *print-length* will have while evaluating code.
Displays this help document as an HTML file in your preferred HTML browser program on Windows, or in Firefox on Linux if installed. The HTML help file is doc.html.
Displays this help document as a plain text file. The file is doc.txt.
When checked, pressing F1 while a menu item is highlighted will show the HTML file that contains all Gruff documentation in your web browser, just as when you press F1 at other times to invoke Help | Show Documentation as HTML, and then it will attempt to scroll the browser to the help entry for the menu command that was highlighted when you pressed F1. This option may not work, depending on your web browser program, especially on Linux.
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.
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.
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.
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.
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.
Runs a cyclical animated demonstration of the graph view and the table view. The demo will run indefinitely until you stop it either by invoking this command again or by pressing the Escape key or the Q key.
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 on the Franz web site ( http://www.franz.com ) on the main Gruff page, in the area for downloads. 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.
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.
Displays a dialog with various statistics about the currently-open triple-store. Specifically, this is what is printed by the functions index-status-report and db-room.
This command is present only on AllegroGraph version 3.
Displays the About dialog with the current Gruff version number. The version number is held in the variable *gruff-version*.
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 can be built into a standalone lisp application. 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".
(1) Install the special 9.0 CG patches for an 8.2 lisp. To use the Gruff fasl file in an 8.2 Allegro Common Lisp IDE, you will need to install a special large patch that provides all of 9.0 Common Graphics on the 8.2 lisp. This patch is downloaded by default, but is not installed by default. To install it, first make sure that you have downloaded all current patches. Then rename the file require-search-list.txt in the main Allegro directory to require-search-list.cl. Then run update.exe (or simply "update" on Linux or Mac) as usual. For more information, see this page:
http://www.franz.com/support/patches/log/8.2/index.lhtml#cg9.0_*
(2) The AllegroGraph client (and therefore Gruff) requires using a case-sensitive version of the lisp, which generally means using allegro.exe rather than allegro-ansi.exe.
(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:
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 graph view pane in the full browser.
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:
(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 expression 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.
(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:
(eval-when (compile load eval) (use-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 100 900 700))))
(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.
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.
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 (merge-pathnames "tempgraph" (sys:temporary-directory)) :if-exists :supersede)
The symbols documented here are exported from the gruff package, which has the nickname "uf".
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.
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 layout pane".
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* (triple-store:resource "MiddleThing"))
(defparameter *things* (let* ((things nil))
(dotimes (j 9)
(push (triple-store:resource
(format nil "Thing ~a" j))
things))
(nreverse things)))
(defparameter *points-to* (triple-store:resource "PointsTo"))
(let* ((count 9)
(triples nil))
(dotimes (j count)
(triple-store:add-triple *middle-thing* *points-to* (nth j *things*))
(triple-store: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 (triple-store:get-triples-list :p *points-to*)
:keep-old-nodes nil
:layout-from-scratch t
:node-pane *my-node-pane*
:select-window t)
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 "<foo>".)
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)
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.
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 "<foo>".)
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.
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 "<foo>".)
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.
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 "<foo>".) 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)
(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*))
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 the first arbitrary set of triples that are found will be used, even if they are already displayed on the node pane.
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.
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 "<foo>".)
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*)
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.
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.
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.
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 "<foo>".)
See the example for display-linked-nodes.
This function corresponds to the menu command Global Options | Select Current Predicates.
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 "<foo>".)
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.
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.
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 "<foo>".)
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.
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.
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.
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 layout 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.
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.
(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.
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. On Windows a BMP file will be saved, while on Linux a PNG file will be saved.
(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.
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.
Uncaches information as needed if the open store has been modified after displaying information from it in Gruff.
(defun uncache-for-modified-triple-store ()
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.
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.
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.
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.
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.
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.
A global variable whose value is a string indicating the current version of Gruff. This value is shown in the Help | About dialog.
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 | Graph View Panes | Show Legend - show-legend (boolean) View | 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 | Label Predicate Language - label-property-language (string) 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 Session Ports - 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 | Reasoner Enables Restriction Reasoning - reasoner-enables-restriction-reasoning (boolean) Global Options | Miscellaneous | External Format for Loading Triples - external-format-for-load-ntriples (symbol) 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 (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)
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 external-format-for-load-ntriples symbol should be a keyword such as :iso8859-3 that names an external format, or else the symbol :default.
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)))
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.
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.
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 except on AG3 to local), 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 (except on AllegroGraph version 3) user and password. On AllegroGraph version 3, the store-name argument should be a full directory path (percent-encoded), and the catalog argument is not used.
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 (except on AllegroGraph 3) 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. (Not available on AllegroGraph version 3.) 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.
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.
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
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 either ag-store for an AllegroGraph store, or endpoint for a SPARQL endpoint, or the empty string if neither of those are open.
http://hazel:8008/store-info?attribute=store-name
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 query-string, which should be the percent-encoded query text itself. Optional arguments are layout, keep-old-nodes, and allow-dialogs, which may be either yes or no, defaulting to no.
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
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.
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
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
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
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
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
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
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
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
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
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
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>
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
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
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.
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
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
animation-demo-delay canvas-resize-factor drag-scroll-zoom-factor
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
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
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
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
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
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.bmp&show=yes
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
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
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
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 Session Ports or configure the AllegroGraph server and your firewall to allow the same range of ports. See A Note About Session Ports and Firewalls.
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.
On the MacIntosh, 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 http://xquartz.macosforge.org/landing/ and install it following the instructions there. Do this even if you have installed Xquartz before. If the problem persists, contact Franz Inc. at support@franz.com.