Inside boxes


Any box can be opened from a model's main canvas by either right clicking on the box and choosing the Open... option from the menu that appears, or by double clicking on the box. The window that appears allows the box's properties, initial state, current state, message log and description to be viewed and/or edited. The types of view available depend on the class of the box being opened. Thus, processes don't have a current state, although buffers and data sources do. The precise layout of information within the views also depends on the class of the box being examined. Nevertheless, where possible a consistent approach is adopted.

General Features

All box windows have a panel at the top with a row of buttons (File, Mode, Run..., Help..., Done), a row specifying the box's name and class, a row in which a short comment describing the box can be given. These widgets should all be familiar from the main model window. The principal differences between an object's window and the main model's window is that some of the buttons on an object's window may not be present (e.g., the Run... button), corresponding to the fact that those functions are not available for individual objects, and that the lower panel of the box's window will (generally) not contain a box/arrow diagram.

Recall that a complete model, consisting of a set of boxes and arrows, is actually a self-contained compound box. The composition of a box as a set of elements is common to all box classes. In the case of compounds, the elements are other boxes and arrows, but in the case of buffers the elements are buffer elements, and in the case of data sources, the elements are messages. In all cases, the Initial State view (which is called Initial Contents in the context of buffers) provides a mechanism for viewing and editing the elements which comprise an object. The Mode menu also provides access to all other views available for the box being examined.

The Buttons

The top row of buttons hide a variety of functionality. Beneath the File button is a menu of various file related functions.

The Mode function is similar to that on the main project window. It allows switching between several ``views'' of the model. When mode is set to Diagram (the default) the the complete model's box/arrow diagram is shown in the window. Models have descriptions (analogous to project descriptions, but specific to each model within a project), and a model's description can be viewed or edited by switching to Description mode. The final viewing mode, Message Log relates to aspects of the model which change as the model is being executed.

The remaining two buttons, Help... and Done, are analogous to the corresponding buttons on the main project window. They provide context specific help and window closing respectively. Note though that the Done button hides a pull-down menu. By default Done will recursively save all changes that have been made to the box and its subboxes, but if changes should not be saved, then the Ignore all edits option should be selected from the Done menu. Alternatively, if modification to some but not all boxes are to be saved, then the Confirm Save option should be selected.

Naming a Box

A model may be named by directing keyboard focus to the Name field (by positioning the cursor over the Name field and left clicking) and typing the model's name. There are no restrictions on the characters which may be used in model names, but there is a restriction in length (35 characters). When a box's name is altered, the name is automatically (and spontaneously) updated on the project's history window. At this stage it is probably also appropriate to fill in the Comment field by giving a brief description of the model (or the intention behind the model).

The File Menu

Beneath the File button is a menu with seven options (right click over the button to pull this menu down): Save, Reopen, Clear, Print, Import..., Export..., and Check Syntax. Clicking the Save button will write the current model to disk. Clicking Reopen will reread the model from disk and redisplay it (thereby discarding any edits you may have made). Clear discards the complete model (though, provided you don't then Save, it can be recovered with Reopen). Print allows all aspects of model to be printed (in PostScript, HTML or plain ASCII text).

The Save button has a further menu to its right. This is because the save function can be applied either just to the box/arrow model, or recursively to the components of that model. Recall that a model is represented as a compound box: a big box containing lots of boxes inside it (and some of these boxes can themselves be compounds). A non-recursive save will write just the details of the outer-most box to disk. A recursive save will also write the details of all boxes (and any subboxes they might have).

The Import and Export functions are provided for advanced users who wish to bypass the user-friendly editing facilities provided by COGENT. Basically, the export function allows the contents of boxes to be transfered to or from a single ASCII text file. This file can then be edited (with a standard text editor) and reloaded via the Import function. A standard text editor will generally have the advantage of allowing repetitive changes to be automated. In addition, some users may be happier working in an environment with which they are more familiar. The disadvantage of using a text editor is that it is very easy to create incorrectly structured data without the constraints imposed by COGENT's structured editors.

To export a model, select the Export... function from the file menu. A dialogue box will appear asking for a filename. Enter a valid filename and COGENT will create a file by that name in your Import/Export Directory. This file can be edited with any text editor, but do be sure to restrict your edits so that they stick to the format of the original exported file.

The import facility, which is not available for compound boxes, is intended to take a model that was previously exported (and possibly edited) and load it into COGENT so that COGENT's other facilities can be used for displaying and animating the model. The difficulty with importing is that the file to be imported must adhere rigidly to the format that COGENT expects.

The last function, Check Syntax allows the well-formedness of a box/arrow model to be automatically checked. This operation checks that all necessary arrows are present, that no arrows are duplicated, and that no illegal arrows (e.g., arrows reading from processes, or sending from buffers) are present. Any syntax violations will be reported and corrected.

Initial State

The label and type of data shown on the Initial State view of a box depends on the class of box. Data sources show sequences of messages which will be sent on successive processing cycles. Buffers show a set of elements which are loaded into the buffer whenever the buffer is initialised. Processes show a set of rules and condition definitions which define the processes' behaviour. The view is not available for networks and data sinks, as no initial information is appropriate for these box classes.

The initial states of most boxes can be shown in either summarised or expanded form. A button on the top right of the window toggles between these two modes. In summarised mode, just the descriptions of elements are displayed. In expanded mode, full details of all elements are shown. Expanded mode is useful when looking at the full set of elements and seeing how they interact. Summarised mode is useful if an overview is required or there are too many elements to display in a single window.

The initial state canvas is sensitive to mouse clicks. Clicking the right button with the mouse position above an element (whether it be a data element, buffer element, rule or condition) highlights the item and brings up a menu allowing various operations to be performed on the item. Right clicking with the mouse positioned between items brings up a different menu, allowing new items to be created or pasted between existing items. The various operations in all cases (i.e., irrespective of the object class) are:

Double left-clicking on an item is equivalent to right-clicking and selecting Edit --- it brings up an editor for the selected item.

When a model is first created, the initial states of all boxes are empty. The first thing to do once you have opened, named and described a new box is usually to enter its initial contents. As the initial contents canvas is sensitive to mouse clicks, right clicking anywhere on the canvas will bring up some form of the menu described above. You may then proceed from there by selecting Create or one of its suboptions.


The Description option from the Mode menu gives access to the box's text-based description. When selected, the lower pane of the box's window changes to display a text editor containing the box's description. This text editor (and the buttons associated with it) mirrors that used for describing projects and individual models.

Current Contents

The Current Contents options from the Mode menu sets the lower pane of the box's window to display the contents of the box during processing. This view allows dynamic aspects of box to be viewed as they change. Thus, the current contents view of a buffer can be used to examine changes to buffer contents through time. Similarly, the current contents of a data source can be used to examine the consumption of data source elements by the remainder of the model.

The current contents view is for information and debugging purposes only. The user cannot directly alter anything that appears in the view.

Message Log

The message log, like the current state, is relevant only when a model is being executed. Then, all messages received and generated by the corresponding box are displayed in this view.

Message Matrix

Compound boxes may also be viewed in Message Matrix mode. This mode displays the compound as a 2-dimensional table, with a column for each message generating box and a row for each message receiving box. Messages (or abbreviations of messages) are displayed in the appropriate cells when the model is being executed. The message matrix provides a global view of message passing between a compound's subboxes, clearly illustrating the parallelism within the execution cycle.