Plugins
Each plugin defines a specific functionality. To use this functionality one must create instances of the plugin. Some plugins do some background computing (e.g. PositionPacketNodePositioner), while others display something on the screen (e.g. SimpleNodePainter).
Usually there will be more than one visible instance to be displayed on the screen. Thus, one needs to define a ranking, which instance should be displayed on top of another. So some content of an instance in the background might be hidden by content of another instance. This is done in the Plugin overview of the Preferences Dialog (see below).
But there is also another advantage for the existence of this ranking. Some plugins may provide actions, if the user clicks on an object on the screen, e.g. the NodePainter opens or closes an extended view when the double-clicks on the node. It is always the topmost plugin instance that can handle those events, that catches the command and indeed handles the event. Since currently only the NodePainter handles events, this feature is more or less for future use.
On the page for general preferences one must define basic values especially for the relation between the position that the nodes send and their position on the screen. The unit of length is the unit that will be displayed on the preference pages of all plugins where parameters concerning any height or width must be set. It has no semantic effect, since SpyGlass expects all positions given with the packets in coordinates and this coordinates are generally interpreted unitless.
The scaling factor defines the scaling of coordinates per dimension. If e.g. an x-coordinate of a position received from a packet is 5 and the scaling factor of the x-dimension is 20, SpyGlass takes 100 as the real x-coordinate. The scaling factors of the two dimensions may be defined independently or may also associated to each other by activating the button with the chain. Then a change of one scaling factor automatically changes the scaling factor of the other dimension to the same value.
The offset defines the origin of the coordinates. The value of the x-axis is added to all x-coordinates received from a packet. It is the same for the offset of the y- axis and y-coordinates. If e.g. a packet contains a position (10,10), the x-offset is set to 50 and the y-offset is set to 80, then SpyGlass takes (60,90) as the real coordinates.
The real coordinates per dimension can be seen in the ruler on the drawing area. The ruler can be set to visible or invisible on the top of this page.
The button to restore the defaults sets all values to predefined default values. That is “m” as metric unit, 1 for the scaling and 0 for the offset in both dimensions.
The metric of time values are not used anywhere yet. So they are for future use. All values with respect to time have predefined time units in all current plugins.
There is a group of basic preferences which must be configured for all plugin instances. This is the instances name, at least one semantic type (if the plugin computes packages), the activity status and the visibility.
The name is used to reference to the instance, e.g. in dialog windows. The semantic types define, which packets will be delivered to this instance. "-1" means, that the instance will receive all packets independently from the semantic type. One can define a comma separated list of semantic types, a range or a combination of both, e.g. "3-5,8" is the same as "3,4,5,8".
If an instance is not able to compute a packet, because the payload is not suitable to the plugin, a warning or error window will appear at runtime.
An active plugin instance will receive all packets of the semantic types defined above. Thus, generally spoken "active" means, it computes packets. An instance does only display anything, if "visible" is set as well. So, if an instance is active but not visible, it computes the packets in the background.
Each plugin has a particular page to create instances. On the bottom of all of these pages, one can find the following buttons:
On this page one must configure the instance that shall be created. The config- uration can be saved as the new default configuration. The values of the default configuration will be set on this page whenever it is shown again or the button "restore default" is selected. A click on the button "create instance" creates an instance of the plugin with the specified configuration.
If one tries to enter illegal values into the configuration, the changes cannot be applied and a window pops up to tell the user about the mistake.
Each plugin instance gets its own entry in the plugin tree of the preference dialog window. Here one can either delete the instance or change its configuration. If the button "apply" is pressed, then the new configuration will be activated. If one made a mistake while changing the configuration, the old values can be restored with the button "restore values" until "apply" has been pressed.
Like on the page for the instance creation, illegal values cannot be applied.
The plugin overview page presents all plugin instances in a tabular form (see below). Here one can do some basic operations on the instances. At first one can change the order of the plugin. Each instance that is on top of another in this list will draw its content over all instances contents that should be displayed on the same position on the screen.
If e.g. an instance "SNP" of the SimpleNodePainter paints a node as a rectangle and a VectorSequencePainter instance "VSP" draws a line that crosses this rectangle, the line is drawn "behind" the node (i.e. is invisible) if "SNP" is above "VSP" in the list. Otherwise the line would be drawn above the rectangle. Thus especially BackgroundPainters should be on the bottom of this list in most cases. To change an instances position one must simply select the instance and click on "Up" or "Down".
The button "Reset instance" makes the instance to forget all past packets. It has the same effect like deleting the instance and creating a new one with the same values. "Delete instance" deletes the selected instance unrecoverably.
The next two buttons are to change the status of an instance. Their labels change automatically on demand.
SpyGlass plugins can be categorized according to what type of information they draw. The following list contains the bundled plugins grouped by their category type:
NodePainter plugins paint the actual node and any information that might be directly associated with them e.g., their internal state, sensor values, etc.
A NodePositioner collects and provides the information about the current po- sitions of the nodes in the network. Every incoming packet will be forwarded to the active NodePositioner instance. This instance grabs the nodes ID, its current position and the time, when the node sent the packet out of the packets header.
This information is available either until it is overwritten because the node sent a new packet or until the information times out. The time-out-interval must be set in the preference page of the instance. On the preference page one can decide, whether the instance is active or not. Since there can only be one active instance of the NodePositioner plugin, the current instance will be deactivated, when another instance is activated. The option “visible” cannot be set or changed since the plugin instance does not display anything anyway.
RelationPainter plugins paint relations between individual nodes. This may be e.g., the connectivity between two nodes, visualized by a simple line or e.g., the route from data sources to a sink, visualized by a vector sequence.
BackgroundPainter plugins paint information that usually is displayed in the background (i.e. "below" the information other plugin types draw).
GlobalInformation plugins are a special category of plugins that usually don't draw directly onto the canvas but use a specific part of the application window. Usually they present aggregate information in table form such as packets per second, average node degree, etc.