% signal=squid

\startcomponent excursion-en-interactivity

%\enablemode[screen]

\enablemode[**en-us]

%\startmode[screen]
%\environment  excursion-screen
%\stopmode

\project excursion

\startchapter[title=Interactive mode in electronic documents,reference=chap:interactivity]

\startsection[title=Introduction]

\index[reader]{\READER}

Documents that are electronically available for consulting and displaying on a
computer screen are called interactive documents.

Interaction means that you can click on active areas and jump to the indicated
locations. For example if you consult a register you can click on a (active) page
number and you will jump to the corresponding page.

Interaction relates to:

\startitemize[packed]
  \startitem
    active chapter numbers in the table of content
  \stopitem
  \startitem
    active page numbers in registers
  \stopitem
  \startitem
    active page numbers, chapter numbers and figure numbers in internal
    references to pages, chapters, figures etc. in the running text
  \stopitem
  \startitem
    active titles, page numbers, and chapter numbers in external references to
    other interactive documents
  \stopitem
  \startitem
    active menus as navigation tools
  \stopitem
  \startitem
    references to webpages and programs
  \stopitem
\stopitemize

Interactivity depends on the program you use to view the interactive document.
Not all viewers have the same features.

\CONTEXT\ is a very powerful system for producing electronic or interactive \PDF\
documents. However, only a few standard features are described in this chapter.
Allmost all manuals of \CONTEXT\ are provided with the distribution, including
their sources. Reverse engineering is one of the options to become more
acquainted with the possibilities of \CONTEXT.

Good examples of interactive documents are \CONTEXT\ presentations (see
\in{chapter}[chap:presentations]).

For more complex interactive \PDF\ documents with forms you should read the \goto
{\Emph{\CONTEXT\ interaction}} [ url (manual:interaction) ] manual.

\stopsection

\startsection[title=Bookmarks]

\index{interaction+bookmark}

\Command{\tex{bookmark}}

One of the interactive options in \PDF\ documents are bookmarks. \CONTEXT\ is
capable of putting such bookmarks into the \PDF\ document. The bookmarks are
displayed in the \READER\ in a side bar and they are clickable to jump to the
respective place in the document.

For using interaction, this mode has to be activated.

\Command{\tex{setupinteraction}}

\shortsetup{setupinteraction}

A second command tells \CONTEXT\ to produce bookmarks

\Command{\tex{setupinteractionscreen}}

\shortsetup{setupinteractionscreen}

There is a command to put a bookmark at any place in a document with

\shortsetup{bookmark}

\page[bigpreference]

An example of a simple document with bookmarks could look like this.

\startbuffer[ExampledocumentA]
\setupinteraction
  [state=start]

\setupinteractionscreen
  [option=bookmark]

\definelist
  [Mylist]

\startdocument
  \placebookmarks[chapter,Mylist]

  \bookmark[Mylist]{A Bookmark used as a title at the top of the bookmarks}

  \placelist[chapter][criterium=all]

  \startchapter[title=Hasselt,reference=city:Hasselt]
    Something about the history of Hasselt
  \stopchapter
\stopbuffer

\startbuffer[ExampledocumentB]
  \startchapter
    [title=Rivers around Hasselt,reference=rivers:Hasselt]
    A description of the different rivers around Hasselt
  \stopchapter
\stopdocument
\stopbuffer

\typebuffer[ExampledocumentA]

\page[bigpreference]

\typebuffer[ExampledocumentB]

In this setup the chapter-bookmarks are generated automatically, however
bookmarks created with \type{\bookmark} need their own list which is in this case
\type{Mylist}. For placing a bookmark in the list to which it belongs must be
stated between brackets after the command. The following braces can contain any
text. \type{\placelist[chapter,Mylist]} is responsible to use the indicated list
levels and lists to produce the entries in the \PDF\ file. The
\type{\placelist[chapter][criterium=all]} places a table of contents which is in
itself also interactive.

