Getting Started

This section gives you an overview of ALVIS, including installation, work area, file format to store Alvis model and license.

A Java JRE 1.7 or higher required. ALVIS runs successfully on the most recent systems with Java installed on it. If your computer does not meet these requirements, you may not be able to use ALVIS. ALVIS home website, hosting information about current status of the project, is located a https://alvis.kis.agh.edu.pl/wiki/software. The current version of the tool can also be download from the website.

The ALVIS work area includes a diagram pane that displays graphic layer, hierarchy tree pane on the left side that helps you browse through the every distributed parts (called pages) of the diagram, code editor, and outline. Toolbars near the top of the window provide other controls that you can use to work with ALVIS model such as undo, redo, add agent and save/open ALVIS model.

1 - Main Menu. 2 - Toolbar. 3 - Multi-tab panel. 4 - Hierarchy Tree panel. 5 - Outline. 6 - Current cursor position. 7 - Work Area.

As you get acquainted with ALVIS, you can control over how your work area is arranged and displayed.

• To hide the outline, choose View > unchecked Outline.
• To change zooming, choose View > Zoom menus.
• To change display page view, choose View > Page Layout. A checkmark Page Layout indicates that the page with background is displayed (if not the web layout is displayed).
• To hide a grid, uncheck the View > Grid menu.
• To hide a ruler, uncheck the View > Rulers.

The main window has six items: File Menu, Edit Menu, View Menu, Format Menu, Alignment Menu, Help Menu. Each menu and its submenus is described below.

• New – Creates a new empty diagram and prompt before discard current diagram (if any);
• Open – Opens an existing diagram and prompt before discard current diagram (if any);
• Save – Saves the current diagram;
• Save As … – Save the current diagram with a new name;
• Export to EPS … – Export the current diagram into the EPS format;
• Export to SVG … – Export the current diagram into the SVG format;
• Export to PNG … – Export the current diagram into the PNG format;
• Page Setup - Customizes printer settings;
• Print – Prints the current page (without subpages);
• Preferences … – Displays the Preferences window;
• Exit – Exits the application.

• Undo – Undoes the last operation;
• Redo – Redoes the last undone operation;
• Cut – Cuts the selected elements to the clipboard;
• Copy – Copies the selected elements to the clipboard;
• Paste – Inserts the elements from the clipboard;
• Delete – Deletes the selected elements;

• Page Layout – Shows and hides page layout;
• Antialias – Turns on and off the antialias option;
• Grid – Shows and hides grid;
• Rulers – Shows and hides rulers;
• Zoom in – Zooms in on the diagram;
• Zoom out – Zooms out on the diagram;
• Page – Changes view layout – page or web layout;
• Width - Zooms the diagram to the page width size;
• Actual Size – Zooms the diagram to its width size;
• Outline – Shows and hides the outline;

