Bouml – Tutorial

This tutorial is written to help you to use BOUML forthe first time, only few features of BOUML are exposed here, but afull description of BOUML is given in the reference manual.

The tutorial must be read in order because I will notrepeat each time the general commands to call a menu etc ...

Starting

When you execute BOUML the following message appears, hit okthis time, but you will have to define you own identifierfor an effective usage of BOUML :

The BOUML window appears (the drawing is dependent on the usedrelease of Qt, here the 2.4 under Linux to be compatible with theWindows release) :

The bouml window is composed of three parts :

• The left sub-window display a browser presenting your project, the navigation may be done by the mouse or the keyboard's arrows. The bold font is used when an item is modifiable, an item is read-only when you do not have the write permission for the file(s) supporting it.

• The bottom-right sub-window is used to display/modify the comment associated to the current selected item.

• The top-right part is used to display/modify the diagrams, these ones may be maximized or minimized.

Obviously the respective sizes of the sub-windows may be changed,placing the mouse on the separation between them. Note : if you haveat least a dual monitor configuration the better is to set theenvironment variable BOUML_LIMIT_DESKTOP, see here.

At this level you have to create a new project, or to load analready existing project.

Create a new project

Here we create a new project : in the menu Project choosenew, a file dialog appears (its aspect depend on the usedsystem and window manager) and you have to select the directory wherethe project will be placed and its name, I choose the project fooplaced under /tmp :

In this case BOUML creates the directory foounder /tmp, and places some files in /tmp/foo includingfoo.prj which is the file to load when you will re-load thisproject. Note : do not rename or delete the files produced byBOUML nor the directory itself !

A new dialog appears :

Following the recommendation, I set for instance the toggle forC++ and Java in the Language menu (we will see why later) :

The name of the project appears in thebrowser, the project is the top level package, a right mouseclick on it produces the menu :

As you can see, a package may contain other packagesand some views : use case view, class view, component view anddeployment view.

View, Use case

Bouml uses views ina project to organize and structure the model elements and diagrams.The different types of views provide different context menus listingthe diagrams and model elements that can be created in it.

To define use cases we need tohave a use case view, so we choose new use case view :

Bouml asks for the name of the view, to change it later the usecase view must be edited through a double mouse click, orchoosing edit in the menu appearing on a right mouse click,showing the use case editor :

Diagram

To create a use case diagram in this view, do a right clickon the use case view and choose new use case diagram :

The name is also asked, to change it the use case diagrammust be edited choosing edit in the menu appearing on a rightmouse click. Contrary to the non diagram items, a double click on adiagram show it :

Add elements in a diagram

To create and place a use case in the use case diagramyou have two ways :

• to do a right click on the use case view and to choose new use case, then to drag it from the browser to the diagram,

• or to hit the ellipsis button in the top of the diagram sub-windows, then to hit somewhere in the diagram sub-window. Note that the use case is created in the view containing the diagram, this will be the same thing in the others case whatever the diagram except for the states machine.

Let's Withdraw the name of theuse case.

To move the use case in thediagram, do a left click on it and move the mouse click down, thename follow the use case but the name may be movedindependently, for instance to place it in the middle of theellipsis. You may also select the use case and to use thearrows of the keyboard.

Create an actor named Customerlike you create the use case, to have :

Note that an actor is in fact a class, when thestereotype is actor the icon shown in the browser is an actor,else a class. To change the stereotype edit the class (doublemouse click on the class, or choosing edit in the menuappearing on a right mouse click on the class), choose among thepredefined list of stereotypes or enter a new one, read the referencemanual to change the predefined list of stereotypes.

The use case picture may be resized moving the pointsappearing when you click on the use case. The actorcan't be resized.

You have to ways to draw theassociation : a simple line as UML recommendation, or an arrow. Hiton the desired icon, left click on the actor, move the mouseclick down up to the use caseand release the click :

The lines may be broken during the initial construction if yourelease the click out of any item, or after the construction with aleft mouse click on the line and moving the mouse click down. Toremove a point in a line, double left click on it, or right click toshow the menu and choose remove from view. To abort a lineduring its construction : double click.

Add new elements in the diagram likethis (edit the dependency to set the stereotype include):

As you can see, the generalizations and dependenciesare visible on the browser, their menu (on a right click) in thebrowser allows to navigate to the target.

