Gruff: A Triple-Store Browser, Query Manager, and Editor

Main Contents

These are links into the Detailed Contents.

Introduction
    Getting Started
The Graph View
    The Graph View Node Pop-Up Menu
    The Graph View Link Pop-Up Menu
    The Graph View Background Pop-Up Menu
The Table View
    The Table View Value Column Editing Pop-Up Menu
    The Table View Value Column Navigation Pop-Up Menu
    The Table View Property Column Pop-Up Menu
The Outline View
    The Outline View Editing Pop-Up Menu
    The Outline View Navigation Pop-Up Menu
The Query View
The Graphical Query View
    The Graphical Query Background Pop-Up Menu
    The Graphical Query Variable Node Pop-Up Menu
    The Graphical Query Non-Variable Node Pop-Up Menu
    The Graphical Query Link Pop-Up Menu
    The Widgets on the Left Side of the Graphical Query View
Building an Ad Hoc Federation from Multiple Stores and Endpoints
Reification Support in Gruff
The Menu Bar Commands
    The File Menu
    The View Menu
    The Text Search Menu
    The Display Menu
    The Link Menu
    The Remove Menu
    The Layout Menu
    The Select Menu
    The Edit Menu
    The Global Options Menu
    The Query Options Menu
    The Table Options Menu
    The Outline Options Menu
    The Visual Graph Options Menu
    The Help Menu
Using Gruff Programmatically in a Lisp Application
    The Programmatic Lisp API to Gruff
    Lisp Functions for Modifying User Options Programmatically
The HTTP Interface to Gruff

Detailed Contents

These are links into the actual content.

Introduction
    Running Gruff
    Getting Started
        Using the Various Gruff Views
        Using Gruff Menus
The Graph View
    Special Mouse Clicks in the Graph View
    Using Current Predicates to Quickly Build a Graph
    Interrupting a Long-Running Layout
    The Selected Node
    Visual Indicators in the Graph View
    Displaying Images for Nodes
    The Graph View Node Pop-Up Menu
        Graph View Node | Display the Nodes and Link of This Triple
        Graph View Node | Display a Linked Node from Menus
        Graph View Node | Display Linked Nodes from a Tree
        Graph View Node | Display Linked Nodes for the Current Predicates
        Graph View Node | Display Only Linked Nodes for the Current Predicates
        Graph View Node | Display Paths Between Two Nodes
        Graph View Node | Display Only Paths Between Two Nodes
        Graph View Node | Create a Triple by Linking Nodes
        Graph View Node | Create a Triple Using Most Recent Predicate
        Graph View Node | Delete a Triple from Store
        Graph View Node | Edit Node by Type
        Graph View Node | Select Preferred Type for Node Colors
        Graph View Node | Copy Node URI to Clipboard
        Graph View Node | Invoke Web Browser or Program
        Graph View Node | Highlight the Node
        Graph View Node | Pin the Node
    The Graph View Link Pop-Up Menu
        Graph View Link | Remove Link from Display
        Graph View Link | Delete Triple from Store
        Graph View Link | Reverse Triple Direction in Store
        Graph View Link | Drag to Replace Triple
        Graph View Link | Create a Reifying Triple
        Graph View Link | Display a Reifying Triple
        Graph View Link | Copy Predicate URI to Clipboard
        Graph View Link | Copy Triple ID to Clipboard
        Graph View Link | Highlight the Link
    The Graph View Background Pop-Up Menu
        Graph View Background | Redo Layout from Scratch
        Graph View Background | Update Layout Incrementally
        Graph View Background | Make Canvas Larger
        Graph View Background | Make Canvas Smaller
        Graph View Background | Go Back
        Graph View Background | Go Forward
        Graph View Background | Search the Current View
        Graph View Background | Remove All Nodes
        Graph View Background | Eraser Mode
        Graph View Background | Remove All Node and Link Highlighting
        Graph View Background | Remove All Node Pinning
The Table View
        Special Colors in the Table View
    The Table View Value Column Editing Pop-Up Menu
        Table View Value Column Editing | Enter a Different Node
        Table View Value Column Editing | Select a Different Node
        Table View Value Column Editing | Enter a Typed Literal
        Table View Value Column Editing | Rename the Node
        Table View Value Column Editing | Reverse Triple Direction
        Table View Value Column Editing | Create Row for a New Triple
        Table View Value Column Editing | Create Row for the Same Predicate
        Table View Value Column Editing | Delete the Triple
        Table View Value Column Editing | Undo
        Table View Value Column Editing | Redo
        Table View Value Column Editing | Edit Displayed Node by Type
        Table View Value Column Editing | Rename the Displayed Node
        Table View Value Column Editing | Show the Navigation Menu
    The Table View Value Column Navigation Pop-Up Menu
        Table View Value Column Navigation | Visit Node in Table
        Table View Value Column Navigation | Add Node to Visual Graph
        Table View Value Column Navigation | Visit Node and Add to Visual Graph
        Table View Value Column Navigation | Show Reifying Triples in Table
        Table View Value Column Navigation | Copy URI to Clipboard
        Table View Value Column Navigation | Copy Triple ID to Clipboard
        Table View Value Column Navigation | Invoke Web Browser or Program
        Table View Value Column Navigation | Go Back
        Table View Value Column Navigation | Go Forward
        Table View Value Column Navigation | Refresh Table
        Table View Value Column Navigation | Scroll Down Most of a Page
        Table View Value Column Navigation | Scroll Up Most of a Page
    The Table View Property Column Pop-Up Menu
        Table View Property Column | Collapse or Expand Property Values
        Table View Property Column | Add Triples of Predicate to Graph View
        Table View Property Column | Toggle Current Predicate
        Table View Property Column | Copy URI to Clipboard
        Table View Property Column | Go Back
        Table View Property Column | Go Forward
        Table View Property Column | Rename the Predicate
        Table View Property Column | Refresh Table
The Outline View
    The Outline View Editing Pop-Up Menu
        Outline View Editing | Enter a Different Node
        Outline View Editing | Select a Different Node
        Outline View Editing | Enter a Typed Literal
        Outline View Editing | Rename the Node
        Outline View Editing | Reverse Triple Direction
        Outline View Editing | Create Item for a New Triple
        Outline View Editing | Create Sibling for Same Predicate
        Outline View Editing | Create Child for Same Predicate
        Outline View Editing | Delete the Triple
        Outline View Editing | Shift Downward
        Outline View Editing | Shift Upward
        Outline View Editing | Shift Downward to Next Parent
        Outline View Editing | Shift Upward to Previous Parent
        Outline View Editing | Shift Rightward
        Outline View Editing | Shift Leftward
        Outline View Editing | Show the Navigation Menu
        Drag and Drop in the Outline View
    The Outline View Navigation Pop-Up Menu
        Outline View Navigation | Move Down to Next Node
        Outline View Navigation | Move Up to Previous Node
        Outline View Navigation | Leap to Parent
        Outline View Navigation | Move Down to Next Sibling
        Outline View Navigation | Move Up to Previous Sibling
        Outline View Navigation | Display Linked Nodes for the Current Predicates
        Outline View Navigation | Hide Children (or jump to parent)
        Outline View Navigation | Display a Linked Node from Menus
        Outline View Navigation | Display a Linked Node from a Tree
        Outline View Navigation | Add to Graph View
        Outline View Navigation | Display in Table View
        Outline View Navigation | Copy to Top Level
        Outline View Navigation | Move to Top Level
        Outline View Navigation | Copy URI to Clipboard
        Outline View Navigation | Copy Triple ID to Clipboard
        Outline View Navigation | Invoke Web Browser or Program
        Outline View Navigation | Scroll Down Half a Page
        Outline View Navigation | Scroll Up Half a Page
    Building a Hierarchy from Scratch in the Outline View
The Query View
        Mouse Clicks and Keyboard Shortcuts in the Query View
        Generating Visual Graphs from Query Results
The Graphical Query View
    The Graphical Query Background Pop-Up Menu
        Graphical Query Background | Add Variable Node
        Graphical Query Background | Add Non-Variable Node
        Graphical Query Background | Remove Nodes and/or Links
        Graphical Query Background | Add Regular Grouper
        Graphical Query Background | Add Union Grouper
        Graphical Query Background | Add Optional Grouper
        Graphical Query Background | Change Grouper Type
        Graphical Query Background | Remove Grouper
        Graphical Query Background | Tighten Up Groupers
        Graphical Query Background | Add Filter to Grouper
        Graphical Query Background | Add Top-Level Filter
        Graphical Query Background | Specify Variables to Select
        Graphical Query Background | Specify Variables to Order By
    The Graphical Query Variable Node Pop-Up Menu
        Graphical Query Variable Node | Add Predicate Link
        Graphical Query Variable Node | Add Predicate Variable Link
        Graphical Query Variable Node | Add Filter Link
        Graphical Query Variable Node | Specify Node Filter
        Graphical Query Variable Node | Add Node Filter
        Graphical Query Variable Node | Remove Node Filter
        Graphical Query Variable Node | Rename Node Variable
        Graphical Query Variable Node | Specify a Different Variable
        Graphical Query Variable Node | Reverse Order-By Direction
        Graphical Query Variable Node | Convert to Non-Variable
        Graphical Query Variable Node | Remove Node
    The Graphical Query Non-Variable Node Pop-Up Menu
        Graphical Query Non-Variable Node | Add Predicate Link
        Graphical Query Non-Variable Node | Add Predicate Variable Link
        Graphical Query Non-Variable Node | Add Filter Link
        Graphical Query Non-Variable Node | Select a Different Node
        Graphical Query Non-Variable Node | Convert to Variable Node
        Graphical Query Non-Variable Node | Convert to Variable with Types
        Graphical Query Non-Variable Node | Remove Node
    The Graphical Query Link Pop-Up Menu
        Graphical Query Link | Specify Predicate
        Graphical Query Link | Specify Predicate Variable
        Graphical Query Link | Specify Link Filter
        Graphical Query Link | Add Predicate
        Graphical Query Link | Add Predicate Variable
        Graphical Query Link | Rename Predicate Variable
        Graphical Query Link | Reverse Order-By Direction
        Graphical Query Link | Add Link Filter
        Graphical Query Link | Toggle Optional
        Graphical Query Link | Reverse Link Direction
        Graphical Query Link | Remove Link
    The Widgets on the Left Side of the Graphical Query View
        The SPARQL and Prolog Radio Buttons
        The Name Query Button and the Revisit Button
        The Show Text Query Button and the Run Query Button
        The Full Cardinality, REDUCED, and DISTINCT Radio Buttons
        The Limit and Offset Widgets
    Controlling the Order of the Generated Query Text
Building an Ad Hoc Federation from Multiple Stores and Endpoints
Reification Support in Gruff
        Browsing Reified Triples
        Creating Reified Triples
The Menu Bar Commands
    The File Menu
        File | New Triple-Store
        File | Open Triple-Store
        A Note About Session Ports and Firewalls
        Opening a Store with Command Line Arguments
        Specifying the Position and Size of Gruff with a Command Line Argument
        File | Close Triple-Store
        File | Connect to SPARQL Endpoint
        File | Commit
        File | Roll Back and Refresh
        File | Load Triples | Load N-Triples
        File | Load Triples | Load RDF / XML
        File | Load Triples | Load N-Quads
        File | Load Triples | Load Trix
        File | Load Triples | Load Turtle
        File | Extract Microformat/RDFa Data from Web Page
        File | Federate Recent Stores
        File | Index All Triples
        File | Apply RDFS++ Reasoner
        The File Menu's List of Recent Stores to Re-Open
        File | Save Layout State
        File | Load Layout State
        File | Save Table Object URI
        File | Load Table Object URI
        File | Save Query String
        File | Load Query String
        File | Save Graphical Query
        File | Load Graphical Query
        File | Save Layout as Pixmap
        File | Export Displayed Data As | N-Triples
        File | Export Displayed Data As | RDF/XML
        File | Export Displayed Data As | RDF-N3
        File | Export Displayed Data As | TriX
        File | Export Displayed Data As | Node URIs
        File | Clear and Uncache Everything
        File | Exit
    The View Menu
        View | Graph View
        View | Table View
        View | Outline View
        View | Query View
        View | Graphical Query View
        View | Graph View Panes | Show Legend
        View | Graph View Panes | Show Overview
        View | Graph View Panes | Pop Up Overview
        View | Graph View Panes | Retain Pop-Up Overview
        View | Invoke Web Browser or Program
        View | Add Selected Node to Outline
        View | Go Back
        View | Go Forward
        View | Copy
        View | Paste
        View | View Current Store in AGWebView
        View | Browse a Single Graph
        The View Menu's List of Recent States to Redisplay
    The Text Search Menu
        Text Search | Find and Display Nodes
        Text Search | Find and Display Triples
        Text Search | Select or Create a Text Index
        Text Search | Edit the Current Text Index
        Text Search | Add a Single Predicate
        Text Search | Text Search Timeout
        Text Search | Search the Current View
    The Display Menu
        Display | Display a Node by URI or Literal
        Display | Display a Node by Label
        Display | Display a Recently Selected Node
        Display | Display an Instance Node by Type
        Display | Display a Type Node by Type
        Display | Display an Instance Node by Class Hierarchy
        Display | Display a Class Node by Class Hierarchy
        Display | Display Some Sample Triples
        Display | Display Triples of One Graph
    The Link Menu
        Link | Display Linked Nodes for the Current Predicates
        Link | Display Only Linked Nodes for the Current Predicates
        Link | Fill In All Links for the Current Predicates
        Link | Triples to Include | Include Triples as Subject Only
        Link | Triples to Include | Include Triples as Object Only
        Link | Triples to Include | Include Triples as Either
        About Node Background Color for Unseen Links
        Link | Display Paths Between Two Nodes
        Link | Display Only Paths Between Two Nodes
        Link | Display a Linked Node from Menus
        Link | Display Linked Nodes from a Tree
    The Remove Menu
        Remove | Remove Selected Node
        Remove | Exclude Selected Node
        Remove | Remove Selected Link
        Remove | Remove All Nodes
        Remove | Eraser Mode
        Remove | Remove All Orphan Nodes
        Remove | Remove All Leaf Nodes
        Remove | Remove All Unhighlighted Nodes
    The Layout Menu
        Layout | Redo Layout from Scratch
        Layout | Update Layout Incrementally
        Layout | Update Layout Vigorously
        Layout | Update Layout Conservatively
        Layout | Abort the Layout or Command
        Layout | Make Canvas Larger
        Layout | Make Canvas Smaller
        Layout | Zoom Out
        Layout | Zoom In
        Layout | Zoom Out All the Way
        Layout | Zoom In All the Way
        Layout | Zoom In Around the Mouse
        Layout | Center the Graph
    The Select Menu
        Select | Toggle Pinning of the Selected Node
        Select | Remove All Node Pinning
        Select | Toggle Highlighting of the Selected Node or Link
        Select | Remove All Node and Link Highlighting
        Select | Copy Highlighted to Graphical Query View
        Select | Deselect the Selected Node and/or Link
        Select | Reselect Previous Node and Link
        Select | Rotate to Next Link Clockwise
        Select | Rotate to Next Link Counterclockwise
        Select | Leap Across Selected Link
    The Edit Menu
        Edit | Create Node by Type
        Edit | Edit Selected Node by Type
        Edit | Create a Triple by Linking Nodes
        Edit | Create a Triple Using Most Recent Predicate
        Edit | Reverse Triple of Selected Link
        Edit | Delete Triple of Selected Link or Node
        Edit | Undo
        Edit | Redo
        Edit | Confirm Triple Deletion
        Edit | Prompt for Commit on Exit
        Edit | Show Menus of Recent Namespaces
        Edit | Prompt for Label for New Blank Node
        Edit | Percent-Decode Characters for Editing
        Edit | Percent-Encode Non-ASCII After Editing
    The Global Options Menu
        Global Options | Status Bar Font
        Global Options | Widget Font
        Global Options | Node Label Predicates | Use Label Predicates for Node Labels
        Global Options | Node Label Predicates | Label Predicate Language
        Global Options | Node Label Predicates | Custom Predicates for Node Labels
        Global Options | Node Label Predicates | Custom Predicates for Node Comments
        Global Options | Node Label Predicates | Custom Predicates for Node Pixmaps
        Global Options | Node Label Predicates | Custom Predicates for Web Pages
        Global Options | Derived Node and Link Labels | Exclude Namespaces from Labels
        Global Options | Derived Node and Link Labels | Add Spaces to Labels
        Global Options | Derived Node and Link Labels | Collapse Contiguous Spaces in Labels
        Global Options | Derived Node and Link Labels | Capitalize First Word
        Global Options | Derived Node and Link Labels | Convert Percent Encoding in Labels
        Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass"
        Global Options | Namespace Abbreviations
        Global Options | Select Current Predicates
        Global Options | Use a Recent Set of Current Predicates
        Global Options | Maximum Choices When Selecting a Subset
        Global Options | General Triple-Fetching Limit
        Global Options | Timeouts | Finding All Types Timeout
        Global Options | Timeouts | Finding All Predicates Timeout
        Global Options | Timeouts | Finding All Graphs Timeout
        Global Options | Timeouts | Bulk Property-Fetching Timeout
        Global Options | Timeouts | Endpoint-Testing Timeout
        Global Options | Timeouts | General Triple-Fetching Timeout
        Global Options | Timeouts | Query Timeout
        Global Options | Timeouts | Text Search Timeout
        Global Options | Timeouts | Path-Finding Timeout
        Global Options | SPARQL Endpoints | Query Results Limit
        Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels
        Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color
        Global Options | SPARQL Endpoints | Maximum Sample Triples to Display
        Global Options | Pop-Up Menus | Maximum Menu String Length
        Global Options | Pop-Up Menus | Show Full URIs in Pop-Up Menus
        Global Options | Pop-Up Menus | Case-Sensitive Sorting for Menus
        Global Options | Communications | Start HTTP Server
        Global Options | Communications | Use Session Ports
        Global Options | Communications | Use Direct Access When Possible
        Global Options | Communications | HTTP Proxy
        Global Options | Communications | Use any23.org for RDFa
        Global Options | Communications | Ignored RDFa Relationships
        Global Options | Miscellaneous | Warm Up the Store
        Global Options | Miscellaneous | Confirm Exit
        Global Options | Miscellaneous | Treat Literals as Objects
        Global Options | Miscellaneous | Confirm Closing Stores
        Global Options | Miscellaneous | Display Graph-Part Reification
        Global Options | Miscellaneous | Merge Retained Triples
        Global Options | Miscellaneous | Minimum Triples for Individual Property Lookup
        Global Options | Miscellaneous | Reasoner Enables Restriction Reasoning
        Global Options | Miscellaneous | External Format for Loading Triples
        Global Options | Miscellaneous | Auto Font Switching on Text Entry
        Global Options | Miscellaneous | Use Web Browser for All Documents
        Global Options | Miscellaneous | Document Base Folder
        Global Options | Revert to Default Options
        Global Options | Save All Options
    The Query Options Menu
        Query Options | Query String Font
        Query Options | Query Timeout
        Query Options | Query Results Limit
        Query Options | Include More Triples in Visual Graphs
        Query Options | Exclude Orphans from Visual Graphs
        Query Options | Percent-Encode Non-ASCII in Queries
        Query Options | Query Logging Enabled
        Query Options | Query Logging File
        Query Options | New Log File for Each Session
        Query Options | Show Current Log File Now
        Query Options | Query Text Report Show Full URIs
        Query Options | Query Text Report One Line per Value
        Query Options | CSV File Include Full URIs
        Query Options | CSV File Include Column Headers
    The Table Options Menu
        Table Options | Table Property Name Font
        Table Options | Table Property Value Font
        Table Options | Show Full URIs in Tables
        Table Options | Show Multiple Property Values
        Table Options | Sticky Multiple Property Values
        Table Options | Show Multiple Text Lines
        Table Options | Display Literals of All Languages
        Table Options | Display Links to Reifying Triples
        Table Options | Maximum Triples Per Predicate in Table
        Table Options | Maximum String Length in Table
        Table Options | Table Color One
        Table Options | Table Color Two
        Table Options | Table Cell Vertical Padding
    The Outline Options Menu
        Outline Options | Outline Font
        Outline Options | Show Full URIs in Outline
        Outline Options | Show Comments When Hovering
        Outline Options | Wrap Text When Hovering
        Outline Options | Hovering Delay
        Outline Options | Maximum Width for Wrapped Text
        Outline Options | Indicate Which Items are Openable
        Outline Options | Create All Nodes as Blank Nodes
    The Visual Graph Options Menu
        Visual Graph Options | Node Labels | Node Label Font
        Visual Graph Options | Node Labels | Show Full URIs on Nodes
        Visual Graph Options | Node Labels | Maximum Node Label Length
        Visual Graph Options | Node Labels | Enforce Maximum Node Label Length
        Visual Graph Options | Node Labels | Absolute Maximum Node Label Length
        Visual Graph Options | Node Labels | Maximum Word Length in Node Boxes
        Visual Graph Options | Node Labels | Show Full Label When Selected
        Visual Graph Options | Node Labels | Show Full Label When Under Mouse
        Visual Graph Options | Link Labels | Draw Link Labels
        Visual Graph Options | Link Labels | Draw Graph Link Labels Horizontally
        Visual Graph Options | Link Labels | Draw Query Link Labels Horizontally
        Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse
        Visual Graph Options | Link Labels | Link Label Font
        Visual Graph Options | Link Labels | Use Line Color for Link Labels
        Visual Graph Options | Link Labels | Link Label Color
        Visual Graph Options | Link Labels | Link Label Box Color
        Visual Graph Options | Layout Options | Do Automatic Incremental Layouts
        Visual Graph Options | Layout Options | Animate Layouts
        Visual Graph Options | Layout Options | Maximum Nodes for Animation
        Visual Graph Options | Layout Options | Maximum Iterations for Full Layout
        Visual Graph Options | Layout Options | Maximum Iterations for Incremental Layout
        Visual Graph Options | Layout Options | Center After Full Layout
        Visual Graph Options | Layout Options | Center After Incremental Layout
        Visual Graph Options | Layout Options | Compress After Full Layout
        Visual Graph Options | Layout Options | Compress After Incremental Layout
        Visual Graph Options | Layout Options | Honor Layout Direction Constraints
        Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate
        Visual Graph Options | Layout Options | Clear Layout Direction for a Predicate
        Visual Graph Options | Layout Options | Canvas Resize Factor
        Visual Graph Options | Layout Options | Drag Scroll Zoom Factor
        Visual Graph Options | Layout Options | Mouse Wheel Zooms
        Visual Graph Options | Layout Options | Include Legend in Saved Pixmaps
        Visual Graph Options | Layout Options | Show Saved Layout Pixmaps
        Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout
        Visual Graph Options | Spring Layout Options | Spacing Factor
        Visual Graph Options | Spring Layout Options | Velocity Divisor
        Visual Graph Options | Spring Layout Options | Slowdown Exponent
        Visual Graph Options | Spring Layout Options | Grid Cell Size
        Visual Graph Options | Spring Layout Options | Reduce Nodes Overlapping Links
        Visual Graph Options | Spring Layout Options | Keep Nodes on Canvas
        Visual Graph Options | Constraint-Based Layout Options | Begin Full Layout at Random Positions
        Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal
        Visual Graph Options | Inclusion Options | Number of Total Links for Warning
        Visual Graph Options | Inclusion Options | Number of Total Links for Abort
        Visual Graph Options | Inclusion Options | Number of Links from One Node for Warning
        Visual Graph Options | Inclusion Options | Show 1 Level of Nodes on Display Only Linked Nodes
        Visual Graph Options | Inclusion Options | Show 2 Levels of Nodes on Display Only Linked Nodes
        Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display
        Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length
        Visual Graph Options | Finding Paths Between Nodes | Find Only Shortest Paths
        Visual Graph Options | Finding Paths Between Nodes | Path-Finding Timeout
        Visual Graph Options | Finding Paths Between Nodes | Number of Found Paths for Warning
        Visual Graph Options | Finding Paths Between Nodes | Maximum Paths to Display
        Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Left and Right
        Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Top and Bottom
        Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes Anywhere
        Visual Graph Options | Finding Paths Between Nodes | Path End Node Margin
        Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing
        Visual Graph Options | Node and Link Spacing | Minimum Link-to-Node Spacing
        Visual Graph Options | Node and Link Spacing | Node Label Margin
        Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy
        Visual Graph Options | Node and Link Spacing | Spacing Increment for Many Links
        Visual Graph Options | Node and Link Spacing | Add Spacing for Long Paths
        Visual Graph Options | Node and Link Spacing | Long Path Spacing Increment
        Visual Graph Options | Node and Link Spacing | Long Path Maximum Spacing
        Visual Graph Options | Node and Link Spacing | Limit Outward Stretching
        Visual Graph Options | Node and Link Spacing | Link Line Mousing Margin
        Visual Graph Options | Node and Link Flashing | Flash Legend Matches
        Visual Graph Options | Node and Link Flashing | Flash End Nodes of Found Paths
        Visual Graph Options | Node and Link Flashing | Flash Newly Added Nodes
        Visual Graph Options | Node and Link Flashing | Flash Selected Search Matches
        Visual Graph Options | Node and Link Flashing | Times to Flash
        Visual Graph Options | Node and Link Flashing | Flashing Time Interval
        Visual Graph Options | Node and Link Flashing | Flashing Node Color Delta
        Visual Graph Options | Tooltips | Show Node Tooltips
        Visual Graph Options | Tooltips | Show Link Tooltips
        Visual Graph Options | Tooltips | Tooltip Font
        Visual Graph Options | Tooltips | Tooltip Background Color
        Visual Graph Options | Tooltips | Node Tooltips Delay
        Visual Graph Options | Tooltips | Link Tooltips Delay
        Visual Graph Options | Antialiasing | Antialias Lines
        Visual Graph Options | Antialiasing | Antialias Text
        Visual Graph Options | Antialiasing | Suppress Antialiasing During Animation
        Visual Graph Options | Arrowheads | Arrowhead Length
        Visual Graph Options | Arrowheads | Arrowhead Width
        Visual Graph Options | Arrowheads | Draw Arrowtails
        Visual Graph Options | Color Gradients | Show Node Color Gradients
        Visual Graph Options | Color Gradients | Color Gradient Intensity
        Visual Graph Options | Color Gradients | Suppress Color Gradients During Animation
        Visual Graph Options | Color Nodes for Node Type
        Visual Graph Options | Color Nodes for Unseen Links
        Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color
        Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color
        Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color
        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 | Remove Color Mapping for Selected Node's Type
        Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate
        Visual Graph Options | Node and Link Color for Types | Specify Line Width for Selected Link's Predicate
        Visual Graph Options | Node and Link Color for Types | Specify Dashing for Selected Link's Predicate
        Visual Graph Options | Node and Link Color for Types | Suppress Link Line Styles
        Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Current Links
        Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Non-Current Links
        Visual Graph Options | Node Color for Unseen Links | Node Color for No Unseen Links
        Visual Graph Options | Window Background | Graph View Background Color
        Visual Graph Options | Window Background | Legend Background Color
        Visual Graph Options | Window Background | Background Pixmap
        Visual Graph Options | Window Background | Show Background Pixmap (if any)
        Visual Graph Options | Window Background | Stretch Background Pixmap
        Visual Graph Options | Window Background | Graphical Query View Background Color
        Visual Graph Options | Node Border Color
    The Help Menu
        Help | Show Documentation as HTML
        Help | Show Documentation as Plain Text
        Help | Use Web Browser for Menu Help
        Help | Show Warnings in Dialog
        Help | Quick Start
        Help | Show Quick Start on Startup
        Help | Example Store Demo
        Help | Animation Demo (Actors Store)
        Help | Display Store Info
        Help | About
Using Gruff Programmatically in a Lisp Application
        Requirements for Loading the Gruff FASL File
    Using the standard full browser or a plain graph layout pane
    Adjusting the size of the canvas for the layout
    Using the usual AllegroGraph functions to create or open a store
    The Programmatic Lisp API to Gruff
        display-triples
        display-upis
        display-upis-from-file
        find-and-display-paths
        display-paths
        display-linked-nodes
        display-store
        remove-node-of-upi
        remove-orphans
        remove-all-nodes
        current-predicates
        set-current-predicates
        highlight-node-by-upi
        remove-all-highlighting
        update-the-layout
        center-the-graph
        gruff-browser
        graph-node-pane
        save-layout
        load-layout
        save-layout-as-pixmap
        uncache-for-modified-triple-store
        uncache-for-new-triple-store
        gruff-options-path
        *selected-node*
        *selected-link*
        *suppressing-gruff-messages*
        *gruff-version*
    Lisp Functions for Modifying User Options Programmatically
        Data formats of the option accessor functions
The HTTP Interface to Gruff
        open-store (HTTP command)
        connect-to-endpoint (HTTP command)
        store-info (HTTP command)
        query (HTTP command)
        lay-out-triples (HTTP command)
        display-all-triples (HTTP command)
        update-layout (HTTP command)
        number-of-nodes (HTTP command)
        node-at-index (HTTP command)
        node-position (HTTP command)
        select-node (HTTP command)
        selected-node (HTTP command)
        pin (HTTP command)
        highlight (HTTP command)
        remove (HTTP command)
        current-predicates (HTTP command)
        display-linked-nodes (HTTP command)
        find-paths (HTTP command)
        option (HTTP command)
        Boolean Option Names
        Integer Option Names
        Float Option Names
        set-color-for-type (HTTP command)
        set-line-style-for-predicate (HTTP command)
        set-direction-for-predicate (HTTP command)
        save-layout (HTTP command)
        load-layout (HTTP command)
        save-layout-as-pixmap (HTTP command)
        set-canvas-size (HTTP command)
        center-the-visual-graph (HTTP command)
        display-node-in-table (HTTP command)


Introduction

Gruff 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.


Running Gruff

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.)


Getting Started

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

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.

