-
Notifications
You must be signed in to change notification settings - Fork 1
Presentation Sheet
The presentation sheet ($instantiation/src/PresentationAG.ag) specifies how the enriched document is presented to the user. It is written as an attribute grammar for the uuagc attribute grammar system. The presentation is defined by defining a synthesized attribute pres :: Xprez for each nonterminal in the document. The type of the presentation is Xprez, the presentation language of Proxima. The actual type has a number of type parameters (Xprez doc enr node clip token), but these will be omitted here for brevity.
The syntax of the attribute grammar is described in the user manual of the attribute grammar system, which is available on the project page. Each Proxima presentation sheet needs to include a generated file containing rules for attributes that are required by Proxima. It is included with this statement:
INCLUDE "PresentationAG_Generated.ag"
For each non-terminal, the presentation sheet should contain a rule for a local attribute loc.pres, which is used in PresentationAG_Generated to define the synthesized attribute lhs.pres. Each loc.pres rule must start with either structural if the non-terminal is presented structurally, or parsing if it has a parsing presentation. Ordinary Haskell code may be included in the attribute grammar code by surrounding it with braces ({}).
For every top-level parsing presentation, we must specify which parser will be used with the combinator parsingWithParser, which takes a parser of the appropriate type as its first argument, and the presentation as the second argument. Type checking will fail if the parser is not of the same type as the nonterminal. If besides the parser also a lexer needs to be specified (e.g. when there are multiple lexers for the editor), we can use parsingWithParserLexer, which takes as an extra argument the identifier string for the lexer, which is declared in the scanner sheet (as an Alex start code.)
If the document type contains a list of , we need to define a loc.pres attribute for both List_ and ConsList_. For the nonterminal List_, an extra attribute press :: [Xprez] is defined in PresentationAG_Generated. It contains the presentations of the list elements, and can be used to let the parent of the list specify its presentation, rather than the list itself. This is useful if the list type appears in several places in the document type, each with a different presentation.
Section 6.2 of Martijn Schrage's PhD thesis gives an overview of the language. Here we briefly explain the basic combinators, but for issues such as alignment and stretching, the reader is referred to the thesis. All Xprez combinators are defined in the $proxima/src/Presentation/XprezLib.hs.
The combinators for atomic presentations are:
empty :: Xprez
text :: String -> Xprez
rect :: Xprez
img :: String -> Xprez
poly :: [ (Float, Float) ] -> Xprez
The empty combinator has a presentation that is invisible and takes up no space; it is the neutral element for various presentation compositions. A string is presented with combinator text, and a rectangle with rect. The poly combinator takes a list of relative coordinates between (0.0, 0.0) and (1.0, 1.0) and produces a line figure that connects these points. The coordinates are relative because the final coordinates depend on the size of the poly presentation. Finally, img can be used to display external images. The argument is a string that contains the path to the image file.
row, col, overlay :: [ Xprez ] -> Xprez
rowR, colR :: Int -> [ Xprez ] -> Xprez
format :: [ Xprez ] -> Xprez
The row combinator yields a composite presentation in which all children are placed immediately next to each other, aligned according to their vertical reference lines. With col, the children are placed in a column underneath each other, aligned to their horizontal reference lines. An overlay is created with overlay, causing the children to be aligned according to both reference lines. Finally, with a formatter, presentations are put in a column of rows, based on the available width, useful for line breaking.
In the presentation sheet, we can specify edit operations for mouse clicks and context menus. The edit operation has type UpdateDoc, which is defined in Presentation/PresTypes as:
type UpdateDoc doc clip = DocumentLevel doc clip -> DocumentLevel doc clip
The withMouseDown combinator binds an edit operation to a presentation (which can be any subpresentation of the presentation of the nonterminal).
withMouseDown :: Xprez -> UpdateDoc doc clip -> Xprez
A second combinator withMouseDownEx is available for specifying a wrapped edit operation that can be targeted at an arbitrary level, instead of only the document. The type is:
withMouseDownEx :: Xprez -> Wrapped doc enr node clip token -> Xprez
Context menu items can be specified in a similar way as mouse click edit operations. A popup item consists of a label string and a wrapped edit operation:
type PopupMenuItem doc enr node clip token = (String, Wrapped doc enr node clip token)
We distinguish two different kinds of popup menu items: local items, which are bound only to the presentation of the nonterminal, but not to its children, and inheritable items, which are bound to the presentation of the nonterminal, as well as to the presentation of its descendents.
Inheritable items can be specified again in two ways. With addPopupItems, the items are appended to the list of items that were declared by outer presentations, whereas with withInheritablePopupMenuItems any popup items declared by outer presentations are replaces by the argument list of items. The types are:
withInheritablePopupMenuItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
addPopupItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
For local items there are two similar combinators:
withLocalPopupMenuItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
addLocalPopupItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
Besides drag and drop in graphs, Proxima supports document-level drag and drop on any list structure in the document. When a row or column presentation of a list is specified as draggable, the elements in the list can be reordered by dragging their presentations, and elements from the list can be dropped onto other lists of the same type. The drag operations on the presentation result in corresponding edit operations on the document.
In order to specify that a row or column is draggable, put the higher-order function dropTarget Horizontal in front of the row (for a column, use Vertical), and map the function dropSource on each of the children.
The XprezLib module contains a large number of other combinators, for example for setting fonts, colors, and alignment. The meaning of most of these combinators is obvious and can be taken from the source of the module.
-- Main.MartijnSchrage - 05 Mar 2010