Difference between revisions of "Interaction"

From Wiki
Jump to navigation Jump to search
m (minor adjustments, nothing new)
(Added information on expansion of XML information for bookmarks)
(15 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
+
__TOC__
 
 
* [[Presentation effects]] and [[Presentations]]
 
* see in [[Using Graphics| using graphics]] how to use movies.
 
* [[Widgets]] (interactive elements, form fields etc.) and [[Interaction and button]]
 
 
 
  
 
The {{cmd|setupinteraction}} command configures all interaction in the resulting PDF document. Basic interaction (meaning clickable links for references) is enabled using
 
The {{cmd|setupinteraction}} command configures all interaction in the resulting PDF document. Basic interaction (meaning clickable links for references) is enabled using
Line 12: Line 7:
 
</texcode>
 
</texcode>
  
This makes all links generated with the {{cmd|goto}} command (and indirectly the {{cmd|in}} and {{cmd|at}} commands) clickable.
+
This makes all links generated with the {{cmd|goto}} command (and indirectly the {{cmd|in}} and {{cmd|at}} commands) clickable. A page is dedicated to this system of '''[[References]]'''.
  
 
= Link coloring =
 
= Link coloring =
Line 45: Line 40:
 
</texcode>
 
</texcode>
  
= PDF Bookmarks and Headers =
+
= PDF Bookmarks =
 +
 
 +
== Quick start ==
 +
 
 +
For the impatient (like me), here is a complete example showing typical and useful commands, which are explained below:
 +
 
 +
<texcode>
 +
\setupinteraction[state=start] % don't forget this line!
 +
% make chapter, section bookmarks visible when opening document
 +
\placebookmarks[chapter,section,subsection][chapter,section]
 +
\setupinteractionscreen[option=bookmark]
 +
\starttext
 +
\startchapter[title=The beginning]
 +
Hi!
 +
\stopchapter
 +
\startchapter[title={A very, very\\long title}]
 +
Greetings!
 +
\startsection[title=Why so long]
 +
I don't know
 +
\startsubsection[title=Why not?]
 +
Good point.
 +
\stopsubsection
 +
\stopsection
 +
\stopchapter
 +
\startchapter[title=The never-ending story]
 +
Oh no.
 +
\stopchapter
 +
\startchapter[title=The never-ending story,
 +
                    bookmark=Forever!]
 +
Oh no.
 +
\stopchapter
 +
\stoptext
 +
</texcode>
 +
 
 +
== Explanation ==
 +
 
 +
You need to activate the interaction handling in order to see the bookmarks using {{cmd|setupinteraction|[state=start]}}.
 +
 
 +
<texcode>
 +
\setupinteraction
 +
  [state=start]
 +
</texcode>
 +
 
 +
The bookmarks window is usually not visible by default. To have the bookmark window open automatically when the document is opened:
 +
 
 +
<texcode>
 +
\setupinteractionscreen
 +
  [option=bookmark]
 +
</texcode>
 +
 
 +
''Disclaimer:'' {{cmd|setupinteraction}} works with Adobe Reader/Acrobat, but other PDF viewers behave differently. E.g. xpdf v3.01 always opens the bookmark window.
  
Refer to the dedicated [[PDF Bookmarks and Headers]] page.
+
To get bookmarks for chapters, sections, and subsections, use:
 +
 
 +
<texcode>
 +
\placebookmarks[chapter,section,subsection]
 +
</texcode>
  
 +
In the bookmark window, only chapter bookmarks are visible by default.
 +
If chapter and section bookmarks should be visible:
  
 +
<texcode>
 +
\placebookmarks
 +
  [chapter,section,subsection]
 +
  [chapter]
 +
</texcode>
 +
 +
This will open the document with the bookmarks for chapters and sections visible (read as: and open up the chapter bookmarks)
 +
 +
The [[Titles|unnumbered headings]] ({{cmd|title}}, {{cmd|subject}} etc.) do '''not''' create bookmarks, even when listed in {{cmd|placebookmarks}}.
 +
 +
In order to create the bookmarks, you need to add <code>force=yes</code>, for example like this:
 +
 +
<texcode>
 +
\placebookmarks
 +
  [title, subject]
 +
  [force=yes]
 +
</texcode>
 +
 +
If you do not like seeing the structure numbering in the bookmarks, you can add <code>number=no</code>, like this:
 +
 +
<texcode>
 +
\placebookmarks
 +
  [chapter,section]
 +
  [chapter]
 +
  [number=no]
 +
</texcode>
 +
 +
== Unwanted output ==
 +
 +
With a long heading in a huge font, you might want to add linebreaks by hand.  No problem, just use <tt>\\</tt>.  The bookmark code ignores <tt>\\</tt>, so the bookmark itself won't have a linebreak.
 +
For example:
 +
 +
<texcode>
 +
\setupinteraction[state=start]
 +
\placebookmarks[chapter]
 +
\setupinteractionscreen[option=bookmark]
 +
\starttext
 +
\startchapter[title=Long\\ title]
 +
hello
 +
\stopchapter
 +
\stoptext
 +
</texcode>
 +
 +
ConTeXt attempts to replace commands inside bookmarks with an acceptable string. However, the result is not always optimal. To tweak ConTeXts behaviour, add specific commands to {{cmd|simplifiedcommands}}.
 +
 +
For example, to replace the <code>\CONTEXT</code> logo (which would normally become ''CONTEXT'') with a camel-cased version, use the following:
 +
 +
<texcode>
 +
\appendtoks
 +
    \def\CONTEXT{ConTeXt}
 +
\to \simplifiedcommands
 +
</texcode>
 +
 +
A more general method, also usable for the above problem, is to use the <code>bookmark</code> option to specify the bookmark text explicitly.  For example:
 +
 +
<texcode>
 +
\setupinteraction[state=start]
 +
\placebookmarks[chapter]
 +
\setupinteractionscreen[option=bookmark]
 +
\starttext
 +
\startchapter[title=A very long chapter\\ about splines,
 +
                    bookmark=Splines]
 +
hello
 +
\stopchapter
 +
\stoptext
 +
</texcode>
 +
 +
{{mkii|In mkii, such manual bookmarks used the {{cmd|bookmark}} command on a separate line following a {{cmd|chapter}} command. With the new {{cmd|startchapter}} command, this is no longer needed, nor recommended.}}
 +
 +
== Private bookmarks ==
 +
 +
We can also place our own list of bookmarks:
 +
 +
<texcode>
 +
\setupinteraction
 +
  [state=start]
 +
\setupinteractionscreen
 +
  [option=bookmark]
 +
\definelist
 +
  [mylist]
 +
\placebookmarks
 +
  [chapter,mylist]
 +
  [chapter,mylist]
 +
\starttext
 +
    \startchapter[title={My title}]
 +
        \input knuth\page 
 +
        \bookmark[mylist]{Before input zapf}\input zapf
 +
    \stopchapter
 +
\stoptext
 +
</texcode>
 +
 +
== XML source ==
 +
 +
When processing XML input file information in TUC file is stored as the XML command with the reference to XML node
 +
 +
<texcode>
 +
["titledata"]={
 +
  ["label"]="section",
 +
  ["title"]="\\xmlatt {xml:name::4}{title}"
 +
</texcode>
 +
 +
You have to expand the information to get the text in TUC file and subsequently in bookmarks by modifying sections:
 +
 +
<texcode>
 +
\setuphead
 +
    [section]
 +
    [expansion=yes]
 +
</texcode>
 +
 +
 +
= PDF Headers =
 +
 +
In order to add '''Author''', '''Title''', '''Keywords''', ... to PDF headers, use:
 +
 +
<texcode>
 +
\setupinteraction
 +
  [state=start,
 +
    title={...},
 +
    author={...},
 +
    subtitle={...},
 +
    keyword={...}]
 +
</texcode>
 +
 +
== Prevent certain characters from appearing in pdf headers ==
 +
 +
To ignore certain TeX commands in {{cmd|setupinteraction}} add them to {{cmd|simplifiedcommands}}. For example, to ignore {{cmd|quad}} in <code>pdfauthor</code>, use the following
 +
 +
<texcode>
 +
\appendtoks
 +
    \let\quad\space
 +
\to \simplifiedcommands
 +
 +
\setupinteraction
 +
    [author={Author1\quad Author2}]
 +
</texcode>
 +
 +
{{mkii|Accented characters like ''ä'', ''č'', ... will turn into their unaccented counterparts ''a'', ''c'', ... by default. If you want to prevent that, use
 +
 +
<texcode>
 +
\input spec-tst
 +
</texcode>
 +
 +
For example
 +
 +
<texcode>
 +
\enableregime[utf]
 +
 +
\setupinteraction
 +
  [state=start]
 +
\setupinteractionscreen
 +
  [option=bookmark]
 +
 +
% before \placebookmarks
 +
\input spec-tst.tex
 +
 +
\placebookmarks
 +
  [chapter,section,subsection]
 +
  [chapter]
 +
 +
... and here is your document with accented characters in titles & bookmarks ...
 +
 +
</texcode>}}
 +
 +
 +
= Further reading =
 +
 +
* [[URL]]: typesetting of URLs references.
 +
* [[Presentations]], [[Presentation Styles]], [[SlideWithSteps]],  [[Presentation effects]]
 +
* [[Widgets]] (interactive elements, form fields etc.) and [[Interaction and button]]
 +
* See in [[Using Graphics| using graphics]] how to use movies.
  
[[Category:Presentation]]
+
[[Category:Interaction]]
[[Category:Command/Interaction|Interaction]]
 

Revision as of 14:29, 7 October 2020

The \setupinteraction command configures all interaction in the resulting PDF document. Basic interaction (meaning clickable links for references) is enabled using

\setupinteraction[state=start]

This makes all links generated with the \goto command (and indirectly the \in and \at commands) clickable. A page is dedicated to this system of References.

Link coloring

By default, the link text gets a green or red color, depending on whether the link is to another page or to the same page. You can change the link colors with the color (links to other pages) and contrastcolor (links to the same page) properties. For example, to disable link coloring alltogether:

\setupinteraction[state=start,color=,contrastcolor=]

Clickable table of contents

To make table of contents items clickable, use the \setupcombinedlist command.

\setupcombinedlist[content][interaction=all]

This makes the entire table of contents line clickable. It is possible to select just one part (sectionnumber, pagenumber, text).

If links have a color, this will also make the table of contents get a different text color. You can use the color property to change it back, e.g.:

\setupcombinedlist[content][interaction=all,color=black]

Alternatively, you can use the textcolor property to change just the text colour, and leave the section and page numbers colored.

Default focus mode

By default, clicking an inter-document hyperlink will switch to "fit page" mode, to override this:

\setupinteraction[state=start,focus=standard]

PDF Bookmarks

Quick start

For the impatient (like me), here is a complete example showing typical and useful commands, which are explained below:

\setupinteraction[state=start] % don't forget this line!
% make chapter, section bookmarks visible when opening document
\placebookmarks[chapter,section,subsection][chapter,section]
\setupinteractionscreen[option=bookmark]
\starttext
\startchapter[title=The beginning]
Hi!
\stopchapter
\startchapter[title={A very, very\\long title}]
Greetings!
\startsection[title=Why so long]
I don't know
\startsubsection[title=Why not?]
Good point.
\stopsubsection
\stopsection
\stopchapter
\startchapter[title=The never-ending story]
Oh no.
\stopchapter
\startchapter[title=The never-ending story,
                    bookmark=Forever!]
Oh no.
\stopchapter
\stoptext

Explanation

You need to activate the interaction handling in order to see the bookmarks using \setupinteraction.

\setupinteraction
  [state=start]

The bookmarks window is usually not visible by default. To have the bookmark window open automatically when the document is opened:

\setupinteractionscreen
   [option=bookmark] 

Disclaimer: \setupinteraction works with Adobe Reader/Acrobat, but other PDF viewers behave differently. E.g. xpdf v3.01 always opens the bookmark window.

To get bookmarks for chapters, sections, and subsections, use:

\placebookmarks[chapter,section,subsection]

In the bookmark window, only chapter bookmarks are visible by default. If chapter and section bookmarks should be visible:

\placebookmarks
   [chapter,section,subsection]
   [chapter]

This will open the document with the bookmarks for chapters and sections visible (read as: and open up the chapter bookmarks)

The unnumbered headings (\title, \subject etc.) do not create bookmarks, even when listed in \placebookmarks.

In order to create the bookmarks, you need to add force=yes, for example like this:

\placebookmarks
  [title, subject]
  [force=yes]

If you do not like seeing the structure numbering in the bookmarks, you can add number=no, like this:

\placebookmarks
  [chapter,section]
  [chapter]
  [number=no]

Unwanted output

With a long heading in a huge font, you might want to add linebreaks by hand. No problem, just use \\. The bookmark code ignores \\, so the bookmark itself won't have a linebreak. For example:

\setupinteraction[state=start]
\placebookmarks[chapter]
\setupinteractionscreen[option=bookmark]
\starttext
\startchapter[title=Long\\ title]
hello
\stopchapter
\stoptext

ConTeXt attempts to replace commands inside bookmarks with an acceptable string. However, the result is not always optimal. To tweak ConTeXts behaviour, add specific commands to \simplifiedcommands.

For example, to replace the \CONTEXT logo (which would normally become CONTEXT) with a camel-cased version, use the following:

 \appendtoks
     \def\CONTEXT{ConTeXt}
 \to \simplifiedcommands

A more general method, also usable for the above problem, is to use the bookmark option to specify the bookmark text explicitly. For example:

\setupinteraction[state=start]
\placebookmarks[chapter]
\setupinteractionscreen[option=bookmark]
\starttext
\startchapter[title=A very long chapter\\ about splines,
                     bookmark=Splines]
hello
\stopchapter
\stoptext
ConTeXt Mkii (deprecated) notes (See: Mkii):
In mkii, such manual bookmarks used the \bookmark command on a separate line following a \chapter command. With the new \startchapter command, this is no longer needed, nor recommended.


Private bookmarks

We can also place our own list of bookmarks:

\setupinteraction
  [state=start]
\setupinteractionscreen
  [option=bookmark]
\definelist
  [mylist]
\placebookmarks
  [chapter,mylist]
  [chapter,mylist]
\starttext
    \startchapter[title={My title}]
        \input knuth\page   
        \bookmark[mylist]{Before input zapf}\input zapf
    \stopchapter
\stoptext

XML source

When processing XML input file information in TUC file is stored as the XML command with the reference to XML node

["titledata"]={
   ["label"]="section",
   ["title"]="\\xmlatt {xml:name::4}{title}"

You have to expand the information to get the text in TUC file and subsequently in bookmarks by modifying sections:

\setuphead
    [section]
    [expansion=yes]


PDF Headers

In order to add Author, Title, Keywords, ... to PDF headers, use:

\setupinteraction
   [state=start,
    title={...},
    author={...},
    subtitle={...},
    keyword={...}]

Prevent certain characters from appearing in pdf headers

To ignore certain TeX commands in \setupinteraction add them to \simplifiedcommands. For example, to ignore \quad in pdfauthor, use the following

 \appendtoks
     \let\quad\space
 \to \simplifiedcommands

\setupinteraction
    [author={Author1\quad Author2}]
ConTeXt Mkii (deprecated) notes (See: Mkii):
Accented characters like ä, č, ... will turn into their unaccented counterparts a, c, ... by default. If you want to prevent that, use
\input spec-tst

For example

\enableregime[utf]

\setupinteraction
   [state=start]
\setupinteractionscreen
   [option=bookmark]

% before \placebookmarks
\input spec-tst.tex 

\placebookmarks
   [chapter,section,subsection]
   [chapter]

... and here is your document with accented characters in titles & bookmarks ...


Further reading