If you edit the generalizationfrom Withdraw you will have a simple dialog, this is not thecase for the generalization between the actors because thisinheritance may produce source code : an actor is a class.

Remove an element in a diagram

To remove something in the diagram,select the desired elements (left click on it) and press Suppror call the menu and choose remove from view. Note that thisis not possible to remove a label.

Delete / undelete browser element

To delete something from the model, usecontrol-d or choose delete from model, you may also dothat on the item in the browser. For instance if I delete theAdministrator :

Obviously the Administrator and the generalizationdisappear from the diagram, but this is not the case in the browser :they are just marked deleted. Their menu is modified : you mayundelete just the Administrator or this one and all hischildren (undelete recursively), you have no menu for thegeneralization because it can't be undeleted whileAdministrator is deleted !

Note that the deleted elements are notsaved, if you reload the project the deleted elements will bedefinitively lost.

Undelete the actorand the generalization, they do not reappears in the diagram.

Reinsert the actorin the diagram, using a drag&drop from the browser to the diagramsub-window, or hit the actor icon in the diagram then clicksomewhere in the diagram and select Administrator in theproposed list. The generalization is not automatically drawn, butthis may be the case for a class diagram (depending on thedrawing settings). To draw the generalization do adrag&drop from it the browser to the diagram.

Drawing settings

The colors andother drawing characteristics may be changed setting the drawingsettings. If you prefer to always have blue use case thebetter is to call the menu on the project (i.e. on foo in thebrowser) and choose edit drawing settings, go in the last taband change the default use case color. If you do that on a sublevel, for instance on the diagram, the scope of the new value willbe limited on the chosen level and recursively on all its children.The value specified on a upper level is followed while the settingvalues default, this is the case by default except at theproject level (there is nothing upper).

So, we change thecolor of the use cases to blue at the project level, now allare blue. We call the menu on Withdraw (in the browser or thediagram, doing a right click) and choose edit drawing settings,change the color which is default (to follow the rule definedupper) to green :

Now, in the browser call the menu on the diagram and chooseduplicate, this duplicate the diagram and call the dialog onthe clone to change the name for instance. Hit ok and open thediagram, yes this is a clone, edit its drawing setting to haveyellow use case and of course :

Select elements in a diagram

To select several elements in the diagram, for instance to movethem :

• control-a select all

• a left mouse click with the control key down allows to add/remove the pointed element from the selection list

• doing a left mouse click down out of any item and moving the mouse click down define a rectangle, on the mouse clock on all the included items will be selected

• choosing select linked items in the menu of an object in a diagram allows to select all the items having any line between them, practical isn't it (all the elements here) ?

z-dimension

Add and removeelements in Diagram2 to have (the diagram was maximized) :

Add a subject and resize it to have :

Now try to add a dependency from Transfer funds toCard identification : you can't. What is append ?

Because you add the subjectafter Card identification, the subject is upperthe use case and BOUML considers you try to do a dependencyfrom Transfer funds to the subject.

If you change the color of the subjectthis is more visible :

Don't panic, contrarily to other UML tools you don't have to redoall, just call the menu of the subject and choose lower,and now you may add the dependency.

Zoom, window size, diagram format

When you open a diagram the scale is set to 100% and the windowsize is unfixed.

When you change scale using the little arrows or directly writingthe desired value inside the spin box (practical to come back exactlyto 100%) the size of the arrows is unchanged, this allows to see themeven with a small scale, and to not use a large area for that whenthe scale is hight.

