diff options
Diffstat (limited to 'Master/texmf-dist/doc/context/sources/general/manuals/interaction')
21 files changed, 2584 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-actions.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-actions.tex new file mode 100644 index 00000000000..a5caf2c0bdf --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-actions.tex @@ -0,0 +1,204 @@ +% language=uk + +\environment interaction-style + +\usemodule[references-identify] + +\startcomponent interaction-actions + +\startchapter[title=Actions] + +The reference mechanism not only deals with the more traditional cross +references, but also takes care of navigation, launching applications (although +that is often limited by viewers), running \JAVASCRIPT, etc. By integrating these +features in one mechanism, we limit the number of commands needed for hyperlinks, +menus and buttons. Normally such actions are driven by the \type {\goto} command, +but you can also use buttons: + +\starttyping +\goto[inner reference] +\goto[outer reference::] +\goto[outer reference::inner reference] +\stoptyping + +The inner reference is normally a user defined one, for instance a reference to a +named location like a chapter or figure. The outer reference refers to a file or +\URL and is normally defined at the document level and is accessed by the \type +{::}. By using symbolic names updating them becomes easier. + +There are also predefined references, like \type {nextpage} to go to the next +page or \type {forward} to cycle, \type {nextcontents} for the next level table +of contents in a linked list of such tables, etc. Some keywords are actually +shortcuts to actions that are delegated to the viewer. Here you need to keep in +mind that nowadays we're talking of \PDF\ viewers, but originally (\MKII) we also +supported \DVI\ viewers. A special class of references are the viewer control +ones, like \type {CloseDocument} or \type {PreviousJump}. They can be recognized +by their capitals. + +When we speak of a reference, we actually refer to a whole bunch of possible +references. We already mentioned inner and outer references, but special actions +are also possible. These are actually plugins. Examples are the \JAVASCRIPT\ and +\URL\ plugins. The interface evolved a bit over a few decades but most has been +there right from the start, which is why we keep it as is. Actually, there is not +that much new functionality added in \MKIV, although the implementation was +mostly rewritten. Here is a overview of the syntax, just to give you an idea. + +\starttyping +\goto[inner] +\goto[inner(foo,bar)] +\goto[inner{argument,argument}] +\goto[inner{argument}] +\goto[outer::] +\goto[outer::inner] +\goto[outer::special(operation{argument,argument})] +\goto[outer::special(operation)] +\goto[outer::special()] +\goto[outer::inner{argument}] +\goto[special(operation{argument})] +\goto[special(operation{argument,argument})] +\goto[special(operation)] +\goto[special(outer::operation)] +\goto[special(operation)] +\goto[special(operation(whatever))] +\goto[special(operation{argument,argument{whatever}})] +\goto[special(operation{argument{whatever}})] +\stoptyping + +There can be multiple actions, separated by a comma, think of: go to the page +with label \quote {foo} and start video \quote {bar}. + +\showsetup{goto} + +Examples of operations are \type {page}, \type {program}, \type {action}, \type +{url} and \type {JS}. \footnote {There are a few more operations but not all make +sense at the user level.} The \type {page} operation accepts a pagenumber as +well as relevant keywords. One can prefix a pagenumber by a file or \URL\ tag. +The \type {program} operation starts up a program. It is an example of an old +feature that has proven to be unstable, simply because viewers change behaviour +over time. + +\showsetup{definereference} + +The built|-|in actions are interfaces via shortcuts with camelcase names. In most +cases the name is a good indication of what to expect: + +\starttyping +\definereference [CloseDocument] [action(close)] +\definereference [ExitViewer] [action(exit)] +\definereference [FirstPage] [action(first)] +\definereference [LastPage] [action(last)] +\definereference [NextJump] [action(forward)] +\definereference [NextPage] [action(next)] +\definereference [PauseMovie] [action(pausemovie)] +\definereference [PauseSound] [action(pausesound)] +\definereference [PauseRendering] [action(pauserendering)] +\definereference [PreviousJump] [action(backward)] +\definereference [PreviousPage] [action(previous)] +\definereference [PrintDocument] [action(print)] +\definereference [SaveForm] [action(exportform)] +\definereference [LoadForm] [action(importform)] +\definereference [ResetForm] [action(resetform)] +\definereference [ResumeMovie] [action(resumemovie)] +\definereference [ResumeSound] [action(resumesound)] +\definereference [ResumeRendering] [action(resumerendering)] +\definereference [SaveDocument] [action(save)] +\definereference [SaveNamedDocument][action(savenamed)] +\definereference [OpenNamedDocument][action(opennamed)] +\definereference [SearchDocument] [action(search)] +\definereference [SearchAgain] [action(searchagain)] +\definereference [StartMovie] [action(startmovie)] +\definereference [StartSound] [action(startsound)] +\definereference [StartRendering] [action(startrendering)] +\definereference [StopMovie] [action(stopmovie)] +\definereference [StopSound] [action(stopsound)] +\definereference [StopRendering] [action(stoprendering)] +\definereference [SubmitForm] [action(submitform)] +\definereference [ToggleViewer] [action(toggle)] +\definereference [ViewerHelp] [action(help)] +\definereference [HideField] [action(hide)] +\definereference [ShowField] [action(show)] +\definereference [GotoPage] [action(gotopage)] +\definereference [Query] [action(query)] +\definereference [QueryAgain] [action(queryagain)] +\definereference [FitWidth] [action(fitwidth)] +\definereference [FitHeight] [action(fitheight)] +\definereference [ShowThumbs] [action(thumbnails)] +\definereference [ShowBookmarks] [action(bookmarks)] +\definereference [HideLayer] [action(hidelayer)] +\definereference [VideLayer] [action(videlayer)] +\definereference [ToggleLayer] [action(togglelayer)] +\stoptyping + +In the \type {java-imp-*.mkiv} files you will find examples of similar shortcuts, +for instance: + +\starttyping +\definereference [SetupStepper] [JS(SetupStepper{step,50})] +\definereference [ResetStepper] [JS(ResetStepper)] +\definereference [CheckStepper] [JS(CheckStepper{\StepCounter})] +\definereference [InvokeStepper] [JS(InvokeStepper)] +\stoptyping + +Other examples of redefined references are: + +\starttyping +\definereference [firstpage] [page(firstpage)] +\definereference [previouspage] [page(previouspage)] +\definereference [nextpage] [page(nextpage)] +\definereference [lastpage] [page(lastpage)] +\definereference [forward] [page(forward)] +\definereference [backward] [page(backward)] +\definereference [firstsubpage] [page(firstsubpage)] +\definereference [previoussubpage] [page(previoussubpage)] +\definereference [nextsubpage] [page(nextsubpage)] +\definereference [lastsubpage] [page(lastsubpage)] +\stoptyping + +Some of these actions expect arguments, for instance: + +\starttyping +\goto{start}[StartMovie{mymovie}] +\stoptyping + +You can load the module \type {references-identify} which gives you +a command: + +\startbuffer +\showreference[page(123),StartMovie{mymovie}] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\showreference[JS(Forget_Changes),CloseDocument] +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\showreference[manual::contents] +\stopbuffer + +\typebuffer \getbuffer + +You should be careful with colons in references. This gives you an idea how +\CONTEXT\ interprets what you requested. + +\starttabulate[|T|p|] +\NC prefix:whatever \NC The \type {prefix} creates a namespace. When references are + resolved and there is no hit a lookup without prefix + takes place. \NC \NR +\NC document::whatever \NC The \type {document} is a symbolic reference to an external + resource. This is explained elsewhere. \NC \NR +\NC component:::whatever \NC The \type {component} is a symbolic reference to a component in + a product. References defined in such a component are loaded on + demand. \NC \NR +\stoptabulate + +% url(http://a,b.c) +% url(http://a,b.c) +% url(http://a.b.c) + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-annotations.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-annotations.tex new file mode 100644 index 00000000000..e61a0953d3d --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-annotations.tex @@ -0,0 +1,106 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-annotations + +\startchapter[title=Annotations] + +Before we discuss interactive features (in following chapter) a few words will be +spent on so called annotations. This term is used in Acrobat and is somewhat +confusing as hyperlinks conceptually are not really annotations while comments +are. The term relates to the way \PDF\ files can have added functionality. It +might help understand the following chapters better when you know what model is +used inside a \PDF. + +If you open a \PDF\ file in an editor you will finds lots of objects. Numbers are +an object, as are strings and booleans. Symbols (represented as strings with a +leading slash) are also objects. Objects can be collected in indexed tables +(arrays) and hash tables (dictionaries). Serialized arrays are bounded by square +brackets: + +\starttyping +[ (value1) (value2) ] +[ 1 2 3 ] +[ 1 2 (value1) (value3) true /foo ] +\stoptyping + +and hashes by double angle brackets: + +\starttyping +<< + /Key1 (value1) + /Key2 (value2) + /Key3 123 + /Key4 true + /Key5 [ 1 2 3 4 ] +>> +\stoptyping + +A \PDF\ file is a collection of objects: + +\starttyping +1 0 obj + ... +endobj +\stoptyping + +Instead of a number, string, boolean, array or dictionary an object can also be +a stream of bytes: + +\starttyping +1 0 obj << /Length 123 >> +stream +... 123 bytes ... +endstream +endobj +\stoptyping + +Objects can refer to each other and can be looked up via a so called xref table. +We refer to object with number one and revision zero as follows: + +\starttyping +/foo 1 0 R +\stoptyping + +When an object is updated it can be added to the end of the file and the version +number can get bumped. A program that does something with the \PDF\ is supposed +to do something clever with these numbers. More often the revision stays zero. + +A document is normally a sequence of pages. When a file is opened the cross +reference table is loaded and the so called catalog is looked up. From there +pages can be found. Pages have a content stream and can refer to resources, like +fonts, special color spaces, complex objects (xforms) and among other things +annotations. + +The page is rendered from the content stream but that stream has no information +about hyperlinks and such. The \type {/Link} annotation objects that implement +interactivity are independent and kind of layered over the rendered page. They +describe rectangular areas that a viewer can use to intercept mouse clicks. If +you want to see where the actions happens, search for \type {/Dest} and \type +{/Annot} in an (uncompressed) \PDF file. When you process a file with + +\starttyping +\nopdfcompression +\stoptyping + +you get an uncompressed file and with an appropriate editor you can see where +annotations end up. + +The main reason for mentioning these details is that when you are checking a file +for problems you need to look for annotation objects instead of the page stream. +You also need to realize that these annotations in no way interfere with the page +stream. They only exist because a viewer can use that information to add +functionality. Their reference point is the lower left corner of the page. This +is a conceptual difference with \HTML\ where hyperlinks are often in|-|line and +part of the content stream. Both approaches have their advantages and +disadvantages. From the perspective of quality typesetting it makes much sense to +have them overlayed and explicitly defined (in terms of dimensions) but users +will of course in most cases define them inline. This means that in order to make +the \PDF\ some analyzing and juggling has to take place. In \CONTEXT\ we always +have done as much as possible at the \TEX\ (therefore bypassing some limitations +in the engine) end in \MKIV\ we don't use the engine's features at all. + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-attachments.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-attachments.tex new file mode 100644 index 00000000000..6ae9b63103c --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-attachments.tex @@ -0,0 +1,174 @@ +% language=uk + +% Written while intermittently watching those always positive "Walk off the Earth" +% videos to keep me in the mood. They make what's normally not my kind of music +% into something very interesting. I hope that this chapter is kind of interesting +% in the end too. + +\environment interaction-style + +\enabletrackers[attachments.anchors] + +\setupattachment + [location=inmargin] + +\startcomponent interaction-attachments + +\startchapter[title=Attachments] + +Attachments are (normally) embedded files that the reader can extract. A viewer +can decide to just show the content or call an associated program to deal with +the file (which one depends on the operating system). As with other annotations +they started out depicted by symbols but then browsers started showing them in +lists next to the displayed page. + +\startbuffer +\attachment + [attachment 1] + [file=interaction-attached-001.txt, + title=Just some text, + width=2em, + height=2em, + author=Hans, + subtitle=Plain text] + +\attachment + [attachment 2] + [file=cow.mp, + title=Just a graphic, + author=Hans, + subtitle=Some MetaPost, + method=hidden] +\stopbuffer + +\typebuffer \getbuffer + +These two attachments differ in one aspect: the second one is hidden, i.e. it has +no icon in the text. However, the attachment is in the file and is (often) +visible in the side bar. The symbol for the visible one is in the margin, which +is achieved with: + +\starttyping +\setupattachment + [location=inmargin] +\stoptyping + +You can use your own icon, for instance: + +\startbuffer +\startuniqueMPgraphic{cow}{height,s:color} + loadfigure "cow.mp" number 1 ; + refill currentpicture withcolor "\MPvar{color}" ; + currentpicture := currentpicture ysized \MPvar{height} ; +\stopuniqueMPgraphic + +\definesymbol + [attachment-normal] + [\uniqueMPgraphic{cow}{height=4ex,color=darkblue}] +\definesymbol + [attachment-down] + [\uniqueMPgraphic{cow}{height=4ex,color=darkyellow}] +\stopbuffer + +\typebuffer \getbuffer + +% \startattachment[hello][symbol={attachment-normal,attachment-down}] +% oeps +% \stopattachment + +\attachment + [symbol={attachment-normal,attachment-down}, + file=cow.pdf, + title=A cow, + author=Hans, + subtitle=graphic] + +This time we get a cow as icon and the cow is also embedded as image. When +writing this manual a click in Sumatra just opens the \PDF\ file, but when I +embed an mp3 file, a save-as window pops up. + +The previous examples directly injected the attachment using the \type +{\attachment} commands with the appropriate arguments. You can add titles, define +a name that will be used when the attachment is saved: + +\starttyping +\attachment[sometag][extra specs] +\attachment[test.tex] +\attachment[file=test.tex] +\attachment[file=test.tex,method=hidden] +\attachment[name=newname,file=test.tex] +\attachment[title=mytitle,name=newname,file=test.tex] +\stoptyping + +but there's also a more indirect way, for instance here we define some +attachments: + +\starttyping +\defineattachment[whatever-1][file=test.tex] +\defineattachment[whatever-2][file=test.tex,method=hidden] +\stoptyping + +that later can be called up with: + +\starttyping +\attachment[whatever-1][method=hidden] +\attachment[whatever-2] +\stoptyping + +where of course hidden is to be omitted when you want an icon. The commands that +are used to define and tune an instance are: + +\showsetup{defineattachment} + +\showsetup{setupattachment} + +There is one predefined instance: + +\starttyping +\defineattachment[attachment] +\stoptyping + +So we have: + +\showsetup{startattachment:instance} + +\showsetup{attachment:instance} + +Yet another level of abstraction can be achieved with: + +\showsetup{registerattachment} + +For example: + +\starttyping +\registerattachment + [sometag] + [name=fool.txt, + file=foo.txt, + title=Fool me, + subtitle=Not you, + author= Joker] +\stoptyping + +This is the \MKIV\ replacement for the \MKII\ method: + +\starttyping +\useattachment[test.tex] +\useattachment[whatever][test.tex] +\useattachment[whatever][newname][test.tex] +\useattachment[whatever][title][newname][test.tex] +\stoptyping + +or with all options: + +\starttyping +\useattachment[name][file][author][title][subtitle] +\stoptyping + +The \type {\use...} variant stays around for old times sake and just maps onto +\type {\registerattachment}, you can better use that one because it frees you +from remembering which arguments is what for. + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex new file mode 100644 index 00000000000..04dd3f89d05 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-bookmarks.tex @@ -0,0 +1,75 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-bookmarks + +\startchapter[title=Bookmarks] + +Bookmarks are a sort of table of contents displayed by the viewer and as such +they take up extra space on the screen. You need to turn on interaction in +order to get bookmark data embedded in the document. + +\starttyping +\placebookmarks + [chapter,section,subsection,mylist] + [chapter] +\stoptyping + +A bookmark list is added to the document only when interaction is enabled. The +list in the first argument are bookmarked while the second argument specifies +what bookmark (sub)trees are opened. if you don't get what you expect, check your +document structure! Also, use the \type {\start}|-|\type {stop} alternatives. + +Bookmarks are taken from the section title, but you can overload the title +as follows: + +\starttyping +\startchapter[title=Foot,bookmark=food] + ... +\stopchapter +\stoptyping + +If you have a more complex typeset title you can also try: + +\starttyping +\enabledirectives[references.bookmarks.preroll] +\stoptyping + +From \MKII\ we inherit the option to overload the last set bookmark but the +previously mentioned approach is better. + +\starttyping +\chapter {the first chapter} +\bookmark {the first bookmark} +\stoptyping + +You can add entries to a bookmark list: + +\starttyping +\bookmark[mylist]{whatever} +\stoptyping + +This assumes that you have defined the list. + +\showsetup {bookmark} + +If you want to have the bookmark tab open when you start a document, you +can say: + +\starttyping +\setupinteractionscreen[option=bookmark] +\stoptyping + +There are only a few options that you can use. The \type {number} parameter can +be used to hide section numbers. The \type {sectionblock} parameter controls the +addition of section block entries, something that can be handy when you have +multiple section blocks with similar section titles. With \type {force} you force +an entry to the file, bypassing mechanisms that to be clever. + +\showsetup{setupbookmark} + +\stopchapter + +\stopcomponent + diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-buttons.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-buttons.tex new file mode 100644 index 00000000000..d083a61a774 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-buttons.tex @@ -0,0 +1,98 @@ +\environment interaction-style + +\startcomponent interaction-buttons + +\startchapter[title={Buttons}] + +There is not much to tell about buttons. They are clickable areas on the screen +that when clicked on bring you some location or invoke some action in the viewer, +for instance triggered by a \JAVASCRIPT. As usual with many commands, you can +define categories of buttons and set them up globally or per category. + +\showsetup{definebutton} + +\showsetup{setupbutton} + +The default button command is: + +\showsetup{button} + +Buttons are an example of a construct that builds upon \type {\framed} so the +keys that apply there also apply to buttons. You can enable or disable buttons +with the \type {state} parameter. As usual there are a \type {style} and \type +{color} parameters and an additional \type {contrastcolor} option for tuning the +color of a button which action let you stay on the same page. Actually, when you +do stay on the same page, the \type {samepage} parameter let you control if the +button should be empty, hidden or whatever. + +\starttabulate[|B|c|c|c|] +\NC \BC frame \BC text \BC shown \NC \NR +\NC \type {yes} \NC + \NC + \NC + \NC \NR % 0 +\NC \type {empty} \NC + \NC - \NC + \NC \NR % 1 +\NC \type {no} \NC - \NC - \NC + \NC \NR % 2 +\NC \type {none} \NC - \NC - \NC - \NC \NR % 3 +\NC \type {normal} \NC + \NC + \NC + \NC \NR % 1 +\NC \type {default} \NC + \NC + \NC + \NC \NR % 1 +\stoptabulate + +Here is an example of a button: + +\startbuffer +\button + [background=color,backgroundcolor=darkred, + style=bold,color=white, + framecolor=blue,rulethickness=2pt, + width=3cm,height=1.5cm] + {go to the next page} + [nexpage] +\stopbuffer + +\typebuffer + +This colorful button shows up as: + +\startlinecorrection +\getbuffer +\stoplinecorrection + +When you use interaction in presentations you might want to make the page +and|/|or text area active. Here is an example. + +\starttyping +\defineoverlay + [PrevPage] + [\overlaybutton{PrevPage}] + +\setupbackgrounds + [page] + [background=PrevPage] + +\setuptexttexts + [\overlaybutton{NextPage}] +\stoptyping + +We provide two variants: the normal one with square brackets, but also a more +direct one that accepts curly braces, which is handy when you pass an overlay +button as argument. + +\showsetup {overlaybutton} +\showsetup {overlaybutton:direct} + +The difference in usage is shown here: + +\starttyping +\setuptexttexts [\overlaybutton{NextPage}] +\setuptexttexts[{\overlaybutton[NextPage]}] +\stoptyping + +An overlay button adapts its size to the current overlay so you don't need to +worry about passing dimensions. + +It is possible to define more complex buttons, like roll|-|over buttons or +buttons that change appearance when you clock on them. These are more resource +hungry and also depend on the viewer. These will discussed in the chapter about +widgets. + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-comments.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-comments.tex new file mode 100644 index 00000000000..b19894d577d --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-comments.tex @@ -0,0 +1,194 @@ +\environment interaction-style + +\enabletrackers[comments.anchors] + +\startcomponent interaction-comments + +\setupcomment + [location=inmargin] + +\startchapter[title={Comments}] + +Many \PDF\ viewers support text annotations. These are small notes that can be +popped up. In \CONTEXT\ we call them comments, because often that's what they are +used for. Comments evolved from simple ones using a limited encoding into more +advanced ones with representations. A comment looks like: + +\startbuffer +\startcomment + Hello beautiful world! +\stopcomment +\stopbuffer + +\typebuffer + +\getbuffer + +When you open a document with comment you will likely see some symbol depicting +it. But, it's one of those features that is viewer dependent so when it looks odd +or unexpected, check in \ACROBAT\ first. The position and size can differ per +viewer and when you zoom in the size can either stay the same or scale. The +viewer can show the pop up text at the same location or someplace else. Although +in principle there is control over this, my experience is that viewers (also +Acrobat) keep changing this (not always for the best). Just assume the worst: it +will never look good and although for a while we kept up with viewers, the +inconsistency (and accumulated waste of time) led us to the current minimalistic +approach. + +By default, in \CONTEXT\ comments are placed at the spot a bit raised. In this +document we put them in the margin, by saying: + +\starttyping +\setupcomment + [location=inmargin] +\stoptyping + +Comments can have titles and properties but not all viewers support properties. +Contrary to other environments, the first argument is not a category but a title. +This because we are compatible with \MKII. + +\startbuffer +\startcomment[french] + In France they use «angle bracket glyphs» in subsentences. +\stopcomment + +\startcomment[accents][color=darkgreen] + You can used an à çéñţêð character too. +\stopcomment +\stopbuffer + +\typebuffer \getbuffer + +And normally empty lines are also supported (again this can differ per viewer): + +\startbuffer +\startcomment[lines][color=darkblue] + How about an + + empty line? +\stopcomment +\stopbuffer + +\typebuffer \getbuffer + +As we can see here, comments are sort of stacked. These examples also show that +we can pass an optional title and set up some characteristics. An inline comment +is defined with \type {\comment}: + +\startbuffer +\comment {How I hate those notes spoiling the layout.} Maybe some day +I can convince myself to add some features \comment {Think of comment classes +that can be turned on and off and get their own colors.} related to version +control. +\stopbuffer + +\typebuffer + +\inlinebuffer\ Comments hide part of the text and thereby are to be used with +care. Until now I never used them. Anyhow, from now on, one can happily use: + +You can use other symbols than the default, and a couple are predefined in +the standard: {\tt \cldcontext {table.concat (lpdf.commentsymbols(), ", ")}}. + +\startbuffer +\startcomment[symbol=Help] + Do we want this kind of rubish? +\stopcomment +\stopbuffer + +You can also use your own symbols: + +% \definesymbol [comment-normal][{\externalfigure[cow.pdf]}] +% \definesymbol [comment-down] [{\externalfigure[cow.pdf]}] +% +% \unexpanded\def\CowSymbol#1#2% +% {\scale +% [height=#1] +% {\startMPcode +% loadfigure "cow.mp" number 1 ; +% refill currentpicture withcolor #2 ; +% \stopMPcode}} +% +% \definesymbol [comment-normal] [\CowSymbol{4ex}{darkred}] +% \definesymbol [comment-down] [\CowSymbol{4ex}{darkgreen}] + +\startbuffer +\startuniqueMPgraphic{cow}{height,s:color} + loadfigure "cow.mp" number 1 ; + refill currentpicture withcolor "\MPvar{color}" ; + currentpicture := currentpicture ysized \MPvar{height} ; +\stopuniqueMPgraphic + +\definesymbol + [comment-normal] + [\uniqueMPgraphic{cow}{height=4ex,color=darkred}] +\definesymbol + [comment-down] + [\uniqueMPgraphic{cow}{height=4ex,color=darkgreen}] + +\stopbuffer + +\typebuffer \getbuffer + +\startbuffer +\startcomment[hello][symbol={comment-normal,comment-down}] + oeps +\stopcomment +\stopbuffer + +\typebuffer \getbuffer + +Again the way this shows up depends on the viewer capabilities so there might be +a fallback on the normal comment symbol. You can influence the size of the image +(icon): + +\startbuffer +\startcomment[hello] + [symbol={comment-normal,comment-down},width=\marginwidth] + oeps +\stopcomment +\stopbuffer + +\typebuffer \getbuffer + +There are some options that you can use for finetuning the comments. + +\showsetup{setupcomment} + +A new instance is defined with: + +\showsetup{definecomment} + +The default instance is predefined by + +\starttyping +\definecomment[comment] +\stoptyping + +You can define your own instances: + +\starttyping +\definecomment[mycomment] +\stoptyping + +The generated commands have a syntax like: + +\showsetup{startcomment:instance} + +and: + +\showsetup{comment:instance} + +Most fields explain themselves. With \type {state} you can disable this feature. +Comments can be hidden in which there is no icon shown. The \type {nx} and \type +{ny} fields determine the size of the popup. + +In case you wonder where the yellow backgrounds come from, here is the trick: + +\starttyping +\enabletrackers[comments.anchors] +\stoptyping + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-contents.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-contents.tex new file mode 100644 index 00000000000..0b59c1cbb00 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-contents.tex @@ -0,0 +1,11 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-contents + +\starttitle[title=Contents] + \placelist[chapter][criterium=text] +\stoptitle + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-enabling.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-enabling.tex new file mode 100644 index 00000000000..8e31ccbe6f7 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-enabling.tex @@ -0,0 +1,117 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-enabling + +\startchapter[title=Enabling] + +Interaction is turned off by default. Of course cross referencing +work without interaction but there are no hyperlinks. You turn on +interaction with the \type {\setupinteraction} command: + +\showsetup {setupinteraction} + +The \type {state} key is the switch you need to use. In addition you might want +to setup the style and color. + +\starttyping +\setupinteraction + [state=start, + style=, + color=, + contrastcolor=] +\stoptyping + +This is the least intrusive way to get interaction in your document. By default +the style is bold and the \type {color} defaults to green. The \type +{contrastcolor} is used when a hyperlink refers to the same page and defaults to +red. A neutral setup makes sense because nowadays the reader kind of knows what +can be clicked on. + +The \type {title}, \type {subtitle}, \type {author}, \type {date} and \type +{keyword} parameters are passed to the document and will show up when you request +document information. + +The \type {openaction} parameter can for instance be used to start at a specific +page, while the \type {closeaction} can be used to trigger a \JAVASCRIPT\ cleanup +script. The \type {openpageaction} and \type {closepageaction} can for instance +initialize and reset states, something we do in some presentation styles. + +The \type {click} parameter controls how a viewer responds to pressing a mouse +button on an annotation: highlight or not. The \type {display} parameter +determines if a cross document link opens in the current window. + +The \type {menu} parameter is a quick way to disable menus, of which there can be +many: at each side of the page, stacked or not, etc. The \type {symbolset} +determines the look and feel of symbols used in for instance menus, buttons and +status bars. + +The \type {page} parameters is a bit special, and it function is an inheritance +from the early days. Some \DVI\ and \PDF\ viewers supported named destinations, +others only page references. This parameter can be used to force one or the +other. There was a time that there was a limit on the number of named references, +so going page was the only option \footnote {We're talking of 1995 when we made +documents of many thousands of pages with tens of thousands of hyperlinks, cross +linked tables of contents, registers, active graphics, etc.\ Think of +dictionaries used in very specific projects, or quality assurance manuals.} + +Personally I consider an electronic document an entity to be seen full screen on +a dedicated device. However some users prefer the target of a link to fit the +width of the screen and alike. The \type {focus} parameter can (within) +reasonable bounds provide this. The \type {focusoffset} is then used to keep +things a bit visual convenient. + +The \type {height} and \type{depth} parameters are sort of special and probably never +used. When we go back in time, to when we started adding interactivity, there were +a few issues that needed to be dealt with: + +\startitemize[packed] +\startitem + We need to make sure that we have something to click on, so we need to add + some offset if needed. +\stopitem +\startitem + We need to handle nested hyperlinks, which is why \CONTEXT\ didn't use the + link features of for instance \PDFTEX\ but built its own. +\stopitem +\startitem + Hyperlinks should break properly across lines without side effects, again a + reason for bypassing some of the \TEX\ engine's behaviour. +\stopitem +\startitem + We have to make sure that there is at least a consistent height and depth + of hyperlinks. These tight links with viewer supplied bounding boxes to + click on just look real bad! So, we had to do better. +\stopitem +\stopitemize + +Normally the two mentioned parameters are not used. However, their value will +kick in when we say \type {\setfalse \locationstrut}, in which case the given +height and depth will be used. Some advice: don't mess with this. We only have +this because it permits special effects. + +If you want to see what the target (destinations) and sources (references) of +links are, you can say: + +\starttyping +\enabletrackers[nodes.references,nodes.destinations] +\stoptyping + +The \type {fieldlayer} parameter can be used to set a so called viewer layer, so +that you can hide them (given that a viewer supports that). The \type {calculate} +parameter can associate a calculator (initializer) with the fields. + +You can create an interaction environment with: + +\showsetup {defineinteraction} + +which then can be used with: + +\showsetup {startinteraction} + +\stopchapter + +\stopcomponent + + diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex new file mode 100644 index 00000000000..f204d502e18 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-hyperlinks.tex @@ -0,0 +1,32 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-hyperlinks + +\startchapter[title=Hyperlinks] + +A hyperlink is something that you click on and that brings you to nother spot in +the document. The regular links are a side effect of references. The most commonly +used references are: + +\starttyping +\in{figure}[fig:foo] +\at{page}[fig:foo] +\about[fig:foo] +\stoptyping + +The first argument is what gets prepended to the number and the while can be +clicked on. Here we create a namespace with \type {fig:}. This can be somewhat +confusing with respect to prefixes but normally the resolver does a direct lookup +first. + +\showsetup{at} +\showsetup{in} +\showsetup{about} + +\stopchapter + +\stopcomponent + + diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-importing.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-importing.tex new file mode 100644 index 00000000000..8c36128f6b5 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-importing.tex @@ -0,0 +1,73 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-importing + +\startchapter[title=Importing] + +This is a very short chapter that deals with external figures. Normally an image +is a graphic with possible some text. There are however workflows where one +includes pages from other documents. Such documents can contain cross references, +bookmarks, comments and|/|or fields. Normally annotations of any kind are ignored +and for good reason: they assume the whole document to be the, not just one or a +few pages. Merging references for instance is a source for clashes, not only for +named ones but also for page references. + +But when you {\em know} what you're doing, as for instance Taco (who requested +this feature) does, there is a way to merge annotations. This is controlled by +the interaction keys in \type {externalfigure}: + +\starttyping +\externalfigure[somedoc][page=1,interaction=yes] +\externalfigure[somedoc][page=2,interaction={reference,bookmark}] +\stoptyping + +However, only references and bookmarks are officially supported! The other +annotations are possible but the code is experimental and will be finished +when we find a good reason for it. + +\starttabulate[|B|p|] +\FL +\NC \type {reference} \NC named and page references and urls \NC \NR +\NC \type {comment} \NC comments if possible with relevant icon \NC \NR +\NC \type {bookmark} \NC text bookmarks that refer to pages \NC \NR +\NC \type {field} \NC widgets but only within reason \NC \NR +\NC \type {layer} \NC viewer layers \NC \NR +\ML +\NC \type {yes} \NC named and page references, urls and bookmarks \NC \NR +\NC \type {all} \NC all annotations \NC \NR +\LL +\stoptabulate + +If things don't work out well, imagine for a while what is involved in supporting +this: analyzing a page from a document, remapping the annotations onto some +\CONTEXT\ mechanism, making sure that we don't get clashes, keeping overhead +acceptable. + +Because this is a somewhat tricky feature, tracing can help you to identify +problems: \typ {figures.merging}, \typ {figures.links}, \typ {figures.comments}, +\typ {figures.fields} and \typ {figures.outlines}. + +Another complication when including pages can be the presence of so called marked +content in the page stream. There is experimental support for removing those but +right now (2018) you need to explicitly enable this explicitly: + +\starttyping +\enabledirectives[graphics.pdf.uselua] +\enabledirectives[graphics.pdf.stripmarked] +%enabledirectives[graphics.pdf.recompress] +\stoptyping + +This will delegate inclusion from the backend to \LUA. This might become the +default as it is just as efficient as using the backend. That way we can filter +the content stream. \footnote {We might add a callback to \LUATEX\ for filtering +the content stream (no hard todo but post version 1.10).} + +\stopchapter + +\stopcomponent + + + + diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-introduction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-introduction.tex new file mode 100644 index 00000000000..a6f44b05b1c --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-introduction.tex @@ -0,0 +1,58 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-introduction + +\startchapter[title=Introduction] + +This document introduces the cross reference mechanism, viewer control, fill||in +fields, \JAVASCRIPT\ support, comments, attachments and more. It is a rewrite of +the \MKII\ widgets manual. There is (always) more available than discussed in +manuals so if you miss something, take a look at test suite or when you're brave, +peek into the source code as there can be examples there. + +Interactivity has always been available in \CONTEXT\ and in fact it was one of +the reasons for writing it. In for instance the YandY \WINDOWS\ previewer, one +could have hyperlinks and we used that for a while when checking documents. Later +Acrobat showed up and \PDF\ stepwise added interactive features that we always +supported right from the start. Unfortunately there is a viewer dependency and +the documentation of \PDF\ lagged behind, so solutions based on trial and error +could not work well in a follow up on \PDF. Some features disappeared or became +so limited that they effectively became useless. Especially multi||media have a +reputation of unreliability. Because open source viewers never really catched up +(at least not in this area) the momentum was lost to make sure that documents +could have audio and video embedded in reliable ways. Even forms and basic +\JAVASCRIPT\ control of for instance layers is often missing. + +That said, we do support a lot but can support more when it makes sense. Deep +down in \CONTEXT\ we always had the mechanisms to deal with this, so extensions +are not that hard to program. Somehow we thought that publishers would like these +features but that never really was the case, so there was no pressure from that +end. Most features are user driven or just there because at some point we wanted +to make some fancy presentation. In fact, the \type {s-present-*} files provide +examples of interactivity. + +The original \PDF\ reference was a couple of hundred pages and looked quite nice. +A later print has many more pages and still looks ok, but nowadays we have to do +with a \PDF\ document. If you want to see what \PDF\ supports you can study this +(now about) 750 page standard. It is, being an \ISO\ standard, not public but +you can probably find a (maybe older) copy someplace on the web. + +When reading this manual you need to keep in mind that we assume that you design +a decent layout and when you make something for an electronic medium, we hope +that you pay attention to the way you can enhance accessibility. + +If you miss something here, don't hesitate to ask for clarification, or even +better, provide an example that we then can use to discuss (an aspect of) some +mechanism. + +\stopchapter + +\stopcomponent + +% A nice double page e-ink device can be seen at: +% +% https://www.youtube.com/watch?v=QdOXCn1vvzI : +% +% vkgoeswild: Playing Pink Floyds Great Gig in the Sky on Imperial by Bösendorfer diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-javascript.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-javascript.tex new file mode 100644 index 00000000000..64e78446493 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-javascript.tex @@ -0,0 +1,136 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-javascript + +\startchapter[title={JavaScript}] + +Annotations can be controlled with \JAVASCRIPT\ but it really depends on the +viewer if it works out well. Using these scripts is a multi||step process where +common functions and data structures can be shared and collected in preambles: + +\starttyping +\startJSpreamble {name} + MyCounter = 0 ; +\stopJSpreamble +\stoptyping + +The more action oriented scripts are defined as: + +\starttyping +\startJScode {increment} + MyCounter = MyCounter + 1 ; // or: ++MyCounter ; +\stopJScode +\stoptyping + +This script is executed with: + +\starttyping +\goto {advance by one} [JS(increment)] +\stoptyping + +Nicer is to define a function: + +\starttyping +\startJSpreamble {helpers} used now + function Increment(n) { + MyCounter = MyCounter + n ; + } +\stopJSpreamble +\stoptyping + +and then say: + +\starttyping +\goto {advance by one} [JS(Increment{5})] +\stoptyping + +The distribution contains a collection of scripts that can be preloaded and used +when needed. You can recognize the files by the \type {java-imp-} prefix. To +prevent all preambles ending up in the \PDF\ file, we can say: + +\starttyping +\startJSpreamble {something} used later +\stopJSpreamble +\stoptyping + +We already saw that one can also say \type {used now} and there's also a way +to filter specific preambles on usage: + +\starttyping +\startJScode {mything} uses {something} +\stopJScode +\stoptyping + +One should be aware of the fact that there is no decent way to check if every +script is all right! Even worse, the \JAVASCRIPT\ interpreter currently used in +the \ACROBAT\ tools is not reentrant, and breaks down on typos + +The full repertoire of commands is: + +\showsetup{startJScode} + +\showsetup{startJSpreamble} + +\showsetup{addtoJSpreamble} + +\showsetup{setJSpreamble} + +As we're into \LUA\ and because \LUA\ is so lightweight I've wondered several +times now if it would make sense to embed \LUA\ in \PDF\ viewers. After all, +annotations are an extension mechanism. In the early days of \PDF\ this was +actually quite doable because \ACROBAT\ reader (and exchange) had a plugin model. +However, the more functionality ended up in the program, the least interesting +(and popular) the plugins mechanism became. Some open source viewers have an +\API\ so in principle adding the lightweight \LUA\ interpreter (of course with +\LPEG, and quite probably without file \IO) is possible. It has been discussed at +a recent \CONTEXT\ meeting, so who knows \unknown For now we're stuck with +\JAVASCRIPT. + +An example of \JAVASCRIPT\ usage is the following, where we load a video and add +some controls. Beware that this kind of functionality is very viewer dependent +and therefore also very unstable over time. Even worse, if you look at the loaded +\JAVASCRIPT\ file you will notice a dependency on soon obsolete (in \ACROBAT\ at +least) shockwave support. First we load a library that will predefine a video +graphic: and then create an instance: + +\starttyping +\useJSscripts[vplayer] + +\setupinteraction + [state=start] + +\externalfigure + [shockwave] + [frame=on, + width=480pt, + height=270pt, + file=test.mp4, + label=foo] +\stoptyping + +The controls are defined with: + +\starttyping +\goto{START} [JS(StartShockwave{foo})] +\goto{REWIND}[JS(RewindShockwave{foo})] +\goto{PAUSE} [JS(PauseShockwave{foo})] +\goto{STOP} [JS(StopShockwave{foo})] +\stoptyping + +or, as we have some defined reference shortcuts: + +\starttyping +\goto{START} [StartShockwave{foo}] +\goto{REWIND}[RewindShockwave{foo}] +\goto{PAUSE} [PauseShockwave{foo}] +\goto{STOP} [StopShockwave{foo}] +\stoptyping + +It's actually not that hard to add all kind of functionality if only we could be +sure of stable support and continuity. + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-menus.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-menus.tex new file mode 100644 index 00000000000..6e002b5cd52 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-menus.tex @@ -0,0 +1,12 @@ +\environment interaction-style + +\startcomponent interaction-menus + +\startchapter[title={Menus}] + + {\em This chapter will discuss interaction menus that normally end up in the + margins.} + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-progress.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-progress.tex new file mode 100644 index 00000000000..c077337b329 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-progress.tex @@ -0,0 +1,11 @@ +\environment interaction-style + +\startcomponent interaction-progress + +\startchapter[title={Progress}] + + {\em This chapter will discuss progress bars.} + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-structure.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-structure.tex new file mode 100644 index 00000000000..793139d6c0d --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-structure.tex @@ -0,0 +1,76 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-structure + +\startchapter[title=Structure] + +There is a lot of structure in \CONTEXT: + +\startitemize[packed] +\startitem document structure: projects, products, components, environments \stopitem +\startitem sectioning, with or without numbers (visible), support for lists and userdata \stopitem +\startitem lists, most often related to sections, but there are more \stopitem +\startitem registers \stopitem +\startitem itemized lists \stopitem +\startitem images, \METAPOST\ graphics, different types of tables \stopitem +\startitem typographical objects: constructions, descriptions and enumerations \stopitem +\startitem notes, like footnotes, endnotes, linenotes \stopitem +\startitem marginal notes \stopitem +\startitem formulas (and subformulas) \stopitem +\startitem text areas, layers, overlays \stopitem +\startitem graphic placement with captions and references \stopitem +\startitem cross references to most structural components \stopitem +\startitem bibliographic databases and citations \stopitem +\blank +\startitem \unknown\ and more \unknown \stopitem +\stopitemize + +Most of them in some way carry information about their location in the document +and on the page, and sometimes their exact position. This also means that we can +use that information for annotations. But most users will use the standard +functionality. + +\starttyping +\startsection[title=Whatever] + ... +\stopsection +\stoptyping + +In addition to typesetting this will add the title to a list. In order to do that +some anchor has to be placed in the text, because we need to register the exact +location in order to get the right pagenumber after \TEX\ has broken the flow into +pages. + +\starttyping +\placelist[section][criterium=text] +\stoptyping + +This will place a list of all sections. If you want the whole entry to be a +clickable areas, you can say: + +\starttyping +\placelist[section][interaction=all] +\stoptyping + +Otherwise only clicking on the title will bring you to the spot. If you also say: + +\starttyping +\setuphead[interaction=list] +\stoptyping + +Clicking on the head will bring you back to the table of contents. There are +special list rendering alternatives for interactive documents (\typ +{alternative=e} onwards). You can use the \type {list} and \type {bookmark} +parameters to a section head to deviate from the given \type {title}. + +Many commands accept a \type {reference} as optional argument and when you use +an alternative with key|/|values a \type {reference} key will do the job. + +{\em What should go into this chapter.} + +\stopchapter + +\stopcomponent + diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-style.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-style.tex new file mode 100644 index 00000000000..e9922fb1415 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-style.tex @@ -0,0 +1,59 @@ +\startenvironment interaction-style + +\usemodule[abr-02] +\usemodule[scite] +\usemodule[setups-basics] + +\loadsetups[context-en] + +\setupbodyfont[plex,rm] + +\setupwhitespace + [big] + +\setuptolerance + [verytolerant,stretch] + +\setuppagenumbering + [alternative=doublesided] + +\setuplayout + [footer=0cm, + backspace=3cm, + cutspace=2cm, + width=middle, + height=middle, + margin=1.75cm, + margindistance=5mm] + +\setupfloats + [ntop=100] + +\setupinteraction + [state=start, + style=, + color=, + contrastcolor=] + +\setuphead + [interaction=list] + +\setuphead + [chapter] + [header=high, + style=\bfd] + +\setuphead + [section] + [style=\bfb] + +% \definecolor[backcolor][r=.8,b=.7,g=.8] +\definecolor[backcolor][s=.8] + +\setupframedtext + [setuptext] + [frame=off, + background=color, + backgroundcolor=backcolor] + +\stopenvironment diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-tagging.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-tagging.tex new file mode 100644 index 00000000000..d38c922f2b9 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-tagging.tex @@ -0,0 +1,26 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-tagging + +\startchapter[title=Tagging] + +In a tagged \PDF\ document the page stream is enriched (or polluted) by marks +that indicate what kind of content is involved. + +\starttyping +\setuptagging[state=start] +\stoptyping + +Only the \type {state} parameters is of general use. + +\showsetup {setuptagging} + +The \TEX\ end of this mechanism overlaps with the export related tagging so when +you add your own elements that will be reflected in the tagging. And indeed: the +keyword here is structure. The worse the structure, the worse the tagging. + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex new file mode 100644 index 00000000000..43b29baf961 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-titlepage.tex @@ -0,0 +1,47 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-titlepage + +\startMPpage + + StartPage ; + numeric w, h, sh ; transform t ; path p ; pair c ; + w := PaperWidth ; + h := PaperHeight ; + p := Page ; + fill p withcolor .4white ; + sh := define_linear_shade(llcorner p, urcorner p, .6yellow, .6blue) ; + c := center boundingbox outlinetext.p("\ss\bf INTERACTIVITY") ; + set_grid(w, h, w/8, h/8) ; + forever : + if new_on_grid(uniformdeviate w,uniformdeviate h) : + t := identity + scaled (3+uniformdeviate 3) + shifted ((dx,dy) - c) + ; + draw outlinetext.b + ("\bf\ss INTERACTIVITY") + (transformed t withshade sh) + (transformed t withpen pencircle scaled 3 withcolor .6white) + ; + fi ; + exitif grid_full ; + endfor ; + draw anchored.lrt ( + textext("\bf\ss \ConTeXt") xsized .6PaperWidth, + lrcorner p shifted (-10mm,40mm) + ) withcolor white ; + draw anchored.lrt ( + textext("\bf\ss Hans Hagen") xsized .6PaperWidth, + lrcorner p shifted (-10mm,15mm) + ) withcolor white ; + StopPage; + +\stopMPpage + +\page[empty] +\page[right] + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-transitions.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-transitions.tex new file mode 100644 index 00000000000..0cde2804076 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-transitions.tex @@ -0,0 +1,64 @@ +% language=uk + +\environment interaction-style + +\startcomponent interaction-transitions + +\startchapter[title={Page transitions}] + +I'm not sure if this feature is still used but in the early days of \PDF\ support +in \TEX, users loved it. I never really used it myself. Page transitions only +make sense in presentations, and unfortunately the ones provided by the Acrobat +viewers are just ugly. Anyhow, one automatically gets them by saying: + +\starttyping +\setuppagetransitions[random] +\stoptyping + +This way one gets random transitions. Resetting transitions is done by: + +\starttyping +\setuppagetransitions[reset] +\stoptyping + +If needed one can specify transitions but I strongly advice against this, because +these commands are very viewer dependant, therefore: if in despair, use numbers! +By default, the next set is used, and one can access them by number, + +\starttabulate[|c|l|] +\HL +\NC \bf number \NC \bf transition effects \NC\NR +\HL +\NC 1\quad 2 \NC \type{{split,in,vertical}} + \type{{split,in,horizontal}} \NC\NR +\NC 3\quad 4 \NC \type{{split,out,vertical}} + \type{{split,out,horizontal}} \NC\NR +\NC 5\quad 6 \NC \type{{blinds,horizontal}} + \type{{blinds,vertical}} \NC\NR +\NC 7\quad 8 \NC \type{{box,in}} + \type{{box,out}} \NC\NR +\NC 9\quad10\quad11\quad12 \NC \type{{wipe,east}} + \type{{wipe,west}} + \type{{wipe,north}} + \type{{wipe,south}} \NC\NR +\NC 13 \NC \type{dissolve} \NC\NR +\NC 14\quad15 \NC \type{{glitter,east}} + \type{{glitter,south}} \NC\NR +\HL +\stoptabulate + +The next settings are all valid: + +\starttyping +\setuppagetransitions +\setuppagetransitions[1] +\setuppagetransitions[3,5,8,random] +\stoptyping + +Valid setups are: + +\setup{setuppagetransitions} + +\stopchapter + +\stopcomponent diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-widgets.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-widgets.tex new file mode 100644 index 00000000000..e4fa136c9c5 --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction-widgets.tex @@ -0,0 +1,977 @@ +\environment interaction-style + +\startcomponent interaction-widgets + +\startchapter[title={Widgets}] + + {\em This chapter will discuss forms and special buttons.} + +\stopchapter + +\stopcomponent + +% Below comes from the old widgets manual: + +\def\fillinfield#1{} + +% \useJSscripts[fld] +% \setupinteraction[state=start,closeaction=ForgetAll] + +\section{Fill||in fields} + +Fields come in many disguises. Currently \CONTEXT\ supports +the field types provided by \PDF, which in turn are derived +from \HTML. Being a static format and not a programming +language, \PDF\ only provides the interface. Entering data +is up to the viewer and validation to the built in +\JAVASCRIPT\ interpreter. The next paragraph shows an +application. + +\startbuffer +A few years back, \TEX\ could only produce \fillinfield [dvi] +{\DVI} output, but nowadays, thanks to \fillinfield {Han The +Thanh}, we can also directly produce \fillinfield [pdf] {\PDF}! +Nice eh? Actually, while the first field module was prototyped +in \ACROBAT, the current implementation was debugged in +\fillinfield [pdfTeX] {\PDFTEX}. Field support in \fillinfield +[ConTeXt] {\CONTEXT} is rather advanced and complete and all +kind of fields are supported. One can hook in appearances, and +validation \fillinfield [JavaScripts] {\JAVASCRIPT}'s. Fields +can be cloned and copied, where the latter saves some space. By +using \fillinfield {objects} when suited, this module saves +space anyway. +\stopbuffer + +\getbuffer + +This paragraph is entered in the source file as: + +\typebuffer + +I leave it to the imagination of the user how +\type{\fillinfield} is implemented, but trust me, the +definition is rather simple and is based on the macros +mentioned below. + +Because I envision documents with many thousands of fields, +think for instance of tutorials, I rather early decided to +split the definition from the setup. Due to the fact that +while typesetting a field upto three independant instances +of \type{\framed} are called, we would end up with about +150~hash entries per field, while in the current +implementation we only need a few. Each field can inherit +its specific settings from the setup group it belongs to. + +Let's start with an example of a {\em radio} field. In fact +this is a collection of fields. Such a field is defined +with: + +\startbuffer +\definefield + [Logos] [radio] [LogoSetup] + [ConTeXt,PPCHTEX,TeXUtil] [PPCHTEX] +\stopbuffer + +\typebuffer + +\getbuffer + +Here the fourth argument specifies the subfields and the +last argument tells which one to use as default. We have to +define the subfields separately: + +\startbuffer +\definesubfield [ConTeXt] [] [ConTeXtLogo] +\definesubfield [PPCHTEX] [] [PPCHTEXLogo] +\definesubfield [TeXUtil] [] [TeXUtilLogo] +\stopbuffer + +\typebuffer + +\getbuffer + +The second argument specifies the setup. In this example +the setup (\type {LogoSetup}) is inherited from the main +field. The third arguments tells \CONTEXT\ how the fields +look like when turned on. These appearances are to be +defined as symbols: + +\startbuffer +\definesymbol [ConTeXtLogo] [{\externalfigure[mp-cont.502]}] +\definesymbol [PPCHTEXLogo] [{\externalfigure[mp-cont.503]}] +\definesymbol [TeXUtilLogo] [{\externalfigure[mp-cont.504]}] +\stopbuffer + +\typebuffer + +\getbuffer + +Before we typeset the fields, we specify some settings to use: + +\startbuffer +\setupfield [LogoSetup] + [width=4cm, + height=4cm, + frame=off, + background=screen] +\stopbuffer + +\typebuffer + +\getbuffer + +Finally we can typeset the fields: + +\startbuffer +\hbox to \hsize + {\hss\field[ConTeXt]\hss\field[PPCHTEX]\hss\field[TeXUtil]\hss} +\stopbuffer + +\typebuffer + +This shows up as: + +\startbaselinecorrection +\getbuffer +\stopbaselinecorrection + +An important characteristic of field is cloning cq.\ +copying, as demonstrated below: + +% \tracefieldstrue + +\startbuffer[symbol] +\definesymbol [yes-a] [$\times$] +\definesymbol [yes-b] [$\star$] +\definesymbol [nop-a] [$\bullet$] +\definesymbol [nop-b] [$-$] +\stopbuffer + +\getbuffer[symbol] + +\startbuffer[define] +\definefield [example-1] [radio] [setup 1] [ex-a,ex-b,ex-c] [ex-c] +\definesubfield [ex-a,ex-b,ex-c] [setup 1] [yes-a,nop-a] +\stopbuffer + +\getbuffer[define] + +\startbuffer[clone] +\clonefield [ex-a] [ex-p] [setup 2] [yes-b,nop-b] +\clonefield [ex-b] [ex-q] [setup 2] [yes-b,nop-b] +\clonefield [ex-c] [ex-r] [setup 2] [yes-b,nop-b] +\stopbuffer + +\getbuffer[clone] + +\startbuffer[copy] +\copyfield [ex-a] [ex-x] +\copyfield [ex-b] [ex-y] +\copyfield [ex-c] [ex-z] +\stopbuffer + +\getbuffer[copy] + +\startbuffer[setup] +\setupfield [setup 1] [width=1cm,height=1cm,framecolor=red] +\setupfield [setup 2] [width=.75cm,height=.75cm] +\stopbuffer + +\getbuffer[setup] + +\startbuffer[field] +\hbox to \hsize + {\field[ex-a]\hfil\field[ex-b]\hfil\field[ex-c]\hfil\hfil + \field[ex-p]\hfil\field[ex-q]\hfil\field[ex-r]\hfil\hfil + \field[ex-x]\hfil\field[ex-y]\hfil\field[ex-z]} +\stopbuffer + +\startbaselinecorrection \getbuffer[field] \stopbaselinecorrection + +The next table shows the relations between these fields of type radio: + +\startbaselinecorrection +\showfields +\stopbaselinecorrection + +This table is generated by \type {\showfields} and can be +used to check the relations between fields, but only when +we have set \type {\tracefieldstrue}. Radio fields have the +most complicated relationships of fields, due to the fact +that only one of them can be activated (on). By saying +\type {\logfields} one can write the current field +descriptions to the file \type {fields.log}. + +Here we used some \TEX\ mathematical symbols. These are +functional but sort of dull, so later we will define a more +suitable visualization. + +\typebuffer[symbol] + +The parent fields were defined by: + +\typebuffer[define] + +and the clones, which can have their own appearance, by: + +\typebuffer[clone] + +The copies are defined using: + +\typebuffer[copy] + +using the setups + +\typebuffer[setup] + +Finally all these fields are called using \type {\field}: + +\typebuffer[field] + +Now we will define a so called {\em check} field. This +field looks like a radio field but is independant of +others. First we define some suitable symbols: + +\startbuffer +\definesymbol [yes] [{\externalfigure[mp-cont.502]}] +\definesymbol [no] [] +\stopbuffer + +\getbuffer + +\typebuffer + +A check field is defined as: + +\startbuffer +\definefield [check-me] [check] [setup 3] [yes,no] [no] +\stopbuffer + +\getbuffer + +\typebuffer + +This time we say \type{\field[check-me]} and get: + +\startbuffer +\setupfield + [setup 3] + [width=2cm, height=2cm, + rulethickness=3pt, corner=round, framecolor=red] +\stopbuffer + +\getbuffer + +\startlinecorrection +\hbox to \hsize{\hss\field[check-me]\hss} +\stoplinecorrection + +As setup we used: + +\typebuffer + +We already saw an example of a {\em line} field. By default +such a line field looks like: + +\startbuffer[define] +\definefield [Email] [line] [ShortLine] [] [pragma@wxs.nl] +\stopbuffer + +\getbuffer[define] + +\startbuffer[field] +\field [Email] [your email] +\stopbuffer + +\startbaselinecorrection \getbuffer[field] \stopbaselinecorrection + +We defined this field as: + +\typebuffer[define] + +and called it using a second, optional, argument: + +\typebuffer[field] + +As shown, we can influence the way such a field is typeset. +It makes for instance sense to use a monospaced typeface +and limit the height. When we set up a field, apart from +the setup class we pass some general characteristics, and +three more detailed definitions, concerning the +surrounding, the label and the field itself. + +\startbuffer +\setupfield + [ShortLine] + [label,frame,horizontal] + [offset=4pt,height=fit,framecolor=green, + background=screen,backgroundscreen=.80] + [height=18pt,width=80pt,align=middle, + background=screen,backgroundscreen=.90,frame=off] + [height=18pt,width=80pt,color=red,align=right,style=type, + background=screen,backgroundscreen=.90,frame=off] +\stopbuffer + +\typebuffer + +So now we get: + +\getbuffer + +\startbuffer[mainmail] +\definemainfield [MainMail] [line] [ShortLine] [] [pragma@wxs.nl] +\stopbuffer + +\getbuffer[mainmail] + +\startlinecorrection +\field [MainMail] [your email] +\stoplinecorrection + +Such rather long definitions can be more sparse when we set +up all fields at once, like: + +\startbuffer +\setupfields + [label,frame,horizontal] + [offset=4pt,height=fit,framecolor=green, + background=screen,backgroundscreen=.80] + [height=18pt,width=80pt, + background=screen,backgroundscreen=.90,frame=off] + [height=18pt,width=80pt,color=red,align=middle, + background=screen,backgroundscreen=.90,frame=off] +\stopbuffer + +\typebuffer + +So given that we have defined field \type {MainMail} we can +say: + +\startbuffer[MP] +\startuniqueMPgraphic{button} + path p ; p := fullcircle xyscaled (OverlayWidth,OverlayHeight) ; + fill p withcolor (.8,.8,.8) ; + draw p withcolor OverlayColor withpen pencircle scaled 3 ; +\stopuniqueMPgraphic + +\defineoverlay [normalbutton] [\uniqueMPgraphic{button}] +\stopbuffer + +\getbuffer[MP] + +\startbuffer +\setupfield [LeftLine] + [background=normalbutton, backgroundcolor=darkgreen, + offset=2ex, height=7ex, width=.25\hsize, + style=type, frame=off, align=left] +\setupfield [MiddleLine] + [background=normalbutton, backgroundcolor=darkgreen, + offset=2ex, height=7ex, width=.25\hsize, + style=type, frame=off, align=middle] +\setupfield [RightLine] + [background=normalbutton, backgroundcolor=darkgreen, + offset=2ex, height=7ex, width=.25\hsize, + style=type, frame=off, align=right] + +\clonefield [MainMail] [LeftMail] [LeftLine] +\clonefield [MainMail] [MiddleMail] [MiddleLine] +\clonefield [MainMail] [RightMail] [RightLine] +\stopbuffer + +\typebuffer + +\getbuffer + +We get get three connected fields: + +\startlinecorrection +\hbox to \hsize + {\field[LeftMail]\hss\field[MiddleMail]\hss\field[RightMail]} +\stoplinecorrection + +(Keep in mind that in \CONTEXT\ left aligned comes down to +using \type {\raggedleft}, which can be confusing, but +history cannot be replayed.) + +By the way, this shape was generated by \METAPOST\ using +the overlay mechanism: + +\typebuffer[MP] + +Due to the fact that a field can have several modes (loner, +parent, clone or copy), one cannot define a clone or copy +when the parent field is already typeset. When one knows in +advance that there will be clones or copies, one should +use: + +\typebuffer[mainmail] + +Now we can define copies, clones and even fields with the +same name, also when the original already is typeset. Use +\type {\showfields} to check the status of fields. When in +this table the mode is typeset slanted, the field is not +yet typeset. + +The values set up with \type {\setupfield} are inherited by +all following setup commands. One can reset these default +values by: + +\startbuffer +\setupfields[reset] +\stopbuffer + +\typebuffer + +\getbuffer + +When we want more than one line, we use a {\em text} field. +Like the previous fields, text must be entered in the +viewer specific encoding, in our case, \PDF\ document +encoding. To free users from thinking of encoding, +\CONTEXT\ provides a way to force at least the accented +glyphs into a text field in a for \TEX\ users familiar way: + +\setupfields + [horizontal] + [offset=4pt,height=fit,framecolor=green, + background=screen,backgroundscreen=.80] + [height=18pt,width=80pt, + background=screen,backgroundscreen=.90,frame=off] + [height=18pt,width=80pt,color=red,align=middle, + background=screen,backgroundscreen=.90,frame=off] + +\definefield + [SomeField] [text] [TextSetup] + [hi there, try \string\\ \string " e or + \string\\ \string~ n to get \"e or \~n] + +\setupfield + [TextSetup] + [label,frame,horizontal][framecolor=green][] + [height=80pt,width=240pt,style=\sl,align=middle, + enterregion=JS(Initialize_TeX_Key), + afterkey=JS(Convert_TeX_Key), + validate=JS(Convert_TeX_String)] + +\startbaselinecorrection +\field[SomeField][Just Some Text] +\stopbaselinecorrection + +Now, how is this done? Defining the field is not that hard: + +\starttyping +\definefield [SomeField] [text] [TextSetup] [default text] +\stoptyping + +The conversion is taken care of by a \JAVASCRIPT's. We can assign such +scripts to mouse and keyboard events, like in: + +\starttyping +\setupfield + [TextSetup][...][...][...] + [...., + regionin=JS(Initialize_TeX_Key), + afterkey=JS(Convert_TeX_Key), + validate=JS(Convert_TeX_String)] +\stoptyping + +The main reason for using the \type{JS(...)} method here is +that this permits future extensions and looks familiar at +the same time. Depending on the assignments, one can +convert after each keypress and|/|or after all text is +entered. + +\startbuffer +\definefield + [Ugly] [choice] [UglySetup] + [ugly,awful,bad] [ugly] +\setupfield + [UglySetup] + [width=6em, + height=1.2\lineheight, + location=low] +\stopbuffer + +\getbuffer + +We've arrived at another class of fields: {\em choice}, +{\em pop||up} and {\em combo} fields. All those are menu +based (and \vbox{\field[Ugly]}). This in||line menu was +defined as: + +\typebuffer + +\startbuffer +\definefield + [Ugly2] [popup] [UglySetup] + [ugly,awful,bad] [ugly] +\definefield + [Ugly3] [combo] [UglySetup] + [ugly,{AWFUL=>awful},bad] [ugly] +\stopbuffer + +\getbuffer + +Pop||up fields look like: \vbox{\field[Ugly2]} and combo +fields permit the user to enter his or her own option: +\vbox{\field[Ugly3]}. The amount of typographic control +over these three type of fields is minimal, but one can +specify what string to show and what string results: + +\typebuffer + +Here \type{AWFUL} is shown and when selected becomes the +choice \type{awful}. Just in case one wonders why we use +\type{=>}, well, it just looks better and the direction +shows what value will be output. + +\startbuffer[uglies] +\definefieldset [AllUglies] [Ugly, Ugly2, Ugly3] +\stopbuffer + +\getbuffer[uglies] + +\startbuffer +One can for instance \goto {reset the form} [ResetForm] or +\goto {part of the form} [ResetForm{AllUglies}]. This last +sentence was typed in as: +\stopbuffer + +A special case of the check type field is a pure {\em push} +field. Such a field has no export value and has only use as +a pure interactive element. For the moment, let's forget +about that one. + +Before we demonstrate our last type of fields and show some +more tricky things, we need to discuss what to do with the +information provided by filling in the fields. There are +several actions available related to fields. + +\getbuffer + +\typebuffer + +Hereby \type {AllUglies} is a set of fields to be defined +on forehand, using + +\typebuffer[uglies] + +In a similar way one can \goto {submit some or all fields} +[SubmitForm] using the \type {SubmitForm} directive. This +action optionally can take two arguments, the first being +the destination, the second a list of fields to submit, for +instance: + +\starttyping +\button{submit}[SubmitForm{mailto::pragma@wxs.nl,AllUglies}] +\stoptyping + +Once the fields are submitted (or saved in a file), we can +convert the resulting \FDF\ file into something \TEX\ with +the perl program \type{fdf2tex}. One can use \type +{\ShowFDFFields{filename}} to typeset the values. If you do +not want to run the \PERL\ converter from within \TEX, say +\type {\runFDFconverterfalse}. In that case, the (stil) +less robust \TEX\ based converter will be used. + +I already demonstrated how to attach scripts to events, but +how about changing the appearance of the button itself? +Consider the next definitions: + +\startbuffer +\definesymbol [my-y] [$\times$] +\definesymbol [my-r] [?] +\definesymbol [my-d] [!] + +\definefield + [my-check] [check] [my-setup] + [{my-y,my-r,my-d},{,my-r,my-d}] +\stopbuffer + +\typebuffer + +\getbuffer + +Here we omitted the default value, which always is {\em no} +by default. The setup can look like this: + +\startbuffer +\setupfield + [my-setup] + [width=1.5cm, height=1.5cm, + frame=on, framecolor=red, rulethickness=1pt, + backgroundoffset=2pt, background=screen, backgroundscreen=.85] +\stopbuffer + +\typebuffer + +\getbuffer + +Now when this field shows up, watch what happens when the +mouse enters the region and what when we click. + +\startbaselinecorrection +\hbox to \hsize{\hss\field[my-check]\hss} +\stopbaselinecorrection + +So, when instead of something \type{[yes,no]} we give +triplets, the second element of such a triplet declares the +roll||over appearance and the third one the push||down +appearance. The braces are needed! + +One application of appearances is to provide help or +additional information. Consider the next definition: + +\startbuffer +\definefield [Help] [check] [HelpSetup] [helpinfo] [helpinfo] +\stopbuffer + +\typebuffer + +\getbuffer + +This means as much as: define a check field, typeset this +field using the help specific setup and let \type{helpinfo} +be the on||value as well as the default. Here we use the +next setup: + +\startbuffer +\setupfields + [reset] +\setupfield + [HelpSetup] + [width=fit,height=fit,frame=off,option={readonly,hidden}] +\stopbuffer + +\typebuffer + +\getbuffer + +We didn't use options before, but here we have to make sure +that users don't change the content of the field and by +default we don't want to show this field at all. The actual +text is defined as a symbol: + +\startbuffer +\definesymbol [helpinfo] [\SomeHelpText] + +\def\SomeHelpText% + {\framed + [width=\leftmarginwidth,height=fit,align=middle,style=small, + frame=on,background=color,backgroundcolor=white,framecolor=red] + {Click on the hide button to remove this screen}} +\stopbuffer + +\typebuffer + +\getbuffer + +\startbuffer +\inmargin {\fitfield[Help]} Now we can put the button somewhere and +turn the help on or off by saying \goto {Hide Help} [HideField{Help}] +or \goto {Show Help} [ShowField{Help}]. Although it's better to put +these commands in a dedicated part of the screen. And try \goto +{Help} [JS(Toggle_Hide{Help})]. +\stopbuffer + +\getbuffer + +We can place a field anywhere on the page, for instance by +using the \type {\setup...texts} commands. Here we simply +said: + +\typebuffer + +When one uses for instance \type {\setup...texts}, one +often wants the help text to show up on every next page. +This can be accomplished by saying: + +\starttyping +\definemainfield [Help] [check] [HelpSetup] [helpinfo] [helpinfo] +\stoptyping + +Every time such a field is called again, a new copy is +generated automatically. Because fields use the +objectreference mechanism and because such copies need to +be known to their parent, field inclusion is a multi||pass +typesetting job (upto 4 passes can be needed!). + +When possible, appearances are shared between fields, +mainly because this saves space, but at the cost of extra +object references. This feature is not that important for +straight forward forms, but has some advantages when +composing more complicated (educational) documents. + +Let us now summarize the commands we have available for +defining and typesetting fields. The main definition macro +is: + +\setup{definefield} + +and for radiofields we need to define the components by: + +\setup{definesubfield} + +Fields can be cloned and copied, where the latter can not +be set up independently. + +\setup{clonefield} + +\setup{copyfield} + +Fields can be grouped, and such a group can have its own +settings. Apart from copied fields, we can define the +layout of a field and set options using: + +\setup{setupfield} + +Such a group inherits its settings from the general setup +command: + +\setup{setupfields} + +Fields are placed using one of: + +\setup{field} + +or + +\setup{fitfield} + +Some pages back I showed an example of: + +\setup{fillinfield} + +Finally there are two commands to trace fields. These +commands only make sense when one already has said: \type +{\tracefieldstrue}. + +\setup{showfields} + +\setup{logfields} + +\section{Tooltips} + +\startbuffer +Chinese people seem to have no problems in recognizing their many +different pictorial glyphs. \tooltip [left] {Western} {European +and American} people however seem to have problems in understanding +what all those \tooltip [middle] {icons} {small graphics} on their +computer screens represent. But, instead of standardizing on a set +of icons, computer programmers tend to fill the screen with so +called tooltips. Well, \tooltip {\CONTEXT} {a \TEX\ macro package} +can do tooltips too, and although a good design can do without them, +\TEX\ at least can typeset them correctly. +\stopbuffer + +\getbuffer + +The previous paragraph has three of such tooltips under +{\em western}, {\em icons} and {\em \CONTEXT}, each aligned +differently. We just typed: + +\typebuffer + +This is an official command, and thereby we can show its +definition: + +\setup{tooltip} + +\section{Fieldstacks} + +In due time I will provide more dedicated field commands. +Currently apart from \type {\fillinfield} and \type +{\tooltip} we have \type {\fieldstack}. Let's spend a few +words on those now. + +\startbuffer[somemap1] +\useexternalfigure [map -- -- --] [euro-10] [width=.3\hsize] +\useexternalfigure [map nl -- --] [euro-11] [map -- -- --] +\useexternalfigure [map nl de --] [euro-12] [map -- -- --] +\useexternalfigure [map nl de en] [euro-13] [map -- -- --] + +\definesymbol [map -- -- --] [{\externalfigure[map -- -- --]}] +\definesymbol [map nl -- --] [{\externalfigure[map nl -- --]}] +\definesymbol [map nl de --] [{\externalfigure[map nl de --]}] +\definesymbol [map nl de en] [{\externalfigure[map nl de en]}] + +\stopbuffer + +\startbuffer[somemap2] +\definefieldstack + [somemap] + [map -- -- --, map nl -- --, map nl de --, map nl de en] + [frame=on] +\stopbuffer + +\startbuffer[somemap3] +\placefigure + [left][fig:somemap] + {Do you want to see what interfaces + are available? Just click \goto + {here} [JS(Walk_Field{somemap})] + a few times!} + {\fieldstack[somemap]} +\stopbuffer + +\getbuffer[somemap1,somemap2,somemap3] + +One can abuse field for educational purposes. Take for +instance \in{figure}[fig:somemap]. In this figure we can +sort of walk over different alternatives of the same +graphic. This illustration was typeset by saying: + +\typebuffer[somemap3] + +However, before we can ask for such a map, we need to +define a field set, which in fact is a list of symbols to +show. This list is defined using: + +\typebuffer[somemap2] + +which in turn is preceded by: + +\typebuffer[somemap1] + +\startbuffer +\placefigure + [here][fig:anothermap] + {Choose \goto {one} [JS(Set_Field{anothermap,2})] country, + \goto {two} [JS(Set_Field{anothermap,3})] countries, + \goto {three} [JS(Set_Field{anothermap,4})] countries or + \goto {no} [JS(Set_Field{anothermap,1})] countries at all.} + {\fieldstack + [anothermap] + [map -- -- --, map nl -- --, map nl de --, map nl de en] + [frame=on]} +\stopbuffer + +\getbuffer + +A slightly different illustration is shown in +\in{figure}[fig:anothermap]. Here we use the same symbols +but instead say: + +\typebuffer + +As one can see, we can can skip the definition and pass it +directly, but I wouldn't call that beautiful. + +The formal definitions are: + +\setup{definefieldstack} + +\setup{fieldstack} + +Instead if stacking fields, you can of course also put them +alongside. This makes sense when you want to use dedicated +(visible) captions for each image. + +\startbuffer +\useexternalfigure [europe] [euro-10] [width=.3\hsize] +\useexternalfigure [holland] [euro-nl] [europe] +\useexternalfigure [germany] [euro-de] [europe] +\useexternalfigure [england] [euro-en] [europe] + +\definesymbol [europe] [{\externalfigure[europe]}] +\definesymbol [holland] [{\externalfigure[holland]}] +\definesymbol [germany] [{\externalfigure[germany]}] +\definesymbol [england] [{\externalfigure[england]}] + +\definefield + [interface] [radio] [map] + [england,germany,holland] [holland] + +\definesubfield [holland] [] [holland,europe] +\definesubfield [germany] [] [germany,europe] +\definesubfield [england] [] [england,europe] + +\setupfield[map][frame=off] +\stopbuffer + +\typebuffer + +\getbuffer + +We can for instance typeset the fields by saying: + +\startbuffer +\startcombination[3] + {\fitfield[holland]} {Dutch Interface} + {\fitfield[germany]} {German Interface} + {\fitfield[england]} {English Interface} +\stopcombination +\stopbuffer + +\typebuffer + +\startbaselinecorrection +\getbuffer +\stopbaselinecorrection + + + +%D \starttyping +%D \defineviewerlayer[test] +%D +%D \startviewerlayer[test]Hide Me\stopviewerlayer +%D +%D \defineoverlay +%D [WithTest] +%D [{\overlayrollbutton[HideLayer{test}][VideLayer{test}]}] +%D +%D \framed[background=WithTest]{toggle} +%D \stoptyping + + + +% \setupinteraction[state=start] +% +% \definepushbutton [reset] +% +% \startuniqueMPgraphic{whatever}{color} +% fill fullcircle xysized (OverlayWidth,OverlayHeight) withcolor \MPvar{color} ; +% \stopuniqueMPgraphic +% +% \definepushsymbol [reset] [n] [\uniqueMPgraphic{whatever}{color=red}] +% \definepushsymbol [reset] [r] [\uniqueMPgraphic{whatever}{color=green}] +% \definepushsymbol [reset] [d] [\uniqueMPgraphic{whatever}{color=blue}] +% +% \starttext +% \startTEXpage +% \pushbutton [reset] [page(2)] +% \stopTEXpage +% \startTEXpage +% \pushbutton [reset] [page(1)] +% \stopTEXpage +% \stoptext + + +% \setupinteraction[state=start] +% +% \definepushbutton [reset] +% +% \startuniqueMPgraphic{whatever}{color} +% fill fullcircle xysized (OverlayWidth,OverlayHeight) withcolor \MPvar{color} ; +% \stopuniqueMPgraphic +% +% \definepushsymbol [reset] [n] [\uniqueMPgraphic{whatever}{color=red}] +% \definepushsymbol [reset] [r] [\uniqueMPgraphic{whatever}{color=green}] +% \definepushsymbol [reset] [d] [\uniqueMPgraphic{whatever}{color=blue}] +% +% \starttext +% \startTEXpage +% \pushbutton [reset] [page(2)] +% \stopTEXpage +% \startTEXpage +% \pushbutton [reset] [page(1)] +% \stopTEXpage +% \stoptext + +% \appendtoks +% \let\startrob\scrn_menu_rob_start +% \let\stoprob \relax +% \let\rob \scrn_menu_rob_direct +% \to \everysetmenucommands + +% \protect \endinput diff --git a/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction.tex b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction.tex new file mode 100644 index 00000000000..077e4abd8fb --- /dev/null +++ b/Master/texmf-dist/doc/context/sources/general/manuals/interaction/interaction.tex @@ -0,0 +1,34 @@ +\environment interaction-style + +\setuplayout[bottom=1cm,bottomdistance=1cm] +\setupbottomtexts[\infofont work in progress] + +\startdocument + + \component interaction-titlepage + + \startfrontmatter + \component interaction-contents + \component interaction-introduction + \stopfrontmatter + + \startbodymatter + \component interaction-annotations + \component interaction-enabling + \component interaction-actions + \component interaction-hyperlinks + \component interaction-structure + \component interaction-comments + \component interaction-attachments + \component interaction-bookmarks + \component interaction-javascript + \component interaction-buttons + \component interaction-menus + \component interaction-progress + \component interaction-widgets + \component interaction-transitions + \component interaction-importing + \component interaction-tagging + \stopbodymatter + +\stopdocument |