# Graphical Extensions to the Iowa Logic Language

### Oct 29, 1998

The Iowa Logic Specification Language was developed between 1983 and 1988, before the widespread introduction of graphical user interfaces, so it is purely textual.

The purpose of this page is to suggest a standard form for embedding graphical display information into a circuit description given in this language. There are two distinct issues here:

1. The icon to be used for circuit when incorporated, as a subcircuit, in some other higher level circuit.

2. The drawing of the internal details of a circuit when it is being edited.
These will be dealt with separately in the following. In general, the following suggestions are based on the idea that display information can be embedded in a circuit description using comments, so the simulator can ignore these comments while graphical editors can use them. Comments in the Iowa Logic Specification language take 3 forms:
```    -- Ada style comment, filling remainder of line
{ Pascal style comment, enclosed in curly braces }
(* Pascal style comment, enclosed in alternative braces *)
```
We'll use text embedded in these comments in what follows in order to direct the display of circuits. Specifically, we'll use the following general notational idea:
```    {USE:X=1,Y=30}
```
This specifies an X-Y coordinate pair to be put to some use. Where the context determines the use, the use may be omitted. Coordinates should be integers. I suggest that coordinates be measured in units of approximately 1 mm, rounded to something like 3 display pixels on a typical computer display. Numbers with zero digits may be omitted, and omitted numerical parameters are taken to have the value zero.

## The Icon

The basic structure of a circuit description in the Iowa Logic Specification Language is:

```    circuit name ( parameters );
inputs a, b, c;
outputs d, e;
parts
...
wires
...
end
```
Commas and semicolons are, in general, optional (their inclusion improves the quality of the syntax errors generated by the simulator, but the simulator is happy to parse input that contains no such decorations). Circuit descriptions created by a graphical editor should not include parse errors, and it is unlikely that users will ever edit circuit descriptions with graphical tags. Nonetheless, I suggest that graphical circuit editors should generate the commas and semicolons on their output and that they should not require them on input.

The parameter list on a circuit is only useful for generic circuits, where parameters specify such things as the word-size of a computer or the speed of some component. I suspect that graphical user interfac based circuit editors will have difficulty making use of these features of the language, so I will ignore the possibility of parameters in what follows.

We'll extend the basic outline of a circuit given above, as follows, to include the graphical information needed for drawing the icon for a circuit:

```    circuit name;
{ICON:H=xxx,W=yyy}
{BOX:X=nnn,Y=mmm,H=hhh,W=www}
{LINE:X=nnn,Y=mmm,H=hhh,W=www}
{TRI:X=nnn,Y=mmm,H=hhh,W=www}
{CIRC:X=nnn,Y=mmm,R=rrr}
{DOT:X=nnn,Y=mmm,R=rrr}
{ARC:X=nnn,Y=mmm,H=hhh,W=www}
{TEXT:X=nnn,Y=mmm,S=sss,T=text to display}
{LABE:X=nnn,Y=mmm,S=sss,T=text to display}
inputs a, b, c;
...
```
A circuit icon must have a fixed size, given by the ICON comment, although graphical editors may scale the icon to other sizes, if needed. The ICON comment should come first, and there may be any number of other drawing instructions, in any order, between the size comment and the inputs list for the circuit. These special comments should not span line breaks, and on output, a circuit editor should generate them one per line.

The BOX comment gives the X and Y coordinates of one corner of a rectangle to be drawn in the icon, while H and W give the height and width of the box. If H and W are both positive, the X and Y coordinates are for the lower left corner. Signed values of H and W may be used to give coordinates of other corners of the box.

The LINE comment gives the X and Y coordinates of one end of a the line to be drawn in the icon, and the H and W coordinates give the coordinates of the other end relative to the first end. If H is omitted, the line is horizontal; if W is omitted, the line is vertical.

The TRI comment gives the coordinates and dimensions of a box enclosing a triangle. The base will be one edge of the box, while the vertex will be on the center of the opposite edge. The base will always extend from the point X,Y, and the vertex will always be counterclockwise from the base around this point. Thus, if H and W are both positive, the base extends horizontally to the right of X,Y, and the vertex is above this.

The CIRC comment gives the coordinates of the center of a circle and its radius.

The ARC comment gives the dimensions of a rectangle to be drawn enclosing an arc of a circle. If the rectangle is a square, the arc will be displayed as a 90 degree arc centered on the X and Y coordinates given, and with radius equal to the dimension of the square. If one of X or Y is shorter, the radius will be the larger of X or Y, and that part of the arc extending outside the rectangle will not be drawn. This strange verison of ARC lets us draw the curved parts of an OR gate in a fairly simple way.

The TEXT comment allows textual material to be presented as part of the icon for a circuit. The coordinates locate the center of a rectangular box bounding the text. The S attribute gives the size of the text. Omitting S means size zero; negative sizes are smaller, positive sizes are bigger, and size zero is a sensible default size, perhaps something that makes capital letters about 4 mm or 12 pixels high. Size -1 should give letters about 3 mm tall, perhaps 9 or 10 pixels. The T attribute gives the text to display; if this is missing, the circuit name is displayed.

