diff options
Diffstat (limited to 'doc/context/sources/general/manuals/metafun/metafun-positioning.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/metafun/metafun-positioning.tex | 1013 |
1 files changed, 1013 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/metafun/metafun-positioning.tex b/doc/context/sources/general/manuals/metafun/metafun-positioning.tex new file mode 100644 index 000000000..5a3b1ece0 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-positioning.tex @@ -0,0 +1,1013 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\startcomponent metafun-positioning + +\environment metafun-environment + +\startchapter[reference=sec:positioning,title={Positional graphics}] + +\startintro + +In this chapter, we will explore one of the more advanced, but also conceptually +more difficult, graphic capabilities of \CONTEXT. It took quite a few experiments +to find the {\em right} way to support these kind of graphics, and you can be +sure that in due time extensions will show up. You can skip this chapter if you +are no \CONTEXT\ user. Because we're now a decade into \MKIV\ the tricks here +will assume that you use \CONTEXT\ \MKIV\ because we have a more convenient +interface there. For old|-|school \MKII\ usage you can look in old \METAFUN\ +manuals or in the \type {mkii} source files. Of course we remain compatible, it's +just that more (convenient) interfaces were added. + +\stopintro + +\startsection[title={The status quo}] + +After \TEX\ has read a paragraph of text, it will try to break this paragraph +into lines. When this is done, the result is flushed and after that \TEX\ will +check if a page should be split off. As a result, we can hardly predict how a +document will come out. Therefore, when we want graphics to adapt themselves to +this text, maybe even to text broken across lines, we have to deal with this +asynchronous feature of \TEX\ in a rather advanced way. Before we present a way +of dealing with this complexity, we will elaborate on the nature of embedded +graphics in \TEX. + +When \TEX\ entered the world of typesetting, desktop printers were not that +common, let alone color desktop printers. But times have changed and nowadays we +want color and graphics and if possible we want them integrated in the text. When +\METAPOST\ showed up it depended on the \DVI\ processor to recognize the +\POSTSCRIPT\ code as being produced by \METAPOST\ and therefore also include the +fonts that were used. But color was still limited to \RGB. When \PDFTEX\ evolved +I wrote an interpreter (in \TEX) that could translate the output to \PDF. This +also opened up the possibility to add features to \METAPOST, like \CMYK\ colors, +shading, transparencies etc. But basically the \TEX\ and \METAPOST\ processes +were rather isolated. We could of course pass information to \METAPOST\ and pick +up information from \METAPOST\ in a second pass. That has changed in \LUATEX. + +In order to really integrate \METAPOST\ graphics into the flow you need to know +where you are on the page and how large graphics should be, especially when you +want them to depend on the layout. A first solution to this was to embed specials +in the \DVI\ that could later be used to extract positions. In retrospect this +was a relative trivial extension, something that could have been around much +earlier but somehow didn't happen. Anyhow, after some experiments \PDFTEX\ got a +native position tracker which meant that no post processor was needed. Of course +\LUATEX\ inherited this feature too. Because positioning is rather bound to the +macro package reading this chapter only makes sense when you use \CONTEXT. + +\stopsection + +\startbuffer[arrow:1] +\startMPpositionmethod{mypos:arrow} + \startMPpositiongraphic{mypos:arrow} + save pa, pb, pm, pab, na, nb, sa, sb ; + path pa, pb, pm, pab ; numeric na, nb ; string sa, sb ; + % the tags + sa := texstr("from") ; + sb := texstr("to") ; + % we need to check page crossing so we fetch the page numbers + na := positionpage(sa) ; + nb := positionpage(sb) ; + % we use the repositioned shapes + pa := positionbox(sa) ; + pb := positionbox(sb) ; + % but want circles instead of rectangles + pa := llcorner pa .. lrcorner pa .. urcorner pa .. ulcorner pa .. cycle ; + pb := llcorner pb .. lrcorner pb .. urcorner pb .. ulcorner pb .. cycle ; + pickup pencircle scaled 1pt ; + if na = nb : + % both are on the same page + fill pa withcolor .800white ; + fill pb withcolor .800white ; + draw pa withcolor .625yellow ; + draw pb withcolor .625yellow ; + pm := .5[center pa,center pb] shifted (0,2*LineHeight) ; + pab := center pa .. pm .. center pb ; + pab := pab cutbefore (pab intersectionpoint pa) ; + pab := pab cutafter (pab intersectionpoint pb) ; + drawarrow pab dashed evenly withcolor .625red ; + positionatanchor(sa) ; + elseif nb < na : + % they are on different pages and we're at the first one + fill pb withcolor .800white ; + draw pb withcolor .625yellow ; + pab := center pb {up} .. ulcorner bbox pb ; + pab := pab cutbefore (pab intersectionpoint pb) ; + drawarrow pab dashed evenly withcolor .625red ; + positionatanchor(sb) ; + else : + % they are on different pages and we're at the last one + fill pa withcolor .800white ; + draw pa withcolor .625yellow ; + pab := center pa {up} .. urcorner bbox pa ; + pab := pab cutbefore (pab intersectionpoint pa) ; + drawarrow pab dashed evenly withcolor .625red ; + positionatanchor(sa) ; + fi ; + \stopMPpositiongraphic + % we put it here at the first position + \MPpositiongraphic{mypos:arrow} + % we need to carry information forward and make sure that we also + % check and flush at the second position of the pair + \ifnum\MPp{\MPvar{from}}<\MPp{\MPvar{to}}\relax + \expanded{\setMPpositiongraphic{\MPvar{to}}{mypos:arrow}{to=\MPvar{from}}} + \fi +\stopMPpositionmethod +\stopbuffer + +\startbuffer[arrow:2] +\setMPpositiongraphic{A-1}{mypos:arrow}{to=A-2} +\stopbuffer + +\startbuffer[box:1] +\startMPpositiongraphic{mpos:box}{fillcolor,linecolor,linewidth} + string tag; tag := "\MPvar{self}" ; + path box ; box := positionbox(tag) ; + box := box enlarged \MPvar{filloffset} ; + fill box + withcolor \MPvar{fillcolor} ; + draw box + withcolor \MPvar{linecolor} + withpen pencircle scaled \MPvar{linewidth} ; + positioninregion ; +\stopMPpositiongraphic +\stopbuffer + +\startbuffer[box:1:also] +\startMPpositiongraphic{mpos:box}{fillcolor,linecolor,linewidth} + path box ; box := positionbox(texstr("self")) ; + box := box enlarged texvar("filloffset") ; + fill box + withcolor texvar("fillcolor") ; + draw box + withcolor texvar("linecolor") + withpen pencircle scaled texvar("linewidth") ; + positioninregion ; +\stopMPpositiongraphic +\stopbuffer + +\startbuffer[box:2] +\setupMPvariables + [mpos:box] + [linecolor=blue, + linewidth=\linewidth, + fillcolor=lightgray, + filloffset=2pt] + +\setupMPvariables[mpos:box][linecolor=darkred] +\setupMPvariables[mpos:par][linecolor=darkred] + +\startpositionoverlay{backgraphics} + \setMPpositiongraphic{A-0}{mpos:box}{self=A-0} + \setMPpositiongraphic{A-3}{mpos:box}{self=A-3} + \setMPpositiongraphic{A-4}{mpos:box}{self=A-4} +\stoppositionoverlay +\stopbuffer + +\getbuffer[arrow:1,arrow:2] +\getbuffer[box:1,box:2] + +\startsection[title={The concept}] + +\index {graphics+positioning} +\index {positioning} +\index {anchoring} + +Because we have a \LUA\ connection in \MPLIB, we have implemented a couple of +helpers that make live easier. This is also why the following examples are \MKIV\ +specific, although \MKII\ can do the same, but with a bit different set of +helpers. We can for instance query properties of \hpos {A-0} {positions} without +using \TEX\ macros but can use \METAPOST\ macros instead. Let's give an example. +The background and frame behind the word \type {position} in this paragraph is +not done with \type {\framed} but using a different mechanism: + +\starttyping +to get \hpos {A-0} {positions} sorted +\stoptyping + +The \type {\hpos} refers to a position and we have bound that position to a graphic: + +\starttyping +\setMPpositiongraphic{A-0}{mpos:box}{self=A-0} +\stoptyping + +The graphic itself is defined with: + +\typebuffer[box:1] + +A variant that has no macro calls and does all via the \LUA\ intercaface in \MKIV\ is +the following: + +\typebuffer[box:1:also] + +A \type {\hpos} position has several properties: the coordinates of the origin: +\type {x} and \type {y}, the dimensions of the boxed content, \type {w}, \type +{h} and \type {d}, and the page number \type {p}. An additional helper \type +{positioninregion} will move the drawing to the right spot in the region. +Examples or regions are the page, text area or some overlay. The \type +{positionatanchor} variant relocates to the anchor of the given tag. The first +helper is actually a shortcut for: + +\starttyping +currentpicture := currentpicture shifted - positionxy(positionanchor) ; +\stoptyping + +In our case we use a dedicated layer \type {backgraphics} that we have hooked into +the page backgrounds: + +\starttyping +\setupbackgrounds + [page] + [background={backgraphics,foreground,foregraphics}] + +\defineoverlay [backgraphics] [\positionoverlay{backgraphics}] +\defineoverlay [foregraphics] [\positionoverlay{foregraphics}] +\stoptyping + +The relation between position graphics and that layer are defined as follows +(we will come back to this in a moment): + +\typebuffer[box:2] + +\stopsection + +\startsection[title={A more detailed view}] + +As we know, a decent portion of \TEX's attention is focused on breaking +paragraphs into lines and determining the optimal point to split off the page. +Trying to locate the optimal points to break lines is a dynamic process. The +space between words is flexible and we don't know in advance when a \hpos {A-1} +{word} or piece of a word |<|maybe it's best to talk of typographic \hpos {A-2} +{globs} instead|>| will end up on the page. It might even cross the page +boundary. + +In the previous section we saw \hpos {A-3} {word} and \hpos {A-4} {globs} +encircled and connected by an arrow. This graphic can be drawn only when the +position and dimensions are known. Unfortunately, this information is only +available after the paragraph is typeset and the best breakpoints are chosen. +\bpos {A-5} Because the text must be laid on top of the graphic, the graphic must +precede the first word in the typeset stream or it must be positioned on a +separate layer. In the latter case it can be calculated directly after the +paragraph is typeset, but in the former case a second pass is needed. \epos {A-5} +Because such graphics are not bound to one paragraph, the multi||pass option +suits better because it gives us more control: the more we know about he final +state, the better we can act upon it. Think of graphics on the first page that +depend on the content of the last page \bpos {A-6} or, as in this paragraph, +backgrounds that depend on the typeset text. \epos {A-6} + +The arrows that connect the shapes are drawn with the following code that now +looks familiar: + +\typebuffer[arrow:1] + +and + +\typebuffer[arrow:2] + +However, here we anchor at one of the positions because we don't flush in a layer +but at the position itself. Indeed it looks complex. + +It may be clear now that we need some positional information in order to provide +features like the ones shown here. The fact that we will act upon in a second +pass simplifies the task, although it forces us to store the positional +information between runs in some place. This may look uncomfortable at first +sight, but it also enables us to store some additional information. Now why is +that needed? + +A position has no dimensions, it's just a place somewhere on the page. In order +to do tricks like those shown here, we also need to know the height and depth of +lines at a specific point as well as the width of the box(es) we're dealing with. +In the encircled examples, the dimensions of the box following the positional +node are stored along with the position. + +In order to process the graphics, we tag each point with a name, so that we can +attach actions to those points. In fact they become trigger points. As we will +demonstrate, we also need to store the current page number. This brings the data +stored with a point to: + +\starttyping +<identifier> <pagenumber> <x> <y> <width> <height> <depth> +\stoptyping + +Actually we store more information, for example the region in which the positions +sit. Depending on the use we can also get access to paragraph and line properties +but discussing these is beyond this manual. These are for instance used in the +text backgrounds. + +The page number is needed in order to let the graphics engine determine boundary +conditions. Backgrounds like those shown here can span multiple pages. In order +to calculate the right backgrounds, some additional information must be +available, like the top and bottom of the current text area. In fact, these are +just normal points that can be saved while processing the split off page. So, +apart from positioning anchors in the text we need anchors on crucial points of +the layout. This means that this kind of support cannot be fully integrated into +the \TEX\ kernel, unless we also add extensive support for layout definitions, +and that is probably not what we want. + +As soon as something like $(x,y)$ shows up, a logical question is where $(0,0)$ +is located. Although this is a valid question, the answer is less important than +you may expect. Even if we know that ($0,0)$ is \quote {officially} located in +the bottom left corner of the page, the simple fact that in \CONTEXT\ we are +dealing with a mixed page concept, like paper size and print paper size, or left +and right pages, forces us to think in relative positions instead of absolute +ones. Therefore, graphics, even those that involve multiple positions, are +anchored to a position on the layer on which they are located. + +Users who simply want to use these features may wonder why we go into so much +detail. The main reason is that in the end many users will want to go beyond the +simple cases, and when dealing with these issues, you must be aware not only of +height, depth and width, but also of the crossing of a page boundary, and the +height and depth of lines. In some cases your graphics may have to respond to +layout characteristics, like differences between odd and even pages. Given that +unique identifiers are used for anchor points, in \CONTEXT\ you can have access +to all the information needed. Here are some of the helpers: + +\starttabulate[|T||] +\NC positionpath (tag) \NC the path determined by width, height and depth \NC \NR +\NC positionxy (tag) \NC the origin \NC \NR +\NC positionwhd (tag) \NC the dimensions (in a triplet) \NC \NR +\NC positionpage (tag) \NC the page number fo the position \NC \NR +\NC positionregion(tag) \NC the region that the position sits in \NC \NR +\NC positionbox (tag) \NC the positioned box (path shifted over coordinates) \NC \NR +\NC positionanchor \NC the current anchor of the region \NC \NR +\stoptabulate + +The \type {positionwhd} macro returns a triplet that you can query, like: + +\starttyping +triplet whd ; whd := positionwhd("\MPvar{from}"); +numeric wd; wd := wdpart whd ; +\stoptyping + +We will add more such convenient helpers in the future. In the \CONTEXT\ +distribution you can find examples (in manuals or librarties) that demonstrate +other tricks with positioning. + +\stopsection + +\startsection[title={Anchors and layers}] + +\index{anchoring} +\index{layers} + +\startbuffer[g-circle] +\startMPpositiongraphic{mypos:circle} + path p ; p := positionbox(texstr("self")) ; + p := fullcircle xsized (bbwidth(p)+4pt) shifted center p ; + pickup pencircle scaled 1pt ; + fill p withcolor .800white ; + draw p withcolor .625yellow ; + positioninregion ; +\stopMPpositiongraphic +\stopbuffer + +\startbuffer[g-line] +\startMPpositiongraphic{mypos:line} + path pa, pb, pab ; numeric na, nb ; string ta, tb ; + ta := texstr("from") ; + tb := texstr("to") ; + na := positionpage(ta) ; + nb := positionpage(tb) ; + pa := positionbox(ta) ; + pb := positionbox(tb) ; + pa := fullcircle xsized (bbwidth(pa)+4pt) shifted center pa ; + pb := fullcircle xsized (bbwidth(pb)+4pt) shifted center pb ; + if na = nb : + pab := center pa -- center pb ; + pab := pab cutbefore (pab intersectionpoint pa) ; + pab := pab cutafter (pab intersectionpoint pb) ; + pickup pencircle scaled 1pt ; + draw pab withcolor .625yellow ; + positioninregion ; + fi ; +\stopMPpositiongraphic +\stopbuffer + +\getbuffer[g-circle,g-line] + +\startbuffer[a] +\setMPpositiongraphic{X-1}{mypos:arrow}{to=X-2} +\setMPpositiongraphic{X-2}{mypos:arrow}{to=X-3} +\stopbuffer + +\startbuffer[b] +In a previous section we saw that some \hpos {X-1} {words} were +\hpos {X-2} {circled} and connected by an \hpos {X-3} {arrow}. +As with most things in \CONTEXT, marking these words is separated +from declaring what to do with those words. This paragraph is keyed +in as: +\stopbuffer + +\getbuffer[a,b] + +\typebuffer[b] + +We see three position anchors, each marked by an identifier: \type {X-1}, \type +{X-2} and \type {X-3}. Each of these anchors can be associated with a (series) of +graphic operations. Here we defined: + +\typebuffer[a] + +These examples clearly demonstrate that we cannot control to what extent graphics +will cover text and vice versa. A solution to this problem is using position +overlays. We can define such an overlay as follows: + +\startbuffer +\startpositionoverlay{backgraphics} + \setMPpositiongraphic{G-1}{mypos:circle} + \setMPpositiongraphic{G-2}{mypos:circle} + \setMPpositiongraphic{G-3}{mypos:circle} + \setMPpositiongraphic{G-4}{mypos:circle} +\stoppositionoverlay + +\startpositionoverlay{foregraphics} + \setMPpositiongraphic{G-1}{mypos:line}{to=G-2} + \setMPpositiongraphic{G-2}{mypos:line}{to=G-3} + \setMPpositiongraphic{G-3}{mypos:line}{to=G-4} +\stoppositionoverlay +\stopbuffer + +\getbuffer \typebuffer + +\startbuffer +First we have defined an \hpos {G-1} {\strut overlay}. This +overlay can be attached to some overlay layer, like, in our +case, the \hpos {G-2} {\strut page}. We define four small \hpos +{G-3} {\strut circles}. These are drawn as soon as the page +overlay is typeset. Because they are located in the +background, they don't cover the \hpos {G-4} {\strut text}, while +the lines do. The previous paragraph was typeset by saying: +\stopbuffer + +\getbuffer \typebuffer + +As said, the circles are on the background layer, but the lines are not! They are +positioned on top of the text. This is a direct result of the definition of the +page background: + +\starttyping +\defineoverlay [foregraphics] [\positionoverlay{foregraphics}] +\defineoverlay [backgraphics] [\positionoverlay{backgraphics}] + +\setupbackgrounds + [page] + [background={backgraphics,foreground,foregraphics}] +\stoptyping + +\doifmode{screen}{\writestatus{CHECK}{POSITION GRAPHICS}} + +In this definition, the predefined overlay \type {foreground} inserts the page +data itself, so the foreground graphics end up on top. This example also +demonstrates that you should be well aware of the way \CONTEXT\ builds a page. +There are six main layers, in some cases with sublayers. The body text goes into +the main text layer, which, unless forced otherwise, lays on top. + +\startitemize[packed,n,columns,three] +\item paper background +\item area backgrounds +\item page backgrounds +\item text areas +\item logo areas +\item main text +\stopitemize + +The paper background is used for special (sometimes internal) purposes. There are +three page backgrounds: left, right and both. The text areas, logo areas and +backgrounds form a $5 \times 5$ matrix with columns containing the leftedge, +leftmargin, text, rightmargin, and rightedge. The rows of the matrix contain the +top, header, text, footer, and bottom. The main text is what you are reading now. + +Since the page background is applied last, the previous layers can be considered +to be the foreground to the page background layer. And, indeed, it is available +as an overlay under the name \type {foreground}, as we already saw in the +example. Foregrounds are available in most cases, but (for the moment) not when +we are dealing with the text area. Since anchoring the graphics is implemented +rather independent of the position of the graphics themselves, this is no real +problem, we can put them all on the page layer, if needed in separate overlays. + +How is such a graphic defined? In fact these graphics are a special case of the +already present mechanism of including \METAPOST\ graphics. The circles are +defined as follows: + +\typebuffer[g-circle] + +Drawing the lines is handled in a similar fashion. + +\typebuffer[g-line] + +The command \tex {startMPpositiongraphic} defines a graphic, in this example we +have called it \type {mypos:circle}. Here we show the definition out of order but +normally you need to define it before you refer to it. + +The \METAPOST\ macro \type {positionbox} returns a box that is constructed from +the coordinates and dimensions. After this call, the corners are available via +\type {llcorner}, \type {lrcorner}, \type {urcorner} and \type {ulcorner}. The +center is accessible by \type {center}. When we are finished drawing the graphic, +we can anchor the result with \type {positioninregion}. This macro automatically +handles positioning on specific layers. The helper macros are not loaded by +default, you do that with: + +\typebuffer[g-include] + +The position macro \type {\MPpos} returns the current characteristics of a +position. The previously defined G~positions return: + +\starttabulate[|c|c|c|c|c|c|c|] +\HL +\NC position\NC page\NC$x$\NC$y$\NC width\NC height\NC depth\NC\NR +\HL +\NC G-1\NC\MPp{G-1}\NC\MPx{G-1}\NC\MPy{G-1}\NC\MPw{G-1}\NC\MPh{G-1}\NC\MPd{G-1}\NC\NR +\NC G-2\NC\MPp{G-2}\NC\MPx{G-2}\NC\MPy{G-2}\NC\MPw{G-2}\NC\MPh{G-2}\NC\MPd{G-2}\NC\NR +\NC G-3\NC\MPp{G-3}\NC\MPx{G-3}\NC\MPy{G-3}\NC\MPw{G-3}\NC\MPh{G-3}\NC\MPd{G-3}\NC\NR +\NC G-4\NC\MPp{G-4}\NC\MPx{G-4}\NC\MPy{G-4}\NC\MPw{G-4}\NC\MPh{G-4}\NC\MPd{G-4}\NC\NR +\HL +\stoptabulate + +The numbers represent the real pagenumber~$p$, the current position $(x,y)$, and +the dimensions of the box $(w,h,d)$ if known. These values are fed directly into +\METAPOST\ graphics but the individual components can be asked for by \type +{\MPp}, \type {\MPx}, \type {\MPy}, \type {\MPw}, \type {\MPh} and \type {\MPd}. + +In the previous definition of the graphic, we saw another macro, \type {\MPvar}. +When we invoke a graphic or attach a graphic to a layer, we can pass variables. +We can also set specific variables in other ways, as we will see later. + +\starttyping +\setMPpositiongraphic{G-1}{mypos:circle} +\setMPpositiongraphic{G-1}{mypos:line}{to=G-2} +\stoptyping + +In the second definition, we let the variable \type {to} point to another +position. When needed, we can ask for the value of \type {to} by \type +{\MPvar{to}}. For reasons of convenience, the current position is assigned +automatically to \type {from} and \type {self}. This means that in the line we +saw in the graphic: + +\starttyping +path p ; p := positionbox(texstr("self")) ; +\stoptyping + +\type {texstr("self")} will return the current position, which, fed to \type +{positionbox} will return a box with the right dimensions. We already warned the +reader: this is not an easy chapter. + +\stopsection + +\startsection[title={More layers}] + +\index{layers} + +\setupbackgrounds + [state=repeat] + +Overlays are one of the nicer features of \CONTEXT\ and even more nice things can +be build on top of them. Overlays are defined first and then assigned to framed +boxes using the \type {background} variable. + +You can stack overlays, which is why they are called as such. You can use the +special overlay called \type {foreground} to move the topmost (often text) layer +down in the stack. + +\starttabulate +\HL +\NC background overlay \NC a text, graphic, hyperlink or widget \NC \NR +\NC position overlay \NC a series of macros triggered by positions \NC \NR +\NC background layer \NC a box that can hold boxes with offsets \NC \NR +\HL +\stoptabulate + +The last kind of layer can be used in other situations as well, but in most cases +it will be hooked into a background overlay. + +\startbuffer +\definelayer[MyLayer][option=test] + +\setupbackgrounds[text][leftmargin][background=MyLayer] + +\setlayer[MyLayer][x=.5cm,y=5cm] + {\rotate{\framed{This goes to the background}}} +\stopbuffer + +\typebuffer \getbuffer \setuplayer[MyLayer][option=] % no frames + +In this case the framed text will be placed in the background of the (current) +page with the given offset to the topleft corner. Instead of a fixed position, +you can inherit the current position using the \type {position} directive. Say +that we have a layer called \type {YourLayer} which we put in the background of +the text area. + +\startbuffer +\definelayer[YourLayer] +\setupbackgrounds[text][text][background=YourLayer] +\stopbuffer + +\typebuffer \getbuffer + +We can now move some framed text to this layer using \type {\setlayer} with the +directive \type {position} set to \type {yes}. + +\startbuffer +here: \setlayer[YourLayer][position=yes]{\inframed{Here}} +\stopbuffer + +\typebuffer + +You can influence the placement by explicitly providing an offset (\type +{hoffset} and|/|or \type {voffset}), a position (\type {x} and|/|or \type {y}) or +a location directive (\type {location}). Normally you will use the offsets for +the layer as a whole and the positions for individual contributions. The next +example demonstrates the use of a location directive. + +\startbuffer +here: \setlayer[YourLayer][position=yes,location=c]{\inframed{Here}} +\stopbuffer + +\typebuffer \getbuffer + +Many layers can be in use at the same time. In the next example we put something +in the page layer. By default, we turn on position tracking, which visualizes the +bounding box of the content and shows the reference point. + +\startbuffer +\definelayer[BackLayer][position=yes] +\setupbackgrounds[page][background=BackLayer] +\stopbuffer + +\typebuffer \getbuffer + +\setupbackgrounds + [page] + [background={PageFrame,BackLayer,backgraphics,foreground,foregraphics}] + +Next we define an overlay that we can put behind for instance framed texts. We +use \METAPOST\ to draw \type {Shape}. + +\startbuffer +\defineoverlay[Shape] [BackLayer] [\uniqueMPgraphic{Shape}] + +\startuniqueMPgraphic{Shape} + path p ; p := fullcircle xyscaled(OverlayWidth,OverlayHeight) ; + fill p withcolor \MPcolor{lightgray} ; + draw p withpen pencircle scaled 1pt withcolor \MPcolor{darkred} ; +\stopuniqueMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer[def] +\defineframed[Shaped][background=Shape,frame=off,location=low] +\stopbuffer + +\getbuffer[def] + +We can now put this background shape behind the running text, for instance with: + +\startbuffer +.... some \inframed[background=Shape]{text} with a frame ... +.... some \Shaped{text} with a frame ... +\stopbuffer + +\typebuffer + +\startlines +\getbuffer +\stoplines + +The \type {\Shaped} macro was defined as: + +\typebuffer[def] + +Watch how the graphics are moved to the background while the frame of the first +text stays on top, since it remains part of the text flow. + +\startbuffer[def] +\setuplayer[BackLayer][direction=reverse] +\stopbuffer + +\getbuffer[def] + +\startlines +\getbuffer +\stoplines + +In the previous instance of the example we have reversed the stacking. Reversal +can be done with the \type {direction} directive. + +\typebuffer[def] + +% next series + +\startbuffer +\setuplayer + [BackLayer] + [position=no,corner=bottom,height=\paperheight] + +\setlayer[BackLayer][x=2cm,y=10cm,location=bl] + {\externalfigure[somecow.pdf][width=1cm]} + +\setlayer[BackLayer][x=1cm,y=8cm,location=br] + {\externalfigure[somecow.pdf][width=1cm]} + +\setlayer[BackLayer][x=2cm,y=4cm,location=tl] + {\externalfigure[somecow.pdf][width=1cm]} + +\setlayer[BackLayer][x=10cm,y=1cm,location=tr] + {\externalfigure[somecow.pdf][width=1cm]} +\stopbuffer + +You can influence the placement of a background component by using a different +anchor point. + +\typebuffer {\setuplayer[option=test]\getbuffer} + +\startbuffer[xx] +\setuplayer + [BackLayer] + [position=no,corner=bottom,height=\paperheight] + +\setlayer[BackLayer][x=15cm,y=5cm,location=bl] + {\externalfigure[somecow.pdf][width=3cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=br] + {\externalfigure[somecow.pdf][width=3cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=tl] + {\externalfigure[somecow.pdf][width=2cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=tr] + {\externalfigure[somecow.pdf][width=2cm]} + +\setlayer[BackLayer][x=15cm,y=5cm,location=c] + {\externalfigure[somecow.pdf][width=3cm]} +\stopbuffer + +% \startpostponing + +Instead of using relative positions, you can also use absolute ones. Of course +you need to know how your coordinates relate to the rest of the layout +definition. + +\typebuffer[xx] + +These examples again demonstrate how we can influence the placement by assigning +an anchor point to \type {position}. Here we also put the reference point in the +lower left corner (\type {bottom}). This mechanism only works when we also use +\type {height}. + +{\setuplayer[option=test]\getbuffer[xx]} + +\page + +% \stoppostponing + +\setupbackgrounds + [page] + [background={PageFrame,DemoLayer,backgraphics,foreground,foregraphics}] + +\definelayer + [DemoLayer] + [position=yes] + +\startbuffer +\definelayer + [DemoLayer] + [position=yes] + +\startplacefigure[title={Demo 1}] + \ruledhbox\bgroup + \setlayerframed + [DemoLayer] [hoffset=-10mm,voffset=5mm] + {\startMPcode + fill fullcircle scaled 2cm withcolor .625red ; + \stopMPcode}% + \setlayerframed + [DemoLayer] [voffset=-10mm] + {\startMPcode + fill fullcircle scaled 2cm withcolor .625green ; + \stopMPcode}% + \setlayerframed + [DemoLayer] [hoffset=10mm,voffset=5mm] + {\startMPcode + fill fullcircle scaled 2cm withcolor .625blue ; + \stopMPcode}% + \egroup +\stopplacefigure +\stopbuffer + +\getbuffer + +One of the reasons for developing the layer mechanism was that we needed to +slightly change the position of figures in the final stage of typesetting. The +previous pages demonstrate how one can position anything anywhere on the page, +but in the case of figures the position may depend on where the text ends up on +the page. + +Normally, when you manipulate a document this way, you are in the final stage of +typesetting. You may qualify this as desk top publishing without actually using a +desktop. + +\typebuffer + +\startbuffer[demo] +\startbuffer +\setlayer [DemoLayer] + [position=yes, + voffset=-1.5cm, + width=3cm, + height=2cm] + {\MPfigure{somecow.pdf}{scaled .5 slanted .5}} +\stopbuffer + +\placefigure[right]{}{\ruledhbox{\getbuffer}} +\stopbuffer + +{\setuplayer[option=test]\getbuffer[demo]} + +The previous example also demonstrated the use of \METAPOST\ for rotating the +picture. The \type {\MPfigure} macro encapsulates the code in a shortcut. You can +achieve special effects by using the layers behind floating bodies and alike, but +always keep in mind that the readability of the text should not be violated too +much. + +\typebuffer[demo] + +In these examples we added a \type {\ruledhbox} around the pseudo graphics so +that you can see what the size is of those graphics. + +% summary + +We have already seen a lot of parameters that can be used to control the content +of a layer. There are a few more. General housekeeping takes place with: + +\starttabulate[|Tl|Tl|l|] +\HL +\NC state \NC start \NC enable the layer \NC \NR +\NC \NC stop \NC disable the layer \NC \NR +\NC position \NC no \NC use absolute positions \NC \NR +\NC \NC yes \NC use relative positions \NC \NR +\NC \NC overlay \NC idem, but ignore the size \NC \NR +\NC direction \NC normal \NC put new data on top \NC \NR +\NC \NC reverse \NC put new data below old data \NC \NR +\HL +\stoptabulate + +Sometimes all data needs to be offset in a similar way. You can use both offset +parameters for that. + +\starttabulate[|Tl|l|] +\HL +\NC hoffset \NC an additional horizontal displacement \NC \NR +\NC voffset \NC an additional vertical displacement \NC \NR +\HL +\stoptabulate + +You can position data anywhere in the layer. When positioning is turned on, the +current position will get a placeholder. You can change the dimensions of that +placeholder (when \type {position} is set to \type {overlay}), zero dimensions +are used. + +\starttabulate[|Tl|l|] +\HL +\NC x \NC the horizontal displacement \NC \NR +\NC y \NC the vertical displacement \NC \NR +\NC width \NC the (non natural) width \NC \NR +\NC height \NC the (non natural) height \NC \NR +\NC location \NC \tttf l r t b c lt lb rt rb \NC \NR +\HL +\stoptabulate + +The \type {location} directive determines what point of the data is used as +reference point. You can keep track of this point and the placement when you +enable test mode. This is how the rectangles in the previous examples were +drawn. + +\starttabulate[|Tl|Tl|l|] +\HL +\NC option \NC test \NC show positioning information \NC \NR +\HL +\stoptabulate + +When you are enhancing the final version of a document, you can explicitly +specify on what page the data will go. Use this option with care. + +\starttabulate[|Tl|l|] +\HL +\NC page \NC the page where the data will go \NC \NR +\HL +\stoptabulate + +Because layers can migrate to other pages, they may disappear due to the +background not being recalculated. In case of doubt, you can force repetitive +background calculation by: + +\starttyping +\setupbackgrounds[state=repeat] +\stoptyping + +% restore 'm + +\setupbackgrounds + [page] + [background={PageFrame,backgraphics,foreground,foregraphics}] + +\setupbackgrounds + [state=start] + +\stopsection + +\startsection[title={Complex text in graphics}] + +\index{text} + +If you like to embed \METAPOST\ snippets in \CONTEXT, you may want to combine +text and graphics and let \METAPOST\ provide the position and the dimensions of +the text to be typeset outside by \TEX. For most applications using the \METAFUN\ +\type {textext} macro works well enough, but when the typeset text needs to +communicate with the typesetting engine, for instance because it contains +hyperlinks or references, you can use the following method: + +\startitemize[packed] +\item define a layer +\item define a (reusable) graphic +\item put your text into the layer +\item combine the graphic with the text +\stopitemize + +You must be aware of the fact that when the layer is flushed, its content is +gone. You can take advantage of this by using the same graphic with multiple +texts. + +\startbuffer +\definelayer[test] +\stopbuffer + +\typebuffer \getbuffer + +You don't need to pass the width and height explicitly, but when you do so, you +have access to them later. + +\startbuffer +\startuseMPgraphic{oeps} + path p ; p := fullcircle scaled 6cm ; + fill p withcolor .8white ; + draw p withpen pencircle scaled 1mm withcolor .625red ; + register ("somepos-1",0cm,0cm,center currentpicture) ; + register ("somepos-2",3cm,1cm,(-1cm,-1cm)) ; + register ("somepos-3",2cm,0cm,(-2cm,2cm)) ; +\stopuseMPgraphic +\stopbuffer + +\typebuffer \getbuffer + +The \METAFUN\ \type {register} macro takes the following arguments: + +\starttyping +register ("tag",width,height,(x offset,y offset)) ; +\stoptyping + +The width and height are available in the macros \type {\MPlayerwidth} and \type +{\MPlayerheight} and are equivalent to \type {\MPw{tag}} and \type {\MPh{tag}}, + +\startbuffer +\setMPlayer [test] [somepos-1] [location=c] + {Does it work al right?} + +\setMPlayer [test] [somepos-2] + {\framed + [width=\MPlayerwidth,height=\MPlayerheight, + background=color,backgroundcolor=white] + {It Works!}} + +\setMPlayer [test] [somepos-3] + {\externalfigure[cow-fun.mps][width=2cm]} +\stopbuffer + +\typebuffer \getbuffer + +Combining the graphic and the text is handled by the macro \type {\getMPlayer}. + +\startbuffer +\getMPlayer [test] {\useMPgraphic{oeps}} +\stopbuffer + +\typebuffer \getbuffer + +The macro \type {\getMPlayer} is built on top of \type {\framed}. The settings +passed in the (optional) second argument are the same as those to \type +{\framed}. + +\starttyping +\getMPlayer + [test] + [frame=on,offset=5pt] + {\useMPgraphic{oeps}} +\stoptyping + +As you see, you need a bit of a twisted mind to handle graphics this way, but at +least the functionality is there to create complex graphics in a declarative way. + +\stopsection + +\stopchapter + +\stopcomponent |