The dashed lines show the limits of the diagram (canvas size), youcan see something placed outside these lines. By default the formatof a diagram is European ISO A4. To Change the format of a diagram,call its menu from the diagram sub-window and choose the format (themenu of the diagram in the browser doesn't allow to do that). Theformat 'A' corresponds to the USA letter, 'B' to USA large and 'C' iseven larger. To set the format used for the diagram you will createin the future, choose the sub menu Diagram default format ofthe menu Miscellaneous.

fit% change the scale to be the larger one allowing to seeall the diagram elements depending on the diagram sub-window size.This may also be done choosing optimal scale in the diagrammenu.

In the opposite you can automatically change the size of thediagram sub-window to see all the diagram elements for the currentscale choosing optimal window size in the same menu or throughthe button .

Closing then re-opening the diagram the window size and the scaleare reset by default. To save the current window size and scale torestore them the next time you re-open the diagram, choose setpreferred size and scale in the menu of the diagram in thediagram sub-window (not possible from the menu in the browser).

Export diagram picture

There are several way to export a diagram picture :

• to print it : if needed open the diagram to show it, use the button which icon is a printer on the top left of the BOUML window

• to copy it, for a paste in an other program : if needed open the diagram to show it, choose the entry copy visible picture part in the diagram menu (not possible from the menu in the browser). The visible part is the part of the diagram which appears depending on the diagram sub-window's scrollbars position. To copy all the elements even the non visible ones, choose copy optimal picture part.

• to save the picture in a PNG file : if needed open the diagram to show it, choose the entry save visible picture part (png) in the diagram menu (not possible from the menu in the browser). To get all the elements even the non visible ones because of the current size of the sub windows, choose the entry save optimal picture part (png)

• to save the picture in a SVG file : if needed open the diagram to show it, choose the entry save visible picture part (svg) in the diagram menu (not possible from the menu in the browser). To get all the elements even the non visible ones because of the current size of the sub windows, choose the entry save optimal picture part (cvg).

• to use a plug-out, for instance the HTML generator. In case an exported diagram is not already opened, the scale and the size of the saved part are the default ones except if you had specify them using set preferred size and scale.

Sub package, class view, classdiagram, class

Now we want to design classes togenerate code.

For that we have first to create aclass view, and why not we don't want to place it directly inthe project package. First call the project menu (rightmouse click on the project's name in the browser) and choose newpackage, name it Package3. Call the Package3 menuand choose new class view named Class view4 :

A class diagram is not mandatory to define classes (exceptto add relations), but create a class diagram through theclass view menu, then open this diagram :

Click on the button which icon is a class and clicksomewhere in the diagram (it is also possible to create the classusing the class view menu in the browser), name the class C1

Because the actors are classes, they can be added in theclass diagram, using a drag & drop from the browser to thediagram sub-window, or using the diagram class icon and choosing forinstance Administrator hitting 'a' in the combo box orusing its arrow. The actor is drawn as an actor, this adefault for the classes having the stereotype actor (thisdepend on the drawing settings of the class, the other specialcases are for the stereotypes control, boundary and entity):

However in the normal case the goal of an actor is not tobe used to generate code, and in the generation settings thestereotype actor at class level is translated to ignoredin the target languages. To continue without this limitation, editthe generation settings, goin the tab stereotype andreplace ignored byclass in C++ and otherlanguage in the line for actor :

Add attribute and operation

We want to define an attribute named att, and anoperation named oper. Call the class menu doing a leftmouse click on the class in the diagram or in the browser, choose addattribute then add operation. When you add the membersthrough the diagram their editor are automatically called, notthrough the browser. The class members are visible in the browser andthe class picture :

Because of the default visibility set through the classsettings the attribute is protected and the classis public. The class settings may be set at the classview or package levels, following the same principles ofthe drawing settings.

Edit attribute

One decide that att must be an int, we have to editit, this may be done through several ways : double click on it in thebrowser, to call its menu on the browser and choose edit, otto call the menu of its class in the diagram choosing editattribute then att. You obtain the dialog :

The first tab concern the UML characteristics, by defaultan attribute is an instance member (not a class member), isnot volatile and is not read-only. Each other tab is link to aspecific language : with BOUML you may design in several languages atthe same time. For instance the HTML generator implementationis done in C++ and Java both.

Set the type to int, choosingamong the predefined types list (modifiable through the generationsettings) or typing int.

Go in the C++ tab (clicking onC++) :

As you can see, the visibility for C++ is the UML one by default,but this is not mandatory to allow to help to not have the samevisibility for instance in C++ and Java, and in C++ an attributemay be mutable.

