Eiffel Home Page (Web) -- Getting started with Eiffel (local)

Displaying a cluster view

We are going to play with the root cluster. Make sure the Cluster tree and the Context Tool are up. Also make sure that the Context tool is in Isolate rather than Merge behavior ( "Isolating the context", page 68 ); you can see this by going to the Edit menu : if there is an entry Isolate context tool , select it; otherwise (the corresponding entry reads "Merge context tool") don't do anything, you're fine. (You can also use the Merge/Isolate button added earlier to the Browsing toolbar for this very purpose.)

The earlier diagrams were "class views", giving a picture of the world around a class. For a change, we are now going to start working with cluster views , showing the content of a cluster. Select the Diagram Tab in the Context Tool; from the Cluster Tree, pick-and-drop root_cluster to the Context Tool. This displays the graphical view of the root cluster in the Context Tool:

Hiding a class

First we decide that we don't want to be bothered with class INVALID . We could delete it altogether from the system by pick-and-drop its bubble to the Delete hole. This is not what we want, but try this now to see the confirmation request:

Make sure to answer No to that confirmation request (you want to keep the class even though it wouldn't be a catastrophe to lose it) and instead pick-and-drop the INVALID bubble into the Hide hole. This time there is no confirmation request, since the operation is reversible -- it just affects what's displayed in the cluster view -- and the class is removed from the display:

You can try undoing this change, then redoing it:

You can also click History which, during the rest of the session, will display the list of executed operations, and let you undo or redo many operations at once by clicking the oldest to be kept or the youngest to be redone.

For the rest of this discussion we assume INVALID is hidden.

Adding a class

We are now going to add a class graphically to our system. This means you don't have to worry about creating and initializing a file; EiffelStudio will take care of the details.

The useful button here is New class :

This button is a pebble, meant to be dropped into the diagram. Drop it somewhere above the bubble for TESTROOT ; the exact place doesn't matter, but it has to be within the area of the cluster root_cluster because we'll want our class to part of it. You're asked to name the class:

Overwrite the default name being proposed, NEW_CLASS , by the name HEIR2 , as we are going to create a new heir of PARENT . Don't touch the file name in the second field; as you type the class name EiffelStudio automatically sets the file name to heir2 . e , so you would only set it if you wanted to override the default convention for names of class files.

The new class is now in the diagram, part of root_cluster :

Using conventional drag-and-drop (not pick-and-drop), move the class bubbles for HEIR2 , TESTROOT and PARENT so that the display looks approximately like the following. The double circle around TESTROOT is the BON convention to identify a system's root class.

Adding an inheritance link

Now we are going to make HEIR2 an heir of PARENT . To create inter-class relations, you will select a relation by clicking one of the "Create link" buttons, then use pick-and-drop from the source class to the target class. There are three possibilities:

Click the button marked heir above. Now pick-and-drop from the HEIR2 bubble to the PARENT bubble. (Now you see why conventional drag-and-drop is used to move bubbles: pick-and-drop on the diagram serves to add links between classes).

To convince yourself that the new class has been made an heir of PARENT , in its text and not just in the diagram, pick-and-drop HEIR2 bubble to the Editing Tool at the top to see its text. (You could also control-right-click to the bubble to bring up a new Development Window on this class.) All the code has been generated from your graphical operations: creating the class produced a class template with all the standard style and clauses, and the reparenting operation made HEIR2 inherit from PARENT .

In a moment we'll use this Editing Tool to see how, conversely, EiffelStudio will automatically reflect in the diagram a change made to the text. For the moment go back to the Development Window.

In the Cluster Tree in the top-left pane, you will notice that the name of HEIR2 appears grayed out; so does the name of INVALID :

This is EiffelStudio's way of telling us that these two classes, listed because they appear in one of the system's clusters, are not actually in the system because the root class doesn't reference them directly or indirectly.

Adding a client link

Let's add HEIR2 to the system by making TESTROOT a client of this class. Click the button that selects Client as the next relation to make links (the link creation buttons were shown on page 117 ). Pick-and-drop from the TESTROOT bubble to the HEIR2 bubble. This asks you what kind of client link you want:

This technique gives you many option and in fact is a convenient way to build your classes, whether at the analysis, design or implementation level. Here, fill the fields as follows. For the top choice, keep the default, Attribute ; we'll give class TESTROOT an attribute of type HEIR2 . In the feature clause, which will indicate its export status, replace the default choice NONE by ANY , so that the attribute will be public. For its feature category, keep the choice currently displayed, Access . For its name, replace the default, new_feature , by the name my_heir . In the invariant clause, enter

my_heir /= Void

to specify the invariant property that this attribute should never be void. Finally, to see how EiffelStudio can generate the full accompaniment to an attribute, check the box Generate set procedure . Click OK .

The diagram -- shown below after a slight move of the bubble for TESTROOT for more readability -- shows that TESTROOT is now a client of HEIR2 . By default it only displays inheritance links; now it has switched automatically to a mode that shows client links as well, so that we also see that TESTROOT is (and always was) a client of PARENT through attributes including o2 .

Now pick-and-drop the class bubble TESTROOT to the top Editing Tool to see how the class has been modified. The situation here is different from what we saw earlier with HEIR2 , which had been generated from scratch by the diagram. Here TESTROOT existed before, in text form; so the diagram mechanisms have had to preserve the existing feature and feature clauses, and add the elements corresponding to what you have specified through the diagram mechanisms. Here is the beginning of class TESTROOT in its updated form:

Note how EiffelStudio has generated both the attribute and the associated "set" procedure, set_my_heir , complete with a precondition -- deduced from the invariant you have specified, my_heir /= Void -- and a postcondition. The unlabeled Feature clause of the existing class has been kept; the new features have been entered into clauses labeled Access and Element change , observing the Eiffel standard for common feature clauses in libraries.

If you look at the end of the class, you will see an invariant clause listing the invariant that you have entered.

Updating the diagram from the text

In this tour of the diagram facilities we have, so far, worked on the diagram and see the text updated immediately. Of course we want full reversibility. So let's make a change in the text and check the diagram.

The change will be very simple. We'll make TESTROOT a client of HEIR . In the top Editing Tool, use the editor to add an attribute declaration

other: HEIR

without further ado, as this is just a simple check.

If you are concerned about the correctness of the class, you may with to update its creation procedure make to add a creation instruction create my_heir . Without it the just added invariant would be violated upon creation.

Nothing happens yet to the diagram. This is normal: EiffelStudio doesn't update the diagram every time you type some text (which, for one thing, might be syntactically incorrect, or invalid). You need to recompile first. Click the Compile button. Then on the Context Tool click Diagram ; the new relation appears:

If the label other of that relation doesn't appear in the exact place shown here, try moving it using conventional drag-and-drop. You can only move such a link label within a small area on either side of the link.

Creating a cluster

Earlier on, we saw how to create a class from the EiffelStudio diagram, letting EiffelStudio take care of creating and initializing the file. Similarly, you can create a new cluster graphically, and let EiffelStudio create the corresponding directory.

To create a cluster, you can go through Project --> Project settings , or you can click the little Cluster Creation button at the top of the Cluster Tree:

Click this button. The resulting dialog asks you for the cluster name, and the existing cluster (non-precompiled) of which you want to make it a subcluster, here leaving only one choice:

Instead of the NEW_CLUSTER default name, type my_cluster ; select the only possible supercluster, root_cluster , and click Create at the bottom of the dialog.

This technique only allows you to create a new cluster as a subcluster of an existing one. You can create a top-level cluster by going through Project --> Project settings

Recompile the project and bring up the cluster diagram again. It shows the subcluster:

Make sure that the display looks approximately like the above; you may have to resize either or both clusters (drag a corner), and move the small cluster (drag-and-drop).

Moving a class to a different cluster

Among the many operations you can do graphically is to move a class from one cluster to another. Drag-and-drop (again, using conventional drag and drop) the HEIR2 class bubble to the rounded rectangle for MY_CLUSTER . Make sure the bubble fits entirely (that's why we wanted the cluster rectangle to be big enough).

This graphical manipulation has caused a structural change: class HEIR2 is now part of MY_CLUSTER . Check this by expanding the Cluster Tree on the left:

If you like, you can also look into the project directory -- using the Windows Explorer, or cd and ls on Unix/Linux -- and check that it now has a subdirectory my_cluster with a file heir2 . e containing the text of class HEIR2 .

Clearly, it's much more convenient to use EiffelStudio for such manipulations than to move files around manually.

Changing a class name

Here is another operation that would be even more tedious if you had to perform it manually: changing a class name. You must make sure that every reference to the class in the system is updated; but that's difficult to do with a text editor since -- assuming we are changing the name of HEIR to HEIR1 -- you must check references one by one to avoid, for example, changing an occurrence of the word in a string.

Instead, find the icon whose tooltip reads "Change class name and generics":

This is not a button but a hole (as you'll be reminded if you try just clicking it). Pick-and-drop HEIR to it:

As you can see, this dialog also serves to change the name of formal generic parameters when the selected class is generic. Type HEIR1 (or heir1 , EiffelStudio always converts class names to upper case) under New name and click OK .

As EiffelStudio traverses the system to update all references to HEIR , a progress bar appears so that you know what's going on. Everything is updated, including the current cluster diagram, which displays the new name in the class bubble:

Adjusting the display

A number of buttons enable you to customize the display:

So far all class bubbles had the same default color (yellow). Try pick-and-dropping a bubble into the Color hole to get a color palette that enables you to select a different color. This is useful if you want to highlight classes possessing certain properties, for example classes that are part of a certain Design Pattern.

Relation depth enables you to select the depth at which inter-class relations will be displayed. (Don't change this setting now.) Extend to cluster is more useful for class diagrams than for the cluster diagram we have now, which by default included all classes of the cluster; if you click it here it will add the class INVALID that you removed earlier. There is no need to do this now.

Views

So far the top-right View field has always shown DEFAULT . You can define any number of views in your project, and apply them to various class and cluster diagrams.

For example, using the buttons to show and hide links of various kinds

you can produce diagrams that only show the inheritance links, and others that only show the client links. If you want to keep both kinds of diagram, simply define views by typing view names -- such as Inheritance , Client , All_links -- into the View field.

You can also use views to retain some of the choices seen just before, such as different colors and depths.

To load a previously defined view, just use the menu associated with the View field.

You may remember that when we generated HTML documentation, the dialog (page 46 ) asked you to select a view among the available ones. You can choose a different view for each cluster.

Class diagrams, cluster diagrams

Whereas our initial encounter with diagrams at the beginning of this Tour used class diagrams, in the present discussion we have used cluster diagrams. Both are interesting. To obtain a class diagram, you will target a Context Tool to a class, and select the Diagram Tab. By default, this shows the parents of the class. Do this now for TESTROOT :

It's for class diagrams that the Relation depth button is most interesting. It will let you select the exact depth that you wish displayed for every relation:

This will conclude our review of the Diagram facilities of EiffelStudio, although you'll surely discover some further riches by yourself and through the rest of the documentation. We hope the complete seamlessness between text and pictures will enable you to increase the effectiveness of your analysis work, or your design work, or your programming -- whatever level of system development you need to tackle.