diff options
Diffstat (limited to 'doc/context/sources/general/manuals/metafun/metafun-gadgets.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/metafun/metafun-gadgets.tex | 548 |
1 files changed, 548 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/metafun/metafun-gadgets.tex b/doc/context/sources/general/manuals/metafun/metafun-gadgets.tex new file mode 100644 index 000000000..9010fc403 --- /dev/null +++ b/doc/context/sources/general/manuals/metafun/metafun-gadgets.tex @@ -0,0 +1,548 @@ +% language=uk +% +% copyright=pragma-ade readme=readme.pdf licence=cc-by-nc-sa + +\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} +\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 |