KeyJnote Documentation

http://keyjnote.sourceforge.net/
Version: 0.8.2
Author: Martin J. Fiedler
Last updated: 2006-07-13

Table Of Contents

  1. Synopsis
  2. Requirements
  3. Installation
  4. Command Line Parameters
  5. Usage
  6. Info Scripts
  7. Other Useful Information

Synopsis

KeyJnote 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.

Requirements

The following software packages are required or recommended to use KeyJnote:

Debian users can install all these packages at once by typing
apt-get install python python-opengl python-pygame python-imaging gs pdftk

Windows users can download a “batteries included” ZIP file containing all necessary libraries instead of the standard source code distribution of KeyJnote.

In addition to these software requirements, the following hardware requirements exist:

Installation

The installation procedure differs betweed Windows and “generic” Unix systems.

Generic Installation

After installing the prerequisites mentioned in the last chapter, extract the file keyjnote.py from the downloadable archive. You can either start it directly or copy it to some location in your $PATH (~/bin or /usr/local/bin are good candidates).

To start a presentation, simply type something like
keyjnote.py demo.pdf

Windows Installation

Download the ZIP file of the Windows version and extract it into a folder of your choice. There is an executable file called keyjnote.exe in this directory. You can either directly drop PDF files or directories containing image files on this .exe in Explorer, or you install a link to keyjnote.exe in your “Send To” Menu (usually C:\Documents and Settings\YourNameHere\SendTo). Using the latter method, you can start a presentation by right-clicking a PDF file and selecting “Send To / KeyJnote”.

Command Line Parameters

When used from the command line (some terminal and shell in Unix, cmd.exe on Windows), KeyJnote accepts a range of command-line options in GNU getopt syntax.

The last parameter specified on the command line must be either the name of an (existing and readable) PDF file, or the name of an (existing, browseable and readable) directory that contains image files to display.

The following options are available (in alphabetical order):

-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.
-B <ms> or --boxfade <ms>
Sets the duration (in milliseconds) of the highlight box fade-in/fade-out animation. Default value: 100 ms.
-c or --nocache
Turns off the page cache. By default, KeyJnote pre-renders all pages of the document or slideshow on startup, using a notable amount of memory for each page. If this option is used, pre-rendering is not performed. Instead, KeyJnote will only keep two pages in RAM: The currently displayed one, and the following one. This will introduce a notable delay when cycling through the pages, because they have to be rendered on demand. Additionally, the overview page will not be complete and show up placeholders until each page has been rendered at least once.
-D<ms> or --mousedelay <ms>
Sets the time (in milliseconds) the mouse cursor is shown in fullscreen mode if it is not moved. Default value: 3000 ms.
-f or --fullscreen
Toggles fullscreen mode. By default, fullscreen mode is activated, and can be deactivated using this switch.
Note: On Windows systems, toggling fullscreen mode while KeyJnote runs does not work. So, this option is the only way to set whether fullscreen mode shall be used or not.
-g <width>x<height> or --geometry <width>x<height>
Sets the screen size or resolution KeyJnote shall use (in pixels). The default screen size is 1024x768 pixels. Note that this option is not the standard X “geometry” option and does therefore not support window positioning (e.g. -g 800x600+0-0 will not work!).
-h or --help
If this option is specified, KeyJnote writes a short command line help screen to standard output and does not start a presentation.
-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 KeyJnote 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.
-l or --listtrans
If this option is specified, KeyJnote writes a list of all available transition classes to standard output and does not start a presentation.
-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 you're going to give a presentation on a foreigh PC with an old, broken or otherwise problematic GhostScript installation: By generating images of the PDF pages you can ensure that no rendering bugs will happen on the target system.
-P <path> or --gspath <path>
This option can be used to override the GhostScript path autodetection. The full path to the GhostScript executable (gs or gs.exe) must be specified.
-r <n> or --rotate <n>
Display all pages rotated by n×90 degrees clockwise. Try -r 1 or -r 3 if you run into problems with PDFs generated by LaTeX on some GhostScript versions.
-R <X>x<Y> or --meshres <X>x<Y>
Most effects subdivide the visible screen into a mesh of rectangular or quadratic pieces, each with its own coordinates and alpha blend values. Using this parameter, the resolution of the subdivision mesh can be defined. The default value is 48x36. On slow machines, lower values like 24x18 or 12x9 can heavily speed up transition rendering at the cost of visual quality. On the other hand, higher values like 64x48 or 96x72 improve quality, but use much more CPU cycles.
-s or --scale (image input only)
If a directory with image files is used as input, KeyJnote 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 antialiating by 4x supersampling instead of the normal multisampling method used by GhostScript. While this usually degrades both visual quality and performance, it may be necessary for circumventing white strips or moiré-like patterns in gradients.
-t <ms> or --transition <trans1[,trans2...]>
Using this switch, the set of transitions KeyJnote 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. Default value: 1000 ms.
-w or --wrap
If this option is set, KeyJnote 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.
-Z <ms> or --zoom <ms>
Sets the duration (in milliseconds) of the overview page zoom-in/zoom-out effects. Default value: 250 ms.

