Help reading this manual
So far the project modifications that we have made used the text editor in the Editing Tool. We used graphics, but as a way to reflect system structures, not to build them ( "A peek at diagrams", page 21 , and subsequent discussions).
In line with the principles of seamlessness and reversibility recalled at the beginning of this Tour, EiffelStudio's text-diagram interaction is bi-directional. When you make a textual modification, the next incremental recompilation will update the diagram; but you can also work directly from the diagram, and the text will be generated or updated after each graphical operation.
Many people like to use the graphical mechanisms at the beginning of a project, to draft the overall structure of a system in "bubbles-and-arrows" style, then concentrate on text as they get closer to implementation. But there is really no such obligation. At any point in the development, just use the form that is more suited to your taste and to your needs of the moment.
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:
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 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.
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.
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.
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 .
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.
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
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.
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.
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.
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.
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).
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 .
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.
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:
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.
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 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.
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 :
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.
Copyright Interactive Software Engineering, 2001