Me@0:
This file describes the first Visualizer project
Me@0:==========
Me@0:Steps in the project
Me@0:It looks like a good way to go is to start with some simple examples, then Me@0: work toward harder ones. This will be easier for you and at the same time let Me@0: me develop the data structures over time, as the project proceeds.
Me@0:A good way to organize the project is to do a number of smaller, mini-projects. Me@0: The first is just visualizing a syntax graph for "A + B", and having it paint Me@0: in the Display.
Me@0:Please be aware that the syntax-graph data structures and the custom properties Me@0: for EQNLang will change as more experience is gained in using them and it becomes Me@0: clear that they have to be modified. This will cause the code you write to be Me@0: modified, even after it is already working.
Me@0:==========
Me@0:Theory behind the syntax graph
Me@0:The theory behind the way I want to do the syntax graph will probably seem Me@0: a bit "strange" to you at first, especially if you have any experience with Me@0: compilers. It's a bit abstract; the reason is to allow the same data structures Me@0: to be re-used for any CTOS language that can be designed.
Me@0:The best file to look at first is the "SyntacticElement.java" file, which has Me@0: a very long comment that talks a bit about the thinking behind the data structures. Me@0:
Me@0:To summarize the idea behind the syntax data structures: Syntax is a pattern Me@0: that correlates to the visual pattern that humans look at. Each element of the Me@0: visual pattern has a corresponding element in the syntactic pattern.
Me@0:So, that is the only thing that the data structures need to support: an element Me@0: in the syntax for each visual cue. Visual cues are shapes and physical position. Me@0: Physical position determines which visual pattern a given shape belongs to (more Me@0: on this in the comment).
Me@0:So, there are only three kinds of thing in the syntax graph:
Me@0:Syntactic element
Me@0:Syntactic link
Me@0:Syntactic property
Me@0:plus, a set of property-types, and a set of property values, for links and Me@0: elements
Me@0:To summarize the data structures.. I have only two main syntactic data types: Me@0: elements and links. Each of these has a list of properties attached to it.
Me@0:The element properties state what kind of element it is (for EQNLang), such Me@0: as a root of a syntactic pattern, and/or a structural element, and/or a shape Me@0: containing element.
Me@0:The link properties state what kind of link it is (for EQNLang) such as a "back" Me@0: link to the root of a syntactic pattern, or a link that indicates that data Me@0: flows from one syntactic pattern to another..
Me@0:===========
Me@0:Property Names and Property Values
Me@0:I have decided to make all property names and all property values be integers. Me@0: I have included, in "EQNLangSyntaxSpecialization" a bunch of files that have Me@0: static constants in them. These constants define the property names and property Me@0: values. I also have a skeleton of how to use the properties in EQNLangSrcVisualizer.java Me@0:
Me@0:That file shows how to use the constants inside switch statements. The switch Me@0: statements steer, to code that takes some action on the DisplayList. Each piece Me@0: of code is only invoked if some set of things is true. For example, the method Me@0: "foobar" is called when "Currently processing a SyntacticElement, and it is Me@0: a command-type" is true, and only when that is true.
Me@0:If you want to use a different code structure, write me an e-mail that makes Me@0: a case for why you view the alternative structure as better.
Me@0:You will find in EQNLangSrcHolder a test syntax graph that has been built in Me@0: the code. This is the first syntax graph that you will visualize.
Me@0:The next project after this one will add multiple syntactic patterns, positioning Me@0: of them, and scaling of them. For now, just a single command with two variables.
Me@0:============
Me@0:What the Visualizer does
Me@0:Each command in EQNLang has not only a shape but "ports". Each port is either Me@0: an input or an output. They are placed visually around the shape.
Me@0:The Visualizer must place an expression in the position of each port. If the Me@0: input position in the syntax graph is empty, then the visualizer places an empty Me@0: box in that input port's position. If the input position links to another command-rooted Me@0: syntax pattern, then that entire syntax-pattern goes in the input-port's position. Me@0:
Me@0:The plus command in "A + B" has both input ports filled, and the command has Me@0: no explicit output port. By "no explicit output port" I mean that, upon evaluation, Me@0: the expression will be replaced by whatever it evaluates to. An expression's Me@0: visual placement implies where it's output goes to. Syntax patterns with implied Me@0: output ports are placed inside the input ports of other syntax patterns.
Me@0:In the expression "A + B", the input ports of the "+" are filled by the "A" Me@0: and "B". These are both "Name" patterns of memProcessor type. Name patterns Me@0: have no visual input ports, and implied output ports.
Me@0:What this all means is that information is needed about the position of input Me@0: ports for each command. This additional information is what the Visualizer will Me@0: use to place the syntax-patterns.
Me@0:==========
Me@0:Details of the Visualizer project
Me@0:Here is what I would like (most of this is also in comments in the code):
Me@0:-- The Visualizer will generate a DisplayList, which is a linked list of DisplayElements. Me@0:
Me@0:-- It first places a virtual shape for each syntactic element on a virtual Me@0: grid, then generates a DisplayElement for each virtual shape.
Me@0:-- The Visualizer doesn't know what the actual shapes are, it only knows the Me@0: name of the shape and a bounding box for it. The Visualizer works with the bounding Me@0: boxes.
Me@0:-- The Visualizer places shapes onto a virtual grid. The grid is continuous, Me@0: so each position is a float value.
Me@0:-- the Display will create its own version of the virtual grid, and set "0,0" Me@0: of its virtual grid to the lower left corner of its window (to start with.. Me@0: the User can then pan and zoom).
Me@0:-- Each syntactic element has associated layout information that is looked Me@0: up via some mechanism.
Me@0:-- The look-up info is loaded from disk during initialization of the Visualizer. Me@0:
Me@0:-- The layout information is a shape plus a list of ports.
Me@0:-- The shape is a shape-name plus a bounding-box.
Me@0:-- a bounding box consists of an origin x,y value and width plus height value.
Me@0:-- The bounding box for a shape is the "minimum enclosing bounding box". The Me@0: origin of the shape, when looked up, is always 0,0
Me@0:-- a port has a bounding box too, but it has no shape.. instead, it's bounding Me@0: box represents a constraint on how big the collection of shapes inside that Me@0: port can grow.
Me@0:-- The origin of a port bounding box is relative to the origin of the shape's Me@0: BB (bounding box). It's as if the shape defined its own mini-grid, and the ports Me@0: are placed on the shape's mini-grid. Thus, the origins of the ports are actually Me@0: offsets from the origin of the shape.
Me@0:-- The layout information for a "variable" in the syntax-graph comes from two Me@0: sources: the type of variable is used to look up a font plus font-size, while Me@0: the syntax-graph node has an attached text-string as a property-value.
Me@0:-- Generate the shape's bounding box by calculating it. First look up the bounding Me@0: box for each character in the string (from information about the font). Then Me@0: calculate the smallest bounding box that encloses the entire string. Make the Me@0: origin of the calculated enclosing bounding box be 0,0. A variable has no ports, Me@0: so done.
Me@0:-- do two passes when placing shapes. The first pass generates a tree of bounding Me@0: boxes, the second pass scales and translates the bounding boxes, placing them Me@0: onto the virtual grid.
Me@0:Me@0:
First pass:
Me@0:-- walk the syntax-graph (in a spanning tree fashion) and build up a tree of Me@0: BoundingBoxTreeNode.
Me@0:-- start with a root BBChildLink. Set it to be the current BBChildLink.
Me@0:-- set the root of the syntax-graph to be the current syntactic element.
Me@0:-- Generate a BoundingBoxTreeNode for the current syntactic element.
Me@0:-- Set the link in the current parent BBChildLink to the newly created BoundingBoxTreeNode. Me@0:
Me@0:-- look up the type of syntactic element to get its shape info and port list. Me@0:
Me@0:-- If the syntactic element has ports, then make a BBChildLink for each port Me@0: on the port-list. Make the BBChildLink's BB be the bounding box information Me@0: that was in the port-info. This is a constraint bounding box.
Me@0:-- Each port corresponds to a child in the syntax graph, go to each child and Me@0: make a BoundingBoxTreeNode, connect the corresponding BBChildLink to it, and Me@0: repeat the above process.
Me@0:-- There are two kinds of bounding box here. One kind is the minimum size box Me@0: that completely encloses a shape. The other kind is a constraint. When the second Me@0: pass is performed, the shapes will be scaled, such that the shape bounding box Me@0: gets as big as possible while still completely enclosed by some constraining Me@0: bounding box.
Me@0:-- See the comments in the skeleton code for BoundingBoxTreeNode and BBChildLink. Me@0:
Me@0:-- Once all the syntactic elements have been added to the bounding-box tree, Me@0: go to the second pass, which performs scaling and translation of bounding boxes, Me@0: which places them onto the virtual grid.
Me@0:Me@0:
Second pass:
Me@0:-- start with a default root bounding box that represents the entire graph. Me@0: This is the "root" bounding box. It's origin is at 0,0 on the virtual grid. Me@0:
Me@0:-- this root BB is made the parent constraining BB
Me@0:-- set the root node of the bounding-box tree as the current BoundingBoxTreeNode Me@0: and begin:
Me@0:-- <loop>
-- generate the minimum enclosing bounding box for the BoundingBoxTreeNode's Me@0: shape together with all of its child nodes. Leave the BoundingBoxTreeNode's Me@0: shape where it is, so the generated enclosing BB will have its origin placed Me@0: relative to the shape's origin, but possibly shifted due to the ports around Me@0: the shape.
Me@0:-- calculate the scaling factor that will make the enclosing bounding box as Me@0: large as possible while still being enclosed by the parent constraining bounding Me@0: box.
Me@0:-- apply the scaling factor (which moves the origins, as well as changes the Me@0: sizes of the BBs)
Me@0:-- calculate the translation to apply to the resized minimum enclosing BB to Me@0: shift its origin to match the origin of the parent constraining BB
Me@0:-- apply that translation to the shape's enclosing bounding box and each of Me@0: its children's constraining bounding boxes. Those bounding boxes are now at Me@0: their final placement on the virtual grid, at their final size.
Me@0:-- generate the DisplayElement for the BoundingBoxTreeNode's shape, and add Me@0: it to the DisplayList.
Me@0:-- now, repeat the process for the contents of each child constraining BB:
Me@0: In turn, set the child constraining BB to be the parent constraining BB.. and
Me@0: set the BBChildLink's node as the current BoundingBoxTreeNode.. and go to the
Me@0:
-- (Note, out of interest, that as one descends the bounding-box tree, the Me@0: scaling factors multiply, and translations add..)
Me@0:Me@0:
-- When this process is complete for the entire syntax-graph, send the DisplayList Me@0: to the Display.
Me@0: Me@0: