# Formalisms

#### Authors: J.Ferber, O. Gutknecht (c) 2001

##

1. What is a formalism
   1. Building a simple graphical formalism
   2. Adding behaviors to nodes and arrows
2. Formalisms files
   1. Header section
   2. Connector types section
   3. Node types section
   4. Arrow types section
   5. Action list section
3. The sedit-formalism DTD
4. Installed formalisms
   1. Automaton
   2. Logical gates
   3. Module based {{ou Module tutorial ???}}
   4. Petri
   5. Bric
   6. Tutorial
   7. MicroWorld serie {{???}}
      1. WarBot
      2. Preys

## What is a formalism

This documentation is still incomplete (well, it's a beta), but already provides most of the information needed to build a new formalism.

A formalism is a model definition that represent domain-specific nodes and links (i.e. UML models, Petri nets, logical gates, ...). A formalism is basically a list of nodes and links. It is possible to define basic properties for these elements and valid connections.

A SEdit formalism is defined as a XML file using our `sedit-formalism.dtd`. XML knowledge is not mandatory but reading some basic tutorial material will help (such as the XML FAQ).

Formalism files can be created and edited with any text editor. But it's definitively more convenient to use a XML editor (or something which knows to interpret DTD files). There is an interesting list of tools at . I personally use the Xeena Editor from IBM.

### Building a simple graphical formalism

In this section we will see how to define a new simple formalism without any behavior.

Here is the definition of a (very) small formalism, called tutorial1, which contains three node types and two arrow types.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE formalism SYSTEM "sedit-formalism.dtd">
    <formalism name="tutorial1" description="a simple tutorial example">
      <formalism-info>
        <author>Jacques Ferber</author>
        <author>Ol. Gutknecht</author>
      </formalism-info>

    <node-types>
      <node-desc name="round node" class="SEdit.SimpleNode">
          <icon url="images/place1.gif"/>
      </node-desc>
      <node-desc name="rectangular node" class="SEdit.SimpleNode">
          <icon url="images/transition1.gif"/>
          <graphic-element class="SEdit.Graphics.GRectangle">
              <property name="width">80</property>
              <property name="height">40</property>
          </graphic-element>
      </node-desc>
      <node-desc name="iconic node" class="SEdit.SimpleNode">
          <icon url="images/monalisa.gif"/>
          <graphic-element class="SEdit.Graphics.GIcon">
    		<property name="imageaddress">images/monalisa.gif</property>
    		<property name="width">40</property>
    		<property name="height">40</property>
    		<property name="labelLocation">4</property>
          </graphic-element>
        </node-desc>
      </node-types>

    <arrow-types>
      <arrow-desc name="link1" class="SEdit.SArrow"
                  description="A link from anything to anything">
          <icon url="images/arrowwithsharpedge.gif"/>
          <graphic-element >
             <property name="displaylabel">false</property>
             <property name="endingForm">2</property>
          </graphic-element>
      </arrow-desc>
      <arrow-desc name="link2" class="SEdit.SArrow" from="round node" to="round node"
                  description="A link from node1 to node1"/>
    </arrow-types>
    </formalism>

Here is an example of its use:

In this example, the general section, after the XML header, contains only some information about the name and description of the formalism, followed by the authors of the formalism.

Its node list section describes three types of nodes:

1. The first one, called `round node` is associated to the Java class `SEdit.SimpleNode` and its icon for the element palette can be found at the location `images/place1.gif` (an icon which is commonly used for describing places in automaton and Petri nets). And that's all!! All other properties are derived from default properties of SEdit nodes.
2. In the second the `<graphic-element ...>` tag add all the necessary information to describe the visual representation of elements in SEdit. Here, we see that this node is represented by the Java class `SEdit.Graphics.GRectangle` of width 80 and of height = 40 (size numbers are given in pixels).
3. In the third one, the node is visually represented on the screen by an icon, i.e. by an image stored in a .gif file whose location is given through the `imageaddress` property. Another property, the `labelLocation` property describes where the label of the element (i.e. its name) should be placed.

Its arrow list section contains two types of arrows, `link1` and `link2`. Globally the description of arrows is similar to that of nodes. There are two main differences:

1. In the graphic properties, there are the `startingForm` and `endingForm` properties which describes the beginning and ending shapes of arrows. The list of available shapes can be found here.
2. The `<arrow-desc ...>` tag contains two optional fields `from` and `to`. These fields are used to set some constraints on the source and target node. In our example, the `link2` arrow can only connect `round node` to `round node`.

### Adding behaviors to nodes and arrows

It is quite easy to provide some behavior to nodes and arrows, to simulate an operational model (as for Petri nets or finite state automata for instance), to compute some functions (as for logical gates for instance), etc..

To do so, one has to define classes in Java that derives (directly or indirectly via subclasses) from `SNode` for nodes and `SArrow` for arrows. See the following sections for more details.

## Formalisms files

In this section, we will provide all the details neccessary to understand and build your own formalism.

A formalism file is made of five section:

1. The header section
2. The connector types section
3. The node types section
4. The arrow types section
5. The action list section

### 1. Header section

The header section, after the general tags of any XML file, contains some global information about the formalism itself. It holds the mandatory `name` attribute which identifies the formalism, an optional `description` attribute and an optional `class` attribute which corresponds to the Java structure class. See {{link}} for more details on Java structures.

Information about the formalism is defined by the `<formalism-info>` tag. Here are the possible attributes:

- a list of authors, tag `<author>...</author>`
- a formalism documentation as a reference to an .html documentation page, tag `<doc url=...>`
- an icon representing the formalism (not used for the moment): `<icon url=...>`

Here is the header section of the Tutorial1 formalism.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE formalism SYSTEM "sedit-formalism.dtd">
    <formalism name="tutorial1" description="a simple tutorial example">
      <formalism-info>
        <author>Jacques Ferber</author>
        <author>Ol. Gutknecht</author>
      </formalism-info>

Here is the header section of the DataFlow formalism {{link}}. This header shows a documentation tag in the formalism-info section.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE formalism SYSTEM "sedit-formalism.dtd">
    <formalism name="DataFlow">
      <formalism-info>
        <author>Olivier Gutknecht</author>
        <doc url="http://www.madkit.org/mydoc.html"/>
      </formalism-info>

Here the header section of the Automaton formalism. This header shows a `class` attribute within the formalim tag, which expresses that SEdit should use the structure class `SEdit.Formalisms.Automaton.AutomatonStructure` instead of the standard `SEdit.Structure` class.

    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE formalism SYSTEM "sedit-formalism.dtd">
    <formalism name="automaton" description="Automate (et simulation)"
    	   class="SEdit.Formalisms.Automaton.AutomatonStructure">
      <formalism-info>
        <author>Jacques Ferber</author>
        <author>Ol. Gutknecht</author>
      </formalism-info>

### 2. The connector types section

{{to be finished}}

### 3. The node types section

#### General

The `<node-types>` section holds one or many `<node-desc>` definition. A simplistic `<node-desc>` tag only contains the `name` attribute, as for the following node types section which contains only the most simple node description:

      <node-types>
        <node-desc name="Process"/>
      </node-types>

A node description can also store information about the graphic element which can represent the node, configure default properties for both the node and its graphical representation, etc.. If a `class` attribute is set, SEdit will instantiate a specialized Java class for these nodes. A optional description attribute will allow for the documentation of the node and will appear as a tool tip in the element palette of a diagram editor window:

        <node-desc name="state" class="SEdit.Formalisms.Automaton.AutomatonState"
                   description="a state">
        </node-desc>

#### Graphic representation

Many information about visual appearance of may be associated to a node description. An `<icon url=..>` tag allows for the assocation of an icon to a node type. This icon will be used in the element palette instead of its name to refer to the node type.

A `graphic-element` tag may be used to describe the graphical representation of a node in the editor. This tag contains a `class` attribute which describes the Java class which should be used to display the node. By default, SEdit uses the class `SEdit.Graphics.GOval`. Values may be specified to properties of the graphic element. Standard graphic properties are `width`, `height`, `labelLocation` and `displayLabel`. The first three properties accepts integers while the latter accepts only boolean. All properties have default values (see the table below).

Here is the definition of a node which is represented as a rectangle of width 80, of height 40, which display its label (i.e. its "name") at

       <node-desc name="rectangular node" class="SEdit.SimpleNode">
          <icon url="images/transition1.gif"/>
          <graphic-element class="SEdit.Graphics.GRectangle">
    		<property name="width">80</property>
    		<property name="height">40</property>
    		<property name="displayLabel">true</property>
    		<property name="labelLocation">4</property>
          </graphic-element>
        </node-desc>

All graphic classes derives from the Java class SEdit.Graphics.GObject which describes the following attributes:

Name | Type of value | Default value | Description
width | integer | 40 | width of the node
height | integer | 40 | height of the node
displayLabel | boolean | true | show/do not show the label of the node
labelLocation | integer | 5 (CENTER) | specifies the location of the node label relative to the node

Here are the possible label locations. The default label location is 5 (Center):

Number | Position | Description
1 | RIGHT | the label is displayed on the right of the node
2 | LEFT | the label is displayed on the left of the node
3 | TOP | the label is displayed above the node
4 | BOTTOM | the label is displayed just below the node
5 | CENTER | the label is displayed in the middle of the node
6 | TOP_RIGHT | the label is displayed above and slightly on the right of the node

Here is the list of the general graphic representation classes which are provided for nodes.

- `SEdit.Graphics.GOval`: draws an oval (or a circle)
- `SEdit.Graphics.GRectangle`: draws a rectangle
- `SEdit.Graphics.GHexa`: draws an hexagon
- `SEdit.Graphics.GRoundedRectangle`: draws a rectangle with rounded corners. Add the properties `arcWidth` and `arcHeight` whose default values are: `arcWidth=40, arcHeight=60`.
- `SEdit.Graphics.GJavaComponent`: draws a Java component (in alpha release for the moment, use it at your own risks..).
- `SEdit.Graphics.GIcon`: draws an iconic representation of a node as a `.gif` image. Add the property `imageaddress` which contains the address of the `.gif` image file.

More Java graphic representation classes will be provided with future releases of SEdit.

Here is an example of a node which is represented as an icon:

        <node-desc name="iconic node" class="SEdit.SimpleNode">
          <icon url="images/monalisa.gif"/>
          <graphic-element class="SEdit.Graphics.GIcon">
    		<property name="imageaddress">images/monalisa.gif</property>
    		<property name="width">40</property>
    		<property name="height">40</property>
    		<property name="labelLocation">4</property>
          </graphic-element>
        </node-desc>

All graphical properties may be modified using the graphical property editor.

#### Properties on nodes

It is possible to add properties directly to nodes. Two properties are provided as standard: the `label` property and the `comment` property. The first one may be used to specify a general label to all nodes of a given type. The second one may be used to add comments to nodes.

It is quite easy to add new properties to node. A property is just a pair of "getter/setter" methods, generally associated to a class attribute, declared as public. For instance, in the Automaton formalism, the modification of the character associated to a transition is defined in this way in the `AutomatonTransition` class:

    public class AutomatonTransition extends SimpleNode
    {
              ........ // lot of code here...

        public char c='#' ; // the character the transition can read

        /**
           * Get the value of c.
           * @return Value of c.
           */
        public char getTransitionValue() {return c;}

        /**
           * Set the value of c.
           * @param v  Value to assign to c.
           */
        public void setTransitionValue(char  v) {
            this.c = v; setLabel(""+c);
        }
    }

#### Java actions on nodes

It is possible to add java actions to nodes. These actions will appear in the pop-up menu associated to a node (to learn how to trigger these actions from the editor see SEdit U ser manual/Using the diagram editor/Local actions on nodes and arrows).

To add an action to a node, in the Java class associated to that node, just create a Java method declared as `public` with no arguments and with return type `void`. Then add a tag of the form `<action description="nom methode">` within the node description of the formalism file. For instance, in the Automaton formalism, the validate method of the `AutomatonTransition` class is defined in the following way:

        public boolean activated=false;
        public String currentWord;

        public void validate()
        {
          if (activated){
             if (inArrows != null)
                for(int i = 0; i < inArrows.size(); i++)
                    ((AutomatonLink)inArrows.elementAt(i)).consume();
             if (outArrows != null)
                for(int i = 0; i < outArrows.size(); i++)
                   ((AutomatonLink)outArrows.elementAt(i)).produce(currentWord.substring(1));
          } else
             System.out.println("Error, non active transition!!");
        }

In the related formalism file, `automaton.xml`, the transition node is described as follows:

        <node-desc name="transition" class="SEdit.Formalisms.Automaton.AutomatonTransition">
          <icon url="images/transition1.gif"/>
          <graphic-element class="SEdit.Graphics.GRectangle">
    		<property name="width">10</property>
    		<property name="height">40</property>
          </graphic-element>
          <action description="validate">
    		<java-method name="validate"/>
          </action>
        </node-desc>

### 4. The arrow types section

The `<arrow-types>` section holds one or many `<arrow-desc>` definition. Arrow descriptions are very similar to node descriptions. Here are the differences:

1. For the moment, there is only one graphic class `GArrow` which is the graphic class used by default.
2. There are some new properties associated to the graphic class, relative to the shape of arrows ends.
3. It is possible to add constraints on the origin and destination of arrows with the `to` and `from` attributes (which must be set to already defined `node-desc` names).

For instance, here is the definition of the arrow types section of the Automaton formalism:

      <arrow-types>
        <arrow-desc name="link" class="SEdit.Formalisms.Automaton.AutomatonLink">
          <icon url="images/arrowwithsharpedge.gif"/>
          <graphic-element>
    	       <property name="displaylabel">false</property>
          </graphic-element>
        </arrow-desc>
      </arrow-types>

We can find the definition of the Java class associated to that node, the icon which is displayed in the element palette, and the `displaylabel` property which is set to false.

#### Graphic properties

It is possible to specify the shape of both starting and ending edge of an arrow. Just use the properties `startingForm` and `endingForm`, with an integer value corresponding to the following table:

Number | Shape | Description
0 | NOTHING | No shape.
1 | SHARPEND | Classic head arrow style, filled with plain black
2 | SQUAREEND | The head is drawn as a little square, filled with plain black
3 | ROUNDEND | The head is drawn as a little circle, filled with plain black
4 | DIAMONDEND | The head is drawn as a diamond
5 | WHITESHARPEND | Classic head arrow style, filled with plain white

Default values are the following:

     		<property name="startingForm">0</property>
    		<property name="endingForm">1</property>

There will be more shapes for arrows in future releases of SEdit.

It is also possible to specify an arrow without any joint (articulation point). To do so, use the property `lineStyle` with a value of 1. Default value of `lineStyle` is 0 which correspond to a line with a joint. Here is the definition of a direct arrow without any joint:

     		<property name="lineStyle">1</property>

#### Constraints

It is possible, from the formalism file, to specify the type of nodes that are accepted as origin or destination of arrows. To to so, just add the attribute `to` and `from` to the arrow-desc tag. For instance, to specify that an arrow or type `link` has as origin a node of type `typeNode1` and as destination (or target) a node of type `typeNode2`, do the following :

     	<arrow-desc name="link"
      		class="SEdit.SArrow" from="typeNode1" to="typeNode2"/>

The following figure shows an example (see the Tutorial2 formalism) of several types of arrows with different ending shapes, constraints and line style:

### 5. The action list section

The action list section define the set of global actions that are added to the user toolbar (see SEdit U ser manual/using the diagram editor to get an overview of the use of the editor). Adding a global action is similar to adding an action to a node. The main differences is that the Java method has to be defined in the Structure class of the formalism, and that it is possible to associate an icon, which will be displayed in the user toolbar, to that action.

For instance, in the Automaton formalism, the global action `run`, which activates the automaton, is declared in the formalism file as follows:

    <formalism name="automaton"
    	   class="SEdit.Formalisms.Automaton.AutomatonStructure">

           ....

      <action description="Run">
        <icon url="images/run.gif"/>
        <java-method name="step"/>
      </action>

and here is the definition of the `AutomatonStructure` which is merely dedicated to the definition of the `step` Java method.

    public class AutomatonStructure extends Structure {

        Vector activated=new Vector();
         ....
        public void step() {
           if ((activated != null) && (activated.size()>0)) {
             AutomatonTransition a = (AutomatonTransition)activated.firstElement();
             a.validate();
             activated.removeElementAt(0);
           }
        }
    }

## The sedit-formalism DTD

Here is the definition of the XML DTD of SEdit formalismst. It is possible to use a XML Editor to play with this DTD.

`<?xml encoding="US-ASCII"?> <!-- This SEdit-Formalisms DTD (c) 1999 by MadKit/SEdit Development Team --> <!-- Element descriptions --> <!ELEMENT formalism (formalism-info,connector-types?,node-types,arrow-types?,action*)>` `<!ELEMENT formalism-info (author+,doc?,icon?)>` `<!ELEMENT java-method EMPTY> <!ELEMENT scheme-function (#PCDATA)>` Not implemented yet`<!ELEMENT action (icon?,(java-method|scheme-function))> <!ELEMENT property (#PCDATA)> <!ELEMENT arrow-desc (icon?,graphic-element?,property*,action*)> <!ELEMENT arrow-types (arrow-desc+)> <!ELEMENT connector-desc (icon?,graphic-element?,property*)> <!ELEMENT connector-types (connector-desc+)> <!ELEMENT connector (property*)> <!ELEMENT module (connector*,property*)> <!ELEMENT icon EMPTY> <!ELEMENT graphic-element (property*)> <!ELEMENT node-desc (icon?,graphic-element?,module?,property*,action*)> <!ELEMENT node-types (node-desc+)> <!ELEMENT doc EMPTY> <!ELEMENT author (#PCDATA)> <!-- Attributes -->` `<!ATTLIST icon url CDATA #REQUIRED > <!ATTLIST java-method name NMTOKEN #REQUIRED> <!ATTLIST scheme-function name NMTOKEN #REQUIRED> <!ATTLIST action name NMTOKEN #IMPLIED description CDATA #REQUIRED > <!ATTLIST property name NMTOKEN #REQUIRED> <!ATTLIST arrow-desc name ID #REQUIRED description CDATA #IMPLIED class NMTOKEN #IMPLIED to IDREF #IMPLIED from IDREF #IMPLIED category NMTOKEN #IMPLIED > <!ATTLIST node-desc name ID #REQUIRED description CDATA #IMPLIED class NMTOKEN #IMPLIED category NMTOKEN #IMPLIED > <!ATTLIST connector-desc name ID #REQUIRED description CDATA #IMPLIED class NMTOKEN #IMPLIED mode (In | Out) #REQUIRED category NMTOKEN #IMPLIED > <!ATTLIST module type (Free | Fixed) #REQUIRED layout (Auto | Justified | Manual) "Auto" > <!ATTLIST connector type IDREF #REQUIRED name NMTOKEN #IMPLIED side (Left | Top | Right | Bottom) #IMPLIED ratio CDATA #IMPLIED > <!ATTLIST graphic-element class NMTOKEN #IMPLIED > <!ATTLIST doc url CDATA #REQUIRED > <!ATTLIST formalism name ID #REQUIRED description CDATA #IMPLIED class NMTOKEN #IMPLIED >`

## Installed formalisms

There are many predefined formalisms in SEdit. These formalismes may be used directly as such or serve as basis for the definition of more specialized formalisms.

Here is the list of predefined formalisms:

- Automaton
- Logical gates
- Module based {{ou Module tutorial ???}}
- Petri
- Bric
- Tutorial
- Preys
- Ant
- Warbot