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
45 effect if caching is disabled (--cache none, see below).
46 -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 --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 -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 -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 -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 --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 --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 -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 -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 --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 -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 -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 --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 -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 --fullscreen
190 Starts Impressive in fullscreen mode (the default). See the dis‐
191 cussion of the -f option for details.
192 --fake-fullscreen
194 Starts Impressive in "fake fullscreen" mode. See the discussion
195 of the -f option for details.
196 -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 -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 -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 -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 -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 -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 -I <filename> or --script <filename>
261 Overrides automatic derivation of the info script filename and
262 specifies a script file directly.
263 --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 -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 -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 -L <spec> or --layout <spec>
289 Specifies the OSD layout. Read below for an explanation of this
290 option.
291 --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 --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 -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 --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 -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 --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 --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 --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 --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 -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 -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 -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 -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 -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 -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 -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 -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 -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 -S <pixels> or --fontsize <pixels>
445 This option sets the size, in pixels, of the OSD font. The
446 default value is 14.
447 --spot-radius <pixels>
449 This option sets the initial radius of the spotlight, in pixels.
450 The default value is 64.
451 --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 -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 -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 --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 -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 -v or --verbose
489 This option makes Impressive more verbose, i.e. it will print
490 slightly more informational messages than usual.
491 -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 -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 -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 --windowed
520 Starts Impressive in windowed mode. See the discussion of the -f
521 option for details.
522 -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 -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 -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 --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 -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 --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 -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 --cachefile <filename>
568 Activates persistent cache mode and specifies the name of the
569 cache file to use.
570
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 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 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 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 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 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 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 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 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 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
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
668 The keyboard and mouse controls used by Impressive are configurable
669 (with very few exceptions). The default controls are as follows:
670 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 Q key or Alt+F4
677 Quit Impressive immediately.
678 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 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 Home key / End key
688 Go directly to the first or last page of the presentation.
689 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 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 F key
701 Toggle fullscreen mode.
702 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 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 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 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 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 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 S key
752 Save the info script associated with the current presentation.
753 The main purpose for this is to permanently save highlight boxes
754 or keyboard shortcuts, so they will be restored the next time
755 this presentation is started.
756 T key
758 Activate or deactivate the time display at the upper-right cor‐
759 ner of the screen. If the timer is activated while the very
760 first page of the presentation is shown, it activates time
761 tracking mode, just as if the command-line option --tracking had
762 been specified.
763 R key
765 Reset the presentation timer.
766 C key
768 Removes ("clears") all highlight boxes from the current page.
769 Return key or Enter key
771 Toggle spotlight mode. In this mode, the page is darkened in the
772 same way as if highlight boxes are present, but instead of (or
773 in addition to) the boxes, a circular "spotlight" will be shown
774 around the mouse cursor position, following every motion of the
775 mouse cursor.
776 + / - key, 9 / 0 key or mouse wheel in spotlight mode
778 Adjust the spotlight radius.
779 Ctrl+9 or Ctrl+0 keys
781 Resets the spotlight radius to the default value, i.e. the value
782 that has been set up by the radius page property, the
783 --spot-radius command-line option or Impressive's built-in
784 default.
785 7 / 8 key
787 Adjust the amount of darkening applied to the page in spotlight,
788 highlight box or box-zoom mode.
789 Ctrl+7 or Ctrl+8 keys
791 Resets the amount of darkening in spotlight, highlight box and
792 box-zoom mode to the default values, i.e. the value that have
793 been set up by the darkness and zoomdarkness page properties,
794 the --darkness and --zoomdarkness command-line options or
795 Impressive's built-in defaults.
796 Z key
798 Toggle zoom mode. When this key is first pressed, the current
799 page will zoom in. The page will be displayed at double size,
800 but in its original resolution (i.e. it will be blurry). Impres‐
801 sive will re-render the page at the new resolution if the graph‐
802 ics hardware supports it. During this time, Impressive will not
803 accept any input, so don't even think about clicking the mouse
804 or pressing keys before the image gets crisp again.
805 In zoom mode, all other functions will work as normal. Any oper‐
806 ations that leave the current page, such as flipping the page or
807 entering the overview screen, will leave zoom mode, too.
808 [ / ] key
810 Adjust the gamma value of the display (might not be supported on
811 every hardware).
812 { / } key
814 Adjust the black level of the display (might not be supported on
815 every hardware).
816 \ key
818 Revert gamma and black level back to normal.
819 O key
821 This will toggle the "visible on overview page" flag of the cur‐
822 rent page. The result will not be visible immediately, but it
823 can be saved to the info script (using the S key) and will be in
824 effect the next time the presentation is started.
825 I key
827 This will toggle the skip flag of the current page. A page
828 marked as skipped will not be reachable with the normal forward/
829 backward navigation keys.
830 B / W key or . (dot) / , (comma) key
832 Fade to black or white, respectively. This feature can be used
833 if a whiteboard or blackboard in front of the projection area is
834 to be used during the presentation. Using these two keys, the
835 screen will fade into a solid color. On any keypress or mouse
836 click, it will fade back to normal. These keys are not available
837 in overview mode.
838 click&drag with MMB (middle mouse button) or RMB (right mouse button)
840 in zoom mode
841 Move the visible part of the page in zoom mode.
842 mouse wheel up / down in zoom mode, U key
844 Zoom a bit in or out. When zoomed out fully, zoom mode is left;
845 note that in the default configuration, this means that when
846 trying to zoom out even more using the wheel, the page is left
847 instead. This is different if the -W/--nowheel option is used,
848 where page navigation using the mouse wheel is disabled, and the
849 wheel is always used for zooming. In this mode, the wheel can
850 also be used to enter zoom mode in the first place.
851 Note that changing the zoom level on the fly with the wheel does
852 not make Impressive automatically re-render the page at a higher
853 resolution to increase the level of detail. To do this, the U
854 key needs to be pressed manually when the desired zoom level has
855 been set up.
856 Cursor keys in overview mode
858 Navigate through pages.
859 Alt+Tab keys
861 If Impressive is in fullscreen mode, the window will be mini‐
862 mized so that other applications can be used.
863 Any alphanumeric (A-z, 0-9) or function key (F1-F12) that is not bound
865 to a specific action mentioned above or configured by the user (see
866 below) can be used to assign shortcuts to pages that require quick
867 access. If one of the keys is pressed together with Shift, the cur‐
868 rently displayed page is associated with this key. To recall the page
869 later, it is sufficient to press the shortcut key again. Shortcuts can
870 be stored permanently with the S key.
871
873 As already mentioned in the previous chapter, the keyboard and mouse
874 bindings of Impressive can be widely configured. The only exceptions
875 are the Alt+F4 and Alt+Tab key combinations that will always quit or
876 minimize Impressive, respectively. For everything else, there is a ver‐
877 satile configuration system in place; the controls described in the
878 previous section are merely the defaults.
879 Impressive's control system works by associating events with actions.
881 An event is a key on the keyboard, a mouse button or a mouse wheel
882 movement. An action is something that is performed by Impressive as a
883 result of an event, like going to the next page, switching to overview
884 mode or quitting the program. The association of an event to an an
885 action is called a binding. Multiple events can be bound to the same
886 action (like the page down and space keys in the default setting, both
887 of which go to the next page); furthermore, multiple actions can be
888 bound to the same event. In fact, bindings do not associate events with
889 single actions at all, but with chains of actions. Only the first
890 action in the chain that matches (i.e. makes sense in) the current con‐
891 text will be executed if the event fires; all other actions will be
892 ignored. If no action matches, no action will be performed and the
893 event will be ignored.
894 One example of such an action chain is the default binding for the left
896 mouse button, which draws a highlight box if the mouse cursor moved, or
897 visits a hyperlink if the mouse cursor hovers over one, or goes to the
898 next page if none of the other conditions are met.
899 Both events and actions have mnemonic names that are used in the com‐
901 mand-line options and configuration files used for setting up bindings.
902 Event and actions names are generally case-insensitive, though the
903 canonical notation is lowercase.
904 If an event or action specified on the command line or in a configura‐
905 tion file is not recognized by Impressive, an error message will be
906 written to the console and the offending event or action will be
907 ignored. Errors in control configuration are thus always non-fatal.
908 SUPPORTED EVENTS
910 Keyboard events are generally named after the keys they refer to. Con‐
911 sequently, the events a to z and 0 to 9 mean the respective letter and
912 number keys on the main keyboard, f1 to f12 are the function keys and
913 kp0 to kp9 are the number keys on the numerical keypad. All of these
914 are raw scancodes, which has two implications: First, the key names are
915 not internationalized and refer to the US keyboard layout (e.g. the Z
916 key on a German or French keyboard will actually react to the event
917 name y or w); second, modifiers will be ignored as well (e.g. the
918 numerical keypad will always generate the kpX scancodes, even if Num
919 Lock is off).
920 The mnemonic names for the other keyboard events are as follows (in
922 alphabetic order): ampersand, asterisk, at, backquote, backslash,
923 backspace, break, capslock, caret, clear, comma, down, end, escape,
924 euro, exclaim, greater, hash, help, home, insert, kp_divide, kp_enter,
925 kp_equals, kp_minus, kp_multiply, kp_plus, lalt, last, lctrl, left,
926 leftbracket, leftparen, less, lmeta, lshift, lsuper, menu, minus, mode,
927 numlock, pagedown, pageup, pause, period, plus, power, print, question,
928 quote, quotedbl, ralt, rctrl, return, right, rightbracket, rightparen,
929 rmeta, rshift, rsuper, scrollock, semicolon, slash, space, sysreq, tab,
930 underscore, up. The events prefixed with kp_ refer to keys on the
931 numerical keypad. Other than that, the names should be reasonably
932 descriptive, so they will not be described futher at this point. Also
933 note that not all keyboards and platforms support the full range of
934 keys defined in this list.
935 Mouse event names are mapped as follows:
937 lmb
939 the left mouse button
940 mmb
942 the middle mouse button
943 rmb
945 the right mouse button
946 wheelup
948 scrolling the mouse wheel upwards
949 wheeldown
951 scrolling the mouse wheel downwards
952 btnX (i.e. btn6, btn7, ...)
954 additional mouse buttons, the mapping of which is device-spe‐
955 cific; use --evtest to see which button is which
956 The event names can be prefixed with the three modifiers ctrl+, alt+
958 and shift+ to make the event valid only if the specified set of modi‐
959 fiers is pressed as well. This works for both keyboard and mouse
960 events. Multiple modifiers can be combined, but the order must match
961 the one mentioned in this paragraph. For example, ctrl+shift+x is a
962 valid event name, while shift+ctrl+x is not.
963 A simple way to determine the name associated with an event is using
965 Impressive's "Event Test Mode" by invoking impressive --evtest. In this
966 mode, the name of each incoming event will be displayed on the screen
967 (and logged to standard output), which makes it possible to determine
968 event names by experimentation.
969 SUPPORTED ACTIONS
971 The following list describes all actions supported by Impressive,
972 together with the conditions under which they will match. Note that
973 most actions will not match in overview mode and during video playback,
974 unless mentioned otherwise in the description.
975 box-add
977 Draw a highlight box if the mouse has been moved since the but‐
978 ton has been pressed down. This action must only be bound to a
979 mouse button event, otherwise it will not function properly.
980 box-clear
982 Removes all boxes from the current page.
983 box-remove
985 Removes the highlight box under the mouse cursor, if there is
986 any.
987 box-zoom
989 Define a region to zoom into by drawing a rectangle. This action
990 must only be bound to a mouse button event, otherwise it will
991 not function properly.
992 box-zoom-exit
994 If in box-zoom (but not normal zoom) mode, leave box-zoom mode.
995 fade-less, fade-more
997 Decrease or increase the amount of darkening applied to the
998 background in spotlight or highlight box mode.
999 fade-reset
1001 Resets the background darkness in spotlight or highlight box
1002 mode to its default value.
1003 fade-to-black, fade-to-white
1005 Fades to a black or white screen. Once the screen is faded out,
1006 any event except those bound to the quit action will just leave
1007 fade mode and not perform its assigned action.
1008 fullscreen
1010 Toggle fullscreen mode on platforms that support it.
1011 gamma-decrease, gamma-increase
1013 Decrease or increase the gamma level (i.e. roughly the bright‐
1014 ness) of the display on platforms that support it.
1015 gamma-bl-decrease, gamma-bl-increase
1017 Decrease or increase the black level of the display on platforms
1018 that support it.
1019 gamma-reset
1021 Reset the gamma and black level settings to their defaults.
1022 goto-end, goto-end-notrans
1024 Go to the last page of the presentation, with or without a tran‐
1025 sition.
1026 goto-last, goto-last-notrans
1028 Go to the last (i.e. most recently) visited page, with or with‐
1029 out a transition.
1030 goto-next, goto-next-notrans
1032 Go to the following page of the presentation, with or without a
1033 transition.
1034 goto-prev, goto-prev-notrans
1036 Go to the previous page of the presentation, with or without a
1037 transition.
1038 goto-start, goto-start-notrans
1040 Go to the first page of the presentation, with or without a
1041 transition.
1042 hyperlink, hyperlink-notrans
1044 Navigate to the hyperlink under the mouse cursor, if there is
1045 one. If the hyperlink is a reference to another page of the pre‐
1046 sentation, this page will be activated with or without a transi‐
1047 tion. If the hyperlink refers to an external object (e.g. an
1048 URL), it will be opened externally, if supported by the system.
1049 overview-confirm
1051 When in overview mode, confirm the selection and leave overview
1052 mode, navigating to the selected page.
1053 overview-down, overview-up
1055 When in overview mode, select the page above or below the cur‐
1056 rently selected one in the grid.
1057 overview-enter
1059 When not in overview mode, zoom out of the current page, enter‐
1060 ing overview mode.
1061 overview-exit
1063 When in overview mode, leave overview mode, zooming back to the
1064 page that has been displayed before entering overview mode.
1065 overview-next, overview-prev
1067 When in overview mode, select the following or previous page.
1068 quit
1070 Quits Impressive immediately. This action is available in all
1071 modes.
1072 save
1074 Save or update the Info Script for the current presentation.
1075 spotlight-enter
1077 If spotlight mode is not active, enable spotlight mode.
1078 spotlight-exit
1080 If spotlight mode is active, deactivate spotlight mode.
1081 spotlight-grow, spotlight-shrink
1083 When in spotlight mode, increase or decrease the radius of the
1084 spotlight.
1085 spotlight-reset
1087 When in spotlight mode, reset the spotlight radius to the
1088 default value.
1089 time-reset
1091 Reset the presentation timer.
1092 time-toggle
1094 Toggle on-screen display of the current presentation time, or
1095 wall-clock time if the --clock option is used. If this is done
1096 at the start of the presentation, before the first page has been
1097 left, time tracking mode will be enabled, like the --tracking
1098 option would have done.
1099 toggle-overview
1101 This toggles the "page is visible on overview screen" flag for
1102 the current page. This will not have an immediate effect, but it
1103 can be saved to an Info Script.
1104 toggle-skip
1106 This toggles the "skip page when navigating with goto-prev and
1107 goto-next" flag for the current page.
1108 video-pause
1110 In video playback mode, this pauses or unpauses playback.
1111 video-seek-backward-10, video-seek-backward-1, video-seek-forward-1,
1113 video-seek-forward-10
1114 In video playback mode, seek forward or backward by 1 or 10 sec‐
1115 onds.
1116 video-step
1118 In video playback mode, if playback is paused, advance one frame
1119 in the video.
1120 video-stop
1122 In video playback mode, stop playback and return to normal page
1123 display mode.
1124 zoom-enter
1126 If not in zoom mode, enter zoom mode with the zoom level config‐
1127 ured with the -z/--zoom option.
1128 zoom-exit
1130 If in zoom or box-zoom mode, leave that mode.
1131 zoom-in, zoom-out
1133 Slightly increase or decrease the current zoom level. This does
1134 not change the page's rendering resolution, it only zooms the
1135 visible part of the screen in or out, centered around the mouse
1136 cursor's position. Zoom mode is left automatically if the zoom
1137 level goes to down to 1x; conversely, zoom mode is entered when
1138 calling zoom-in while zoom mode is not active.
1139 zoom-pan
1141 If in zoom mode, the visible area of the page can be moved
1142 around with the mouse while the key or mouse button of the asso‐
1143 ciated event is held down.
1144 zoom-update
1146 If in zoom mode, re-render the current page in a resolution that
1147 best fits the current zoom level, up to the limits of the graph‐
1148 ics hardware or the --maxzoom setting. This only needs to be
1149 done explicitly when zooming with the zoom-in action; zoom-enter
1150 and box-zoom do this automatically.
1151 BINDING SYNTAX
1153 The arguments of the -e/--bind command-line option have the following
1154 basic syntax:
1155 <event> [,<event2>...] <operator> <action> [,<action2>...]
1156 In other words, it is a sequence of event names joined with commas,
1157 followed by an operator (see below) and a sequence of action names
1158 joined with commas. Multiple such binding statements can be combined
1159 into one argument by joining them with a semicolon (;).
1160 The used operator defines in which way the action list shall modify the
1162 bindings of the referenced events:
1163 = (equals sign), += (plus sign and equals sign)
1165 The specified actions will be added to the bindings of the spec‐
1166 ified events. In other words, event=action1,action2 does exactly
1167 the same as event=action1; event=action2.
1168 := (colon and equals sign)
1170 The specified actions will replace the bindings of the specified
1171 events.
1172 -= (minus sign and equals sign)
1174 The specified actions will be removed from the bindings of the
1175 specified events. For example, to make the Esc key in the
1176 default bindings not clear highlight boxes, but otherwise pre‐
1177 serve its original functionality, escape -= box-clear can be
1178 used.
1179 Other than bindings, a statement can also contain one of the following
1181 special commands:
1182 clearall
1184 Clears all current bindings.
1185 defaults
1187 Discards all current bindings and (re-)establishes the default
1188 bindings.
1189 include <filename>
1191 Loads and executes a control configuration file with a specified
1192 name.
1193 The syntax for the configuration files used with the -E/--controls
1195 option or include statement is exactly the same as for the ad-hoc con‐
1196 figuration option, except that individual bindings can be written on
1197 individual lines instead of joining them together to a single long line
1198 with semicolons. In addition, everything following a hash sign (#) on a
1199 line will be ignored as a comment.
1200 One practical example for such a configuration file can be the follow‐
1202 ing: The author of this program uses a cheap presentation remote con‐
1203 trol device that has four cursor keys, one "enter" key and a slider
1204 that switches between keyboard and mouse mode. Mouse mode works as
1205 expected, but what it does in keyboard mode is quite peculiar: the up
1206 and down keys act like Page-Up and Page-Down keys on a keyboard, the
1207 right arrow key sends the letter B to the computer, and the left key
1208 toggles between Esc and F5 each time it's pressed. The following con‐
1209 figuration file allows basic navigation and access to overview mode
1210 with this device:
1211 clearall # don't use the default bindings
1213 lmb = quit # quit Impressive by clicking in mouse mode
1214 # everything else uses keyboard mode:
1215 return = overview-enter, overview-confirm # toggle overview mode
1216 escape, f5 = overview-prev, goto-prev
1217 b = overview-next, goto-next
1218 pageup = overview-up, goto-prev
1219 pagedown = overview-down, goto-next
1220 To get a better idea of how the control configuration system works in
1222 practice, it's recommended to study the output of impressive --con‐
1223 trol-help - this not only gives a concise overview of all events and
1224 actions, but also a full dump of Impressive's default bindings that can
1225 be used as a starting point for own customizations.
1226
1228 Impressive offers a powerful way to customize individual presentations
1229 using so-called info scripts. An info script is a text file having the
1230 same name and located in the same directory as the presentation file
1231 itself, except for the additional suffix .info. Thus, a presentation
1232 file called BrandNewProduct.pdf would have a info script with the name
1233 BrandNewProduct.pdf.info. If multiple arguments were specified on the
1234 command line, the info script will be called just .info (a dot file, so
1235 to speak). If a directory name was specified as the only argument,
1236 either a file called DirectoryName.info or a file called .info inside
1237 the directory will be used, depending on whether a path separator was
1238 specified at the end of the directory name or not - Impressive simply
1239 appends .info to whatever the input path name was.
1240 In any case, the default file name can be overridden by the -I command
1241 line option.
1242 Info scripts are actually Python scripts with full access to Impres‐
1244 sive's global data structures and functions. (It is possible to write
1245 real interactive applications using info scripts.) Thus, they can mod‐
1246 ify a broad range of settings concerning Impressive. This manual will
1247 only cover the most basic ones.
1248 PAGE PROPERTIES
1250 The main part of an info script defines the properties of each page. At
1251 the moment, the following properties are defined:
1252 title
1254 Each page can have a title that is displayed in the Impressive
1255 window's title bar. If there is no title explicitly specified in
1256 the info script, the title of the page will be extracted from
1257 PDF metadata if pdftk is installed, or the image file name will
1258 be used if the presentation is an image slideshow.
1259 transition
1261 With this property, the transition class to be used for render‐
1262 ing the transition to this page (i.e. between the previous page
1263 and this page) can be specified. For pages lacking this prop‐
1264 erty, random transitions will be chosen. A list of available
1265 transition classes can be obtained with impressive -l.
1266 transtime
1268 This property overrides the global transition time parameter (-T
1269 at the command line). It contains the integer time (in millisec‐
1270 onds) the transition to this page shall take.
1271 overview
1273 This property holds a boolean value (0/False or 1/True) that
1274 specifies whether the page shall be included in the overview
1275 page. If this property isn't specified, it is assumed to be
1276 True.
1277 skip
1279 This boolean property can be set to 1/True if the page shall be
1280 skipped during the presentation.
1281 Pages with overview:True, skip:False will be accessible both by
1282 cycling through the pages and using the overview page,
1283 pages with overview:True, skip:True will be silently skipped in
1284 the normal page cycle, but remain accessible from the overview
1285 page,
1286 pages with overview:False, skip:False will appear in the normal
1287 cycle, but not on the overview page
1288 and pages with overview:False, skip:True will not be accessible
1289 at all.
1290 boxes
1292 This property stores a list of highlight box coordinates. Nor‐
1293 mally, there is no need to edit this by hand, as Impressive han‐
1294 dles this automatically if the S key is pressed.
1295 timeout
1297 If a timeout property is present and the page is shown, Impres‐
1298 sive will automatically switch to the next page after the speci‐
1299 fied number of milliseconds. Normally, the timeout will only be
1300 effective the first time the page is shown unless wrap mode is
1301 used (command-line option -w or --wrap). This restriction makes
1302 it possible to create self-running presentations with individual
1303 per-page timeouts.
1304 radius
1306 This property takes an integer value that, if defined, will be
1307 used to set a new spotlight radius every time the page is
1308 entered. This overrides the current setting as defined by the
1309 --spot-radius command line option or run-time adjustments. Note
1310 that the value is not reset to the default value after the page
1311 has been left again.
1312 darkness
1314 This property takes an integer or floating-point percentage
1315 value that, if defined, will be used to set the background dark‐
1316 ness in spotlight or highlight box mode each time the page is
1317 entered. This overrides the current setting as defined by the
1318 --darkness command line option or run-time adjustments. Note
1319 that the value is not reset to the default value after the page
1320 has been left again.
1321 zoomdarkness
1323 This property takes an integer or floating-point percentage
1324 value that, if defined, will be used to set the background dark‐
1325 ness in box-zoom mode each time the page is entered. This over‐
1326 rides the current setting as defined by the --zoomdarkness com‐
1327 mand line option or run-time adjustments. Note that the value is
1328 not reset to the default value after the page has been left
1329 again.
1330 comment
1332 This property can hold a string with a single line of text that
1333 will be displayed on screen while the page is shown. Display of
1334 this text can not be disabled.
1335 sound
1337 Specifies the file name of a sound file to be played (via
1338 MPlayer) when the page is first entered. Once started, the sound
1339 will be played until its end is reached, another sound or video
1340 is played, or Impressive is exited.
1341 video
1343 Specifies the file name of a video file to be played when the
1344 page is first entered. The video will be displayed full-screen.
1345 Any key or mouse click stops playback, except the cursor keys,
1346 which are used to seek in the video file, and space, which can
1347 be used to pause playback.
1348 Please not that this function is still somewhat experimental. It
1349 uses an external player application (MPlayer, or omxplayer on
1350 Raspberry Pi) to perform the actual playback, and embeds it into
1351 Impressive's window.
1352 always
1354 If this property is present and set to 1 or True, the media file
1355 specified in the sound or video properties will be played every
1356 time the page is entered, not just the first time.
1357 progress
1359 If this property is set to zero, the presentation progress bar
1360 (which is usually set up with the -d/--duration command line
1361 switch) will not be shown on this page. In practice, it might be
1362 useful to hide the bar from the first page so that it is not
1363 visible during the introduction.
1364 reset
1366 If this property is set to 1 or True, the timer will be reset
1367 each time this page is left, just as if the R has been pressed.
1368 If the special value 2 or FirstTimeOnly is used, the reset will
1369 only take place if the page was shown for the first time. Again,
1370 this is particularly useful on the first page: A combination of
1371 progress:False, reset:FirstTimeOnly makes it possible to set up
1372 the presentation long before it actually begins - the first page
1373 can be showed as long as desired, actual timing starts at the
1374 second page.
1375 rotate
1377 This property is a per-page override of the global -r command
1378 line option: It specifies how the page shall be rotated, in
1379 90-degree steps clockwise.
1380 OnEnter, OnLeave, OnEnterOnce, OnLeaveOnce
1382 These properties can contain a Python callable (i.e. a function
1383 reference or lambda expression) that is executed when the page
1384 is entered or left. The ~Once variants will only be executed
1385 when the page is entered or left for the first time. The
1386 callable must not take any arguments. This feature can be used
1387 to associate arbitrary Python code with specific pages, for
1388 example to execute external programs.
1389 Warning: Lambda expressions cannot be properly processed by the
1390 Info Script save function (S key). If Impressive encounters
1391 lambda expressions when saving, it will remove them. In addi‐
1392 tion, it will not overwrite the original info script, but gener‐
1393 ate an extra file that needs to be merged withe the original
1394 script by hand.
1395 keys
1397 This property can be assigned a dictionary that maps alphanumer‐
1398 ical keys to Python functions. For example, 'keys': { 'x': Some‐
1399 Function } will invoke SomeFunction() if the lowercase character
1400 'x' is typed while the page is displayed. Regarding the func‐
1401 tions, the same restrictions as for the OnEnter/OnLeave family
1402 apply: the function must not take any parameters and lambda
1403 functions can not be saved. Also note that it is not possible to
1404 overwrite Impressive's pre-defined key bindings with this
1405 method.
1406 invert
1408 This property specifies whether the colors of that page shall be
1409 inverted in the same way the --invert command-line switch does.
1410 It overrides the --invert setting on a per-page basis: If set to
1411 True, the page will always be inverted; if set to False, the
1412 page will never be inverted even if --invert has been specified
1413 on the command line.
1414 Note that in Impressive versions prior to 0.11.0, the transition and
1416 transtime properties defined the transition from the current page to
1417 the next, not from the previous page to the current one.
1418 The properties are stored together in a Python dictionary called Page‐
1420 Props. The syntax looks like in this example:
1421 PageProps = {
1423 1: {
1424 'title': "Title Page",
1425 'transition': PagePeel,
1426 'sound': "background_music.mp3"
1427 },
1428 2: {
1429 'title': "Another Page",
1430 'timeout': 5000
1431 }
1432 }
1433 The PageProps definition (and only the PageProps definition) will be
1435 rewritten by Impressive if the S key is pressed. User-defined PageProps
1436 entries will also be left untouched, except for some pretty-printing.
1437 GLOBAL PRESENTATION PROPERTIES
1439 The name of the presentation is shown in the title bar of the Impres‐
1440 sive window (if not in fullscreen mode). By default, the file name or
1441 (if available) PDF metadata title will be used for this purpose, but
1442 the presentation title can also be explicitly set by overwriting the
1443 DocumentTitle variable:
1444 DocumentTitle = "My Presentation"
1445 Another useful variable, AvailableTransitions, contains a list of all
1447 transition classes that may be used for randomly assigning transitions
1448 to pages lacking the transition property. Thus, if a certain transition
1449 is undesired (either because of personal dislike or because it shall be
1450 used exclusively on pages where it is manually assigned using Page‐
1451 Props), something like the following can be written:
1452 AvailableTransitions.remove(WipeBlobs)
1453 On the other side, it's possible to activate transitions that are not
1454 enabled by default:
1455 AvailableTransitions += [SlideUp, SlideDown]
1456 Alternatively, AvailableTransitions can be completely overwritten to
1457 have the same transition (or set of transitions) assigned to all pages:
1458 AvailableTransitions = [Crossfade]
1459 OPTION OVERRIDES
1461 Another use of info scripts is overriding the default or command-line
1462 settings on a per-file basis. This can be done by simply overwriting
1463 one of the variables that are defined at the beginning of impres‐
1464 sive.py. Each of these variables corresponds either to a command-line
1465 setting, or to some constant related to visual appearance or perfor‐
1466 mance. So, for example, to force fullscreen mode for a presentation,
1467 write
1468 Fullscreen = True
1469 WORKING DIRECTORIES
1471 The working directory while executing the info scripts themselves is
1472 always the directory in which the info script is stored in.
1473 The base directory for external actions that originate from Page Prop‐
1475 erties or PDF hyperlinks is always the directory of the PDF or image
1476 file this page belongs to. In other words, if e.g. 'sound': "music.mp3"
1477 is written in the info script for one page of presentation.pdf, the
1478 file music.mp3 is expected to be located in the same directory as pre‐
1479 sentation.pdf.
1480
1482 Impressive and its documentation has been written mainly by Martin J.
1483 Fiedler <martin.fiedler@gmx.net>, with small portions of the code writ‐
1484 ten by external contributors. See the source code file for details.
1485
1487 Report bugs to to <martin.fiedler@gmx.net>.
1488Martin J. Fiedler 2018-02-04 IMPRESSIVE(1)