% language=us

\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

