Proxima Home
Gallery
Download
Documentation
   Proxima Client
   Proxima Server
   Proxima Engine
   Building an editor
   User manual
Publications
Contribute
Bug reporting
Oblomov Systems
Presentation Sheet

Proxima
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 [[http://hackage.haskell.org/package/uuagc][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.


---++ Presentation AG

The syntax of the attribute grammar is described in the user manual of the attribute grammar system, which is available on the [[http://www.cs.uu.nl/wiki/bin/view/HUT/AttributeGrammarSystem][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:

<verbatim>
INCLUDE "PresentationAG_Generated.ag"
</verbatim>

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 (<tt>{}</tt>).

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 <tt>&lt;TYPE&gt;</tt>, we need to define a =loc.pres= attribute for both <tt>List_&lt;TYPE&gt;</tt> and <tt>ConsList_&lt;TYPE&gt;</tt>. For the nonterminal <tt>List_&lt;TYPE&gt;</tt>, an extra attribute <tt>press :: [Xprez]</tt> 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.

---++ Xprez

[[http://igitur-archive.library.uu.nl/dissertations/2004-1115-104001/c6.pdf][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 [[https://subversion.cs.uu.nl/viewvc/staff.doaitse.proxima/proxima/trunk/src/Presentation/XprezLib.hs?view=co][$proxima/src/Presentation/XprezLib.hs]]. 

---+++ Atomic presentations

The combinators for atomic presentations are:

<verbatim>
empty :: Xprez
text :: String -> Xprez
rect :: Xprez
img :: String -> Xprez
poly :: [ (Float, Float) ] -> Xprez
</verbatim>

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.

---+++ Composite presentations

<verbatim>
row, col, overlay  :: [ Xprez ] -> Xprez
rowR, colR :: Int -> [ Xprez ] -> Xprez
format :: [ Xprez ] -> Xprez
</verbatim>

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.

---+++ Specifying edit operations

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:

<verbatim>
type UpdateDoc doc clip = DocumentLevel doc clip -> DocumentLevel doc clip
</verbatim>

---++++ Mouse clicks
The =withMouseDown= combinator binds an edit operation to a presentation (which can be any subpresentation of the presentation of the nonterminal).

<verbatim>
withMouseDown ::  Xprez  -> UpdateDoc doc clip -> Xprez
</verbatim>

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:

<verbatim>
withMouseDownEx :: Xprez -> Wrapped doc enr node clip token -> Xprez
</verbatim>

---++++ Context menus

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:

<verbatim>
type PopupMenuItem doc enr node clip token = (String, Wrapped doc enr node clip token)
</verbatim>

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:

<verbatim>
withInheritablePopupMenuItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
addPopupItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
</verbatim>

For local items there are two similar combinators:

<verbatim>
withLocalPopupMenuItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
addLocalPopupItems :: Xprez -> [PopupMenuItem doc enr node clip token] -> Xprez
</verbatim>


---+++ Drag and drop

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. 

---+++ Miscellaneous combinators

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