• Direct to source – Changes the current connection direction (the connection will lead from target to source;
• Direct to target – Changes the current connection direction (the connection will lead from source to target;
• Undirect – Changes the current connection to bidirectional one;
• Line – Changes the current connection's style;

• Left – Lays out the selected elements to the left;
• Center – Centers the selected elements horizontally;
• Right – Lays out the selected elements to the right;
• Top – Lays out the selected elements to the top;
• Middle – Centers the selected elements vertically;
• Bottom – Lays out the selected elements to the bottom.

• About Alvis – Shows the application’s detail information dialog.
• Generate report – Generates the current model report.

ALVIS uses XML format to store Alvis diagrams. The structure of such file is defined by the following dtd:

<?xml version="1.0" encoding="UTF-8"?>

<!--
    Document   : aml.dtd
    Created on : 1 marzec 2008, 21:25
    Author     : ptm
    Description:
        Purpose of the document follows.

    TODO define vocabulary identification data
    PUBLIC ID  : -//ptm//alvis//EN
    SYSTEM ID  : http://server/path/alvis.dtd
-->

<!ELEMENT agent ( port+ ) >
<!ATTLIST agent id ID #REQUIRED >
<!ATTLIST agent parentID NMTOKEN #IMPLIED >
<!ATTLIST agent hierarchical NMTOKEN #REQUIRED >
<!ATTLIST agent name NMTOKEN #REQUIRED >
<!ATTLIST agent height NMTOKEN #IMPLIED >
<!ATTLIST agent width NMTOKEN #IMPLIED >
<!ATTLIST agent x NMTOKEN #IMPLIED >
<!ATTLIST agent y NMTOKEN #IMPLIED >
<!ATTLIST agent type NMTOKEN #REQUIRED >

<!ELEMENT code ( #PCDATA ) >

<!ELEMENT connection EMPTY >
<!ATTLIST connection source NMTOKEN #REQUIRED >
<!ATTLIST connection target NMTOKEN #REQUIRED >
<!ATTLIST connection direction NMTOKEN #REQUIRED >
<!ATTLIST connection style NMTOKEN #REQUIRED >

<!ELEMENT port EMPTY >
<!ATTLIST port id ID #REQUIRED >
<!ATTLIST port name NMTOKEN #REQUIRED >
<!ATTLIST port x NMTOKEN #IMPLIED >
<!ATTLIST port y NMTOKEN #IMPLIED >

<!ELEMENT hierarchy (node+)>

<!ELEMENT node EMPTY>
<!ATTLIST node agent NMTOKEN #REQUIRED >
<!ATTLIST node name NMTOKEN #REQUIRED >

<!ELEMENT page (agent+ | connection*) >
<!ATTLIST page name NMTOKEN #REQUIRED >


<!ELEMENT alvisproject ( hierarchy | page+ | code ) >

XML file stores both textual and graphical layers. Every simple page of diagrams is separeted from hierachy. The graphical layer is represented by hierarchy and pages nodes. First part of stored file describes hierachy, second one describes every single page. While we reconstruct model from file we create hierarchical tree with empty pages then we input body of pages into every page (node of tree). The textual layer is represented by code tag.

ALVIS is a free software covered by the GNU Library General Public License. The tool is being developed at AGH University of Science and Technology in Kraków, Poland. ALVIS home website, some details and current version, is located at https://alvis.kis.agh.edu.pl/wiki/software.

This chapter describes how to use ALVIS to create an Alvis diagram. When you start ALVIS, an empty diagram opens by default.

To open an existing file choose File > Open, or click the Open button on File Toolbar or use shorcut Ctrl + O. In the Open dialog box, select the file name, and click Open. Alvis files are usually identified with .alvis extension.

To add a new passive/active agent do one of the following:

• Click the appropriate buttons on the toolbar;
• Right-click on empty space in the modeled diagram and select the appropriate entry;

New agent has a default name Agent_x, where x is a incremented maximum value x of all other agents on the current page.

Fig. New agent Agent_0 was added to diagram using tool bar. The passive Agent_1 was added by right click on empty space of working area.

The agents' pop-up menu is used to manipulate agents' properties, e.g. adding new ports. To add a new port to an agent select Add port from its pop-up menu.

Double click the agent to change agents' name. Alternatively, you can use the F2 key. New name is also visible in the tree hierarchy.

Fig. Pop-up agents’ menu

The active agent has two additional features:

• The active agent at one level can be replaced by a page on the lower level, which usually gives a more precise and detailed description of the activity represented by the agent. To add a subpage to agent click Add Page from its pop-up menu. Hierarchical agents are indicated by black triangles at the bottom right corner.
• The active agent may be defined to start in Running state as shown in Fig. below. If agent is defined to start in running state then select Start in Initial State from its pop-up menu to define it to start in initial state.

Fig. Name of agent Agent_0 is underline. It means that Agent_0 starts in running state.

To remove an agent from the model select Delete from its pop-up menu or click Delete key. Once the hierarchical agent is selected, you also remove all of its subpages.

To add new port to agent right click on an agent and select Add port menu. The ports' name is by default port_x, where x is a incremented maximum value x of all other ports of the agent. Number of ports are not limited.

Fig. New ports added to the diagram

To change ports' name click the right mouse button on port and select Edit from its pop-up menu. Alternatively, you can use the F2 key.

Removing ports To remove a port right click on port and select Delete from its pop-up menu or press the Delete on keyboard. Removing a port will also remove all edges connected with it.

To create a connection click on the source port and drag the connector to the destination one. If the connection is valid destination port is green hightlight and it is placed onto the diagram.

Fig. Adding new connection between ports Agent_0 and Agent_1.

Fig. Connection between ports port_0 and port_2 is forbidden. Warning message is displayed when you try to add a wrong connection to the model.

Right click the connection to show pop-up menu (see Fig. below). It is used to set connections’ properties such as direction, style and to remove it. The direction of communication is is represented by end cap of line. Unidirectional communication is represented by flat line (with no arrows).

To remove an agent from the model select Delete from its pop-up menu or click Delete key.

For the effective modelling Alvis communication diagrams enable to distribute parts of the diagram across multiple subdiagrams called pages. Pages are combined using the so-called substitution mechanism. An active agent at one level can be replaced by a page on the lower level, which usually gives a more precise and detailed description of the activity represented by the agent. Such a substituted agent is called hierarchical one.

The hierarchy tree shows relation among every pages in the model. After a page is attached/remove to a particular agent, all changes made to the model will refresh hierarchy tree.

To add page to agent click the right mouse button on agent and select Add Page. In the input dialog type the name of the page. The name must be unique, and contain more than two latin characters. The copy page option causes the newly created page will be a separeted copy of the selected page (optional).

After adding a page, it will become currenty working page. A current working page is highlighted with an special icon.

Fig. Adding page to Agent_0.

To change pages' name, right click on hierarchical tree node and select Edit.

To remove page, right click on hierarchical tree node and select Delete.

The root System node cannot be edited and removed.

ALVIS includes various advance features, such as:

• Syntax highlighting for Alvis language
• Unlimited undo/redo
• Bracket matching
• Current line highlighting

Fig. Alvis Textal Layer

The hierarchy tree and the multi-tab panel located over working area, enables you to open multiple pages in a single instance of ALVIS. Double-clicking the mouse on any node in the tree to start editing choosen page. Alternately, you can open page by click name of page in multi-tab panel panel. A current working page box is highlighted with special icon.

You can switch to the sub-page of a hierarchical agent by click Go to child page from pop-up menu.

Fig. Navigation among pages of model.

The View menu and toolbar offer some tools to adjust the viewport of the current diagram. All of these tools have no effect on the geometry of the entities of the diagram. They only change the zoom factor and the visible area (viewport).

• The zoom in feature allows you to get a close-up view of the diagram. To perform zoom in, select Zoom In from the View menu.
• The zoom out feature allows you to see more of the diagram at a reduced size. To perform zoom out, select Zoom Out from the View menu.
• The zoom to Actual size feature allows you to view the diagram in its actual size (100%).

Instead hot keys are used for zooming on a page:

• Zoom In: Ctrl + Scroll
• Zoom out: Ctrl + Scroll

Fig. Presentation of zooming feature.

The ALVIS is equipped with Grid and Snap to Grid options. They allow for more precision in positioning elements on your diagram. When the Grid option is enabled (View > Grid), the elements can easily be positioned and resized along the grid interval. Alternatively, you can disable Grid feature.

The alignment options may be used to align elements in relation to other elements. Aligning elements in the diagram can be done with the use of alignment options in the Alignment menu. Alternatively, you can use the alignment icons form pop-up menu when you select more then one element (see Fig. below).

• Left – The option aligns elements according to the left border of the first selected element.
• Center – The option aligns elements according to the center of the first selected element (horizontally).
• Right – The option aligns elements according to the right border of the first selected element.
• Top – The option aligns elements according to the top border of the first selected element.
• Middle – The option aligns elements according to the center of the first selected element (vertically).
• Bottom – The option aligns elements according to the bottom border of the first selected element.

Fig. Alignment elements.

The ALVIS allows for exporting diagrams into EPS, SVG and PNG formats, which is helpful in documenting tested cases. To export your diagram into the desire format select File > Export to …. Only currently working page is exported.