The text behind declaration is editable, not the one behindresult after substitution which shows the source code as itwill be generated by the C++ generator (supposing you don't modify it!). Except for the keywords signaled by ${} and the userproperties signaled by @{} all the other characters aregenerated unchanged, including the new line. It is not difficult tounderstand that ${type} is replaced by int and ${name}by att, both set in the UML tab. This also means thatif you replace ${type} by aze the generated type foratt in C++ will be aze, etc ...

Perhaps you have coding rules and forinstance in C++ the name of an attribute must start by '_' ? Ofcourse you may rename the attribute _att, but to see the '_'in the class diagram is not very pretty, it is better to addthe '_' before ${name} :

Go in the Java tab :

The principle is the same, applied on Java.

It is not possible to see the Idl and Php definitions. Why ?Remember, at the beginning I ask you set the toggle for C++ and Javain the Languages menu, so the definitions for the non toggledlanguages are hidden. Close the dialog hitting on ok, ask forall the languages through the menu Languages, reedit theattribute and go in the IDL tab :

The declaration is empty ! This is also because Idl was not set inthe menu Languages. Hitting the button Default Statedeclaration we have :

First the visibility is private rather than protected becauseprotected doesn't exist.

Furthermore ${type} is replaced by long rather thanint, this is because the type int doesn't exist in IDL,and the better target is long, magic !

They are other type conversions automatically done by BOULM, forinstance if you choose any in UML you will have void *in C++, Object in Java and any in IDL. Obviously theseconversions are not hard coded, they are set through the generationsettings.

Go in the Php tab and ask for thedefault declaration :

This is a definition for Php5, if youwant to use Php4 the better is to change the visibility to package,and the definition will be :

The definitions given the default formswith the keywords may also be modified through the generationsettings, this allows you to add the '_' to name the attributein C++ as above etc ... look at the reference manual for more. Remark: when you change the generation settings, the definition ofthe already existing elements is notchanged.

Hit ok tovalidate the changes.

Class drawingsettings

In the class diagram only the name of the attribute and theoperation are visible, not the types nor the visibility, call theclass menu in the diagram and change three drawing settingslike this :

the class picture is now :

Do not hesitate to try the other drawing settings, and look at thereference manual for details.

Relations

We want to add amono directional association from C1 to Administrator,hit the corresponding icon on the top of the diagram sub-window andadd draw the relation as for the ones in the use case diagram:

As you can see the relation is added in the browser, by defaultits name is , edit therelation :

Like for the attributes we have the tab for UML andeach language.

Because the relation is unidirectionalonly one role is editable. Like for the attributes and operation thedefault visibility is specified by the Class settings.The role name will produce the name of the member, and wefound the flags already existing for the attributes : there nodifference between a relation and an attribute for the generationpoint of view.

Name the relation admin and goin the C++ tab :

By default an association and anaggregation produce a pointer in C++, an aggregation by value willnot produce a pointer. Obviously this default definition may bechanged through the generation settings or just for thisrelation.

Go in the Java tab :

Go in the Php tab :

Go in the IDL tab :

Go back in the UML tab, change first the type of therelation to have an association (bi directional) then do the othermodifications to have :

Go in the C++ tab and hit thebutton Default declaration for the two roles :

Go in the Java tab and hit the button Defaultdeclaration for the two roles :

Go in the IDL tab and hit thebutton Default declaration for the two roles :

As you can see the default definitions depend on the type of therelation and the multiplicity, of course these defaults aremodifiable through the generation settings.

The way a UML stereotype is projected for each language is alsomodifiable through the generation settings, as you can see above andbelow vector produces vector in C++ Vector inJava and sequence in IDL :

Press the button Ok and look atthe diagram :

Because the relation is now bi-directional this one appears in thebrowser in C1 and Administrator (I mark them in thebrowser : they are red).

Define struct, union, typedef, enum

To define a C++ or IDL structuse the class stereotype struct, and edit the class using theDefault declaration button on the desired language(s). In Javaa struct is implemented through a standard class, of coursethe projection of a class stereotype from UML to a given language maybe set through the generation settings, look at the dialogalready shown below and read the reference manual.

To define a C++ orIDL union use the class stereotype union as for astruct.

To define forinstance the C++ typedef T which is a pointer to a C1 :create the class T, and draw a dependency from T to C1

Edit the class andset the stereotype to typedef : the dialog is changed toindicate a base type, thanks to the dependency this oneis set to C1, but you may change it . Go in the C++ tab :

Of course thedependency in not mandatory, for instance to define typedef intturlututu

Add a '*' between${type} and ${name} :

The enums are supported through the stereotypes enumand enum_pattern.

Create a class E , edit E to set its stereotype to enumand press Ok, call the menu on the class in the browser chooseadd item and name it a, then recall the menu and chooseadd attribute and name it b. Edit E and go inthe C++ tab, ask for the default declaration :

As you can see, ${items} producea (the '...' indicates that only the name is shown, not the fulldefinition) but not b, this is because in C++ an enumonly have items, attributes and operations are illegal.

Go in the Java tab, this is anenum for at least the JDK5

b is produced by ${member} because its stereotype isattribute allowing to separate the items and theattributes.

Go in the Php tab, b doesn'tappears like in C++

Go in the IDL tab, b doesn'tappears like in C++

In the same way, if you add an operation in the enumthis one will not be defined in C++, Php and IDL.

Now create the class OE, edit itto set its stereotype to enum_pattern and press Ok,look at the menu of OE : it is only possible to add items.There is no difference with the E in C++ and IDL, but in Javathis is completely different because this kind of enum issupported by a class, this is for the Java release before the JDK 5:

An other time the form is defined through the generationsettings.

I propose you to edit the item a in E and OEin all the language to see the definitions.

Code generation, deployment view, artifact

Perhaps you had seen the class menu entry Generate, try togenerate the code for C1 : whatever the language you have theerror “C1 : does not have associated artifact”. inUML 2 the artifacts represent the generated files, sources, object,library, executable, jar etc ..., and of course the codegeneration is done in a source, so you must specify which source. Inthe first releases of BOUML the code generation was associated to thecomponents but because this is not compatible with UML 2 (UML1 was very evasive on the subject) I had prefer to do the change,contrarily to many tools ...

An artifactmay be placed only in a deployment view, create a deploymentview in the package Package3 (this is not mandatory, youmay place it in any package), let's suppose this name beDeployment view6

Now there are twoways to associate to each class an artifact of kind source and namedlike the class. The long way is to do for each class : create anartifact in Deployment view6, edit it to name it like theclass, to set its stereotype to source and to associate it theclass. The second way is better to associate several classes :associate Deployment view6 to Class view4 (because itcontains C1 etc ...) editing Class view4 :

Thanks to this association when you call the menu of C1 andthe other classes in Class view4 in the browser you may choosecreate source artifact and the appropriate artifact iscreated, do that for C1 :

Edit the artifact (you may select it calling the menu of C1and choosing select associated artifact) and go in the tabassociated classes :

C1 is associated to the artifact and you mayassociate several classes, in this case several classes will beproduced in the same source file, you can change their orderselecting an associated class and using go up/down.

Three tabs are not availables :

• Php source because the associate classes (here C1) doesn't have a definition in Php,

• Idl source because the associate classes (here C1) doesn't have a definition in IDL,

• Associated artifact because the stereotype of the artifact is source. If the stereotype is not source you may associate artifacts to an artifact for instance to indicate which artifacts compose an executable (this way is used by the plug-out genpro).

Look at the other tabs and refer to thereference manual for details

Create an associated artifact for T,O and OE.

Try to generate code, this is possiblecalling the menu on each class, or on their class view, or thepackage containing the view etc ... up to the projectlevel, in this case you may also call for the generation in the menuTools. If you do that you have an other error because BOUMLdoesn't know where the files must be generated, the artifacts givestheir names not their path !

It is possible to specify an owndirectory in each package (you may also specify a namespace/ package / module), it is also possible to specify a directory(or a base directory) for all the project in the generationsettings. Call the menu of the project in the browser (rightmouse click on foo) and choose generation settings, goin the last tab named Directory and specify a directoryfor C++ and Java, for instance /tmp for both (choose anotherand better directories in the future !), validate (button Ok).

Now if you ask for the code generationyou will have something generated. Ask for the generation a secondtime for the same language : the trace indicates that the files arenot modified, because this is useless. Note that the code generatorsreally check that the files already have the right contain, in caseyou change a file through an external editor and re-ask for thegeneration the modified file will be rewritten. This means that eventhis is not the faster way, you may ask for the code generation onthe project and the date of the already generated files will notchange, for the pleasure of your Makefiles or equivalent.

Epilogue

Now you are ready to start to use BOUML... and to read the reference manual because this tutorial onlycontain a little part of the features of BOUML.

To finish don't forget that :

• BOUML may be extended writing plug-outs. A plug-out may be developed in C++ or Java, look at the existing plug-outs as example.

• When you don't know how to do to have a desired generated code, the better is probably to write (a part of) this code by hand in file(s), and to do a reverse in a new and empty project (to not pollute he current one) and to look at the result. Obviously the reverse may also be used to constitute a project.

• Java programmers : use the plug-out Java Catalog !

Happy modeling !

Bruno Pagès