Extensions:Uni-Verse/vcall

Introduction

This page describes the tool called "vcall". The purpose of vcall is to present a graphical user interface through which you can issue calls to Verse object node methods.

If you develop (or use) a method-call based system using Verse, vcall might be helpful since it allows you to fairly easily send method calls. This ability might make it possible to test a methods-driven engine before there are suitable custom user interfaces available.

For an example of a (large) such methods-driven engine based on Verse, see the Purple project. Unfortunately, Purple was developed before vcall. :)

Installation

This section describes how to get vcall running on your machine. First, you need to get the vcall source code, which is easiest from CVS. The name of the module is "vcall".

Requirements

Since vcall is written in Python, there is not much installation required of the program itself. You do, however, need a working Python environment, with the following external (3:rd party, i.e. not included in Python itself) libraries:

PyVerse

This is Brecht Van Lommel's most excellent wrapper of the Verse API in Python. It makes it possible to develop Verse clients using Python, which is a very pleasant choice sometimes.

PyGTK

PyGTK is a wrapper around the popular (at least in Linux) GTK+ user interface toolkit. It simply makes the GTK+ toolkit available for use from Python.

Exact details on how to install these libraries on your system depend on what kind of system you are using, and are left out of this document.

Running vcall

To start the vcall program on a POSIX system, simply invoke it by name, like this (from the directory where the code is):

 $ ./vcall.py

This will automatically call the Python interpreter on the source, and run the program. In other environments (Windows, maybe also Mac OS X?), it might be easier to double-click an icon representation of the program. The author has not tested these, so please forgive the scarcity of details.

Options

To control the initial behavior of the program, you can pass options to it. The following options are currently defined:

-ip=HOST[:PORT]

Controls the host address of the Verse server to use. The vcall client will try to connect to this address, and let you issue calls to the object nodes on it. If not specified, it will default to connecting to localhost.

User Interface

Being a graphical user interface client, vcall will open a window as soon as it can, and fill it with controls for the user to manipulate. The image below shows an example of how this window can look:

The window is divided into two main areas, separated by a draggable vertical bar:

• On the left, a tree shows the available object nodes, their method groups, and the methods contained in those groups.
• On the right, the currently selected single method gets presented with an interface that lets you assign values to the method's parameters. There is also a button to send a method call.

The Tree

As mentioned, the left part of the window contains a tree view. This view shows, from top to bottom hierarchy level:

• Each object node on the server, and if the node has method group(s):
• Each method group, and if the group has method(s):
• Each method.

Each of these gets shown using its server-side numerical ID, and its name, in the two columns of the tree.

You can manipulate the tree as with any other such view. Click the little triangles to expand or collapse the associated object node or method group, showing or hiding its contents accordingly. Click a method to make it current, and to switch the right side of the window to display a user interface for that particular method.

You can click the headers (the words "ID" and "Name" above the tree) to sort the tree on the clicked column.

You can search the Name column by just typing. The search is incremental, and will move the selection to the best current match, as you type. Press Escape to stop the search.

Argument Values

The right part of the window shows a user interface that presents controls for setting the parameters of the currently selected method (in the tree on the left).

At the top of the method area, the complete name and (in square brackets) the numerical "address" of the current method is shown. This is simply constructed as:

<node name>.<method group name>.<method name>() [<node id>.<method group id>.<method id>]

and is intended to complement reading in the tree (might be handy if the method group name is not visible due to there being a large number of methods).

Below the name, the method's parameters are listed from top to bottom. On the left is the name of the parameter (in bold, preceded by the type in a slightly smaller font), on the right is a control to set a value. The type of control given depends on the type; for numerical values you get spinbuttons, for instance. For a string-type parameter, you get a plain text entry box, and so on.

Once you are happy with the values you've entered into the controls, you can click the "Send Call" button at the bottom right part of the window. This will immediately send a call to the current method to the Verse server, using the values of the controls for the arguments.

If you switch to a different method, all values will be remembered and left untouched when you return.

On Destruction

If a node, method group or method is destroyed, it will immediately be removed from the tree. If the deletion means the current method no longer exists, the view will switch back to a "neutral mode", requiring you to manually select a new method to work with.

Limitations

• Sometimes the client gets confused when downloading information about which object nodes exist, and which have method groups. This might lead to existing nodes not showing up in the tree, and is thus rather crippling. It is often solved by just restarting the client. It will be investigated further.
• The user interface for selecting a node is not very user-friendly, since it requires you to enter the numerical ID of the desired node. Since such IDs are (at least in theory) session-local, this is a bit flimsy.
• Perhaps more advanced controls for editing matrix data would be useful. At the moment though, I'm not aware of any client that uses matrix-valued method parameters, so ...