1
2
3\environment interactionstyle
4
5\usemodule[referencesidentify]
6
7\startcomponent interactionactions
8
9\startchapter[title=Actions]
10
11The reference mechanism not only deals with the more traditional cross
12references, but also takes care of navigation, launching applications (although
13that is often limited by viewers), running \JAVASCRIPT, etc. By integrating these
14features in one mechanism, we limit the number of commands needed for hyperlinks,
15menus and buttons. Normally such actions are driven by the \type {\goto} command,
16but you can also use buttons:
17
18\starttyping
19\goto[inner reference]
20\goto[outer reference::]
21\goto[outer reference::inner reference]
22\stoptyping
23
24The inner reference is normally a user defined one, for instance a reference to a
25named location like a chapter or figure. The outer reference refers to a file or
26\URL and is normally defined at the document level and is accessed by the \type
27{::}. By using symbolic names updating them becomes easier.
28
29There are also predefined references, like \type {nextpage} to go to the next
30page or \type {forward} to cycle, \type {nextcontents} for the next level table
31of contents in a linked list of such tables, etc. Some keywords are actually
32shortcuts to actions that are delegated to the viewer. Here you need to keep in
33mind that nowadays were talking of \PDF\ viewers, but originally (\MKII) we also
34supported \DVI\ viewers. A special class of references are the viewer control
35ones, like \type {CloseDocument} or \type {PreviousJump}. They can be recognized
36by their capitals.
37
38When we speak of a reference, we actually refer to a whole bunch of possible
39references. We already mentioned inner and outer references, but special actions
40are also possible. These are actually plugins. Examples are the \JAVASCRIPT\ and
41\URL\ plugins. The interface evolved a bit over a few decades but most has been
42there right from the start, which is why we keep it as is. Actually, there is not
43that much new functionality added in \MKIV, although the implementation was
44mostly rewritten. Here is a overview of the syntax, just to give you an idea.
45
46\starttyping
47\goto[inner]
48\goto[inner(foo,bar)]
49\goto[inner{argument,argument}]
50\goto[inner{argument}]
51\goto[outer::]
52\goto[outer::inner]
53\goto[outer::special(operation{argument,argument})]
54\goto[outer::special(operation)]
55\goto[outer::special()]
56\goto[outer::inner{argument}]
57\goto[special(operation{argument})]
58\goto[special(operation{argument,argument})]
59\goto[special(operation)]
60\goto[special(outer::operation)]
61\goto[special(operation)]
62\goto[special(operation(whatever))]
63\goto[special(operation{argument,argument{whatever}})]
64\goto[special(operation{argument{whatever}})]
65\stoptyping
66
67There can be multiple actions, separated by a comma, think of: go to the page
68with label \quote {foo} and start video \quote {bar}.
69
70\showsetup{goto}
71
72Examples of operations are \type {page}, \type {program}, \type {action}, \type
73{url} and \type {JS}. \footnote {There are a few more operations but not all make
74sense at the user level.} The \type {page} operation accepts a pagenumber as
75well as relevant keywords. One can prefix a pagenumber by a file or \URL\ tag.
76The \type {program} operation starts up a program. It is an example of an old
77feature that has proven to be unstable, simply because viewers change behaviour
78over time.
79
80\showsetup{definereference}
81
82The builtin actions are interfaces via shortcuts with camelcase names. In most
83cases the name is a good indication of what to expect:
84
85\starttyping
86\definereference [CloseDocument] [action(close)]
87\definereference [ExitViewer] [action(exit)]
88\definereference [FirstPage] [action(first)]
89\definereference [LastPage] [action(last)]
90\definereference [NextJump] [action(forward)]
91\definereference [NextPage] [action(next)]
92\definereference [PauseMovie] [action(pausemovie)]
93\definereference [PauseSound] [action(pausesound)]
94\definereference [PauseRendering] [action(pauserendering)]
95\definereference [PreviousJump] [action(backward)]
96\definereference [PreviousPage] [action(previous)]
97\definereference [PrintDocument] [action(print)]
98\definereference [SaveForm] [action(exportform)]
99\definereference [LoadForm] [action(importform)]
100\definereference [ResetForm] [action(resetform)]
101\definereference [ResumeMovie] [action(resumemovie)]
102\definereference [ResumeSound] [action(resumesound)]
103\definereference [ResumeRendering] [action(resumerendering)]
104\definereference [SaveDocument] [action(save)]
105\definereference [SaveNamedDocument][action(savenamed)]
106\definereference [OpenNamedDocument][action(opennamed)]
107\definereference [SearchDocument] [action(search)]
108\definereference [SearchAgain] [action(searchagain)]
109\definereference [StartMovie] [action(startmovie)]
110\definereference [StartSound] [action(startsound)]
111\definereference [StartRendering] [action(startrendering)]
112\definereference [StopMovie] [action(stopmovie)]
113\definereference [StopSound] [action(stopsound)]
114\definereference [StopRendering] [action(stoprendering)]
115\definereference [SubmitForm] [action(submitform)]
116\definereference [ToggleViewer] [action(toggle)]
117\definereference [ViewerHelp] [action(help)]
118\definereference [HideField] [action(hide)]
119\definereference [ShowField] [action(show)]
120\definereference [GotoPage] [action(gotopage)]
121\definereference [Query] [action(query)]
122\definereference [QueryAgain] [action(queryagain)]
123\definereference [FitWidth] [action(fitwidth)]
124\definereference [FitHeight] [action(fitheight)]
125\definereference [ShowThumbs] [action(thumbnails)]
126\definereference [ShowBookmarks] [action(bookmarks)]
127\definereference [HideLayer] [action(hidelayer)]
128\definereference [VideLayer] [action(videlayer)]
129\definereference [ToggleLayer] [action(togglelayer)]
130\stoptyping
131
132In the \type {javaimp*.mkiv} files you will find examples of similar shortcuts,
133for instance:
134
135\starttyping
136\definereference [SetupStepper] [JS(SetupStepper{step,50})]
137\definereference [ResetStepper] [JS(ResetStepper)]
138\definereference [CheckStepper] [JS(CheckStepper{\StepCounter})]
139\definereference [InvokeStepper] [JS(InvokeStepper)]
140\stoptyping
141
142Other examples of redefined references are:
143
144\starttyping
145\definereference [firstpage] [page(firstpage)]
146\definereference [previouspage] [page(previouspage)]
147\definereference [nextpage] [page(nextpage)]
148\definereference [lastpage] [page(lastpage)]
149\definereference [forward] [page(forward)]
150\definereference [backward] [page(backward)]
151\definereference [firstsubpage] [page(firstsubpage)]
152\definereference [previoussubpage] [page(previoussubpage)]
153\definereference [nextsubpage] [page(nextsubpage)]
154\definereference [lastsubpage] [page(lastsubpage)]
155\stoptyping
156
157Some of these actions expect arguments, for instance:
158
159\starttyping
160\goto{start}[StartMovie{mymovie}]
161\stoptyping
162
163You can load the module \type {referencesidentify} which gives you
164a command:
165
166\startbuffer
167\showreference[page(123),StartMovie{mymovie}]
168\stopbuffer
169
170\typebuffer \getbuffer
171
172\startbuffer
173\showreference[JS(ForgetChanges),CloseDocument]
174\stopbuffer
175
176\typebuffer \getbuffer
177
178\startbuffer
179\showreference[manual::contents]
180\stopbuffer
181
182\typebuffer \getbuffer
183
184You should be careful with colons in references. This gives you an idea how
185\CONTEXT\ interprets what you requested.
186
187\starttabulate[Tp]
188\NC prefix:whatever \NC The \type {prefix} creates a namespace. When references are
189 resolved and there is no hit a lookup without prefix
190 takes place. \NC \NR
191\NC document::whatever \NC The \type {document} is a symbolic reference to an external
192 resource. This is explained elsewhere. \NC \NR
193\NC component:::whatever \NC The \type {component} is a symbolic reference to a component in
194 a product. References defined in such a component are loaded on
195 demand. \NC \NR
196\stoptabulate
197
198
199
200
201
202\stopchapter
203
204\stopcomponent
205 |