Gary Farmaner - Last updated: November 3, 1997
The Landscape Editor (lsedit) is a Java Applet which can display, edit, and provide simple visual queries, on software architectural diagrams (Landscapes).
The input to lsedit is in the form of the Tuple-Attribute Language (TA).
Due to limitation of the current Web Browsers, the editor functionality can only be obtained by running the applet within the appletviewer supplied with the Java Development Kit (JDK). This is accomplished by running one of two script files for file (direct) or URL (bookshelf) usage.
A reduced functionality Viewer can also be executed within a Java capable (and ENABLED) browser such as Netscape or MS-Internet Explorer. This is how it is used within the Portable Software Bookshelf
One common use within a environment.
This document assumes a familiarity with the TA language.
The Landscape Editor software and documentation was written by Gary Farmaner (dialog@cs.toronto.edu)
The lsedit is wrapped by the script files lsedit.file (direct editing) and lsedit (bookshelf editing) either of which launches the appletviewer from the Sun Java Development Kit on the editor classes.
You require an installation of JDK 1.0.2 or later to use lsedit.
The lsedit distribution is a tarred and gzipped file containing a lsedit.file script template, the Java class files which implement the Landscape Editor, and a local copy of this documentation HTML file.
The various script files must be editted before being used to set up appropriate paths.
Obtain the lsedit distribution.
Place it in a empty directory. To uncompress the files:
gunzip lsedit.tar.gz and then tar xf lsedit.tar OR
gzip -d lsedit.tar.gz and then tar xf lsedit.tar OR
tar xzf lsedit.tar (GNU tar)
Be sure to follow the directions in the supplied README file. It details some technical steps REQUIRED to make lsedit usable.
If you're building a full scale Portable Software Bookshelf (PBS) system, then the TA will have already been created and placed within the Bookshelf framework. You can skip to Starting lsedit .
For those who wish to start simple, and merely create and edit TA files directly on the file system, then there are couple of avenues to take:
For this you will need a fairly good understanding of the Tuple-Attribute Language (TA). You may also want to incorporate the supplied SCHEME section files listed in Appendix A.
For C language source, there is a suite of tools for parsing, extracting facts, infering facts, and creating initial layouts for landscapes. These are documented in Generating TA.
Using the above tools will result in the following two TA files being generated for each landscape:
In addition to these, you'll need to have a SCHEME TUPLE and SCHEME ATTRIBUTE sections. The lsedit distribution contains three example files which you can use and study. These are listed in Appendix A.
Depending on whether you are directly editing filesystem based TA files or editing a landscape stored within a Portable Software Bookshelf (PBS) environment, you use one of two script files:
lsedit.file TAfile
To make sure everything is installed, edited, and working properly, the lsedit distribution a stand-alone version of the eg_bookshelf landscape. From the directory where lsedit was uncompressed:
cd TA ../bin/lsedit.file eg_bookshelf.ta
This should bring up a landscape that looks much like the one presented in the eg_bookshelf PBS.
lsedit.url PROJECT LANDSCAPE RELEASE
In both case, the editor will start-up, read the TA file, parse, and finally display the architecture diagram within the editor's GUI.
This is how the Editor will look running in the appletviewer. To see how the Viewer will look running in a Bookshelf, see the Example Bookshelf
Each section is described below:
This has five GUI components which are fully documented in the section Landscape Editor Menu Bar
If the $ROOT entity is provided with an attribute "description", the value string will be displayed here. See Implied Scheme of Landscape Editor
If a CLOSED entity is provided with an attribute "description", the value string will be displayed here when the mouse cursor is passed over the entity. If a mouse button is pressed then description of all entities (including open boxes) is displayed. See Implied Scheme of Landscape Editor
All single line feedback messages from the applet will be displayed here. For example, when a mode change has occured.
The entity (box) or relation (edge) the mouse cursor (pointer) is currently over, will be displayed here. If mouse is not over an entity or relation in the landscape, this box will be emply.
The architecture diagram is displayed here.
For each mode one or more mouse keys will have certain functionality. These three boxes give a very brief reminder of the current functionality of (left to right) the left, middle, and right mouse buttons. See also: Mouse Button Notes
A listing box for multiple line text (such as visual query results). Also serves as the display box for the legend.
The menu bar contains the following menus:
Once editing has been completed, use this option to save the resulting landscape.
Displays a dialog box for entering the URL for a TA file. The editor will then open the supplied URL and display the associated TA.
Displays a dialog box for entering a pathname for a TA file. The editor will then open the file and display the associated TA.
On some systems the incorrect font geometry is returned to the applet which indicates a font is actually twice its actual height. This switch compensates for the problem.
A graphical display of the current entity/relation color scheme is displayed in the Listing Box.
Take back the previous action.
Scale the landscape up by 10% to make it appear larger.
Scale the landscape down by 10% to make it appear smaller.
The landscape diagram is displayed within the viewport. If the landscape is too large to be completely displayed, scroll bars will be visible to allow the user to scroll the document.
Selecting scale to viewport scales the diagram to optimally fit the current viewport.
This selection toggles the visibility of edges of a the currently selected relation class (Relation menu) between a visible and hidden state.
Under development - ignore this option
This selection toggles between persistant and non-persistant visual queries.
Visual queries performed when Query relations is used can be displayed only while the left mouse button is depressed (persistance off) or until the next query is performed or the query is cleared (persitance on).
Selecting this action causes the current query state to be cleared. This will result in all appropriate edges being redisplayed.
Edge elision stumps will be displayed from the source entity only.
Edge elision stumps will be displayed into the destination entity only.
Edge elision stumps will be displayed both from the source entity and into the destination entity.
This selection toggles the presence of the left and right description boxes.
This selection toggles the presence of the message feedback and entity/relation boxes.
This selection toggles the presence of the listing box.
When group selection is active, these options operate on the entire group selection.
Fine grain control, on a per entity/relation basis, is obtained through mouse buttons clicks and selecting a mode of operation.
In lsedit the right mouse button is reserved for a TA defined popup menu (see section Popup Menus for details). The left and middle mouse buttons select all the actions for the modes.
Note: For machines with one or two button mice:
One button: The middle button is simulated by pressing the ALT key and then the mouse button. The right button is simulated by pressing the META key and then the mouse button (eg. Apple logo on Mac).
Two button: The middle button is simulated by pressing the ALT key and then the LEFT mouse button.
Modes:
In order as they appear in the modes menu, the modes available are as follows (the letter in parenthisis is the keyboard shortcut):
This is the default mode for lsedit. It permits group selection using the MIDDLE mouse button. When used within a browser (currently limitted to the viewer) a navigate action is available with the LEFT mouse button. In that case the 'navlink' attribute will be processed and a http link invoked.
One common use within a Portable Software Bookshelf has been for the navlink to invoke a display of source for modules, and a display of the bookshelf page for subsystems.
Toggles edge elision on an entity:
NOTE: The way elision is displayed depends on the stump mode currently selected, not whether it was source or destination elided. Thus, toggling a previously elided edge back on may be a bit tricky, since either or both source and destination elision may be active for a particular edge.
Toggles containment elision on an entity. If closed, the contents of the entity will be hidden, and the entity will be coloured as specified in the scheme. If open, the contents (child entities and edges) will be displayed, and the entity will have a background colour determined by the lsedit tool based on the depth of the containment.
This mode provides a powerful visual query ability within the tool. A visual query displays a subset of the edges in the landscape. Edges are not elided for queries. And the particular relations involved depends on what relation menu item is selected.
The type of query is determined by which mouse button is used:
This mode allows you to move an entity or group of entities within the landscape. To move a single entity which isn't part of a group selection press the LEFT mouse button with the pointer over the desired entity. Move the mouse to move an outline of the entity. Release the mouse button to select final location.
To move a group of entities, make a group selection and then press the LEFT mouse button with the pointer over one of the group entities. Moving the mouse will move outlines of the entire group. Release the mouse button to select final location.
To move a single entity which is currently part of a group, merely press the left mouse button on a non-group entity (to clear the group selection) and then on the desired entity.
This mode allows you to resize entities within the landscape.
Using the LEFT mouse button, you can dynamically resize an entity to a desired size.
Using the MIDDLE mouse button, the entity will be sized such that the entity label is big enough to make the label completely visible, but no bigger.
By default, those edges leaving/entering an object will pass through an in or an out point which is automatically calculated. These points are determined by the number of relations, and spreading them evenly along a top/bottom edge.
You can select your own in or out point by selecting a particular relation from the relation menu, and then pressing the LEFT mouse to select for a new IN point, or the MIDDLE mouse button to select for a new OUT point.
The actual point will the point along an edge of the selected entity nearest to the current mouse position.
Allows you to add an entity to the landscape. The entity type is of that class which is currently selected in the relation menu. A particular relation class must be selected. 'All' is not a permitted relation.
Depress the LEFT mouse button with the mouse pointer over the source (subject) of the relation. Move the mouse, and a phantom edge will dynamically follow the mouse. Release the mouse with the pointer over the destination (relation subject). If the relation is legal (the SCHEME TUPLEs allow it) the edge will be added to the landscape.
Delete a selected entity and all edges it is involved in.
If an entity is a container, its children are NOT deleted, but rather they are moved to be contained by the parent container of the entity being deleted.
Delete a selected entity, and all edges it is involved in, and recursively delete all entities it contains.
Allows the label and description of a selected entity to be modified.
The defined relations (classes) (except $RELATION and contain) will be listed on this drop-down menu after "All".
This menu selects which relation(s) the various modes will be applied to. For example, by selecting a specific relation an edge elision can be applied to only that relation, while if "All" is selected the elision would be applied to all relations.
The defined entity classes (except $ENTITY) will be listed on this drop-down menu.
Currently this has only one use, for selecting the entity class for drawing new entities.
There are a number of options within the editor which are related to dealing with groups of entities. This section discusses how groups are selected and changed.
There is always one and only one group. Usually that group has no members. But, when a group is selected the entities in the group will be displayed with an X through the entity. If the entity is the key entity for the group, it will have a * drawn through it (actually the X in addition to a + drawm through the entity).
In Navigate or Move modes the MIDDLE mouse button allows for the selection of a group of entities.
Place the mouse pointer over the container of the entities you wish grouped. Moving the mouse will show a dynamic rectangle. Any entity that rectangle touches will be part of the group when the mouse button is released.
In Navigate or Move modes the SHIFT key, plus pressing the MIDDLE mouse button while the pointer is over an entity, will toggle the membership of that entity in the group.
If an entity is not a member of the group, it will be added to the group. In addition, it will be set as the key entity for the group.
If an entity is already a member of the group, it is removed from the group. If such an entity was the key entity, the key flag is transfered to another entity in the group.
A visible group can be built up from the empty group using the above method.
For certain group actions, such as alignment and sizing, one of the entities is used as a key.
Whenever a group is selected, one of the group will automatically set as the key entity. To select another member of the group as the key, press the MIDDLE mouse button while the pointer is over the entity you wish set as the key.
This section is only of interest to those generating TA to be viewed/edited with the lsedit tool.
The TA supplied to lsedit may or may not define an explicit scheme. However, irregardless of the scheme supplied, lsedit imposes a default scheme (schema), and has a specific interpretation of that scheme.
The equivalent of the following TA is pre-defined by lsedit:
SCHEME TUPLE :
$INHERIT ROOT_ENTITY $ENTITY
SCHEME ATTRIBUTE :
$ENTITY {
color = (0.0 0.0 1.0) // Box color == blue
x
y
width
height
label
description
elision
outelision
navlink
views
}
$ROOT_ENTITY {
reln_elided
stumpmode = 1
}
$RELATION {
color = (0.0 0.0 0.0) // Edge color == black
label
}
FACT TUPLE :
$INSTANCE $ROOT $ROOT_ENTITY
Attributes of $ENTITY:
The color used to fill a (closed) entity or used to draw a relation (edge). It is defined as a list of floating point numbers representing an RGB triple.
eg.
eg.c {
color = (0.0 0.0 1.0) // Blue
}
A set of entity layout attributes. The (x, y) coordinates relative to the container. And the width and height of the entity.
eg.
eg.c {
x = 100.2
y = 80.1
width = 70
height = 65
}
Within lsedit, only labels are displayed. By default, the label is assigned the same value string as the identifier name.
Each entity must have an identifier unique to the entire system the TA is modelling (which may be spread over many TA files). This global identifier may be long, or have other properties that make it undesirable to display. By overriding the label, a more appropriate display name can be defined.
Note the label is mostly intended for entities. However, the relation classes also have a label which permits a separation between the displayed relation name, and the associated id provided by the facts.
eg. for entity main.c
main.c {
label = "Main Program"
}
Each entity in the landscape (including $ROOT) can have an associated description. The description for $ROOT is displayed in the left description box, and the description for all other entities is displayed in the right description box.
eg. for entity global.h
global.h {
description = "Global include file"
}
Any text can appear between the quote marks. Carriage returns (line breaks) within the description string are shown as line breaks when the string is displayed. Lines are automatically wrapped if they are too long to be displayed.
The various flavours of edge (relation) elision are represented by these two attributes.
Represents elision of destination (incoming) edges and containment elision. The value type is a list of relation class ids.
Also handles internal/external elision 'internal' or 'external' values in list, as well as containment elision via 'contains' value.
eg.
main.c {
elision = (call contain)
}
Represents elision of source (outgoing) edges. The value type is also a list of relation class ids.
eg. for a subsystem (abstract architecture container) foo.ss elide incoming calls and reference edges, outgoing calls, amd all edges within the subsystem:
foo.ss {
elision = (call ref internal)
outelision = (use)
}
When the navlink attribute is defined, a left mouse button click on a landscape object with a navlink attribute will cause the editor to request the contents of the associated URL link. Thus, this provides the ability to define default click behaviour associated with any landscape object.
The possibilities are varied. The PBS model uses navlink to display source code for modules (files) and to jump to the landscape for subsystems.
The value type of the link attribute is a two element list:
navlink = (urlstring target)
A URL address string. Special meaning is given to substrings which are bracketted by $ characters. These will be macro substituted:
$ID$ is replaced by the landscape object's identifier (id).
$IDPREFIX$ is replaced by landscape objects's id not including any dotted extension suffix.
eg. main.c -> main, main.prg.c -> main.prg
All other macro substrings are replaced by the matching parameter as supplied to the applet ( tag).
eg. Simple navlink
main.c {
navlink = "http://system/src/main.c.html"
}
eg. Macro substitution
main.c {
navlink = ("http://system/cgi-bin/$VIEWER$/main.c TARGET_NEW)
}
Note: $ID$ and $IDPREFIX$ use the id not the label.
One of the following strings:
TARGET_TOP the full browser window
TARGET_NEW the full window in a new browser window
TARGET_FRAME the frame containing the applet
TARGET_LIST the right list box
Note: Only TARGET_LIST is useful for lsedit operating outside of a browser environment. The first three target the browser's window/frames and so have no meaning outside of a web browser.
A views attribute associated with an entity or an edge, allows for a popup menu to be displayed when the right mouse button is pressed while the pointer is over a selected entity or edge.
The attribute value is a list of lists. The outer list representing a list of menu entries. The inner lists representing the individual menu entries.
The format of the menu entries list is a 3-tuple: label link target where:
eg. Popup menu on the entity main.c
main.c {
views = ((Show source http://system/cgi-bin/showsrc,$ID$ TARGET_NEW)
(Show facts http://system/cgi-bin/showfacts,$ID$ TARGET_NEW)
)
}
Additional attributes of $ROOT_ENTITY:
These can be thought of as modelling global options of the editor.
The editor can selected to globally elide a relation (class). This means that the edges of an elided relation are not shown. The value type of this attribute is a list of relations (classes).
eg. Don't show call or reference edges
$ROOT {
reln_elided = (call ref)
}
This attribute defines the currently selected stumpmode. Its type is a integer literal. See documentation for stump mode for full information.
eg. Use stump mode 2
$ROOT {
stumpmode = 2
}