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.
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"?> |
Its node list section describes three types of nodes:
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:
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.
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:
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:
Here is the header section of the Tutorial1 formalism.
<?xml version="1.0" encoding="UTF-8"?> |
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"?> |
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"?> |
{{to be finished}}
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"> |
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"> |
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.
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"> |
All graphical properties may be modified using the graphical property editor.
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 |
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:
|
In the related formalism file, automaton.xml, the transition node is described as follows:
<node-desc name="transition" class="SEdit.Formalisms.Automaton.AutomatonTransition"> |
The <arrow-types> section holds one or many <arrow-desc> definition. Arrow descriptions are very similar to node descriptions. Here are the differences:
For instance, here is the definition of the arrow types section of the Automaton formalism:
<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.
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> |
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> |
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" |
The following figure shows an example (see the Tutorial2 formalism) of several types of arrows with different ending shapes, constraints and line style:
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" |
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 { public void step() { if ((activated != null) && (activated.size()>0)) { AutomatonTransition a = (AutomatonTransition)activated.firstElement(); a.validate(); activated.removeElementAt(0); } } } |
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> <!ATTLIST icon |
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: