% output=pdftex engine=pdftex language=uk
%
% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa

\startcomponent mfun-008

\environment mfun-000

\chapter [sec:positioning] {Positional graphics}

\startintro

In this chapter, we will explore some 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.

\stopintro

\section {The concept}

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, we have to deal with this
asynchronous feature of \TEX\ in a rather advanced way.
Before we present one way of dealing with this complexity,
we will elaborate on the nature of such graphics.

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. To accomplish this several options are open:

\startitemize[packed,n]
\item  Use a backend that acts on the typeset text. This is
       the traditional way, using specials to embed
       directives in the \DVI\ output file.
\item  Use the power of a second language and pass snippets
       of code to the backend which takes care of proper
       handling of those snippets of text. Impressive results
       are booked by passing \POSTSCRIPT\ to the \DVI\ file.
\item  Extend \TEX\ in such a way that \TEX\ itself takes
       care of these issues. This is the way \PDFTEX\ works.
\stopitemize

The first method is rather limited, although for business
graphics the results are acceptable. The second method is
very powerful but hardly portable, since it depends on the
\DVI\ to \POSTSCRIPT\ postprocessor. But what about the
third method?

There has been some reluctance to divert from traditional
\TEX\ and \DVI, but with the development of \PDFTEX, the
third option becomes a viable option. Much of what I will
discuss here can be realized in \DVI, using a dedicated
postprocessor to extract the information needed. Although we
believe that the \PDFTEX\ way is the natural way to go,
\CONTEXT\ also supports the same mechanism in \DVI.

\setMPpositiongraphic{A-1}{mypos:arrow}{to=A-2}

As said, 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.

\setupMPvariables[mpos:box][linecolor=darkred]
\setupMPvariables[mpos:par][linecolor=darkred]

\startpositionoverlay{backgraphics}
  \setMPpositiongraphic{A-3}{mpos:box}{self=A-3}
  \setMPpositiongraphic{A-4}{mpos:box}{self=A-4}
  \setMPpositiongraphic{b:A-5}{mpos:par}{self=A-5}
  \setMPpositiongraphic{b:A-6}{mpos:par}{self=A-6}
\stoppositionoverlay

In the previous paragraph \hpos {A-3} {word} and \hpos {A-4}
{globs} are 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. \fpos {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. \tpos {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 \fpos {A-6} or, as in this paragraph, backgrounds
that depend on the typeset text. \tpos {A-6}

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 the background example, we store the current
height and depth of the strut (an imaginary character
{\showstruts \strut} with maximum height and depth but no
width) along with the current text width.

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

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 $(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. The \type {\MPanchor} macro takes care of
this.

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.

\section {Anchors and layers}

\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 vise 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} {overlay}. This
overlay can be attached to some overlay layer, like, in our
case, the \hpos {G-2} {page}. We define four small \hpos
{G-3} {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} {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 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 \type {\startMPpositiongraphic} defines a
graphic, in this example we have called it \type
{mypos:circle}.

The \METAPOST\ macro \type {initialize_box} returns the
characteristics of the box as identified by \type {\MPpos}.
After this call, the corners are available in \type {llxy},
\type {lrxy}, \type {urxy} and \type {ulxy}. The center is
defined by \type {cxy} and the path stored in \type {pxy}.
When we are finished drawing the graphic, we can anchor the
result with \type {anchor_box}. This macro automatically
handles positioning on specific layers.

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 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
initialize_box(\MPpos{\MPvar{self}}) ;
\stoptyping

\type {\MPvar{self}} will return the current position,
which, fed to \type {\MPpos} will return the list of
positional numbers. We already warned the reader: this is not
an easy chapter.

\section {More 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 \getbuffer

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=11cm,y=6cm,location=bl]
  {\externalfigure[somecow.pdf][width=5cm]}

\setlayer[BackLayer][x=12cm,y=5cm,location=br]
  {\externalfigure[somecow.pdf][width=5cm]}

\setlayer[BackLayer][x= 8cm,y=8cm,location=tl]
  {\externalfigure[somecow.pdf][width=3cm]}

\setlayer[BackLayer][x= 9cm,y=7cm,location=tr]
  {\externalfigure[somecow.pdf][width=4cm]}
\stopbuffer

You can influence the placement of a background component by
using a different anchor point.

\typebuffer {\tracelayerstrue\getbuffer}

\startbuffer[xx]
\setuplayer
  [BackLayer]
  [position=no,corner=bottom,height=\paperheight]

\setlayer[BackLayer][x=8cm,y=7cm,location=bl]
  {\externalfigure[somecow.pdf][width=5cm]}

\setlayer[BackLayer][x=8cm,y=7cm,location=br]
  {\externalfigure[somecow.pdf][width=5cm]}

\setlayer[BackLayer][x=8cm,y=7cm,location=tl]
  {\externalfigure[somecow.pdf][width=3cm]}

\setlayer[BackLayer][x=8cm,y=7cm,location=tr]
  {\externalfigure[somecow.pdf][width=4cm]}

\setlayer[BackLayer][x=8cm,y=7cm,location=c]
  {\externalfigure[somecow.pdf][width=5cm]}
\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
\type {height}.

{\tracelayerstrue\getbuffer[xx]}

\page

\stoppostponing

\startbuffer
\startbuffer
\setlayer [BackLayer]
  [position=yes,location=c,voffset=-.5cm,width=50pt,height=50pt]
  {\startMPcode
     externalfigure "somecow.pdf"
       xscaled 100bp yscaled 100bp rotated 25 ;
   \stopMPcode}
\stopbuffer

\placefigure[left]{}{\getbuffer}
\stopbuffer

% the \getbuffer cannot be unattached, since else the side
% float will interfere with the intermediate content

\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
\startbuffer
\setlayer [BackLayer]
  [position=yes,voffset=-1.5cm,width=3cm,height=2cm]
  {\MPfigure{somecow.pdf}{scaled .5 slanted .5}}
\stopbuffer

\placefigure[right]{}{\getbuffer}
\stopbuffer

{\tracelayerstrue\getbuffer}

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

% 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 where 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. \footnote {Soon, this feature will be
hooked into the named pages handler.}

\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: \footnote{This will be default behaviour
when computers become faster.}

\starttyping
\setupbackgrounds[state=repeat]
\stoptyping

% restore 'm

\setupbackgrounds
  [page]
  [background={PageFrame,backgraphics,foreground,foregraphics}]

\setupbackgrounds
  [state=start]

\section {Complex text in graphics}

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 the \METAPOST\ run. 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.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 twisted mind to handle graphics
this way, but at least the functionality is there to create
complex graphics in a declarative way.

% \section {Some examples}
%
% {\em In due time, there will a few more examples here. For
% that, the interface has to be more frozen than it currently
% is.}

\stopcomponent
