====== Getting Started ====== This section gives you an overview of ALVIS, including installation, work area, file format to store Alvis model and license. ==== Installing ALVIS ==== 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. ==== Work Area ==== 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. {{:alvis:alvisemptyhighlignblue.png?600|}} 1 - Main Menu. 2 - Toolbar. 3 - Multi-tab panel. 4 - Hierarchy Tree panel. 5 - Outline. 6 - Current cursor position. 7 - Work Area. ==== Customizing the 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. ==== About Main Menu ==== 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. == File Menu == * 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. == Edit Menu == * 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; == View Menu == * 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; == Format Menu == * 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; == Alignment Menu == * 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. == Help Menu == * About Alvis – Shows the application’s detail information dialog. * Generate report – Generates the current model report. ==== Alvis Files Format ==== ALVIS uses XML format to store Alvis diagrams. The structure of such file is defined by the following dtd: 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. ==== License ==== 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]]. ===== Using ALVIS ===== This chapter describes how to use ALVIS to create an Alvis diagram. When you start ALVIS, an empty diagram opens by default. ==== Opening an Alvis model ==== 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. ==== Modelling single page ==== === Adding a new agent === 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. {{:alvis:alvisadingagent.png?600|}} 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. === Editing agents === 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. {{:alvis:alvisagentpopup.png?600|}} 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. {{:alvis:alvisagentinitialstate.png?600|}} Fig. Name of agent //Agent_0// is underline. It means that //Agent_0// starts in running state. === Removing agents === 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. === Adding ports to agent === 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. {{:alvis:alvisaddingport.png?600|}} Fig. New ports added to the diagram === Editing port === 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. === Adding connections === 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. {{:alvis:alvisaddingconnectionsucces.png?600|}} Fig. Adding new connection between ports //Agent_0// and //Agent_1//. {{:alvis:alvisaddingconnectionfail.png?600|}} 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. === Editing connection === 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). === Removing connection === To remove an agent from the model select Delete from its pop-up menu or click Delete key. ==== Modelling hierarchical tree ==== 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. === Adding page === 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. {{:alvis:alvisaddingpage.png?600|}} Fig. Adding page to //Agent_0//. === Editing/removing page === 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. ==== Writing textual layer ==== ALVIS includes various advance features, such as: * Syntax highlighting for Alvis language * Unlimited undo/redo * Bracket matching * Current line highlighting {{:alvis:alvistext.png?600|}} Fig. Alvis Textal Layer ==== Navigation ==== 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. {{:alvis:alvisnavigate.png?600|}} Fig. Navigation among pages of model. ==== Zooming ==== 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 {{:alvis:alviszooming.png?600|}} Fig. Presentation of zooming feature. ==== Aligning elements ==== 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. {{:alvis:alvisalignment.png?600|}} Fig. Alignment elements. ==== Export model ==== 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.