root/gaphor-doc/trunk/gaphor-internals.xml

<?xml version="1.0"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
    "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
>
<chapter id="chap-internals">
  <title>Working with <application>Gaphor</application>'s internals</title>

  <para>As stated before, <application>Gaphor</application> is completely
  written in <ulink
  url="http://www.python.org"><application>Python</application></ulink>. Well,
  completely... It makes use of the <ulink
  url="http://www.gnome.org">GNOME2</ulink> desktop environment. GNOME has
  powerful bindings for <application>Python</application>.</para>

  <section id="sect-datamodel">
    <title>Data model</title>

    <para>Lots of effort has been put in the creation of an easy to use and
    extensible data model. The data model supports:
      <orderedlist>
        <listitem><para>attributes, such as strings and integers</para></listitem>
        <listitem><para>associations, both uni- and bi-directional</para></listitem>
        <listitem><para>enumerations</para></listitem>
        <listitem><para>derived unions and redefined values</para></listitem>
      </orderedlist>
    These items will be refered to as <emphasis>properties</emphasis>.
    </para>

    <para>When a property changes, a signal is be emited. Other objects can
    attach signal handlers to the property owners (data objects) in order to
    be notified.</para>

    <note><simpara>When a property emits a signal, all redefine properties and derived
    unions also send a signal.</simpara></note>

    <para><application>Gaphor</application>'s data model is build from properties. This makes it easy to
    see which properties can be set on a model element and which can not.
    </para>

    <section>
      <title>Working with the data model</title>

      <para>The data model is designed so it is easy to retrieve all kinds of
      information from the data model. One can retrieve all possible properties
      of a class by simply typing (output is slightly modified to remove default
      properties):
        <screen>
          &gt;&gt;&gt; dir(Class)
          ['connect', 'attribute', 'clientDependency', 'disconnect', 'elementImport',
          'feature', 'general', 'generalization', 'importedMember',
          'inheritedMember', 'isAbstract', 'isKindOf', 'isLeaf', 'isTypeOf',
          'load', 'member', 'name', 'namespace', 'nestedClassifier', 'notify',
          'ownedAttribute', 'ownedComment', 'ownedElement', 'ownedMember',
          'ownedOperation', 'ownedRule', 'ownedUseCase', 'owner', 'package',
          'packageImport', 'postload', 'redefinedClassifier', 'redefinedElement',
          'redefinitionContext', 'save', 'substitution', 'superClass',
          'supplierDependency', 'unlink', 'visibility']
        </screen>
      Besides properties also a few default methods can be found:
        <variablelist>
          <varlistentry>
            <term>connect</term>
            <listitem><para>Attach (connect) a signal handler to an
            instance</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>disconnect</term>
            <listitem><para>Detach (disconnect) a signal handler.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>notify</term>
            <listitem><para>Notify all objects that attached to a specific
            signal. This is automatically done when a property changes.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>isKindOf</term>
            <listitem><para>OCL method. Same as <literal>isinstance()</literal>.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>isTypeOf</term>
            <listitem><para>Check if the <literal>type()</literal> is equal.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>load</term>
            <listitem><para>Load a given name-value pair. This is used for
            loading a model.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>postload</term>
            <listitem><para>Postload is called after all information is loaded.
            </para></listitem>
          </varlistentry>
          <varlistentry>
            <term>save</term>
            <listitem><para>Save a name-value pair. This is used to serialize
            (save) the object.</para></listitem>
          </varlistentry>
          <varlistentry>
            <term>unlink</term>
            <listitem><para>End the life cycle of an object. Unlink removed all
            relations with the object.
            </para></listitem>
          </varlistentry>
        </variablelist>
      Exept for those methods, all other fields are properties of the data
      object.
      </para>

      <para>It is pretty easy to find out what type of object could be
      connected to an attribute:
        <screen>
          &gt;&gt;&gt; print Class.name
          &lt;attribute name: &lt;type 'str'&gt;[0..1] = None&gt;
        </screen>
      </para>
      <para>An association displays similar results:
        <screen>
          &gt;&gt;&gt; print Class.ownedAttribute
          &lt;association ownedAttribute: Property[0..*]&gt;
        </screen>
      This shows the definition of <property>Class.ownedAttribute</property>. It
      has a uni-directional to zero or more <classname>Property</classname>
      objects.
      The following code shows a bi-directional association:
        <screen>
          &gt;&gt;&gt; print Class.generalization
          &lt;association generalization: Generalization[0..*] -&gt; specific&gt;
          &gt;&gt;&gt; print Generalization.specific
          &lt;association specific: Classifier[1] -&gt; generalization&gt;
        </screen>
      </para>

      <para>One of the more advanced features of the data model are derived
      unions (which show a <literal>/</literal> before their name and
      redefined properties (which carry a <literal>{redefine}</literal> tag).
      A derived union is a gathering of one or more other properties. a
      redefined property is some sort of alias.  In the following example a
      <classname>Class</classname> object is added to a
      <classname>Package</classname>.
        <screen>
          &gt;&gt;&gt; p = Package()
          &gt;&gt;&gt; c = Class()
          &gt;&gt;&gt; c.package = p
          &gt;&gt;&gt; c.package
          &lt;uml2.Package object at 0x00815020&gt;
          &gt;&gt;&gt; c.owner
          &lt;uml2.Package object at 0x00815020&gt;
          &gt;&gt;&gt; c.namespace
          &lt;uml2.Package object at 0x00815020&gt;
          &gt;&gt;&gt; p.ownedClassifier
          [&lt;uml2.Class object at 0x008166F0&gt;]
          &gt;&gt;&gt; p.ownedElement
          [&lt;uml2.Class object at 0x008166F0&gt;]
          &gt;&gt;&gt; p.ownedMember
          [&lt;uml2.Class object at 0x008166F0&gt;]
        </screen>
      Besides <property>package</property> also the
      <property>namespace</property> and <property>owner</property> properties
      of the <classname>Class</classname> are set. Well, they are not actually
      set, they are derived values from <property>c.package</property>.  The
      same thing happens for <property>Package.ownedClassifier</property> (the
      opposite side of <property>package</property>).</para>
    </section>

    <section>
      <title>Extensions to the data model</title>

      <para>A few changes have been made to <application>Gaphor</application>s implementation of
      the Metamodel. First of all some relationships have to be modified
      since the same name is used for different relationships.
      These are all small changed and
      should not restrict the usability of <application>Gaphor</application>s model.</para>

      <para>The biggest change is the addition of a whole new class:
      <classname>Diagram</classname>.
      <classname>Diagram</classname> is inherited from
      <classname>Namespace</classname> and is used to hold a
      diagram.  It contains a <classname>diacanvas.Canvas</classname> object
      which can be displayed on screen by a <classname>DiagramView</classname>
      class.</para>

    </section>
<!-- 
    <figure id="fig-uml" float="1">
      <title>gaphor.UML</title>
      <graphic fileref="uml.png"/>
    </figure>
 -->
  </section>

  <section>
    <title>User interface</title>

    <para>For the user interface (UI), <application>Gaphor</application> makes use of the GTK+ 2.0 libraries.
    All UI stuff is found in the <classname>gaphor.ui</classname> module.
    </para>

    <para>All windows are inherited from
    <classname>AbstractWindow</classname>. This class provides some basic
    stuff such as window construction and popup menu handling. The classes
    that are inherited from <classname>AbstractWindow</classname> all use
    the <classname>gtk.Window</classname> and provide some content of
    themselves. Each <classname>AbstractWindow</classname> manages a set of
    <classname>Action</classname>s. Those actions are kept in an
    <classname>ActionPool</classname>.</para>

    <para><classname>AbstractWindow</classname> also provides an
    interface for all windows. A window can have three states: INIT, ACTIVE
    and CLOSED. If a new <classname>AbstractWindows</classname>
    deriviate is instantiated it has the
    state INIT. The <function>construct()</function> method is called to
    create the actual window on the screen, the state changes to ACTIVE. You
    can now invoke all operations on the window (such as getting the real
    ui components and setting a message in the status bar). The last state,
    CLOSED, is reached when the <function>close()</function> method has
    been called. The UI components are destroyed and the object is basically
    useless.</para>

    <para>Note that the <classname>AbstractWindow</classname> is itself no a
    ui component, it contains the graphical objects and observes their
    activities. It is a Mediator.</para>
    
    <figure id="fig-ui-uml" float="1">
      <title>gaphor.ui</title>
      <graphic fileref="Diagrams/Gaphor/ui/ui.png"/>
    </figure>

    <para>As of this writing three windows are provided: a main window,
    an editor window and a console window. The main window is what you get when
    <application>Gaphor</application> is started (see <xref linkend="chap-usage"/>).</para>

    <para>Diagrams are shown in the main window, in a notebook (tab). Each tab
    contains a <classname>DiagramView</classname> object, which is a
    specialized version of a <classname>DiaCanvasView</classname> (which in
    his turn is a subclass of a <classname>GnomeCanvas</classname>). The tabs,
    the currently shown tab, diagram and view can be queried through the
    <classname>MainWindow</classname> interface.</para>
    
    <para>One of the more neat features are the Console window and the Editor
    window. They allow you to run python scripts directly within
    <application>Gaphor</application>. This
    is also a nice way to try new peaces of code and debug the data model.
    </para>

    <section>
      <title>Actions</title>

      <para>Every (well almost every) action that can be done in
      <application>Gaphor</application> is
      represented by an Action
      (<classname>gaphor.misc.action.Action</classname>). An action is created
      in the context of a window (<classname>AbstractWindow</classname>) and
      represents an action that can be executed through the user interface
      (for example: there is an action that opens a model, an action that
      switches the grid on a diagram, etc.).</para>
      
      <para>When you create a plugin you should register actions.</para>
    </section>
  </section>

  <section id="sect-plugin">
    <title>Plugins</title>
    <para>As of version 0.5.0, <application>Gaphor</application> provides some code for plugins. They are
    loaded on application startup (as <application>Python</application>
    modules.</para>

    <para>Plugins can be stored in two places:
      <variablelist>
        <varlistentry>
          <term><filename>${datadir}/plugins</filename></term>
          <listitem>
            <para>The system wide location. <literal>${datadir}</literal> is
            usually something like <filename>/usr/share/gaphor</filename> or
            <filename>/usr/local/share/gaphor</filename>.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><filename>${HOME}/.gaphor/plugins</filename></term>
          <listitem>
            <para>Plugins can also be stored in a directory in the users home
            directory.
            </para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
    <para>A plugin consists of a directory with at least the following files
    present:
      <variablelist>
        <varlistentry>
          <term><filename>plugin.xml</filename></term>
          <listitem>
            <para>This is an XML file that contains a description of the
            plugin as well as a list of prerequisites and provided actions.
            Requirements can be either modules (e.g.
            <literal>os.path</literal>) or other plugins that a plugin depends
            on. The provided actions are shown as menu items in the
            application.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><filename>__init__.py</filename></term>
          <listitem>
            <para>This file is required by <application>Python</application>,
            otherwise it wouldn't be recognised as a module (the plugin is
            loaded as a module).</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>


    <para>Before a plugin is loaded <filename>plugin.xml</filename> is read
    which contains some definitions for the plugin:
      <orderedlist>
        <listitem>
          <para>Information such as author, version, and of course the name.
          </para>
        </listitem>
        <listitem>
          <para>Requirements: other plugins this one depends on, modules.
          </para>
        </listitem>
        <listitem>
          <para>definitions of <classname>Action</classname>s.
          </para>
        </listitem>
        <!--
        <listitem>
          <para>Code that should be ran before and after installation, before
          and after removal.
          </para>
        </listitem>
        -->
      </orderedlist>
    </para>

    <para>A typical <filename>plugin.xml</filename> file looks like this:
    <programlisting>
<![CDATA[<?xml version="1.0"?>
<plugin name="UML metamodel sanity check"
        version="0.1"
        author="Arjan Molenaar">
  <description>
    A description of what this thing does.
  </description>

  <require>
    <!--
      Define modules and plugins that are needed for this plugin to function
      properly.
    -->
    <module name="os.path"/>
    <plugin name="anotherPlugin"/>
  </require>

  <provide>
    <!--
      Actions should be defined on the module's toplevel (like in __init__.py).
    -->
    <action id="MyPlugin"
            label="Do a typical thing with the plugin"
            icon-file="myicon.png"
            tooltip="bla bla"
            class="MyPluginAction" slot="WindowSlot">
      <!--
        Add optional dependencies to this action. The action is then updated
        when actions defined in the depends tag are executed.
      -->
      <depends action="ItemFocus"/>
    </action>
  </provide>
</plugin>]]>
      </programlisting>
    </para>

    <para>A plugin contains three sections:
      <variablelist>
        <varlistentry>
          <term>description</term>
          <listitem>
            <para>A description of the plugin (could be shown in a plugin
            browser for example) This is just a text field.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>require</term>
          <listitem>
            <para>The require section can contain modules and plugins that are
            needed for this plugin to work.</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term>provide</term>
          <listitem>
            <para>Actions that are provided by this plugin.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>

    <para>The <literal>provide</literal> section contains the actions that can
    be added to the application.  An action is a
    <application>Python</application> class that extends
    <classname>gaphor.plugin.Action</classname> (or
    <classname>CheckAction</classname> for checkbox actions or
    <classname>RadioAction</classname> for radiobutton actions). An action has
    an:
      <variablelist>
        <varlistentry>
          <term><literal>id</literal></term>
          <listitem>
            <para>Id is a unique identifier for the action.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>label</literal></term>
          <listitem>
            <para>A label that is shown in the menu.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>tooltip</literal></term>
          <listitem>
            <para>A short description of the action that can be displayed in a
            status bar or as a tooltip.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>icon-file</literal></term>
          <listitem>
            <para>A file containing a nice (24x24) image, preferbly a PNG image.
            </para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>class</literal></term>
          <listitem>
            <para>The <classname>Action</classname> class to load from the
            module. The <classname>Action</classname> class should be visible
            through <filename>__init__.py</filename> (class names like
            <classname>test.TestAction</classname> do not work).</para>
          </listitem>
        </varlistentry>
        <varlistentry>
          <term><literal>slot</literal></term>
          <listitem>
            <para>Slots are predefined places in a menu where new actions can
            be added. For a list of slots take a look at the documentation of
            <application>Gaphor</application>.</para>
          </listitem>
        </varlistentry>
      </variablelist>
    </para>
  </section>
</chapter>
<!-- vi:sw=2:tw=78:tabstop=2:sts=2
-->