Provided by: impressive_0.11.1-1_all 
NAME
Impressive - presentation tool with eye candy
SYNOPSIS
impressive [OPTIONS...] FILES...
DESCRIPTION
Impressive is a simple presentation program that displays slideshows of image files (JPEG,
PNG, TIFF and BMP) or PDF documents. Rendering is done via OpenGL, which allows for some
"eye candy" effects.
A somewhat-modern GPU (graphics processing unit) supporting OpenGL 2.0 or OpenGL ES 2.0
and appropriate drivers is required to run Impressive.
OPTIONS
-a <seconds> or --auto <seconds>
Automatically advance to the next page after the given number of seconds. Together
with the -w option (described below), this can be used to create automatic
slideshows.
-A <X>:<Y> or --aspect <X>:<Y>
Specifies the display aspect ratio. Normally, Impressive assumes that the pixel
aspect ratio is 1:1 (square pixels), regardless of the display resolution that has
been set up. If a resolution has been selected that doesn't match the display's
aspect ratio, the screen will be distorted. To overcome this, this option may be
used to manually specify the display aspect ratio, e.g. "-A 16:9". Note that this
option has no effect if the MuPDF backend is used for rendering.
-b or --noback
Disables background rendering. By default, Impressive will pre-render all pages in
a separate background thread while the presentation runs. If this option is
specified, it will instead render all pages immediately on startup. This option has
no effect if caching is disabled (--cache none, see below).
-B <ms> or --boxfade <ms>
Sets the duration (in milliseconds) of the highlight box fade-in/fade-out
animation. Default value: 100 ms.
-c <mode> or --cache <mode>
Specifies the page cache mode to use. Valid options are:
none
Disables page caching altogether, only the current and the following page
will be kept in RAM. Jumping between pages will be very slow, because
Impressive will need to render the requested pages on the fly. In addition,
the overview page won't be complete until every page has been shown at least
once.
memory
Caches all page images in memory. This is the fastest method, but it
requires very large amounts of memory (about 3 MiB per page at 1024x768
resolution).
compressed or z
Caches all page images in memory as well, but in compressed form. This will
be a little slower than memory mode, but on pages with uniform backgrounds,
this will easily reduce the required amount of RAM by a factor of 20.
disk
Like memory, but uses a temporary file rather than memory for storage. This
is the default.
persistent
Uses a permanent cache file for caching. This file will not be deleted when
Impressive quits and will be reused on subsequent invocations. The default
name for the cache file is derived like the names for Info Scripts (see
below for an explanation), but with a .cache file name extension instead of
.info. This method is a little bit slower than disk mode, but the time span
until the overview page is fully populated will be significantly decreased
if Impressive is ran again with the same input files and options.
The mode name may be abbreviated at will, down to one character. Thus, --cache
persistent, -c persist and even -cp are all synonyms.
-C <filename>[:<X>,<Y>] or --cursor <filename>[:<X>,<Y>]
This option can be used to specify an image that shall be used as a (software)
mouse cursor instead of the normal (hardware) one. It can either be a name of an
image file (typically a transparent .png) or one of the special values "-" (dash)
or "default", both of which select a built-in cursor image. On platforms that do
not support a hardware cursor, this default cursor will also be used as a default
if this option is not used.
If the name of an external file is specified, the position of the hotspot (the
pixel inside the cursor where the actual mouse position is located) can be
specified as well, for example: --cursor mycursor.png:2,4.
--clock
If this option is enabled, the current time will be shown instead of the elapsed
time if time display is activated (with the T key in the default control
configuration). Compatible with the -M option.
--control-help
This option will output a short help screen of how the control configuration
(keyboard and mouse bindings) work, along with a list of all recognized events and
actions and a dump of the current bindings (which is the default configuration if
no other -e/--bind or -E/--controls options precede this option). After that,
Impressive will exit; no presentation will be started.
-d <time> or --duration <time>
Specifies the expected run time of the presentation. The time parameter can be
either a number of seconds or a human-readable time like 1:23 (1 minute and 23
seconds), 4:56h (4 hours and 56 minutes), 3m45s (3 minutes and 45 seconds), 5m (5
minutes) or 1:23:45 (1 hour, 23 minutes and 45 seconds).
If an expected duration is specified, Impressive will show a semi-transparent green
progress bar at the lower edge of the screen, indicating how much time has already
passed. If the time is up, the bar will occupy the whole edge and fade to yellow
(at 125% of the expected time) to red (at 150% or more).
-D <ms> or --mousedelay <ms>
Sets the time (in milliseconds) the mouse cursor is shown in fullscreen mode if it
is not moved. There are two special values: 0 (zero) shows the mouse cursor
permanently, 1 (one) hides it completely. The default value is 3000 ms.
--darkness <percentage>
Specifies how much the screen shall become darker when using highlight boxes or
spotlight mode. The value is specified in percent, with 25 being the default. A
value of zero would mean no darkening at all (the screen would just be blurred
slightly, and desaturated if the graphics hardware supports it), and a value of 100
would make everything but the highlighted parts of the screen black.
-e <bindings> or --bind <bindings>
Configures keyboard or mouse bindings. For the syntax of the argument, refer to the
Control Configuration section of the manual.
-E <filename> or --controls <filename>
Loads a configuration file for keyboard and mouse bindings. For the syntax of these
files, refer to the Control Configuration section of the manual.
--evtest
If this option is specified, Impressive will not start a normal presentation, but
instead enter the so-called "Event Test Mode" after the display has been
initialized. In this mode, Impressive will simply capture all keyboard and mouse
events and display the name of the last event on the screen. In addition, events
will be logged to standard output. This mode helps with determining the event names
for each key when creating a custom control configuration (see the Control
Configuration section).
-f
Sets the window/fullscreen mode Impressive shall start up with. This option can be
specified multiple times; each times it is found, the next of the three options is
selected, in the follwing order: (1.)True fullscreen mode, including setting the
video mode. This is the default mode. (2.)Windowed mode, where Impressive runs in a
standard window. (3.)"Fake-fullscreen" mode, where fullscreen is emulated by uding
a window without border that fills the whole screen. Setting the display resolution
is not possible in this mode. Each of these modes has a corresponding long option
that enables it directly (--fullscreen, --windowed and --fake-fullscreen).
--fullscreen
Starts Impressive in fullscreen mode (the default). See the discussion of the -f
option for details.
--fake-fullscreen
Starts Impressive in "fake fullscreen" mode. See the discussion of the -f option
for details.
-F <file> or --font <file>
Impressive uses some kind of text OSD to overlay the current page number and title
(if available) on the overview page. This option can be used to specify a TrueType
font file (.ttf) to use for the OSD. If the path specified doesn't directly point
to a useable font file, Impressive will try to search the system font directories.
It assumes that all fonts are stored below /usr/share/fonts, /usr/local/share/fonts
or /usr/X11R6/lib/X11/fonts/TTF for this purpose (the latter one is useful for Mac
OS X systems specifically). If this option is not specified, any of DejaVuSans.ttf
or Vera.ttf (the typical file name of Bitstream Vera Sans) will be used as a
default.
-g <width>x<height>[+<posX>+<posY>] or --geometry <width>x<height>[+<posX>+<posY>]
Sets the screen size or resolution Impressive shall use (in pixels). If xrandr is
installed, the default screen size for fullscreen mode is the current screen
resolution; on other platforms, Impressive uses the highest resolution available to
the graphics system. If a standard resolution cannot be determined, the default is
1024x768 pixels. This is also the default for windowed mode.
Furthermore, if the additional parameters posX and posY are present, they specify
the position of the upper-left corner of the window (relative to the upper-left
corner of the desktop), in pixels, for windowed and fake-fullscreen mode. The
values are ignored in "true" fullscreen mode.
-G <gamma>[:<blacklevel>] or --gamma <gamma>[:<blacklevel>]
Sets up the startup gamma and (optional) black level value. The black level is the
original image's intensity level (0...254) that is to be mapped to black in
Impressive's output. Note that gamma and black level adjustments may be unavailable
or constrained on some systems.
-h or --help
If this option is specified, Impressive writes a short command line help screen to
standard output and does not start a presentation.
-H or --half-screen
This option makes Impressive show the overview page and OSD elements on the right
half of the screen only. The overview page will only show the left half of the
slides as previews. Using a multi-monitor setup with a wide virtual screen and
specially crafted slides (e.g. those that can be generated with LaTeX's beamer
class), this makes it possible to have presenter's notes on the second screen.
Note that transitions and animations are still operating on the whole screen,
making some of them (like PagePeel) look ugly. Impressive also disables the
overview zoom animation in half-screen mode; it can be re-enabled by explicitly
setting it to another value with a later command line option (--zoomtime).
Another limitation is that the allocation of the screen halves (slides left,
overview right) is fixed.
-i <page> or --initialpage <page>
Specifies the page number to start with. The default value is 1 (start with the
first page). If another value is specified, the page shown by Impressive right
after initialization is not the first one of the PDF or image list. Additionally,
pre-rendering (if enabled) will also start at the specified page.
-I <filename> or --script <filename>
Overrides automatic derivation of the info script filename and specifies a script
file directly.
--invert
This option makes Impressive invert the colors of each page, turning black to white
and vice-versa. Note that it is a full RGB inversion, so it will, for example, turn
dark green to light purple (and vice-versa) too.
-k or --auto-progress
This option makes Impressive show a progress bar at the bottom of the screen,
visualizing the timeout on pages that have one (either specified as a page property
or using the --auto command-line option). Nothing is done on pages that don't have
a timeout.
The progress bar shown by this option takes precedence over the --duration or
--page-progress bars: If one of these options is specified as well, the timeout
progress bar will be shown on pages with a timeout, and the other progress bar will
be shown on pages without one.
-l or --listtrans
If this option is specified, Impressive writes a list of all available transition
classes to standard output and does not start a presentation. Transitions that are
enabled by default are marked with a star (*) left of the class name.
-L <spec> or --layout <spec>
Specifies the OSD layout. Read below for an explanation of this option
--min-box-size <pixels>
This option sets the minimum size of a highlight box, in pixels. Boxes that are not
this many pixels wide and high are rejected in order to prevent accidental creation
of highlight boxes. The default value for this is 30 pixels.
-M or --minutes
If this option is set, Impressive will show the on-screen timer (activated with the
[T] key) only with 1 minute resolution. By default, it will show a timer with 1
second resolution.
--noblur
By default, Impressive uses a fragment shader to blur and desaturate the image when
in highlight box or spotlight mode. This is usually the faster and nicer-looking
method; however, some very old hardware implementations can't deal with that shader
and fall back to an unusably slow software implementation. Impressive tries to
detect scenarios where this would happen and automatically falls back to a
different implementation.
There might be situations where this machanism fails and Impressive tries to use
the non-functional shader anyway. In these cases, the --noblur option can be used
to enforce the fallback implementation.
--noclicks
If this option is enabled, switching to the previous or next page with the left and
right mouse buttons is deactivated. The keyboard shortcuts are unaffected from
this.
Note that this option only works as intended when the default controls are used. If
the -e/--bind or -E/--controls options have been used, --noclicks might not have
the intended effect.
--nologo
This option disables the Impressive logo and version number display. Instead, the
loading screen will be just black or, if background rendering is disabled, only the
progress bar will be visible.
-o <directory> or --output <directory>
Do not display the presentation, but render it into a series of PNG image files
inside the specified directory. The images will be generated in the current
resolution as specified by the -g option. This option is useful if the presentation
is to be given on on a foreign PC with an old, broken or otherwise problematic Xpdf
installation: By generating images of the PDF pages, is is made sure that no
rendering bugs will happen on the target system.
-O <mode> or --autooverview <mode>
Enables or disables automatic derivation of whether a page shall or shall not be
shown on the overview page. This feature is based on the fact that some LaTeX
presentation packages tag all pages with a title (that can be read by Impressive
with the help of pdftk), except those that contain multiple reveal steps.
The following modes are available:
off
Disables automatic overview mode. All pages will be shown on the overview
page by default. This is also the default setting.
first
All pages with a PDF title will be shown on the overview page. The purpose
is to show the initial state of multi-step slides on the overview page.
last
All pages before a page with a PDF title will be shown on the overview page.
The purpose is to show the final state of multi-step slides on the overview
page.
Again, the mode may be abbreviated arbitrarily, down to one character, just like
with the -c option above..
-p <start>-<end> or --pages <start>-<end>
Using this option, the range of the page displayed can be narrowed down. The
presentation will start at the first page in the range. All pages outside of the
range will not be shown on the overview page and will not be cached. However, they
can be entered manually when cycling through the presentation. Due to the fact that
these pages are uncached, preparation of the display will take considerably longer.
-P <path> or --gspath <path>
This option can be used to override the Xpdf / GhostScript path autodetection. The
full path to the executable of either GhostScript (gs or gs.exe) or Xpdf's pdftoppm
utility must be specified.
-q or --page-progress
If this option is enabled, Impressive will show a light-blue semi-transparent
progress bar at the lower edge of the screen that shows the position inside the
presentation, i.e. the relation between the current page number and the total
number of pages. Note that this progress bar will not be shown if the duration
progress bar (-d option) is also enabled.
-Q or --autoquit
If this option is specified, Impressive quits automatically when trying to navigate
to the page after the last page or the page before the first page.
This option does not have any effect if --wrap is used.
-r <n> or --rotate <n>
Display all pages rotated by nx90 degrees clockwise. Try -r 1 or -r 3 if there are
problems with PDFs generated by LaTeX on some Xpdf or GhostScript versions.
-s or --scale (image input only)
If a directory with image files is used as input, Impressive will scale down images
that are too big for the screen. But by default, it will not scale up smaller
images to fit the screen; it will leave a black border instead. This option
overrides this setting and enables upscaling of smaller images.
-s or --supersample (PDF input only)
This switch enables antialiasing by 4x supersampling instead of the normal
multisampling method used by Xpdf or GhostScript. While this usually degrades both
visual quality and performance, it may be necessary for circumventing white strips
or moire-like patterns in gradients.
-S <pixels> or --fontsize <pixels>
This option sets the size, in pixels, of the OSD font. The default value is 14.
--spot-radius <pixels>
This option sets the initial radius of the spotlight, in pixels. The default value
is 64.
-t <ms> or --transition <trans1[,trans2...]>
Using this switch, the set of transitions Impressive will randomly draw at page
changes can be specified. If only one transition class is specified, this class
will be used for all pages that do not have another transition explicitly assigned
in their page properties. Multiple transitions have to be separated by commas; they
will be used in random order. The -l option can be used to get a list of available
transitions.
-T <ms> or --transtime <ms>
Sets the duration (in milliseconds) of page transitions. 0 (zero) disables
transitions altogether. Default value: 1000 ms.
--tracking
This option enables time tracking mode. In this mode, a report of all pages visited
with their display duration, enter and leave times will be written to standard
output. This can be very useful when preparing presentations.
-u <seconds> or --poll <seconds>
If this option is specified, the source file or directory will be checked for
changes regularly. If a change in the input PDF file or any of the image files in
the input image directory is detected, the page cache will be flushed and the
current page as well as the info script will be reloaded. The current page's
transition will be shown between the old and the new version of the page.
The new PDF file must have at least as much pages as the old one; also, it should
have the same aspect ratio. If the input is a directory, image files must not have
disappeared.
-v or --verbose
This option makes Impressive more verbose, i.e. it will print slightly more
informational messages than usual.
-V <pixels> or --overscan <pixels>
PDF files often contain tiny amounts of white borders around the edges which look
bad in screen presentations. To eliminate this problem, Impressive uses "overscan":
PDF files will not be rendered to fit the screen size exactly, but they will be
rendered a bit larger so that the (possibly broken) borders can be cropped off. The
amount of overscan, in screen pixels, can be set with this option. The default
value is 3 pixels, which should remove borders in most presentations at most common
screen resolutions without cropping the pages too much.
-w or --wrap
If this option is set, Impressive will "wrap" over to the first page after the last
page. In other words, advancing to the next page at the end of the presentation
will restart the whole presentation.
-W or --nowheel
By default, it is possible to change pages using the mouse wheel. This option
disables this behavior, which can be useful to prevent spurious page changes if the
mouse wheel is likely to be moved by accident.
Note that this option only works as intended when the default controls are used. If
the -e/--bind or -E/--controls options have been used, --noclicks might not have
the intended effect.
--windowed
Starts Impressive in windowed mode. See the discussion of the -f option for
details.
-x or --fade
This option enables a smooth fade-in effect at the start of the presentation and a
fade-out effect just before Impressive quits.
-X or --shuffle
If this option is enabled, the input files will be shuffled into random order
before starting the presentation. The individual pages of PDF input files will stay
in their original order, though, so this option is mainly useful for image
presentations.
-y or --auto-auto
This option can be used together with --duration to have Impressive compute a page
timeout (as with the --auto option) automatically. This results in a presentation
that runs automatically, displaying each slide for the same time, so that the
desired total duration will be reached (almost) exactly.
-z <factor> or --zoom <factor>
Sets the zoom factor that is used in zoom mode. It must be an integer value of at
least 2. The default value is 2. Note that it might not be possible to get
high-quality zooming for large zoom factors due to hardware restrictions. Also,
note that if the hardware doesn't support non-power-of-two textures or if the -e
option is used, the number must be a power of two.
-Z <ms> or --zoomtime <ms>
Sets the duration (in milliseconds) of the overview page zoom-in/zoom-out effects.
Default value: 250 ms.
--cachefile <filename>
Activates persistent cache mode and specifies the name of the cache file to use.
ARGUMENTS
Following the options, the input file name(s) must be specified. Recognized file types are
PDF, JPEG, PNG, TIFF, BMP and PGM/PPM. If the name of a directory is put on the command
line, all recognized image files (no PDF files!) in this directory will be played in
alphanumeric order (case-insensitive).
In addition, Impressive can use a text file containing a list of files or directories to
show: This text file must contain at most one file name per line; every character after a
hash sign (#) is treated as a comment and will be ignored. If such a comment is put on the
same line as an image file name, it will be used as the page's title. List file names must
be prefixed with an at sign (@) on the command line, e.g. impressive @my_list_file.
Impressive will also expand wild-card characters (* and ?) if this isn't already done by
the shell, but apart from that, it will not reorder the arguments. Thus, it will show the
documents in the order specified at the command line.
LAYOUT OPTIONS
The OSD layout option (-L/--layout) accepts a string with comma-separated key=value pairs.
The following keywords are recognized:
alpha
The opacity of the OSD text, either as a floating-point value between 0 and 1 or a
percentage between 2 and 100.
margin
The distance (in pixels) of the OSD text to the screen borders.
time
The position of the timer.
title
The position of the page title in overview mode.
page
The position of the page number in overview mode.
status
The position of the status line.
The position specifications are composed by one character that indicates whether the text
shall be displayed at the top (T) or bottom (B) edge of the screen and one character that
indicates whether it shall appear on the left (L), on the right (R) or centered (C).
For example, the default OSD layout equals the following option string:
-L margin=16,alpha=1,time=TR,title=BL,page=BR,status=TL
EXAMPLES
The following examples illustrate some typical command lines. They assume that Impressive
can be run by simply typing "impressive" on the command line. Depending on how Impressive
is installed, this has to be substituted with the actual way to run Impressive (e.g.
"python ~/impressive/impressive_dev.py" for a fresh SVN checkout). Furthermore, the file
"demo.pdf" is used as the document to show here; obviously this has to be replaced by the
path to the actual PDF file too.
In the simplest case, Impressive is run directly with the name of the file to show and no
further parameters. This will start a full-screen presentation with all settings at their
defaults:
impressive demo.pdf
To just quickly check a slide deck, it might make sense to run Impressive in a small
window and not full-screen. This can be done with something like
impressive -f -g 800x600 demo.pdf
Impressive can also be used in digital signage scenarios, like displays in shop windows
with a permanent slideshow. This can be achieved by having Impressive advance to the next
page automatically after a specified time (e.g. 10 seconds) and re-start the presentation
from the start after the last slide:
impressive -a 10 -w demo.pdf
USAGE
On startup, Impressive will display a black screen with the program logo at the center. If
caching is enabled, but background rendering is disabled, all pages of the presentation
will then be rendered once. A bar in the lower half of the screen displays the progress of
this operation. Any key or mouse click (except for those that quit Impressive, typically Q
and Esc) skips this process, with the effect that Impressive will render the remaining
pages on demand. Please note that the overview page will not be complete until every page
has been rendered at least once. In other words, if the precaching process was skipped,
placeholders will be displayed for all pages that have not been rendered yet. By default,
Impressive will build up the cache in the background while the presentation runs. Thus,
the progress bar will not appear and the preparation will only take the amount of time
required to render the first two pages of the presentation. After this initialization
process, Impressive will switch to the first page directly and without any transition.
DEFAULT CONTROLS
The keyboard and mouse controls used by Impressive are configurable (with very few
exceptions). The default controls are as follows:
Esc key
Return from the currently active special mode (zoom, overview, spotlight, highlight
boxes); if no such special mode is active, quit Impressive altogether.
Q key or Alt+F4
Quit Impressive immediately.
LMB (left mouse button), mouse wheel down, Page Down key, Cursor Down key, Cursor Right
key or Spacebar
Go to the next page (using a transition).
RMB (right mouse button), mouse wheel up, Page Up key, Cursor Up key, Cursor Left key or
Backspace key
Go to the previous page (using a transition).
Home key / End key
Go directly to the first or last page of the presentation.
Ctrl key (modifier)
If one of the page navigation keys (Page Up/Down, Cursor keys, Space, Backspace,
Home, End) is pressed while the Ctrl key is held down, the destination page will be
entered immediately, without a transition.
L key
Return to the last (most recently displayed) page. This can be used to toggle back
and forth between two pages.
F key
Toggle fullscreen mode.
Tab key
Zoom back to the overview page. While in overview mode, a page can be selected with
the mouse and activated with the left mouse button. The right or middle mouse
button or the Tab key leave overview mode without changing the current page.
MMB (middle mouse button)
In normal display mode, this acts like the Tab key: it zooms back to the overview
page. If the page is zoomed in, it will return to normal mode.
LMB over a PDF hyperlink
Jump to the page referenced by the hyperlink. Two types of hyperlinks are
supported: Links that point to some other page of the same document, and URL
hyperlinks like Web links and e-mail addresses. This feature is only available if
pdftk is installed. Furthermore, xdg-open from the freedesktop.org Portland project
is required for URL links to work. Please note that the hyperlink feature will not
work properly when pages are rotated.
click&drag with LMB (left mouse button)
Create a new highlight box. While at least one highlight box is defined on the
current page, the page itself will be shown in a darker, blurry and (if supported
by the graphics hardware) desaturated rendition. Only the highlight boxes will be
displayed in their original lightness, sharpness and color saturation.
If a page with highlight boxes is left, the boxes will be saved and restored the
next time this page is shown again.
RMB (right mouse button) over a highlight box
If the right mouse button is clicked while the mouse cursor is above a highlight
box, the box will be removed. If the last box on a page is removed, the page will
turn bright and sharp again.
S key
Save the info script associated with the current presentation. The main purpose for
this is to permanently save highlight boxes or keyboard shortcuts, so they will be
restored the next time this presentation is started.
T key
Activate or deactivate the time display at the upper-right corner of the screen. If
the timer is activated while the very first page of the presentation is shown, it
activates time tracking mode, just as if the command-line option --tracking had
been specified.
R key
Reset the presentation timer.
C key
Removes ("clears") all highlight boxes from the current page.
Return key or Enter key
Toggle spotlight mode. In this mode, the page is darkened in the same way as if
highlight boxes are present, but instead of (or in addition to) the boxes, a
circular "spotlight" will be shown around the mouse cursor position, following
every motion of the mouse cursor.
+ / - key, 9 / 0 key or mouse wheel in spotlight mode
Adjust the spotlight radius.
Ctrl+9 or Ctrl+0 keys
Resets the spotlight radius to the default value, i.e. the value that has been set
up by the radius page property, the --spot-radius command-line option or
Impressive's built-in default.
7 / 8 key
Adjust the amount of darkening applied to the page in spotlight or highlight box
mode.
Ctrl+7 or Ctrl+8 keys
Resets the amount of darkening in spotlight or highlight box mode to the default
value, i.e. the value that has been set up by the darkness page property, the
--darkness command-line option or Impressive's built-in default.
Z key
Toggle zoom mode. When this key is first pressed, the current page will zoom in.
The page will be displayed at double size, but in its original resolution (i.e. it
will be blurry). Impressive will re-render the page at the new resolution if the
graphics hardware supports it. During this time, Impressive will not accept any
input, so don't even think about clicking the mouse or pressing keys before the
image gets crisp again.
In zoom mode, all other functions will work as normal. Any operations that leave
the current page, such as flipping the page or entering the overview screen, will
leave zoom mode, too.
[ / ] key
Adjust the gamma value of the display (might not be supported on every hardware).
{ / } key
Adjust the black level of the display (might not be supported on every hardware).
\ key
Revert gamma and black level back to normal.
O key
This will toggle the "visible on overview page" flag of the current page. The
result will not be visible immediately, but it can be saved to the info script
(using the S key) and will be in effect the next time the presentation is started.
I key
This will toggle the skip flag of the current page. A page marked as skipped will
not be reachable with the normal forward/backward navigation keys.
B / W key or . (dot) / , (comma) key
Fade to black or white, respectively. This feature can be used if a whiteboard or
blackboard in front of the projection area is to be used during the presentation.
Using these two keys, the screen will fade into a solid color. On any keypress or
mouse click, it will fade back to normal. These keys are not available in overview
mode.
click&drag with RMB (right mouse button) in zoom mode
Move the visible part of the page in zoom mode.
Cursor keys in overview mode
Navigate through pages.
Alt+Tab keys
If Impressive is in fullscreen mode, the window will be minimized so that other
applications can be used.
Any alphanumeric (A-z, 0-9) or function key (F1-F12) that is not bound to a specific
action mentioned above or configured by the user (see below) can be used to assign
shortcuts to pages that require quick access. If one of the keys is pressed together with
Shift, the currently displayed page is associated with this key. To recall the page later,
it is sufficient to press the shortcut key again. Shortcuts can be stored permanently with
the S key.
CONTROL CONFIGURATION
As already mentioned in the previous chapter, the keyboard and mouse bindings of
Impressive can be widely configured. The only exceptions are the Alt+F4 and Alt+Tab key
combinations that will always quit or minimize Impressive, respectively. For everything
else, there is a versatile configuration system in place; the controls described in the
previous section are merely the defaults.
Impressive's control system works by associating events with actions. An event is a key on
the keyboard, a mouse button or a mouse wheel movement. An action is something that is
performed by Impressive as a result of an event, like going to the next page, switching to
overview mode or quitting the program. The association of an event to an an action is
called a binding. Multiple events can be bound to the same action (like the page down and
space keys in the default setting, both of which go to the next page); furthermore,
multiple actions can be bound to the same event. In fact, bindings do not associate events
with single actions at all, but with chains of actions. Only the first action in the chain
that matches (i.e. makes sense in) the current context will be executed if the event
fires; all other actions will be ignored. If no action matches, no action will be
performed and the event will be ignored.
One example of such an action chain is the default binding for the left mouse button,
which draws a highlight box if the mouse cursor moved, or visits a hyperlink if the mouse
cursor hovers over one, or goes to the next page if none of the other conditions are met.
Both events and actions have mnemonic names that are used in the command-line options and
configuration files used for setting up bindings. Event and actions names are generally
case-insensitive, though the canonical notation is lowercase.
If an event or action specified on the command line or in a configuration file is not
recognized by Impressive, an error message will be written to the console and the
offending event or action will be ignored. Errors in control configuration are thus always
non-fatal.
SUPPORTED EVENTS
Keyboard events are generally named after the keys they refer to. Consequently, the events
a to z and 0 to 9 mean the respective letter and number keys on the main keyboard, f1 to
f12 are the function keys and kp0 to kp9 are the number keys on the numerical keypad. All
of these are raw scancodes, which has two implications: First, the key names are not
internationalized and refer to the US keyboard layout (e.g. the Z key on a German or
French keyboard will actually react to the event name y or w); second, modifiers will be
ignored as well (e.g. the numerical keypad will always generate the kpX scancodes, even if
Num Lock is off).
The mnemonic names for the other keyboard events are as follows (in alphabetic order):
ampersand, asterisk, at, backquote, backslash, backspace, break, capslock, caret, clear,
comma, down, end, escape, euro, exclaim, greater, hash, help, home, insert, kp_divide,
kp_enter, kp_equals, kp_minus, kp_multiply, kp_plus, lalt, last, lctrl, left,
leftbracket, leftparen, less, lmeta, lshift, lsuper, menu, minus, mode, numlock, pagedown,
pageup, pause, period, plus, power, print, question, quote, quotedbl, ralt, rctrl, return,
right, rightbracket, rightparen, rmeta, rshift, rsuper, scrollock, semicolon, slash,
space, sysreq, tab, underscore, up. The events prefixed with kp_ refer to keys on the
numerical keypad. Other than that, the names should be reasonably descriptive, so they
will not be described futher at this point. Also note that not all keyboards and platforms
support the full range of keys defined in this list.
Mouse event names are mapped as follows:
lmb
the left mouse button
mmb
the middle mouse button
rmb
the right mouse button
wheelup
scrolling the mouse wheel upwards
wheeldown
scrolling the mouse wheel downwards
The event names can be prefixed with the three modifiers ctrl+, alt+ and shift+ to make
the event valid only if the specified set of modifiers is pressed as well. This works for
both keyboard and mouse events. Multiple modifiers can be combined, but the order must
match the one mentioned in this paragraph. For example, ctrl+shift+x is a valid event
name, while shift+ctrl+x is not.
A simple way to determine the name associated with an event is using Impressive's "Event
Test Mode" by invoking impressive --evtest. In this mode, the name of each incoming event
will be displayed on the screen (and logged to standard output), which makes it possible
to determine event names by experimentation.
SUPPORTED ACTIONS
The following list describes all actions supported by Impressive, together with the
conditions under which they will match. Note that most actions will not match in overview
mode and during video playback, unless mentioned otherwise in the description.
box-add
Draw a highlight box if the mouse has been moved since the button has been pressed
down. This action must only be bound to a mouse button event without modifiers,
otherwise it will not function properly.
box-clear
Removes all boxes from the current page.
box-remove
Removes the highlight box under the mouse cursor, if there is any.
fade-less, fade-more
Decrease or increase the amount of darkening applied to the background in spotlight
or highlight box mode.
fade-reset
Resets the background darkness in spotlight or highlight box mode to its default
value.
fade-to-black, fade-to-white
Fades to a black or white screen. Once the screen is faded out, any event except
those bound to the quit action will just leave fade mode and not perform its
assigned action.
fullscreen
Toggle fullscreen mode on platforms that support it.
gamma-decrease, gamma-increase
Decrease or increase the gamma level (i.e. roughly the brightness) of the display
on platforms that support it.
gamma-bl-decrease, gamma-bl-increase
Decrease or increase the black level of the display on platforms that support it.
gamma-reset
Reset the gamma and black level settings to their defaults.
goto-end, goto-end-notrans
Go to the last page of the presentation, with or without a transition.
goto-last, goto-last-notrans
Go to the last (i.e. most recently) visited page, with or without a transition.
goto-next, goto-next-notrans
Go to the following page of the presentation, with or without a transition.
goto-prev, goto-prev-notrans
Go to the previous page of the presentation, with or without a transition.
goto-start, goto-start-notrans
Go to the first page of the presentation, with or without a transition.
hyperlink, hyperlink-notrans
Navigate to the hyperlink under the mouse cursor, if there is one. If the hyperlink
is a reference to another page of the presentation, this page will be activated
with or without a transition. If the hyperlink refers to an external object (e.g.
an URL), it will be opened externally, if supported by the system.
overview-confirm
When in overview mode, confirm the selection and leave overview mode, navigating to
the selected page.
overview-down, overview-up
When in overview mode, select the page above or below the currently selected one in
the grid.
overview-enter
When not in overview mode, zoom out of the current page, entering overview mode.
overview-exit
When in overview mode, leave overview mode, zooming back to the page that has been
displayed before entering overview mode.
overview-next, overview-prev
When in overview mode, select the following or previous page.
quit
Quits Impressive immediately. This action is available in all modes.
save
Save or update the Info Script for the current presentation.
spotlight-enter
If spotlight mode is not active, enable spotlight mode.
spotlight-exit
If spotlight mode is active, deactivate spotlight mode.
spotlight-grow, spotlight-shrink
When in spotlight mode, increase or decrease the radius of the spotlight.
spotlight-reset
When in spotlight mode, reset the spotlight radius to the default value.
time-reset
Reset the presentation timer.
time-toggle
Toggle on-screen display of the current presentation time, or wall-clock time if
the --clock option is used. If this is done at the start of the presentation,
before the first page has been left, time tracking mode will be enabled, like the
--tracking option would have done.
toggle-overview
This toggles the "page is visible on overview screen" flag for the current page.
This will not have an immediate effect, but it can be saved to an Info Script.
toggle-skip
This toggles the "skip page when navigating with goto-prev and goto-next" flag for
the current page.
video-pause
In video playback mode, this pauses or unpauses playback.
video-seek-backward-10, video-seek-backward-1, video-seek-forward-1, video-seek-forward-10
In video playback mode, seek forward or backward by 1 or 10 seconds.
video-step
In video playback mode, if playback is paused, advance one frame in the video.
video-stop
In video playback mode, stop playback and return to normal page display mode.
zoom-enter
If not in zoom mode, enter zoom mode.
zoom-exit
If in zoom mode, leave zoom mode.
zoom-pan
When in zoom mode, the visible area of the page can be moved around with the mouse
while the key or mouse button of the associated event is held down.
BINDING SYNTAX
The arguments of the -e/--bind command-line option have the following basic syntax:
<event> [,<event2>...] <operator> <action> [,<action2>...]
In other words, it is a sequence of event names joined with commas, followed by an
operator (see below) and a sequence of action names joined with commas. Multiple such
binding statements can be combined into one argument by joining them with a semicolon (;).
The used operator defines in which way the action list shall modify the bindings of the
referenced events:
= (equals sign), += (plus sign and equals sign)
The specified actions will be added to the bindings of the specified events. In
other words, event=action1,action2 does exactly the same as event=action1;
event=action2.
:= (colon and equals sign)
The specified actions will replace the bindings of the specified events.
-= (minus sign and equals sign)
The specified actions will be removed from the bindings of the specified events.
For example, to make the Esc key in the default bindings not clear highlight boxes,
but otherwise preserve its original functionality, escape -= box-clear can be used.
Other than bindings, a statement can also contain one of the following special commands:
clearall
Clears all current bindings.
defaults
Discards all current bindings and (re-)establishes the default bindings.
include <filename>
Loads and executes a control configuration file with a specified name.
The syntax for the configuration files used with the -E/--controls option or include
statement is exactly the same as for the ad-hoc configuration option, except that
individual bindings can be written on individual lines instead of joining them together to
a single long line with semicolons. In addition, everything following a hash sign (#) on a
line will be ignored as a comment.
One practical example for such a configuration file can be the following: The author of
this program uses a cheap presentation remote control device that has four cursor keys,
one "enter" key and a slider that switches between keyboard and mouse mode. Mouse mode
works as expected, but what it does in keyboard mode is quite peculiar: the up and down
keys act like Page-Up and Page-Down keys on a keyboard, the right arrow key sends the
letter B to the computer, and the left key toggles between Esc and F5 each time it's
pressed. The following configuration file allows basic navigation and access to overview
mode with this device:
clearall # don't use the default bindings
lmb = quit # quit Impressive by clicking in mouse mode
# everything else uses keyboard mode:
return = overview-enter, overview-confirm # toggle overview mode
escape, f5 = overview-prev, goto-prev
b = overview-next, goto-next
pageup = overview-up, goto-prev
pagedown = overview-down, goto-next
To get a better idea of how the control configuration system works in practice, it's
recommended to study the output of impressive --control-help - this not only gives a
concise overview of all events and actions, but also a full dump of Impressive's default
bindings that can be used as a starting point for own customizations.
INFO SCRIPTS
Impressive offers a powerful way to customize individual presentations using so-called
info scripts. An info script is a text file having the same name and located in the same
directory as the presentation file itself, except for the additional suffix .info. Thus, a
presentation file called BrandNewProduct.pdf would have a info script with the name
BrandNewProduct.pdf.info. If multiple arguments were specified on the command line, the
info script will be called just .info (a dot file, so to speak). If a directory name was
specified as the only argument, either a file called DirectoryName.info or a file called
.info inside the directory will be used, depending on whether a path separator was
specified at the end of the directory name or not - Impressive simply appends .info to
whatever the input path name was.
In any case, the default file name can be overridden by the -I command line option.
Info scripts are actually Python scripts with full access to Impressive's global data
structures and functions. (It is possible to write real interactive applications using
info scripts.) Thus, they can modify a broad range of settings concerning Impressive. This
manual will only cover the most basic ones.
PAGE PROPERTIES
The main part of an info script defines the properties of each page. At the moment, the
following properties are defined:
title
Each page can have a title that is displayed in the Impressive window's title bar.
If there is no title explicitly specified in the info script, the title of the page
will be extracted from PDF metadata if pdftk is installed, or the image file name
will be used if the presentation is an image slideshow.
transition
With this property, the transition class to be used for rendering the transition to
this page (i.e. between the previous page and this page) can be specified. For
pages lacking this property, random transitions will be chosen. A list of available
transition classes can be obtained with impressive -l.
transtime
This property overrides the global transition time parameter (-T at the command
line). It contains the integer time (in milliseconds) the transition to this page
shall take.
overview
This property holds a boolean value (0/False or 1/True) that specifies whether the
page shall be included in the overview page. If this property isn't specified, it
is assumed to be True.
skip
This boolean property can be set to 1/True if the page shall be skipped during the
presentation.
Pages with overview:True, skip:False will be accessible both by cycling through the
pages and using the overview page,
pages with overview:True, skip:True will be silently skipped in the normal page
cycle, but remain accessible from the overview page,
pages with overview:False, skip:False will appear in the normal cycle, but not on
the overview page
and pages with overview:False, skip:True will not be accessible at all.
boxes
This property stores a list of highlight box coordinates. Normally, there is no
need to edit this by hand, as Impressive handles this automatically if the S key is
pressed.
timeout
If a timeout property is present and the page is shown, Impressive will
automatically switch to the next page after the specified number of milliseconds.
Normally, the timeout will only be effective the first time the page is shown
unless wrap mode is used (command-line option -w or --wrap). This restriction makes
it possible to create self-running presentations with individual per-page timeouts.
radius
This property takes an integer value that, if defined, will be used to set a new
spotlight radius every time the page is entered. This overrides the current setting
as defined by the --spot-radius command line option or run-time adjustments. Note
that the value is not reset to the default value after the page has been left
again.
darkness
This property takes an integer or floating-point percentage value that, if defined,
will be used to set the background darkness in spotlight or highlight box mode each
time the page is entered. This overrides the current setting as defined by the
--darkness command line option or run-time adjustments. Note that the value is not
reset to the default value after the page has been left again.
comment
This property can hold a string with a single line of text that will be displayed
on screen while the page is shown. Display of this text can not be disabled.
sound
Specifies the file name of a sound file to be played (via MPlayer) when the page is
first entered. Once started, the sound will be played until its end is reached,
another sound or video is played, or Impressive is exited.
video
Specifies the file name of a video file to be played when the page is first
entered. The video will be displayed full-screen. Any key or mouse click stops
playback, except the cursor keys, which are used to seek in the video file, and
space, which can be used to pause playback. Note that this function is highly
experimental and might not work reliably on every system!
always
If this property is present and set to 1 or True, the media file specified in the
sound or video properties will be played every time the page is entered, not just
the first time.
progress
If this property is set to zero, the presentation progress bar (which is usually
set up with the -d/--duration command line switch) will not be shown on this page.
In practice, it might be useful to hide the bar from the first page so that it is
not visible during the introduction.
reset
If this property is set to 1 or True, the timer will be reset each time this page
is left, just as if the R has been pressed. If the special value 2 or FirstTimeOnly
is used, the reset will only take place if the page was shown for the first time.
Again, this is particularly useful on the first page: A combination of
progress:False, reset:FirstTimeOnly makes it possible to set up the presentation
long before it actually begins - the first page can be showed as long as desired,
actual timing starts at the second page.
rotate
This property is a per-page override of the global -r command line option: It
specifies how the page shall be rotated, in 90-degree steps clockwise.
OnEnter, OnLeave, OnEnterOnce, OnLeaveOnce
These properties can contain a Python callable (i.e. a function reference or lambda
expression) that is executed when the page is entered or left. The ~Once variants
will only be executed when the page is entered or left for the first time. The
callable must not take any arguments. This feature can be used to associate
arbitrary Python code with specific pages, for example to execute external
programs.
Warning: Lambda expressions cannot be properly processed by the Info Script save
function (S key). If Impressive encounters lambda expressions when saving, it will
remove them. In addition, it will not overwrite the original info script, but
generate an extra file that needs to be merged withe the original script by hand.
keys
This property can be assigned a dictionary that maps alphanumerical keys to Python
functions. For example, 'keys': { 'x': SomeFunction } will invoke SomeFunction() if
the lowercase character 'x' is typed while the page is displayed. Regarding the
functions, the same restrictions as for the OnEnter/OnLeave family apply: the
function must not take any parameters and lambda functions can not be saved. Also
note that it is not possible to overwrite Impressive's pre-defined key bindings
with this method.
invert
This property specifies whether the colors of that page shall be inverted in the
same way the --invert command-line switch does. It overrides the --invert setting
on a per-page basis: If set to True, the page will always be inverted; if set to
False, the page will never be inverted even if --invert has been specified on the
command line.
Note that in Impressive versions prior to 0.11.0, the transition and transtime properties
defined the transition from the current page to the next, not from the previous page to
the current one.
The properties are stored together in a Python dictionary called PageProps. The syntax
looks like in this example:
PageProps = {
1: {
'title': "Title Page",
'transition': PagePeel,
'sound': "background_music.mp3"
},
2: {
'title': "Another Page",
'timeout': 5000
}
}
The PageProps definition (and only the PageProps definition) will be rewritten by
Impressive if the S key is pressed. User-defined PageProps entries will also be left
untouched, except for some pretty-printing.
GLOBAL PRESENTATION PROPERTIES
The name of the presentation is shown in the title bar of the Impressive window (if not in
fullscreen mode). By default, the file name or (if available) PDF metadata title will be
used for this purpose, but the presentation title can also be explicitly set by
overwriting the DocumentTitle variable:
DocumentTitle = "My Presentation"
Another useful variable, AvailableTransitions, contains a list of all transition classes
that may be used for randomly assigning transitions to pages lacking the transition
property. Thus, if a certain transition is undesired (either because of personal dislike
or because it shall be used exclusively on pages where it is manually assigned using
PageProps), something like the following can be written:
AvailableTransitions.remove(WipeBlobs)
On the other side, it's possible to activate transitions that are not enabled by default:
AvailableTransitions += [SlideUp, SlideDown]
Alternatively, AvailableTransitions can be completely overwritten to have the same
transition (or set of transitions) assigned to all pages:
AvailableTransitions = [Crossfade]
OPTION OVERRIDES
Another use of info scripts is overriding the default or command-line settings on a
per-file basis. This can be done by simply overwriting one of the variables that are
defined at the beginning of impressive.py. Each of these variables corresponds either to a
command-line setting, or to some constant related to visual appearance or performance. So,
for example, to force fullscreen mode for a presentation, write
Fullscreen = True
WORKING DIRECTORIES
The working directory while executing the info scripts themselves is always the directory
in which the info script is stored in.
The base directory for external actions that originate from Page Properties or PDF
hyperlinks is always the directory of the PDF or image file this page belongs to. In other
words, if e.g. 'sound': "music.mp3" is written in the info script for one page of
presentation.pdf, the file music.mp3 is expected to be located in the same directory as
presentation.pdf.
AUTHOR
Impressive and its documentation has been written mainly by Martin J. Fiedler
<martin.fiedler@gmx.net>, with small portions of the code written by external
contributors. See the source code file for details.
REPORTING BUGS
Report bugs to to <martin.fiedler@gmx.net>.