Using the Various Gruff Views

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

  • The Graph View for viewing visual graphs of nodes connected by link lines. Typically you would begin in this view by using a command on The Display Menu to select a starter node, and then using commands on The Link Menu to display additional nodes that are linked with the starter node. Right-click a node, link line, or the background for a pop-up menu of commands from the menu bar that are applicable to the clicked object.
  • The Table View for listing and optionally editing the properties of nodes. You could begin in this view by using a command on The Display Menu to select an initial node to view, and then jump to related nodes via the usual hyperlinks. Right-click a property value for a pop-up menu of editing commands that are specific to the table view, or shift-right click for a pop-up menu of navigation commands.
  • The Outline View for viewing parts of a graph in an outline format. You could begin in this view by using a command on The Display Menu to select an initial node to view, and then "open" various nodes to reveal other nodes that are linked with them. This requires first using Global Options | Select Current Predicates to specify the predicates by which to find linked nodes. As with the table view, right-click for a menu of editing commands, or shift-right-click for a menu of navigation commands.
  • The Query View for editing and performing SPARQL and Prolog Queries. You could begin here by typing or pasting a query string, or loading one that you saved to a file in a previous Gruff session. You can then perform the query, then perhaps examine some nodes from the query results in the table view, or generate a visual graph from the results into the graph view.
  • The Graphical Query View for desiging queries as diagrams of nodes and links. You could begin here by starting a new query diagram from scratch, or loading a previouslay-saved diagram from a file and then editing it and performing it. Right-click the background (and objects later) for commands that are unique to this view.
  • Using Gruff Menus

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

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

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

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

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


    The Graph View

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

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

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

    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.


    Special Mouse Clicks in the Graph View

    In addition to the menu bar commands, there are some special mouse clicks in the graph view.

  • Left-click a node or link to select it. See the section on The Selected Node.
  • Left-click the background to deselect the selected node and/or link.
  • Double-left-click a node to display its properties in the table view.
  • Control-left-click a node as a shortcut for Select | Toggle Highlighting of the Selected Node or Link.
  • Control-left-click the background as a shortcut for Select | Remove All Node and Link Highlighting.
  • Shift-left-click a node as a shortcut for Select | Toggle Pinning of the Selected Node.
  • Shift-left-click the background as a shortcut for Select | Remove All Node Pinning.
  • Control-shift-left-click a node to invoke your preferred web browser program on the node's value string.

  • Using Current Predicates to Quickly Build a Graph

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

  • Use one of the commands on the Display menu to place a "starter node" into the visual graph.
  • Use Global Options | Select Current Predicates to select one or more predicates. This document often refers to this set of predicates as "the current predicates".
  • Click on a visible node to select it, and then use Link | Display Linked Nodes for the Current Predicates to add any nodes that are linked by the current predicates to the node that you clicked.
  • Repeat that last step any number of times. Note that the F key is the keyboard shortcut for Link | Display Linked Nodes for the Current Predicates, so you can build a graph quickly by repeatedly clicking on a node and then pressing the F key to show its linked nodes.
  • Here's a way to quickly build a graph that shows the circular paths (cycles) within a group of nodes: Using the above procedure, add the linked nodes of several or more already-displayed nodes, but interrupt the layout each time by pressing the spacebar (or Q or Escape) just after you press F to add each group of linked nodes. This allows you to quickly add many nodes without waiting to lay them out each time. For now, don't worry about lots of overlapping between the nodes and links. Then use Remove | Remove All Leaf Nodes a few times to remove all nodes that are not part of cycles among the displayed nodes. Then use Layout | Redo Layout from Scratch to show a layout of just the cycles for all of the nodes that you displayed.

  • Interrupting a Long-Running Layout

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

  • Press the Escape key or the Q key to interrupt the layout (those keys invoke Layout | Abort the Layout or Command), or press the spacebar to interrupt the layout and deselect the selected node if any (see Select | Deselect the Selected Node and/or Link). Then use the View | Go Back command to return to the previous good state, where you can choose a different operation that would add fewer nodes and/or links to the display. In particular, if Link | Display Linked Nodes for the Current Predicates adds too many nodes, then you can instead use Link | Display Linked Nodes from a Tree to choose an explicit subset of the nodes that the other command had tried to add by default. Or use View | Table View to select individual nodes to add from the table, and then toggle back to the graph view to see them.
  • Interrupt the layout as above, but then use Layout | Make Canvas Larger one or more times to increase the layout area by one or more notches. Then use Layout | Update Layout Incrementally to proceed with the current layout (or Layout | Redo Layout from Scratch to increase the likelihood of success).
  • Let the layout proceed if you have time to wait for possible success. If it fails after the maximum allowed number of iterations (see Visual Graph Options | Layout Options | Maximum Iterations for Full Layout), then the layout will stop anyway. There will be a status bar message about the layout failure, but it will likely be obvious due to a messy layout with links crossing behind unrelated nodes. At this time, using the Layout | Update Layout Incrementally command will proceed further with the current layout, and sometimes will still succeed eventually. This approach may be needed if you are trying to find the smallest canvas size into which the layout can fit, such as for publication.
  • Use commands on The Remove Menu to remove some nodes that are less of interest, and try the layout again.

  • The Selected Node

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

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

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


    Visual Indicators in the Graph View

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

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

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

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

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


    Displaying Images for Nodes

    If the 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 contains the "file:///" URI prefix or not. On Windows, the file must have a .bmp or .ico file type. On Linux and Mac, the file type may be either .png, .bmp, or .jpg.

    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.


    The Graph View Node Pop-Up Menu

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

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

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

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

    Graph View Node | Display a Linked Node from Menus

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

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

    Graph View Node | Display Linked Nodes from a Tree

    Lets you select a set of nodes from a tree 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 a Tree. See that command for more information.

    Graph View Node | Display Linked Nodes for the Current Predicates

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

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

    Graph View Node | Display Only Linked Nodes for the Current Predicates

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

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

    Graph View Node | Display Paths Between Two Nodes

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

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

    Graph View Node | Display Only Paths Between Two Nodes

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

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

    Graph View Node | Create a Triple by Linking Nodes

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

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

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

    Graph View Node | Create a Triple Using Most Recent Predicate

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

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

    Graph View Node | Delete a Triple from Store

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

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

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

    Graph View Node | Edit Node by Type

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

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

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

    Graph View Node | Select Preferred Type for Node Colors

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

    This command itself does not exist on the menu bar.

    Graph View Node | Copy Node URI to Clipboard

    Copies the URI of the selected node to the system clipboard.

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

    Graph View Node | Invoke Web Browser or Program

    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.

    Graph View Node | Highlight the Node

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

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

    Graph View Node | Pin the Node

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

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


    The Graph View Link Pop-Up Menu

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

    Graph View Link | Remove Link from Display

    Removes the link line from the display.

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

    Graph View Link | Delete Triple from Store

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

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

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

    Graph View Link | Reverse Triple Direction in Store

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

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

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

    Graph View Link | Drag to Replace Triple

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

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

    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.

    Graph View Link | Create a Reifying Triple

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

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

    Graph View Link | Display a Reifying Triple

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

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

    Graph View Link | Copy Predicate URI to Clipboard

    Copies the URI of the predicate of the triple that the link line represents to the 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.

    Graph View Link | Copy Triple ID to Clipboard

    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.

    Graph View Link | Highlight the Link

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

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


    The Graph View Background Pop-Up Menu

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

    Graph View Background | Redo Layout from Scratch

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

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

    Graph View Background | Update Layout Incrementally

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

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

    Graph View Background | Make Canvas Larger

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

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

    Graph View Background | Make Canvas Smaller

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

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

    Graph View Background | Go Back

    Returns to an earlier version of the visual graph.

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

    Graph View Background | Go Forward

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

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

    Graph View Background | Search the Current View

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

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

    Graph View Background | Remove All Nodes

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

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

    Graph View Background | Eraser Mode

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

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

    Graph View Background | Remove All Node and Link Highlighting

    Unhighlights all currently highlighted nodes, if any.

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

    Graph View Background | Remove All Node Pinning

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

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


    The Table View

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

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

    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.

    Special Colors in the Table View

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

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

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


    The Table View Value Column Editing Pop-Up Menu

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

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

    Table View Value Column Editing | Enter a Different Node

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

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

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

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

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

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

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

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

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

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

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

    Table View Value Column Editing | Select a Different Node

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

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

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

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

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

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

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

    Table View Value Column Editing | Enter a Typed Literal

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

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

    Table View Value Column Editing | Rename the Node

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

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

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

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

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

    Table View Value Column Editing | Reverse Triple Direction

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

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

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

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

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

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

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

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

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

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

    This command is just like Table View Value Column Editing | Create Row for a New Triple, except that you are not 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.

    Table View Value Column Editing | Delete the Triple

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

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

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

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

    Table View Value Column Editing | Undo

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

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

    Table View Value Column Editing | Redo

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

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

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

    Table View Value Column Editing | Edit Displayed Node by Type

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

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

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

    Table View Value Column Editing | Rename the Displayed Node

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

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

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

    Table View Value Column Editing | Show the Navigation Menu

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


    The Table View Value Column Navigation Pop-Up Menu

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

    Table View Value Column Navigation | Visit Node in Table

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

    Table View Value Column Navigation | Add Node to Visual Graph

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

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

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

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

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

    Table View Value Column Navigation | Show Reifying Triples in Table

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

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

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

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

    See Reification Support in Gruff.

    Table View Value Column Navigation | Copy URI to Clipboard

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

    Table View Value Column Navigation | Copy Triple ID to Clipboard

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

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

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

    Table View Value Column Navigation | Invoke Web Browser or Program

    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.

    Table View Value Column Navigation | Go Back

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

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

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

    Table View Value Column Navigation | Go Forward

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

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

    Table View Value Column Navigation | Refresh Table

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

  • If you toggle Table Options | Show Full URIs in Tables, Gruff does not change the height of rows so that you can easily see the corresponding versions of each row. But the text may require different numbers of text lines in the two views. In particular, a literal string that contains embedded newlines will occupy more text lines when that option is off than when it is on, since it will wrap at the newline characters, yet turning the option off will not resize the rows taller and so some text mey not be visible. Using this command will regenerate the table with all rows at the appropriate height for the current view.
  • If you have modified the store using techniques that Gruff is not aware of, or if Gruff does not catch all of its own cases, then the table view will not know to regenerate itself automatically, and so you can use this command to update it.
  • Table View Value Column Navigation | Scroll Down Most of a Page

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

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

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


    The Table View Property Column Pop-Up Menu

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

    Table View Property Column | Collapse or Expand Property Values

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

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

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

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

    Table View Property Column | Toggle Current Predicate

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

    Table View Property Column | Copy URI to Clipboard

    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.

    Table View Property Column | Go Back

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

    Table View Property Column | Go Forward

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

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

    Table View Property Column | Rename the Predicate

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

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

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

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

    Table View Property Column | Refresh Table

    See Table View Value Column Navigation | Refresh Table.


    The Outline View

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

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

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

    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.


    The Outline View Editing Pop-Up Menu

    Outline View Editing | Enter a Different Node

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

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

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

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

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

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

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

    Outline View Editing | Select a Different Node

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

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

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

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

    Outline View Editing | Enter a Typed Literal

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

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

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

    Outline View Editing | Rename the Node

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

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

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

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

    Outline View Editing | Reverse Triple Direction

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

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

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

    Outline View Editing | Create Item for a New Triple

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

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

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

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

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

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

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

    Outline View Editing | Create Sibling for Same Predicate

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

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

    Outline View Editing | Create Child for Same Predicate

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

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

    Outline View Editing | Delete the Triple

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

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

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

    Outline View Editing | Shift Downward

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

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

    Outline View Editing | Shift Upward

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

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

    Outline View Editing | Shift Downward to Next Parent

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

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

    Outline View Editing | Shift Upward to Previous Parent

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

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

    Outline View Editing | Shift Rightward

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

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

    Outline View Editing | Shift Leftward

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

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

    Outline View Editing | Show the Navigation Menu

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

    Drag and Drop in the Outline View

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

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

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

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


    The Outline View Navigation Pop-Up Menu

    Outline View Navigation | Move Down to Next Node

    Selects the node that is immediately beneath the currently selected node. (Normally you would want to use the keyboard shortcut (the J key or the down arrow key) rather than invoking the menu; the navigation menu is mostly a reminder of its keyboard shortcuts.)

    Outline View Navigation | Move Up to Previous Node

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

    Outline View Navigation | Leap to Parent

    Selects the parent item of the currently selected outline item.

    Outline View Navigation | Move Down to Next Sibling

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

    Outline View Navigation | Move Up to Previous Sibling

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

    Outline View Navigation | Display Linked Nodes for the Current Predicates

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

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

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

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

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

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

    Outline View Navigation | Display a Linked Node from Menus

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

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

    Outline View Navigation | Display a Linked Node from a Tree

    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 a Tree. See that command for more information.

    Outline View Navigation | Add to Graph View

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

    Outline View Navigation | Display in Table View

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

    Outline View Navigation | Copy to Top Level

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

    Outline View Navigation | Move to Top Level

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

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

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

    Outline View Navigation | Copy URI to Clipboard

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

    Outline View Navigation | Copy Triple ID to Clipboard

    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.

    Outline View Navigation | Invoke Web Browser or Program

    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.

    Outline View Navigation | Scroll Down Half a Page

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

    Outline View Navigation | Scroll Up Half a Page

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


    Building a Hierarchy from Scratch in the Outline View

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

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

  • After creating or opening a store, first use View | Outline View to show the outline view. If there is any content in the outline view, then use Remove | Remove All Nodes to clear the view.
  • Right-click the background and invoke the command Outline View Editing | Create Item for a New Triple. (That will be the only command on the pop-up menu when there is no content yet.)
  • A pop-up menu will appear, asking for the way that you'd like to specify a new node. Select "Enter a Node URI or Literal String". If a menu of suggested namespaces then appears, select the first choice "Other Namespace (or None)", because the namespace that we want to use is (probably) not in the list.
  • You will then be prompted to enter a string that names a node for the outline item to represent. When you see a flashing text cursor, enter the string "http://www.franz.com/simple#animal", and press the Enter key to accept that name. Do not include the double-quote characters, because that would create a literal, whereas we want to create a resource for that URI instead. This will intern a resource for a new node, but will not create any triples; a triple would be created only when the new outline item has a parent item to link with it.
  • The new node will appear simply as "Animal" in the outline item. To see the full URIs of all resources that are in the outline, use Outline Options | Show Full URIs in Outline. The 8 key (on the main part of the keyboard) is the keyboard shortcut for that menu bar command, so you could frequently press 8 to toggle between showing full URIs and showing more easily readable "pretty" labels. For now, press 8 as needed to show the shorter labels.
  • Now we are ready to create a triple by specifying a second new node, along with a predicate with which to link it to the first node. First right-click the new node for Animal to show the pop-up menu again. This is the outline view's editing menu, which will contain several commands now that there is an outline item to which commands can be applied. Most of the commands will conceptually "edit" a triple in some way, by deleting one triple and creating a replacement triple, though the commands in the second section simply create OR delete a triple.
  • From the pop-up menu, invoke the command Outline View Editing | Create Item for a New Triple. (This is the same command that we used before.)
  • A first pop-up menu for this command will ask whether you want to create a child or a sibling of the currently selected outline item. Select "Create Child Item". A new blank outline item will then appear just below the first item. It will be indented to the right of the first item to indicate that it is a "child" of the first item, which is the "parent" of the new item. This means that those two items represent a triple that links the nodes of the outline items. Note that the parent/child relationship pertains only to the way that the information is being displayed in the outline view, and does indicate the type of relationship that the two nodes have with each other in the triple store.
  • The next pop-up menu will ask for the "direction" that the triple between the new nodes should have. Select "New Node is Object of Triple with Parent" to indicate that the node of the child outline item will be the object of a triple that you are creating, and the node of the parent outline item will be the subject of the triple. (This may be a relatively tricky point that should become clear later.)
  • We now need to specify the predicate for the new triple. The first step is to specify the desired way to select a predicate, on the next pop-up menu that appears. It's problematic to choose from a large set of predicates, so this menu lets you select from one of various subsets of predicates. Select the choice "Common Predicates". The next pop-up menu will then list an arbitrary set of several often-used standard predicates. Choose "Narrower" from that list, which stands for skos:narrower (notice the full URI in the status bar as you highlight that menu choice). The word Narrower will then appear in the new outline item.
  • And finally it's time to specify the node for the new outline item, which will be linked to the node of the parent outline item by a new triple. As before, a pop-up menu will ask which way you'd like to specify the node. Select "Enter a Node URI or Literal String" as before.
  • This time when the menu of suggested namespace appears, it should include the choice "http://www.franz.com/simple#" that you typed in explicitly for the first node. Select that choice from the menu so that you don't need to type it in again.
  • This time when you are prompted to enter the text, the namespace that you selected will appear as a starter string, with the text cursor at the end of it. At this time, simply type the string "goat" at the end of the namespace string and press Enter.
  • Now that the new child outline item has been fully specified, a triple is created that links the item's node with the node of the parent item. The parent item says "Animal" and the child item says "Narrower Goat", which means that the triple "Animal Narrower Goat" exists in the store. Press the 8 key as usual to see all of the full URIs of the triple, and then again to return to the shorter labels.
  • That general command for creating a new triple from scratch involved quite a few steps. But there are a couple of shortcut commands for the common case where you are creating multiple triples that use the same predicate. To try this out, right-click the Goat item, and this time invoke the command Outline View Editing | Create Sibling for Same Predicate. This will skip the menus for specifying the predicate and the "direction" of the new triple, and instead copy that information from the triple that links the nodes of the selected outline item and its parent item. As before, select the choice to enter a URI for the new node, and then the franz.com/simple namespace, and this time enter "hamster" as the name of the new node.
  • Another way to add items more quickly is to use keyboard shortcuts. The keystrokes that are shown to the right of each command in the pop-up menu are ones that you can use without showing the menu at all. Right-click again and notice that the shortcut for "Create Sibling for Same Predicate" is the N key. Also notice the "access keys" that are printed along the left side of the menu. These are keys that you can press to select a menu command if you did show the menu. (You can also press the M key to initially show the editing menu in any view, or Shift-M to show the navigation menu.) Press Escape to dismiss the pop-up menu.
  • To add another sibling item by using keyboard shortcuts, first make sure that the Hamster item is selected, and press the N key (without using the shift key), which is the shortcut for adding a sibling item. Then press the E key to select the menu choice for enterring a URI for the new node, and finally press whatever letter key is at the left side of the next menu for the franz.com/simple namespace. This time enter "fish" for the name of the new node.
  • You may have noticed that so far we are creating a subclass tree, and wondered why we're not using the rdfs:subClassOf predicate. In this tutorial, that's simply to avoid any confusion from the fact that subClassOf is defined "backwards" with respect to a subclass outline. If you use that predicate and want to add a new subclass that's shown as a child outline item of its superclass, then you'll need to select "New Node is Subject of the Triple with Parent" when prompted for the triple direction, since the predicate is subClassOf rather than "subClass" or "hasSubClass". Also, by default the outline item will awkwardly say "is Sub Class Of of", to follow the general rule that's not so clear for this particular predicate. As a special exception for subClassOf, you can turn on Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass", which will cause the outline item to say "Subclass". But for this tutorial we will use the predicate skos:narrower, which is more intuitive for an outline.
  • You may also notice at this point that our tree is not quite right, because goats and hamsters are kinds of mammals, and mammal should be a sibling of fish in the tree. This is no problem, because we can insert a node for mammal and then shift goat and hamster under it. First select the Animal item, and press the C key to invoke the general command from the editing pop-up menu for creating an outline item. Add a child item as before, naming this one "mammal".
  • The outline items from top to bottom should now be Animal, Mammal, Goat, Hamster, and Fish. We want to select Goat and shift it under Mammal, but first let's learn how to select Goat with the keyboard. Shift-right-click any item (or type Shift-M) to see the outline view's navigation menu. This is a separate pop-up menu from the editing menu that we have used so far. Some of the commands on the navigation menu are rather awkward to use from the menu itself, so just notice toward the right side of the menu that J is the keyboard shortcut for Outline View Navigation | Move Down to Next Node, and K is the shortcut to move up to the previous node. Press Escape to cancel the menu, and then press the J and K keys as needed to select Goat.
  • Now we're ready to make Goat be a kind of Mammal rather than directly a kind of Animal. With the Goat item selected, press the M key to show the editing pop-up menu. Toward the bottom of the menu, note that the keyboard shortcut for Outline View Editing | Shift Rightward is Control->. But since we've shown the menu, press R to invoke that command from the menu. You will see Goat shift to the right so that it is now indented under Mammal. Internally, this deletes the triple Animal Narrower Goat and creates the triple Mammal Narrower Goat. (Notice the status bar for a message about the triple creation and deletion.)
  • In the general case, you will likely need to first use Outline View Editing | Shift Downward and/or Shift Upward to position the moving item just below the item that you want to shift it underneath.
  • Next press J to select Hamster, and type Control-> to similarly shift it under Mammal. (Type Control-> by holding down the Control key and the pressing the period key, whose shifted character (at least on US English keyboards) is the greater-than character.) This shifting behavior is unique to the outline view, and makes it easy to intuitively edit a hierarchy of linked nodes such as an ontology.
  • There are many more commands on both of the pop-up menus and the menu bar in the outline view that we have not covered in this tutorial. Please explore them, and remember that you can highlight any menu command and press F1 to see the help for that particular command.
  • A good approach for creating an entire store in Gruff is to use the outline view to build hierarchies or ontologies such as subclasses and instances, and then use the table view to add and edit properties of individual instances. See the table view's right-click editing menu for commands for editing properties. And if nodes that have the same type often have some of the same properties, then it may be especially handy to use Edit | Edit Selected Node by Type directly from the outline view, to edit the properties of the selected instance node.

  • The Query View

    The query view displays a view where you can do a SPARQL or Prolog query and see the results in a table. Nodes in the results table can then be viewed in detail in the table view, or added as nodes to the graph view.

    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 string 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.

    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.

    In SPARQL mode, only SELECT and DESCRIBE queries are supported at this time, 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.

    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.

    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 string widget to make it easy to begin typing in a new query or pasting a copied query string over the old string. This button will also move the keyboard focus to the query string widget. So typing its keyboard shortcut (alt-A) is a quick way to set things up for entering a new query string.

    See View | Copy and View | Paste for a way to insert URIs into the query string 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 string 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 strings sometimes contain URIs or literals that contain non-ASCII characters, then see Query Options | Percent-Encode Non-ASCII in Queries.

    Mouse Clicks and Keyboard Shortcuts in the Query View

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

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

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

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

    There are also some handy keystrokes in the query results table, once you have given the table the keyboard focus by tabbing to it if needed. The TAB moves between the three tables and the query string 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 string. 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 string 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 string for a URI that does not appear there.

    In the query string 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 string 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 string 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 string widget and then use any pull-down menu keyboard shortcuts.

    Generating Visual Graphs from Query Results

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

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

    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

    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.


    The Graphical Query Background Pop-Up Menu

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

    Graphical Query Background | Add Variable Node

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

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

    Graphical Query Background | Add Non-Variable Node

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

    Graphical Query Background | Remove Nodes and/or Links

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

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

    Graphical Query Background | Add Regular Grouper

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

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

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

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

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

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

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

    Graphical Query Background | Add Union Grouper

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

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

    Graphical Query Background | Add Optional Grouper

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

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

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

    Graphical Query Background | Change Grouper Type

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

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

    Graphical Query Background | Remove Grouper

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

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

    Graphical Query Background | Tighten Up Groupers

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

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

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

    Graphical Query Background | Add Filter to Grouper

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

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

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

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

    Graphical Query Background | Add Top-Level Filter

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

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

    While you're editing the text of a filter, a special feature is invoked by typing control-V to do a paste. Rather than simply pasting whatever is on the system clipboard as usual, a pop-up menu first appears with choices on what to paste. The first choice in this menu is "Clipboard String", 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.

    Graphical Query Background | Specify Variables to Select

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

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

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

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

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

    Graphical Query Background | Specify Variables to Order By

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

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


    The Graphical Query Variable Node Pop-Up Menu

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

    Graphical Query Variable Node | Add Predicate Link

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

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

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

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

    Graphical Query Variable Node | Add Predicate Variable Link

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

    Graphical Query Variable Node | Add Filter Link

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

    Graphical Query Variable Node | Specify Node Filter

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

    This command will replace any filters that were on the node previously. To add an additional filter instead, use Graphical Query Variable Node | Add Node Filter.

    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.

    Graphical Query Variable Node | Add Node Filter

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

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

    Graphical Query Variable Node | Remove Node Filter

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

    Graphical Query Variable Node | Rename Node Variable

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

    Graphical Query Variable Node | Specify a Different Variable

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

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

    Graphical Query Variable Node | Reverse Order-By Direction

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

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

    Graphical Query Variable Node | Convert to Non-Variable

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

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

    Graphical Query Variable Node | Remove Node

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


    The Graphical Query Non-Variable Node Pop-Up Menu

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

    Graphical Query Non-Variable Node | Add Predicate Link

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

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

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

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

    Graphical Query Non-Variable Node | Add Predicate Variable Link

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

    Graphical Query Non-Variable Node | Add Filter Link

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

    Graphical Query Non-Variable Node | Select a Different Node

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

    Graphical Query Non-Variable Node | Convert to Variable Node

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

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

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

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

    Graphical Query Non-Variable Node | Remove Node

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


    The Graphical Query Link Pop-Up Menu

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

    Graphical Query Link | Specify Predicate

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

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

  • Recently Selected Predicates - This option will list the predicates that you have most recently explicitly selected in some way, such as by clicking on a link line or a predicate table cell or by doing a string search. This allows you to re-select a predicate that you've recently used in the same query or in a recent query, or to copy a predicate from some other Gruff view. The list for each store is remembered across Gruff sessions, allowing you to specify a predicate that you used in a recent Gruff session. This option will not appear if you have not yet selected any predicates.
  • Common Predicates - This option simply lists several standard predicates that are commonly used in RDF stores, such as rdf:type, rdfs:subClassOf, rdfs:label, and rdfs:comment.
  • Predicates of End Node - This option will appear only if one of the two nodes that are connected by the link represents an actual node that's in the store rather than a node variable. When selected, a menu will appear that includes all of the predicates of triples where that end node is either the subject or the object, depending on the direction of the link line. (The arrow on one end of a link line points to the object node, and the other node is the subject node.)
  • Referenced Predicates - This option will appear only if you have already asked Gruff to display any nodes from the current store in any of Gruff's views. The "referenced predicates" are then the predicates of all of the triples of those nodes. This may be the predicate subset that is most often useful when both end nodes are variable nodes (and therefore Predicates of End Node is not applicable).
  • Current Predicates - This option will appear only if you have used Global Options | Select Current Predicates on the menu bar. The predicates that you selected there will then be offered here.
  • All Predicates - This option uses a series of menus for selecting any predicate that's in the store. The first time the menu of all predicates is requested, there will be a delay as Gruff searches for and caches all of the predicates. See Global Options | Timeouts | Finding All Predicates Timeout.
  • Typed URI or Literal - This option lets you type or paste in the URI of the desired predicate. A namespace abbreviation may be used in the URI if an applicable one is defined; see Global Options | Namespace Abbreviations. One way to obtain a predicate URI for pasting, for example, is to go to the table view, click on a predicate in the left column to select it, and then use View | Copy to place it on the clipboard.
  • Predicate On Clipbaord - This option uses the string that's on the system-wide clipboard, if it is a URI for a predicate that's in the store. You can copy a predicate to the clipboard, for example, by selecting a link line and using View | Copy (though if the link line represents multiple predicates then it will always copy the first one rather than letting you choose). Or you could copy the URI string from another application.
  • Graphical Query Link | Specify Predicate Variable

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

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

    Graphical Query Link | Specify Link Filter

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

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

    Graphical Query Link | Add Predicate

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

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

    Graphical Query Link | Add Predicate Variable

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

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

    Graphical Query Link | Rename Predicate Variable

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

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

    Graphical Query Link | Reverse Order-By Direction

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

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

    Graphical Query Link | Add Link Filter

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

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

    Graphical Query Link | Toggle Optional

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

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

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

    Graphical Query Link | Reverse Link Direction

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

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

    Graphical Query Link | Remove Link

    Removes the link line from the graphical query.


    The Widgets on the Left Side of the Graphical Query View

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

    The SPARQL and Prolog Radio Buttons

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

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

    The Name Query Button and the Revisit Button

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

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

    The Show Text Query Button and the Run Query Button

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

    The Full Cardinality, REDUCED, and DISTINCT Radio Buttons

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

    The Limit and Offset Widgets

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

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


    Controlling the Order of the Generated Query Text

    You can partially control the order of the generated query text via the positioning of nodes and groupers in the graphical query. 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.


    Building an Ad Hoc Federation from Multiple Stores and Endpoints

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

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

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

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

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

    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 | Federate Recent Stores, or to select multiple stores in the same catalog when using File | Open Triple-Store. That will federate ALL of the triples from the multiple stores together, and then you can browse all of them as a single AG store, including doing user queries over the whole federation.


    Reification Support in Gruff

    Gruff has some functionality that is specific to viewing and editing reified triples. This support applies mainly to reifications that are made using triple-id reification, as our documentation suggests, or a similar style that uses the graph part rather than the triple-id part, though RDF-style reification should be handled fine by Gruff as well. Multiple levels of reification are handled.

    Browsing Reified Triples

    There are a few features for browsing any reified triples that exist in a store:

  • If a node's value is a triple-id typed literal, then it's label will include the short labels of the three parts of the triple. This label will appear in all of the usual places such as in a table row or title, or in a node box in the graph view. This is also done for nodes of type rdf:Statement when RDF-style reification was used.
  • When a triple-id node is displayed in the table view, the table will include three special rows at the top for the subject, predicate, and object of the triple that the triple-id corresponds to, though the store does not contain actual triples for those table rows. Clicking on one of those objects in the righthand column displays the page for that object as usual. This allows browsing directly from a triple that reifies another one to the parts of the triple that it reifies. (For an rdf:Statement object in RDF-style reification, adding these rows is simply the usual behavior because actual triples will normally exist for the rdf:subject, rdf:predicate, and rdf:object properties of an rdf:Statement node.)
  • These special three rows are also displayed for a node that is used as the graph part of a single triple in the store, though only when Global Options | Miscellaneous | Display Graph-Part Reification is enabled. In that case the three rows will show the parts of that single triple. This may be useful if you are using graph-part reification.

  • If there are reifing triples for the triple of a table row, and they use triple-id reification, they can be seen by using Table View Value Column Navigation | Show Reifying Triples in Table, or more simply by left-clicking the reification icon that will appear to the left of the vertical divider between the two table columns. Those icons will appear only if the option Table View Value Column Navigation | Show Reifying Triples in Table is enabled.
  • 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.

  • In the graph view, a triple ID node is displayed by default as a (typically large) node whose label includes the triple ID number as well as the labels of the three parts of the triple that that triple ID node reifies. But if the triple ID and both of the nodes of the reified triple are present in the visual graph simultaneously, then the display will automatically be updated to redirect the link line that's connected to the reifying subject node so that it no longer connects to the triple ID node and instead connects to the middle of the link line for the reified triple. This is a more intuitive representation of the reification. If nothing is then left connected to the triple ID node in the visual graph (that is, it is now an orphan node), then it will automatically be removed from the display. An exception is that if the reifying subject node is also the subject or object node of the reified triple, then this conversion is not done because the reifying link line would overlap the reified link line, and so the triple ID node is left on the display instead.
  • In the graph view, if there are any reifying triples for a triple of a link line, and any of those are not already displayed, then a command will be included on the right-click pop-up menu for the link line that allows you to select and display one of the reifying triples. This is also provided when the triple is the only one in its graph, for similar graph-part reification. See Graph View Link | Display a Reifying Triple.
  • In the graph view, if you right-click a triple ID node, then a command will be included that allows you to display the nodes and link of the triple that it represents. See Graph View Node | Display the Nodes and Link of This Triple. This is also provided when the node is used as the graph part of a single triple in the store, but only when Global Options | Miscellaneous | Display Graph-Part Reification is enabled.
  • Creating Reified Triples

    A reifying triple may be created in the table view by using Table View Value Column Navigation | Copy Triple ID to Clipboard. That command is on the table view's pop-up navigation menu (shift-right-click). 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 Nodes, and then clicking on a link to reify the triple that that link represents.


    The Menu Bar Commands

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

    To find the documentation for a particular menu command, show the menu and highlight the desired command, and then press the F1 key. (You can highlight a menu command by moving the mouse over it or by using the up and down arrow keys.) 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.


    The File Menu

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

    File | New Triple-Store

    Creates an AllegroGraph 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.

    File | Open Triple-Store

    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.

    On AllegroGraph 4, 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.

    On AllegroGraph 3, if you are opening a store on the local machine 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 | 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.

    A Note About Session Ports and Firewalls

    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 AllegroServe 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.

    Opening a Store with Command Line Arguments

    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 on AllegroGraph 4, or the path of the store's directory on AllegroGraph 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. If Gruff was built on AllegroGraph 4 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 (when Gruff is built on AllegroGraph 4).

    gruff --read --host fred -u alice my-store 
    

    Specifying the Position and Size of Gruff with a Command Line Argument

    --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 
    

    File | Close Triple-Store

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

    File | Connect to SPARQL Endpoint

    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 string 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.

    File | Commit

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

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

    This menu command does not exist in AllegroGraph version 3.

    File | Roll Back and Refresh

    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 | Clear and Uncache Everything.

    This menu command does not exist in AllegroGraph version 3.

    File | Load Triples | Load N-Triples

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

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

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

    In AllegroGraph 3, this command always indexes new triples after the load, and in AllegroGraph 4 and beyond it always does a commit.

    If the N-Triples file contains non-ASCII characters, see Global Options | Miscellaneous | External Format for Loading Triples.

    File | Load Triples | Load RDF / XML

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

    File | Load Triples | Load N-Quads

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

    File | Load Triples | Load Trix

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

    File | Load Triples | Load Turtle

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

    File | Extract Microformat/RDFa Data from Web Page

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

    If Global Options | Miscellaneous | 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.

    File | Federate Recent Stores

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

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

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

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

    If all of the stores to federate are in the same catalog (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.

    File | Index All Triples

    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.

    File | Apply RDFS++ Reasoner

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

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

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

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

    File | Save Layout State

    This command appears only in the graph view.

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

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

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

    File | Load Layout State

    This command appears only in the graph view.

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

    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.

    File | Save Table Object URI

    This command appears only in the table view.

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

    File | Load Table Object URI

    This command appears only in the table view.

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

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

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

    File | Save Query String

    This command appears only in the query view.

    Saves the string that currently appears in the query string 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 String to reload the query string into the query string widget. By default, the saved file's extension will be "query", though this is not required.

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

    File | Load Query String

    This command appears only in the query view.

    Loads a query string that was saved at some earlier time with File | Save Query String. The query string 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 string 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 string than using this command to select it with the file dialog.

    File | Save Graphical Query

    This command appears only in the graphical query view.

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

    File | Load Graphical Query

    This command appears only in the graphical query view.

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

    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.

    File | Save Layout as Pixmap

    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.

    This command is present only in the graph view.

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

    File | Export Displayed Data As | N-Triples

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

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

    Commands for exporting triples do nothing in the query view because query results are not triples. You can use File | Export Displayed Data As | Node URIs in the query view, though.

    File | Export Displayed Data As | RDF/XML

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

    File | Export Displayed Data As | RDF-N3

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

    File | Export Displayed Data As | TriX

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

    File | Export Displayed Data As | Node URIs

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

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

    File | Clear and Uncache Everything

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

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

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

    File | Exit

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


    The View Menu

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

    View | Graph View

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

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

    View | Table View

    Displays a table of all of the properties of a particular node (meaning all of its triples). If there is a selected node in the view that you are in when you invoke this command, then a new table for that node will be generated; otherwise the table view is simply shown in its current state. If you accidentally generate a new table when you intended to simply switch back to the table view to continue viewing the node that had been displayed there, then use View | Go Back to return to the previous displayed node.

    You can browse to linked nodes in the table view in the usual hyperlink way by clicking on nodes in the righthand column. You can also edit the triples of the displayed node, using commands on the right-click pop-up menu.

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

    View | Outline View

    Displays a set of linked nodes as an indented outline.

    This command simply shows the outline view in its current state. To also create a new top-level outline item for the node that's selected in the view that you are switching from, use View | Add Selected Node to Outline instead.

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

    View | Query View

    Displays a view where you can do a SPARQL or Prolog query and see the results in a table. Nodes in the results table can then be viewed in detail in the table view, or added as nodes to the graph view.

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

    View | Graphical Query View

    Displays a view where you can construct a query "visually" by arranging nodes and links into a diagram.

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

    View | Graph View Panes | Show Legend

    Toggles whether a legend pane is shown in the graph view. The legend displays the meaning of each predicate line style and each node type background color that is currently represented in the graph layout. The predicate line styles are shown at the top, with the name of each predicate shown just above a sample line that shows the line color and dashing style that's used for that predicate. The node type colors are shown below the line styles, with a sample node drawn for each node type with the name of the type displayed in the sample node that shows the background color for that type.

    If Visual Graph Options | Node and Link Flashing | Flash Legend Matches is enabled, then clicking an item in the legend will flash matching nodes or links in the graph layout to point them out. Pressing the spacebar when the legend pane has the keyboard focus will flash the matching nodes or links of the legend item that's already selected, if any. The matching nodes or links will also flash in the overview pane, which indicates where you need to scroll to in order to see the matches in the main graph pane (for example, you can simply click in the overview pane where it is flashing to scroll the matching nodes or links into view).

    You can right-click an item in the legend to get a pop-up menu with a few commands for changing the link line style or node type background color for that legend item. These commands invoke particular options on the Visual Graph Options menu, which can alternately be used after left-clicking a legend item to select it. The menu for a node type also includes a command to display the properties of that type in the table view; you can also do this by double-clicking the item. Both menus include an item for copying the URI of that item to the clipboard; the URI could then be pasted into a query or into the node pane.

    One command on the legend right-click menu that's not also available on the menu bar is "Remove Matching Link Lines (or Nodes)". This command will remove from the visual graph any nodes or link lines that match the selected legend item. These are the same nodes or links that flash when that legend item is selected. If Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal is active, then any remaining orphans will also be removed; this may be useful, for example, to remove all nodes for label properties after generating a visual graph for a DESCRIBE query, simply by right-clicking the legend item for the label property and selecting "Remove Matching Link Lines".

    The width of the legend pane can be modified by dragging the thick border between the legend and the graph layout.

    The up and down arrow keys can be used to select legend items when the legend pane has been given the keyboard focus by clicking on it. The Escape key will de-select any selected legend item (as will clicking the legend background).

    The TAB key will shift the keyboard focus between the legend pane and the node pane. A blue rectangle will be drawn just inside the legend pane's border when it has the keyboard focus.

    The node types in the legend include ones whose background color you have set explicitly, along with others whose colors were chosen automatically. Colors are chosen automatically when there are displayed nodes that have no types for which you have explicitly set the color. Displayed nodes may have other types as well, and you can't set the colors for those types in the legend if they are not displayed there already. Instead, you would need to select the node in the graph layout and then use Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type. When you right-click a node type item in the legend, the pop-up menu will include a command for removing its mapping to a color if and only if you have explicitly specified a color for that type.

    The Graph View Panes child menu is present only in the graph view.

    View | Graph View Panes | Show Overview

    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.

    View | Graph View Panes | Pop Up Overview

    Displays a "floating" overview window, which is a top-level window that is owned by the main Gruff window. This window can be positioned and sized arbitrarily, and will reappear wherever you last left it (during the current Gruff session).

    By default, this window will disappear as soon as you click in its interior to scroll. But if View | 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.

    View | Graph View Panes | Retain Pop-Up Overview

    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.

    View | Invoke Web Browser or Program

    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.

    View | Add Selected Node to Outline

    Creates a top-level outline item in the outline view for the node that's currently selected in whichever view you are in, and then switches over to the outline view to allow you to browse to linked nodes in outline format. If there is no selected node when you issue this command, then it does nothing.

    View | Go Back

    Returns to the previous state of the display. You may apply this command multiple times to return to earlier states up to a certain maximum.

    In the graph view, this command returns to the previous state of the layout. In the table view it returns to the previously displayed node. In the query view it returns to the previous query. In the graphical query view it returns to the previous state of the query diagram.

    In the graph view, this command allows you to freely experiment with adding nodes to the visual graph even when the new nodes turn out to be uninteresting or where too many nodes make the layout unwieldy. If that happens, you can use this command to return to the most recent desirable state.

    View | Go Forward

    Returns to the next state from which you returned to the current state with View | Go Back. You can apply this command multiple times until you return to the state from which you began going back.

    An exception is that if you Go Back and then do an operation that changes the display (other than Go Back and Go Forward), then the Go Back stack is truncated and you cannot Go Forward from that state.

    View | Copy

    Extracts a URI or literal text from the selected object and posts it onto the 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 string 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 a query string without remembering or typing its long value.

    If there is no selected node or link in the graph view or the graphical query view, but there are one or more highlighted nodes (see Select | Toggle Highlighting of the Selected Node or Link), then this command will copy all of the highlighted nodes. Then doing a paste into any view will paste all of the copied nodes there.

    An advanced feature for editing reification: If a table cell node or graph view node represents a triple ID node, then that node will also be pushed onto an internal stack of all triple ID nodes that have been copied in the current Gruff session. You could later use Table View Value Column Editing | Select a Different Node (selecting the "Triple ID Node (for reification)" option) to create a triple that reifies the triple of the triple ID node that you had copied earlier. See Reification Support in Gruff.

    View | Paste

    Pastes the string that is on the 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 string widget of the query view, the string 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 string widget of the query view it will paste each node onto a different line of text. In the table view it will display one node at a time, and then you could use View | Go Back to view the properties of each of the pasted nodes.

    View | View Current Store in AGWebView

    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.

    View | Browse a Single Graph

    Lets you browse only a single graph that's in the store, or to revert to browsing the entire store after browsing a single graph. A dialog will appear that lists the graphs that are in the store. Selecting one will place Gruff into a mode where all commands that look for triples to display will find only triples that are in that graph. Selecting the first choice for the entire store some time later will return to browsing the entire store.

    If the only choices in the dialog are for the entire store and for the default graph, then the store does not contain multiple graphs, and using this command has no real effect.

    Using this command will clear everything that Gruff is currently displaying (and uncache data that it has collected), as when opening a different store. To instead display a visual graph of all of the triples in a particular graph without clearing other Gruff views and uncaching data, see Display | Display Triples of One Graph.

    Using various editing commands to create triples will create the triples in the graph that is currently being browsed, if any, and otherwise will create them in the default graph. Using this command is the only way in Gruff to create triples in a graph other than the default graph.

    Using this command could lead to confusion if you forget that you are browsing a single graph and wonder why other triples are not appearing. The single graph that is being browsed is mentioned in the title bar as a reminder.

    This command can fail if Global Options | Timeouts | Finding All Graphs Timeout is exceeded.

    The View Menu's List of Recent States to Redisplay

    The bottom section of the View menu lists states that were saved for the particular view that is currently shown. A state may be loaded and redisplayed by selecting it in this list.

    The states in this list (if it appears at all) were saved with the Save command on the File menu, which is either File | Save Layout State, File | Save Table Object URI, File | Save Query String, or File | Save Graphical Query, depending on the view that was displayed at the time. Those states can be loaded with the corresponding Load commands on the File menu, while this bottom section of the View menu is a quicker alternative for loading the states that were saved or loaded most recently for the particular store that is being browsed.

    Up to nine states will appear in this list. These menu items will begin with a numeral that you can type as a shortcut once you have shown the View menu, followed by the name of the layout file. To see the full pathname of the layout file, highlight the menu item and check the status bar at the bottom of the application.


    The Text Search Menu

    These commands allow searching for triples in the store textually, and then displaying some or all of the matches. You can specify a simple word or phrase to search for, to find literals or even URIs that contain the word or phrase. More complex searches can be done by specifying pattern-matching and/or logical expressions.

    The command at the bottom of this menu, Search the Current View, searches for a word or phrase in the text that's currently displayed on the screen in the selected view, rather than searching through the triple store as the other commands do.

    Text Search | Find and Display Nodes

    Displays the subject nodes of triples that match a text search. First a dialog appears for entering a word, phrase, or expression to search for in the triple store. If any triples are found that match the expression, then a second dialog appears listing the subject nodes of those triples.

    You can then select multiple matching nodes to display in the graph view or the graphical query view. In the table view you can select a single node to display a table of its properties; in the outline view you can select a single node to add to the outline; and in the query view you can select a single node to paste its text into the query text widget. (In the query view it will work only if the query text widget currently has the keyboard focus to indicate where the insertion point is.)

    The number of matching subject nodes that will be listed for selection is limited to Global Options | Maximum Choices When Selecting a Subset.

    The text search dialog mentions a few examples of the types of search expressions that can be used. Here is the meaning of each of those examples.

    one two three 
    

    This search expression will match any triple part whose value contains the word "one" and also contains the word "two" and the word "three", though those words do not need to be connected in the triple part value.

    "one more time" two three 
    

    The quotation marks here indicate that the entire phrase "one more time" (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.

    Text Search | Find and Display Triples

    This is like Text Search | Find and Display Nodes except that the second dialog lists the complete triples that were found rather than their subjects only. And selecting some of the matching triples will add nodes and links to the graph view for all parts of the selected triples.

    This command is present only in the graph view.

    Text Search | Select or Create a Text Index

    Lets you select a different current text index to search, or to create a new index. This menu command also displays the currently selected index in brackets, so that you can see whether the desired text index is already the current one.

    Invoking this command will show a pop-up menu for selecting the current text index. A special "New Index" choice at the top allows you to create a new text index, and this will be the only choice if the store does not yet have any text indexes. If there are any indexes to choose from, they will be listed below a separator bar, and a second special "All Indexes" choice in the upper section allows searching all of the store's indexes at once.

    A special "Delete an Index" option at the bottom of the menu allows removing a text index from the store, if you select an index from the menu that will appear next.

    This command does not appear in AllegroGraph 3, where a store can have only a single text index.

    Text Search | Edit the Current Text Index

    Shows a dialog that lets you specify what parts of the triple store will be searched by the current text index.

    The dialog primarily features a list of all of the predicates that are in the currently open store, with the ones that are currently indexed already selected. You can select a number of additional predicates to index them as well. You can also deselect any that are already selected in order to remove them from the index (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.

    Text Search | Add a Single Predicate

    Lets you select a predicate on which you would like to perform text searches. It will then update the current text index to search the triples of that predicate, in addition to the triples of any predicates that were already specified for that index.

    A series of menus will appear to let you select any predicate in the store, using sorted lists that discriminate on successive characters in the predicate names until there is no ambiguity. (That should make sense once you see it.)

    The first time this command is used for a particular open store, there will first be a pause to collect and sort all predicates that are in the store. A yellow message window appears during the pause. See Global Options | Timeouts | Finding All Predicates Timeout.

    If the current text index is "All Indexes" (for searching all indexes at once), then a pop-up menu will first appear to ask which index you would like to modify. (This 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.

    Text Search | Text Search Timeout

    This is the number of seconds before a text search will give up and return no results. Otherwise a text search might take an indefinite amount of time and hang Gruff.

    Text Search | Search the Current View

    Lets you search for any currently-displayed node in the graph view or the graphical query view, or any table cell in the table view, by typing a portion of the label that's printed on a node or in a table cell. A small window will appear that displays the search text as you've typed it so far. Initially the window will be at the lower left corner of the main Gruff window, but you can drag it elsewhere if you like. When you see the small window, just start typing characters. Use the Backspace or Delete key or Control-H to erase the most recently typed characters as needed.

    The search is an incremental one that updates the state of any matching nodes or table cells as you enter or erase each character of the search text. One of the currently matching nodes or cells (if there are any) will be selected at each step, and a status-bar message will indicate how many matches there are. The background color of the search window will also indicate whether there are matches for the current search text: It will be gray when there are no characters in the search text, blue when there are multiple matches, green when there is a single match, and red when there are no matches.

    When there are multiple matches, you can press the Tab key to select a different matching node or table cell. When the search text is at least three characters long, all matching nodes or cells will be highlighted with a red background (for nodes) or orange background (for table cells), and the currently selected matching node or cell will be scrolled toward the center of the window as far as possible to make it easy to spot the matching node or cell. (Tabbing to a match will scroll it toward the center even when the search text is less than three characters long.)

    To accept a match and leave it selected and scrolled toward the middle of the window, press the Enter key. To cancel the search and scroll the window back to where it was and reselect the previously selected node or cell (if any), press the Escape key.

    The selected matching node will flash momentarily if Visual Graph Options | Node and Link Flashing | Flash Selected Search Matches is enabled, as it is by default.


    The Display Menu

    These commands offer a variety of ways for adding an arbitrary node to the display, especially an initial node to which linked nodes can then be added with commands on the Link menu.

    These commands are typically used when you're in the graph view, to add a node to the set of nodes that is already displayed there. But they can also be used to display a node's properties in the table view, or to add a top-level node to the outline view, or to add a non-variable node to the query view, or even to insert the URI of the specified node into the query text in the query view.

    In the graph view, a newly added node will be placed at the mouse cursor. The node will also flash briefly if Visual Graph Options | Node and Link Flashing | Flash Newly Added Nodes is enabled.

    An alternatives to these Display menu commands is to use View | Paste to paste a node whose URI is on the system clipboard.

    Display | Display a Node by URI or Literal

    Displays a node that has the URI or literal string that you type or paste into a text-edit box in a dialog. The string should be a complete URI for a resource, such as http://www.cyc.com/2002/04/08/cyc#Balloon, or else a complete literal string (without quote marks). 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.

    Display | Display a Node by Label

    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.

    Display | Display a Recently Selected Node

    Presents a menu of nodes that you have selected recently in the store that you are browsing, and displays the one that you select, if any. The most recently selected nodes will appear toward the top of the menu.

    The list of nodes will include nodes that you selected in recent Gruff sessions. That makes this command useful for getting started in a new Gruff session by locating and displaying nodes that you were using in the previous Gruff session for the same store.

    Display | Display an Instance Node by Type

    This command is useful in any store that contains triples that use the rdf:type predicate. It finds all of the objects of those triples and presents them as a series of alphabetized pop-up menus, for selecting any "type" object in the store. After selecting a type, a further series of pop-up menus let you select an instance of the selected type, meaning the subject of some rdf:type triple whose object is the selected type.

    The first time you use this command, it may take a while to find all of the types. You can interrupt the search at any time by pressing the Q key or the Escape key; if you do that while it is still collecting nodes (before it begins to sort them), then it will proceed to sort the ones that it's found so far and then let you select from that subset of all types.

    To display a node for a type itself, rather than one of its instances, use Display | Display a Type Node by Type instead.

    Display | Display a Type Node by Type

    This is like Display | Display an Instance Node by Type, except that it displays a node for a selected type itself, rather than further asking for an instance of that type to display.

    Display | Display an Instance Node by Class Hierarchy

    This command is useful only if the triple-store being browsed contains triples that use the rdfs:subClassOf predicate to define subclass relationships. If that is true, then a dialog is presented that displays all nodes that are part of subClassOf triples. Initially only the top-level classes in the hierarchy are visible. These top-level class items can be opened (by clicking the icons on the left) to reveal various levels of subclasses. Selecting a class in this dialog will then display a series of pop-up menus for selecting an instance of the selected class. If an instance is selected, then a node will be added to the display for the selected instance.

    In the dialog for the subClassOf hierarchy, classes that have no instances will appear in grayed-out text. Selecting such a class would inform you that there are no instances to select, but they still appear in the outline to allow navigating to their subclasses. (By a "class with no instances", we mean a node that is the subject or object of one or more rdfs:subClassOf triples but not the object of any rdf:type triples.)

    The first time you use this command, it may take a while to find all of the top-level classes, though you can interrupt the search by pressing Q or Escape, and then select one of the classes that it has found so far.

    To display a node for a class itself, rather than one of its instances, use Display | Display a Class Node by Class Hierarchy instead.

    Display | Display a Class Node by Class Hierarchy

    This is like Display | Display an Instance Node by Class Hierarchy, except that it displays a node for a class that you select from the hierarchy of all subClassOf objects, rather than further asking for an instance of the selected class to display.

    Display | Display Some Sample Triples

    Adds nodes and links to the graph view for some triples in the current triple store, up to a limit that's defined by Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display. The graph view is first cleared of all other nodes and links, though you can always use View | Go Back to retrieve them.

    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.

    Display | Display Triples of One Graph

    Adds nodes and links to the graph view for all of the triples of one particular graph that you first select from a list. The graph view is first cleared of all other nodes and links. The number of triples that are added is limited to Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display.

    This command may be especially useful in a store that contains many graphs, where one graph is used for each "thing" of some kind, and where not all of the triples for a thing are linked with each other via shared nodes.

    This command can fail if Global Options | Timeouts | Finding All Graphs Timeout is exceeded.

    To cause all Gruff commands to browse only a single graph, see View | Browse a Single Graph.

    This command is present only in the graph view.

    In the lisp interface, the corresponding function is display-store when passing a :graph argument to it.


    The Link Menu

    These commands are for adding nodes to the visual graph that are linked (in the database) to nodes that are already displayed. Before using these commands you need to use a command on the Display menu to add an initial node.

    The menu is present only in the graph view.

    Link | Display Linked Nodes for the Current Predicates

    Adds any nodes to the display that are linked with the currently selected node by any of the current predicates. First you need to select the current predicates with Global Options | Select Current Predicates.

    This is useful for quickly building a visual graph, by alternately selecting different nodes and then using this command to see what's linked with them. If this adds too many nodes or undesired nodes, use View | Go Back to revert to the previous state.

    Triples will be included where the selected node is either the subject or the object, unless either Link | Triples to Include | Include Triples as Subject Only or Link | Triples to Include | Include Triples as Object Only is enabled.

    Link lines will also be added to display between any newly-added nodes and any already-displayed nodes to which they are linked by the current predicates. Though for efficiency reasons this is not done for larger stores, specifically any store that contains more triples than Global Options | Miscellaneous | Minimum Triples for Individual Property Lookup.

    If there is no selected node but there are one or more highlighted nodes, then this command will be applied to all of the highlighted nodes simultaneously. This is an even faster way to display lots of linked nodes, though it may usually display more than desired. See Select | Toggle Highlighting of the Selected Node or Link.

    If this operation would cause the entire visual graph to contain more links than Visual Graph Options | Inclusion Options | Number of Total Links for Abort, then it will stop looking for additional links at that point. If that happens, or otherwise if the total number of links would exceed Visual Graph Options | Inclusion Options | Number of Total Links for Warning, then a warning dialog will be shown. The dialog will offer options to either display all of the linked nodes, or to let select a subset from a list of them, or to cancel. If you use the option to select a subset of the linked nodes, then the number of nodes that will be listed for selection will be limited to Global Options | Maximum Choices When Selecting a Subset.

    When using the alternative node-coloring scheme Visual Graph Options | Color Nodes for Unseen Links, this command will have an effect only on nodes whose background color is yellow (by default), which indicates that they have undisplayed linked nodes for the current predicates.

    See also the introductory section Using Current Predicates to Quickly Build a Graph.

    In the lisp interface, the corresponding function is display-linked-nodes.

    Link | Display Only Linked Nodes for the Current Predicates

    This is the similar to Link | Display Linked Nodes for the Current Predicates just above, except that it first removes all nodes from the display except for the selected node. This is useful for starting a new visual graph with one of the currently displayed nodes. It is also useful for browsing through a sequence of nodes without retaining everything that you pass through, by repeatedly selecting a leaf node and then using this command to see only that node and the ones that are linked with it.

    In addition, if Visual Graph Options | Inclusion Options | Show 2 Levels of Nodes on Display Only Linked Nodes has been selected, then this command will display not only the selected node and the ones that are immediately linked with it, but also any nodes that are immediately linked with any of those linked nodes (by the current predicates). If that does not display too many nodes at one time, it allows you to more quickly browse through a sequence of nodes by repeatedly selecting a node that is either one or two links away from the previously selected node.

    Link | Fill In All Links for the Current Predicates

    Adds any "missing" links to the display for the nodes that are already on the display and the current predicates. It will also update any existing link lines to represent any additional current predicates that they do not already represent. This is useful after selecting additional current predicates, to show where the newly-selected predicates connect any nodes that were already on the display. It is also useful after adding individual nodes from the table view or with Link | Display Linked Nodes from a Tree, 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.

    Link | Triples to Include | Include Triples as Subject Only

    Causes Link | Display Linked Nodes for the Current Predicates to show only triples where the selected node is the subject. This includes when opening items in the outline view.

    This will also make Link | Display a Linked Node from Menus skip its initial menu asking for triples as subject or as object.

    Link | Triples to Include | Include Triples as Object Only

    Causes Link | Display Linked Nodes for the Current Predicates to show only triples where the selected node is the object. This includes when opening items in the outline view.

    This will also make Link | Display a Linked Node from Menus skip its initial menu asking for triples as subject or as object.

    Link | Triples to Include | Include Triples as Either

    Causes Link | Display Linked Nodes for the Current Predicates to show triples where the selected node is either the subject or the object.

    About Node Background Color for Unseen Links

    Related to the above commands, here is a note about using node background color to facilitate adding linked nodes for the current predicates. This applies only when the Visual Graph Options | Color Nodes for Unseen Links option is in effect, which it is not by default.

    When using Color Nodes for Unseen Links, the background color of a node will indicate whether it is linked with other resources in the database that aren't currently displayed. This tells you whether particular commands in this section of the Link menu will do anything when applied to the selected node.

    If a node is yellow (by default), then there are undisplayed resources in the database that are linked to this node by the current predicates (see Global Options | Select Current Predicates). Therefore the Display Linked Nodes for the Current Predicates command will do something when a yellow node is the selected node, and not otherwise. If you are building a graph with that command, then the yellow nodes are the ones that are worth selecting.

    If a node is green (by default), then it does NOT have any undisplayed linked nodes for the current predicates, but it DOES have undisplayed linked nodes for other predicates. Therefore Display Linked Nodes for the Current Predicates will do nothing when a green node is the selected node, but Display Linked Nodes from a Tree WILL show additional linked nodes that you could add to the display. And the table view will similarly show the additional nodes that could be added.

    A cyan node (by default) has no linked resources in the database that are not currently displayed, and so there is no point in selecting it for adding linked nodes to the display.

    Those three special colors may be changed on the Visual Graph Options menu.

    Link | Display Paths Between Two Nodes

    Adds to the display any nodes and links that lie on paths between two specified nodes that are already on the display. The only paths that will be found are ones whose links use only the current predicates (see Global Options | Select Current Predicates), and which are no longer than Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length. The results are also affected by Visual Graph Options | Finding Paths Between Nodes | Find Only Shortest Paths.

    The currently selected node will be used as one of the end nodes of the path, so you should click a node to select it just before using this command (unless the desired node is already selected). The command will then draw a rubber-band line from the selected node to indicate that you need to click on the other end node. If you do click on another node, then the triple-store will be searched for paths between the two nodes, and any nodes and links for the found paths that are not already displayed will be added to the display.

    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.

    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.

    In the lisp interface, the corresponding function is find-and-display-paths.

    Link | Display Only Paths Between Two Nodes

    This is like Link | Display Paths Between Two Nodes except that it also removes all nodes and links that are not part of the paths that were found.

    It may be useful to use View | Go Back along with this command, to display only the paths between two nodes of a large layout, and then to return to the large layout to select two other nodes to display their paths, and so on.

    The placement of the selected nodes that lie at the ends of the found paths is affected by whether Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Left and Right or one of its alternatives is currently selected.

    Path-finding is not available when using a SPARQL endpoint rather than an AllegroGraph store.

    Link | Display a Linked Node from Menus

    Lets you select a node that is linked to the currently selected node in the store, and adds that node to the display, with a link line connecting the two nodes. You select the linked node in a series of pop-up menus, first selecting whether the selected node is the subject or the object of the triples to select from, then selecting a predicate, and finally selecting a node that is linked by the selected predicate in the selected direction. On each menu there is an "All" choice for displaying all of the remaining choices instead of a single one.

    The menus are prepared in a way that allows making the next selection by pressing a single character on the main part of the keyboard. The first menu is always the choice for the set of triples where the selected node is either the subject or the object; you can type S or O to make this selection. (This menu is skipped if either Link | Triples to Include | Include Triples as Subject Only or Link | Triples to Include | Include Triples as Object Only is enabled.)

    The next menus allow choosing a particular predicate for which there are triples with the selected node as the subject or object. If there are no more than 25 predicates from which to choose, then all of the choices will appear on a single menu that uses the letters A through Y as keyboard shortcuts. Otherwise the predicates will be divided into a series of pop-up menus that allow refining your choice by typing single letters.

    After choosing a predicate, a node that's linked by that predicate can then be chosen in the same way that the predicate was chosen. That node will then be added to the display. If there are no more than 25 linked nodes for the predicate that you selected, then the menu of linked nodes will have a special "All" item at the top; selecting this choice will add all of the linked nodes for that predicate to the display.

    The menus will exclude choices for nodes and links that are already in the visual graph.

    Link | Display Linked Nodes from a Tree

    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.

    A predicate name in the outline will have a yellow background if it is one of the "current predicates" whose nodes could alternately be added with the Link | Display Linked Nodes for the Current Predicates command. A node name in the outline will have a cyan background if it is already on the display (though the link line between the nodes may not exist yet). A node name will have a red background if you have explicitly excluded that node with the Remove | Exclude Selected Node command; but you can still add that node to the display with this command, which also removes it from the set of excluded nodes.

    A rather similar technique for adding nodes is to toggle over to the table view and select them there. And the Link | Display a Linked Node from Menus command is also similar when adding a single linked node at a time.


    The Remove Menu

    These commands offer various ways to prune some of the nodes and links in a visual graph. In the graph view, the nodes and links tend to accumulate until the visual graph becomes unwieldy.

    This menu is present only in the graph view and the graphical query view, and only some of these commands are present in the graphical query view.

    Remove | Remove Selected Node

    Removes the currently selected node from the display. Any orphan nodes that remain will also be removed if the Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal option is active.

    In the lisp interface, the corresponding function is remove-node-of-upi.

    Remove | Exclude Selected Node

    This is like Remove Selected Node, but it also marks the removed node so that it will not be added to the display again during the current browser session by any of the commands that add nodes for the current predicates. This is useful for removing a node that is clearly not of interest and to prevent it from popping back up again and again. This helps to remove clutter that only makes the layout more difficult. It may be especially useful for nodes that have many links (assuming that they are not of interest).

    Link | Display Linked Nodes from a Tree or the table view can still be used to add excluded nodes back to the display. The node names will have a red background in those windows to indicate that they have been explicitly excluded. If an excluded node is added to the display in one of those ways, it will no longer have excluded status.

    This command is present only in the graph view.

    In the lisp interface, the corresponding function is remove-node-of-upi.

    Remove | Remove Selected Link

    Removes the currently select link (if any) from the display.

    Any orphan nodes that remain will also be removed if the Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal option is active.

    Remove | Remove All Nodes

    Clears all nodes and links from the display, for a fresh start. If done accidentally, you can return to the previous state as usual with View | Go Back.

    Remove | Eraser Mode

    Allows quickly removing an arbitrary subset of the displayed nodes and links. It puts the graph view into a mode where any node or link that the mouse cursor touches will immediately be removed, along with any links to any removed nodes as usual. The mouse cursor will change to warn you that you are in eraser mode.

    Eraser mode can be turned off in several ways. You can either invoke the Eraser Mode command again, or press Escape or Q to invoke Layout | Abort the Layout or Command, or click the mouse anywhere, or move to another pane or application.

    This command may make it rather easy to inadvertently delete nodes or links that you would like to remain. If that happens, just use View | Go Back to revert to the state before eraser mode was turned on.

    Remove | Remove All Orphan Nodes

    Removes all orphan nodes from the display. An orphan node is one that has no link lines attached to it on the display (though it may have triples in the database).

    This command is present only in the graph view and the graphical query view.

    In the lisp interface, the corresponding function is remove-orphans.

    Remove | Remove All Leaf Nodes

    Removes all leaf and orphan nodes from the display. This includes any node that has no more than one link line attached to it on the display.

    This command can be useful when you are primarily interested in cycles in the displayed graph. All nodes that are not a part of a cycle can be removed by applying this command multiple times as needed (since removing some leaves can turn other nodes into leaves). You can even view the cycles temporarily by using this command (and then perhaps updating the layout), and then using View | Go Back to return to the earlier state with leaf nodes intact.

    One paradigm for building a graph with lots of cycles is to continue adding linked nodes until there are many more nodes on the display than you would care to see at one time. (This process can be sped up by pressing Q or Escape or the spacebar to interrupt each incremental layout after adding each set of new nodes.) Then use this Remove All Leaf Nodes command a few times to prune out all nodes that are not in cycles, and then update the layout to see all of the interesting cycles between the remaining nodes.

    This command is present only in the graph view and the graphical query view.

    In the lisp interface, the corresponding function is remove-orphans, when passing the leaves-too argument as true.

    Remove | Remove All Unhighlighted Nodes

    Removes all nodes from the display except for those that you've highlighted with Select | Toggle Highlighting of the Selected Node or Link. A mouse shortcut for that command is Control-Left-Click.

    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.


    The Layout Menu

    These commands modify the arrangement of nodes in the visual graph, using layout algorithms that attempt to make the graph easily readable, and manage your view of the layout.

    This menu is present only in the graph view and the graphical query view, and only some of these commands are present in the graphical query view.

    Layout | Redo Layout from Scratch

    Rearranges the displayed nodes and links to make a more readable layout, by moving nodes near to other nodes that they are linked with and reducing overlapping.

    Gruff implements two different layout algorithms: A constraint-based algorithm that's used for smaller graphs and a spring algorithm that's used for larger graphs. The option Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout determines which is used. The constraint-based algorithm specializes in avoiding overlapping between nodes and links, to make it as clear as possible which nodes are linked by each link line. But that algorithm doesn't scale well, and so a spring algorithm is used for larger graphs to make them fast enough for interactive use.

    The nodes do not start out at their current positions, as with Layout | Update Layout Incrementally. Instead, the constraint-based algorithm begins with all nodes at the center of the canvas, to remove any bias that the current node positions might otherwise cause in the layout algorithm. This usually achieves a cleaner layout than a series of incremental updates to the layout. The spring algorithm begins with nodes scattered at random positions around the canvas (and so will the constraint-based algorithm if Visual Graph Options | Constraint-Based Layout Options | Begin Full Layout at Random Positions is enabled).

    The layout will be animated if Visual Graph Options | Layout Options | Animate Layouts is enabled. Otherwise the display will be updated only once at the end of the layout computation. Animation slows down the layout, but shows you how it is progressing.

    When there are many nodes and animation is enabled, the layout will be faster if you first use Layout | Zoom Out All the Way, because then the nodes will be drawn more simply and the overview pane will not be present and so will not be drawn.

    The layout will stop if the number of iterations reaches Visual Graph Options | Layout Options | Maximum Iterations for Full Layout. The constraint-based algorithm may stop before then if it sees that the important constraints have been satisified. The spring layout does not know if it has reached a reasonable solution, though, and so it will always proceed toward this maximum, then slow down and typically stop some time before the limit is reached. If the layout is not judged good enough when it stops, then proceed to use Layout | Update Layout Incrementally one or more times to make the layout go further. If it looks good enough before reaching the limit, then you can interrupt the layout by pressing Escape, Q, or the spacebar (which are shortcuts for menu bar commands).

    If a layout fails to achieve a decent arrangement because there is not enough room, then first use Layout | Make Canvas Larger. Or use Layout | Zoom Out, which effectively makes a larger canvas after the scrollbars have gone away, because the canvas is always at least as large as the node pane.

    The cleanest possible layout is usually achieved by first unpinning any pinned nodes (see Select | Remove All Node Pinning) and then using this command, followed by Layout | Update Layout Incrementally if more work is needed.

    This menu command corresponds to the lisp function update-the-layout.

    This command is present only in the graph view.

    Layout | Update Layout Incrementally

    Rearranges the nodes as needed to make a more readable layout, beginning from the current node positions. This leaves nodes at or near their current positions when feasible, so that you don't lose track of the current context. This command can be used one or times in succession to improve a layout that is not yet satisfactory. You can issue this command (typically using its keyboard shortcut) while a layout is being done to speed the layout back up.

    If there is a selected node and the constraint-based layout is being used, then that node will remain fixed in its current position. A cleaner layout might be achieved by first clicking the background (or pressing the spacebar) to deselect the current node, which gives more freedom to the layout algorithm.

    This command is performed automatically by various commands that add or remove nodes, unless Visual Graph Options | Layout Options | Do Automatic Incremental Layouts is deselected. But it can still be useful to invoke explicitly at other times, such as after you have dragged nodes around. In particular, if you spot a case where the layout can be improved, you can drag nodes to better spots yourself. Using this command after that may make further adjustments to where you dragged the nodes. When you do drag nodes, try to leave the usual minimum spacing between the dragged node and other nodes and links if you want this incremental layout command to take your hint and retain your explicit changes. To ensure that the nodes that you dragged do not simply snap back to where they were, first use Select | Toggle Pinning of the Selected Node to force particular nodes to stay where you've placed them when a layout is later done.

    The layout will stop if it the number of iterations reaches Visual Graph Options | Layout Options | Maximum Iterations for Incremental Layout.

    If a layout fails to achieve a decent arrangement because there is not enough room, then first use Layout | Make Canvas Larger or Layout | Zoom Out.

    This command is present only in the graph view.

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

    Layout | Update Layout Vigorously

    Performs an incremental layout that "shakes things up" more during the first part of the layout. This may be useful if the regular incremental layout is failing to untangle any crossed chains of nodes, and you'd like to untangle those without undoing the progress that layouts have made so far.

    This works internally by making linked nodes pull harder on each other in the early stages of the layout. An alternative may be to reduce Visual Graph Options | Spring Layout Options | Velocity Divisor, which would make layouts both push and pull harder all the time.

    This command always uses the spring layout algorithm, even when the visual graph contains fewer nodes than Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

    Layout | Update Layout Conservatively

    Performs an incremental layout that mainly tries to moves any nodes off of link lines that they are sitting on, without disturbing the layout a lot. This can be useful after a spring layout, because the spring layout algorithm does not try to keep nodes off of link lines for speed reasons.

    This command always uses the constraint-based layout algorithm, even when the visual graph contains more nodes than Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout. This command is mostly like Layout | Update Layout Incrementally when that command uses the constraint-based algorithm, except that this one disallows nodes from jumping very far away, to avoid disrupting the layout much.

    Because the constraint-based algorithm does not scale well, this command can take a long time when there are more than around 100 nodes. But to achieve the neatest layout with a larger graph, the best approach is probably to first use Layout | Redo Layout from Scratch once, then Layout | Update Layout Incrementally zero or more times as needed until the spring layout appears to have taken things as far as it will, and finally (when you're ready to have lunch or go to sleep) to use this command once and leave it running for a while.

    You can always interrupt this command in the usual way by pressing Escape, Q, or the spacebar.

    Layout | Abort the Layout or Command

    Aborts a layout that is in progress, or certain other time-consuming activities such as searching for all top-level classes (or all nodes) in the triple-store. At any time you can press either the Q key or the Escape key to invoke this command.

    You can also abort a layout simply by executing some other command, which will abort the layout and then proceed with the new command. This includes pressing the spacebar to invoke Select | Deselect the Selected Node and/or Link, and so the spacebar is a handy way to abort a layout as long as it's OK to also deselect the selected node.

    See also the introductory section Interrupting a Long-Running Layout.

    Layout | Make Canvas Larger

    Increases the size of the scrollable canvas (into which the layout must fit) by one "notch", which by default is around one fifth of the current canvas size in each direction. This can be useful to make a layout succeed after it failed at a smaller canvas size. Typically you would notice a layout attempt thrashing about, then use this command to abort the layout and make the canvas larger, and then try the layout again.

    The factor by which this command increases the canvas size each time can be set with Visual Graph Options | Layout Options | Canvas Resize Factor.

    In case the keyboard shortcut that's shown on the menu item for this command is not clear, it is a period. That key was chosen because the greater-than symbol (or right angle bracket) is typically on the same key, as a mnemonic for a larger canvas.

    If the Visual Graph Options | Node and Link Spacing | Limit Outward Stretching option is off, then the layout tends to fill the available canvas, requiring more scrolling to see everything, and so it's best to reduce the canvas size later if the larger size is no longer necessary. The size of the scrollbar sliders provides a clue about the current canvas size, and so does the size of the content in the overview pane at the lower left.

    If the Visual Graph Options | Node and Link Spacing | Limit Outward Stretching option is on (as it is by default), then the layout will still tend to stretch things out somewhat more than necessary, so if you want to fit the layout into the smallest area possible then you would still need to make the canvas smaller in order to constrain the layout further. For example, if a layout extends just a little ways outside of the visible window when the canvas is large, it will likely fit entirely in the window if you first use Layout | Make Canvas Smaller repeatedly until the scrollbars turn off entirely.

    Layout | Make Canvas Smaller

    Reduces the size of the scrollable canvas by one "notch", which is around one fourth the current canvas size in each direction. This can reduce the size of future layouts so that you don't have to scroll as far to see everything, but can also make a layout less likely to succeed.

    The keyboard shortcut for this command is the comma key because the less-than symbol (or left angle bracket) is typically on the same key, as a mnemonic for a smaller canvas.

    If the canvas is already at its minimum size, which means that the scrollbars are turned off, and you are not currently zoomed in all the way, then this command will actually zoom in by one notch, as with Layout | Zoom In, and then also reduce the canvas size again so that the scrollbars are still turned off. This can be a handy way to zoom in when you are zoomed out farther then necessary, but without making the canvas larger than the window.

    Layout | Zoom Out

    Zooms the visual graph outward so that more nodes and links can be seen at once. Labels will not be drawn in node boxes or on link lines when zoomed out by any amount, but they will appear in tooltips when hovering over nodes and links.

    Layout | Zoom In

    Zooms the visual graph inward to display more detail or to make nodes easier to click on. Node and link labels will be drawn only when zoomed in all the way.

    If you are zoomed out farther than necessary, then see Layout | Make Canvas Smaller as a way to zoom in without making the canvas larger than the window.

    Layout | Zoom Out All the Way

    Zooms the visual graph outward far enough that all of the nodes and links fit into the node pane at the same time. This provides a complete picture of a larger graph.

    Animated layouts may be more interesting when zoomed out all the way, because you can see how the entire graph is being rearranged. Animated layouts will also be faster, because the nodes are drawn more simply when zoomed out, and the overview pane will not be drawn as well because it is turned off whenever all nodes and links fit into the node pane.

    The mouse shortcut is Control-Alt-Right Click, which can be handy just after using Control-Alt-Left Click for Layout | Zoom In Around the Mouse.

    Layout | Zoom In All the Way

    Zooms the visual graph inward to the normal size where node labels are drawn (and link labels as well when enabled). The graph will be centered around the same nodes and links that it was centered around before zooming in.

    Layout | Zoom In Around the Mouse

    Zooms the visual graph inward all the way, centering on the nodes and links that were near the mouse cursor when the command was issued.

    When you're already zoomed in all the way, this command can still be used to quickly scroll the mouse position to the center.

    It is most convenient to invoke this command with its mouse shortcut, which is Control-Alt-Left Click.

    Layout | Center the Graph

    Moves the entire set of displayed nodes as a whole so that they are centered within the scrolling canvas, and then scrolls the window to the center of the canvas. This is typically useful to bring all of the graph (or else the middle of it) into view after a layout has inadvertently shifted everything over toward one side. It can also increase the likelihood of success of future incremental layouts by increasing the minimum amount of space that's available off any one side of the window.

    By default, nodes are moved to the center of the canvas automatically after either type of layout. See Visual Graph Options | Layout Options | Center After Full Layout and Visual Graph Options | Layout Options | Center After Incremental Layout. But the window is scrolled to the center automatically only for a full layout.

    In the lisp interface, the corresponding function is center-the-graph.


    The Select Menu

    These commands allowing selecting, highlighting, and pinning nodes.

    This menu is present only in the graph view and the graphical query view, and only some of these commands are present in the graphical query view.

    Select | Toggle Pinning of the Selected Node

    Pins the selected node so that it will not be moved whenever a layout is done. 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.

    Select | Remove All Node Pinning

    Unpins all currently pinned nodes. A shortcut is to shift-left-click the background (that is, the window interior where there is no node or link line).

    This command is present only in the graph view and the graphical query view.

    Select | Toggle Highlighting of the Selected Node or Link

    Highlights the selected node or link, or unhighlights it if it is already highlighted. A node is highlighted by drawing it with a thick blue border, similar to the thick red border of the single selected node. A link is highlighted by drawing it in red. A node or link will remain highlighted when it is no longer the single selected node or link. You can therefore highlight multiple nodes by selecting various nodes and using this command on each one.

    A shortcut for highlighting multiple nodes and links is to control-left-click each one (without needing to first select each one). And you can remove all highlighting by control-left-clicking the background. Multiple nodes can be highlighted with a single gesture by control-left-clicking down on the background and then dragging a box downward and to the right that completely surrounds the set of nodes to highlight.

    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.)

    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.

    Select | Remove All Node and Link Highlighting

    Unhighlights all currently highlighted nodes and links. A shortcut is to control-left-click the background (that is, the window interior where there is no node or link line).

    This menu command corresponds to the lisp function remove-all-highlighting.

    This command is present only in the graph view and in the graphical query view.

    Select | Copy Highlighted to Graphical Query View

    Copies any currently highlighted nodes, along with any link lines that connect two highlighted nodes, over to the graphical query view. You can then turn those nodes and links into a graphical query by converting some of the copied nodes and links into variables. (Two non-variables 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, 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.

    Select | Deselect the Selected Node and/or Link

    Deselects the currently selected node if there is one, and also the selected link if there is one. Altenately you can click the background, though this command's keyboard shortcut (the spacebar) may be more convenient when you don't have a hand on the mouse.

    Like many of the commands, this one interrupts the layout if one is currently being done. Therefore, pressing the spacebar can be a convenient way to interrupt the current layout and deselect the selected node. In particular, if an incremental update is being done automatically at the end of some command, then you could press the spacebar and then R (the shortcut for Layout | Redo Layout from Scratch) to interrupt the incremental layout and do a full layout instead.

    If the keyboard focus is in a table rather than in the graph view, then the keyboard shortcut for this command, which is the spacebar, does not invoke this command and instead emulates a mouse click in the table cell that has the keyboard focus.

    This command is present only in the graph view.

    Select | Reselect Previous Node and Link

    Reselects the node and link that were most recently selected, if any, and otherwise selects an arbitrary node and/or link. This provides a keyboard way of selecting a node or link as required by various other commands.

    Select | Rotate to Next Link Clockwise

    Selects the next link clockwise from the currently selected link extending from the selected node. If no node is currently selected, then the previously selected node (or an arbitrary node if none) is first selected. If no link is currently selected, or the selected link is not connected to the selected node, then this command selects an arbitrary link that's connected to the selected node.

    This command is typically useful for selecting a link across which to jump to another node with the Leap Across Selected Link command below.

    If the legend pane has the keyboard focus (as when you press Tab to move it there), then this command will select the next item in the legend.

    Select | Rotate to Next Link Counterclockwise

    Selects the next link counterclockwise from the currently selected link.

    If the legend pane has the keyboard focus (as when you press Tab to move it there), then this command will select the previous item in the legend.

    Select | Leap Across Selected Link

    Selects the node that is on the other end of the currently selected link from the currently selected node. If no link is currently selected, then the previously selected link (or an arbirary link if none) is first selected. If no node is currently selected, or that node is not connected to the selected link, then this command arbitrarily selects one of the nodes that are connected to the selected link.

    This command and the Rotate to Next Link commands just above provide a way of selecting various nodes with the keyboard rather than the mouse. When working with nearby nodes and/or using a laptop without a mouse, this could perhaps be faster than using the mouse or laptop touchpad, with practice.

    If the legend pane has the keyboard focus (as when you press Tab to move it there), then this command will leap from the list of node types to the list of predicates or vice versa.


    The Edit Menu

    These commands allow you to edit the triple-store by adding and removing triples. They work in conjunction with commands that are on the right-click pop-up menu in the table view.

    Edit | Create Node by Type

    Creates a new object that has a specified rdf:type, then lets you fill in the values of properties that nodes of that type have. A triple will be created in the store for the type that you select, and other triples will be created if you fill in other suggested property values in the form that appears in the table view.

    A pop-up menu will first ask you to select one of the various ways to select a type, and then further prompts will ask you to select the actual type for a new node.

    You will next be prompted to specify a URI for the new node. A pop-up menu will likely appear with a set of suggested namespaces, followed by a dialog for entering an IRI string. If you chose one of the suggested namespaces, it will appear in the text-editing widget to facilitate entering the IRI.

    Next the new node for the specified URI will be shown in the table view, just as when you use Edit | Edit Selected Node by Type on a node that already exists. The table will show the triple that was created for the selected type, and typically also a set of table rows for predicates that are associated with the type that you specified. Supplying a value for an empty cell in one of these rows will create a triple.

    See Edit | Edit Selected Node by Type for information on how the suggested predicates are chosen for the type that you specified.

    Right-click an empty cell (or move the keyboard focus to it and press the M key) to see the pop-up menu of editing commands for that cell. In particular, Table View Value Column Editing | Enter a Different Node will let you type in a URI for an empty cell, while Table View Value Column Editing | Select a Different Node will let you select a node that already exists in the store.

    Edit | Edit Selected Node by Type

    Displays the selected node in the table view, and then adds table rows for additional properties that you may want to fill in. Supplying a value in one of these rows will create a triple in the store.

    The suggested properties that are offered in the table are found in two ways. One way is collecting a sample of triples for the type that you specified, and seeing what properties the subjects of those triples have. (And also what properties the objects of the triples are values of.) The other way is looking for any predicates that define their rdfs:domain or rdfs:range to be the type that you specified, or any superclass of it. Rows with blank values are added to the table for any such predicates that are found for which the object does not yet have values.

    In the graph view and the graphical query view, this command is applied to the currently-selected node, if any. In the query view it is applied to the node cell that has the keyboard focus, if any. In the table view it is applied to the currently displayed object (rather than the node in the table row that has the keyboard focus), and so it will simply add table rows for the node that is already displayed there. This command also appears on the right-click pop-up menu of the table view.

    Edit | Create a Triple by Linking Nodes

    Lets you create a new triple in the store by connecting the selected node to either another node or to a link. Connecting to a second node will create a "regular" triple, while connecting to a link line will create a triple that reifies the triple of that link line.

    If there is a selected node when this command is used, then a rubber band line will appear between that node and the mouse cursor to indicate that it is waiting for you to click on a second node or on a link line. If you do click on a second object, then you will be asked to select a predicate. If you select a predicate, then a new triple will be created using the two nodes and predicate that you have sprecified. A new link line will appear that represents the new triple (unless there was already a link line connecting the two nodes, in which case that existing link line will represent the new triple as well).

    When asking for a predicate, a first pop-up menu will offer various ways of selecting a predicate from various subgroups of all of the predicates that are in the store. Then further menus will let you select a particular predicate from the subgroup that you selected.

    When the second object is a link, the new triple will have the first node as its subject and a triple ID typed node for the object, where the integer value of the triple ID node is the ID of the triple that the selected link line represents. (Except if the link's triple is the only one in its graph, then the object of the new triple will be the graph part of the link's triple rather than its triple-ID part.) If the link line represents multiple triples, a pop-up menu will ask which of the triples should be used. See Reification Support in Gruff.

    No automatic layout is done when the new link line is displayed, to avoid disruption as you add a series of triples. This may leave the new link lines overlapping other objects, and so you may want to use Layout | Update Layout Incrementally or Layout | Redo Layout from Scratch when you are done createing triples.

    This command is present only in the graph view.

    Edit | Create a Triple Using Most Recent Predicate

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

    This is handy when creating a number of triples that use the same predicate, to avoid reselecting the same predicate every time.

    Edit | Reverse Triple of Selected Link

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

    This command is present only in the graph view.

    Edit | Delete Triple of Selected Link or Node

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

    You can use Edit | Undo to re-create a triple that you've deleted. It will not recreate the link line in the graph view, though, because the displayed nodes and links may have partially or fully changed by the time that you undo the triple deletion, and it's not clear in the general case when it might be intuitive to recreate the link line.

    This command is present only in the graph view.

    Edit | Undo

    Shows a menu of commands to undo recent triple creation, editing, or deletion. The most recent edits appear toward the top of the menu, with the most recent at the very top.

    The commands will undo changes to the store that were done using the right-click pop-up menu in the table view, though an undo can be done in any view or after browsing to a different object in the table. If an undo happens to affect the currently displayed node in the table, then the table will update itself automatically.

    Each command briefly indicates what it will do. If the command begins with the word "Recreate", then it will create a triple to replace one that was individually deleted. If it begins with "Restore", then it will create the triple that it mentions as well as deleting another triple that had replaced the deleted triple (see Table View Value Column Editing | Enter a Different Node). If it begins "Delete", then it simply deletes a triple that was individually created. If it begins with "Restore URI", then it creates and deletes a number of triples to restore a URI that was edited with Table View Value Column Editing | Rename the Node.

    Once an undo action is performed, it will no longer appear on the undo menu, though a new command to redo the modification that was undone will then appear on the redo menu.

    Edit | Redo

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

    Once a redo action is performed, it will no longer appear on the redo menu, though a new command to once again undo the edit that was redone will then appear on the undo menu.

    Edit | Confirm Triple Deletion

    If this option is enabled, as it is by default, then any attempt to delete triples from the store will first display a modal dialog that asks you to confirm the deletion.

    Edit | Prompt for Commit on Exit

    If this option is enabled, as it is by default, and you attempt to exit Gruff when there are uncommitted edits to the store, then you will prompted for whether to commit the changes before exiting. Alternately you could use File | Commit to commit changes explicitly. If this option is disabled, then the prompt will not appear and no automatic commit will be done.

    Unsaved changes generally result from adding, editing, and deleting triples in the table view. Gruff will do a commit automatically, on the other hand, when you use its commands to load triples or create text search indexes.

    This menu command does not exist in AllegroGraph version 3.

    Edit | Show Menus of Recent Namespaces

    When you specify a new node or predicate by typing or pasting its URI, if this option is enabled then you will first be prompted to select a recently-used namespace to facilitate enterying the URI. When it is disabled, the namespace that would have been the first choice in the menu is used automatically.

    If the namespace choices are in two groups with a separator line between them, then the upper group are namespaces that are used by other values of the same predicate, with more frequently-used namespaces (in the small sample that is taken) appearing toward the top of the menu. The lower group are other namespaces of nodes that have been browsed recently. The upper group that applies to the same predicate may be more likely to include the desired namespace.

    If you don't want to use any of the suggested namespaces, then select the choice at the top for "Other Namespace (or None)". This allows entering a literal or an IRI with some other namespace from scratch.

    No namespaces will be suggested or pasted when entering a new value for a property when other nodes that have that property all use literals for the property value.

    This option is used by Edit | Create Node by Type and by Table View Value Column Editing | Enter a Different Node.

    Edit | Prompt for Label for New Blank Node

    If true, then whenever you create a new blank, you will be further prompted to type in a string for the rdfs:label property of the new blank node. This is a handy shortcut when you are using rdfs:label properties for all blank nodes to make them easily identifiable.

    See also Outline Options | Create All Nodes as Blank Nodes for another convenience option when creating blank nodes in the outline view.

    Edit | Percent-Decode Characters for Editing

    When enabled, editing a URI textually will first convert any non-ASCII characters that are percent-encoded as hexadecimal values using the %xx notation will first be converted to the actual characters to facilitate editing the string. (Percent-encoding is also called URI-encoding.)

    This option might be removed in the future in favor of a new utility program for converting percent-encoded non-ASCII characters in triples files. This will allow normalizing triples before adding them to a store, removing the need for Gruff to accomodate irregular data.

    Edit | Percent-Encode Non-ASCII After Editing

    When enabled, editing a URI textually will convert any non-ASCII characters in the edited URI will be percent-encoded using the %xx format before storing them.

    The trend appears to be toward storing non-percent-encoded Unicode characters directly in stores, and so this option is off by default. Turning this option on could result in edited values becoming percent-encoded in the store when they were not before.

    When this option is on, a URI that is entered when using Display | Display a Node by URI or Literal will also have its non-ASCII characters percent-encoded to match percent-encoded characters that are in the store.

    This option might be removed in the future in favor of a new utility program for converting percent-encoded non-ASCII characters in triples files. This will allow normalizing triples before adding them to a store, removing the need for Gruff to accomodate irregular data.


    The Global Options Menu

    Options that may affect all Gruff views.

    Global Options | Status Bar Font

    This is the font that is used for status messages at the bottom of the window. A larger font is easier to read but fits less text into the single text line of the status bar.

    Global Options | Widget Font

    This is the font that is used in miscellaneous widgets and the hints in tables. This generally includes any text that is not covered by more specific font options such as Visual Graph Options | Node Labels | Node Label Font, Visual Graph Options | Link Labels | Link Label Font, Global Options | 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 String Font.

    Changing this font may not take effect in modal dialogs that have already been created, until you restart Gruff.

    Global Options | Node Label Predicates | Use Label Predicates for Node Labels

    When enabled, the label that is displayed for a resource node in various Gruff views and menus will be the 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.

    Global Options | Node Label Predicates | Label Predicate Language

    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.

    Global Options | Node Label Predicates | Custom Predicates for Node Labels

    Determines which properties are used for providing strings that are displayed as labels to represent nodes.

    If a store does not contain rdfs:label properties but it does use some other custom predicate to define the label strings of 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 made the set of predicates be this:

    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.

    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.

    Global Options | Node Label Predicates | Custom Predicates for Node Comments

    Determines which properties are used for providing strings that are displayed as comments in tooltips when you hover over nodes in the graph view or over outline items in the outline view.

    This works like Global Options | Node Label Predicates | Custom Predicates for Node Labels except that (1) Global Options | Node Label Predicates | Use Label Predicates for Node Labels does not need to be enabled, and (2) only the first property value that is found will be displayed, rather than concatenating all of them together.

    Global Options | Node Label Predicates | Custom Predicates for Node Pixmaps

    Determines which properties (if any) are used for providing images to display on some nodes in the graph view. When provided, the images will be displayed instead of the usual label strings.

    When a particular node is displayed in the graph view, if there is a triple in the store where that node is the subject, and the predicate is one of the predicates that you specify for this property, and the object's URI or literal string is the name of a pixmap file, 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.

    On Windows, the file must have a .bmp or .ico file type. On Linux and Mac, the file type may be either .png, .bmp, or .jpg. 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.

    See Displaying Images for Nodes for more information.

    Global Options | Node Label Predicates | Custom Predicates for Web Pages

    Determines which predicates are used for providing URLs of web pages to visit for nodes in a third-party web browser program.

    When you use the command View | 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.

    Global Options | Derived Node and Link Labels | Exclude Namespaces from Labels

    When checked, the string that appears for a resource in a node or a menu will be only the final descriptive part (local name) of the resource's URI.

    When unchecked, a string that indicates the full URI will be shown, though it will always use a namespace abbreviation (as defined by a call to register-namespace) for the first part of the URI. If there is an existing namespace abbreviation mapping that is applicable to the URI, then that one will be used, and otherwise a namespace mapping will be created automatically. The name of an automatically created namespace will be brX, where X is an integer that specifies a unique namespace name. The "br" stands for "browser".

    So nodes will always display abbreviations of URIs to save space, and using this option abbreviates URIs further by excluding the namespace abbreviation prefix. Using this option makes the labels more easily readable but may also lead to ambiguities. To see the full URI of a resource, glance at the status bar at the bottom of the window when holding the mouse cursor over a node in the graph view or over a table cell in the table view. Or turn on Visual Graph Options | Node Labels | Show Full URIs on Nodes to display complete URIs directly on nodes themsleves. To see full URIs in the cells of a table, enable Table Options | Show Full URIs in Tables.

    This option is ignored for objects that have rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

    Global Options | Derived Node and Link Labels | Add Spaces to Labels

    When checked, spaces will be added in certain cases to node label strings to make them more easily readable. Additional spaces also allow long node labels to be wrapped to multiple lines at more places within the string (since wrapping is done only at spaces); this may save space in the layout by reducing the maximum dimension of some nodes.

    When this option is used, a space will be inserted after any lowercase character that is followed by an uppercase character, which would change "fooBar" to "foo Bar", for example. In addition, any underscore character will be replaced by a space, and a space will be inserted after any colon.

    This option is ignored for objects that have rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

    Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

    Global Options | Derived Node and Link Labels | Collapse Contiguous Spaces in Labels

    When checked, any sequence of two or more space characters in a node label string will be replaced by a single space.

    This option is ignored for objects that have rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

    Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

    Global Options | Derived Node and Link Labels | Capitalize First Word

    When checked, the first character of any node label is uppercased. This may make labels nicer for human reading if the words in the label are capitalized except for the first word, as in fooBarBaz. Using this option along with Global Options | Derived Node and Link Labels | Add Spaces to Labels would convert fooBarBaz to Foo Bar Baz.

    This option is ignored for objects that have rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

    Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

    Global Options | Derived Node and Link Labels | Convert Percent Encoding in Labels

    When checked, any percent-encoded characters in a URI will be converted into the single Unicode characters that they represent when deriving pretty labels to display.

    This option is ignored for objects that have rdfs:label properties when Global Options | Node Label Predicates | Use Label Predicates for Node Labels is enabled.

    Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

    Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass"

    This is a special hack to cause the rdfs:subClassOf predicate to be printed by Gruff as "Superclass". This may make it easier to recognize the direction of subclass links, especially to avoid the expression "is Sub Class Of of" in the predicate labels that are displayed when Visual Graph Options | Link Labels | Draw Link Labels 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".

    Global Options | Namespace Abbreviations

    Shows a dialog that contains all registered abbreviations for namespaces. You can edit the mapping of abbreviations to namespaces here. Then you can use the abbreviations in query strings in The Query View, or with Display | Display a Node by URI or Literal.

    The abbreviations are saved with other options for use in future Gruff sessions. The mappings are global across all stores, rather than specific to each store that Gruff browses.

    The mappings that are shown in the static list at the bottom of the dialog are standard mappings that are always defined, and so you don't need to add them to your own list.

    Global Options | Select Current Predicates

    Allows you to modify the set of "current predicates". This set of predicates primarily determines which nodes are displayed by Link | Display Linked Nodes for the Current Predicates in the graph view or the outline view. In the graph view, the current predicates are also used by Link | Display Paths Between Two Nodes. And in the graphical query view, selecting a predicate from the set of current predicates will be one choice when using Graphical Query Link | Specify Predicate.

    A dialog is shown that contains a list of predicates. The list contains all of the predicates that are applicable to any of the nodes that have been displayed for the current triple-store during the current browser session.

    You can toggle multiple predicate names on and off by simply left-clicking each one on the Windows platform, or by control-left-clicking on any platform. You can select a contiguous series of predicates by left-clicking the one at one end of the series and then shift-left-clicking the one at the other end. The "Select All" and "Deselect All" buttons below each outline can be used to either select or deselect all of the predicates in either list.

    Selecting all predicates typically causes many nodes and links to be added by Link | Display Linked Nodes for the Current Predicates, so it's usually better to select only particular predicates of interest to reduce clutter in the layout.

    In the table view and in the results table of the query view, current predicates are indicated with a yellow background. In the outline view, the arrow icon of a node will be solid if there are other nodes that are linked with that node by the current predicates, and which can be shown by "opening" that outline item; otherwise the arrow icon will be hollow.

    In the lisp interface, the corresponding function is set-current-predicates.

    Global Options | Use a Recent Set of Current Predicates

    Lets you reselect a set of current predicates that you have used recently in the currently open store. A pop-up menu will appear that lists the most recently used sets of predicates. This allows quickly reselecting frequently used sets of predicates without needing to select each individual predicate in the Global Options | Select Current Predicates dialog every time.

    Global Options | Maximum Choices When Selecting a Subset

    When a command asks you to select a subset of the matches that it has found for possible display, this is the maximum number of choices that it will present in a dialog that lists the choices in alphanumeric order and lets you select any portion of them. Additional choices will not be included in the list. Such dialogs are typically shown when the number of found choices exceeds some other option value that triggers a warning dialog, where the warning dialog has an option for selecting a subset.

    This can arise when using Link | Display Linked Nodes for the Current Predicates, Link | Display Paths Between Two Nodes, Text Search | Find and Display Nodes, and similar commands, as well as when generating a visual graph from query results in the query view.

    Global Options | General Triple-Fetching Limit

    This is the maximum number of triples that will be found whenever Gruff asks for all of the triples where a particular node is either the subject or the object. Gruff generally asks for that set of triples whenever it first needs to find any of the triples for a node, and then uses that set of triples for the node thereafter. If the node has more triples than this limit allows, then Gruff will behave as if there are fewer triples for the node than there really are.

    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 | Query Results Limit will be used.

    Global Options | Timeouts | Finding All Types Timeout

    This is the number seconds before Gruff's initial attempt to find and cache all types in the store will give up and display a warning dialog about a timeout. This search will be done automatically the first time you use the command Display | Display an Instance Node by Type or Display | Display a Type Node by Type, and perhaps at other times.

    An error dialog will be shown if this timeout is exceeded. If it is worth waiting longer for the commands that are affected by this timeout, then you can set this particular option to a longer time and try again.

    Global Options | Timeouts | Finding All Predicates Timeout

    This is the number seconds before Gruff's initial attempt to find and cache all predicates in the store will give up and display a warning dialog about a timeout. This search will done you edit a text search index, to provide a list of all predicates that allows you to chose which ones to index. It will also be done when adding a non-variable link in the graphical query view and choosing the option to select a predicate from all predicates, or if you create a triple and choose the similar option.

    Finding all predicates may be slower if the user does not have permission on the server to evaluate arbitrary code.

    An error dialog will be shown if this timeout is exceeded. If it is worth waiting longer for the commands that are affected by this timeout, then you can set this particular option to a longer time and try again.

    Global Options | Timeouts | Finding All Graphs Timeout

    This is the number of seconds before Gruff's attempt to find all of the graphs in the store will give up and display a warning message. Gruff will look for all of the graphs whenever you View | Browse a Single Graph or Display | Display Triples of One Graph.

    An error dialog will be shown if this timeout is exceeded. If it is worth waiting longer for the commands that are affected by this timeout, then you can set this particular option to a longer time and try again.

    Global Options | Timeouts | Bulk Property-Fetching Timeout

    To save time, Gruff sometimes uses a single query to ask the server for the label properties or types of a group of nodes. This option is the number of seconds that Gruff will wait for the server to reply. If this time is exceeded, then Gruff will abandon that query and revert to looking up those properties individually later as needed.

    Since the information is retrieved in other ways if this timeout is exceeded, it is safe to set it to a relatively low value. That will prevent what is usually an optimization from using up excessive time if it turns out not be efficient in some cases.

    The problem is that you are not told when this timeout is exceeded, because Gruff silently reverts to more basic approaches, and so the value of this option could be optimized only by trial and error. Normally the default value shoud be fine.

    Global Options | Timeouts | Endpoint-Testing Timeout

    This is the number of seconds that Gruff will wait for a SPARQL endpoint to reply to a trivial test query when you are connecting to a SPARQL endpoint with File | Connect to SPARQL Endpoint.

    The test query should not take much time, so this option can be a relatively short time to avoid hanging up Gruff for a little while when the requested endpoint does not really exist or is currently unresponsive.

    Global Options | Timeouts | General Triple-Fetching Timeout

    This is the number of seconds that Gruff will wait for the server to reply to any request that's not covered by more specific (and normally shorter) timeouts.

    If this timeout is exceeded, Gruff will quietly behave as if there were no triples on the server for the request. This can be misleading, and so this option normally should be a relatively long time whose sole purpose is to prevent Gruff from hanging indefinitely when the server is not responding adequately.

    User queries in the query view are not subject to this timeout, and are subject only to Query Options | Query Timeout instead. So if you set that timeout to a large value for complex user queries, you do not need to also set this timeout to a large value.

    Global Options | Timeouts | Query Timeout

    This is a copy of Query Options | Query Timeout, to group all of the timeout options on a single menu.

    Global Options | Timeouts | Text Search Timeout

    This is a copy of Text Search | Text Search Timeout, to group all of the timeout options on a single menu.

    Global Options | Timeouts | Path-Finding Timeout

    This is a copy of Visual Graph Options | Finding Paths Between Nodes | Path-Finding Timeout, to group all of the timeout options on a single menu.

    Global Options | SPARQL Endpoints | Query Results Limit

    This option applies only when browsing a SPARQL endpoint rather than an AllegroGraph store.

    This is the maximum number of results that Gruff will ask for when it internally queries a SPARQL endpoint as you browse. It does not apply to the SPARQL queries that you write yourself in the query view or graphical query view, where you need to specify the limit in your query.

    When browsing an AllegroGraph store, the option Global Options | General Triple-Fetching Limit is roughly equivalent to this option for SPARQL endpoints.

    This separate option is provided in case you want to use a smaller limit with SPARQL endpoints where turnaround may be slower.

    Global Options | SPARQL Endpoints | Use Label Predicates for Node Labels

    This option applies only when browsing a SPARQL endpoint. When browsing an AllegroGraph store instead, see Global Options | Node Label Predicates | Use Label Predicates for Node Labels.

    When enabled, the labels that are displayed for nodes in the various Gruff views will be the rdfs:label properties for any nodes that have them. More generally, if you have set up any custom label predicates with Global Options | Node Label Predicates | Custom Predicates for Node Labels, and the resource has any of those properties, then they will be used instead of the resource's rdfs:label property. This overrides the options for deriving labels directly from URIs and literal strings.

    This option is off by default because looking up label properties typically increases the browsing time significantly with SPARQL endpoints. The corresponding option for AllegroGraph stores is on by default because there are optimized ways for retrieving the label properties of a group of nodes at once. This separate option is supplied so that it can remain off while the other option remains on, though you may want to test turning this one on to see if browsing is still fast enough. It may be needed at a SPARQL endpoint that contains nodes whose URIs do not contain meaningful names.

    Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color

    This option applies only when browsing a SPARQL endpoint rather than an AllegroGraph store.

    When this option is enabled, and a node has multiple rdf:type properties, then Gruff will attempt to find the "most specific" type of the node and then color the node to indicate that type. When this option is disabled, Gruff will arbitrarily choose one of the node's types. The most specific type is defined as the one that has the longest chain of superclasses above it, using the subClassOf predicate.

    This option is off by default because it typically requires more additional time than it is worth when using a SPARQL endpoint. But the corresponding option that's used with AllegroGraph stores is on by default because the added time is typically not very significant. That option is Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color.

    Another option for controlling which types are used for node colors is Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color. That technique should not have a significant time cost.

    Global Options | SPARQL Endpoints | Maximum Sample Triples to Display

    When browsing a SPARQL endpoint rather than an AllegroGraph store, this is the maximum number of triples that will be displayed by Display | Display Some Sample Triples and by Display | Display Triples of One Graph. The default is rather small for SPARQL endpoints due to the number of round trips to the endpoint that are required.

    When browsing an AllegroGraph store the option Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display is used instead.

    Global Options | Pop-Up Menus | Maximum Menu String Length

    This is the maximum number of characters that will appear in any string that appears on a pull-down or pop-up menu. If a string is longer than this, then it will be truncated and an ellipsis will be shown at the end to indicate that it has been truncated. The purpose is to prevent menus from being overly wide.

    Global Options | Pop-Up Menus | Show Full URIs in Pop-Up Menus

    When checked, any pop-up menus that list nodes or predicates will display the complete URIs for those objects. 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.

    Global Options | Pop-Up Menus | Case-Sensitive Sorting for Menus

    When checked, lists of nodes and predicates that are presented in menus and dialogs will be sorted in a case-sensitive way, and otherwise will be sorted in a case-insenstive way. The case-sensitive option would sort information that's being cached more quickly, thereby reducing delays, but would make some menus longer by causing them to have separate sections for items that begin with uppercase or lowercase letters.

    Toggling this option will uncache various lists of sorted objects that can appear in menus, requiring it to be re-sorted and cached again when it is next needed, and so you may notice delays shortly after toggling this option.

    Global Options | Communications | Start HTTP Server

    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.

    Global Options | Communications | Use Session Ports

    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.

    Global Options | Communications | Use Direct Access When Possible

    When enabled, if you create or open a store using a server that's running on the local machine, then the connection to the server will use direct access rather than communicating via HTTP as usual.

    Sometimes direct access is referred to as "local" mode and HTTP communication as "remote" mode, though the HTTP approach can still be used when the server is the local machine.

    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.

    Global Options | Communications | HTTP Proxy

    If you are behind a firewall that uses an HTTP proxy, then you can enter the proxy information in the dialog that this option command shows. 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.

    Global Options | Communications | Use any23.org for RDFa

    Whether the command File | Extract Microformat/RDFa Data from Web Page will use the web site any23.org for extracting triples from the web page, as opposed to a custom technique. The any23 technique alternately works on microdata. Yet each technique may find triples that the other does not.

    Global Options | Communications | Ignored RDFa Relationships

    This option is used only if Global Options | Miscellaneous | Use any23.org for RDFa is disabled.

    This is a list of HTML relationship attributes that will be skipped by File | Extract Microformat/RDFa Data from Web Page. You can select one or more attributes here to exclude some types of triples from the set that is collected, to avoid cluttering up the graph of all of the extracted triples.

    For example, selecting "stylesheet" will avoid collecting triples for HTML links to .css web pages.

    Global Options | Miscellaneous | Warm Up the Store

    Brings as much internal data as possible into physical memory for fast access thereafter. Alternately, this can be done when opening the store by using two check boxes on the store-opening dialog.

    Global Options | Miscellaneous | Confirm Exit

    If this option is enabled, as it is by default, then attempting to exit Gruff will show a dialog asking you to confirm that you really want to exit.

    Global Options | Miscellaneous | Treat Literals as Objects

    When enabled, Gruff will treat any literal node as an object that is linked with every node that has that literal as a property value. Otherwise, multiple nodes that have a same literal property value are not considered to be related to each other.

    This has a special effect in the graph view. For example, if you display the nodes for two people and also the nodes for their ages (where the age values are literals), and the people are both 37 years old, then Gruff will use separate node boxes for the two age 37 literals when this option is disabled. But if this option is enabled, then a single age 37 node box will be displayed, with two link lines connecting that single node box to the ones for the two people.

    Enabling this option is also needed in order to apply certain other commands to a literal node, such as displaying all of the triples for a literal in the table view, or using Link | Display Linked Nodes on a literal in the graph view.

    Changing the value of this option while a store is open requires Gruff to clear everything that is currently displayed, and to uncache internal information that may then need to be refetched from the server. A dialog box will warn you about this before the change is made.

    Global Options | Miscellaneous | Confirm Closing Stores

    When enabled, if you open or create a store or connect to a SPARQL endpoint while an AllegroGraph store is open, Gruff you first show a dialog asking whether it's OK to first close that store. If you agree, then Gruff will close that store and proceed. Otherwise the new operation will be canceled. Gruff can browse only a single open store at any time.

    Global Options | Miscellaneous | Display Graph-Part Reification

    When enabled, Gruff will sometimes automatically display reification relationships that use graph-part reification. In that style of reification, a graph that contains only a single triple can reify that triple with other triples that use the graph part of the reified triple as their subject or object parts. This option is turned off by default because it may take a long time to look up the relationships in a large store that does not have a triple index for the graph part.

    See Reification Support in Gruff.

    Global Options | Miscellaneous | Merge Retained Triples

    This option is used if you select the option to retain the triples that were downloaded from the previous store or endpoint when you open a new store or connect to a new endpoint. See File | Open Triple-Store. This option may also come into play when using a SERVICE clause in a SPARQL query in the query view to borrow information from a separate endpoint.

    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), 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. 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.

    Toggling this option will behave as needed only if it is toggled before opening the first store (or connecting to the first endpoint) and then opening additional stores or connecting to additional endpoints while selecting the option to retain earlier triples.

    Global Options | Miscellaneous | Minimum Triples for Individual Property Lookup

    This is a somewhat obscure option that could be adjusted to optimize how efficiently Gruff retrieves triples from the server and caches them for later use. You could try setting the value to two numbers where one is greater than the number of triples in the store that you're browsing and one is less, and use whichever setting results in general faster browsing (if there is any noticable difference). For the most accurate experiment, when you begin testing each value you should re-open the store or use File | Clear and Uncache Everything.

    Here's the background: In a smaller store, it's nearly as fast to ask the server for all triples where a particular node is the subject as it is to ask for that node's triples for a particular predicate. So when a particular property of a node such as rdfs:label is needed, Gruff retrieves all of the triples where that node is the subject and caches them. Then later when Gruff needs another property of that node, it can find it quickly in the cached triples for that node rather than making an additional server request.

    But in a larger store it can take much longer to retrieve all of the triples where a node is the subject than to retrieve just the triples for a particular predicate. So when Gruff needs certain properties such as type, label, comment, and pixmap, which it often needs for nodes for which it does need most properties, it does NOT retrieve and cache all triples where the node is the subject, and instead asks the server only for the triples for that property.

    This option sets the number of triples at which Gruff switches to the second strategy for larger stores. If the store that Gruff is currently browsing contains fewer triples than this number, then it will use the first strategy above for caching all triples where a node is the subject. But if the store contains more triples than this number, then it will use the second strategy for fetching individual properties from the server instead.

    One other effect of this option is that in stores with more triples than the option value, Link | Display Linked Nodes for the Current Predicates will not add links to the display between newly-added nodes and any already-displayed nodes to which they are linked by the current predicates. This is done to make that command faster in larger stores.

    Global Options | Miscellaneous | Reasoner Enables Restriction Reasoning

    If you are browsing a reasoning store by having invoked the command File | Apply RDFS++ Reasoner, then the reasoner will include reasoning about owl:hasValue, owl:someValuesFrom, and owl:allValuesFrom whenever this option is enabled.

    Global Options | Miscellaneous | External Format for Loading Triples

    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. 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.

    Global Options | Miscellaneous | Auto Font Switching on Text Entry

    This option has an effect only on the WIndows platform.

    It determines whether text-editing panes in Gruff may automatically switch fonts when needed to draw inserted characters properly. This typically may be needed when inserting Asian or other multibyte characters. Even when the official font contains the needed characters, the text-editing control may not allow enough width for them to be displayed clearly. This affects the query string 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 String Font and Table Options | Table Property Value Font.

    Global Options | Miscellaneous | Use Web Browser for All Documents

    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.

    Global Options | Miscellaneous | Document Base Folder

    If your store contains literal nodes that refer to document files that are stored on the local machine, then you can use View | 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.

    Global Options | Revert to Default Options

    Sets the value of most options (from all of the options menus) to their initial values, if you say OK when a confirmation dialog apeaars. The display should update to reflect any changes just as when you modify individual options.

    The list of recently opened files that appears on the File menu is not cleared, even though it is saved in the options file, and the same is true for the most recently used host, port, and path. A few other options are not cleared because the default values are random or empty; these include the options that are set by the commands Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type, Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate, Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate, Global Options | Node Label Predicates | Custom Predicates for Node Labels, and Global Options | Namespace Abbreviations. These exceptions allow reverting from options that you may have modified temporarily, without undoing certain other preferences that are more tedious to set up.

    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.

    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.


    The Query Options Menu

    Options that affect SPARQL and Prolog queries. This menu is present only in the query view and the graphical query view.

    Query Options | Query String Font

    This is the font that is used in the query string widget of the query view.

    The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when the keyboard focus is in the query text widget.

    Query Options | Query Timeout

    This is the number of seconds before a query that's done in the query view will give up and return no results. Otherwise a query might take an indefinite amount of time and hang Gruff.

    Query Options | Query Results Limit

    This is the maximum number of rows that will be created in the query view's results table. This is simply to save time creating the table when many results are returned.

    Query Options | Include More Triples in Visual Graphs

    This option determines which of two approaches is used to derive triples from query results. The triples are often used to generate a visual graph from query results, using the "Create Visual Graph" button widget in the query view, and can also be used to export triples to a file with File | Export Displayed Data As | N-Triples and related commands.

    The results of a SELECT query are not triples, but triples are what a visual graph displays. So to generate a visual graph from query results, an arbitrary approach must be used to derive triples that are related to the query results. This is somewhat complex, but here is a basic description of how the two approaches that Gruff offers work internally. You can choose whichever is closest to what you're looking for.

    When this option is disabled, triples are derived by plugging variable matches from the query results into triple patterns from the query. These triples directly relate to the query because each one matches a triple pattern that was the source of some of the query results.

    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 unkown 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.

    Query Options | Exclude Orphans from Visual Graphs

    Whether nodes that have no displayed links will be excluded from visual graphs that are generated from query results. An orphan would result when a node is in either the query results or the query itself, but it is not part of any triple whose three parts are all in either the query results or the query itself. If you are interested in seeing only triples in the visual graph, then you could select this option.

    If the visual graph would contain ONLY orphan nodes, then the nodes will still be displayed to avoid confusion when the visual graph contains nothing at all.

    Query Options | Percent-Encode Non-ASCII in Queries

    Whether all non-ASCII characters that are entered into SPARQL and Prolog query strings 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), in which case you would not need this option.

    (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 a query string, 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.

    Query Options | Query Logging Enabled

    When checked, each SPARQL or Prolog query that is performed will be written to the log file that's specified by Query Options | Query Logging File. The query string itself will be written, followed by the table of results in textual form. The report is written in a primarily human-readable format, though in a regular way that could also be parsed by analysis software. The format of the table is affected by other options on this menu.

    An alternative is to use the Write Text Report button widget in the query view to write a single query with its results to a file that you specify on the fly.

    Other information will also be written to the log file when logging is enabled, including data written by commands on the File | Export Displayed Data As child menu, and notes about when a Gruff session began and ended.

    Query Options | Query Logging File

    This is the file to which SPARQL and Prolog queries will be logged whenever Query Options | Query Logging Enabled is currently toggled on. This option will default to a file called gruff-log.txt in your home directory on Linux or your personal documents directory on Windows.

    If this file doesn't exist when a query is done, then it is created, and otherwise the new query will be appended to the end of the file. You could change the value of this option to begin writing a new sequence of queries to a different file.

    Query Options | New Log File for Each Session

    When checked, a different log file will be created and used for each Gruff session (when query logging is enabled). This can help prevent a single log file from growing overly long.

    The name of the log file that will be used will be derived by appending a date-time string for the time at which the Gruff session began to the official log file pathname.

    Query Options | Show Current Log File Now

    This one is actually a command rather than an option. It invokes a third-party program to display the current log file. The program will be the one that's registered for displaying documents of the type that you specified for the log file, such as invoking Notepad to display a .txt file.

    Nothing will happen if the log file is not found, which is normally when no queries have been done yet with query logging enabled.

    Query Options | Query Text Report Show Full URIs

    When checked, queries that are written to text report files will print the full URI of each node or predicate. Otherwise only brief names will be printed to save space. When this option is on, you may want to also turn on the One Line per Value option below to prevent the text lines from getting overly long.

    This option affects files that are written by automatic query logging as well as by the Write Text Report button widget.

    Query Options | Query Text Report One Line per Value

    When checked, queries that are written to text report files will print each table cell value (along with its variable name) to a separate line of text, rather than printing all values of a table row to a single line of text. This option may be needed when the Show Full URIs option above is enabled, to prevent the text lines from getting overly long.

    This option affects files that are written by automatic query logging as well as by the Write Text Report button widget.

    Query Options | CSV File Include Full URIs

    When checked, queries that are written to CSV files will print the full URI of each node or predicate. Otherwise only brief prettified node labels will be printed for readability.

    This option affects files that are written by the "Save as CSV" button widget.

    Query Options | CSV File Include Column Headers

    When checked, queries that are written to CSV files will include an initial text line at the top that contains the names of the query results column variables. They will be enclosed in double quote characters and separated by commas, as with the variable values in other rows.

    This option affects files that are written by the "Save as CSV" button widget.


    The Table Options Menu

    Options that affect the display of information in tables. This menu is present only in the table view and the query view, and only some of its commands are present in the query view. (In the query view it applies to the query results tables.)

    Table Options | Table Property Name Font

    This is the font that is used for text in the lefthand column of the table in the table view. That column displays property names, also known as predicates of triples.

    The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the table view. (The value font will be adjusted along with it.)

    Table Options | Table Property Value Font

    This is the font that is used for text in the righthand column of the table in the table view. That column displays property values, also known as objects of triples.

    The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the table view. (The name font will be adjusted along with it.)

    Table Options | Show Full URIs in Tables

    When checked, each table cell in the table view or the query view will display the complete URI of a node or predicate rather than a shorter label that was found or derived in some other way. This will override all other options that find or derive labels in various ways for the table view.

    This option has a keyboard shortcut, which is simply the 8 numeral key on the main part of the keyboard. This shortcut is handy for for frequently toggling the table view between easily-readable short labels and complete URIs.

    Table Options | Show Multiple Property Values

    When checked, each property that has multiple values will display all of the values, each on their own lines. When unchecked, each property will display only a single line, which will show the property value if it has only a single value, or else will show the number of values that it has.

    Using this option shows all of the triples of the displayed node, but may require lots of scrolling to see all of the properties (predicates) that the node has.

    Regardless of whether this option is enabled, you can always left-click on a property cell to toggle whether that particular property displays all of its values.

    Table Options | Sticky Multiple Property Values

    When this option is enabled and the table is in expanded mode (meaning that Table Options | Show Multiple Property Values is currently on), clicking on a predicate to collapse it will cause that predicate to continue to be collapsed as you visit further nodes. This can be undone by later clicking that predicate again (in either expanded or collapsed mode) to re-expand it.

    Similarlly, clicking a predicate to expand it while in collapsed mode will cause that predicate to continue to be initially expanded as you visit further nodes, until you click it again later to re-collapse it.

    Table Options | Show Multiple Text Lines

    When checked, displaying each literal in the table view will make the table row tall enough to fit the value within its table cell. When unchecked, every table row will be just tall enough to fit a single line of text.

    Using this option allows seeing all of the text of long literals, but may cause fewer table rows to fit in the window at one time.

    Table Options | Display Literals of All Languages

    When checked, the table view will display all literals regardless of their language tags. When unchecked, the table view will display only literals that have no language and literals that have the language tag that is currently selected on the Global Options | Node Label Predicates | Label Predicate Language child menu.

    This command is present only in the table view.

    Table Options | Display Links to Reifying Triples

    When checked, whenever the triple for a row in the table has any reifying triples in the store that use triple-id reification, then a small icon will be displayed just to the left of the border between the two table columns. Clicking this icon will display the table for the triple-ID node of the row's triple, which will show all of the triples that reify the row's triple. See Table View Value Column Navigation | Show Reifying Triples in Table.

    This option is off by default because most stores do not use much reification, and it can take significant time to check for any reifying triples for the triple of each table row.

    See Reification Support in Gruff.

    Table Options | Maximum Triples Per Predicate in Table

    This is the maximum number of triples that will 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.

    Table Options | Maximum String Length in Table

    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.

    Table Options | Table Color One

    This is one of the two background colors that are used for alternate rows in the table. These default colors are overridden by special colors in some table cells.

    Table Options | Table Color Two

    This is one of the two background colors that are used for alternate rows in the table. These default colors are overridden by special colors in some table cells.

    Table Options | Table Cell Vertical Padding

    This is the number of pixels of blank space between text in a row of the table and the border of the row. A larger value increases readability but fits fewer table rows into the window.


    The Outline Options Menu

    Options that affect the display of information in the outline view. This menu is present only in the outline view.

    Outline Options | Outline Font

    This is the font that is used for the names of nodes in the outline view.

    The names of predicates will be drawn in a variant of this font, to distinguish them from the node names. If this is a bold font, then the predicate will be drawn in the non-bold version of the font. If it is a non-bold font, then the predicate will be drawn in the italicized version of the font.

    The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the outline view.

    Outline Options | Show Full URIs in Outline

    When checked, each node and predicate in the outline view that's a resource will be displayed as the complete URI of the node or predicate, rather than as a shorter label that is found or derived in some other way. This will override all other options that find or derive pretty labels.

    This option has a keyboard shortcut, which is simply the 8 numeral key on the main part of the keyboard. This shortcut is handy for for frequently toggling the outline view between easily-readable short labels and complete URIs.

    Outline Options | Show Comments When Hovering

    When checked, holidng the mouse cursor briefly over an outline item will display the comment property of the node that's in the item, if it has one. The comment will be displayed as a wrapped string in a box just below the outline item. The wrapped text will go away when you move the mouse cursor off of the item.

    The hovering time that is required is controlled by Outline Options | Hovering Delay. The font for the comment is controlled by Visual Graph Options | Tooltips | Tooltip Font.

    The actual predicates to search for a comment to display can be customized with Global Options | Node Label Predicates | Custom Predicates for Node Comments.

    Outline Options | Wrap Text When Hovering

    When checked, holding the mouse cursor briefly over an outline item whose text is clipped at the right (because the text is too long to fit on one line) will display the complete text in a box as multi-line wrapped text. The wrapped text will go away when you move the mouse cursor off of the item.

    The hovering time that is required is controlled by Outline Options | Hovering Delay.

    If the mouse cursor gets in the way of reading the text, a rule of thumb is to hold the mouse cursor over the name of the predicate, where it will be out of the way of the text box that is displayed to the right.

    Outline Options | Hovering Delay

    This is the number of milliseconds that you must hold the mouse cursor over an outline item before its comment property or full text (when clipped) will appear.

    Outline Options | Maximum Width for Wrapped Text

    This is the maximum width for the rectangle into which text will be displayed in the outline view according to the options Outline Options | Wrap Text When Hovering and Outline Options | Hovering Delay. The value is measured in pixels.

    This constraint is provided to make wrapped text easier to read in a column that is not overly wide. The value could be increased if needed to make more text fit in the available vertical space.

    Outline Options | Indicate Which Items are Openable

    When checked, outline items will display hollow arrows when no nodes are linked with that item's node by the current predicates, other than the node of the parent outline item. This indicates that opening the item would not show any child items (see Link | Display Linked Nodes for the Current Predicates, which is run when you open an outline item).

    The arrows for a newly-revealed set of child items are not changed to hollow mode immediately because it may take a while to ask the server for the linked nodes of each node. Instead, a command is queued up to handle each one individually when nothing else is busy. But if it still bogs things down, this option could be turned off to avoid displaying hollow arrows at all; you would then need to open an item to find out if it has any children.

    Outline Options | Create All Nodes as Blank Nodes

    When checked, then creating a new node in the outline view will always create a blank node, rather than asking you for an RDF string or a literal.

    This provides a fast way to create new nodes when you don't care that each one has an RDF name.

    See also Edit | Prompt for Label for New Blank Node for another convenience option when creating blank nodes.


    The Visual Graph Options Menu

    Options that affect how the information in a store is displayed in a visual graph of node pictures that are connected by link lines.

    This menu is present only in the graph view and in the graphical query view. Only some of its commands are present in the graphical query view.

    Visual Graph Options | Node Labels | Node Label Font

    This is the font that is used to draw labels on nodes in the graph view, and also in menus that are shown in the graph view. A larger font is easier to read but increases the size of the graph.

    The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the graph view. (The link label font will be adjusted along with it.)

    Visual Graph Options | Node Labels | Show Full URIs on Nodes

    When checked, the complete URI for each node will be displayed on the node itself in the graph view. This will override all other node label options for using either label predicates or derived labels.

    The nodes will be larger due to containing more text, and also less nearly square, and so a larger canvas will typically be needed to display the nodes. After turning on this option, you can use Layout | Make Canvas Larger if needed to increase the canvas size, followed by Layout | Update Layout Incrementally to rework the layout for the larger node boxes.

    Visual Graph Options | Node Labels | Maximum Node Label Length

    Strings that are displayed in node boxes will be truncated to this length when longer, but only when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is enabled.

    Visual Graph Options | Node Labels | Enforce Maximum Node Label Length

    When checked, strings that are displayed in node boxes will be truncated to Visual Graph Options | Node Labels | Maximum Node Label Length when longer. This is to keep node boxes small so that more of them will fit into a visual graph.

    When not checked, strings in node boxes will still be truncated to Visual Graph Options | Node Labels | Absolute Maximum Node Label Length, to avoid attempting to display any extremely long strings.

    Visual Graph Options | Node Labels | Absolute Maximum Node Label Length

    Strings that are displayed in node boxes will be truncated to this length even when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is disabled. This is to avoid attempting to display any extremely long strings.

    Visual Graph Options | Node Labels | Maximum Word Length in Node Boxes

    When drawing labels in node boxes in the graph view, if any single word (as delimited by spaces) is more than this number of characters long, then it will be allowed to split in the middle of the word, wrapping part of the word to the next line of text. This avoids having a very wide node box that interferes with graph layout.

    If this behavior is undesirable, set the value to a large number.

    Visual Graph Options | Node Labels | Show Full Label When Selected

    When checked, a node label string that would normally be truncated when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is enabled will not be truncated for the currently selected node (if any).

    This allows you to click on a node that has truncated text to expand that single node to show its full text. The node will also be brought to the front so that no other nodes can partially cover it.

    Visual Graph Options | Node Labels | Show Full Label When Under Mouse

    When checked, a node label string that would normally be truncated when Visual Graph Options | Node Labels | Enforce Maximum Node Label Length is enabled will not be truncated for a node that's under the mouse cursor.

    This allows you to move the mouse over various nodes that have truncated labels to make them momentarily expand to show their full text, until you move the mouse away. Each node that the mouse cursor enters will also be brought to the front so that no other nodes can partially cover it.

    Visual Graph Options | Link Labels | Draw Link Labels

    When checked, text labels are drawn near link lines to indicate which predicates they represent. This is the same string that will appear in a tooltip when the mouse cursor hovers over the link line.

    The layout algorithm does not make room for link labels, and so they sometimes will collide with other objects, including other link labels. For this reason, and to reduce clutter, and because there are tooltips and a legend that indicate the predicates for each line style, this option is not enabled by default. It does, however, have a simple keyboard shortcut (the M key) for toggling it on and off quickly. It may be most useful for toggling on now and then you need to check predicates.

    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.)

    Visual Graph Options | Link Labels | Draw Graph Link Labels Horizontally

    When checked, all link labels in the graph view will be drawn horizontally. Otherwise most link labels will be drawn along the link lines on platforms that support text at arbitrary angles. Currently link labels are always drawn horizontally on GTK (which is used on Linux and the Mac).

    Even when this option is not checked, some link labels will be drawn horizontally when heuristics suggest that the label will probably fit better that way.

    This command is present only in the graph view.

    Visual Graph Options | Link Labels | Draw Query Link Labels Horizontally

    When checked, all link labels in the graphical query view will be drawn horizontally. Otherwise most will be drawn along the link lines on platforms that support text at arbitrary angles.

    This option is separate from the one for the graph view because it may be optimal to use angled labels in the graph view where horizontal labels may not fit as well amongst the many nodes and links, but to use horizontal labels in the graphical query view where the sparser content is arranged by hand and where it is more important to be able to read all of the labels clearly.

    This command is present only in the graphical query view.

    Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse

    When checked, moving the mouse cursor over a node in the graph view will cause labels to appear for the predicates of the triples that are currently displayed for that node. The labels will appear just over the nodes that are linked with the node that is under the mouse, where there tends to be room to fit the labels in (and so this option may look neater than Visual Graph Options | Link Labels | Draw Link Labels).

    The labels will be drawn inside boxes, where the box color can be set with Visual Graph Options | Link Labels | Link Label Box Color. If the other node is the object of the triple, then the label above it will be of the form "Type", whereas if the other node is the subject then the label will of the form "is Type of". To avoid the awkward expression "is Sub Class Of of" for the subClassOf predicate, you may want to enable Global Options | Derived Node and Link Labels | Display subClassOf as "Superclass".

    Node tooltips will always be disabled when this option is on, because it is annoying when tooltips obscure the momentary predicate labels.

    This command is present only in the graph view.

    Visual Graph Options | Link Labels | Link Label Font

    This is the font in which all link labels are drawn, when enabled.

    The size of this font can be adjusted with the familiar Control-Plus and Control-Minus keystrokes when you are in the graph view. (The node label font will be adjusted along with it.)

    Visual Graph Options | Link Labels | Use Line Color for Link Labels

    When checked, each link label is drawn in the same color as the link line that it goes with. Otherwise all link labels are drawn in the single color that's set with Visual Graph Options | Link Labels | Link Label Color.

    This command is present only in the graph view. (The line color is always used in the graphical query view.)

    Visual Graph Options | Link Labels | Link Label Color

    This is the color in which all labels are drawn on link lines, when Visual Graph Options | Link Labels | Draw Link Labels is enabled.

    This command is present only in the graph view. (The line color is always used in the graphical query view.)

    Visual Graph Options | Link Labels | Link Label Box Color

    This is the color of the background of the boxes that appear around predicate labels when Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse 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.

    Visual Graph Options | Layout Options | Do Automatic Incremental Layouts

    When checked, operations such as displaying additional nodes or removing nodes from the display will automatically run the Layout | Update Layout Incrementally command. This is usually useful for keeping all of the nodes arranged in a relatively readable layout. But if you have explicitly placed nodes at meaningful positions, then you may want turn this option off.

    When unchecked, displaying additional nodes will still attempt to move only the new nodes to empty spots, though if this is not successful then they may end up on top of an existing node (when adding linked nodes) or at the mouse cursor position, and you may need to drag them elsewhere yourself.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Animate Layouts

    When 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.

    Visual Graph Options | Layout Options | Maximum Nodes for Animation

    If the total number of nodes in the visual graph exceeds this number, then layouts will not be animated even if Visual Graph Options | Layout Options | Animate Layouts is enabled.

    Visual Graph Options | Layout Options | Maximum Iterations for Full Layout

    This is the number of iterations at which a full layout will give up if it has not reached a solution. A full layout is done by the Layout | Redo Layout from Scratch command.

    If this limit is reached, the Layout | Update Layout Incrementally command can be used to continue the layout just as if this limit had been larger. Alternately, Layout | Make Canvas Larger could first be used to increase the chance of a successful layout.

    The default value is rather small so that layouts that are done interactively will not go on for a long time. If you want to do large layouts without waiting for them, for example, then you may want to increase this value a lot. The spring layout in particular does not know when it has taken a layout about as far as it can, and so will always tend to continue until it approaches this limit, so you may need to experiment with this limit for optimal spring layouts.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Maximum Iterations for Incremental Layout

    This is the number of iterations at which an incremental layout will give up if it has not reached a solution. An incremental layout is done by the Layout | Update Layout Incrementally command, and is also done automatically after various operations that change the displayed graph.

    The default value is rather small so that layouts that are done interactively will not go on for a long time. If you want to do large layouts without waiting for them, for example, then you may want to increase this value a lot.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Center After Full Layout

    When checked, the entire graph is shifted so that it is centered in the scrolling canvas after a full layout, as with the Layout | Center the Graph command. This can correct drift that tends to occur during a layout.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Center After Incremental Layout

    When checked, the entire graph is shifted so that it is centered in the scrolling canvas after an incremental layout. The window will not be automatically scrolled to the center, however, as with Layout | Center the Graph.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Compress After Full Layout

    When checked, an extra step is done at the end of a full layout to bring some nodes more toward the center of the graph so that the entire graph fits in a smaller area. The only drawbacks with this are that it takes a bit more time, and doing an incremental layout just afterward will not produce exactly the same result as continuing the original layout would have.

    The layout algorithm tends to fill the available space in the canvas so as to provide more "holes" into which nodes can be moved, and it doesn't know when it may be nearing a satisfactory solution. Therefore, nodes may end up scattered farther apart than desired without this option.

    When the spring layout algorithm is used, this option applies only to groups of nodes that are not connected with each other.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Compress After Incremental Layout

    When checked, an extra step is done at the end of an incremental layout to bring some nodes more toward the center of the graph so that the entire graph fits in a smaller area.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Honor Layout Direction Constraints

    This option determines whether the layout directions that have been specified for particular predicates are currently used by the layout algorithm. Once you have used Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate to specify the general directions in which some set of predicates should be laid out, you can toggle this option to quickly turn all of the layout direction constraints on or off.

    Using this command will not automatically redo the layout to reflect the new constraint. You will need to use either Layout | Update Layout Incrementally or Layout | Redo Layout from Scratch yourself after this command.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate

    Allows you to specify that the link lines that are displayed for a particular predicate should always be oriented in one general direction, either upward, downward, leftward, or rightward. For example, if you are displaying subClassOf links, you could specify that all subClassOf links should point upward only; that will cause all subclasses to be displayed below their superclasses.

    These specifications will be in effect only when the Visual Graph Options | Layout Options | Honor Layout Direction Constraints option is toggled on.

    A quicker alternative to this menu bar command is to right-click a link in the legend and use the "Specify Layout Direction" command on the shortcut menu there.

    The term "upward" basically means "more upward than downward", and so an upward link could still point East by Northeast, for example.

    It's possible to establish layout directions for multiple predicates, though each one makes the layout more difficult. In particular, the layout may not work well when any single node has many directional links. In the general case, a larger canvas or increased layout time may be required. It may also be desirable either to set Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy to a lower value, or else to set Visual Graph Options | Node and Link Spacing | Spacing Increment for Many Links to a higher value, since a directional link can be connected via only half of the circumference of a node.

    This command shows two dialogs. The first dialog shows a list of all predicates that have triples in the database for nodes that have been displayed during this browser session for the current triple-store. (It's the same list as is shown by Global Options | Select Current Predicates.) If you select a predicate, then the second dialog asks which of the four layout directions should be used for that predicate.

    Using this command will not automatically redo the layout to reflect the new constraint. You will need to use either Layout | Update Layout Incrementally or Layout | Redo Layout from Scratch yourself after this command.

    Use Visual Graph Options | Layout Options | Clear Layout Direction for a Predicate to clear layout directions that have been set up by this command. That will return to the default behavior where nodes are placed wherever they fit best, without regard to direction.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Clear Layout Direction for a Predicate

    Removes a specification for laying out all links for a particular predicate in one general direction. A dialog will show a list of all predicates that are currently being laid out in a single direction, and which are applicable to nodes that have been browsed so far. Choosing one allows the links for that predicate to once again be laid out in any direction.

    Note that the layout directions that have been set up by Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate are saved in your preferences file, and will continue to be in effect in future sessions until you remove them with this command.

    This command is present only in the graph view.

    Visual Graph Options | Layout Options | Canvas Resize Factor

    This is the factor by which Layout | Make Canvas Larger (or Smaller) will resize the scrolling canvas each time it is invoked. A larger value allows more quickly switching between very different canvas sizes, but a smaller value allows more accuracy in choosing a canvas size that is just large for a particular graph, in order to minimize the size of the rectangle that encloses all nodes.

    Visual Graph Options | Layout Options | Drag Scroll Zoom Factor

    This controls how fast the canvas will scroll when you click the background and drag the mouse. The number is the factor by which the mouse movement distance is multiplied to find the distance by which to scroll the canvas. A larger value lets you reach another part of the graph more quickly, but makes it harder to stop exactly where desired.

    Visual Graph Options | Layout Options | Mouse Wheel Zooms

    When checked, the mouse wheel will do zooming in the graph view, and otherwise it will do scrolling.

    When in zooming mode, the wheel performs the commands Layout | Zoom In (when pushed forward) and Layout | Zoom Out (when pulled backward). This is similar to using an airplane joystick. You can still scroll with the mouse by clicking on the background of the node pane and dragging in any direction while holding the mouse button down.

    When in scrolling mode, the wheel will scroll the visual graph vertically when used by itself, or horizontally when the control key is held down.

    Visual Graph Options | Layout Options | Include Legend in Saved Pixmaps

    When checked, File | Save Layout as Pixmap will include the legend in the saved image. Otherwise it will contain only the nodes and links from the graph pane.

    Visual Graph Options | Layout Options | Show Saved Layout Pixmaps

    When checked, File | Save Layout as Pixmap will display the pixmap that 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.

    Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout

    The number of nodes in the visual graph at which the layout will switch from a constraint-based algorithm that's used for smaller graphs to a spring algorithm that's used for larger graphs.

    The constraint-based algorithm specializes in avoiding any overlapping between nodes and links, to make it clear which nodes are linked by each link line. But that algorithm does not scale well, and so a spring layout is used for larger graphs to find a solution much more quickly, though it does not attempt to prevent nodes from overlapping link lines.

    This 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.

    Visual Graph Options | Spring Layout Options | Spacing Factor

    The value of this option is a small integer, where a larger value results in a visual graph with nodes that are spaced farther apart. It's difficult to tweak the algorithm to produce a desirable spacing for any graph, and so this value may need to be adjusted to personal taste or to the types of visual graphs that are done. The value may need to be larger for graphs that are larger or have many cycles in them.

    Visual Graph Options | Spring Layout Options | Velocity Divisor

    The value of this option is an integer, where a larger value results in a layout that is smoother (when animated) but which takes longer. A smaller value results in a layout that is "wilder" (when animated), but which may actually untangle crossed chains of nodes more successfully.

    Roughly speaking, the total of the distances from a node to its ideal positions relative to each of its linked or nearby nodes is divided by this number to find the amount by which its velocity is incremented at each iteration.

    Visual Graph Options | Spring Layout Options | Slowdown Exponent

    The value of this option is a small integer that affects how gradually or abruptly a spring layout will slow down before stopping. The velocities of nodes are deliberately dampened so that the layout can approach a final state and finally stopped. A lower value for this option will cause the layout to slow down more linearly (more gradually), while a larger value will cause it to maintain a speed that's closer to full speed over most of the layout, and then to slow down more abruptly toward the end.

    Visual Graph Options | Spring Layout Options | Grid Cell Size

    This is the width and height, in pixels, of an internal grid that's used to speed up spring layouts. A smaller value makes the spring layout faster, but as a tradeoff may degrade the layout results somewhat, especially by clumping nodes too closely together. To achieve the best feasible speed, trial and error could be used to find the smallest value that does not appear to degrade the layout quality for your layouts.

    This option works by dividing the canvas into a grid of cells and keeping track of which nodes are in each cell at any given time. Then when finding nodes that are close to each to make them repel each other, it looks only in the same cell and the neighboring cells of each moving node to consider only nearby nodes, rather than looping over all of the other cells, which scales badly.

    Two nodes that have many links may normally repel each other up to around 1000 pixels away (when zoomed in all the way), so the most conservative value would be around 1000. But in our tests layouts appeared not to be seriously degraded with values as low as 400, and so we set the default to a somewhat conservative value of 600.

    A lower value can also cause nodes that have more than a few links to annoyingly jump back and forth during animated layouts, even when that doesn't appear to hurt the final layout.

    Visual Graph Options | Spring Layout Options | Reduce Nodes Overlapping Links

    When this option is enabled, the spring layout algorithm will reduce the amount of overlapping between node boxes and link lines that tend to pass through them. This makes a more readable and neater-looking layout, but it takes something like twice as long. You could turn this option off for a faster layout, though then the algorithm will not attempt to keep nodes from overlapping link lines at all.

    Visual Graph Options | Spring Layout Options | Keep Nodes on Canvas

    When this option is enabled, nodes that get shifted out of the range of the current canvas will be forced back onto the canvas. That avoids not being able to see all of the nodes during an animated spring layout, though the layout might be somewhat better when this option is off to allow nodes to roam freely. By default a layout that roams out of the canvas will be brought back to the center of the canvas at the end of the layout, or you can use Layout | Center the Graph explicitly if needed to bring the whole visual graph back into view.

    Visual Graph Options | Constraint-Based Layout Options | Begin Full Layout at Random Positions

    This option affects only the constraint-based layout algorithm that's used for smaller visual graphs.

    When unchecked, Layout | Redo Layout from Scratch will begin with all nodes at the center of the visible part of the window, and it should produce the same layout every time.

    When checked, Layout | Redo Layout from Scratch will begin with the nodes distributed randomly within the visible part of the window, and it will produce a different layout each time.

    It may be useful to use this option to attempt several different layouts in order to choose the best one. It may also help to get a layout started more quickly if it has more than a few large leaf nodes, which can have trouble finding a place to move to from the center. In general, though, layouts may take a little longer and not be quite as good as when starting with all nodes at the center.

    This command is present only in the graph view.

    Visual Graph Options | Inclusion Options | Remove Orphans on Node Removal

    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.

    Visual Graph Options | Inclusion Options | Number of Total Links for Warning

    If a command is about to add nodes and links to the graph view, and the resulting total number of links in the graph view would be greater than this number, then a confirmation dialog is first shown asking if you want to proceed. This helps you avoid adding more links to the graph view than you expected, or more than could feasibly be laid out at the desired canvas size.

    If you proceed and there are more nodes and links than desired, you can still easily undo the operation with View | Go Back.

    The Inclusion Options child menu is present only in the graph view.

    Visual Graph Options | Inclusion Options | Number of Total Links for Abort

    If a command is about to add nodes and links to the graph view, and the resulting total number of links in the graph view would be greater than this number, then the operation is aborted and a dialog mentions that fact. This limit is most useful to avoid waiting until all of the resources that would be added are even found, since the Total Links for Warning limit will be triggered after all of the resources are found. The wait in the meantime could be substantial if a huge number of links would have been found.

    The Inclusion Options child menu is present only in the graph view.

    Visual Graph Options | Inclusion Options | Number of Links from One Node for Warning

    If a command is about to add nodes and links to the graph view, and the resulting total number of links from any single node in the graph view would be greater than this number, then a dialog is first shown asking if you want to proceed. This helps you avoid adding more links to a single node than you expected.

    If many links are added to a single node, the node will be split into multiple copies of itself to avoid a layout problem.

    The Inclusion Options child menu is present only in the graph view.

    Visual Graph Options | Inclusion Options | Show 1 Level of Nodes on Display Only Linked Nodes

    See Visual Graph Options | Show 2 Levels of Nodes on Display Only Linked Nodes immediately below.

    The Inclusion Options child menu is present only in the graph view.

    Visual Graph Options | Inclusion Options | Show 2 Levels of Nodes on Display Only Linked Nodes

    These options determine how many levels of nodes are added to the display when you use Link | Display Only Linked Nodes for the Current Predicates. 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 for the Current Predicates to see that node along with any that are linked with it. Only the most recently displayed nodes will remain on the display, rather than retaining all nodes that have been displayed so far.

    The Inclusion Options child menu is present only in the graph view.

    Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display

    This is the maximum number of triples that will be displayed by Display | Display Some Sample Triples and by Display | Display Triples of One Graph. To see a larger visual graph, increase this limit and then use the Display Some Sample Triples command.

    This option is used only when browsing an AllegroGraph store. When browsing a SPARQL endpoint instead, use Global Options | SPARQL Endpoints | Maximum Sample Triples to Display.

    The Inclusion Options child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Maximum Path Length

    This is the maximum length of any paths that will be found by Link | Display Paths Between Two Nodes or Link | Display Only Paths Between Two Nodes. The length is measured as the number of links in the path. The value should be an integer and should be at least 2 to provide functionality not available elsewhere.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Find Only Shortest Paths

    If this option is enabled, as it is by default, then the commands Link | Display Paths Between Two Nodes and Link | Display Only Paths Between Two Nodes will call the function all-bidirectional-search-paths to find the paths to display, and otherwise will call all-depth-first-search-paths. The former function is guarranteed to return a list of only the shortest paths that are found, and is probably the best choice in most cases to avoid sometimes returning an unwieldy number of paths.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Path-Finding Timeout

    This is the number seconds before the path-finding commands 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.

    Visual Graph Options | Finding Paths Between Nodes | Number of Found Paths for Warning

    If Link | Display Paths Between Two Nodes is about to add nodes and links to the graph view, and the number of found paths is greater than this number, then a dialog is first shown asking if you want to proceed. This helps you avoid inadvertently adding a huge number of nodes and links with that command.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Maximum Paths to Display

    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.

    Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Left and Right

    This option causes Link | Display Only Paths Between Two Nodes to pin the end nodes near the left and right edges of the window. This typically makes the paths clearer by stretching them more linearly between two edges of the window. Due to moving the end nodes, the automatic layout that's done is a full layout.

    The other path-displaying command, Link | Display Paths Between Two Nodes, never pins the end nodes.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes at Top and Bottom

    This option causes Link | Display Only Paths Between Two Nodes to pin the end nodes near the top and bottom edges of the window.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Place Path End Nodes Anywhere

    This option causes Link | Display Only Paths Between Two Nodes to not pin the end nodes, allowing them to be moved about freely by the automatic incremental layout that's done after placing the new path nodes on the display.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Finding Paths Between Nodes | Path End Node Margin

    This is the number of pixels between the edge of the graph pane and the end nodes of the paths that are found by Link | Display Only Paths Between Two Nodes, when that command pins the end nodes during the automatic layout.

    The Finding Paths Between Nodes child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing

    This is the minimum amount of space that the layout algorithm attempts to maintain between any two nodes in the displayed graph, measured in pixels. The number can be made smaller to save space, or larger for a less cluttered graph.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Minimum Link-to-Node Spacing

    This is the minimum amount of space that the layout algorithm attempts to maintain between any link line in the displayed graph and any node to which it is not connected, measured in pixels. Keeping link lines clearly away from unrelated nodes makes it easier to tell which nodes are connected to which.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Node Label Margin

    This is the number of pixels between the text in any node and the node's border. Use a smaller number to save space or a larger number for a cleaner look.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy

    This is the number of displayed links that a node may have before it is automatically split into multiple copies of itself. The multiple copies will be linked with each other by a special thicker link line.

    If this number is large, then a many-linked node can use up an overly large amount of screen space. The default is rather small to conserve screen space.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Spacing Increment for Many Links

    This is the number of additional pixels of spacing to require around a node for each of its links beyond the first four. When a node has many other nodes directly linked with it, the other nodes generally need to be positioned farther from the many-linked node in order for the layout to succeed. Otherwise some of the linked nodes will typically be placed near the many-linked node, thereby blocking a large angle through which other nodes could be linked.

    When a link has a layout direction constraint (see Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate), this increment is added doubly for that link to help accomodate the additional layout requirement.

    You may need to increase the value of this option if the layout is having trouble finding a solution when there are nodes with many links, especially if some of them have direction layout constraints. Or try decreasing Visual Graph Options | Node and Link Spacing | Maximum Links Per Node Copy.

    This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Add Spacing for Long Paths

    When this option is turned on, additional spacing will be required between any two nodes where the shortest path between them is relatively long, and similarly between any node and link-line. This usually results in a cleaner layout with unrelated clusters of nodes not so close to each other, and with fewer unnecessary crossed links.

    This option sometimes makes the layout require more iterations to complete. It also typically makes the layout take up a little more space.

    This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Long Path Spacing Increment

    This is used only when the Add Spacing for Long Paths option is enabled. This value is then the number of additional pixels of spacing to require between any two nodes for each link in the shortest path between the nodes beyond the first two links.

    For example, if this value is 15 and Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing is 12 (as they are by default), then two nodes that are just two links apart can be positioned with only 12 pixels of spacing between them. But two nodes that are three links apart will require 27 pixels of spacing between them, two nodes that are four links apart will require a spacing of 42 pixels, and so on.

    This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Long Path Maximum Spacing

    This is used only when the Add Spacing for Long Paths option is enabled. It is then the maximum number of additional pixels of spacing that will be added between two nodes (or between a link and a node) due to the length of the shortest path between them.

    This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Limit Outward Stretching

    This option limits the amount by which nodes may be moved outward toward the edge of the canvas during a layout. It tends to result in a smaller visual graph, but possibly could reduce the quality of a layout otherwise.

    If this option is turned off, you can still constrain the size of the layout with Layout | Make Canvas Smaller.

    This option is used only with the constraint-based layout algorithm that's used for smaller numbers of nodes. See Visual Graph Options | Spring Layout Options | Minimum Nodes for Spring Layout.

    The Node and Link Spacing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Spacing | Link Line Mousing Margin

    This is the distance from a link line within which the mouse cursor must be in order to be considered "on" the line. A larger value makes it easier to position the mouse on a link line (in order to see its tooltip or select it), but could lead to some ambiguity when mousable link lines are close together.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Flash Legend Matches

    If this option is enabled (as it is by default), then left-clicking an item in the legend pane to select it will cause any nodes or links in the graph layout that are matches for that legend item to "flash" a number of times. This makes it easier to spot the matching nodes or links.

    A node is flashed by dimming its background color and then undimming it. (The degree of dimming is determined by Visual Graph Options | Node and Link Flashing | Flashing Node Color Delta.) A link is flashed by making it thicker and then restoring its normal thickness.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Flash End Nodes of Found Paths

    If this option is enabled (as it is by default) when Link | Display Paths Between Two Nodes or Link | Display Only Paths Between Two Nodes is used, then the two end nodes for the paths will flash after the nodes and links for the paths are added to the display and the layout is updated. This helps to spot the requested end nodes after the layout updating likely moved them.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Flash Newly Added Nodes

    If this option is enabled (as it is by default) when a command on the Display menu is used to add a single new node to the display, then that node will flash momentarily to help you spot it. This is useful mostly when there are already a good many nodes on the display.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Flash Selected Search Matches

    If this option is enabled (as it is by default) when you select a particular matching node with Text Search | Search the Current View, then that node will flash momentarily to help you spot it.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Times to Flash

    This is the number of times that matching items in the graph layout will flash when an item in the legend pane is left-clicked, if Visual Graph Options | Node and Link Flashing | Flash Legend Matches is enabled.

    If this value is nil rather than an integer, then matching nodes or links will continue to flash indefinitely, as long as an item in the legend is selected. The only ways to deselect the selected item in the legend are to click the legend's background area or to press the Escape key when the legend pane has the keyboard focus.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Flashing Time Interval

    This is the number of milliseconds between flashing nodes or links on or off when Visual Graph Options | Node and Link Flashing | Flash Legend Matches is used.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Node and Link Flashing | Flashing Node Color Delta

    This is the amount by which to alter the background color of nodes in the graph layout when Visual Graph Options | Node and Link Flashing | Flash Legend Matches is used. The value should be a positive integer, and is subtracted from each of the red, green, and blue components of a node's background color, where each component of the color is an integer between 0 and 255 inclusive.

    The Node and Link Flashing child menu is present only in the graph view.

    Visual Graph Options | Tooltips | Show Node Tooltips

    When checked, a small informational pop-up window will appear whenever the mouse cursor lingers over a node, if that node's resource has an rdfs:comment property in the database. The comment string will appear in the tooltip window.

    Node tooltips are always disabled when Visual Graph Options | Link Labels | Draw Link Labels for Node Under Mouse is enabled.

    The Tooltips child menu is present only in the graph view.

    Visual Graph Options | Tooltips | Show Link Tooltips

    When checked, a small informational pop-up window will appear whenever the mouse cursor lingers over a link line. The tooltip window will list all of the predicates that that link line represents. This set of predicates is not necessarily all of the predicates for which there are triples in the database connecting the two resources, but is instead the set of predicates that you have requested to see in the graph view.

    If a number appears appears in parentheses at the end of the tooltip string, this indicates the number of redundant triples that are in the database for this particular subject, predicate, and object.

    Similar information is always shown in the status bar, though there may not be enough room there when a link line represents multiple predicates.

    The Tooltips child menu is present only in the graph view.

    Visual Graph Options | Tooltips | Tooltip Font

    This is the font that is used in the tooltip windows that appear in the graph view and the outline view.

    The Tooltips child menu is present only in the graph view.

    Visual Graph Options | Tooltips | Tooltip Background Color

    This is the background that is used in the tooltip windows that appear in the graph view and the outline view.

    Visual Graph Options | Tooltips | Node Tooltips Delay

    This is the number of milliseconds that the mouse cursor must linger over a node before its tooltip will appear. The default value is relatively long to avoid annoying tooltips appearing when you are trying to click on a node to select it.

    The Tooltips child menu is present only in the graph view.

    Visual Graph Options | Tooltips | Link Tooltips Delay

    This is the number of milliseconds that the mouse cursor must linger over a link line before its tooltip will appear. The default value is relatively short because there is not much other reason to linger over a link line, and because the predicates that are shown in the tooltip are not otherwise displayed in the graph view (except in the status bar, which may be some distance away).

    The Tooltips child menu is present only in the graph view.

    Visual Graph Options | Antialiasing | Antialias Lines

    This option has an effect only on the Windows platform.

    When enabled, link lines between nodes in the graph view are drawn using multiple shades of the line color to make the lines appear smoother. Arrowheads are drawn this way as well. This slows down the drawing somewhat.

    Visual Graph Options | Antialiasing | Antialias Text

    This option has an effect only on the Windows platform.

    When enabled, horizontal text in various places (in all views) is drawn using multiple shades of the text color to make the text appear smoother. This slows down the drawing somewhat.

    Antialiased text takes up a different amount of space (usually more), and so may warrant updating the layout after turning it on or off, as with Layout | Update Layout Incrementally.

    When ClearType is used on Microsoft Windows, it may be preferable to this somewhat fuzzy text antialiasing. But when ClearType is not available (such as by default when using Remote Desktop, for bandwidth reasons), this antialiased text may be preferable to non-ClearType text.

    Visual Graph Options | Antialiasing | Suppress Antialiasing During Animation

    This option has an effect only on the Windows platform.

    When enabled, lines and text will not be drawn in a smooth, antialiased way during animated layouts when they otherwise would be. Antialiasing slows down the drawing, which is particularly noticeable during animation.

    Visual Graph Options | Arrowheads | Arrowhead Length

    This is length of all arrowheads that are drawn in the graph view, measured in pixels.

    Visual Graph Options | Arrowheads | Arrowhead Width

    This is width of all arrowheads that are drawn in the graph view, measured in pixels at the base of the arrowhead.

    Visual Graph Options | Arrowheads | Draw Arrowtails

    Whether a stub is drawn on the non-arrowhead end of each link line in the graph view. This is useful to differentiate a link that is connected to the node from one that merely happens to be passing under the node.

    Visual Graph Options | Color Gradients | Show Node Color Gradients

    This option has an effect only on the Windows platform.

    When enabled, the background of each node box is drawn using multiple shades of its hue, varying the shade smoothly from lighter to darker from the top of the node to the bottom. This produces a pleasing pseudo-three-dimensional effect.

    Node color cannot be as light in this mode because of the need to keep the lightest part of the node within the maximum lightness while using the same hue over the whole node.

    This command is present only in the graph view.

    Visual Graph Options | Color Gradients | Color Gradient Intensity

    This option has an effect only on the Windows platform.

    This is the difference between the lightest and darkest shade of the gradient colors for each node, where 255 is the lightest value. A larger value produces a more noticeable gradient effect.

    A larger value tends to make most nodes darker, due to the need to keep the lightest shades from exceeding the maximum lightness value while using the same hue over the whole node.

    This command is present only in the graph view.

    Visual Graph Options | Color Gradients | Suppress Color Gradients During Animation

    This option has an effect only on the Windows platform.

    When enabled, node backgrounds will not be drawn with color gradients during animated layouts when they otherwise would be. This can speed up the animation somewhat.

    This command is present only in the graph view.

    Visual Graph Options | Color Nodes for Node Type

    When this option is in effect, the background color of each node in the graph view is determined by the rdf:type property of the node's resource, if any. (Also, a single color will be used for all literals, and another single color will be used for all non-literals that have no rdf:type property.)

    Initially colors will be assigned automatically for the types of any displayed nodes, but you can select the color to use for a type with Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type.

    If you abort the coloring of nodes by pressing Escape or Q, you can resume the coloring by selecting this option, even if it is already in effect. Otherwise node coloring will resume whenever you invoke any command that triggers node coloring.

    This command is present only in the graph view.

    Visual Graph Options | Color Nodes for Unseen Links

    When this option is in effect, the background color of each node in the graph view is determined by whether the node has additional linked nodes in the triple-store that are not currently displayed in the graph view. This tells you which nodes are worth selecting for use with the commands in the upper section of the Link menu for adding linked nodes.

    See About Node Background Color for Unseen Links in the middle of the documentation for the Link menu for details.

    If you abort the coloring of nodes by pressing Escape or Q, you can resume the coloring by selecting this option, even if it is already in effect. Otherwise node coloring will resume whenever you invoke any command that triggers node coloring.

    This command is present only in the graph view.

    Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color

    If this option is enabled, and a node has multiple rdf:type properties, then Gruff will attempt to find the "most specific" type of the node and then color the node to indicate that type. When this option is disabled, Gruff will arbitrarily choose one of the node's types. The most specific type is defined as the one that has the longest chain of superclasses above it, using the subClassOf predicate.

    This option is on by default because it typically doesn't use much time in an AllegroGraph store to find the most specific type. But the corresponding option that's used with SPARQL endpoints is off by default because the added time is typically greater with a SPARQL endpoint. That option is Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color.

    Another option for controlling which types are used for node colors, and which does not have a time cost, is Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color.

    Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color

    This option gives you more control over the colors that are used in the graph view to indicate the type of each node. If a node has multiple types, and some of them but not all are in this list of types to avoid using for node color, then one of the node's types that are not in this list will be used to color that node.

    When the dialog appears, enter the complete URIs of the types to avoid using, with one URI on each line. (It does not matter whether you include angle brackets.) It's best to place the types that should be most avoided toward the top of the list; the reason is that if all of a node's types are in this list of types to avoid, then Gruff will choose the type that comes latest in this list to use for that node's color.

    The types that you enter will be used only for the particular store that's currently open. So you can set up a different set of types for each store that you browse.

    An easy way to add a type to this list is to right-click the node that's shown for it in the legend (if it appears there) and select the command "Avoid This Type for Node Colors" from the pop-up menu.

    If Visual Graph Options | Node and Link Color for Types | Use Most Specific Type for Node Color is enabled, then Gruff may choose the most desirable types automatically in most cases. But this option may still be useful for further control, especially when a node has multiple types that are equally specific. Also, finding the most specific type for each node can be slow, especially with SPARQL endpoints, and so it may desirable for efficiency reasons to disable that option (which is actually Global Options | SPARQL Endpoints | Use Most Specific Type for Node Color when using a SPARQL endpoint) and use this one instead.

    See also Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color.

    Visual Graph Options | Node and Link Color for Types | Types to Prefer for Node Color

    This option gives you more control over the colors that are used in the graph view to indicate the type of each node. If a node has one or more types that are in this list, then one of those types will be used to color that node.

    When the dialog appears, enter the complete URIs of the types to prefer using, with one URI on each line. (It does not matter whether you include angle brackets.) It's best to place the types that should be most preferred toward the top of the list; the reason is that if more than one of the node's types are in this list, then Gruff will choose the type that comes first in this list to use for that node's color.

    The types that you enter will be used only for the particular store that's currently open. So you can set up a different set of types for each store that you browse.

    An easy way to add a type to this list is to right-click a node in the graph view and select "Select Preferred Type for Node Colors" from its pop-up menu.

    See also Visual Graph Options | Node and Link Color for Types | Types to Avoid for Node Color.

    Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type

    Lets you specify the background color in which to draw nodes that have a particular value for their rdf:type property. This color will be used only when the Visual Graph Options | Color Nodes for Node Type option is in effect.

    To use the command, first select a node and then invoke the command. A pop-up menu of all of the types of that node will appear. Select the type whose color you want to specify. A color-selecting dialog will appear.

    Alternately, right-click the node for the type in the legend pane, and select the command for assigning its color.

    The color that is used for a node will be the color for the most specific type property of the node to which you have assigned a color, if any, and otherwise will be a randomly-generated color for the most specific type for the node. The menu will list the types with the most specific type first. Type specificity is defined as the length of the longest chain of superclasses for the type.

    Visual Graph Options | Node and Link Color for Types | Remove Color Mapping for Selected Node's Type

    Lets you remove a mapping from a type to a color that you had specified at some earlier time. If the selected node has any type properties for which you have specified colors, then a pop-up menu of those types will appear. Selecting one will remove the color mapping for that type.

    A node's color will be determined by its most specific type for which there is a specified color mapping. Using this command on a more specific type allows the color for a less specific type property of the node to be used instead. This may be useful if too many colors are currently being used, by mapping a smaller set of more general types to node colors.

    This command is present only in the graph view.

    Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate

    Lets you specify the color in which to draw link lines that represent a particular predicate.

    To use the command, first select a link line by left-clicking on it and then invoke the command. The color dialog will appear to let you select a new color for the predicate that the link line represents.

    Alternately, right-click the link for the predicate in the legend pane, and select the command for assigning its color.

    A single color will be used for all link lines that represent multiple predicates. So if the selected link line represents multiple predicates, then the color that you select will be for all multiple-predicate link lines, and otherwise it will be for all link lines that represent the same single predicate as the selected link line. Another single color will be used for all bridge lines that connect multiple copies of a node that has many links.

    This command is present only in the graph view.

    Visual Graph Options | Node and Link Color for Types | Specify Line Width for Selected Link's Predicate

    Lets you specify the line thickness with which to draw link lines that represent a particular predicate. It presents a dialog with line widths between 1 and 9 inclusive, which is measured in pixels.

    This command is present only in the graph view.

    Visual Graph Options | Node and Link Color for Types | Specify Dashing for Selected Link's Predicate

    Lets you specify the dashing style in which to draw link lines that represent a particular predicate. It presents a dialog that lists all of the available dashing styles, from which you can choose a new style.

    This command is present only in the graph view.

    Visual Graph Options | Node and Link Color for Types | Suppress Link Line Styles

    Causes all link lines in the graph view to be drawn in the same way, using a solid gray line having a line width of 2 pixels. The link lines section of the legend will be removed as well, since all of the entries would look the same.

    Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Current Links

    This is the background color for nodes that have linked nodes in the triple-store for the current predicates that are not currently displayed. This color is used only when the Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type option is in effect.

    If a node is drawn with this background color, then you know that the Link | Display Linked Nodes for the Current Predicates command will add additional nodes to the display.

    (This color also happens to be reused in the table and query views for cells of predicates that are in the set of current predicates.)

    This command is present only in the graph view.

    Visual Graph Options | Node Color for Unseen Links | Node Color for Unseen Non-Current Links

    This is the background color for nodes that have linked nodes in the triple-store for non-current predicates that are not currently displayed. This color is used only when the Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type option is in effect.

    (This color also happens to be reused for variable nodes in the graphical query view.)

    This command is present only in the graph view.

    Visual Graph Options | Node Color for Unseen Links | Node Color for No Unseen Links

    This is the background color for nodes that have no linked nodes in the triple-store that are not currently displayed. This color is used only when the Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type option is in effect.

    (This color also happens to be reused for a couple of other things, namely (1) cells in the table view for objects that are currently in the visual graph in the graph view, and (2) non-variable nodes in the graphical query view.)

    This command is present only in the graph view.

    Visual Graph Options | Window Background | Graph View Background Color

    This is the color in which the general background of the graph view will be drawn. If the color is the standard light gray color (192 192 192), then it will actually use the system-wide button background color instead; this is the default.

    This value is not used if a background pixmap has been specified and Visual Graph Options | Window Background | Show Background Pixmap (if any) is enabled.

    This command is present only in the graph view.

    Visual Graph Options | Window Background | Legend Background Color

    This is the color in which the background of the legend pane in the graph view will be drawn. If the color is the standard light gray color (192 192 192), then it will actually use the system-wide button background color instead; this is the default.

    Visual Graph Options | Window Background | Background Pixmap

    Displays a dialog for selecting a pixmap file to provide a background image in the graph view. 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.

    Visual Graph Options | Window Background | Show Background Pixmap (if any)

    Determines whether the background pixmap is currently displayed in the graph view, if one has been specified with Visual Graph Options | Window Background | Background Pixmap. This command allows quickly toggling the image on and off (by pressing the "7" key on the main part of the keyboard).

    Using a background pixmap can slow things down, especially animation. When using remote display software such as Windows Remote Desktop, you will probably want to turn the background pixmap off.

    This command is present only in the graph view.

    Visual Graph Options | Window Background | Stretch Background Pixmap

    When checked, the background pixmap will be stretched to fill the current scrolling canvas size of the visual graph (if a background pixmap is being used). When unchecked, the pixmap will instead be replicated (tiled) to fill the canvas.

    This command is present only in the graph view.

    Visual Graph Options | Window Background | Graphical Query View Background Color

    This is the color of the general background in the Graphical Query View. It should be a light shade for best contrast with the content in the window.

    This command is present only in the graphical query view.

    Visual Graph Options | Node Border Color

    This is the color in which the lines on the edges of all node boxes are drawn.

    This command is present only in the graph view.


    The Help Menu

    Help | Show Documentation as HTML

    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.

    Help | Show Documentation as Plain Text

    Displays this help document as a plain text file. The file is doc.txt.

    Help | Use Web Browser for Menu Help

    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.

    Help | Show Warnings in Dialog

    When checked, all warnings and error messages will be shown in a modal dialog. Otherwise most warnings and error messages will simply be shown in the status bar.

    The modal dialog ensures that you do not miss the message, but requires a mouse click or keystroke to dismiss the dialog. When you have become very familiar with Gruff's warnings and errors, turning off this option may speed up your workflow.

    Help | Quick Start

    Displays a dialog with brief instructions for getting started with building visual graphs of nodes and links. This dialog is shown by default when Gruff is started up, though it has a check box at the bottom for disabling that default. You can use Gruff to follow this dialog's instructions while the dialog is present, though it may cover content that you need to see.

    Help | Show Quick Start on Startup

    An option for whether the Quick Start dialog will appear whenever Gruff is started up. It is on by default for new users, though typically you would disable it after working through the Quick Start once. You can disable this option either with this menu command or with the check box at the bottom of the Quick Start dialog itself.

    Help | Example Store Demo

    Creates a very small sample store showing some subclass relationships in the animal kingdom, along with who eats whom, and lays out the usual visual graph. This will first close the store that you currently have open, if any, though only if you confirm.

    Help | Animation Demo (Actors Store)

    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.

    Help | Display Store Info

    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.

    Help | About

    Displays the About dialog with the current Gruff version number. The version number is held in the variable *gruff-version*.


    Using Gruff Programmatically in a Lisp Application

    The documentation above describes using the standard Gruff browser as a standalone application to build a visual graph interactively and incrementally. Gruff can also be used as a fasl file that is loaded into an Allegro development lisp, and can be built into a standalone lisp application. This allows calling Gruff functions to build a visual graph with more complete programmatic control. If you have the fasl file, it will be called something like gruff-acl8.2.fasl or gruff-acl9.0.fasl, depending on which release of Allegro Common Lisp it was built for.

    For example, you could use your own lisp code to collect a set of triples that you would like to display as a visual graph, and then pass them to the function display-triples to display them in a single operation.

    This section of the Gruff documentation describes the lisp interface to Gruff. To instead control Gruff programmatically from applications that are written in ANY language, there is another API for sending HTTP requests to Gruff. See The HTTP Interface to Gruff.

    First a few general notes, and then the actual API.

    If you want, you can evaluate the example expressions in the order in which they appear below, which should work without doing anything else other than first loading AllegroGraph and the Gruff fasl file.

    All Gruff symbols below are exported from the "gruff" package, which has the nickname "uf" as well as (mostly for backward compatibility) the nickname "ab".

    Requirements for Loading the Gruff FASL File

    (1) 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:

  • Find the agraph.fasl that was built for the same version of AllegroGraph as the Gruff that you are going to load.
  • Load that agraph.fasl into lisp.
  • Evaluate the form (provide "agraph").
  • Finally load the Gruff fasl file.

  • Using the standard full browser or a plain graph layout pane

    When using Gruff programmatically, you can either create the complete standard interactive browser with all of its menu commands and alternate views, or create a plain window pane that acts like the 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.


    Adjusting the size of the canvas for the layout

    See the menu command Layout | Make Canvas Larger for an explanation of the need to adjust the canvas size to reasonably match the number of nodes and links in a visual graph.

    When using the programmatic interface rather than the menu commands, the canvas size can be adjusted by calling the Common Graphics function set-page-size. For example, the following call will adjust the size of the scrolling canvas of a node pane to be 1000 pixels wide by 800 pixels tall.

    (set-page-size *my-node-pane* 1000 800) 
    

    It is best to set the canvas size before calling update-the-layout or other functions that do a layout automatically. Some trial and error is needed to get a feel for the appropriate canvas size.


    Using the usual AllegroGraph functions to create or open a store

    When using the Gruff browser in a development lisp or application (even when using the full Gruff browser window with its menu bar), you don't need to use Gruff's File menu commands to create or open stores. You can do that programmatically using the usual AllegroGraph functions such as open-triple-store or create-triple-store followed by load-ntriples.

    But one issue is that if you create or open a store programmatically while the Gruff interface is viewing a previous store, then you need to either use the File | 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 Programmatic Lisp API to Gruff

    The symbols documented here are exported from the gruff package, which has the nickname "uf".


    display-triples

    Displays node pictures and link lines in a graph-node-pane for a set of triples, and then does a layout to arrange the nodes for readability.

    (defun display-triples
      (triples &key
               uncache-for-new-triple-store
               keep-old-nodes
               (layout-from-scratch (or uncache-for-new-triple-store
                                        (not keep-old-nodes)))
               node-upi-for-initial-position
               max-iterations
               select-window
               no-push-go-back-state
               no-regroup
               (node-pane (graph-node-pane (gruff-browser))))
    

    triples should be a list of triples that exist in the currently open store. You can use whatever means you like to derive the list of triples to be displayed, such as one or more calls to get-triples-list.

    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)
    

    display-upis

    Displays node pictures on a node pane for a set of subject and object UPIs, and adds link lines between them for a given set of predicate UPIs.

    (defun display-upis
      (upi-list &key predicate-upis
                     uncache-for-new-triple-store
                     keep-old-nodes
                     (layout-from-scratch (or uncache-for-new-triple-store
                                              (not keep-old-nodes)))
                     node-upi-for-initial-position
                     max-iterations
                     select-window
                     no-push-go-back-state
                     no-regroup
                     (node-pane (graph-node-pane (gruff-browser))))
    

    upi-list should be a list of subject and object part IDs of triples that exist in the currently open store. A node picture will be added to the node pane for each one. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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)
    

    display-upis-from-file

    Displays node pictures on a node pane for a set of subject and object UPIs that are listed in a file, and adds link lines between them for a set of predicate UPIs that are listed in the same file. This is like display-upis except that it reads the UPIs from a file instead of accepting them as arguments.

    (defun display-upis-from-file
      (path &key keep-old-nodes
                 select-window
                 (layout-from-scratch (not keep-old-nodes))
                 (node-pane (graph-node-pane (gruff-browser))))
    

    path is the pathname or path namestring of a file that contains the URIs of the nodes and links to display. The file should contain a list of URIs for nodes (subjects and objects), with one URI per text line, followed by a blank line, followed by a list of predicate URIs. All of the URIs should name objects that are in the currently open store.

    See display-triples for descriptions of the other arguments.

    Here is a small example of the contents of a file that could be passed to this function, after opening the dbpedia store.

    http://dbpedia.org/resource/Joanne_Woodward 
    http://dbpedia.org/resource/Paul_Newman 
    http://dbpedia.org/resource/The_Long%2C_Hot_Summer 
    
    http://dbpedia.org/property/starring 
    http://dbpedia.org/property/director 
    

    To display a set of triples from a file (rather than individual resources and predicates as with this function), you could use the usual AllegroGraph functions to create a new store and load triples into it, and then call the Gruff function display-store to display it.


    find-and-display-paths

    Displays nodes and links for all paths between two nodes that use certain predicates, up to a certain maximum path length. Returns the list of paths that were found.

    (defun find-and-display-paths
        (node-upi1 node-upi2 predicate-upis
                   &key (finder-function 'triple-store:all-bidirectional-search-paths)
                   (maximum-depth 4) warn-on-many-triples
                   uncache-for-new-triple-store keep-old-nodes
                   (layout-from-scratch (or uncache-for-new-triple-store
                                            (not keep-old-nodes)))
                   (end-node-placement (and layout-from-scratch
                                            :left-and-right))
                   node-upi-for-initial-position
                   max-iterations select-window no-push-go-back-state
                   (timeout 30)
                   (node-pane (graph-node-pane (gruff-browser))))
    

    node-upi1 and node-upi2 are the part IDs of the two resources and/or literals between which paths should be found. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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.


    display-paths

    Displays nodes and links for a set of paths that are specified as lists of nodes, for a particular set of predicates that link them.

    (defun display-paths (paths predicate-upis
                                &key warn-on-many-triples
                                uncache-for-new-triple-store keep-old-nodes
                                (layout-from-scratch (or uncache-for-new-triple-store
                                                         (not keep-old-nodes)))
                                (end-node-placement (and layout-from-scratch
                                                         :left-and-right))
                                node-upi-for-initial-position
                                max-iterations select-window no-push-go-back-state
                                (node-pane (graph-node-pane (gruff-browser))))
    

    paths is a list of lists of the part IDs of resources and/or literals, where each sublist should specify a sequence of nodes that are linked by the specified predicates. Typically this value would have been returned by one of AllegroGraph's social network path-finding functions such as all-depth-first-search-paths or all-bidirectional-search-paths. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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.


    display-linked-nodes

    Adds nodes to the display that are linked in the store to a particular specified node by any of the current predicates, and adds these links to the display. A link is also added to the display between any newly-displayed node and any newly-displayed or already-displayed node to which it is linked by any current predicate.

    (defun display-linked-nodes
      (from-node-upi &key (keep-old-nodes t)
                          (levels-to-add 1)
                          (deselect-selected-node t)
                          (exclude-explicitly-excluded-nodes t)
                          (node-pane (graph-node-pane (gruff-browser))))
    

    from-node-upi should be a part ID of a node that is already displayed on the node pane. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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*))
    

    display-store

    Displays node pictures and link lines in a graph-node-pane for some or all of the triples in the currently open store, and then does a layout to arrange the nodes for readability.

    (defun display-store
      (&key (limit 100)
            graph
            uncache-for-new-triple-store
            keep-old-nodes
            include-nodes-for-label-properties
            include-nodes-for-comment-properties
            (layout-from-scratch (or uncache-for-new-triple-store
                                     (not keep-old-nodes)))
            max-iterations
            select-window
            no-push-go-back-state
            no-regroup
            (node-pane (graph-node-pane (gruff-browser))))
    

    limit is the maximum number of nodes to add to the display. When limit is less than the number of triples in the store, then 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.


    remove-node-of-upi

    Removes the node picture for a UPI from the display, along with any link lines that are connected to it.

    (defun remove-node-of-upi
      (node-upi &key exclude
                     (node-pane (graph-node-pane (gruff-browser))))
    

    Removes a node picture that has been added to the display at some earlier time. Any link lines that are connected directly to the node picture are also removed (because otherwise they would be left pointing to nothing).

    node-upi should be a part ID of a node that is currently displayed (though if it is not found a status-bar message will simply indicate that). (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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*)
    

    remove-orphans

    Removes any orpan and/or leaf nodes from the display.

    (defun remove-orphans
      (&key leaves-too unhighlighted
            no-update no-warning
            (node-pane (graph-node-pane (gruff-browser))))
    

    This function removes from the display any nodes that are not connected to other displayed nodes by link lines, and optionally also any nodes that are connected to only a single other displayed node.

    If leaves-too is true, then leaf nodes (ones that are linked to exactly one other displayed node) are removed in addition to orphan nodes. If nil, then only orphan nodes (ones that are not linked to any other displayed nodes) are removed. Note that removing leaves may turn some remaining nodes into leaves, and so calling this function again may remove additional nodes.

    If unhighlighted is true, then a completely different thing is done, to remove all nodes except for ones that are highligted.

    If no-update is true, then no layout is done after removing the nodes. If nil, then an incremental layout is done.

    If no-warning is true, then no warning is shown in the status bar if there were no nodes to remove, and otherwise a warning will be shown. It may be useful to suppress the warning to avoid covering an earlier more important status bar message.

    See display-triples for a description of the node-pane argument.

    This function corresponds to the menu commands Remove | Remove All Orphan Nodes, Remove | Remove All Leaf Nodes, and Remove | Remove All Unhighlighted Nodes.


    remove-all-nodes

    Removes all nodes and links from the display. This is useful for clearing the display to begin building a new one.

    This function corresponds to the menu command Remove | Remove All Nodes.


    current-predicates

    Returns the current predicates as UPIs.

    (defun current-predicates () 
    

    Two values are returned, where the first is a list of UPIs of the predicates that will be used when a specified node is the subject of any triples that use those predicates, and the second being a list of UPIs of the predicates that are used when a specified node is the object of a triple.


    set-current-predicates

    Defines the set of predicates that are used by functions that use the current predicates.

    (defun set-current-predicates
      (predicate-upis &key (node-pane (graph-node-pane (gruff-browser))))
    

    Some functions and menu commands act on a set of current predicates. This is a convenience feature that allows specifying a set of predicates that are of interest a single time, and then making multiple calls to add nodes that are linked by those predicates.

    For example, if you call display-upis with the predicate-upis argument as nil, then it will add link lines to the display for any triples that link displayed nodes by these current predicates. And the function display-linked-nodes always uses the current predicates.

    predicate-upis should be a list of predicate part IDs. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<foo>".)

    See the example for display-linked-nodes.

    This function corresponds to the menu command Global Options | Select Current Predicates.


    highlight-node-by-upi

    Highlights or unhighlights a node that is on a node pane, by changing its background color.

    (defun highlight-node-by-upi
      (node-upi &key off (node-pane (graph-node-pane (gruff-browser))))
    

    Highlighted nodes are drawn with a light red background to make it easier to spot particular nodes. This function is like the menu command Select | Toggle Highlighting of the Selected Node or Link, except that you can specify an arbitrary node.

    node-upi should be a part ID of a node picture that is currently displayed on the node pane. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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.


    remove-all-highlighting

    Turns highlighting off for all node pictures that are currently displayed.

    (defun remove-all-highlighting
      (&key (node-pane (graph-node-pane (gruff-browser))))
    

    See display-triples for a description of the node-pane argument.

    This function corresponds to the menu command Select | Remove All Node and Link Highlighting.


    update-the-layout

    Arranges the nodes that are currently displayed to make the overall layout of nodes and links relatively readable.

    (defun update-the-layout
        (&key layout-from-scratch
              max-iterations
              fixed-node-upis
              deselect-selected-node
              compress-layout
              center-the-graph
              (node-pane (graph-node-pane (gruff-browser))))
    

    fixed-node-upis may be a list of part IDs whose node pictures should remain at their current locations during the layout, forcing other nodes to arrange themselves around those fixed nodes. If nil, then no node pictures will be fixed in place. (A part ID is either a UPI, a future-part, or a string in ntriples format such as "<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.


    center-the-graph

    Centers the graph as a whole in the window.

    (defun center-the-graph
      (&key (node-pane (graph-node-pane (gruff-browser))))
    

    This function first moves the whole set of displayed nodes and links as a group to the middle of the scrollable canvas of the node pane, and then scrolls the node pane to the middle of the canvas.

    The two options Visual Graph Options | Layout Options | Center After Full Layout and Visual Graph Options | Layout Options | Center After Incremental Layout cause this to be done automatically at certain times, but note that the option for centering after an incremental layout will scroll the window to the middle only if it was nearly scrolled to the middle before the layout. This function will always do it.

    See display-triples for a description of the node-pane argument.

    This function corresponds to the menu command Layout | Center the Graph.


    gruff-browser

    Returns the standard full Gruff browser, complete with its menu bar of interactive commands and its alternate views. If the browser does not exist currently, it is created automatically.

    (defun gruff-browser (&key expose exterior http-server-port disable-menus) 
    

    If expose is true, then the browser will be brought to the front and given the keyboard focus, whether or not the browser already exists. If nil, then it will come to the front only if it did not exist yet.

    The exterior argument can be passed to specify the screen coordinates of the Gruff window, if it is being created. The value should be a Common Graphics "box" object that specifies the left, top, right, and bottom edges, as created by a call like (make-box 100 100 800 600).

    The http-server-port argument may be an integer to tell Gruff to start up an HTTP server at that port, to allow controlling Gruff remotely with HTTP commands. See The HTTP Interface to Gruff.

    If disable-menus is true, then no menu bar or pop-up menus will appear, and their keyboard shortcuts will be disabled as well. This may be useful for preventing the end user from controlling Gruff interactively if you want to exclusively control Gruff with HTTP commands.

    The programmatic interface for graph layout can be used on the "graph view" node pane of the full browser, which is returned by this expression:

    (graph-node-pane (gruff-browser)) 
    

    Alternately you can make and use a raw instance of the graph-node-pane class. See "Using the standard full browser or a plain graph layout pane".


    graph-node-pane

    This symbol names both a class and a function.

    An instance of the class is a Common Graphics window on which node pictures and link lines are placed. Various Gruff functions take a graph-node-pane as an argument. You can use either the one in the standard full browser, which is returned by (graph-node-pane (gruff-browser)), or use a custom graph-node-pane instance that you create by calling the Common Graphics function make-window.

    See "Using the standard full browser or a plain graph layout pane".

    This symbol also names a function, which returns the "graph view" node pane of the standard full Gruff browser.

    (defmethod graph-node-pane ((window gruff-frame)) 
    

    This simply returns the descendent window of the standard full Gruff browser that is used for drawing visual graphs of nodes and links in the graph view.

    This child window is the default value for functions where a node-pane argument is needed, so you likely will not need to call this function yourself. Either you will be using the full Gruff browser and letting the node-pane arguments default, or you will be using your own instance of graph-node-pane and passing that node pane instead.

    The argument to this function should be the Gruff browser window that's returned by gruff-browser.


    save-layout

    Saves the current state of a visual graph, which can be loaded any time later with load-layout.

    (defmethod save-layout ((pane graph-node-pane) file) 
    

    pane is the graph-node-pane that is displaying a visual graph.

    file is the pathname or path namestring of the file into which to save the data.

    This function corresponds to the menu command File | Save Layout State.


    load-layout

    (defmethod load-layout ((pane graph-node-pane) file) 
    

    Loads a visual graph that was saved some time earlier with save-layout. The same store that was open when the save was done should be open when calling this function (or possibly another store that contains the same triples). Any triples in the saved state that are not found in the currently-open store will simply not be displayed.

    True is returned if the load was successful, and otherwise nil is returned. A return value of nil may indicate that the file does not exist or that it is not really a gruff layout file.

    pane is the graph-node-pane onto which to display the loaded visual graph.

    file is the pathname or path namestring of the file from which to load the data.

    This function corresponds to the menu command File | Load Layout State.


    save-layout-as-pixmap

    Creates a pixmap file containing an image of the currently-displayed visual graph. The pixmap will encompass all of the displayed nodes in the visual graph, even if they are scrolled out of view, adding a bit of margin around them all. 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.


    uncache-for-modified-triple-store

    Uncaches information as needed if the open store has been modified after displaying information from it in Gruff.

    (defun uncache-for-modified-triple-store () 
    

    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.


    uncache-for-new-triple-store

    Clears everything as needed to begin displaying a different triple-store in Gruff.

    (defun uncache-for-new-triple-store
      (&key (node-pane (graph-node-pane (gruff-browser))))
    

    Removes all nodes and links from the specified node pane, and clears information that has been cached about nodes and links in the current store. This is needed when creating or opening a different triple-store programmatically when the node pane is displaying objects from a previous store. This function is called automatically by the functions on the File menu of the standard browser, but otherwise needs to be called by an application that has created or opened a store in some other way after displaying information from another store.

    If you have simply modified the store that's being browsed, without removing any of the currently-displayed triples, then you could instead call uncache-for-modified-triple-store to avoid clearing the currently-displayed information.

    This function corresponds to the menu command File | Clear and Uncache Everything.


    gruff-options-path

    Returns the path of the file where your personal Gruff options are saved.

    (defun gruff-options-path () 
    

    If the standard Gruff browser window is used by calling gruff-browser rather than by creating a custom instance of the graph-node-pane class, then Gruff will save personal preferences from the various options menus of the standard browser. The options will be saved whenever the Global Options | Save All Options command is used, and also when the browser is exited. The saved options will be loaded when the standard browser is restarted.

    The expression (gruff-options-path) returns the path of the file where the option values are saved. This file could be deleted to revert all default options, including ones that are not reverted by Global Options | Revert to Default Options.


    *selected-node*

    A global variable whose value is the UPI of the most recently selected node in the graph view, or else nil if no node has been selected yet.

    This is intended as a handy way to get a programmatic handle on a resource or literal that appears in the interface. A debugging expression using this variable could be evaluated in a lisp listener of a development lisp, for example, after selecting the desired node in the graph view.


    *selected-link*

    A global variable whose value is the UPI of the most recently selected link in the graph view, or else nil if no node has been selected yet.

    If the selected link represents multiple predicates, then one of those predicates is chosen arbitrarily and its UPI is used.


    *suppressing-gruff-messages*

    A global variable that determines whether messages will appear in any ancestor window of a graph-node-pane that has a status bar at the bottom of the window. The value is nil by default, and Gruff binds it to t now and then.

    An application could bind this variable to a non-nil value while executing certain code where the status bar messages would be cumbersome. Or it could set the value permanently to a non-nil value to totally suppress status bar messages.


    *gruff-version*

    A global variable whose value is a string indicating the current version of Gruff. This value is shown in the Help | About dialog.


    Lisp Functions for Modifying User Options Programmatically

    The standard interactive Gruff browser has several menus for modifying a variety of user options interactively. There are also functions for reading and writing the option values programmatically. Each option is an accessor function of the graph-node-pane class.

    For example, the menu option Visual Graph Options | Node and Link Spacing | Minimum Node-to-Node Spacing uses the accessor function min-node-to-node-spacing. Evaluating the form (min-node-to-node-spacing my-node-pane) will return the current value, while (setf (min-node-to-node-spacing my-node-pane) 10) would set the value to 10.

    Here is a table of the various option menu commands and the accessor function that corresponds to each one. Refer to the documentation for each menu command for the meaning of the option.

      View | 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 String 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 | Query Results 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 String Font - query-string-font (font)
      Query Options | Query Timeout - query-timeout (integer)
      Query Options | Query Results Limit - query-results-limit (integer)
      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 String 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)
    

    Data formats of the option accessor functions

    The name of each option accessor function above is followed by a type designator in parentheses. The boolean, integer, and real types correspond to those lisp types. (For the boolean type, nil means no or off, while any other value means yes or on.) Here are the data formats for the other type designators:

    A color value is a list of three integers between 0 and 255 inclusive, for the red, green, and blue components of the color, such as (0 214 255).

    A font value is a list of four values for font family, font face, font size, and font style. These correspond to the values passed to the Common Graphics function make-font-ex. The family is rather obscure and generally can be nil. The face should be a string such as "Arial" or "Courier New". The font size should be an integer for the height of the font in pixels. The style is a list of style flag keywords such as (:bold :italic) for a font that is both bold and italic; use nil for the standard style.

    A file value is a string that names the complete path of a file.

    The label-property-language string should be a two-character string such as "en" for English or "ja" for Japanese.

    The directional-predicates list should be an association list that maps URIs to the four keyword symbols :upward, :downward, :leftward, and :rightward, and where each element is a proper list of two values, such as this:

      (("http://www.w3.org/2000/01/rdf-schema#subClassOf" :upward)
       ("PointsTo" :leftward))
    

    The custom-property-for-node-labels string should be a list of predicate URIs. (This option initially allowed only a single property, and the original function name has been retained for backward compatibility.)

    The 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)))
    

    The HTTP Interface to Gruff

    Gruff supplies an HTTP interface that allows applications that are written in any language to invoke several Gruff 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 string should be in the same format as a query string, though, with arguments separated by ampersands and an equals character joining each argument name to its argument value. Each argument value should still be percent-encoded, as with the GET method.

    An action command will always return a status string that indicates success or some type of failure, while a request for information will return the answer string directly unless there is a failure, in which case it will return a status string similar to those returned by action commands. The status string for a successul action command will always begin with the characters "success - ". If an action command or information request is specified incorrectly, then a status string beginning with "error - " will be returned. And if a command is specified correctly but Gruff fails to do what was requested (for example due to not finding a specified node or predicate in the store), then a status string beginning with "failure - " will be returned.

    Here are the HTTP commands that have been implemented.

    open-store (HTTP command)

    Opens a triple store, as with the interactive command File | Open Triple-Store.

    The arguments are store-name (required), access-mode (either local or remote, defaulting to remote 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.

    connect-to-endpoint (HTTP command)

    Connects to a SPARQL endpoint, as with the interactive command File | Connect to SPARQL Endpoint.

    The only required argument is endpoint-url, which should be the complete URL of the endpoint. Optional arguments are user and password, which are needed for private endpoints.

    Here's an example of connecting to the dbpedia SPARQL endpoint, where Gruff is running on a machine named hazel and has started its HTTP server on port 8008:

    http://hazel:8008/connect-to-endpoint?endpoint-url=http://live.dbpedia.org/sparql 
    

    That command won't actually work as written above, because the endpoint-url argument must first be percent-encoded so that its non-alphanumeric characters will not be interpreted as HTML syntax characters in the URI that it's inside. After percent-encoding that argument, the actual URI to send will look like this:

    http://hazel:8008/connect-to-endpoint?endpoint-url=http%3A%2F%2Flive.dbpedia.org%2Fsparql 
    

    store-info (HTTP command)

    Returns a specified attribute of the store that Gruff currently has open, if any, and otherwise returns the empty string. The only argument is attribute (required), which indicates which store attribute is being requested.

    The valid values of the attribute argument are type, store-name, access-mode, write-mode, host, port, and catalog. This command can be used to determine whether the store that you want to use is already open. The type value will be 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 
    

    query (HTTP command)

    Performs a SPARQL or Prolog query in Gruff, and optionally also lays out a visual graph from the results. The required arguments are language, which may be either sparql or prolog, and query-string, which should be the percent-encoded query string 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 string 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 string argument for transmission by HTTP:

    http://hazel:8008/query?language=sparql&layout=yes&query-string=select ?a ?b ?c ?x where {
        ?a ?x <http://dbpedia.org/resource/Jessica_Alba> .
        ?a ?x ?b .
        ?c ?x ?b .
        ?c ?x <http://dbpedia.org/resource/Brad_Pitt> . }
    

    And here is the actual percent-encoded string to transmit:

    http://hazel:8008/query?language=sparql&layout=yes&query-string=select%20%3Fa%20%3Fb%20%3Fc%20%3Fx%20where%20%7B%0A%20%20%3Fa%20%3Fx%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJessica_Alba%3E%20.%0A%20%20%3Fa%20%3Fx%20%3Fb%20.%0A%20%20%3Fc%20%3Fx%20%3Fb%20.%0A%20%20%3Fc%20%3Fx%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FBrad_Pitt%3E%20.%0A%20%20%7D 
    

    lay-out-triples (HTTP command)

    Creates and lays out a visual graph from an arbitrary set of triples that you specify by their triple IDs or by their URIs and literal strings.

    The only required argument is either triple-ids or ntriples. If triple-ids is passed, its value should be a set of triple ID integers that are separated by dashes. If ntriples is passed, its value should be a percent-encoded ntriples string (such as by taking the full contents of an ntriples file and then percent-encoding it). You may need to use the ntriples option if you don't have a way to find the triple IDs, which are internal to AllegroGraph.

    An optional argument is keep-old-nodes, which can be either yes or no, defaulting to no. If keep-old-nodes is yes, then the triples that were already displayed in the graph view are retained while the specified triples are added to the visual graph. If keep-old-nodes is no, then the graph view is first cleared of all triples before displaying the new ones.

    When passing the ntriples argument (rather than the triple-ids argument), the value will likely be too long for a GET request, in which case you should use a POST request instead, with the entire query portion of the request in the body of the request rather than after a question mark in the URI itself.

    The first example here uses triple IDs.

    http://hazel:8008/lay-out-triples?keep-old-nodes=yes&triple-ids=107537-166633-166645 
    

    Here's an example that uses the ntriples alternative, BEFORE percent-encoding the ntriples argument as needed. It specifies just three triples to lay out:

    http://hazel:8008/lay-out-triples?ntriples=<http://dbpedia.org/resource/Hand_of_Death> <http://dbpedia.org/property/starring> <http://dbpedia.org/resource/Jackie_Chan> . 
    <http://dbpedia.org/resource/Jackie_Chan> <http://www.w3.org/2000/01/rdf-schema#label> "Jackie Chan"@en .
    <http://dbpedia.org/resource/Dragon_Fist> <http://dbpedia.org/property/starring> <http://dbpedia.org/resource/Jackie_Chan> . 
    

    And here is that same example as you actually need to pass it, with the ntriples argument percent-encoded:

    http://hazel:8008/lay-out-triples?ntriples=%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FHand_of_Death%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan%3E%20.%0A%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan%3E%20%3Chttp%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23label%3E%20%22Jackie%20Chan%22%40en%20.%0A%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FDragon_Fist%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan%3E%20. 
    

    display-all-triples (HTTP command)

    Displays all triples of the store up to Visual Graph Options | Inclusion Options | Maximum Sample Triples to Display, as with the interactive command Display | Display Some Sample Triples.

    There are no required arguments. If the optional limit argument is passed, it should be a positive integer, in which case the option for the maximum number of triples to display will first be set, and then the command to display up to that many triples will be performed.

    http://hazel:8008/display-all-triples?limit=300 
    

    update-layout (HTTP command)

    Updates the layout of the nodes and links that are currently displayed in the graph view, as with the interactive commands Layout | Update Layout Incrementally and Layout | Redo Layout from Scratch.

    There are no required arguments. If the optional redo argument is yes, then the layout will be reworked from scratch. Otherwise the layout will be updated incrementally only as needed, starting from the current node positions.

    http://hazel:8008/update-layout?redo=yes 
    

    number-of-nodes (HTTP command)

    Returns the number of nodes that are currently displayed in the graph view. Values from 0 to one less than this number could then be passed as the index argument to the node-at-index command.

    http://hazel:8008/number-of-nodes 
    

    node-at-index (HTTP command)

    Returns the URI or literal string of a node that's currently displayed in the graph view. The only argument is index, which is required. The index should be between 0 and one less than the value that's returned by the number-of-nodes command, inclusive. You can find the values of all of the displayed nodes by sending this command repeatedly, once for each index in the range. A returned string could then be passed as the value of the node argument to various other HTTP commands.

    The returned string will be in ntriples format, meaning that a URI will contain embedded surrounding angle brackets, and a literal will contain embedded surrounding double-quote characters.

    http://hazel:8008/node-at-index?index=3 
    

    node-position (HTTP command)

    Returns the position and size of a node in the graph view, or moves the node to a specified position.

    The only required argument is node, which should be the URI or literal string of the node. If the x and y arguments are not passed (and it is an error pass one of those but not the other), then the returned status string will consist of four integers separated by spaces, where the numbers are the x and y coordinates of the center of the node, followed by the width and height of the node, for example "940 378 80 36". If the x and y arguments are passed, they should be integers that specify where to move the node.

    The x, y, width, and height values are all measured in pixels. The x value is the distance rightward from the left edge of the scrolling canvas to the horizontal center of the node, and y is the distance downward from the top edge of the scrolling canvas to the vertical center of the node.

    Here is how a command to move a node would look if you didn't need to percent-encode the node argument value:

    http://hazel:8008/node-position?node=http://dbpedia.org/resource/Jackie_Chan&x=1400&y=800 
    

    And here is how you must actually pass it, with the node argument percent-encoded:

    http://hazel:8008/node-position?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan&x=1400&y=800 
    

    select-node (HTTP command)

    Selects a specified node in the graph view, or deselects any selected node. There are no required arguments. If the optional node argument is passed, then that node is selected if it is found in the graph view. If no node argument is passed, then the selected node is deselected if there is one, as with the interactive command Select | Deselect the Selected Node and/or Link.

    Whenever a layout is done, the selected node will remain pinned. To allow all nodes to move during a layout, first deselect any selected node and unpin all nodes.

    When passing a node argument, it may be either a URI of a resource or else a literal string. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

    Here is an example before percent-encoding the node argument as needed:

    http://hazel:8008/select-node?node=http://dbpedia.org/resource/Jackie_Chan 
    

    And here is that example as you actually need to pass it, with the node argument percent-encoded:

    http://hazel:8008/select-node?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FJackie_Chan 
    

    selected-node (HTTP command)

    Returns the IRI or literal string of the node that's currently selected in the graph view, followed by the label string that Gruff is displaying for the node. If no node is currently selected, then the empty string is returned. There are no arguments.

    Only a single string can be returned from an HTTP command, so your code will need to parse the two logical strings apart. The two values will be separated by a space. The first value will be the "long" ntriples-format string for the node, which for a resource will be an IRI (which cannot contain spaces) and for a literal will be a string that contains embedded double-quote characters, such as "one two three"@en. (If the value is an IRI, the angle brackets are removed from the "long" ntriples-format string.)

    Therefore, the general rule for parsing apart the two returned values is this: If the string begins with a double-quote character, then divide it at the first space character after the second double-quote character, and otherwise divide it at the first space character.

    In this case, the example is the only way that this command can be specified:

    http://hazel:8008/selected-node 
    

    pin (HTTP command)

    Pins or unpins a single node or all nodes in the graph view, so that they don't move during layouts while pinned, as with the interactive commands Select | Toggle Pinning of the Selected Node and Select | Remove All Node Pinning.

    There are no required arguments. If a node argument is passed, then that single node will be pinned or unpinned, and otherwise all nodes that are currently displayed in the graph view will be pinned or unpinned. If the direction argument is passed as "off", then the node or nodes will be unpinned, and otherwise they will be pinned.

    When passing a node argument, it may be either a URI of a resource or else a literal string. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

    This example would pin Jackie Chan, after percent-encoding the node argument:

    http://hazel:8008/pin?node=http://dbpedia.org/resource/Jackie_Chan 
    
    This example would unpin all nodes: 
    
    http://hazel:8008/pin?direction=off 
    

    highlight (HTTP command)

    Highlights or unhighlights a single node or all nodes in the graph view so that they can more easily be spotted, especially when the layout changes. A highlighted node is drawn with a thick blue border. This corresponds to the interactive commands Select | Toggle Highlighting of the Selected Node or Link and Select | Remove All Node and Link Highlighting.

    There are no required arguments. If a node argument is passed, then that single node will be highlighted or unhighlighted, and otherwise all nodes that are currently displayed in the graph view will be highlighted or unhighlighted. If the direction argument is passed as "off", then the node or nodes will be unhighlighted, and otherwise they will be highlighted.

    When passing a node argument, it may be either a URI of a resource or else a literal string. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

    This example would highlight Natalie Wood, after percent-encoding the node argument:

    http://hazel:8008/highlight?node=http://dbpedia.org/resource/Natalie_Wood 
    
    This example would unhighlight all nodes: 
    
    http://hazel:8008/highlight?direction=off 
    

    remove (HTTP command)

    Removes either a specified node, the selected node (if any), all orphan nodes, all leaf nodes, or all nodes from the graph view. Either a node argument or a set argument should be passed, but not both.

    If the node argument is passed, it should be the percent-encoded URI or literal string of a node that is currently displayed in the graph view. If found, that node and its links will be removed from the displayed graph.

    If the set argument is passed, it should be either selected, orphans, leaves, or all. The value selected will remove the selected node if any, as with Remove | Remove Selected Node; orphans will remove all orphan nodes, as with Remove | Remove All Orphan Nodes; leaves will remove all leaf nodes and all orphan nodes, as with Remove | Remove All Leaf Nodes; and all will clear all nodes and links from the displayed graph, as with Remove | Remove All Nodes.

    http://hazel:8008/remove?set=leaves 
    
    http://hazel:8008/remove?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FNatasha_Henstridge 
    

    current-predicates (HTTP command)

    Returns or sets the set of current predicates, which are used by various Gruff commands. This is like the interactive command Global Options | Select Current Predicates.

    There are no required arguments. If the optional predicates argument is supplied, then the specified list of predicates will become the current predicates, and otherwise the set of current predicates will be returned.

    When specifying a set of predicates, they should be in ntriples format, meaning that a URI will have embedded surrounding angle brackets, and a literal will have embedded surrounding double-quote characters. There should be a space character between successive predicates, and then the whole value of the predicates argument must be percent-encoded. When not specifying new predicates, the current predicates will be returned in that format as well.

    Return the list of current predicates, as an ntriples string:

    http://hazel:8008/current-predicates 
    

    Set a couple of current predicates:

    http://hazel:8008/current-predicates?predicates=%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fdirector%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E 
    

    Here's the way that predicates argument value looked before percent-encoding it:

    <http://dbpedia.org/property/director> <http://dbpedia.org/property/starring> 
    

    display-linked-nodes (HTTP command)

    Adds nodes and links to the graph view to display any nodes that are linked with the selected node by the current predicates. There should already be a set of current predicates and a selected node. This is like the interactive command Link | Display Linked Nodes for the Current Predicates.

    There are no required arguments. If the optional keep-old-nodes argument is yes, then the new nodes and links will be added to the nodes and links that were already displayed. Otherwise all nodes and links will first be removed from the display.

    The optional levels-to-add argument indicates the number of levels of surrounding nodes to add, where 1 means to add only nodes that are directly linked with the selected node, and 2 means to also add nodes that are linked with those nodes. If specified, the value should be a small positive integer. The default value is the value of the levels-to-add-on-add-linked-nodes user option when keep-old-nodes is yes, or levels-to-add-on-display-linked-nodes when keep-old-nodes is no.

    If the optional allow-dialogs argument is yes, then any dialog windows that might appear to ask the user for further guidance will appear. Otherwise default behavior will be done instead, to allow Gruff to be controlled only by the HTTP interface with no interactive user. For example, a dialog may notify the user that there are many results, allowing the user to either display all of them, or to select a subset, or to cancel; when dialogs are not allowed, all of the results will be displayed.

    http://hazel:8008/display-linked-nodes?keep-old-nodes=yes 
    

    find-paths (HTTP command)

    Finds paths that link two specified end nodes via a set of specified predicates, and lays out a visual graph of all of the nodes and links that are in the paths. This is like the interactive command Link | Display Paths Between Two Nodes.

    The required arguments are node1 and node2, each of which should be the percent-encdoed URI or literal string of an end node to find paths between. A URI may either have embedded surrounding angle brackets or not, and a literal may either have embedded surrounding double-quote characters or not.

    An optional argument is predicates. If specified, it can be a set of predicate URIs, where the only paths that will be found are ones that use only those predicates. Otherwise it can be the string "current" to use the current predicates. If no predicates argument is passed, then paths are found using all predicates.

    When the predicates argument is a list of predicates, it should be in ntriples format, with each predicate URI enclosed in angle brackets (to facilitate parsing the list), as in <http://dbpedia.org/property/starring>. There should be a space between successive predicates, and then the entire argument value must be percent-encoded.

    Other optional arguments include keep-old-nodes, which may be yes or no to retain the nodes and links that are currently in the visual graph, or not (the default is no); max-path-length, which may be an integer specifying the maximum number of links that there may be in a path (the default is 4); and find-only-shortest-paths, which may be yes or no to indicate whether paths that are longer than others should be excluded (the default is yes).

    If many predicates are passed, then the query string 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 string as the body of the request, using the POST method.

    Here is a pseudo-example that shows how the request might look if you didn't need to percent-encode the argument values, and you were able to have newlines in the string. (This won't actually work.)

    http://hazel:8008/find-paths 
    ?node1=http://dbpedia.org/resource/Jack_Black 
    &node2=http://dbpedia.org/resource/Paul_Newman 
    &predicates=<http://dbpedia.org/property/starring> <http://dbpedia.org/property/director> 
    &max-path-length=4&find-only-shortest-paths=yes&keep-old-nodes=no 
    

    And here is how that query must actually be passed, with percent-encoding.

    http://hazel:8008/find-paths?node1=http%3A%2F%2Fdbpedia.org%2Fresource%2FJack_Black&node2=http%3A%2F%2Fdbpedia.org%2Fresource%2FPaul_Newman&predicates=%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring%3E%20%3Chttp%3A%2F%2Fdbpedia.org%2Fproperty%2Fdirector%3E&max-path-length=8&find-only-shortest-paths=yes&keep-old-nodes=no 
    

    Here is the predicates argument for using the current predicates:

    &predicates=current 
    

    option (HTTP command)

    Returns or sets the value of one of the user options. Currently every option whose value is an integer, float, or boolean value is supported; other options could be added later if needed.

    The only required argument is option, which should be one of the option command names listed below. If the value argument is also supplied, then the option will be set to that value, with the usual success/error/failure status string returned, and otherwise the current value of the option will be returned.

    For a boolean option, the value argument should be yes to turn the option on, or no to turn it off (and that yes or no string will be returned when not changing the value). An integer option value should be a simple integer string like 123. A float option value can be an integer string or a decimal string like 123.4.

    This first example would return the current path-finding timeout (as a number of seconds):

    http://hazel:8008/option?option=path-finding-timeout 
    

    This example would set the path-finding timeout to 12 seconds:

    http://hazel:8008/option?option=path-finding-timeout&value=12 
    

    And this would tell Gruff to start displaying link labels:

    http://hazel:8008/option?option=draw-link-labels&value=yes 
    

    To find which of the option names below is associated with a particular menu bar command title, see Lisp Functions for Modifying User Options Programmatically.

    Boolean Option Names

      add-spaces-to-labels
      add-spacing-for-long-paths
      animate-layouts
      antialias-lines
      antialias-text
      auto-font-switching-on-text-entry
      begin-with-nodes-at-random-positions
      capitalize-first-word
      case-sensitive-sorting
      center-after-full-layout
      center-after-incremental-layout
      collapse-contiguous-spaces-in-labels
      compress-after-full-layout
      compress-after-incremental-layout
      confirm-exit
      confirm-triple-deletion
      convert-percent-hex-in-labels
      create-all-outline-nodes-as-blank-nodes
      csv-file-include-column-headers
      csv-file-include-full-uris
      display-literals-of-all-languages-in-tables
      display-subclassof-as-superclass
      do-automatic-incremental-layouts
      draw-link-labels
      draw-link-labels-for-node-under-mouse
      draw-link-labels-horizontally
      draw-query-link-labels-horizontally
      enforce-max-node-label-length
      exclude-namespaces-from-labels
      find-only-shortest-paths
      find-remote-paths-on-server
      fit-row-height-to-text
      flash-end-nodes-of-found-paths
      flash-legend-matches
      flash-newly-added-nodes
      flash-selected-search-matches
      honor-layout-direction-constraints
      limit-outward-stretching
      new-log-file-for-each-session
      percent-decode-characters-for-editing
      percent-encode-non-ascii-after-editing
      percent-encode-non-ascii-in-queries
      prompt-for-commit-on-exit
      prompt-for-label-for-new-blank-node
      query-logging-enabled
      query-text-report-one-line-per-value
      query-text-report-show-full-uris
      reasoner-enables-restriction-reasoning
      remove-orphans-on-node-removal
      retain-pop-up-overview
      show-background-pixmap
      show-full-uris-in-outlines
      show-full-uris-in-pop-up-menus
      show-full-uris-in-tables
      show-full-uris-on-nodes
      show-legend
      show-link-tooltips
      show-menus-of-recent-namespaces
      show-node-color-gradients
      show-node-tooltips
      show-overview
      show-quick-start-on-startup
      show-warnings-in-dialog
      spring-layout-keep-nodes-on-canvas
      stretch-background-pixmap
      suppress-antialiasing-during-animation
      suppress-color-gradients-during-animation
      suppress-link-line-styles
      use-label-properties
      use-label-properties-in-tables
      use-line-color-for-link-labels
      use-query-planner
      use-web-browser-for-all-documents
      use-web-browser-for-menu-help
    

    Integer Option Names

      color-gradient-intensity
      default-arrowhead-length
      default-arrowhead-width
      finding-all-predicates-timeout
      finding-all-types-timeout
      flashing-interval
      flashing-node-color-difference
      get-triples-list-limit
      label-margin
      legend-width
      link-line-mousing-margin
      link-tooltip-delay
      long-path-max-spacing
      long-path-spacing-increment
      max-choices-when-selecting-a-subset
      max-iterations-for-full-layout
      max-iterations-for-incremental-layout
      max-links-per-node-copy
      max-menu-item-string-length
      max-node-label-length
      max-nodes-for-animated-layout
      max-path-length-for-add-paths
      max-paths-to-display
      max-triples-for-display-all-triples
      max-triples-per-predicate
      min-link-to-node-spacing
      min-node-to-node-spacing
      min-nodes-for-spring-layout
      node-tooltip-delay
      number-of-found-paths-for-warning
      number-of-links-for-abort
      number-of-links-for-warning
      number-of-radial-links-for-warning
      path-end-node-margin
      path-finding-timeout
      query-results-limit
      query-timeout
      spacing-increment-for-many-links
      spring-layout-slowdown-exponent
      spring-layout-spacing-factor
      spring-layout-velocity-divisor
      table-cell-vertical-padding
      times-to-flash
    

    Float Option Names

      animation-demo-delay
      canvas-resize-factor
      drag-scroll-zoom-factor
    

    set-color-for-type (HTTP command)

    Sets the color to use for the background of nodes in the graph view that are of a specified type. There are four required arguments, which are type-node, red, green, and blue.

    The type-node argument should be the percent-encoded URI of a node in the store that serves as the type of other nodes (specifically, as the object of rdf:type triples).

    The red, green, and blue arguments should each be an integer between 0 and 255 inclusive.

    This HTTP command corresponds to the menu command Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Node's Type.

    http://hazel:8008/set-color-for-type?type-node=http%3A%2F%2Fdbpedia.org%2Fresource%2FEmmy_Award_winners&red=255&green=192&blue=0 
    

    set-line-style-for-predicate (HTTP command)

    Sets the line style for drawing link lines in the graph view that represent a specified predicate. A required argument is predicate, which should be the percent-encoded URI of a predicate. You must also pass either the three arguments red, green, and blue, or one of the arguments width or dashing, or some combination of those three.

    Red, green, and blue should each be an integer between 0 and 255 inclusive. Width should be a small positive integer for the pixel thickness of the link line. Dashing should be one of the words solid, dash, dot, dash-dot, or dash-double-dot. You can specify just one of those three attributes, or any two, or all three.

    This HTTP command corresponds to the menu command Visual Graph Options | Node and Link Color for Types | Specify Color for Selected Link's Predicate and the related two options for the line width and dashing style.

    http://hazel:8008/set-line-style-for-predicate?predicate=http%3A%2F%2Fdbpedia.org%2Fproperty%2Fstarring&red=200&green=70&blue=0&width=2&dashing=solid 
    

    set-direction-for-predicate (HTTP command)

    Sets or removes the layout direction constraint for a specified predicate. A layout direction constraint causes any layout to attempt to point all link lines for the predicate in a particular direction, such as more upward than downward for subClassOf, to display a top-down hierarchy.

    The two required arguments are predicate and direction. The predicate argument should be a percent-encoded URI string, without surrounding angle brackets. The direction argument should be either leftward, upward, rightward, downward, or off. When the direction is off, the layout direction constraint for the specified predicate, if any, will be removed. For the other direction values, the direction constraint for the predicate will be set to that direction.

    This HTTP command corresponds to the menu bar command Visual Graph Options | Layout Options | Specify Layout Direction for a Predicate.

    Here is an example URI before percent-encoding the predicate argument as needed:

    http://hazel:8008/set-direction-for-predicate?predicate=http://www.w3.org/2000/01/rdf-schema#subClassOf&direction=upward 
    

    And here is the actual URI that you would need to use, with the predicate argument percent-encoded:

    http://hazel:8008/set-direction-for-predicate?predicate=http%3A%2F%2Fwww.w3.org%2F2000%2F01%2Frdf-schema%23subClassOf&direction=upward 
    

    save-layout (HTTP command)

    Saves the current state of the visual graph to a specified file, as with the interactive command File | Save Layout State, so that it can be loaded back in any time later. The only argument is file (required), which should be the percent-encoded path of a file to which the layout should be saved.

    http://hazel:8008/save-layout?file=c%3A%2Fgruff%2Fscary-movies.layout 
    

    load-layout (HTTP command)

    Loads a visual graph that was saved earlier with File | Save Layout State, and displays it in the graph view, as with the interactive command File | Load Layout State. The only argument is file (required), which should be the percent-encoded path of a layout file.

    This command could be used repeatedly to present a slideshow or animation of prepared layouts.

    http://hazel:8008/load-layout?file=c%3A%2Fgruff%2Fscary-movies.layout 
    

    save-layout-as-pixmap (HTTP command)

    Saves the current state of the visual graph to a specified file as a pixmap, as with File | Save Layout as Pixmap, so that it could be viewed in other programs. A file argument is required, which should be the percent-encoded path of a file to which the image should be saved.

    If the optional show argument is yes, then the saved pixmap will be displayed by another program. The other program will be either your default pixmap-viewing program or your preferred web browser, depending on the value of Global Options | Miscellaneous | Use Web Browser for All Documents.

    http://hazel:8008/save-layout-as-pixmap?file=c%3A%2Fgruff%2Fscary-movies.bmp&show=yes 
    

    set-canvas-size (HTTP command)

    Sets the size of the scrolling canvas in the graph view. This corresponds roughly to the interactive commands Layout | Make Canvas Larger and Layout | Make Canvas Smaller.

    The only arguments are x and y. When passed, they should be integers that measure the canvas in pixels. One or both of the arguments must be passed. If the canvas size is too small, then a layout is likely to fail, whereas if it much larger than needed then the layout may be spread out more than necessary.

    If an argument is less than the size of the window in that direction, then the canvas size will still be as large as the window, and so passing zero for both arguments (for example) will still allow the graph to fill the window but not extend beyond it.

    http://hazel:8008/set-canvas-size?x=2000&y=3000 
    

    center-the-visual-graph (HTTP command)

    Moves all nodes and links in the graph view to the center of the scrolling canvas, and then scrolls the window to the middle of the canvas, as with the interactive command Layout | Center the Graph. There are no arguments.

    http://hazel:8008/center-the-visual-graph 
    

    display-node-in-table (HTTP command)

    Displays all of the triples of a specified node in Gruff's table view. The only argument is node (required), which should be the percent-encoded URI of a node that's in the currently open store.

    http://hazel:8008/display-node-in-table?node=http%3A%2F%2Fdbpedia.org%2Fresource%2FNatalie_Wood