Usage

On startup, KeyJnote will display a black screen with the program logo at the center. If caching is enabled (the default setting), all pages of the presentation will be rendered once. A bar at the lower edge of the screen displays the progress of this operation. Any key (except for Q and Esc) or mouse click skips this process, with the effect that KeyJnote 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.

After this initialization process, KeyJnote will switch to the first page directly and without any transition. The following keyboard and mouse operations are available from this moment on:

Q key or Esc key
Quit KeyJnote immediately.
LMB (left mouse button), Page Down key, Cursor Down key, Cursor Right key or Spacebar
Go to the next page (using a transition).
RMB (right mouse button), Page Up key, Cursor Up key, Cursor Left key or Backspace key
Go to the previous page (using a transition).
F key
Toggle fullscreen mode. Unfortunately, this does not work on Windows systems.
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 mouse botton ior the Tab key leave overview mode without changing the current page.
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 and blurry rendition. Only the highlight boxes will be displayed in their original lightness and sharpness.
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 all highlight boxes, so they will be restored the next time this presentation is started.
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 / – key
Adjust the spotlight radius in 8 pixel steps.
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). KeyJnote will re-render the page at the new resolution if the graphics hardware supports it. During this time, KeyJnote 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.
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.

Info Scripts

KeyJnote 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.

Info scripts are actually Python scripts with full access to KeyJnote'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 KeyJnote. 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, three properties are defined:

title
Each page can have a title that is displayed in the KeyJnote 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 between this page and the following page can be specified. For pages lacking this property, random transitions will be chosen. A list of available transition classes can be obtained with keyjnote.py -l.
boxes
This property stores a list of highlight box coordinates. Normally, there is no need to edit this by hand, as KeyJnote handles this automatically if the S key is pressed.
timeout
If a timeout property is present and the page is shown for the first time, KeyJnote will automatically switch to the next page after the specified number of milliseconds.
sound
Specifies the file name of a sound file to be played when the page is first entered. Playback is provided through MPlayer on UNIXish systems or the DirectShow-based gplay.exe by Karl M. Syring on Windows systems. Once started, the sound will be played until its end is reached, another sound is played, or KeyJnote is exited.

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 KeyJnote 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 KeyJnote 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 assinging transitions to pages lacking the transition property. Thus, if you want to exclude a certain transition (either because you don't like it or because you want to have it exclusively on pages where you manually assigned it using PageProps), you can write something like
AvailableTransitions.remove(PagePeel)
Alternatively, you can completely overwrite AvailableTransitions 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 keyjnote.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

Other Useful Information

License

KeyJnote is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for any particular purpose. See the GNU General Public License for more details.

Contact

You can always contact the author of KeyJnote to send him ...