root/gaphor-doc/trunk/diagram-model.php

<?php    $title = "Diagram elements and the Model";
    include "header.inc"; ?>

<p class="first">In contrast to applications like Rational Rose, Gaphor relies
heavily on diagrams. Since UML is a <i>graphical</i> language, all information
of your model should be visualized in the diagrams. 
Therefore those diagrams are the center of Gaphor's functionality.

<p>As a result of the visual oriented character of Gaphor, all new model
elements are created through the diagram interface. Gaphor will not follow
any specific development method which will increase its usability for
smaller projects.

<h2>Defining Model Elements</h2>

<p class="first">In UML all classes are inherited from <tt>ModelElement</tt>.
When creating diagram items we can try to use the same strategy:

<p class="image"><img src="images/diagram-model1.png" alt="1"><br>
Metamodel like inheritance structure.

<p class="first">However, we like to make use of the
<a href="http://diacanvas.sourceforge.net">DiaCanvas2</a> predefined classes
wherever possible. Those classes already have good support for &quot;undo&quot;
and other nifty features. 

<p class="image"><img src="images/diagram-model2.png" alt="2"><br>
Diagram structure using DiaCanvas2 classes.

<p class="first">The <tt>ModelElement</tt> (note that this is the
<tt>ModelElement</tt> diagram item, not the model object as defined by
the UML Metamodel) is now defined as base class for
every box-like element on a diagram (class, state, etc.). A
<tt>Relationship</tt> adds Gaphor specific behavior to the line. Line like UML
elements include associations, dependencies and state transitions.

<p><tt>ModelElement</tt>s and <tt>Relationship</tt>s handle their
<tt>subject</tt> in a different way:
<ul>
  <li>A model element is assigned one subject and holds it for as long
  as it exists.
  <li>A relationship does not hold a subject by default, it tries to find an
  existing data object if it is connected to a model element and releases the
  subject if it is disconnected (this will avoid the creation of a lot of
  objects with the same contents).
</ul>
<p class="first">One thing is typical about UML elements: they all contain
a lot of text. The <tt>TextField</tt> class is a simple diagram item that
holds a text shape and has the ability to change the text.
Simple text fields represent an attribute of its parents subject (for example
it's &quot;name&quot;). Editing the text will update the attribute and the
text will be updated in return.
For classes however, a text field can represent a data object (like an attribute
or an operation). It should be possible to connect comment fields too.

<h2>Model-diagram interaction</h2>

<p class="first">Since the <tt>UML</tt> module contains the data model it
should not know about anything diagram related (except <tt>UML.PresentationElement</tt>, which is defined in the meta-model). In the metamodel definition this
relationship is created between a model element and its representation:

<p class="image"><img src="images/presentationelement.png" alt="3"><br>
model element-representation relationship as defined my the UML MetaModel.

<p class="first">Gaphor will try to keep this relationship true, but some
tweaking has to be done... The <tt>PresentationElement</tt>'s are not part
of the <tt>UML</tt> module.

<p>If a model element is represented on a diagram a relation is created from
<tt>ModelElement</tt>s base class, <tt>Element</tt>, to the diagram item
representing the object.

<p class="image"><img src="images/gaphor-representation.png" alt="4"><br>
model element-representation relationship in Gaphor.
  
<p class="first">Note that the relationship is bidirectional. The code in the
diagram item will call <tt>Element.add_presentation()</tt> when it is assigned
a subject and <tt>Element.remove_presentation()</tt> when the diagram item is
removed from the canvas. If the last representation is removed from the model
element, it is <tt>unlink</tt>ed. When unlinking a model element all
relationships with other model elements are destroyed. The model element is not
actually destroyed since it might wants to reinstate itself when a diagram item
is &quot;undone&quot;.

<p>All diagram items have the <tt>subject</tt> property. This means that you
can always retrieve the model element that is represented by the item as
<tt>item.subject</tt>.
There is no reason for the diagram items to have the same inheritance
structure as the data model. The dependencies within the diagram module
are as shown below. The inheritance structure in the <tt>diagram</tt> module
is based on functional requirements of the diagram item.

<p class="image"><img src="images/diagramitems.png" alt="5"><br>
Diagram items.

<p class="first">Model elements like classes, use cases and comments all
represent one data object (<tt>subject</tt>). All objects that are not
line like objects will be inherited from <tt>ModelElement</tt> is possible.

<p><tt>Relationship</tt> contains all line like objects. Text fields may be
attached to the lines as is usually the case for <tt>Association</tt>s.

<p><tt>CommentLine</tt> is a special case: is creates a relationship between a
comment and a model element, but does not have a <tt>subject</tt>.

<?php include "trailer.inc" ?>