1IMPRESSIVE(1)              Impressive Documentation              IMPRESSIVE(1)
2
3
4

NAME

6       Impressive - presentation tool with eye candy
7

SYNOPSIS

9       impressive [OPTIONS...] FILES...
10

DESCRIPTION

12       Impressive is a simple presentation program that displays slideshows of
13       PDF documents, image files  or  video  files.  Rendering  is  done  via
14       OpenGL, which allows for some "eye candy" effects.
15
16       A  somewhat-modern GPU (graphics processing unit) supporting OpenGL 2.0
17       or OpenGL ES 2.0 and appropriate drivers are required  to  run  Impres‐
18       sive.
19

OPTIONS

21       -a <seconds> or --auto <seconds>
22              Automatically advance to the next page after the given number of
23              seconds. Together with the -w option (described below), this can
24              be used to create automatic slideshows.
25              Note  that  this  option will not interrupt video playback: If a
26              video is longer than the interval specified with --auto, it will
27              be  played until the end, but Impressive will change to the next
28              page directly after that.
29
30       -A <X>:<Y> or --aspect <X>:<Y>
31              Specifies the display aspect ratio. Normally, Impressive assumes
32              that  the  pixel aspect ratio is 1:1 (square pixels), regardless
33              of the display resolution that has been set up. If a  resolution
34              has been selected that doesn't match the display's aspect ratio,
35              the screen will be distorted. To overcome this, this option  may
36              be  used  to manually specify the display aspect ratio, e.g. "-A
37              16:9". Note that this option has no effect if the MuPDF  backend
38              is used for rendering.
39
40       -b or --noback
41              Disables  background  rendering.  By  default,  Impressive  will
42              pre-render all pages in a separate background thread  while  the
43              presentation  runs. If this option is specified, it will instead
44              render all pages immediately on startup. This option has no  ef‐
45              fect if caching is disabled (--cache none, see below).
46
47       --background <color>
48              Sets the background color of the overview page and the page bor‐
49              der that's visible if the page's and the screen's aspect  ratios
50              don't match.
51              The  color  is specified using HTML/CSS 3-digit or 6-digit hexa‐
52              decimal RGB syntax: #f00 or #ff0000 is bright red, for  example.
53              The  leading  hash  sign (#) is optional. In addition, the words
54              black (which is also the default) and white are recognized.
55
56       -bare
57              Disables all  functionality  that  relies  on  temporary  files,
58              specifically  video  frame  extraction using MPlayer (extracting
59              video frames with FFmpeg still works), PDF  page  title  extrac‐
60              tion,  PDF  hyperlinks,  and even PDF rendering for all backends
61              except MuPDF 1.4 or newer on Unix-like operating systems.
62
63       --box-edge <pixels>
64              Sets the border size (in pixels when unzoomed) of the  highlight
65              boxes' and spotlight's smooth edges. The default value is 4 pix‐
66              els; it can be set to zero, in which case  highlight  boxes  and
67              the spotlight will have hard edges.
68
69       -B <ms> or --boxfade <ms>
70              Sets  the  duration  (in  milliseconds)  of  the  highlight  box
71              fade-in/fade-out animation. Default value: 100 ms.
72
73       -c <mode> or --cache <mode>
74              Specifies the page cache mode to use. Valid options are:
75              none
76                     Disables page caching altogether, only  the  current  and
77                     the  following  page will be kept in RAM. Jumping between
78                     pages will be very slow, because Impressive will need  to
79                     render  the  requested pages on the fly. In addition, the
80                     overview page won't be complete until every page has been
81                     shown at least once.
82              memory
83                     Caches  all  page  images  in memory. This is the fastest
84                     method, but it requires  very  large  amounts  of  memory
85                     (about 3 MiB per page at 1024x768 resolution).
86              compressed or z
87                     Caches  all  page  images  in memory as well, but in com‐
88                     pressed form. This will be a little  slower  than  memory
89                     mode,  but  on  pages with uniform backgrounds, this will
90                     easily reduce the required amount of RAM by a  factor  of
91                     20.
92              disk
93                     Like memory, but uses a temporary file rather than memory
94                     for storage. This is the default.
95              persistent
96                     Uses a permanent cache file for caching. This  file  will
97                     not  be  deleted when Impressive quits and will be reused
98                     on subsequent invocations. The default name for the cache
99                     file  is derived like the names for Info Scripts (see be‐
100                     low for an explanation), but with a .cache file name  ex‐
101                     tension  instead  of  .info.  This method is a little bit
102                     slower than disk mode, but the time span until the  over‐
103                     view  page  is  fully populated will be significantly de‐
104                     creased if Impressive is ran again with  the  same  input
105                     files and options.
106              The mode name may be abbreviated at will, down to one character.
107              Thus, --cache persistent, -c persist and even -cp are  all  syn‐
108              onyms.
109
110       -C <filename>[:<X>,<Y>] or --cursor <filename>[:<X>,<Y>]
111              This  option  can be used to specify an image that shall be used
112              as a (software) mouse cursor instead of  the  normal  (hardware)
113              one.  It  can  either  be  a  name of an image file (typically a
114              transparent .png) or one of the special  values  "-"  (dash)  or
115              "default",  both  of  which  select  a built-in cursor image. On
116              platforms that do not support a hardware  cursor,  this  default
117              cursor  will  also  be  used  as a default if this option is not
118              used.
119              If the name of an external file is specified,  the  position  of
120              the  hotspot (the pixel inside the cursor where the actual mouse
121              position is located) can be  specified  as  well,  for  example:
122              --cursor mycursor.png:2,4.
123
124       --clock
125              If  this  option  is enabled, the current time will be shown in‐
126              stead of the elapsed time if time display is activated (with the
127              T key in the default control configuration). Compatible with the
128              -M option.
129
130       --control-help
131              This option will output a short help screen of how  the  control
132              configuration  (keyboard  and mouse bindings) work, along with a
133              list of all recognized events and actions and a dump of the cur‐
134              rent  bindings  (which  is the default configuration if no other
135              -e/--bind or -E/--controls options precede this  option).  After
136              that, Impressive will exit; no presentation will be started.
137
138       -d <time> or --duration <time>
139              Specifies  the  expected  run time of the presentation. The time
140              parameter can be either a number of seconds or a  human-readable
141              time  like 1:23 (1 minute and 23 seconds), 4:56h (4 hours and 56
142              minutes), 3m45s (3 minutes and 45 seconds), 5m  (5  minutes)  or
143              1:23:45 (1 hour, 23 minutes and 45 seconds).
144              If  an  expected  duration  is specified, Impressive will show a
145              semi-transparent green progress bar at the bottom  edge  of  the
146              screen, indicating how much time has already passed. If the time
147              is up, the bar will occupy the whole edge and fade to yellow (at
148              125% of the expected time) to red (at 150% or more).
149
150       -D <ms> or --mousedelay <ms>
151              Sets  the time (in milliseconds) the mouse cursor is shown if it
152              is not moved. There are two special values: 0 (zero)  shows  the
153              mouse  cursor  permanently, 1 (one) hides it completely. The de‐
154              fault value is 3000 ms if Impressive is  started  in  fullscreen
155              mode, and 0 (i.e. don't hide) if started in windowed mode.
156
157       --darkness <percentage>
158              Specifies  how  much  the  screen shall become darker when using
159              highlight boxes or spotlight mode. The  value  is  specified  in
160              percent,  with  25 being the default. A value of zero would mean
161              no darkening at all (the screen would just be blurred  slightly,
162              and  desaturated  if  the  graphics hardware supports it), and a
163              value of 100 would make everything but the highlighted parts  of
164              the screen black.
165
166       -e <bindings> or --bind <bindings>
167              Configures keyboard or mouse bindings. For the syntax of the ar‐
168              gument, refer to the Control Configuration section of  the  man‐
169              ual.
170
171       -E <filename> or --controls <filename>
172              Loads  a configuration file for keyboard and mouse bindings. For
173              the syntax of these files, refer to  the  Control  Configuration
174              section of the manual.
175
176       --evtest
177              If  this option is specified, Impressive will not start a normal
178              presentation, but instead enter the so-called "Event Test  Mode"
179              after the display has been initialized. In this mode, Impressive
180              will simply capture all keyboard and mouse  events  and  display
181              the  name  of  the last event on the screen. In addition, events
182              will be logged to standard output. This mode helps  with  deter‐
183              mining  the event names for each key when creating a custom con‐
184              trol configuration (see the Control Configuration section).
185
186       -f
187              Sets the window/fullscreen mode Impressive shall start up  with.
188              This  option  can  be specified multiple times; each times it is
189              found, the next of the three options is selected, in the follow‐
190              ing order: (1.)True fullscreen mode, including setting the video
191              mode. This is the default mode. (2.)Windowed mode, where Impres‐
192              sive  runs  in  a  standard  window. (3.)"Fake-fullscreen" mode,
193              where fullscreen is emulated by using a  window  without  border
194              that  fills  the whole screen. Setting the display resolution is
195              not possible in this mode. Each of these modes has a correspond‐
196              ing  long  option that enables it directly (--fullscreen, --win‐
197              dowed and --fake-fullscreen).
198
199       --fullscreen
200              Starts Impressive in fullscreen mode (the default). See the dis‐
201              cussion of the -f option for details.
202
203       --fake-fullscreen
204              Starts  Impressive in "fake fullscreen" mode. See the discussion
205              of the -f option for details.
206
207       -F <file> or --font <file>
208              Impressive uses some kind of text OSD  to  overlay  the  current
209              page  number and title (if available) on the overview page. This
210              option can be used to specify a TrueType font file (.ttf) to use
211              for  the  OSD. If the path specified doesn't directly point to a
212              useable font file, Impressive will try to search the system font
213              directories.   It  assumes that all fonts are stored below /usr/
214              share/fonts, /usr/local/share/fonts or /usr/X11R6/lib/X11/fonts/
215              TTF for this purpose (the latter one is useful for Mac OS X sys‐
216              tems specifically). If this option is not specified, any of  De‐
217              jaVuSans.ttf  or  Vera.ttf  (the  typical file name of Bitstream
218              Vera Sans) will be used as a default.
219
220       -g        <width>x<height>[+<posX>+<posY>]        or         --geometry
221       <width>x<height>[+<posX>+<posY>]
222              Sets the screen size or resolution Impressive shall use (in pix‐
223              els).  If xrandr is  installed,  the  default  screen  size  for
224              fullscreen mode is the current screen resolution; on other plat‐
225              forms, Impressive uses the highest resolution available  to  the
226              graphics  system. If a standard resolution cannot be determined,
227              the default is 1024x768 pixels. This is  also  the  default  for
228              windowed mode.
229              Furthermore,  if  the  additional  parameters  posX and posY are
230              present, they specify the position of the upper-left  corner  of
231              the  window  (relative to the upper-left corner of the desktop),
232              in pixels, for windowed and fake-fullscreen mode. The values are
233              ignored in "true" fullscreen mode.
234
235       -G <gamma>[:<blacklevel>] or --gamma <gamma>[:<blacklevel>]
236              Sets  up the startup gamma and (optional) black level value. The
237              black level is the original image's  intensity  level  (0...254)
238              that  is to be mapped to black in Impressive's output. Note that
239              gamma and black level adjustments may  be  unavailable  or  con‐
240              strained on some systems.
241
242       -h or --help
243              If  this  option is specified, Impressive writes a short command
244              line help screen to standard output and does not start a presen‐
245              tation.
246
247       -H or --half-screen
248              This option makes Impressive show the overview page and OSD ele‐
249              ments on the right half of the screen only.  The  overview  page
250              will  only  show  the  left  half of the slides as previews. The
251              box-zoom boxes will also be shown on  the  left  half.  Using  a
252              multi-monitor  setup  with  a  wide virtual screen and specially
253              crafted slides (e.g. those that can be  generated  with  LaTeX's
254              beamer  class), this makes it possible to have presenter's notes
255              on the second screen.
256              Note that transitions and animations are still operating on  the
257              whole screen, making some of them (like PagePeel) look ugly. Im‐
258              pressive  also  disables  the   overview   zoom   animation   in
259              half-screen  mode; it can be re-enabled by explicitly setting it
260              to another value with a later command line option (--zoomtime).
261              Another limitation is that the allocation of the  screen  halves
262              (slides left, overview right) is fixed.
263
264       -i <page> or --initialpage <page>
265              Specifies  the page number to start with. The default value is 1
266              (start with the first page). If another value is specified,  the
267              page  shown  by Impressive right after initialization is not the
268              first one of the PDF or image list. Additionally,  pre-rendering
269              (if enabled) will also start at the specified page.
270
271       -I <filename> or --script <filename>
272              Overrides  automatic  derivation of the info script filename and
273              specifies a script file directly.
274
275       --invert
276              This option makes Impressive invert the  colors  of  each  page,
277              turning  black  to  white and vice-versa. Note that it is a full
278              RGB inversion, so it will, for example, turn dark green to light
279              purple (and vice-versa) too.
280
281       -k or --auto-progress
282              This  option  makes  Impressive show a progress bar, visualizing
283              the timeout on pages that have one (either specified as  a  page
284              property  or  using  the --auto command-line option). Nothing is
285              done on pages that don't have a timeout.
286              If the --duration or --page-progress bars are enabled  too,  the
287              --auto-progress  bar  is  shown on the top of the screen; other‐
288              wise, it's shown on the bottom.
289
290       -l or --listtrans
291              If this option is specified, Impressive writes  a  list  of  all
292              available  transition  classes  to  standard output and does not
293              start a presentation. Transitions that are  enabled  by  default
294              are marked with a star (*) left of the class name.
295
296       -L <spec> or --layout <spec>
297              Specifies  the OSD layout. Read below for an explanation of this
298              option.
299
300       --maxzoom <factor>
301              The maximum zoom factor up to which Impressive shall attempt  to
302              render  a high-resolution image of the page when zoomed in. This
303              can be any real number larger than or equal to 1.0; the  default
304              is  5.0.  A  setting  of 1.0 causes Impressive to never render a
305              high-resolution image for zooming; in this case,  the  zoom  and
306              box-zoom  modes  will upscale the image, but not enhance any de‐
307              tails.
308              Note that regardless of this setting, Impressive  always  checks
309              the  graphics  hardware capabilities (in particular, the maximum
310              supported texture size) and may reduce the  effective  value  of
311              --maxzoom if the hardware supports less than what has been spec‐
312              ified.
313
314       --min-box-size <pixels>
315              This option sets the minimum size of a highlight box, in pixels.
316              Boxes  that  are not this many pixels wide and high are rejected
317              in order to prevent accidental creation of highlight boxes.  The
318              default value for this is 30 pixels.
319
320       -M or --minutes
321              If  this option is set, Impressive will show the on-screen timer
322              (activated with the T key) only with 1 minute resolution. By de‐
323              fault, it will show a timer with 1 second resolution.
324
325       --noblur
326              By default, Impressive uses a fragment shader to blur and desat‐
327              urate the image when in highlight box or spotlight mode. This is
328              usually  the faster and nicer-looking method; however, some very
329              old hardware implementations can't deal  with  that  shader  and
330              fall  back  to an unusably slow software implementation. Impres‐
331              sive tries to detect scenarios where this would happen and auto‐
332              matically falls back to a different implementation.
333              There might be situations where this mechanism fails and Impres‐
334              sive tries to use the non-functional  shader  anyway.  In  these
335              cases,  the  --noblur option can be used to enforce the fallback
336              implementation.
337
338       -N or --nocursor
339              This option disables any display of a mouse cursor, i.e. neither
340              the  system ("hardware") not bitmap ("software") cursor is shown
341              at any time. It it equivalent to setting --mousedelay to 1. This
342              is mainly useful for automated presentations, where no mouse in‐
343              teraction is needed.
344
345       --noclicks
346              If this option is enabled, switching to  the  previous  or  next
347              page  with  the left and right mouse buttons is deactivated. The
348              keyboard shortcuts are unaffected from this.
349              Note that this option only works as intended  when  the  default
350              controls  are  used.  If  the -e/--bind or -E/--controls options
351              have been used, --noclicks might not have the intended effect.
352
353       --nologo
354              This option disables the Impressive logo and version number dis‐
355              play.  Instead,  the  loading  screen  will be just black or, if
356              background rendering is disabled, only the progress bar will  be
357              visible.
358
359       --nooverview
360              This  option disables the overview page. Overview thumbnails are
361              not created, and the Tab that normally enters overview  mode  is
362              ignored. (More precisely, the overview-enter action is ignored.)
363
364       --noquit
365              This  option  disables  the  keyboard shortcuts (Q and Esc) that
366              could normally quit Impressive with a single keypress. If it  is
367              used,  the  only  way to exit the program is the key combination
368              Alt+F4, and accidental quitting is no longer possible.
369              Note that this option only works properly if  the  default  con‐
370              trols  are  used. If the -e/--bind or -E/--controls options have
371              been used, --noquit might not have the intended effect.
372
373       -o <directory> or --output <directory>
374              Do not display the presentation, but render it into a series  of
375              PNG  image files inside the specified directory. The images will
376              be generated in the current resolution as specified  by  the  -g
377              option. This option is useful if the presentation is to be given
378              on on a foreign PC with an old, broken or otherwise  problematic
379              MuPDF/Xpdf/GhostScript installation: By generating images of the
380              PDF pages, is is made sure that no rendering bugs will happen on
381              the target system.
382
383       -O <mode> or --autooverview <mode>
384              Enables or disables automatic derivation of whether a page shall
385              or shall not be shown on the  overview  page.  This  feature  is
386              based  on the fact that some LaTeX presentation packages tag all
387              pages with a title (that can be read by Impressive with the help
388              of pdftk), except those that contain multiple reveal steps.
389              The following modes are available:
390              off
391                     Disables automatic overview mode. All pages will be shown
392                     on the overview page by default. This is also the default
393                     setting.
394              first
395                     All  pages with a PDF title will be shown on the overview
396                     page. The  purpose  is  to  show  the  initial  state  of
397                     multi-step slides on the overview page.
398              last
399                     All pages before a page with a PDF title will be shown on
400                     the overview page. The purpose is to show the final state
401                     of multi-step slides on the overview page.
402              Again,  the  mode  may  be  abbreviated arbitrarily, down to one
403              character, just like with the -c option above..
404
405       --overtime <ms>
406              Sets  the  duration  (in  milliseconds)  of  the  overview  page
407              zoom-in/zoom-out effects, without affecting the zoom or box-zoom
408              animation time. Default value: 250 ms.
409
410       -p <start>-<end> or --pages <start>-<end>
411              Using this option, the range of the page displayed can  be  nar‐
412              rowed down. The presentation will start at the first page in the
413              range. All pages outside of the range will not be shown  on  the
414              overview  page  and will not be cached. However, they can be en‐
415              tered manually when cycling through the presentation. Due to the
416              fact  that  these pages are uncached, preparation of the display
417              will take considerably longer.
418
419       -P <path> or --gspath <path>
420              This option can be used to override the Xpdf / GhostScript  path
421              autodetection.  The full path to the executable of either Ghost‐
422              Script (gs or gs.exe) or Xpdf's pdftoppm utility must be  speci‐
423              fied.
424
425       -q or --page-progress
426              If  this  option  is  enabled, Impressive will show a light-blue
427              semi-transparent progress bar at the bottom edge of  the  screen
428              that  shows the position inside the presentation, i.e. the rela‐
429              tion between the current page number and  the  total  number  of
430              pages.
431              If   the   -d/--duration   progress  bar  is  enabled  too,  the
432              --page-progress bar will be stacked above that.
433
434       --progress-last <number>
435              This option  sets  the  page  number  at  which  the  slide  the
436              --page-progress  progress  bar should end. This can be useful to
437              ignore backup slides.
438              This option does not have any effect  if  -q/--page-progress  is
439              not used.
440
441       -Q or --autoquit
442              If this option is specified, Impressive quits automatically when
443              trying to navigate to the page after the last page or  the  page
444              before the first page.
445              This option does not have any effect if --wrap is used.
446
447       -r <n> or --rotate <n>
448              Display all pages rotated by nx90 degrees clockwise. Try -r 1 or
449              -r 3 if there are problems with PDFs generated by LaTeX on  some
450              Xpdf or GhostScript versions.
451
452       -s or --scale (image input only)
453              If  a  directory  with  image files is used as input, Impressive
454              will scale down images that are too big for the screen.  But  by
455              default,  it will not scale up smaller images to fit the screen;
456              it will leave a black border instead. This option overrides this
457              setting and enables upscaling of smaller images.
458
459       -s or --supersample (PDF input only)
460              This  switch enables antialiasing by 4x supersampling instead of
461              the normal multisampling method used  by  Xpdf  or  GhostScript.
462              While this usually degrades both visual quality and performance,
463              it may be necessary for circumventing white strips or moire-like
464              patterns in gradients.
465
466       -S <pixels> or --fontsize <pixels>
467              This  option  sets the size, in pixels, of the OSD font. The de‐
468              fault value is 14.
469
470       --spot-radius <pixels>
471              This option sets the initial radius of the spotlight, in pixels.
472              The default value is 64.
473
474       --time-display
475              This option enables display of the elapsed presentation time, as
476              if the T key has been pressed immediately  after  startup.  This
477              implies time tracking mode (--tracking option).
478
479       -t <trans1[,trans2...]> or --transition <trans1[,trans2...]>
480              Using  this  switch, the set of transitions Impressive will ran‐
481              domly draw at page changes can be specified. If only one transi‐
482              tion  class  is specified, this class will be used for all pages
483              that do not have another transition explicitly assigned in their
484              page  properties.  Multiple  transitions have to be separated by
485              commas; they will be used in random order. The -l option can  be
486              used to get a list of available transitions.
487
488       -T <ms> or --transtime <ms>
489              Sets  the  duration  (in  milliseconds)  of  page transitions. 0
490              (zero) disables transitions altogether. Default value: 1000 ms.
491
492       --tracking
493              This option enables time tracking mode. In this mode,  a  report
494              of  all  pages  visited  with  their display duration, enter and
495              leave times will be written to standard output. This can be very
496              useful when preparing presentations.
497
498       -u <seconds> or --poll <seconds>
499              If  this  option is specified, the source file or directory will
500              be checked for changes regularly. If a change in the  input  PDF
501              file  or  any of the image files in the input image directory is
502              detected, the page cache will be flushed and the current page as
503              well  as  the  info  script will be reloaded. The current page's
504              transition will be shown between the old and the new version  of
505              the page.
506              The  new  PDF  file  must have at least as much pages as the old
507              one; also, it should have the same aspect ratio. If the input is
508              a directory, image files must not have disappeared.
509
510       -v or --verbose
511              This  option  makes  Impressive more verbose, i.e. it will print
512              slightly more informational messages than usual.
513
514       -V <pixels> or --overscan <pixels>
515              PDF files often contain tiny amounts of white borders around the
516              edges  which look bad in screen presentations. To eliminate this
517              problem, Impressive uses "overscan": PDF files will not be  ren‐
518              dered  to fit the screen size exactly, but they will be rendered
519              a bit larger so  that  the  (possibly  broken)  borders  can  be
520              cropped  off.  The  amount of overscan, in screen pixels, can be
521              set with this option. The  default  value  is  3  pixels,  which
522              should  remove  borders  in  most  presentations  at most common
523              screen resolutions without cropping the pages too much.
524
525       -w or --wrap
526              If this option is set, Impressive will "wrap" over to the  first
527              page  after the last page. In other words, advancing to the next
528              page at the end of the presentation will restart the whole  pre‐
529              sentation.
530
531       -W or --nowheel
532              By  default,  it  is  possible  to  change pages using the mouse
533              wheel. This option disables this behavior, which can  be  useful
534              to prevent spurious page changes if the mouse wheel is likely to
535              be moved by accident. In addition, it makes it possible to enter
536              zoom mode with the mouse wheel.
537              Note  that  this  option only works properly if the default con‐
538              trols are used. If the -e/--bind or -E/--controls  options  have
539              been used, --nowheel might not have the intended effect.
540
541       --windowed
542              Starts Impressive in windowed mode. See the discussion of the -f
543              option for details.
544
545       -x or --fade
546              This option enables a smooth fade-in effect at the start of  the
547              presentation and a fade-out effect just before Impressive quits.
548
549       -X or --shuffle
550              If this option is enabled, the input files will be shuffled into
551              random order before starting the  presentation.  The  individual
552              pages  of  PDF  input  files  will stay in their original order,
553              though, so this option is mainly useful for image presentations.
554
555       -y or --auto-auto
556              This option can be used together with --duration to have Impres‐
557              sive compute a page timeout (as with the --auto option) automat‐
558              ically. This results in a presentation that runs  automatically,
559              displaying each slide for the same time, so that the desired to‐
560              tal duration will be reached (almost) exactly. One exception  is
561              the runtime of videos, which is not taken into account.
562
563       --zbox-edge <pixels>
564              Sets  the  border size (in pixels when unzoomed) of the box-zoom
565              boxes' smooth edges. The default value is 1 pixel; it can be set
566              to zero, in which case the box-zoom area will have a hard edge.
567
568       -z <factor> or --zoom <factor>
569              Sets the scaling factor that is used in zoom mode. It can be any
570              real value above 1.0; the default value is  2.0.  Note  that  it
571              might not be possible to get high-quality zooming for large zoom
572              factors due to hardware  restrictions.  Furthermore,  please  be
573              aware  that  after  leaving  zoom mode, the image quality of the
574              normal page display may be slightly degraded until another  page
575              is displayed if a zoom factor other than 2.0 is used.
576
577       --zoomdarkness <percentage>
578              Specifies  how  much  the non-selected parts of the screen shall
579              become darker in box-zoom mode. The value is specified  in  per‐
580              cent,  with  90 being the default. A value of zero would mean no
581              darkening at all (parts outside of the zoom box would  still  be
582              perfectly visible), and a value of 100 would make everything but
583              the selected region black.
584
585       -Z <ms> or --zoomtime <ms>
586              Sets the duration (in milliseconds) of the  zoom,  box-zoom  and
587              overview  page  zoom-in/zoom-out  effects,  all at once. Default
588              value: 250 ms.
589              If separate animation time settings for overview zoom and  zoom/
590              box-zoom are desired, the -Z/--zoomtime option must be specified
591              before the --overtime option.
592
593       --cachefile <filename>
594              Activates persistent cache mode and specifies the  name  of  the
595              cache file to use.
596

ARGUMENTS

598       Following the options, the input file name(s) must be specified. Recog‐
599       nized file types are PDF, image files (JPEG, PNG, TIFF,  BMP,  PGM/PPM)
600       and  video files (AVI, MOV/MP4, MKV/WebM, OGV, MPEG, M2TS, FLV). If the
601       name of a directory is put on the command line,  all  recognized  image
602       files  (no PDF files!) in this directory will be played in alphanumeric
603       order (case-insensitive).
604
605       In addition, Impressive can use a text file containing a list of  files
606       or  directories  to  show: This text file must contain at most one file
607       name per line; every character after a hash sign (#) is  treated  as  a
608       comment  and will be ignored. If such a comment is put on the same line
609       as an image file name, it will be used as the page's title.  List  file
610       names  must  be  prefixed with an at sign (@) on the command line, e.g.
611       impressive @my_list_file.
612
613       Impressive will also expand wild-card characters  (*  and  ?)  if  this
614       isn't  already  done by the shell, but apart from that, it will not re‐
615       order the arguments. Thus, it will show  the  documents  in  the  order
616       specified at the command line.
617
618       If  video files are specified on the command line, Impressive generates
619       presentation pages for them just like it does for image files. If  FFm‐
620       peg or MPlayer are installed, the page will be shown as a screenshot of
621       the first video frame. When entering such a page,  the  video  will  be
622       played  back  if  a suitable player (MPlayer, or omxplayer on Raspberry
623       Pi) is installed.
624
625    LAYOUT OPTIONS
626       The OSD layout option (-L/--layout) accepts a string  with  comma-sepa‐
627       rated key=value pairs. The following keywords are recognized:
628       alpha
629              The  opacity  of  the OSD text, either as a floating-point value
630              between 0 and 1 or a percentage between 2 and 100.
631       margin
632              The distance (in pixels) of the OSD text to the screen borders.
633       time
634              The position of the timer.
635       title
636              The position of the page title in overview mode.
637       page
638              The position of the page number in overview mode.
639       status
640              The position of the status line.
641       The position specifications are composed by one  character  that  indi‐
642       cates  whether the text shall be displayed at the top (T) or bottom (B)
643       edge of the screen and one character that indicates  whether  it  shall
644       appear on the left (L), on the right (R) or centered (C).
645
646       For example, the default OSD layout equals the following option string:
647           -L margin=16,alpha=1,time=TR,title=BL,page=BR,status=TL
648
649    EXAMPLES
650       The  following examples illustrate some typical command lines. They as‐
651       sume that Impressive can be run by simply typing  "impressive"  on  the
652       command  line. Depending on how Impressive is installed, this has to be
653       substituted with the actual way to run Impressive (e.g.  "python  ~/im‐
654       pressive/impressive_dev.py" for a fresh SVN checkout). Furthermore, the
655       file "demo.pdf" is used as the document to show  here;  obviously  this
656       has to be replaced by the path to the actual PDF file too.
657
658       In  the  simplest case, Impressive is run directly with the name of the
659       file to show and no further parameters. This will start  a  full-screen
660       presentation with all settings at their defaults:
661           impressive demo.pdf
662
663       To  just quickly check a slide deck, it might make sense to run Impres‐
664       sive in a small window and not full-screen. This can be done with some‐
665       thing like
666           impressive -f -g 800x600 demo.pdf
667
668       Impressive can also be used in digital signage scenarios, like displays
669       in shop windows with a permanent slideshow. This  can  be  achieved  by
670       having Impressive advance to the next page automatically after a speci‐
671       fied time (e.g. 10 seconds) and  re-start  the  presentation  from  the
672       start after the last slide:
673           impressive -a 10 -w demo.pdf
674

USAGE

676       On  startup,  Impressive  will  display a black screen with the program
677       logo at the center. If caching is enabled, but background rendering  is
678       disabled,  all  pages of the presentation will then be rendered once. A
679       bar in the lower half of the screen displays the progress of this oper‐
680       ation.  Any  key or mouse click (except for those that quit Impressive,
681       typically Q and Esc) skips this process, with the effect  that  Impres‐
682       sive  will  render  the remaining pages on demand. Please note that the
683       overview page will not be complete until every page has  been  rendered
684       at  least  once. In other words, if the precaching process was skipped,
685       placeholders will be displayed for all pages that have  not  been  ren‐
686       dered  yet. By default, Impressive will build up the cache in the back‐
687       ground while the presentation runs. Thus, the progress bar will not ap‐
688       pear  and the preparation will only take the amount of time required to
689       render the first two pages of the presentation. After this  initializa‐
690       tion  process,  Impressive  will  switch to the first page directly and
691       without any transition.
692

DEFAULT CONTROLS

694       The keyboard and mouse controls used  by  Impressive  are  configurable
695       (with very few exceptions). The default controls are as follows:
696
697       Esc key
698              Return  from  the currently active special mode (zoom, box-zoom,
699              overview, spotlight, highlight boxes); if no such  special  mode
700              is active, quit Impressive altogether.
701
702       Q key or Alt+F4
703              Quit Impressive immediately.
704
705       LMB  (left  mouse button), mouse wheel down, Page Down key, Cursor Down
706       key, Cursor Right key or Spacebar
707              Go to the next page (using a transition).
708
709       RMB (right mouse button), mouse wheel up, Page Up key, Cursor  Up  key,
710       Cursor Left key or Backspace key
711              Go to the previous page (using a transition).
712
713       Home key / End key
714              Go directly to the first or last page of the presentation.
715
716       Ctrl key (modifier)
717              If  one  of the page navigation keys (Page Up/Down, Cursor keys,
718              Space, Backspace, Home, End) is pressed while the  Ctrl  key  is
719              held  down,  the  destination  page will be entered immediately,
720              without a transition.
721
722       L key
723              Return to the last (most recently displayed) page. This  can  be
724              used to toggle back and forth between two pages.
725
726       F key
727              Toggle fullscreen mode.
728
729       Tab key
730              Zoom  back  to the overview page. While in overview mode, a page
731              can be selected with the mouse and activated with the left mouse
732              button.  The  right  or middle mouse button or the Tab key leave
733              overview mode without changing the current page.
734
735       MMB (middle mouse button)
736              In normal display mode, this acts like the  Tab  key:  it  zooms
737              back to the overview page. If the page is zoomed in, it will re‐
738              turn to normal mode.
739
740       LMB over a PDF hyperlink
741              Jump to the page referenced by the hyperlink. Two types  of  hy‐
742              perlinks  are  supported: Links that point to some other page of
743              the same document, and URL hyperlinks like Web links and  e-mail
744              addresses. This feature is only available if pdftk is installed.
745              Furthermore, xdg-open from the freedesktop.org Portland  project
746              is  required for URL links to work.  Please note that the hyper‐
747              link feature will not work properly when pages are rotated.
748
749       click&drag with LMB (left mouse button)
750              Create a new highlight box. While at least one highlight box  is
751              defined  on the current page, the page itself will be shown in a
752              darker, blurry and (if supported by the graphics  hardware)  de‐
753              saturated  rendition. Only the highlight boxes will be displayed
754              in their original lightness, sharpness and color saturation.
755              If a page with highlight boxes is left, the boxes will be  saved
756              and restored the next time this page is shown again.
757
758       click&drag with Ctrl+LMB (left mouse button)
759              Draw  a box to zoom into. This enters so-called "box-zoom" mode,
760              where the selected region is zoomed into full view and  anything
761              else is displayed in much darker colors (but not blurred like in
762              highlight box mode). The page contents will be re-rendered in  a
763              higher resolution, if possible (limited to what has been config‐
764              ured with the --maxzoom command-line option,  and  the  graphics
765              hardware's  maximum  supported texture size). To leave this mode
766              again, use RMB, MMB or Esc.
767              Note that box-zoom mode is  mutually  exclusive  with  highlight
768              boxes  and  the  spotlight; if any of those is currently active,
769              it's not possible to draw a zoom box.
770
771       RMB (right mouse button) over a highlight box
772              If the right mouse button is clicked while the mouse  cursor  is
773              above  a highlight box, the box will be removed. If the last box
774              on a page is removed, the page will turn bright and sharp again.
775
776       A key
777              Toggle automatic slideshow mode.
778              If an automatic presentation has been started with the -a/--auto
779              option,  it  is  temporarily  disabled until this key is pressed
780              again. It is not automatically  re-enabled  after  changing  the
781              page. If the -a/--auto has not been used, an automatic presenta‐
782              tion with a timeout of 30 seconds is started when  this  key  is
783              pressed for the first time.
784              Note  that if a page has a timeout PageProp, the specified time‐
785              out is always in effect when the page is entered,  even  if  the
786              automatic slideshow is otherwise disabled.
787
788       S key
789              Save  the  info script associated with the current presentation.
790              The main purpose for this is to permanently save highlight boxes
791              or  keyboard  shortcuts,  so they will be restored the next time
792              this presentation is started.
793
794       T key
795              Activate or deactivate the time display at the upper-right  cor‐
796              ner  of  the  screen.  If  the timer is activated while the very
797              first page of the  presentation  is  shown,  it  activates  time
798              tracking mode, just as if the command-line option --tracking had
799              been specified.
800
801       R key
802              Reset the presentation timer.
803
804       C key
805              Removes ("clears") all highlight boxes from the current page.
806
807       Return key or Enter key
808              Toggle spotlight mode. In this mode, the page is darkened in the
809              same  way  as if highlight boxes are present, but instead of (or
810              in addition to) the boxes, a circular "spotlight" will be  shown
811              around  the mouse cursor position, following every motion of the
812              mouse cursor.
813
814       + / - key, 9 / 0 key or mouse wheel in spotlight mode
815              Adjust the spotlight radius.
816
817       Ctrl+9 or Ctrl+0 keys
818              Resets the spotlight radius to the default value, i.e. the value
819              that has been set up by the radius page property, the --spot-ra‐
820              dius command-line option or Impressive's built-in default.
821
822       7 / 8 key
823              Adjust the amount of darkening applied to the page in spotlight,
824              highlight box or box-zoom mode.
825
826       Ctrl+7 or Ctrl+8 keys
827              Resets  the  amount of darkening in spotlight, highlight box and
828              box-zoom mode to the default values, i.e. the  value  that  have
829              been  set  up  by the darkness and zoomdarkness page properties,
830              the --darkness and --zoomdarkness command-line  options  or  Im‐
831              pressive's built-in defaults.
832
833       Z key
834              Toggle  zoom  mode.  When this key is first pressed, the current
835              page will zoom in. The page will be displayed  at  double  size,
836              but in its original resolution (i.e. it will be blurry). Impres‐
837              sive will re-render the page at the new resolution if the graph‐
838              ics  hardware supports it. During this time, Impressive will not
839              accept any input, so don't even think about clicking  the  mouse
840              or pressing keys before the image gets crisp again.
841              In zoom mode, all other functions will work as normal. Any oper‐
842              ations that leave the current page, such as flipping the page or
843              entering the overview screen, will leave zoom mode, too.
844
845       [ / ] key
846              Adjust the gamma value of the display (might not be supported on
847              every hardware).
848
849       { / } key
850              Adjust the black level of the display (might not be supported on
851              every hardware).
852
853       \ key
854              Revert gamma and black level back to normal.
855
856       O key
857              This will toggle the "visible on overview page" flag of the cur‐
858              rent page. The result will not be visible  immediately,  but  it
859              can be saved to the info script (using the S key) and will be in
860              effect the next time the presentation is started.
861
862       I key
863              This will toggle the skip flag  of  the  current  page.  A  page
864              marked as skipped will not be reachable with the normal forward/
865              backward navigation keys.
866
867       B / W key or . (dot) / , (comma) key
868              Fade to black or white, respectively. This feature can  be  used
869              if a whiteboard or blackboard in front of the projection area is
870              to be used during the presentation. Using these  two  keys,  the
871              screen  will  fade  into a solid color. On any keypress or mouse
872              click, it will fade back to normal. These keys are not available
873              in overview mode.
874
875       click&drag  with  MMB (middle mouse button) or RMB (right mouse button)
876       in zoom mode
877              Move the visible part of the page in zoom mode.
878
879       mouse wheel up / down in zoom mode, U key
880              Zoom a bit in or out. When zoomed out fully, zoom mode is  left;
881              note  that  in  the  default configuration, this means that when
882              trying to zoom out even more using the wheel, the page  is  left
883              instead.  This  is different if the -W/--nowheel option is used,
884              where page navigation using the mouse wheel is disabled, and the
885              wheel  is  always  used for zooming. In this mode, the wheel can
886              also be used to enter zoom mode in the first place.
887              Note that changing the zoom level on the fly with the wheel does
888              not make Impressive automatically re-render the page at a higher
889              resolution to increase the level of detail. To do  this,  the  U
890              key needs to be pressed manually when the desired zoom level has
891              been set up.
892
893       Cursor keys in overview mode
894              Navigate through pages.
895
896       Alt+Tab keys
897              If Impressive is in fullscreen mode, the window  will  be  mini‐
898              mized so that other applications can be used.
899
900       Any  alphanumeric (A-z, 0-9) or function key (F1-F12) that is not bound
901       to a specific action mentioned above or configured by the user (see be‐
902       low)  can  be  used to assign shortcuts to pages that require quick ac‐
903       cess. If one of the keys is pressed together with Shift, the  currently
904       displayed  page  is associated with this key. To recall the page later,
905       it is sufficient to press the shortcut  key  again.  Shortcuts  can  be
906       stored permanently with the S key.
907

CONTROL CONFIGURATION

909       As  already  mentioned  in the previous chapter, the keyboard and mouse
910       bindings of Impressive can be widely configured.  The  only  exceptions
911       are  the  Alt+F4  and Alt+Tab key combinations that will always quit or
912       minimize Impressive, respectively. For everything else, there is a ver‐
913       satile  configuration  system  in  place; the controls described in the
914       previous section are merely the defaults.
915
916       Impressive's control system works by associating events  with  actions.
917       An  event  is  a  key  on the keyboard, a mouse button or a mouse wheel
918       movement. An action is something that is performed by Impressive  as  a
919       result  of an event, like going to the next page, switching to overview
920       mode or quitting the program. The association of an event to an an  ac‐
921       tion  is called a binding. Multiple events can be bound to the same ac‐
922       tion (like the page down and space keys in the default setting, both of
923       which  go to the next page); furthermore, multiple actions can be bound
924       to the same event. In fact, bindings do not associate events with  sin‐
925       gle  actions  at all, but with chains of actions. Only the first action
926       in the chain that matches (i.e. makes sense  in)  the  current  context
927       will be executed if the event fires; all other actions will be ignored.
928       If no action matches, no action will be performed and the event will be
929       ignored.
930
931       One example of such an action chain is the default binding for the left
932       mouse button, which draws a highlight box if the mouse cursor moved, or
933       visits  a hyperlink if the mouse cursor hovers over one, or goes to the
934       next page if none of the other conditions are met.
935
936       Both events and actions have mnemonic names that are used in  the  com‐
937       mand-line options and configuration files used for setting up bindings.
938       Event and actions names  are  generally  case-insensitive,  though  the
939       canonical notation is lowercase.
940       If  an event or action specified on the command line or in a configura‐
941       tion file is not recognized by Impressive, an  error  message  will  be
942       written  to  the  console and the offending event or action will be ig‐
943       nored. Errors in control configuration are thus always non-fatal.
944
945    SUPPORTED EVENTS
946       Keyboard events are generally named after the keys they refer to.  Con‐
947       sequently,  the events a to z and 0 to 9 mean the respective letter and
948       number keys on the main keyboard, f1 to f12 are the function  keys  and
949       kp0  to  kp9  are the number keys on the numerical keypad. All of these
950       are raw scancodes, which has two implications: First, the key names are
951       not  internationalized  and refer to the US keyboard layout (e.g. the Z
952       key on a German or French keyboard will actually  react  to  the  event
953       name  y  or w); second, modifiers will be ignored as well (e.g. the nu‐
954       merical keypad will always generate the kpX scancodes, even if Num Lock
955       is off).
956
957       The mnemonic names for the other keyboard events are as follows (in al‐
958       phabetic  order):  ampersand,  asterisk,  at,   backquote,   backslash,
959       backspace,  break,  capslock,  caret,  clear, comma, down, end, escape,
960       euro, exclaim, greater, hash, help, home, insert, kp_divide,  kp_enter,
961       kp_equals,    kp_minus,  kp_multiply, kp_plus, lalt, last, lctrl, left,
962       leftbracket, leftparen, less, lmeta, lshift, lsuper, menu, minus, mode,
963       numlock, pagedown, pageup, pause, period, plus, power, print, question,
964       quote, quotedbl, ralt, rctrl, return, right, rightbracket,  rightparen,
965       rmeta, rshift, rsuper, scrollock, semicolon, slash, space, sysreq, tab,
966       underscore, up. The events prefixed with kp_ refer to keys on  the  nu‐
967       merical  keypad.  Other  than  that, the names should be reasonably de‐
968       scriptive, so they will not be described futher  at  this  point.  Also
969       note  that  not  all  keyboards and platforms support the full range of
970       keys defined in this list.
971
972       Mouse event names are mapped as follows:
973
974       lmb
975              the left mouse button
976
977       mmb
978              the middle mouse button
979
980       rmb
981              the right mouse button
982
983       wheelup
984              scrolling the mouse wheel upwards
985
986       wheeldown
987              scrolling the mouse wheel downwards
988
989       btnX (i.e. btn6, btn7, ...)
990              additional mouse buttons, the mapping of  which  is  device-spe‐
991              cific; use --evtest to see which button is which
992
993       The  event  names  can be prefixed with the three modifiers ctrl+, alt+
994       and shift+ to make the event valid only if the specified set  of  modi‐
995       fiers  is  pressed  as  well.  This  works  for both keyboard and mouse
996       events. Multiple modifiers can be combined, but the  order  must  match
997       the  one  mentioned  in  this paragraph. For example, ctrl+shift+x is a
998       valid event name, while shift+ctrl+x is not.
999
1000       A simple way to determine the name associated with an  event  is  using
1001       Impressive's "Event Test Mode" by invoking impressive --evtest. In this
1002       mode, the name of each incoming event will be displayed on  the  screen
1003       (and  logged  to standard output), which makes it possible to determine
1004       event names by experimentation.
1005
1006    SUPPORTED ACTIONS
1007       The following list describes all actions supported by  Impressive,  to‐
1008       gether  with the conditions under which they will match. Note that most
1009       actions will not match in overview mode and during video playback,  un‐
1010       less mentioned otherwise in the description.
1011
1012       auto-start
1013              (Re-)enable automatic presentation mode. If the current page has
1014              no timeout PageProp and no -a/--auto option has been  specified,
1015              an  automatic  presentation is started with a 30-second page in‐
1016              terval.
1017
1018       auto-stop
1019              Disable automatic presentation mode. If the current page  has  a
1020              timeout  PageProp or an -a/--auto option has been specified, the
1021              timeout for the current page is stopped.
1022              The automatic presentation stays disabled after changing  pages,
1023              unless  a  timeout  PageProp  is  specified for the target page,
1024              which will take precedence over the otherwise disabled automatic
1025              presentation mode.
1026
1027       auto-toggle
1028              Disables  or  (re-)enables automatic presentations, depending on
1029              the current state.
1030
1031       box-add
1032              Draw a highlight box if the mouse has been moved since the  but‐
1033              ton  has  been pressed down. This action must only be bound to a
1034              mouse button event, otherwise it will not function properly.
1035
1036       box-clear
1037              Removes all boxes from the current page.
1038
1039       box-remove
1040              Removes the highlight box under the mouse cursor,  if  there  is
1041              any.
1042
1043       box-zoom
1044              Define a region to zoom into by drawing a rectangle. This action
1045              must only be bound to a mouse button event,  otherwise  it  will
1046              not function properly.
1047
1048       box-zoom-exit
1049              If in box-zoom (but not normal zoom) mode, leave box-zoom mode.
1050
1051       fade-less, fade-more
1052              Decrease  or  increase  the  amount  of darkening applied to the
1053              background in spotlight or highlight box mode.
1054
1055       fade-reset
1056              Resets the background darkness in  spotlight  or  highlight  box
1057              mode to its default value.
1058
1059       fade-to-black, fade-to-white
1060              Fades  to a black or white screen. Once the screen is faded out,
1061              any event except those bound to the quit action will just  leave
1062              fade mode and not perform its assigned action.
1063
1064       fullscreen
1065              Toggle fullscreen mode on platforms that support it.
1066
1067       gamma-decrease, gamma-increase
1068              Decrease  or  increase the gamma level (i.e. roughly the bright‐
1069              ness) of the display on platforms that support it.
1070
1071       gamma-bl-decrease, gamma-bl-increase
1072              Decrease or increase the black level of the display on platforms
1073              that support it.
1074
1075       gamma-reset
1076              Reset the gamma and black level settings to their defaults.
1077
1078       goto-end, goto-end-notrans
1079              Go to the last page of the presentation, with or without a tran‐
1080              sition.
1081
1082       goto-last, goto-last-notrans
1083              Go to the last (i.e. most recently) visited page, with or  with‐
1084              out a transition.
1085
1086       goto-next, goto-next-notrans
1087              Go  to the following page of the presentation, with or without a
1088              transition.
1089
1090       goto-prev, goto-prev-notrans
1091              Go to the previous page of the presentation, with or  without  a
1092              transition.
1093
1094       goto-start, goto-start-notrans
1095              Go  to  the  first  page  of the presentation, with or without a
1096              transition.
1097
1098       hyperlink, hyperlink-notrans
1099              Navigate to the hyperlink under the mouse cursor,  if  there  is
1100              one. If the hyperlink is a reference to another page of the pre‐
1101              sentation, this page will be activated with or without a transi‐
1102              tion.  If  the  hyperlink  refers to an external object (e.g. an
1103              URL), it will be opened externally, if supported by the system.
1104
1105       overview-confirm
1106              When in overview mode, confirm the selection and leave  overview
1107              mode, navigating to the selected page.
1108
1109       overview-down, overview-up
1110              When  in  overview mode, select the page above or below the cur‐
1111              rently selected one in the grid.
1112
1113       overview-enter
1114              When not in overview mode, zoom out of the current page,  enter‐
1115              ing overview mode.
1116
1117       overview-exit
1118              When  in overview mode, leave overview mode, zooming back to the
1119              page that has been displayed before entering overview mode.
1120
1121       overview-next, overview-prev
1122              When in overview mode, select the following or previous page.
1123
1124       quit
1125              Quits Impressive immediately. This action is  available  in  all
1126              modes.
1127
1128       save
1129              Save or update the Info Script for the current presentation.
1130
1131       spotlight-enter
1132              If spotlight mode is not active, enable spotlight mode.
1133
1134       spotlight-exit
1135              If spotlight mode is active, deactivate spotlight mode.
1136
1137       spotlight-grow, spotlight-shrink
1138              When  in  spotlight mode, increase or decrease the radius of the
1139              spotlight.
1140
1141       spotlight-reset
1142              When in spotlight mode, reset the spotlight radius  to  the  de‐
1143              fault value.
1144
1145       time-reset
1146              Reset the presentation timer.
1147
1148       time-toggle
1149              Toggle  on-screen  display  of the current presentation time, or
1150              wall-clock time if the --clock option is used. If this  is  done
1151              at the start of the presentation, before the first page has been
1152              left, time tracking mode will be enabled,  like  the  --tracking
1153              option would have done.
1154
1155       toggle-overview
1156              This  toggles  the "page is visible on overview screen" flag for
1157              the current page. This will not have an immediate effect, but it
1158              can be saved to an Info Script.
1159
1160       toggle-skip
1161              This  toggles  the "skip page when navigating with goto-prev and
1162              goto-next" flag for the current page.
1163
1164       video-pause
1165              In video playback mode, this pauses or unpauses playback.
1166
1167       video-seek-backward-10,  video-seek-backward-1,   video-seek-forward-1,
1168       video-seek-forward-10
1169              In video playback mode, seek forward or backward by 1 or 10 sec‐
1170              onds.
1171
1172       video-step
1173              In video playback mode, if playback is paused, advance one frame
1174              in the video.
1175
1176       video-stop
1177              In  video playback mode, stop playback and return to normal page
1178              display mode.
1179
1180       zoom-enter
1181              If not in zoom mode, enter zoom mode with the zoom level config‐
1182              ured with the -z/--zoom option.
1183
1184       zoom-exit
1185              If in zoom or box-zoom mode, leave that mode.
1186
1187       zoom-in, zoom-out
1188              Slightly  increase or decrease the current zoom level. This does
1189              not change the page's rendering resolution, it  only  zooms  the
1190              visible  part of the screen in or out, centered around the mouse
1191              cursor's position. Zoom mode is left automatically if  the  zoom
1192              level  goes to down to 1x; conversely, zoom mode is entered when
1193              calling zoom-in while zoom mode is not active.
1194
1195       zoom-pan
1196              If in zoom mode, the visible area  of  the  page  can  be  moved
1197              around with the mouse while the key or mouse button of the asso‐
1198              ciated event is held down.
1199
1200       zoom-update
1201              If in zoom mode, re-render the current page in a resolution that
1202              best fits the current zoom level, up to the limits of the graph‐
1203              ics hardware or the --maxzoom setting. This  only  needs  to  be
1204              done explicitly when zooming with the zoom-in action; zoom-enter
1205              and box-zoom do this automatically.
1206
1207    BINDING SYNTAX
1208       The arguments of the -e/--bind command-line option have  the  following
1209       basic syntax:
1210           <event> [,<event2>...] <operator> <action> [,<action2>...]
1211       In  other  words,  it  is a sequence of event names joined with commas,
1212       followed by an operator (see below) and  a  sequence  of  action  names
1213       joined  with  commas.  Multiple such binding statements can be combined
1214       into one argument by joining them with a semicolon (;).
1215
1216       The used operator defines in which way the action list shall modify the
1217       bindings of the referenced events:
1218
1219       = (equals sign), += (plus sign and equals sign)
1220              The specified actions will be added to the bindings of the spec‐
1221              ified events. In other words, event=action1,action2 does exactly
1222              the same as event=action1; event=action2.
1223
1224       := (colon and equals sign)
1225              The specified actions will replace the bindings of the specified
1226              events.
1227
1228       -= (minus sign and equals sign)
1229              The specified actions will be removed from the bindings  of  the
1230              specified  events.  For  example, to make the Esc key in the de‐
1231              fault bindings not clear highlight boxes, but otherwise preserve
1232              its original functionality, escape -= box-clear can be used.
1233
1234       Other  than bindings, a statement can also contain one of the following
1235       special commands:
1236
1237       clearall
1238              Clears all current bindings.
1239
1240       defaults
1241              Discards all current bindings and (re-)establishes  the  default
1242              bindings.
1243
1244       include <filename>
1245              Loads and executes a control configuration file with a specified
1246              name.
1247
1248       The syntax for the configuration files used with the -E/--controls  op‐
1249       tion or include statement is exactly the same as for the ad-hoc config‐
1250       uration option, except that individual bindings can be written on indi‐
1251       vidual  lines  instead  of  joining them together to a single long line
1252       with semicolons. In addition, everything following a hash sign (#) on a
1253       line will be ignored as a comment.
1254
1255       One  practical example for such a configuration file can be the follow‐
1256       ing: The author of this program uses a cheap presentation  remote  con‐
1257       trol  device  that  has  four cursor keys, one "enter" key and a slider
1258       that switches between keyboard and mouse mode. Mouse mode works as  ex‐
1259       pected, but what it does in keyboard mode is quite peculiar: the up and
1260       down keys act like Page-Up and Page-Down keys on a keyboard, the  right
1261       arrow  key sends the letter B to the computer, and the left key toggles
1262       between Esc and F5 each time it's pressed. The following  configuration
1263       file  allows basic navigation and access to overview mode with this de‐
1264       vice:
1265
1266             clearall  # don't use the default bindings
1267             lmb = quit  # quit Impressive by clicking in mouse mode
1268             # everything else uses keyboard mode:
1269             return = overview-enter, overview-confirm  # toggle overview mode
1270             escape, f5 = overview-prev, goto-prev
1271             b = overview-next, goto-next
1272             pageup = overview-up, goto-prev
1273             pagedown = overview-down, goto-next
1274
1275       To get a better idea of how the control configuration system  works  in
1276       practice,  it's  recommended  to  study the output of impressive --con‐
1277       trol-help - this not only gives a concise overview of  all  events  and
1278       actions, but also a full dump of Impressive's default bindings that can
1279       be used as a starting point for own customizations.
1280

INFO SCRIPTS

1282       Impressive offers a powerful way to customize individual  presentations
1283       using  so-called info scripts. An info script is a text file having the
1284       same name and located in the same directory as  the  presentation  file
1285       itself,  except  for  the additional suffix .info. Thus, a presentation
1286       file called BrandNewProduct.pdf would have a info script with the  name
1287       BrandNewProduct.pdf.info.  If  multiple arguments were specified on the
1288       command line, the info script will be called just .info (a dot file, so
1289       to  speak). If a directory name was specified as the only argument, ei‐
1290       ther a file called DirectoryName.info or a file called .info inside the
1291       directory will be used, depending on whether a path separator was spec‐
1292       ified at the end of the directory name or not - Impressive  simply  ap‐
1293       pends .info to whatever the input path name was.
1294       In  any case, the default file name can be overridden by the -I command
1295       line option.
1296
1297       Info scripts are actually Python scripts with full  access  to  Impres‐
1298       sive's  global  data  structures and functions. (It is possible, though
1299       heavily discouraged, to write real interactive applications using  info
1300       scripts.)  This has some good and bad side effects. The bad news first:
1301       The info scripts must be compatible with the Python version used by Im‐
1302       pressive  itself;  it's  best  to write them in a way that's compatible
1303       with both Python 2.7 (with the __future__ imports print_function,  uni‐
1304       code_literals  and  division)  and  Python 3.x. Furthermore, there's no
1305       built-in security; in other words: don't trust  info  scripts  you  re‐
1306       ceived  from  somebody  else.  The good news, however, is that they can
1307       modify a broad range of settings  concerning  Impressive.  This  manual
1308       will only cover the most basic ones.
1309
1310    PAGE PROPERTIES
1311       The main part of an info script defines the properties of each page. At
1312       the moment, the following properties are defined:
1313
1314       title
1315              Each page can have a title that is displayed in  the  Impressive
1316              window's title bar. If there is no title explicitly specified in
1317              the info script, the title of the page will  be  extracted  from
1318              PDF  metadata if pdftk is installed, or the image file name will
1319              be used if the presentation is an image slideshow.
1320
1321       transition
1322              With this property, the transition class to be used for  render‐
1323              ing  the transition to this page (i.e. between the previous page
1324              and this page) can be specified. For pages  lacking  this  prop‐
1325              erty,  random  transitions  will  be chosen. A list of available
1326              transition classes can be obtained with impressive -l.
1327
1328       transtime
1329              This property overrides the global transition time parameter (-T
1330              at the command line). It contains the integer time (in millisec‐
1331              onds) the transition to this page shall take.
1332
1333       overview
1334              This property holds a boolean value  (0/False  or  1/True)  that
1335              specifies  whether  the  page  shall be included in the overview
1336              page. If this property isn't specified,  it  is  assumed  to  be
1337              True.
1338
1339       skip
1340              This  boolean property can be set to 1/True if the page shall be
1341              skipped during the presentation.
1342              Pages with overview:True, skip:False will be accessible both  by
1343              cycling through the pages and using the overview page,
1344              pages  with overview:True, skip:True will be silently skipped in
1345              the normal page cycle, but remain accessible from  the  overview
1346              page,
1347              pages  with overview:False, skip:False will appear in the normal
1348              cycle, but not on the overview page
1349              and pages with overview:False, skip:True will not be  accessible
1350              at all.
1351
1352       next
1353              This property can be set to the number of the page that shall be
1354              shown after this page. This can be used to skip a lot  of  pages
1355              without setting the skip property on each of those, or to create
1356              a loop that can only be escaped by using the  overview  page  or
1357              bookmarks.
1358
1359       prev
1360              This property can be set to the number of the page that shall be
1361              shown when navigating from this page to the previous page  (e.g.
1362              using  the  right mouse button or the Page-Up key in the default
1363              mappings).
1364
1365       boxes
1366              This property stores a list of highlight box  coordinates.  Nor‐
1367              mally, there is no need to edit this by hand, as Impressive han‐
1368              dles this automatically if the S key is pressed.
1369
1370       timeout
1371              If a timeout property is present and the page is shown,  Impres‐
1372              sive will automatically switch to the next page after the speci‐
1373              fied number of milliseconds. Normally, the timeout will only  be
1374              effective  the  first time the page is shown unless wrap mode is
1375              used (command-line option -w or --wrap). This restriction  makes
1376              it possible to create self-running presentations with individual
1377              per-page timeouts.
1378
1379       radius
1380              This property takes an integer value that, if defined,  will  be
1381              used  to  set  a new spotlight radius every time the page is en‐
1382              tered. This overrides the current  setting  as  defined  by  the
1383              --spot-radius  command line option or run-time adjustments. Note
1384              that the value is not reset to the default value after the  page
1385              has been left again.
1386
1387       darkness
1388              This  property  takes  an  integer  or floating-point percentage
1389              value that, if defined, will be used to set the background dark‐
1390              ness  in  spotlight  or highlight box mode each time the page is
1391              entered. This overrides the current setting as  defined  by  the
1392              --darkness  command  line  option  or run-time adjustments. Note
1393              that the value is not reset to the default value after the  page
1394              has been left again.
1395
1396       zoomdarkness
1397              This  property  takes  an  integer  or floating-point percentage
1398              value that, if defined, will be used to set the background dark‐
1399              ness  in box-zoom mode each time the page is entered. This over‐
1400              rides the current setting as defined by the --zoomdarkness  com‐
1401              mand line option or run-time adjustments. Note that the value is
1402              not reset to the default value after  the  page  has  been  left
1403              again.
1404
1405       comment
1406              This  property can hold a string with a single line of text that
1407              will be displayed on screen while the page is shown. Display  of
1408              this text can not be disabled.
1409
1410       sound
1411              Specifies  the  file  name  of  a  sound  file to be played (via
1412              MPlayer) when the page is first entered. Once started, the sound
1413              will  be played until its end is reached, another sound or video
1414              is played, or Impressive is exited.
1415
1416       video
1417              Specifies the file name of a video file to be  played  when  the
1418              page  is first entered. The video will be displayed full-screen.
1419              Any key or mouse click stops playback, except the  cursor  keys,
1420              which  are  used to seek in the video file, and space, which can
1421              be used to pause playback.
1422              Please not that this function is still somewhat experimental. It
1423              uses  an  external  player application (MPlayer, or omxplayer on
1424              Raspberry Pi) to perform the actual playback, and embeds it into
1425              Impressive's window.
1426
1427       always
1428              If this property is present and set to 1 or True, the media file
1429              specified in the sound or video properties will be played  every
1430              time the page is entered, not just the first time.
1431
1432       progress
1433              If  this property is set to zero, the presentation progress bars
1434              (which are set up with the -d/--duration, -q/--page-progress  or
1435              -k/--auto-progress  command  line switches) will not be shown on
1436              this page. In practice, it might be useful to  hide  the  bar(s)
1437              from  the first page so that they are not visible during the in‐
1438              troduction.
1439
1440       reset
1441              If this property is set to 1 or True, the timer  will  be  reset
1442              each  time this page is left, just as if the R has been pressed.
1443              If the special value 2 or FirstTimeOnly is used, the reset  will
1444              only take place if the page was shown for the first time. Again,
1445              this is particularly useful on the first page: A combination  of
1446              progress:False,  reset:FirstTimeOnly makes it possible to set up
1447              the presentation long before it actually begins - the first page
1448              can  be  showed  as long as desired, actual timing starts at the
1449              second page.
1450
1451       rotate
1452              This property is a per-page override of the  global  -r  command
1453              line  option:  It  specifies  how  the page shall be rotated, in
1454              90-degree steps clockwise.
1455
1456       OnEnter, OnLeave, OnEnterOnce, OnLeaveOnce
1457              These properties can contain a Python callable (i.e. a  function
1458              reference  or  lambda expression) that is executed when the page
1459              is entered or left. The ~Once variants  will  only  be  executed
1460              when  the  page  is  entered  or  left  for  the first time. The
1461              callable must not take any arguments. This feature can  be  used
1462              to  associate arbitrary Python code with specific pages, for ex‐
1463              ample to execute external programs.
1464              Warning: Lambda expressions cannot be properly processed by  the
1465              Info  Script  save  function  (S  key). If Impressive encounters
1466              lambda expressions when saving, it will remove  them.  In  addi‐
1467              tion, it will not overwrite the original info script, but gener‐
1468              ate an extra file that needs to  be  merged  with  the  original
1469              script by hand.
1470
1471       keys
1472              This property can be assigned a dictionary that maps alphanumer‐
1473              ical keys to Python functions. For example, 'keys': { 'x': Some‐
1474              Function } will invoke SomeFunction() if the lowercase character
1475              'x' is typed while the page is displayed.  Regarding  the  func‐
1476              tions,  the  same restrictions as for the OnEnter/OnLeave family
1477              apply: the function must not  take  any  parameters  and  lambda
1478              functions can not be saved. Also note that it is not possible to
1479              overwrite  Impressive's  pre-defined  key  bindings  with   this
1480              method.
1481
1482       invert
1483              This property specifies whether the colors of that page shall be
1484              inverted in the same way the --invert command-line switch  does.
1485              It overrides the --invert setting on a per-page basis: If set to
1486              True, the page will always be inverted; if  set  to  False,  the
1487              page  will never be inverted even if --invert has been specified
1488              on the command line.
1489
1490       Note that in Impressive versions prior to 0.11.0,  the  transition  and
1491       transtime  properties  defined  the transition from the current page to
1492       the next, not from the previous page to the current one.
1493
1494       The properties are stored together in a Python dictionary called  Page‐
1495       Props. The syntax looks like in this example:
1496
1497         PageProps = {
1498           1: {
1499                'title': "Title Page",
1500                'transition': PagePeel,
1501                'sound': "background_music.mp3"
1502              },
1503           2: {
1504                'title': "Another Page",
1505                'timeout': 5000
1506              }
1507         }
1508
1509       The  PageProps  definition  (and only the PageProps definition) will be
1510       rewritten by Impressive if the S key is pressed. User-defined PageProps
1511       entries will also be left untouched, except for some pretty-printing.
1512
1513    GLOBAL PRESENTATION PROPERTIES
1514       The  name  of the presentation is shown in the title bar of the Impres‐
1515       sive window (if not in fullscreen mode). By default, the file  name  or
1516       (if  available)  PDF  metadata title will be used for this purpose, but
1517       the presentation title can also be explicitly set  by  overwriting  the
1518       DocumentTitle variable:
1519           DocumentTitle = "My Presentation"
1520
1521       Another  useful  variable, AvailableTransitions, contains a list of all
1522       transition classes that may be used for randomly assigning  transitions
1523       to pages lacking the transition property. Thus, if a certain transition
1524       is undesired (either because of personal dislike or because it shall be
1525       used  exclusively  on  pages  where it is manually assigned using Page‐
1526       Props), something like the following can be written:
1527           AvailableTransitions.remove(WipeBlobs)
1528       On the other side, it's possible to activate transitions that  are  not
1529       enabled by default:
1530           AvailableTransitions += [SlideUp, SlideDown]
1531       Alternatively,  AvailableTransitions  can  be completely overwritten to
1532       have the same transition (or set of transitions) assigned to all pages:
1533           AvailableTransitions = [Crossfade]
1534
1535    OPTION OVERRIDES
1536       Another use of info scripts is overriding the default  or  command-line
1537       settings  on  a  per-file basis. This can be done by simply overwriting
1538       one of the variables that are  defined  at  the  beginning  of  impres‐
1539       sive.py.  Each  of these variables corresponds either to a command-line
1540       setting, or to some constant related to visual  appearance  or  perfor‐
1541       mance.  So,  for  example, to force fullscreen mode for a presentation,
1542       write
1543           Fullscreen = True
1544
1545    WORKING DIRECTORIES
1546       The working directory while executing the info  scripts  themselves  is
1547       always the directory in which the info script is stored in.
1548
1549       The  base directory for external actions that originate from Page Prop‐
1550       erties or PDF hyperlinks is always the directory of the  PDF  or  image
1551       file this page belongs to. In other words, if e.g. 'sound': "music.mp3"
1552       is written in the info script for one  page  of  presentation.pdf,  the
1553       file  music.mp3 is expected to be located in the same directory as pre‐
1554       sentation.pdf.
1555

AUTHOR

1557       Impressive and its documentation has been written mainly by  Martin  J.
1558       Fiedler <martin.fiedler@gmx.net>, with small portions of the code writ‐
1559       ten by external contributors. See the source code file for details.
1560

REPORTING BUGS

1562       Report bugs to to <martin.fiedler@gmx.net>.
1563
1564
1565
1566Martin J. Fiedler                 2022-03-19                     IMPRESSIVE(1)
Impressum