1IMPRESSIVE(1) Impressive Documentation IMPRESSIVE(1)
2
6 Impressive - presentation tool with eye candy
7
9 impressive [OPTIONS...] FILES...
10
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 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
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 -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 -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 --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 -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 --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 -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 -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 -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 --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 --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 -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 -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 --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 -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 -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 --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 -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 --fullscreen
200 Starts Impressive in fullscreen mode (the default). See the dis‐
201 cussion of the -f option for details.
202 --fake-fullscreen
204 Starts Impressive in "fake fullscreen" mode. See the discussion
205 of the -f option for details.
206 -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 -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 -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 -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 -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 -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 -I <filename> or --script <filename>
272 Overrides automatic derivation of the info script filename and
273 specifies a script file directly.
274 --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 -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 -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 -L <spec> or --layout <spec>
297 Specifies the OSD layout. Read below for an explanation of this
298 option.
299 --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 --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 -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 --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 -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 --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 --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 --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 --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 -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 -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 --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 -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 -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 -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 --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 -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 -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 -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 -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 -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 --spot-radius <pixels>
471 This option sets the initial radius of the spotlight, in pixels.
472 The default value is 64.
473 --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 -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 -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 --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 -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 -v or --verbose
511 This option makes Impressive more verbose, i.e. it will print
512 slightly more informational messages than usual.
513 -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 -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 -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 --windowed
542 Starts Impressive in windowed mode. See the discussion of the -f
543 option for details.
544 -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 -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 -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 --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 -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 --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 -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 --cachefile <filename>
594 Activates persistent cache mode and specifies the name of the
595 cache file to use.
596
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 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 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 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 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 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 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 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 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 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
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
694 The keyboard and mouse controls used by Impressive are configurable
695 (with very few exceptions). The default controls are as follows:
696 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 Q key or Alt+F4
703 Quit Impressive immediately.
704 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 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 Home key / End key
714 Go directly to the first or last page of the presentation.
715 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 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 F key
727 Toggle fullscreen mode.
728 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 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 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 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 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 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 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 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 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 R key
802 Reset the presentation timer.
803 C key
805 Removes ("clears") all highlight boxes from the current page.
806 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 + / - key, 9 / 0 key or mouse wheel in spotlight mode
815 Adjust the spotlight radius.
816 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 7 / 8 key
823 Adjust the amount of darkening applied to the page in spotlight,
824 highlight box or box-zoom mode.
825 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 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 [ / ] key
846 Adjust the gamma value of the display (might not be supported on
847 every hardware).
848 { / } key
850 Adjust the black level of the display (might not be supported on
851 every hardware).
852 \ key
854 Revert gamma and black level back to normal.
855 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 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 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 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 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 Cursor keys in overview mode
894 Navigate through pages.
895 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 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
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 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 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 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 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 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 Mouse event names are mapped as follows:
973 lmb
975 the left mouse button
976 mmb
978 the middle mouse button
979 rmb
981 the right mouse button
982 wheelup
984 scrolling the mouse wheel upwards
985 wheeldown
987 scrolling the mouse wheel downwards
988 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 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 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 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 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 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 auto-toggle
1028 Disables or (re-)enables automatic presentations, depending on
1029 the current state.
1030 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 box-clear
1037 Removes all boxes from the current page.
1038 box-remove
1040 Removes the highlight box under the mouse cursor, if there is
1041 any.
1042 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 box-zoom-exit
1049 If in box-zoom (but not normal zoom) mode, leave box-zoom mode.
1050 fade-less, fade-more
1052 Decrease or increase the amount of darkening applied to the
1053 background in spotlight or highlight box mode.
1054 fade-reset
1056 Resets the background darkness in spotlight or highlight box
1057 mode to its default value.
1058 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 fullscreen
1065 Toggle fullscreen mode on platforms that support it.
1066 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 gamma-bl-decrease, gamma-bl-increase
1072 Decrease or increase the black level of the display on platforms
1073 that support it.
1074 gamma-reset
1076 Reset the gamma and black level settings to their defaults.
1077 goto-end, goto-end-notrans
1079 Go to the last page of the presentation, with or without a tran‐
1080 sition.
1081 goto-last, goto-last-notrans
1083 Go to the last (i.e. most recently) visited page, with or with‐
1084 out a transition.
1085 goto-next, goto-next-notrans
1087 Go to the following page of the presentation, with or without a
1088 transition.
1089 goto-prev, goto-prev-notrans
1091 Go to the previous page of the presentation, with or without a
1092 transition.
1093 goto-start, goto-start-notrans
1095 Go to the first page of the presentation, with or without a
1096 transition.
1097 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 overview-confirm
1106 When in overview mode, confirm the selection and leave overview
1107 mode, navigating to the selected page.
1108 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 overview-enter
1114 When not in overview mode, zoom out of the current page, enter‐
1115 ing overview mode.
1116 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 overview-next, overview-prev
1122 When in overview mode, select the following or previous page.
1123 quit
1125 Quits Impressive immediately. This action is available in all
1126 modes.
1127 save
1129 Save or update the Info Script for the current presentation.
1130 spotlight-enter
1132 If spotlight mode is not active, enable spotlight mode.
1133 spotlight-exit
1135 If spotlight mode is active, deactivate spotlight mode.
1136 spotlight-grow, spotlight-shrink
1138 When in spotlight mode, increase or decrease the radius of the
1139 spotlight.
1140 spotlight-reset
1142 When in spotlight mode, reset the spotlight radius to the de‐
1143 fault value.
1144 time-reset
1146 Reset the presentation timer.
1147 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 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 toggle-skip
1161 This toggles the "skip page when navigating with goto-prev and
1162 goto-next" flag for the current page.
1163 video-pause
1165 In video playback mode, this pauses or unpauses playback.
1166 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 video-step
1173 In video playback mode, if playback is paused, advance one frame
1174 in the video.
1175 video-stop
1177 In video playback mode, stop playback and return to normal page
1178 display mode.
1179 zoom-enter
1181 If not in zoom mode, enter zoom mode with the zoom level config‐
1182 ured with the -z/--zoom option.
1183 zoom-exit
1185 If in zoom or box-zoom mode, leave that mode.
1186 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 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 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 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 The used operator defines in which way the action list shall modify the
1217 bindings of the referenced events:
1218 = (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 := (colon and equals sign)
1225 The specified actions will replace the bindings of the specified
1226 events.
1227 -= (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 Other than bindings, a statement can also contain one of the following
1235 special commands:
1236 clearall
1238 Clears all current bindings.
1239 defaults
1241 Discards all current bindings and (re-)establishes the default
1242 bindings.
1243 include <filename>
1245 Loads and executes a control configuration file with a specified
1246 name.
1247 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 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 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 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
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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 The properties are stored together in a Python dictionary called Page‐
1495 Props. The syntax looks like in this example:
1496 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 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 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 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 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 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 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
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
1562 Report bugs to to <martin.fiedler@gmx.net>.
1563Martin J. Fiedler 2023-11-04 IMPRESSIVE(1)