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

ARGUMENTS

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

USAGE

650       On startup, Impressive will display a black  screen  with  the  program
651       logo  at the center. If caching is enabled, but background rendering is
652       disabled, all pages of the presentation will then be rendered  once.  A
653       bar in the lower half of the screen displays the progress of this oper‐
654       ation. Any key or mouse click (except for those that  quit  Impressive,
655       typically  Q  and Esc) skips this process, with the effect that Impres‐
656       sive will render the remaining pages on demand. Please  note  that  the
657       overview  page  will not be complete until every page has been rendered
658       at least once. In other words, if the precaching process  was  skipped,
659       placeholders  will  be  displayed for all pages that have not been ren‐
660       dered yet. By default, Impressive will build up the cache in the  back‐
661       ground  while  the  presentation  runs. Thus, the progress bar will not
662       appear and the preparation will only take the amount of  time  required
663       to  render the first two pages of the presentation. After this initial‐
664       ization process, Impressive will switch to the first page directly  and
665       without any transition.
666

DEFAULT CONTROLS

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

CONTROL CONFIGURATION

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

INFO SCRIPTS

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

AUTHOR

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

REPORTING BUGS

1525       Report bugs to to <martin.fiedler@gmx.net>.
1526
1527
1528
1529Martin J. Fiedler                 2019-09-02                     IMPRESSIVE(1)
Impressum