SVF Programming Interfaces

Programs which read and display SVF files may wish to expose an API for working with the SVF information. In order to make this consistent across programs, the SVF Programming Interfaces (SPI) defines a set of interfaces that can be adapted for use across a variety of programming languages and environments.

Additionally, SVF Script uses a subset of SPI for a simple system of embedding commands in a hyperlink or notification. This allows the user to pick a hyperlink on an SVF file and have layers toggled or the view change. It is also designed so that it's very simple for an SVF viewer to parse. It's syntax is very similar to Javascript.

Interfaces

In the following interface descriptions, properties are values that can be examined and changed. Read-only properties can only be examined. Some programming may use slightly different syntax for accessing properties. For example, Java might use getFileMajor() to access the fileMajor property.

Methods are functions which perform an action on the information represented by the interface.

Most of the data types should translate easily into the programming language being used.

SVF

This is the main interface that is retrieved from the viewer. It provides access to the other interfaces. 

interface SVF
{
	properties:
		// version number of the SVF file
		int fileMajor;		(read-only)
		int fileMinor;		(read-only)
		// version number of the SVF Programming Interfaces being exposed
		int spiMajor;		(read-only)
		int spiMinor;		(read-only)

		// object which works with the current view
		SVFView view;		(read-only)
		// object which works with views stored in the SVF file
		SVFStoredViews storedViews;	(read-only)
		// object which works with layers
		SVFLayers layers;	(read-only)

	methods:
		// replaces the current SVF file with a new one
		boolean display(string url);
}

SVFView

Provides access to the current view and allows you to zoom and pan. 

interface SVFView
{
	properties:

	methods:
		// change current view so entire SVF is visible
		boolean extents();
		// change current view back to initial view
		boolean initial();
		// switch back to the previous view
		boolean previous();
		// change current view to match the given view from SVFStoredViews
		boolean set(string viewname);
		// zoom in (factor>1) or out (factor<1) around the given point
		boolean zoomFactor(float factor, int centerx,int centery);
		// change current view so given window (in SVF coordinates) fills display window
		boolean zoomWindow(int xmin,int ymin, int xmax,int ymax);
}

SVFStoredViews

Provides access to views stored in the header of the SVF file. You can switch to a particular view using SVFView.set(). 

interface SVFStoredViews
{
	properties:
		// the name of the given stored view
		string name(int viewindex);
		// find out how many views are stored in the SVF file
		int count;		(read-only)

	methods:
}

SVFLayers

Provides access to layer information and allows you to turn layers on and off. 

interface SVFLayers
{
	properties:
		// the name of the given layer
		string name(int layerindex);
		// find out how many layers are stored in the SVF file
		int count;		(read-only)
		// the visibility of the given layer
		boolean isVisible(string layername);

	methods:
		// change the visibilitiy of a set of comma delimited layer names
		boolean visible(boolean onoff, string layernames);
}

SVF Script

SVF Script is a subset of the SVF Programming Interfaces designed to be used in a hyperlink or notification. This allows simple manipulations of the file to be triggered by user actions. It is not intended to be a full programming language. If an SVF viewer wishes to allow more complex actions, it can expose the SPI to a language such as Javascript.

The portion of SPI used by SVF Script is essentially the methods plus the properties which provide access to other interfaces. Thus you can turn layers on/off or change the view, but you can't retrieve properties and pass them off to other functions.

In the URL attached to a hyperlink or notification in an SVF file, an SVF script command is prefaced with svfscript:. It assumes you are working with the SVF interface representing the current SVF file. Thus you start by referencing methods and properties for SVF. For example, svfscript:view.zoomExtents();.

Strings are enclosed in single quotes (') or double quotes ("). Function parameters are enclosed in parentheses. Multiple commands in the same URL are separated by semi-colons (;).

Supported commands:

Sample usage: