diff options
author | Karl Berry <karl@freefriends.org> | 2019-02-03 22:45:55 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2019-02-03 22:45:55 +0000 |
commit | c5d84d1a3ab85b1f314ff62717a7af3c6b75c7af (patch) | |
tree | 26333edc4a6082f37d75349f84eded8dbc0d5aef /Master/texmf-dist/doc/metapost/metauml/manual/metauml-manual.tex | |
parent | 2dcfe2f07af05124d5ebee4672d67d7eeae7af60 (diff) |
metauml (3feb19)
git-svn-id: svn://tug.org/texlive/trunk@49923 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/metapost/metauml/manual/metauml-manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/metapost/metauml/manual/metauml-manual.tex | 2072 |
1 files changed, 2072 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/metapost/metauml/manual/metauml-manual.tex b/Master/texmf-dist/doc/metapost/metauml/manual/metauml-manual.tex new file mode 100644 index 00000000000..933130a33d3 --- /dev/null +++ b/Master/texmf-dist/doc/metapost/metauml/manual/metauml-manual.tex @@ -0,0 +1,2072 @@ +% MetaUML: Tutorial, Reference and Test Suite +% +% Copyright (c) 2005-2019 Ovidiu Gheorghies +% Permission is granted to copy, distribute and/or modify this document +% under the terms of the GNU Free Documentation License, Version 1.2 +% or any later version published by the Free Software Foundation; +% with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +% A copy of the license is included in the section entitled "GNU +% Free Documentation License". + +\documentclass{article} + +\usepackage[utf8]{inputenc} +\usepackage[pdftex,colorlinks=true]{hyperref} +\usepackage{multicol} +\usepackage{multido} +\usepackage[style=ieee]{biblatex} +\addbibresource{metauml-manual.bib} + +\ifx\pdftexversion\undefined + \usepackage[dvips]{graphicx} +\else + \usepackage[pdftex]{graphicx} + \DeclareGraphicsRule{*}{mps}{*}{} +\fi + +\newcommand{\code}{\ttfamily} + +\setcounter{page}{1} + +\begin{document} + +MetaUML: A Manual and Test Suite + +\begin{quote} + Copyright \copyright 2005-2019 Ovidiu Gheorghie\c{s}. + Permission is granted to copy, distribute and/or modify this document + under the terms of the GNU Free Documentation License, Version 1.2 + or any later version published by the Free Software Foundation; + with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. +\end{quote} + +\pagebreak +This page is intentionally left blank. + +\pagebreak +\title{MetaUML: A Manual and Test Suite} + +\author{Ovidiu Gheorghie\c{s}} + +\maketitle + +\begin{abstract} +MetaUML is a MetaPost \cite {metapost} library for creating UML \cite{umlomg} diagrams by means of a textual notation. +While presenting the inner workings of MetaUML, this manual doubles as a step-by-step tutorial. +More importantly, its source code contains many useful examples of diagrams, ranging from the very basic to the +more advanced and customized. +\end{abstract} + +\section{Introduction} + +Here is a quick MetaUML showcase: + +\begin{multicols}{2} +\paragraph{A} Class Diagram\\ +\includegraphics[scale=.55]{fig/appetizer.1} +\paragraph{B} Activity Diagram\\ +\includegraphics[scale=.55]{fig/appetizer.2} +\paragraph{C} Notes\\ +\includegraphics[scale=.55]{fig/appetizer.5} +\columnbreak +\paragraph{D} Use Case Diagram\\ +\includegraphics[scale=.55]{fig/appetizer.3} +\paragraph{E} State Machine Diagram\\ +\includegraphics[scale=.55]{fig/appetizer.4} +\paragraph{F} Package Diagram\\ +\includegraphics[scale=.55]{fig/appetizer.6} +\end{multicols} + +\pagebreak + +The code that generates these diagrams is quite straightforward, combining a natural object-oriented parlance +with the power of MetaPost equation solving. + +For example, a UML class is drawn as follows: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("MyClass") + ("attr1: int", "attr2: int") + ("method1(): void", + "method2(): void"); + +A.nw = (0, 0); % optional, implied +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/appetizer.7} +\end{multicols} + +This code creates a visual object, referenced by its name {\code A}, of the MetaUML-defined type {\code Class}. +Object {\code A} has the following content properties: a name +({\code MyClass}), a list of attributes ({\code attr1}, {\code attr2}) +and a list of methods ({\code method1}, {\code method2}). To set the object's location, we assign a value to the +so-called ``north-west'' point of the encompassing rectangle, {\code A.nw} --- a point which in actual fact references +the upper-left corner. + +Every MetaUML visual object has the layout properties shown in figure \ref{fig:properties}. +These properties may be used to set the location of any given object, either by assigning to them absolute values, +or by linking them relatively to other objects via equations. + +\begin{figure} +\centering +\includegraphics{fig/properties.1} +\caption{Layout properties of MetaUML objects. Here, a {\code Class} object is depicted.} +\label{fig:properties} +\end{figure} + +The following example demonstrates, respectively, the use of absolute and relative positioning for two classes, {\code A} and {\code B}. + +\begin{multicols}{2} +\begin{verbatim} +A.nw = (0,0); +B.w = A.e + (20, 0); +\end{verbatim} +\columnbreak +\includegraphics{fig/appetizer.8} +\end{multicols} + +After the objects have been drawn, it becomes possible to attach links to them. In a class diagram, inheritance +or association relations are meaningful links between classes, while in a state machine diagram, transitions between +states can be used. Here is the general pattern used by MetaUML for drawing links: + +\begin{verbatim} +link(<how-to-draw-information>)(<path-to-draw>); +\end{verbatim} + +The ``how-to-draw-information'' is an object which defines the style of the line (e.g. solid, dashed) and the appearance +of the heads (e.g. nothing, arrow, diamond). One such object, appropriately called {\code inheritance}, defines a solid +line style and a white triangle head. The other parameter, the ``path-to-draw'', is simply a MetaPost path. + +For example, the following call draws an inheritance relation from class {\code B} to class {\code A}. + +\begin{verbatim} +link(inheritance)(B.e -- A.w); +\end{verbatim} + +The direction of the path is important, as MetaUML uses it to determine the +type of adornment to attach to the link ends (if applicable). In our example, a white triangle, +denoting inheritance, points towards the end of the path, that is towards class {\code A}. + +Let us sum up with a diagram typical for MetaUML use. Firstly, we define the objects that we want to include +in our diagram. Secondly, we position these objects relative to each other. Thirdly, we draw the objects. Finally, we +draw the links, by referencing the layout properties of the previously drawn objects. Note that in our example the +positioning of {\code A} need not be set explicitly because ``floating'' objects are automatically positioned at +{\code (0,0)} by their draw method. + +\begin{multicols}{2} + +\begin{verbatim} +input metauml; + +beginfig(1); + Class.A("A")()(); % 1. Define the objects + Class.B("B")()(); + B.w = A.e + (20, 0); % 2. Position the objects + drawObjects(A, B); % 3. Draw the objects + link(inheritance)(B.w -- A.e); % 4. Draw links between objects +endfig; +end +\end{verbatim} +\columnbreak +\includegraphics{fig/appetizer.9} +\end{multicols} + +As far as a user is concerned, this is all there is to MetaUML. With a reference describing how the +UML elements are created, arbitrarily complex diagrams can be crafted. + +\section{Class Diagrams} + +A class is created as follows: + +\begin{verbatim} +Class.<name>(<class-name>) + (<list-of-attributes>) + (<list-of-methods>); +\end{verbatim} + +The suffix {\code <name>} specifies an identifier for the newly created {\code Class} object +(which, of course, represents a UML class). +The name of the UML class is a string given by {\code <class-name>}; +the attributes and methods are given as list of strings, {\code <list-of-attributes>} and {\code <list-of-methods>} +respectively. The list of attributes and the list of methods may be void. + +An attribute or a method string may begin with a visibility marker: ``$+$'' for +public, ``\#'' for protected, ``$-$'' for private, and ``\textasciitilde'' for package private. +The default visibility is package private. + +\begin{multicols}{2} +\begin{verbatim} +Class.A("Point") + ("#x:int", "#y:int") + ("+set(x:int, y:int)", + "+getX():int", + "+getY():int", + "-debug():void", + "test():void"); +drawObject(A); +\end{verbatim} +\columnbreak +\includegraphics{fig/class.1} +\end{multicols} + +To disable showing the visibility markers, use {\code Class\_noVisibilityMarkers}, as shown below: + +\begin{multicols}{2} +\begin{verbatim} + Class.A("Point") + ("#x:int", "#y:int") + ("+toString():String"); + Class_noVisibilityMarkers.A; + + drawObject(A); +\end{verbatim} +\columnbreak +\includegraphics{fig/class.15} +\end{multicols} + +\subsection{Stereotypes} + +After a class is created, but before it is drawn, its stereotypes may be specified by using {\code Class\_stereotypes}: + +\begin{verbatim} +Class_stereotypes.<name>(<list-of-stereotypes>); +\end{verbatim} + +Here, {\code <name>} is the object name of a previously created class and {\code <list-of-stereotypes>} +is a comma-separated list of strings. Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("User")()(); +Class_stereotypes.A("<<interface>>","<<home>>"); + +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/class.2} +\end{multicols} + +\subsection{Interfaces and Abstract Classes} + +At times it is preferred to write the name of an interface in an oblique font, rather than using the ``interface'' +stereotype. This can be easily achieved by using the macro {\code Interface}: + +\begin{verbatim} +Interface.name(class-name) + (list-of-methods); +\end{verbatim} + +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +Interface.A("Observer") + ("+update(src:Object)"); + +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class.11} +\end{multicols} + +Since internally {\code Interface} treated as a special kind of {\code Class}, the code above is equivalent to: +\begin{verbatim} +EClass.A(iInterface)("Observer")() + ("+update(src:Object)"); +\end{verbatim} + +Abstract classes can be drawn similarly using the {\code iAbstractClass} style: +\begin{samepage} +\begin{multicols}{2} +\begin{verbatim} +EClass.A(iAbstractClass)("Observable") + ("observers: Observer[0..*]") + ("+addObserver(o: Observer)", + "+notify()"); + +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class.12} +\end{multicols} +\end{samepage} + +If you prefer, you can use equivalent construct: + +\begin{verbatim} +AbstractClass.A("Observable") + ("observers: Observer[0..*]") + ("+addObserver(o: Observer)", + "+notify()"); +\end{verbatim} + +\subsection{Displaying Class Name Only} + +If you want the empty methods and attributes compartments in a class not being displayed, one way is to set the spacing +at their top and the bottom to {\code 0}: +\begin{samepage} +\begin{multicols}{2} +\begin{verbatim} +Class.A("MyModel")()(); +A.info.iName.top := 10; +A.info.iName.bottom := 10; +A.info.iAttributeStack.top := 0; +A.info.iAttributeStack.bottom := 0; +A.info.iMethodStack.top := 0; +A.info.iMethodStack.bottom := 0; + +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class.13} +\end{multicols} +\end{samepage} + +The same effect can be achieved by using the formatting information object {\code iClassNameOnly} or the {\code ClassName} macro: + +\begin{multicols}{2} +\begin{verbatim} +EClass.A(iClassNameOnly)("MyModel")()(); +ClassName.B("AnotherModel"); +Class_stereotypes.B("<<smart>>"); + +topToBottom(20)(A, B); + +drawObjects(A, B); +\end{verbatim} +\columnbreak +\hspace{2cm}\includegraphics{fig/class.14} +\end{multicols} + +To customize the space around the class name globally, you can set the values of {\code iClassNameOnly.iName.top} and {\code iClassNameOnly.iName.bottom}. Individually, for a given object, say {\code B}, the attributes {\code B.info.iName.top} and {\code B.info.iName.bottom} can be used. + +\subsection{Objects (or Class Instances)} + +A UML object (or class instance) is created as follows: + +\begin{verbatim} +Instance.name(object-name) + (list-of-attributes); +\end{verbatim} + +The suffix {\code name} gives a name to the {\code Instance} object. The name of the object (given by {\code object-name}) is typeset underlined. The attributes are given as a comma-separated list of strings, {\code list-of-attributes}. + +\begin{multicols}{2} +\begin{verbatim} +Instance.order("o: Order") + ("name='book'", "{placed}", "{payed}"); +drawObject(order); +\end{verbatim} +\columnbreak +\hspace{2cm}\includegraphics{fig/instance.1} +\end{multicols} + + +\subsection{Parametrized Classes (Templates)} + +The most convenient way of typesetting a class template in MetaUML is to use the macro {\code ClassTemplate}. +This macro creates a visual object which is appropriately positioned near the class object it adorns. + +\begin{verbatim} +ClassTemplate.name(list-of-templates) + (class-object); +\end{verbatim} + +The {\code name} is the name of the template object, {\code list-of-templates} is a comma-separated list of strings and the {\code class-object} is the name of a class object. + +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("Vector")()(); +ClassTemplate.T("T", "size: int")(A); + +drawObjects(A, T); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class.3} +\end{multicols} + +The macro {\code Template} can also be used to create a template object, but this time the resulting +object can be positioned freely. + +\begin{verbatim} +Template.name(list-of-templates); +\end{verbatim} + +Of course, it is possible to specify both stereotypes and template parameters for a given class. + +\subsection{Types of Links} + +In this section we enumerate the relations that can be drawn between classes by means +of MetaUML macros. Suppose that we have the declared two points, {\code A} (on the left) +and {\code B} (on the right): + +\begin{verbatim} +pair A, B; +A = (0,0); +B = (50,0); +\end{verbatim} + +\begin{tabular}{||l|c||} +\hline +{\code link(association)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.4} \\ +\hline +{\code link(associationUni)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.5} \\ +\hline +{\code link(inheritance)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.6} \\ +\hline +{\code link(realization)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.12} \\ +\hline +{\code link(aggregation)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.7} \\ +\hline +{\code link(aggregationUni)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.8} \\ +\hline +{\code link(composition)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.9} \\ +\hline +{\code link(compositionUni)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.10} \\ +\hline +{\code link(dependency)(X.e -- Y.w)} & \includegraphics{fig/class_diagrams.11} \\ +\hline +\end{tabular} + +\subsection{Associations} +In UML an association typically has two of association ends and may have a name specified for it. +In turn, each association end may specify a multiplicity, a role, a visibility, an ordering. +These entities are treated in MetaUML as pictures having specific drawing information +(spacings, font). + +The first method of creating association ``items'' is by giving them explicit names. +Having a name for an association item comes in handy when referring to its properties +is later needed (see the non UML-compliant diagram below). The last parameter of the macro {\code item} is an equation which may use the item's name to perform positioning. + +\begin{multicols}{2} +\begin{verbatim} +Class.P("Person")()(); +Class.C("Company")()(); +% drawing code ommited + +item.aName(iAssoc)("works for") + (aName.s = .5[P.w, C.w]); +draw aName.n -- (aName.n + (20,20)); +label.urt("association name" infont "tyxtt", + aName.n + (20,20)); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics[scale=.8]{fig/class_association.1} +\end{multicols} + +However, giving names to every association item may become an annoying burden +(especially when there are many of them). Because of this, MetaUML also allows for +``anonymous items''. In this case, the positioning is set by an equation +which refers to the anonymous item as {\code obj}. + +\begin{multicols}{2} +\begin{verbatim} +% P and C defined as in the previous example + +item(iAssoc)("employee")(obj.nw = P.s); +item(iAssoc)("1..*")(obj.ne = P.s); + +% other items are drawn similarly +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/class_association.2} +\end{multicols} + +\subsection{Dependencies and Stereotypes} + +Stereotypes are frequently used with dependencies. Below is an example. +\pagebreak + +\begin{multicols}{2} +\begin{verbatim} +Class.F("Factory")()(); +Class.O("Object")()(); + +O.n = F.s - (0, 50); +drawObjects(F, O); + +clink(dependency)(F, O); +item(iStereo)("<<creates>>")(obj.w = .5[F.s,O.n]) +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/class_association.3} +\end{multicols} + +\section{Notes} + +A note is created as follows: + +\begin{verbatim} +Note.name(list-of-lines); +\end{verbatim} + +The suffix {\code name} is the name of the {\code Note} object. The contents of the note is given by a comma-separated +list of strings, {\code list-of-lines}, gives the text contents of the note object, each string being drawn on its own +line. + +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +Note.A("This note", "has two lines."); +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/note.1} +\end{multicols} + +\subsection{Attaching notes to diagram elements} + +Notes can be attached to diagram elements by using a link of type {\code dashedLink}. + +\begin{multicols}{2} +\begin{verbatim} +Note.A("This is a class"); +Class.C("Object")()(); + +A.sw = C.ne + (20, 20); + +drawObject(A, C); + +clink(dashedLink)(A, C); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/note.2} +\end{multicols} + +Now let us see a more complex example, which demontrates the ability of accessing sub-elements in a MetaUML diagram. +\pagebreak + +\begin{multicols}{2} +\begin{verbatim} +Note.nA("This is the class name"); +Note.nB("This is a key attribute"); +Note.nC("This is a nice method"); + +Class.C("Object")("+id:int") + ("+clone()", "+serialize()"); + +topToBottom.left(10)(nA, nB, nC); +leftToRight(10)(C, nB); + +drawObjects(C, nA, nB, nC); + +clink(dashedLink)(C.namePict, nA); +clink(dashedLink)(C.attributeStack.pict[0], nB); +clink(dashedLink)(C.methodStack.pict[1], nC); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/note.3} +\end{multicols} + +Macros like {\code leftToRight} and {\code topToBottom} are presented in section \ref{section:positioning}. + +\subsection{Using mathematical formulae} + +MetaUML notes can contain mathematical formulae written in TeX \cite{texbook}. Regretably, LaTeX \cite{latexbook} support for formulae is {\bf not} available. +Limited as it may be, this feature is considered experimental, as it is not always straightforward to use. In the example below, note that the MetaPost package {\code TEX} is imported. + +\begin{multicols}{2} +\begin{verbatim} +input metauml; +input TEX; + +beginfig(1); + Note.A("This class implements the formula:", + TEX("$\sum_1^n f(x) \cdot dx$")); + drawObjects(A); +endfig; + +end +\end{verbatim} +\columnbreak +\hspace{0.5cm}\includegraphics{fig/note.4} +\end{multicols} + +For taller formulae, you must be prepared to do some advanced stunts. Remark: {\code "aaa" \& "bbb"} is MetaPost's way to concatenate the strings into {\code "aaabbb"}; +the string containing the formula was split in two for layout reasons. + +\begin{multicols}{2} +\begin{verbatim} +Note.A("Can you do it?", + TEX("$\sum_1^n f(x) \cdot dx " & + "\over \sum_1^m g(y) \cdot dy$")); +A.stack.info.spacing := 30; +A.stack.pict[1].info.ignoreNegativeBase := 0; + +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/note.5} +\end{multicols} + +Alas, this trick does not entirely solve the problem: a third line in the note would be badly aligned. Therefore, +until MetaUML's {\code Note} class is upgraded to better support this scenario, you may want to limit yourself +to two lines per note --- at least when tall formulae are involved. + +\section{Packages} + +MetaUML allows for the creation of packages in various forms. Firstly, we have the option of writing the package +name in the middle of the main box. Secondly, we can write the name on the tiny box above the main box, leaving +the main box empty. Lastly, we can write the package name as in the second case, but the main box can have an arbitrary +contents: classes, other packages, or even other UML items. + +The macro that creates a package has the following synopsis: + +\begin{verbatim} +Package.name(package-name)(subitems-list); +\end{verbatim} + +The parameter {\code package-name} is a string or a list of comma-separated strings representing the package's name. +The {\code subitems-list} parameter is used to specify the subitems (tipically classes or packages) of this package; +its form is as a comma-separated list of objects, which can be void. + +\begin{multicols}{2} +\begin{verbatim} +Package.P("java.lang")(); +drawObject(P); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/package.1} +\end{multicols} + +Below is another example: + +\begin{multicols}{2} +\begin{verbatim} +Package.P("An important", "package")(); +drawObject(P); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/package.2} +\end{multicols} + +If you wish to leave the main box empty, you can use the following code: + +\begin{multicols}{2} +\begin{verbatim} +Package.P("java.lang")(); +P.info.forceEmptyContent := 1; +drawObject(P); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/package.3} +\end{multicols} + +The same effect as above can be achieved globally by doing: + +\begin{verbatim} +iPackage.forceEmptyContent := 1; +\end{verbatim} + +More information on MetaUML's way of managing global and per-object configuration data can be found in +section \ref{section:infrastructure} and section \ref{section:customization}. + +Here is an example involving items contained in a package. + +\begin{multicols}{2} +\begin{verbatim} +Class.A("A")()(); +Class.B("B")()(); +Package.P("net.metauml")(A, B); + +leftToRight(10)(A, B); + +drawObject(P); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/package.4} +\end{multicols} + +\subsection{Types of Links} + +The nesting relation between packages is created by using the {\code nest} link information. + +\begin{tabular}{||l|c||} +\hline +{\code link(nest)(X.e -- Y.w)} & \includegraphics{fig/package.5} \\ +\hline +\end{tabular} + +\section{Component Diagrams} + +A component is created by the macro {\code Component}: + +\begin{verbatim} +Component.name(component-name) + (subitems-list) +\end{verbatim} + +The parameter {\code component-name} is a string representing the component's name. The {\code subitems-list} parameter +is used to specify the subitems of this component (possibly classes, packages or other components); its form is as a +comma-separated list of objects, which can be void. + +\begin{multicols}{2} +\begin{verbatim} +Component.C("Business Logic")(); +drawObject(C); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/component.1} +\end{multicols} + +Here is an example involving subitems in a component: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("A")()(); +Package.B("B")(); +Component.C("C")(); + +Component.BigC("Big Component")(A, B, C); + +leftToRight(10)(A, B); +topToBottom(10)(A, C); + +drawObject(BigC); +\end{verbatim} +\columnbreak +\hspace{3cm}\includegraphics{fig/component.2} +\end{multicols} + +\subsection{Types of Links} + +\begin{tabular}{||l|c||} +\hline +{\code link(requiredInterface)( A.e -- .5[A.e, B.w] );} & \includegraphics{fig/component.3} \\ +\hline +{\code link(providedInterface)( .5[A.e, B.w] -- B.w );} & \includegraphics{fig/component.4} \\ +\hline +\end{tabular} + +\vspace{0.5cm} + +The {\code requiredInterface} and {\code providedInterface} visual constructs can be easily combined, as shown in the following example: + +\begin{multicols}{2} +\begin{verbatim} +Component.A("A")(); +Component.B("B")(); + +leftToRight(80)(A, B); + +drawObjects(A, B); + +link(providedInterface)( A.e -- .5[A.e, B.w] ); +link(requiredInterface)( B.w -- .5[A.e, B.w] ); +\end{verbatim} +\columnbreak +\hspace{-1cm}\includegraphics{fig/component.5} +\end{multicols} + + +\section{Use Case Diagrams} + +\subsection{Use Cases} +An use case is created by the macro {\code Usecase}: + +\begin{verbatim} +Usecase.name(list-of-lines); +\end{verbatim} + +The {\code list-of-lines} is a comma-separated list of strings. These strings are placed +on top of each other, centered and surrounded by the appropriate visual UML notation. + +Here is an use case example: + +\begin{multicols}{2} +\begin{verbatim} +Usecase.U("Authenticate user", + "by name, password"); +drawObject(U); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/usecase.1} +\end{multicols} + +\subsection{Actors} + +An actor is created by the macro {\code Actor}: + +\begin{verbatim} +Actor.name(list-of-lines); +\end{verbatim} + +Here, {\code list-of-lines} represents the actor's name. For convenience, the name may be +given as a list of strings which are placed on top of each other, to provide support for +the situations when the role is quite long. Otherwise, giving a single string +as an argument to the Actor constructor is perfectly fine. + +Here is an actor example: + +\begin{multicols}{2} +\begin{verbatim} +Actor.A("User"); +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/usecase.2} +\end{multicols} + +Sometimes it may be preferable to draw diagram relations positioned relatively to +the visual representation of an actor (the ``human'') rather than relatively to the whole +actor object (which also includes the text). Because of that, MetaUML provides access +to the ``human'' of every actor object {\code actor} by means of the sub-object {\code actor.human}. + +\begin{multicols}{2} +\begin{verbatim} +Actor.A("Administrator"); +drawObject(A); +draw objectBox(A); +draw objectBox(A.human); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/usecase.3} +\end{multicols} + +In MetaUML, {\code objectBox(X)} is equivalent to {\code X.nw -- X.ne -- X.se -- X.sw -- cycle} for every object {\code X}. {\code A.human} is considered a MetaUML object, so you can use expressions like {\code A.human.n} or {\code A.human.midx}. + +\subsection{Types of Links} + +Some of the types of links defined for class diagrams (such as inheritance, association etc.) can be used with similar semantics within use case diagrams. + +\section{Activity Diagrams} + +\subsection{Begin, End and Flow End} + +The begin and the end of an activity diagram can be marked by using the macros {\code Begin} +and {\code End} or {\code FlowFinal}, respectively. The constructors of these visual objects take no parameters: + +\begin{verbatim} +Begin.beginName; +End.endName; +\end{verbatim} + +Below is an example: + +\begin{multicols}{2} +\begin{verbatim} +Begin.b; +End.e; +FlowFinal.f; + +leftToRight(20)(b, e, f); + +drawObjects(b, e, f); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/activity.1} +\end{multicols} + +\subsection{Activity} + +An activity is constructed as follows: +\begin{verbatim} +Activity.name(list-of-strings); +\end{verbatim} + +The parameter {\code list-of-strings} is a comma-separated list of strings. These strings are +centered on top of each other to allow for the accommodation of a longer activity description +within a reasonable space. + +An example is given below: + +\begin{multicols}{2} +\begin{verbatim} +Activity.A("Learn MetaUML -", + "the MetaPost UML library"); +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/activity.2} +\end{multicols} + +\subsection{Fork and Join} + +A fork or join is created by the macro: + +\begin{verbatim} +Fork.name(type, length); +\end{verbatim} + +The parameter {\code type} is a string and can be either of {\code "h"}, {\code "horiz"}, {\code "horizontal"} +for horizontal bars, and either of {\code "v"}, {\code "vert"}, {\code "vertical"} for vertical bars. +The {\code length} gives the bar's length. + +\begin{multicols}{2} +\begin{verbatim} +Fork.forkA("h", 100); +Fork.forkB("v", 20); + +leftToRight(10)(forkA, forkB); + +drawObject(forkA, forkB); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/activity.3} +\end{multicols} + +\subsection{Branch} + +A branch is created by the macro: + +\begin{verbatim} +Branch.name; +\end{verbatim} + +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +Branch.testA; + +drawObject(testA); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/activity.4} +\end{multicols} + + +\subsection{Types of Links} + +In activity diagrams, transitions between activities are needed. They are typeset +as in the example below. In section \ref{composite-states} such a transition +is showed. This type of link is also used for state machine diagrams. + +\begin{verbatim} +link(transition)( pointA -- pointB ); +\end{verbatim} + +\section{State Diagrams} + +The constructor of a state allows for aggregated sub-states: + +\begin{verbatim} +State.name(state-name)(substates-list); +\end{verbatim} + +The parameter {\code state-name} is a string or a list of comma-separated strings representing +the state's name or description. The {\code substates-list} parameter is used to specify +the substates of this state as a comma-separated list of objects; this list may be void. + +An example of a simple state: + +\begin{multicols}{2} +\begin{verbatim} +State.s("Take order")(); +drawObject(s); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/state.1} +\end{multicols} + + +\subsection{Composite States} +\label{composite-states} + +A composite state is defined by enumerating at the end of its constructor the inner +states. Interestingly enough, the composite state takes care of drawing the sub-states it +contains. The transitions must be drawn after the composite state, as seen in the +next example: + +\begin{multicols}{2} +\begin{verbatim} +Begin.b; +End.e; +State.c("Component")(); +State.composite("Composite")(b, e, c); + +b.midx = e.midx = c.midx; +c.top = b.bottom - 20; +e.top = c.bottom - 20; + +composite.info.drawNameLine := 1; +drawObject(composite); + +link(transition)(b.s -- c.n); +link(transition)(c.s -- e.n); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/state.2} +\end{multicols} + +\subsection{Internal Transitions} + +Internal transitions can be specified by using the macro: +\begin{verbatim} +stateTransitions.name(list-transitions); +\end{verbatim} + +Identifier {\code name} gives the state object whose internal transitions are being set, +and parameter {\code list-transitions} is a comma-separated string list. + + +An example is given below: + +\begin{multicols}{2} +\begin{verbatim} +State.s("An interesting state", + "which is worth mentioning")(); +stateTransitions.s( + "OnEntry / Open eyes", + "OnExit / Sleep well"); +s.info.drawNameLine := 1; + +drawObject(s); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/state.3} +\end{multicols} + +\subsection{Special States} + +Similarly to the usage of {\code Begin} and {\code End} macros, one can define history states, +exit/entry point states and terminate pseudo-states, by using the following constructors. + +\begin{verbatim} +History.nameA; +ExitPoint.nameB; +EntryPoint.nameC; +Terminate.nameD; +\end{verbatim} + +\section{Drawing Paths} + +The {\code link} macro is powerful enough to draw relations following arbitrary paths: + +\begin{multicols}{2} +\begin{verbatim} +path cool; +cool := A.e .. A.e+(20,10) .. + B.s+(20,-40) .. B.s+(-10,-30) + -- B.s; +link(inheritance)(cool); + +link(aggregationUni) + (A.n ..(30,30)..B.w); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/paths.1} +\end{multicols} + +Amusing as it may be, this feature gets old soon. When typesetting UML diagrams in good style, rectangular paths are usually preferred. +It is for this kind of paths that MetaUML offers extensive support, by means of ``syntactic sugar'' constructs which +are not only self-documenting, but reduce the amount of typing and thinking required. + +\subsection{Manhattan Paths} + +The ``Manhattan'' path macros generate a path between two points consisting of one +horizontal and one vertical segment. The macro {\code pathManhattanX} generates first a +horizontal segment, while the macro {\code pathManhattanY} generates first a +vertical segment. In MetaUML it also matters the direction of a path, so you +can choose to reverse it by using {\code rpathManhattanX} and {\code rpathManhattanY} +(note the prefix ``{\code r}''): + +\begin{verbatim} +pathManhattanX(A, B) +pathManhattanY(A, B) + +rpathManhattanX(A, B) +rpathManhattanY(A, B) +\end{verbatim} + +\pagebreak +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("A")()(); +Class.B("B")()(); + +B.sw = A.ne + (10,10); +drawObjects(A, B); + +link(aggregationUni) + (rpathManhattanX(A.e, B.s)); +link(inheritance) + (pathManhattanY(A.n, B.w)); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/paths.2} +\end{multicols} + +\subsection{Stair Step Paths} + +These path macros generate stair-like paths between two points. +The ``stair'' can ``rise'' first in the direction of $Ox$ axis ({\code pathStepX}) +or in the direction of $Oy$ axis ({\code pathStepY}). How much should a step +rise is given by an additional parameter, {\code delta}. Again, the macros +prefixed with ``{\code r}'' reverse the direction of the path given by their +unprefixed counterparts. + +\begin{verbatim} +pathStepX(A, B, delta) +pathStepY(A, B, delta) + +rpathStepX(A, B, delta) +rpathStepY(A, B, delta) +\end{verbatim} + +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +stepX:=60; +link(aggregationUni) + (pathStepX(A.e, B.e, stepX)); + +stepY:=20; +link(inheritance) + (pathStepY(B.n, A.n, stepY)); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/paths.3} +\end{multicols} + +\subsection{Horizontal and Vertical Paths} + +There are times when drawing horizontal or vertical links is required, +even when the objects are not properly aligned. To this aim, the following macros +are useful: + +\begin{verbatim} +pathHorizontal(pA, untilX) +pathVertical(pA, untilY) + +rpathHorizontal(pA, untilX) +rpathVertical(pA, untilY) +\end{verbatim} + +A path created by {\code pathHorizonal} starts from the point {\code pA} +and continues horizontally until coordinate {\code untilX} is reached. The macro +{\code pathVertical} constructs the path dually, working vertically. +The prefix ``{\code r}'' reverses the direction of the path. + +Usage example: + +\begin{multicols}{2} +\begin{verbatim} +untilX := B.left; +link(association) + (pathHorizontal(A.e, untilX)); + +untilY:= C.bottom; +link(association) + (pathVertical(A.n, untilY)); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/paths.4} +\end{multicols} + +\subsection{Direct Paths} + +A direct path can be created with {\code directPath}. The call {\code directPath(A, B)} +is equivalent to {\code A -{}- B}. + +\subsection{Paths between Objects} + +Using the constructs presented above, links between diagram objects are drawn easily like this: + +\begin{verbatim} +link(transition)(directPath(objA.nw, objB.se)); +\end{verbatim} + +There are times however when this direct approach may yield unsatisfactory visual results, +especially when the object's corners is round. To tackle these situations, MetaUML provides the macro +{\code pathCut}, whose aim is to limit a given path exactly to the region outside the actual +borders of the objects it connects. The macro's synopsis is: + +\begin{verbatim} +pathCut(thePath)(objectA, objectB) +\end{verbatim} + +Here, {\code thePath} is a given MetaPost path and {\code objectA} and {\code objectB} +are two MetaUML objects. By contract, each MetaUML object of type, say, {\code X} +defines a macro {\code X\_border} which returns the path that surrounds it. Because +of that, {\code pathCut} can make the appropriate modifications to {\code thePath}. + +The following code demonstrates the benefits of the {\code pathCut} macro: + +\begin{multicols}{2} +\begin{verbatim} +z = A.se + (30, -10); +link(transition) + (pathCut(A, B)(A.c--z--B.c)); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/paths.5} +\end{multicols} + +\subsubsection{Direct Paths between Centers} + +At times is quicker to just draw direct paths between the center of two objects, +minding of course the object margins. The macro which does this is {\code clink}: + +\begin{verbatim} +clink(how-to-draw-information)(objA, objB); +\end{verbatim} + +The parameter {\code how-to-draw-information} is the same as for the macro {\code link}; +{\code objA} and {\code objB} are two MetaUML objects. + +Below is an example which involves the inheritance relation: + +\begin{multicols}{2} +\begin{verbatim} +clink(inheritance)(A, B); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/paths.6} +\end{multicols} + +\section{Arranging Diagram Items} +\label{section:positioning} + +Using equations involving cardinal points, such as {\code A.nw = B.ne + (10,0)}, is +good enough for achieving the desired results. However, programs are best to +be written for human audience, rather than for compilers. It does become a bit +tiresome to think all the time of cardinal points and figure out the +direction of positive or negative offsets. Because of that, MetaUML offers +syntactic sugar which allows for an easier understanding of the intent behind +the positioning code. + +Suppose that we have three classes, {\code A}, {\code B}, {\code C} and their base class +{\code Base}. We want the base class to be at the top, and the derived classes to be +on a line below. This code will do: + +\begin{verbatim} +A.ne = B.nw + (20,0); +B.ne = C.nw + (20,0); +Base.s = B.n + (0,-20); +\end{verbatim} + +Unfortunately, writing code such as this makes it hard for fellow programmers to visualize +its intent upon reading it. And ``fellow programmers`` include the author, five minutes later. + +Perhaps the next version of the code will drive home the point. The outcome is +the same as before, but the layout is stated in a more human-friendly way. You might even +infer by yourself that the numeric argument represents the distance between the objects. + +\begin{multicols}{2} +\begin{verbatim} +leftToRight(20)(A, B, C); +topToBottom(20)(Base, B); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/positioning.2} +\end{multicols} + +Below there are examples which show how these macros can be used. Suppose that we have the +following definitions for objects {\code X}, {\code Y}, and {\code Z}; also, let's assume +that {\code spacing} is a numeric variable set to {\code 5}. + +\begin{verbatim} +Picture.X("a"); +Picture.Y("..."); +Picture.Z("Cyan"); +\end{verbatim} + +\begin{tabular}{||l|c||} +\hline +{\code leftToRight.top(spacing)(X, Y, Z);} & \includegraphics{fig/positioning.3} \\ +\hline +{\code leftToRight.midy(spacing)(X, Y, Z);} & \includegraphics{fig/positioning.4} \\ +\hline +{\code leftToRight.bottom(spacing)(X, Y, Z);} & \includegraphics{fig/positioning.5} \\ +\hline +{\code topToBottom.left(spacing)(X, Y, Z);} & \includegraphics{fig/positioning.6} \\ +\hline +{\code topToBottom.midx(spacing)(X, Y, Z);} & \includegraphics{fig/positioning.7} \\ +\hline +{\code topToBottom.right(spacing)(X, Y, Z);} & \includegraphics{fig/positioning.8} \\ +\hline +\end{tabular} \\ + +To make things even easier, the following equivalent contructs are also allowed: + +\begin{verbatim} +leftToRight.midy(spacing)(X, Y, Z); +leftToRight(spacing)(X, Y, Z); +\end{verbatim} + +\begin{verbatim} +topToBottom.midx(spacing)(X, Y, Z); +topToBottom(spacing)(X, Y, Z); +\end{verbatim} + +If you want to specify that some objects have a given property equal, while the distance between them is given elsewhere, you can use the macro {\code same}. +This macro accepts a variable number of parameters, but at least two. The following table gives the interpretation of the macro for a simple example. + +\begin{tabular}{||l|l||} +\hline +{\code same.top(X, Y, Z);} & {\code X.top = Y.top = Z.top;} \\ +\hline +{\code same.midy(X, Y, Z);} & {\code X.midy = Y.midy = Z.midy;} \\ +\hline +{\code same.bottom(X, Y, Z);} & {\code X.bottom = Y.bottom = Z.bottom;} \\ +\hline +{\code same.left(X, Y, Z);} & {\code X.left = Y.left = Z.left;} \\ +\hline +{\code same.midx(X, Y, Z);} & {\code X.midx = Y.midx = Z.midx;} \\ +\hline +{\code same.right(X, Y, Z);} & {\code X.right = Y.right = Z.right;} \\ +\hline +\end{tabular} \\ + +Relative positions of two points can be declared more easily using the macros {\code below}, {\code above}, {\code atright}, {\code atleft}. +Let us assume that {\code A} and {\code B} are two points (objects of type {\code pair} in MetaPost). The following constructs are equivalent: + +\begin{tabular}{||l|l||} +\hline +{\code B = A + (5,0);} & {\code B = atright(A, 5);} \\ +{\code B = A - (5,0);} & {\code B = atleft(A, 5);} \\ +{\code B = A + (0,5);} & {\code B = above(A, 5);} \\ +{\code B = A - (0,5);} & {\code B = below(A, 5);} \\ +\hline +\end{tabular} + + +\section{The MetaUML Infrastructure} +\label{section:infrastructure} + +MetaPost is a macro language based on equation solving. Using it may seem quite +tricky at first for a programmer accustomed to modern object-oriented languages. +However, the great power of MetaPost consists in its versatility. Indeed, it is possible to write +a system which mimics quite well object-oriented behavior. Along this line, METAOBJ +\cite{metaobj} is a library worth mentioning: it provides a high-level objects +infrastructure along with a battery of predefined objects. + +Surprisingly enough, MetaUML does not use METAOBJ. Instead, it uses a custom written, +lightweight object-oriented infrastructure, provisionally called ``{\code util}''. +METAOBJ's facilities, although impressive, were perceived by me as being a bit too much +for what was initially intented as a quick way of getting some UML diagrams layed out. +Inspired by METAOBJ, ``{\code util}'' was designed to fulfill with minimal effort +the specific tasks needed to confortably position, allign or group visual objects +which include text. + +Another library having some object-oriented traits is the {\code boxes} +library, which comes with the standard MetaPost distribution. Early versions of +MetaUML did use {\code boxes} as an infrastructure, but this approach had to be abandoned eventually. +The main reason was that it was difficult to achieve good visual results when stacking texts +(more on that further on). For all it's worth, it did not fit well with the way in which MetaUML's +layout mechanism was shaping up at the time. + +\subsection{Motivation} + +Suppose that we want to typeset two texts with their bottom lines aligned, using {\code boxit}: + +\begin{multicols}{2} +\begin{verbatim} +boxit.a ("yummy"); +boxit.b ("cool"); + +a.nw = (0,0); b.sw = a.se + (10,0); + +drawboxed (a, b); % or drawunboxed(a,b) +draw a.sw -- b.se dashed evenly + withpen pencircle scaled 1.1; +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/boxes_vs_util.1} +\end{multicols} + +Note that, despite supposedly having their bottom lines alligned, +``yummy'' {\it looks} slightly higher than ``cool''. This would be unacceptable +in a UML class diagram, when roles are placed at the ends of a horizontal association. +Regardless of the default spacing being smaller in the {\code util} library, +the very same unfortunate misalignment effect rears its ugly head: + +\begin{multicols}{2} +\begin{verbatim} +Picture.a("yummy"); +Picture.b("cool"); +% comment next line for unboxed +a.info.boxed := b.info.boxed := 1; + +b.sw = a.se + (10,0); + +drawObjects(a, b); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/boxes_vs_util.2} +\end{multicols} + +However, the strong point of {\code util} is that we have a recourse to this problem: + +\begin{multicols}{2} +\begin{verbatim} +iPict.ignoreNegativeBase := 1; + +Picture.a("yummy"); +Picture.b("cool"); +% the rest the same as above +drawObjects(a, b); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/boxes_vs_util.3} +\end{multicols} + +\subsection{The Picture Macro} + +We have seen previously the line {\code iPict.ignoreNegativeBase := 1}. +Who is {\code iPict} and what is it doing in our program? MetaUML +aims at separating the ``business logic'' (what to draw) from the +``interface'' (how to draw). In order to achieve this, it records the ``how to draw'' +information within the so-called {\code Info} structures. The object {\code iPict} +is an instance of {\code PictureInfo} structure, which has the following properties +(or attributes): +\begin{verbatim} +left, right, top, bottom +ignoreNegativeBase +boxed, borderColor +\end{verbatim} + +The first four attributes specify how much space should be left around the +actual item to be drawn. The marvelous effect of {\code ignoreNegativeBase} +has just been shown (off), while the last two attributes control whether the border +should be drawn (when {\code boxed=1}) and if drawn, in which color. + +There's one more thing: the font to typeset the text in. This is specified +in a {\code FontInfo} structure which has two attributes: the font name +and the font scale. This information is kept within the {\code PictureInfo} structure +as a contained attribute {\code iFont}. Both {\code FontInfo} and {\code PictureInfo} +have ``copy constructors'' which can be used to make copies. We have already +the effect of these copy constructors at work, when we used: + +\begin{verbatim} +Picture.a("yummy"); +a.info.boxed := 1; +\end{verbatim} + +A copy of the default info for a picture, {\code iPict}, has been made within +the object {\code a} and can be accessed as {\code a.info}. Having a copy of the +info in each object may seem like an overkill, but it allows for a fine grained +control of the drawing mode of each individual object. This feature comes in very +handy when working with a large number of settings, as it is the case for MetaUML. + +Let us imagine for a moment that we have two types of text to write: one with a small font +and a small margin and one with a big font and a big margin. We could in theory +configure each individual object or set back and forth global parameters, but +this is far for convenient. It is preferable to have two sets of settings and specify +them explicitly when they are needed. The following code could be placed somewhere +in a configuration file and loaded before any {\code beginfig} macro: +\begin{verbatim} +PictureInfoCopy.iBig(iPict); +iBig.left := iBig.right := 20; +iBig.top := 10; +iBig.bottom := 1; +iBig.boxed := 1; +iBig.ignoreNegativeBase := 1; +iBig.iFont.name := defaultfont; +iBig.iFont.scale := 3; + +PictureInfoCopy.iSmall(iPict); +iSmall.boxed := 1; +iSmall.borderColor := green; +\end{verbatim} + +Below is an usage example of these definitions. Note the name of the macro: {\code EPicture}. +The prefix comes form ``explicit'' and it's used to acknowledge that the +``how to draw'' information is given explicitly --- as a parameter, +rather than defaulted to what's recorded in {\code iPict}, as with the {\code Picture} macro. +Having predefined configurations yields short, convenient code. + +\begin{multicols}{2} +\begin{verbatim} +EPicture.a(iBig)("yummy"); +EPicture.b(iSmall)("cool"); +% you can still modify a.info, b.info + +b.sw = a.se + (10,0); + +drawObjects(a, b); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/picture_info.1} +\end{multicols} + +\subsubsection{Fixed Sizes} + +By default, the size of a {\code Picture} object is set by its contents. However, +it is possible to specify fixed dimensions both the width and the height, independently. +This can be done by setting the {\code info}'s attributes {\code fixedWidth} and {\code fixedHeight} to values +greater than 0. If any of these attributes is left to its default value, {\code -1}, then for the corresponding +axis the dimension is set according to the dimension of the content. Nevertheless, the fixed dimensions are enforced, even though the contained object would have needed additional space. + +\begin{multicols}{2} +\begin{verbatim} +PictureInfoCopy.myFixed(iPict); +myFixed.ignoreNegativeBase := 1; +myFixed.fixedWidth := 15; +myFixed.fixedHeight := 20; +myFixed.boxed := 1; + +EPicture.a(myFixed)("a"); +EPicture.b(myFixed)(".-."); +EPicture.c(myFixed)("toolong"); + +leftToRight.bottom(10)(a, b, c); + +drawObjects(a, b, c); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/picture_info.2} +\end{multicols} + +\subsubsection{Content alignment} + +When fixed dimensions are used, one most likely would prefer a centered alignement of the contents in the +{\code Picture} box. This option can be expressed independently for each of the axes, +by setting the {\code info}'s attributes {\code valign} and {\code halign} to descriptive string values. +For horizontal alignement, {\code halign} can be set to {\code "left"} or {\code "center"}, and for +vertical alignement, {\code valign} can be set to {\code "bottom} or {\code "center"}. The default +values for these attributes are {\code "left"} and {\code "bottom"}, respectively. + +The next example uses horizontal centered alignement and a bottom alignement with a {\code 4.5} base offset, for +vertical alignement. This vertical alignement gives a better visual result than the centered one, at +least for the situations in which there are texts to be placed horizontally. + +\begin{multicols}{2} +\begin{verbatim} +PictureInfoCopy.myFixed(iPict); +myFixed.ignoreNegativeBase := 1; +myFixed.bottom := 4.5; +myFixed.valign := "bottom"; +myFixed.halign := "center"; +myFixed.fixedWidth := 25; +myFixed.fixedHeight := 15; +myFixed.boxed := 1; + +EPicture.a(myFixed)("a"); +EPicture.b(myFixed)("yum"); +EPicture.c(myFixed)("b"); + +leftToRight.bottom(10)(a, b, c); + +drawObjects(a, b, c); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/picture_info.3} +\end{multicols} + +\subsection{Stacking Objects} + +It is possible to stack objects, much in the style of {\code setboxjoin} +from {\code boxes} library. + +\begin{multicols}{2} +\begin{verbatim} +Picture.a0("yummy"); +Picture.a1("cool"); +Picture.a2("fool"); + +setObjectJoin(pa.sw = pb.nw); +joinObjects(scantokens listArray(a)(3)); + +drawObjects(scantokens listArray(a)(3)); +% or drawObjects (a0, a1, a2); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/object_stack.1} +\end{multicols} + +The {\code listArray} macro provides here a shortcut for writing +{\code a0, a1, a2}. This macro is particularly useful for generic +code which does not know beforehand the number of elements to be drawn. +Having to write the {\code scantokens} keyword is admittedly a nuisance, but +this is required. + + +\subsection{The Group Macro} + +It is possible to group objects in MetaUML. This feature is the cornerstone +of MetaUML, allowing for the easy development of complex objects, such as +composite stats in state machine diagrams. + +Similarly to the macro {\code Picture}, the structure {\code GroupInfo} +is used for specifying group properties; its default instantiation is +{\code iGroup}. Furthermore, the macro {\code EGroup} explicitely sets the +layout information. + +Here is an example: + +\begin{multicols}{2} +\begin{verbatim} +iGroup.left:=20; +iGroup.right:=15; +iGroup.boxed:=1; +iPicture.boxed:=1; + +Picture.a("yummy"); +Picture.b("cool"); +Picture.c("fool"); + +b.nw = a.nw + (20,20); % A +c.nw = a.nw + (15, 40); % B + +Group.g(a, b, c); +g.nw = (10,10); % C + +drawObject(g); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/group.1} +\end{multicols} + +After some objects are grouped, they can only be drawn +by invoking the {\code drawObject} macro on the group that aggregates them, and not individually. +Conveniently, once the relative positioning of objects within a group is set (line A and B), the whole +group can be ``moved'' do the desired position (line C), and all the contained objects will move along. + +\subsection{The PictureStack Macro} + +The {\code PictureStack} macro is a syntactic sugar for a set of pictures, +stacked according to predefined equations and grouped together. + +\begin{multicols}{2} +\begin{verbatim} +iStack.boxed := 1; +iStack.iPict.boxed := 1; +PictureStack.myStack("foo", + "bar: int" infont "tyxtt", + "nicely-centered" infont defaultfont, + "nice")("vcenter"); + +drawObject(myStack); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/picture_stack.1} +\end{multicols} + +Note the last parameter of the macro {\code PictureStack}, here {\code vcenter}. +It is used to generate appropriate equations based on a descriptive name. +The spacing between individual picture objects is set by the field +{\code iStack.spacing}. Currently, the following alignment names are +defined: {\code vleft}, {\code vright}, {\code vcenter}, +{\code vleftbase}, {\code vrightbase}, {\code vcenterbase}. All these +names refer to vertical alignment (the prefix ``{\code v}''); alignment can +be at left, right or centered. The variants having the suffix ``{\code base}'' align +the pictures so that {\code iStack.spacing} refer to the distance between the +bottom lines of the pictures. The unsuffixed variants use {\code iStack.spacing} as +the distance between one's bottom line and the next's top line. + +The ``{\code base}'' alignment is particularly useful for stacking text, since it +offers better visual appearance when {\code iPict.ignoreNegativeBase} is set to {\code 1}. + +\section{Components Design} + +Each MetaUML component (e.g. {\code Picture}, {\code PictureStack}, {\code Class}) is +designed according to an established pattern. This section gives more insight +on this. + +In order to draw a component, MetaUML categorizes the required information as follows: +\begin{itemize} +\item what to draw, or what are the elements of a component. +\item how to draw, or how are the elements positioned in relation to each other within the component +\item where to draw +\end{itemize} + +For example, in order to draw a picture object we must know, respectively: +\begin{itemize} +\item what is the text or the native picture that needs to be drawn +\item what are the margins that should be left around the contents +\item where is the picture to be drawn +\end{itemize} + +Why do we bother with these questions? Why don't we just simply draw the picture +component as soon as it was created and get it over with? +That is, why doesn't the following code just work? + +\begin{verbatim} +Picture.pict("foo"); +\end{verbatim} + +Well, although we have the answer to question 1 (what to draw), +we still need to have question 3 answered. The code below becomes thus a +necessity (actually, you are not forced to specify the positioning of an object, +because its draw method positions it to {\code (0,0)} by default): + +\begin{verbatim} +% question 1: what to draw +Picture.pict("foo"); + +% question 3: where to draw +pict.nw = (10,10); + +% now we can draw +drawObject(pict); +\end{verbatim} + +How about question 2, how to draw? By default, this problem is addressed behind the +scenes by the component. This means, for the Picture object, that a native picture is created +from the given string, and around that picture certain margins are placed, by means of MetaPost equations. +(The margins also come in handy when stacking Picture objects, so that the result doesn't look too cluttered.) +If these equations were defined within the Picture constructor, then an +usability problem would have appeared, because it wouldn't have been possible to modify the margins, +as in the code below: + +\begin{verbatim} +% question 1: what to draw +Picture.pict("foo"); + +% question 2: how to draw +pict.info.left := 10; +pict.info.boxed := 1; + +% question 3: where to draw +pict.nw = (0,0); + +% now we can draw +drawObject(pict); +\end{verbatim} + +To allow for this type of code, the equations that define the layout of the {\code Picture} object (here, what the margins are) +must be defined somewhere after the constructor. This is done by a macro called {\code Picture\_layout}. +This macro defines all the equations which link the ``what to draw'' information to the ``how to draw'' +information (which in our case is taken from the {\code info} member, a copy of {\code iPict}). +Nevertheless, notice that {\code Picture\_layouts} is not explicitly invoked. To the user's +great relief, this is taken care of automatically within the {\code Picture\_draw} macro. + +There are times however, when explicitly invoking a macro like {\code Picture\_layout} +becomes a necessity. This is because, by contract, it is only after the {\code layout} +macro is invoked that the final dimensions (width, height) of an object are +definitely and permanently known. Imagine that we have a component whose job is to +surround in a red-filled rectangle some other objects. This component +needs to know what the dimensions of the contained objects are, in order to be able to set +its own dimensions. At drawing time, the contained objects must not have been drawn already, +because the red rectangle of the container would overwrite them. +Therefore, the whole pseudo-code would be: +\begin{verbatim} +Create objects o1, o2, ... ok; +Create container c(o1, o2, ..., ok); +Optional: modify info-s for o1, o2, ... ok; +Optional: modify info for c; + +layout c, requiring layout of o1, o2, ... ok; +establish where to draw c; +draw red rectangle defined by c; +draw components o1, o2, ...ok within c +\end{verbatim} + +A natural conclusion is that an object must not be laid out more than once, because otherwise +inconsistent or superfluous equations would arise. To enforce this, by contract, +any object must keep record of whether its layout method has already been invoked, +and if the answer is affirmative, subsequent invocations of the layout macro would +do nothing. It is very important to mention that after the {\code layout} macro is +invoked over an object, modifying the {\code info} member of that object has +no subsequent effect, since the layout equations are declared and interpreted only once. + +\subsection{Notes on the Implementation of Links} + +MetaUML considers edges in diagram graphs as links. A link is composed of a path and the +heads (possible none, one or two). For example, since an association has no heads, it suffices +to draw along the path with a solid pen; however, an unidirectional aggregation has, in addition +to a solid path, two heads: one is an arrow and the other is a diamond. + +The general algorithm for drawing a link is: + +\begin{verbatim} +0. Reserve space for heads +1. Draw the path (except for the heads) +2. Draw head 1 +3. Draw head 2 +\end{verbatim} + +Each of the UML link types define how the drawing should be done, in each of the +cases (1, 2 and 3). Consider the link type of unidirectional composition. +Its ``class'' is declared as: + +\begin{verbatim} +vardef CompositionUniInfo@# = + LinkInfo@#; + + @#widthA = defaultRelationHeadWidth; + @#heightA = defaultRelationHeadHeight; + @#drawMethodA = "drawArrow"; + + @#widthB = defaultRelationHeadWidth; + @#heightB = defaultRelationHeadHeight; + @#drawMethodB = "drawDiamondBlack"; + + @#drawMethod = "drawLine"; +enddef; +\end{verbatim} + +Using this definition, the actual description is created like this: + +\begin{verbatim} +CompositionUniInfo.compositionUni; +\end{verbatim} + +As shown previously, is is the macro {\code link} which +performs the actual drawing, using the link description information +which is given as parameter (generally called {\code iLink}). +For example, we can use: + +\begin{verbatim} +link(aggregationUni)((0,0)--(40,0)); +\end{verbatim} + +%\begin{figure} +%\centering +%\includegraphics{fig/how-links-work.1} +%\caption{An example of a picture stack.} +%\label{fig:hlw} +%\end{figure} + +Let us see now the inner workings of macro {\code link}. Its definition is: + +\begin{verbatim} +vardef link(text iLink)(expr myPath)= + LinkStructure.ls(myPath, + iLink.widthA, iLink.widthB); + drawLinkStructure(ls)(iLink); +enddef; +\end{verbatim} + +\begin{figure} +\centering +\begin{tabular}{l|l} +$AB$ & the path specified by the user \\ +$|AA'|$ & {\code iLink.widthA}\\ +$|BB'|$ & {\code iLink.widthB} +\end{tabular} +\includegraphics{fig/how-links-work.2} +\caption{Details on how a link is drawn by MetaUML.} +\label{fig:hlw2} +\end{figure} + +First, space is reserved for heads, by ``shortening'' the given path {\code myPath} +by {\code iLink.widthA} at the beginning and by {\code iLink.widthB} at the end. +After that, the shortened path is drawn with the ``method'' +given by {\code iLink.drawMethod} and the heads with the ``methods'' +{\code iLink.drawMethodA} and {\code iLink.drawMethodB}, +respectively (figure \ref{fig:hlw2}). + +\subsection{Object Definitions: Easier {\code generic\_declare}} + +In MetaPost, if somebody wants to define something resembling a class in an object-oriented language, +named, say, {\code Person}, he would do something like this: + +\begin{verbatim} +vardef Person@#(expr _name, _age)= + % @# prefix can be seen as `this` pointer + string @#name; + numeric @#age; + + @#name := _name; + @#age := _age; +enddef; +\end{verbatim} + +This allows for the creation of instances (or objects) of class {\code Person} by using +declarations like: + +\begin{verbatim} +Person.personA; +Person.personB; +\end{verbatim} + + However, if one also wants to able able to create indexed arrays of persons, such as +{\code Person.student0}, {\code Person.student1} etc., the definition of class +{\code Person} must read: + +\begin{verbatim} +vardef Person@#(expr _name, _age)= + _n_ := str @#; + generic_declare(string) _n.name; + generic_declare(numeric) _n.age; + + @#name := _name; + @#age := _age; +enddef; +\end{verbatim} + +This construction is rather inelegant. MetaUML offers alternative macros to achieve +the same effect, uncluttering the code by removing the need for the unaesthetic {\code \_n\_} and +{\code \_n}. + +\begin{verbatim} +vardef Person@#(expr _name, _age)= + attributes(@#); + var(string) name; + var(numeric) age; + + @#name := _name; + @#age := _age; +enddef; +\end{verbatim} + +\section{Customization in MetaUML: Examples} +\label{section:customization} + +We have seen that in MetaUML the ``how to draw'' information is memorized into the so-called +``{\code Info}'' structures. For example, the default way in which a {\code Picture} object is +to be drawn is recorded into an instance of {\code PictureInfo}, named {\code iPict}. In this section we +present a case study involving the customization of {\code Class} objects. The customization of +any other MetaUML objects works similarly. Here we cannot possibly present all the customization +options for all kinds of MetaUML objects: this would take too long. Nevertheless, an interested reader can refer +to the top of the appropriate MetaUML library file, where {\code Info} structures are defined. +For example, class diagram related definitions are in {\code metauml\_class.mp}, activity diagram +definitions are in {\code metauml\_activity.mp} etc. + +\subsection{Global settings} + +Let us assume that we do not particularly like the default foreground color of all classes, and wish +to change it so something yellowish. In this scenario, one would most likely want to change +the appropriate field in {\code iClass}: + +\begin{verbatim} +iClass.foreColor := (.9, .9, 0); +\end{verbatim} + +After this, we can obtain the following result: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("A")()(); +Class.B("B")()(); +Class.C("C")()(); + +B.w = A.e + (20,0); +C.n = .5[A.se, B.sw] + (0, -10); + +drawObjects(A, B, C); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class_customization.1} +\end{multicols} + +\subsection{Individual settings} + +To modify the settings of one particular {\code Class} objects, another strategy is more appropriate. How about having class +{\code C} stand out with a light blue foreground color, a bigger font size for the class name and a blue border? + +\begin{multicols}{2} +\begin{verbatim} +iPict.foreColor := (.9, .9, 0); + +Class.A("A")()(); +Class.B("B")()(); +Class.C("C")()(); +C.info.foreColor := (.9, .7, .7); +C.info.borderColor := green; +C.info.iName.iFont.scale := 2; + +% positioning code ommited +drawObjects(A, B, C); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class_customization.2} +\end{multicols} + +As an aside, each {\code Class} object has an {\code info} member which is created as +a copy of {\code iClass}; the actual drawing is performed using this copied +information. Because of that, the {\code info} member can be safely modified after the object +has been created, obtaining the expected results and not influencing other objects. + +Another thing worth mentioning is that the {\code ClassInfo} structure contains +the {\code iName} member, which is an instance of {\code PictureInfo}. In our example we +do not want to modify the spacings around the {\code Picture} object, +but the characteristics of the font its contents is typeset into. To do that, +we modify the {\code iName.iFont} member, which by default is a copy of {\code iFont} +(an instance of {\code FontInfo}, defined in {\code util\_picture.mp}). +If, for example, we want to change the font the class name is rendered into, we would set +the attribute {\code iName.iFont.name} to a string representing a font name +on our system (as used with the MetaPost {\code infont} operator). + +\subsection{Predefined settings} + +This usage scenario is perhaps more interesting. Suppose that we have two +types of classes which we want to draw differently. Making the setting adjustments +for each individual class object would soon become a nuisance. MetaUML's solution consists in the +ability of using predefined ``how to draw'' {\code Info} objects. Let us create such objects: + +\begin{verbatim} +ClassInfoCopy.iHome(iClass); +iHome.foreColor := (0, .9, .9); + +ClassInfo.iRemote; +iRemote.foreColor := (.9, .9, 0); +iRemote.borderColor := green; +\end{verbatim} + +Object {\code iHome} is a copy of {\code iClass} (as it might have been set at +the time of the macro call). Object {\code iRemote} is created just as {\code iClass} +is originally created. We can now use these {\code Info} objects to easily set the +``how to draw'' information for classes. The result is depicted below, +please note the ``{\code E}'' prefix in {\code EClass}: + +\begin{multicols}{2} +\begin{verbatim} +EClass.A(iHome)("UserHome")()(); +EClass.B(iRemote)("UserRemote")()(); +EClass.C(iHome)("CartHome")()(); +EClass.D(iRemote)("CartRemote")()(); +\end{verbatim} +\columnbreak +\hspace{1cm}\includegraphics{fig/class_customization.3} +\end{multicols} + +\subsection{Extreme customization} + +When another font (or font size) is used, it may become necessary to change the space between the +baselines of attributes and methods. Figure below is the result of the (unlikely) code: + +\begin{multicols}{2} +\begin{verbatim} +Class.A("Foo") + ("a: int", "b: int") + ("foo()", "bar()", "gar()"); + +A.info.iName.iFont.name := metauml_defaultFontBold; +A.info.iName.iFont.scale := 1.2; + +A.info.iAttributeStack.iPict.iFont.scale := 0.8; +A.info.iAttributeStack.top := 10; +A.info.iAttributeStack.spacing := 11; + +A.info.iMethodStack.iPict.iFont.scale := 2; +A.info.iMethodStack.spacing := 17; +A.info.iMethodStack.bottom := 10; + +drawObject(A); +\end{verbatim} +\columnbreak +\hspace{4cm}\includegraphics{fig/class_customization.4} +\end{multicols} + +\begin{verbatim} +\end{verbatim} + +Both {\code iAttributeStack} and {\code iMethodStack} are instances of +{\code PictureStackInfo}, which is used to control the display of {\code PictureStack} objects. +%We can also customize the size and colors of the ``locks'' by setting {\code A.info.iLock}. + +As font names, you can choose from the globally defined {\code metauml\_defaultFont}, {\code metauml\_defaultFontOblique}, {\code metauml\_defaultFontBold}, {\code metauml\_defaultFontBoldOblique}, or any other name of a font that is available on your system. + +\section{Alternatives to MetaUML} + +No software package is perfect, and for this MetaUML is a prime example. Here is a list of packages that may also be used to create UML diagrams for LaTeX work: + +\begin{itemize} +\item uml.sty \cite{umlsty} +\item pst-uml \cite{pstumlsty} +\item umldoc \cite{umldoc} +\item TiKZ-UML \cite{tikzuml} +\end{itemize} + +Do not ignore the possibility of creating your diagrams using a GUI program, and then exporting them into a LaTex-friendly open format such as SVG \cite{svglatex}. + +\pagebreak +\input{test-suite} + +\pagebreak +\section{References} +\printbibliography[heading=none] + +\end{document} |