% language=us runpath=texruns:manuals/metafun \startcomponent metafun-gadgets \environment metafun-environment \startchapter[title={Shapes, symbols and buttons}] \startintro One can use \METAPOST\ to define symbols and enhance buttons. Here we introduce some of the gadgets that come with \CONTEXT, as well as explain how to integrate such gadgets yourself. \stopintro \startsection[title={Interfacing to \TEX}] \index {interfacing} \startbuffer[a] \setupMPvariables [EnglishRule] [height=1ex, width=\availablehsize, color=darkgray] \startuniqueMPgraphic{EnglishRule}{height,width,color} numeric height ; height = \MPvar{height} ; x1 = 0 ; x3 = \MPvar{width} ; x2 = x4 = .5x3 ; y1 = y3 = 0 ; y2 := -y4 = height/2 ; fill z1 .. z2 .. z3 & z3 .. z4 .. z1 & cycle withcolor \MPvar{color} ; \stopuniqueMPgraphic \stopbuffer \startbuffer[b] \defineblank [EnglishRule] [medium] \unexpanded\def\EnglishRule {\start \dontcomplain \startlinecorrection[EnglishRule] \noindent \reuseMPgraphic{EnglishRule} \stoplinecorrection \stop} \stopbuffer \getbuffer[a,b] In the early days of \METAPOST\ support in \CONTEXT, Tobias Burnus asked me if it was possible to define English rules. What exactly does an english rule look like? Here is one: \EnglishRule As you can see, such a rule has to adapt itself to the current text width, normally \type {\hsize} in \TEX, or on request \type {\availablehsize} in \CONTEXT. We need to set the height to a reasonable size, related to the font size, and we also need to take care of proper spacing. Of course we want to run \METAPOST\ as less times as possible, so we need to use unique graphics. Let's start with the graphic. \typebuffer[a] As you can see, we pass two arguments to the graphic definition. The first argument is the name, the second argument is a comma separated list of variables. This list serves two purposes. First this list is used to create a unique profile for the graphic. This means that when we change the value of a variable, a new graphic is generated that reflects the change. A second purpose of the list is to convert \TEX\ data structures into \METAPOST\ ones, especially dimensions and colors. The graphic itself is not that spectacular. We use \type {&} because we don't want smooth connections. \typebuffer[b] When setting the variables, we used \type {\availablehsize}. We need to use \type {\noindent}, a rather familiar \TEX\ primitive, that we use here to start a non indented paragraph, being the graphic. The line correction is needed to get the spacing around the rule (graphic) right. We pass a blank skip identifier that is mapped to a convenient medium skip. \startbuffer[c] Why is this called an English line? \startnarrower \EnglishRule Is it because they cannot draw a straight one? This could be true after a few strong beers, but then, how do Germans draw a line? \EnglishRule \stopnarrower \stopbuffer \typebuffer[c] As expected, the rule adapts itself to the current width of the text. The height of the rule in the middle matches the height of a character with no ascenders and descenders. \getbuffer[c] \stopsection \startsection[title={Random graphics}] \index{randomization} \startbuffer[a] \startuseMPgraphic{fuzzycount} begingroup save height, vstep, hsize, span, drift, d, cp ; height := 3/ 4 * \the \bodyfontsize * \currentfontscale ; span := 1/ 3 * height ; drift := 1/10 * height ; hsize := \the\hsize ; vstep := \the\lineheight ; xmax := hsize div 5span ; pickup pencircle scaled (1/12 * height) ; def d = (uniformdeviate drift) enddef ; for i := 1 upto \MPvar{n} : xpos := ((i-1) mod (5*xmax))*span ; ypos := ((i-1) div (5*xmax))*vstep ; draw if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d)) else : ((-d,+d)--(+d,height-d)) fi shifted (xpos,-ypos+d-drift) ; endfor; picture cp ; cp := currentpicture ; if (ypart ulcorner cp - ypart llcorner cp) <= vstep : setbounds currentpicture to (llcorner cp shifted (0,-ypart llcorner cp) -- lrcorner cp shifted (0,-ypart lrcorner cp) -- urcorner cp -- ulcorner cp -- cycle) ; fi endgroup ; \stopuseMPgraphic \stopbuffer \startbuffer[b] \useMPgraphic{fuzzycount}{n=1001} \stopbuffer Given enough time and paper, we can probably give you some \startlinecorrection[blank] \getbuffer[a,b] \stoplinecorrection reasons why \METAPOST\ is fun. To mention a few: you can enhance the layout with graphic ornaments, you can tune your graphics at runtime, and simple high quality graphics can be very effective. \startbuffer[c] \startuseMPgraphic{fuzzycount} begingroup save height, span, drift, d, cp ; height := 3/ 5 * \baselinedistance ; span := 1/ 3 * height ; drift := 1/10 * height ; pickup pencircle scaled (1/12 * height) ; def d = (uniformdeviate drift) enddef ; for i := 1 upto \MPvar{n} : draw if (i mod 5)=0 : ((-d-4.5span,d)--(+d-0.5span,height-d)) else : ((-d,+d)--(+d,height-d)) fi shifted (span*i,d-drift) ; endfor; picture cp ; cp := currentpicture ; % for readability setbounds currentpicture to (llcorner cp shifted (0,-ypart llcorner cp) -- lrcorner cp shifted (0,-ypart lrcorner cp) -- urcorner cp -- ulcorner cp -- cycle) ; endgroup ; \stopuseMPgraphic \stopbuffer \startbuffer[d] \setupMPvariables[fuzzycount][n=10] \stopbuffer \getbuffer[c,d] The previous graphics draws exactly 1001 lines in a scratch||numbers||in||a||wall fashion. In 1998, the \NTG\ did a survey among its members, and in the report, we used this fuzzy counter to enhance the rather dull tables. \startbuffer \starttabulate[|l|c|l|] \HL \NC system \NC \% \NC \# users \NC\NR \HL \NC Atari \NC 10.4 \NC \useMPgraphic{fuzzycount}{n=11} \NC\NR \NC MSDOS \NC 49.1 \NC \useMPgraphic{fuzzycount}{n=52} \NC\NR \NC OS/2 \NC ~9.4 \NC \useMPgraphic{fuzzycount}{n=10} \NC\NR \NC MacOS \NC ~5.7 \NC \useMPgraphic{fuzzycount}{n= 6} \NC\NR \NC UNIX \NC 51.9 \NC \useMPgraphic{fuzzycount}{n=55} \NC\NR \NC WINDOWS \NC 64.2 \NC \useMPgraphic{fuzzycount}{n=68} \NC\NR \HL \stoptabulate \stopbuffer \placetable [here][tab:fuzzy] {Operating system (n=106).}{\getbuffer} \in {Table} [tab:fuzzy] demonstrates how scratch numbers can be used. An interesting side effect is that when you look long enough to these kind of graphics, it looks like the lines are no longer horizontal. This table is defined as follows: \typebuffer You will notice that we pass a variable to the graphic using a second argument. We can access this variable with \type {\MPvar}. The graphic is defined as usable graphic, because we want to generate a unique random one each time. \typebuffer[c] The core of the macro is the \type {for} loop. Within this loop, we draw groups of four plus one lines. The draw path's look a bit complicated, but this has to do with the fact that a \type {mod} returns $0-4$ while we like to deal with $1-5$. The height adapts itself to the height of the line. The bounding box correction at the end ensures that the baseline is consistent and that the random vertical offsets fall below the baseline. Because we want to be sure that \type {n} has a value, we preset it by saying: \typebuffer[d] In the table, it makes sense to adapt the drawing to the lineheight, but a more general solution is to adapt the height to the fontsize. \starttyping height := 3/ 4 * \the \bodyfontsize * \currentfontscale ; \stoptyping \getbuffer[a] In the table we called the graphic directly, but how about making it available as a conversion macro? In \CONTEXT\ this is not that hard: \startbuffer \def\fuzzycount#1{{\tx\useMPgraphic{fuzzycount}{n=#1}}} \defineconversion[fuzzy][\fuzzycount] \stopbuffer \typebuffer \getbuffer Because such a counter should not be that large, we use \type {\tx} to switch to a smaller font. This also demonstrates how the graphic adapts itself to the font size. We can now use this conversion for instance in an itemize. To save space we use three columns and no white space between the lines. The \type {2*broad} directive makes sure that we have enough room for the number. \startbuffer \startitemize[fuzzy,pack,2*broad,columns,three] \item one \item two \item three \item four \item five \item six \item seven \item eight \item nine \stopitemize \stopbuffer \getbuffer \typebuffer A careful reader will have noticed that the previous definition of the fuzzy counter drawing is not suited to generate the graphics we started with. \typebuffer[b] This time we want to limit the width to the current \type {\hsize}. We only need to add a few lines of code. Watch how we don't recalculate the bounding box when more lines are used. \typebuffer[a] \stopsection \startsection[title={Graphic variables}] \index{graphics+variables} \index{variables} In the previous sections we have seen that we can pass information to the graphic by means of variables. How exactly does this mechanism work? \startbuffer[def] \setupMPvariables[smile][type=1,height=1.25ex,color=darkred] \startuniqueMPgraphic{smile}{type,height,color} numeric size ; size := \MPvar{height} ; drawoptions(withcolor \MPvar{color}) ; pickup pencircle xscaled (size/6) yscaled (size/12) ; draw halfcircle rotated -90 scaled size ; pickup pencircle scaled (size/4) ; if \MPvar{type}=1 : for i=-1,+1 : draw origin shifted (0,i*size/4) ; endfor ; elseif \MPvar{type}=2 : for i=-1,+1 : draw origin shifted (-size/2,i*size/4) ; endfor ; pickup pencircle scaled (size/6) ; draw (size/4,0) -- (-size/4,0) ; fi ; \stopuniqueMPgraphic \stopbuffer \startbuffer[sym] \definesymbol[smile] [\uniqueMPgraphic{smile}{type=1}] \definesymbol[smilemore][\uniqueMPgraphic{smile}{type=2}] \stopbuffer \startbuffer[exa] Say it with a \symbol [smile]\ or maybe even a \symbol [smilemore], although seeing too many \dorecurse {10} {\symbol [smile]\ } \unskip in one text may make you cry. \stopbuffer \getbuffer[def,sym] A nice application of setting up variables for a specific graphic (or class of graphics) is the following. In an email message the author can express his own or the readers expected emotions with so called smilies like: \symbol [smile]. If you want them in print, you can revert to combinations of characters in a font, but as a \TEX\ user you may want to include nicer graphics. A convenient way to implement these is to make them into symbols, one reason being that in that case they will adapt themselves to the current font size. \typebuffer[exa] \getbuffer[exa] Because we want an efficient implementation, we will use unique graphics, because these will only be generated when the circumstances change. \typebuffer[sym] The definition itself then becomes: \typebuffer[def] We can now change some characteristics of the smilies without the need to redefine the graphic. \startbuffer[set] \setupMPvariables[smile][height=1ex,color=darkred] \stopbuffer \typebuffer[set] \getbuffer[set,exa] In order to keep the smilies unique there is some magic involved, watch the second argument in the next line: \starttyping \startuniqueMPgraphic{smile}{type,height,color} % the image \stopuniqueMPgraphic \stoptyping Because unique graphics often are used in backgrounds, its uniqueness is determined by the overlay characteristics. In our case however the uniqueness is determined by the smilies type, height and color. By explicitly specifying these, we make sure that they count in the creation of the uniqueness stamp. \startbuffer[exa] \midaligned{\switchtobodyfont[60pt]\symbol[smile]} \stopbuffer \typebuffer[exa] Because we use the ex||height, the previous call works as expected. \startlinecorrection[blank] \getbuffer[exa] \stoplinecorrection \stopsection \startsection[title={Shape libraries}] \index{graphics+libraries} Unfortunately it takes some effort to define graphics, attach them to an overlay, and invoke the background. However, the good news is that since in many cases we want a consistent layout, we only have to do it once. The next table has some hashed backgrounds. (More information about how to define tables can be found in the \CONTEXT\ documentation and Up||To||Date documents.) \startbuffer \bTABLE[frame=off,meta:hash:linecolor=darkyellow,offset=3ex] \bTR \bTD[background=meta:hash:right] right \eTD \bTD[background=meta:hash:left] left \eTD \bTD[background=meta:hash:horizontal] horizontal \eTD \bTD[background=meta:hash:vertical] vertical \eTD \eTR \eTABLE \stopbuffer \getbuffer[shape-a,shape-b,shape-c] \placetable {A hashed table.} {\getbuffer} This table is defined as: \typebuffer The graphics themselves are defined in a \METAPOST\ module. In this particular example, the macro \type {some_hash} is defined in the file \type {mp-back.mp}. This macro takes six arguments: \starttyping some_hash (width, height, linewidth, linecolor, angle, gap) ; \stoptyping Because we don't want to define a specific overlay for each color and linewidth, we will use variables in the definition of the unique graphic. \typebuffer[shape-a] These variables are preset using \type {\setupMPvariables}: \typebuffer[shape-b] The last step in this process is to define the different alternatives as overlays: \typebuffer[shape-c] As we can see in the definition of the table, we can pass settings to the \type {\bTABLE} command. Actually, we can pass such settings to each command that supports backgrounds, or more precisely \type {\framed}. \in {Table} [tab:hashes] is for instance defined as: \startbuffer \bTABLE[frame=off,meta:hash:linewidth=.4pt,align=middle,offset=2ex] \bTR \bTD[background={meta:hash:left,meta:hash:right}, meta:hash:linecolor=darkyellow] left \par \& \par right \eTD \bTD[background={meta:hash:horizontal,meta:hash:vertical}, meta:hash:linecolor=darkred] horizontal \par \& \par vertical \eTD \eTR \eTABLE \stopbuffer \typebuffer The long names are somewhat cumbersome, but in that way we can prevent name clashes. Also, since the \METAPOST\ interface is english, the variables are also english. \placetable [here][tab:hashes] {A double hashed table.} {\getbuffer} \stopsection \startsection[title={Symbol collections}] \index{graphics+symbols} \index{symbols} In \CONTEXT, a symbol can be defined without much coding. The advantage of using symbols is that you can redefine them depending on the situation. So, \starttyping \definesymbol [yes] [\em Yes!] \stoptyping creates a symbol, that lets \type {\symbol[yes]} expand into {\em Yes!} Since nearly anything can be a symbol, we can also say: \starttyping \definesymbol [yes] [\mathematics{\star}] \stoptyping or even the already defined symbol \symbol[star], by saying: \starttyping \definesymbol [yes] [{\symbol[star]}] \stoptyping It may be clear that we can use a graphic as well: \typebuffer[symb-c] Since we have collected some nice buttons in a \METAPOST\ file already, we can use a rather simple definition: \typebuffer[symb-a] This leaves a few settings: \typebuffer[symb-b] These symbols are collected in \in {table} [tab:symbols], and are called up with the \CONTEXT\ commands like \type {\symbol[menu:left]}. If needed, we can collect these button symbols in a so called symbol set, which permits us to instantly switch between sets with similar symbols. \startbuffer \bTABLE[frame=off,width=36pt,align=middle] \bTR \bTD \dontleavehmode \symbol[menu:left] \eTD \bTD \dontleavehmode \symbol[menu:right] \eTD \bTD \dontleavehmode \symbol[menu:list] \eTD \bTD \dontleavehmode \symbol[menu:index] \eTD \bTD \dontleavehmode \symbol[menu:person] \eTD \bTD \dontleavehmode \symbol[menu:stop] \eTD \bTD \dontleavehmode \symbol[menu:info] \eTD \bTD \dontleavehmode \symbol[menu:down] \eTD \bTD \dontleavehmode \symbol[menu:up] \eTD \bTD \dontleavehmode \symbol[menu:print] \eTD \eTR \bTR \bTD left \eTD \bTD right \eTD \bTD list \eTD \bTD index \eTD \bTD person \eTD \bTD stop \eTD \bTD info \eTD \bTD down \eTD \bTD up \eTD \bTD print \eTD \eTR \eTABLE \stopbuffer \getbuffer[symb-a,symb-b,symb-c] \placetable [here][tab:symbols] {A collection of button symbols.} {\getbuffer} \stopsection \stopchapter \stopcomponent