| rev |
line source |
|
seanhalle@6
|
1 <html>
|
|
seanhalle@6
|
2 <head>
|
|
seanhalle@6
|
3 <title>Untitled Document</title>
|
|
seanhalle@6
|
4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
seanhalle@6
|
5 </head>
|
|
seanhalle@6
|
6
|
|
seanhalle@6
|
7 <body bgcolor="#FFFFFF">
|
|
seanhalle@6
|
8
|
|
seanhalle@6
|
9 <h1>The Visualizer Project</h1>
|
|
seanhalle@6
|
10 <p> </p>
|
|
seanhalle@6
|
11 <p>This file describes the first Visualizer project </p>
|
|
seanhalle@6
|
12 <p>========== </p>
|
|
seanhalle@6
|
13 <p>Steps in the project</p>
|
|
seanhalle@6
|
14 <p> It looks like a good way to go is to start with some simple examples, then
|
|
seanhalle@6
|
15 work toward harder ones. This will be easier for you and at the same time let
|
|
seanhalle@6
|
16 me develop the data structures over time, as the project proceeds. </p>
|
|
seanhalle@6
|
17 <p>A good way to organize the project is to do a number of smaller, mini-projects.
|
|
seanhalle@6
|
18 The first is just visualizing a syntax graph for "A + B", and having it paint
|
|
seanhalle@6
|
19 in the Display. </p>
|
|
seanhalle@6
|
20 <p>Please be aware that the syntax-graph data structures and the custom properties
|
|
seanhalle@6
|
21 for EQNLang will change as more experience is gained in using them and it becomes
|
|
seanhalle@6
|
22 clear that they have to be modified. This will cause the code you write to be
|
|
seanhalle@6
|
23 modified, even after it is already working. </p>
|
|
seanhalle@6
|
24 <p>========== </p>
|
|
seanhalle@6
|
25 <p>Theory behind the syntax graph </p>
|
|
seanhalle@6
|
26 <p>The theory behind the way I want to do the syntax graph will probably seem
|
|
seanhalle@6
|
27 a bit "strange" to you at first, especially if you have any experience with
|
|
seanhalle@6
|
28 compilers. It's a bit abstract; the reason is to allow the same data structures
|
|
seanhalle@6
|
29 to be re-used for any CTOS language that can be designed. </p>
|
|
seanhalle@6
|
30 <p>The best file to look at first is the "SyntacticElement.java" file, which has
|
|
seanhalle@6
|
31 a very long comment that talks a bit about the thinking behind the data structures.
|
|
seanhalle@6
|
32 </p>
|
|
seanhalle@6
|
33 <p>To summarize the idea behind the syntax data structures: Syntax is a pattern
|
|
seanhalle@6
|
34 that correlates to the visual pattern that humans look at. Each element of the
|
|
seanhalle@6
|
35 visual pattern has a corresponding element in the syntactic pattern. </p>
|
|
seanhalle@6
|
36 <p>So, that is the only thing that the data structures need to support: an element
|
|
seanhalle@6
|
37 in the syntax for each visual cue. Visual cues are shapes and physical position.
|
|
seanhalle@6
|
38 Physical position determines which visual pattern a given shape belongs to (more
|
|
seanhalle@6
|
39 on this in the comment). </p>
|
|
seanhalle@6
|
40 <p>So, there are only three kinds of thing in the syntax graph: </p>
|
|
seanhalle@6
|
41 <p>Syntactic element </p>
|
|
seanhalle@6
|
42 <p>Syntactic link </p>
|
|
seanhalle@6
|
43 <p>Syntactic property </p>
|
|
seanhalle@6
|
44 <p>plus, a set of property-types, and a set of property values, for links and
|
|
seanhalle@6
|
45 elements </p>
|
|
seanhalle@6
|
46 <p>To summarize the data structures.. I have only two main syntactic data types:
|
|
seanhalle@6
|
47 elements and links. Each of these has a list of properties attached to it. </p>
|
|
seanhalle@6
|
48 <p>The element properties state what kind of element it is (for EQNLang), such
|
|
seanhalle@6
|
49 as a root of a syntactic pattern, and/or a structural element, and/or a shape
|
|
seanhalle@6
|
50 containing element. </p>
|
|
seanhalle@6
|
51 <p>The link properties state what kind of link it is (for EQNLang) such as a "back"
|
|
seanhalle@6
|
52 link to the root of a syntactic pattern, or a link that indicates that data
|
|
seanhalle@6
|
53 flows from one syntactic pattern to another..</p>
|
|
seanhalle@6
|
54 <p> =========== </p>
|
|
seanhalle@6
|
55 <p>Property Names and Property Values </p>
|
|
seanhalle@6
|
56 <p>I have decided to make all property names and all property values be integers.
|
|
seanhalle@6
|
57 I have included, in "EQNLangSyntaxSpecialization" a bunch of files that have
|
|
seanhalle@6
|
58 static constants in them. These constants define the property names and property
|
|
seanhalle@6
|
59 values. I also have a skeleton of how to use the properties in EQNLangSrcVisualizer.java
|
|
seanhalle@6
|
60 </p>
|
|
seanhalle@6
|
61 <p>That file shows how to use the constants inside switch statements. The switch
|
|
seanhalle@6
|
62 statements steer, to code that takes some action on the DisplayList. Each piece
|
|
seanhalle@6
|
63 of code is only invoked if some set of things is true. For example, the method
|
|
seanhalle@6
|
64 "foobar" is called when "Currently processing a SyntacticElement, and it is
|
|
seanhalle@6
|
65 a command-type" is true, and only when that is true.</p>
|
|
seanhalle@6
|
66 <p> If you want to use a different code structure, write me an e-mail that makes
|
|
seanhalle@6
|
67 a case for why you view the alternative structure as better. </p>
|
|
seanhalle@6
|
68 <p>You will find in EQNLangSrcHolder a test syntax graph that has been built in
|
|
seanhalle@6
|
69 the code. This is the first syntax graph that you will visualize. </p>
|
|
seanhalle@6
|
70 <p>The next project after this one will add multiple syntactic patterns, positioning
|
|
seanhalle@6
|
71 of them, and scaling of them. For now, just a single command with two variables.</p>
|
|
seanhalle@6
|
72 <p> ============ </p>
|
|
seanhalle@6
|
73 <p>What the Visualizer does</p>
|
|
seanhalle@6
|
74 <p> Each command in EQNLang has not only a shape but "ports". Each port is either
|
|
seanhalle@6
|
75 an input or an output. They are placed visually around the shape. </p>
|
|
seanhalle@6
|
76 <p>The Visualizer must place an expression in the position of each port. If the
|
|
seanhalle@6
|
77 input position in the syntax graph is empty, then the visualizer places an empty
|
|
seanhalle@6
|
78 box in that input port's position. If the input position links to another command-rooted
|
|
seanhalle@6
|
79 syntax pattern, then that entire syntax-pattern goes in the input-port's position.
|
|
seanhalle@6
|
80 </p>
|
|
seanhalle@6
|
81 <p>The plus command in "A + B" has both input ports filled, and the command has
|
|
seanhalle@6
|
82 no explicit output port. By "no explicit output port" I mean that, upon evaluation,
|
|
seanhalle@6
|
83 the expression will be replaced by whatever it evaluates to. An expression's
|
|
seanhalle@6
|
84 visual placement implies where it's output goes to. Syntax patterns with implied
|
|
seanhalle@6
|
85 output ports are placed inside the input ports of other syntax patterns. </p>
|
|
seanhalle@6
|
86 <p>In the expression "A + B", the input ports of the "+" are filled by the "A"
|
|
seanhalle@6
|
87 and "B". These are both "Name" patterns of memProcessor type. Name patterns
|
|
seanhalle@6
|
88 have no visual input ports, and implied output ports. </p>
|
|
seanhalle@6
|
89 <p>What this all means is that information is needed about the position of input
|
|
seanhalle@6
|
90 ports for each command. This additional information is what the Visualizer will
|
|
seanhalle@6
|
91 use to place the syntax-patterns. </p>
|
|
seanhalle@6
|
92 <p>========== </p>
|
|
seanhalle@6
|
93 <p>Details of the Visualizer project </p>
|
|
seanhalle@6
|
94 <p>Here is what I would like (most of this is also in comments in the code): </p>
|
|
seanhalle@6
|
95 <p>-- The Visualizer will generate a DisplayList, which is a linked list of DisplayElements.
|
|
seanhalle@6
|
96 </p>
|
|
seanhalle@6
|
97 <p>-- It first places a virtual shape for each syntactic element on a virtual
|
|
seanhalle@6
|
98 grid, then generates a DisplayElement for each virtual shape. </p>
|
|
seanhalle@6
|
99 <p>-- The Visualizer doesn't know what the actual shapes are, it only knows the
|
|
seanhalle@6
|
100 name of the shape and a bounding box for it. The Visualizer works with the bounding
|
|
seanhalle@6
|
101 boxes. </p>
|
|
seanhalle@6
|
102 <p>-- The Visualizer places shapes onto a virtual grid. The grid is continuous,
|
|
seanhalle@6
|
103 so each position is a float value. </p>
|
|
seanhalle@6
|
104 <p>-- the Display will create its own version of the virtual grid, and set "0,0"
|
|
seanhalle@6
|
105 of its virtual grid to the lower left corner of its window (to start with..
|
|
seanhalle@6
|
106 the User can then pan and zoom). </p>
|
|
seanhalle@6
|
107 <p>-- Each syntactic element has associated layout information that is looked
|
|
seanhalle@6
|
108 up via some mechanism. </p>
|
|
seanhalle@6
|
109 <p>-- The look-up info is loaded from disk during initialization of the Visualizer.
|
|
seanhalle@6
|
110 </p>
|
|
seanhalle@6
|
111 <p>-- The layout information is a shape plus a list of ports. </p>
|
|
seanhalle@6
|
112 <p>-- The shape is a shape-name plus a bounding-box. </p>
|
|
seanhalle@6
|
113 <p>-- a bounding box consists of an origin x,y value and width plus height value.</p>
|
|
seanhalle@6
|
114 <p> -- The bounding box for a shape is the "minimum enclosing bounding box". The
|
|
seanhalle@6
|
115 origin of the shape, when looked up, is always 0,0 </p>
|
|
seanhalle@6
|
116 <p>-- a port has a bounding box too, but it has no shape.. instead, it's bounding
|
|
seanhalle@6
|
117 box represents a constraint on how big the collection of shapes inside that
|
|
seanhalle@6
|
118 port can grow. </p>
|
|
seanhalle@6
|
119 <p>-- The origin of a port bounding box is relative to the origin of the shape's
|
|
seanhalle@6
|
120 BB (bounding box). It's as if the shape defined its own mini-grid, and the ports
|
|
seanhalle@6
|
121 are placed on the shape's mini-grid. Thus, the origins of the ports are actually
|
|
seanhalle@6
|
122 offsets from the origin of the shape. </p>
|
|
seanhalle@6
|
123 <p>-- The layout information for a "variable" in the syntax-graph comes from two
|
|
seanhalle@6
|
124 sources: the type of variable is used to look up a font plus font-size, while
|
|
seanhalle@6
|
125 the syntax-graph node has an attached text-string as a property-value. </p>
|
|
seanhalle@6
|
126 <p>-- Generate the shape's bounding box by calculating it. First look up the bounding
|
|
seanhalle@6
|
127 box for each character in the string (from information about the font). Then
|
|
seanhalle@6
|
128 calculate the smallest bounding box that encloses the entire string. Make the
|
|
seanhalle@6
|
129 origin of the calculated enclosing bounding box be 0,0. A variable has no ports,
|
|
seanhalle@6
|
130 so done. </p>
|
|
seanhalle@6
|
131 <p>-- do two passes when placing shapes. The first pass generates a tree of bounding
|
|
seanhalle@6
|
132 boxes, the second pass scales and translates the bounding boxes, placing them
|
|
seanhalle@6
|
133 onto the virtual grid. </p>
|
|
seanhalle@6
|
134 <p> </p>
|
|
seanhalle@6
|
135 <p>First pass: </p>
|
|
seanhalle@6
|
136 <p>-- walk the syntax-graph (in a spanning tree fashion) and build up a tree of
|
|
seanhalle@6
|
137 BoundingBoxTreeNode. </p>
|
|
seanhalle@6
|
138 <p>-- start with a root BBChildLink. Set it to be the current BBChildLink. </p>
|
|
seanhalle@6
|
139 <p>-- set the root of the syntax-graph to be the current syntactic element. </p>
|
|
seanhalle@6
|
140 <p>-- Generate a BoundingBoxTreeNode for the current syntactic element. </p>
|
|
seanhalle@6
|
141 <p>-- Set the link in the current parent BBChildLink to the newly created BoundingBoxTreeNode.
|
|
seanhalle@6
|
142 </p>
|
|
seanhalle@6
|
143 <p>-- look up the type of syntactic element to get its shape info and port list.
|
|
seanhalle@6
|
144 </p>
|
|
seanhalle@6
|
145 <p>-- If the syntactic element has ports, then make a BBChildLink for each port
|
|
seanhalle@6
|
146 on the port-list. Make the BBChildLink's BB be the bounding box information
|
|
seanhalle@6
|
147 that was in the port-info. This is a constraint bounding box. </p>
|
|
seanhalle@6
|
148 <p>-- Each port corresponds to a child in the syntax graph, go to each child and
|
|
seanhalle@6
|
149 make a BoundingBoxTreeNode, connect the corresponding BBChildLink to it, and
|
|
seanhalle@6
|
150 repeat the above process. </p>
|
|
seanhalle@6
|
151 <p>-- There are two kinds of bounding box here. One kind is the minimum size box
|
|
seanhalle@6
|
152 that completely encloses a shape. The other kind is a constraint. When the second
|
|
seanhalle@6
|
153 pass is performed, the shapes will be scaled, such that the shape bounding box
|
|
seanhalle@6
|
154 gets as big as possible while still completely enclosed by some constraining
|
|
seanhalle@6
|
155 bounding box. </p>
|
|
seanhalle@6
|
156 <p>-- See the comments in the skeleton code for BoundingBoxTreeNode and BBChildLink.
|
|
seanhalle@6
|
157 </p>
|
|
seanhalle@6
|
158 <p>-- Once all the syntactic elements have been added to the bounding-box tree,
|
|
seanhalle@6
|
159 go to the second pass, which performs scaling and translation of bounding boxes,
|
|
seanhalle@6
|
160 which places them onto the virtual grid. </p>
|
|
seanhalle@6
|
161 <p> </p>
|
|
seanhalle@6
|
162 <p>Second pass: </p>
|
|
seanhalle@6
|
163 <p>-- start with a default root bounding box that represents the entire graph.
|
|
seanhalle@6
|
164 This is the "root" bounding box. It's origin is at 0,0 on the virtual grid.
|
|
seanhalle@6
|
165 </p>
|
|
seanhalle@6
|
166 <p>-- this root BB is made the parent constraining BB </p>
|
|
seanhalle@6
|
167 <p>-- set the root node of the bounding-box tree as the current BoundingBoxTreeNode
|
|
seanhalle@6
|
168 and begin: </p>
|
|
seanhalle@6
|
169 <p>-- <loop><loop point> </p>
|
|
seanhalle@6
|
170 <p>-- generate the minimum enclosing bounding box for the BoundingBoxTreeNode's
|
|
seanhalle@6
|
171 shape together with all of its child nodes. Leave the BoundingBoxTreeNode's
|
|
seanhalle@6
|
172 shape where it is, so the generated enclosing BB will have its origin placed
|
|
seanhalle@6
|
173 relative to the shape's origin, but possibly shifted due to the ports around
|
|
seanhalle@6
|
174 the shape. </p>
|
|
seanhalle@6
|
175 <p>-- calculate the scaling factor that will make the enclosing bounding box as
|
|
seanhalle@6
|
176 large as possible while still being enclosed by the parent constraining bounding
|
|
seanhalle@6
|
177 box. </p>
|
|
seanhalle@6
|
178 <p>-- apply the scaling factor (which moves the origins, as well as changes the
|
|
seanhalle@6
|
179 sizes of the BBs) </p>
|
|
seanhalle@6
|
180 <p>-- calculate the translation to apply to the resized minimum enclosing BB to
|
|
seanhalle@6
|
181 shift its origin to match the origin of the parent constraining BB </p>
|
|
seanhalle@6
|
182 <p>-- apply that translation to the shape's enclosing bounding box and each of
|
|
seanhalle@6
|
183 its children's constraining bounding boxes. Those bounding boxes are now at
|
|
seanhalle@6
|
184 their final placement on the virtual grid, at their final size. </p>
|
|
seanhalle@6
|
185 <p>-- generate the DisplayElement for the BoundingBoxTreeNode's shape, and add
|
|
seanhalle@6
|
186 it to the DisplayList. </p>
|
|
seanhalle@6
|
187 <p>-- now, repeat the process for the contents of each child constraining BB:
|
|
seanhalle@6
|
188 In turn, set the child constraining BB to be the parent constraining BB.. and
|
|
seanhalle@6
|
189 set the BBChildLink's node as the current BoundingBoxTreeNode.. and go to the
|
|
seanhalle@6
|
190 <loop point> </p>
|
|
seanhalle@6
|
191 <p>-- (Note, out of interest, that as one descends the bounding-box tree, the
|
|
seanhalle@6
|
192 scaling factors multiply, and translations add..) </p>
|
|
seanhalle@6
|
193 <p> </p>
|
|
seanhalle@6
|
194 <p>-- When this process is complete for the entire syntax-graph, send the DisplayList
|
|
seanhalle@6
|
195 to the Display.</p>
|
|
seanhalle@6
|
196 </body>
|
|
seanhalle@6
|
197 </html>
|
