diff options
Diffstat (limited to 'doc/context/sources/general/manuals/interaction/interaction-actions.tex')
| -rw-r--r-- | doc/context/sources/general/manuals/interaction/interaction-actions.tex | 194 |
1 files changed, 194 insertions, 0 deletions
diff --git a/doc/context/sources/general/manuals/interaction/interaction-actions.tex b/doc/context/sources/general/manuals/interaction/interaction-actions.tex new file mode 100644 index 000000000..3c9bfe842 --- /dev/null +++ b/doc/context/sources/general/manuals/interaction/interaction-actions.tex @@ -0,0 +1,194 @@ +% 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 navigational, 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 +hyperreferences, 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 {previouspage} 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 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}})] +\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}. 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}] +\showreference[JS(Forget_Changes),CloseDocument] +\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 |