The LAB comment is identical to the TEXT comment, but the default text is the part name -- that is, the name of the instance of the circuit instead of the name of the circuit that will be instantiated to make the circuit.

The positions on the icon for a circuit where the inputs and outputs should be attached must be specified. This is done in the input and output lists for the circuit, as follows:

```    circuit name ( parameters );
...
inputs
a {ICON:X=xxx,Y=yyy},
b {ICON:X=xxx,Y=yyy},
c {ICON:X=xxx,Y=yyy};
outputs
d {ICON:X=xxx,Y=yyy},
e {ICON:X=xxx,Y=yyy};
parts
...
```
As before, graphical editors should allow multiple inputs per line, but should output things in pretty-printed format, as above. The X and Y coordinates given for each input or output specifies the point within the icon for that circuit where the input or output connections should be attached. Frequently, inputs will be on the left edge of the icon's box, and the icon will have a positive width. In this case, X=0 for these inputs and can therefore be omitted!

A 2-input and gate might be declared as follows:

```    circuit and2;
{ICON:H=12,W=12}
{LINE:H=12}
{ARC:X=6,Y=6,H=6,W=6}
{ARC:X=6,Y=6,H=-6,W=6}
inputs
a {ICON:Y=2},
b {ICON:Y=10};
outputs
c {ICON:X=12,Y=6};
...
```

## The Drawing

The circuit drawing must specify the dimensions of the drawing area, the location of the icons for each input, output and part within the drawing area, and the coordinates to be used for drawing each interconnecting wire.

```    circuit name;
{DRAW:H=100,W=150}
inputs
a {DRAW:Y=75},
b {DRAW:Y=50},
c {DRAW:Y=40};
outputs
d {DRAW:X=150,Y=65},
e {DRAW:X=150,Y=45};
parts
g1 {DRAW:X=40,Y=40}: and(2);
g2 {DRAW:X=40,Y=40}: and(2);
...
```
In the above, we have specified a circuit to be drawn in a 100 by 150 drawing area, with 3 inputs on the left edge of the area and 2 outputs on the right edge. By default, the names of the inputs and outputs should appear just above those points, and a small open circle, perhaps 2 mm diameter, should be drawn centered on the indicated point. It may be reasonable to support tage for overriding these details, but I will discourage this unless someone can provide a compelling argument supporting such an ammendment!

Note that the circuit will have both an ICON and a DRAW comment, one specifying the dimensions of the icon to be displayed when this circuit is used as a subcircuit, and the other specifying the dimensions of the drawing area to be used to display the internal structure of the circuit. Also note that each input and each output will end up having both an ICON and a DRAW comment. Where both ICON and DRAW comments are present, these should be accepted in any order and they should be output together on one line, ICON first, with no intervening spaces, as in the following example:

```           d {ICON:X=12,Y=6}{DRAW:X=150,Y=65},
```
The coordinates given for each part in the parts list specify the origin from which the icon for that part should be drawn. If the icon's dimensions are positive, this is the location of the lower left corner. The coordinates of the inputs and outputs of the part are derived from the drawing instructions for the icon itself.

Commentary and auxiliary doodles can be included using the notation introduced in the ICON drawing section. I suggest that all comments directing the inclusion of such material be given as an appendix to the circuit specification, between the last wire in the wire list and the end keyword marking the very end of the circuit. Such comments should be allowed, on input, mixed at random with the parts and wire lists.

Drawing instructions for wires, however, need to be included in the wire list! As already noted, the coordinates of the start and end of each wire are already known, so we only need to specify intermediate points. Part of the wire list for a circuit might look like the following:

```          a to b.in, c.in2;
b.out to c.in1;
c.out to d;
```
We can rewrite part of this as follows to add intermediate coordinate points:
```          b.out to
{TO:X=50,Y=30}
{TO:X=40,Y=60}c.in1;
```
In general, both X and Y coordinates for each point need not be specified because most wires are horizontal or vertical. Only when diagonal wires such as the above are drawn should both coordinates be given.

Where only one coordinate is given, the other coordinate should default to the previous coordinate along the same wire, starting with the coordinates for the origin of the wire (either an input pin to the circuit or the output of some subcircuit).

For wires with multiple destinations, what we must specify is a tree, with branching points given along the way:

```          a to
{DOT:X=60}
{TO:Y=40}b.in,
{TO:Y=20}c.in2;
```
The above text suggests a horizontal line from a to a branching point at X=60, and then vertical lines to Y=40 and Y=20, from which lines are drawn, respectively, to b.in and c.in2.

The above description makes good sense only if the Y coordinate of a is somewhere between 20 and 40, but it is up to the graphics editor to enforce such constraints. A good graphics editor will also forbid two wires to be drawn coincidentally, but will require, instead, that wires either intersect sharply or avoid each other by some reasonable margin.

Dots (branch points) are pushed on a stack as they are accumulated, and the comment {POP} indicates that the top dot is to be popped from the stack. In all cases, when a wire is specified, it is drawn from the top dot on the stack to the endpoint given. If there are no dots on the stack, only one endpoint may be given!