You can copy this example to a file and compile it in order to see how this
mechanism works.

\stopsection

\startsection[title=Interactive mode]

\index{interactive mode}

For example:

\startbuffer
\setupinteraction
  [state=start,
   color=blue,
   style=bold]
\stopbuffer

\typebuffer

The hyper links are now generated automatically and the active words are
displayed in bold blue.

The interactive document is considerably bigger (in MB's) than its paper cousin
because hyperlinks consume space. You will also notice that processing time
becomes longer. Therefore it is advisable to deactivate the interactive mode as
long as your document is under construction.

\stopsection

\startsection[title=Interaction within a document]

\index{interaction+internal}

\Command{\tex{in}}
\Command{\tex{at}}
\Command{\tex{goto}}

Earlier you have seen how to make a reference with \type{\in} and \type{\at}. You may have wondered why you had to type \type{\in{chapter}[chap:introduction]}. In
the first place \Emph{chapter} and its corresponding chapter number will not be
separated at line breaking. In the second place the word \Emph{chapter} and its
number are typeset differently in the interactive mode. This gives the user a
larger clickable area.

\stopsection

\startsection[title=Interaction between documents]

\index{interaction+external}

\Command{\tex{from}}
\Command{\tex{useexternaldocument}}
\Command{\tex{useURL}}

It is possible to link one document to another. First you have to state that you
want to refer to another document. This is done by using the command
\type{\useexternaldocument}.

\shortsetup{useexternaldocument}

The first bracket pair must contain a logical name of the document, the second
pair the file name of the other document and the third pair is used for the title
of the document.

For referring to these other documents you can use

\shortsetup{from}

The brackets contain the reference to the external file.

Look at the example below.

\startbuffer
\useexternaldocument
   [hia][excursion-en-hasseltbook][Festivities in Hasselt]

Most tourist attractions are described in \from[hia].\crlf
A description of the \about[hia::euifeest] is found in \from[hia]. \crlf
The eui||feest is described on \at{page}[hia::euifeest] \crlf
in \from[hia].
See for more information \in{chapter}[hia::euifeest] in \from[hia].
\stopbuffer

\typebuffer

The \type{\useexternaldocument} is usually typed in the setup area of your input
file.

After processing the file \typ{excursion-en-hasseltbook.mkxl} and your input file
you will have two \PDF\ documents.

In order however to make this work it is important to remember that for linking a
file through references its \type{*.tuc} files must be present.

The references come out like this:

\start
\setupinteraction[state=start,color=blue]
\getbuffer
\stop

For more information on cross referencing look at \goto {\Emph{\CONTEXT\ Magazine
1103}} [ url (thisway:crossrefs)].

\stopsection

\startsection[title=Interaction with the world wide web]

In interactive mode there is one other command that has little meaning in the
paper version.

\shortsetup{goto}

The curly braces contain text, the brackets contain a reference (logical name or
a location).

\startbuffer
In \goto {Hasselt[url (https://www.stadindex.nl/plattegrond/hasselt)]
all streets are built in a circular way.
\stopbuffer

\typebuffer

In the interactive document \goto{Hasselt}[
url(https://www.stadindex.nl/plattegrond/hasselt) ] will be blue and active. When
you click the text you will jump to a map of Hasselt.

For a consistent definition of the urls there is the command

\shortsetup{useURL}

\page[bigpreference]

The address is defined with

\startbuffer
\useURL
  [loc:cityplan]                      % id / logical name
  [https:// ... /plattegrond/hasselt] % web address
  []                                  % document
  []                                  % text
\stopbuffer

\typebuffer

The web-address is recalled by its logical name

\type{\goto {Hasselt} [ url(loc:cityplan) ]}.

It is of good practice to define and maintain the urls either in the setup area
of the document or in a separate file.

\stopsection

\startsection[title=buttons]

\index{interaction+button}

The command to define a button is

\shortsetup{button}

The first bracket pair contains the setup keys, the curly braces contain the
button text and the last bracket pair the destination.

\startbuffer
\button
  [height=8mm,width=35mm,
   background=color,backgroundcolor=blue,
   foregroundcolor=white]
   {Website Hasselt} [ url(https://www.hasselt.nl) ]
\button
  [height=8mm,
   foregroundcolor=blue]
  {MSWord Document} [ program(hasselt.docx) ]
\stopbuffer

\typebuffer

The first example results in a jump to a webpage, the second opens the file
\type{hasselt.doc} in a programme that can open \type{*.docx} files.

\doifmodeelse {Screen} {
    \getbuffer
} {
    \blank[small]
    \externalfigure[excursion-en-buttons]
    \par
    Naturally buttons are only visible in screen documents!
}

\stopsection

\page[bigpreference]

\startsection[title=Menus]

\index{interaction+menu}

You can define a menu with

\shortsetup{startinteractionmenu}

And set it up with

\shortsetup{setupinteractionmenu}

The first bracket pair is used for the menu's name and the second pair for
setting it up.

A menu can be used in an interactive document. Below you can find a simple
example that you can copy to do some experimenting.

\startbuffer[Bookmarksetup]
\setuppapersize
  [S6][S6]

\setuplayout
  [header=0cm,topspace=.5cm,backspace=2cm,
   margindistance=.5cm,margin=1cm,rightmargin=0cm,
   edgedistance=.5cm,rightedge=2cm,width=fit,
   height=13.8cm,footer=1cm,bottom=1cm]

\setupinteraction
  [state=start,menu=on]

\setupinteractionmenu
  [bottom]
  [background=color,backgroundcolor=gray, frame=off]

\startinteractionmenu[bottom]
\hfill
\startbut [content]       contents      \stopbut \quad
\startbut [index]         index         \stopbut \quad
\startbut [PreviousJump]  last location \stopbut \quad
\startbut [NextPage]      next page     \stopbut \quad
\startbut [CloseDocument] exit          \stopbut \quad
\stopinteractionmenu
\stopbuffer

\startbuffer[Bookmarkdocument]
\startdocument

\startstandardmakeup
  \midaligned{\tfd Festivities in Hasselt}
\stopstandardmakeup

\completecontent

\startchapter[title=Introduction]
  An introduction.
\stopchapter

\startchapter[title=Kingsday]
  Something about Kingsday in Hasselt.\index{Kingsday}
\stopchapter

\startchapter[title=Hassailt]
  Something about Hassailt.\index{Hassailt}
\stopchapter

\startchapter[title=Euifeest,reference=euifeest]
  Something about the Euifeest.\index{Euifeest}
\stopchapter

\completeindex

\stopdocument
\stopbuffer

\typebuffer[Bookmarksetup]

\page[bigpreference]

\typebuffer[Bookmarkdocument]

The definition of the \type{\startinteractionmenu ... \stopinteractionmenu} will
produce a menu at the bottom of every screen. The menu buttons contain the text
\Emph{contents}, \Emph{index}, \Emph{last location}, \Emph{next page} and
\Emph{exit} with respectively the following functions: jump to the table of
contents, jump to the index, goto the last location in the document, goto next
page and close the document. The labels to obvious destinations like
\type{content} and \type{index} are predefined. Other predefined destinations are
\type{FirstPage}, \type{LastPage}, \type{NextPage} and \type{PreviousPage}.

An action like \type{CloseDocument} is necessary to make an electronic document
self contained. Other predefined actions you can use are \type{PrintDocument},
\type{SearchDocument} and \type{PreviousJump}. The meaning of these actions is
obvious.

\blank

Remember that there is also a manual \goto{\Emph{\CONTEXT\ interactivity}}[ url
(manual:interaction)].

\stopsection

\stopchapter

\stopcomponent
