# The &okular; Handbook

Albert
Astals Cid

    aacid@kde.org

Pino
Toscano

    pino@kde.org

&FDLNotice;
2012-09-09
0.15.70 (&kde; 4.10)

&okular; is a &kde; universal document viewer based on &kpdf; code.

KDE
okular
pdf
ps
postscript
tiff
djvu
dvi
chm
xps
comicbook
fictionbook
mobipocket
plucker
annotation

## Introduction

&okular; is a &kde; universal document viewer based on the code of the &kpdf; application. Although being based on &kpdf; code, &okular; has some unique features such as overview mode, improved presentation support and annotation support.

&okular; supports a lot of different formats like PDF, Postscript, Tiff, CHM, DjVU, Images (png, jpg, &etc;) XPS, Open Document (ODT), Fiction Books, Comic Book, Plucker, EPub and Fax. For all supported formats and their features see &okular; Document Format Handlers.

&okular;s Main Window
&okular;s Main Window

## Basic Usage

### Opening Files

To view any supported file in &okular;, select File Open... , choose a supported file in the dialog and click Open. Your file should now be displayed in the main window.

If you have already opened files in &okular; before, you can quickly access them by selecting them in the File Open Recent menu.

&okular; is the default &kde; application for PDF and Postscript files, launched when you click with the &LMB; on such a file type in the filemanager. If you want to open any file whose format is supported by &okular; use Open with...&okular; from context menu in the filemanager.

After having a file opened you probably want to read it and therefore navigate through it. Go to the next section to learn more about this.

### Navigating

This section describes how you can navigate through a document in &okular;.

There are multiple ways of scrolling the viewing area. One is to use the Up Arrow and Down Arrow keys. You may also use the scrollbar, your mousewheel or the Page Up and Page Down keys.

Another way is to hold the &LMB; down at any place on the document while dragging the mouse in the opposite direction of where you want to move. This procedure only works if the Browse Tool is enabled, which you can select by choosing Tools Browse Tool .

If you want to read a document with several pages use the automatic scrolling feature of &okular;. Start automatic scrolling with &Shift;Down Arrow or &Shift;Up Arrow. Then use these keys to increase and decrease the scrolling speed. You can start or stop automatic scrolling temporarily by pressing the &Shift; key; pressing any other key deactivates this feature.

Another way to navigate through a document with several pages is to use the mouse pointer. Drag the page up or down, continue to drag even while reaching the bottom or top of the screen and behold. Once you cross the border of a page, the mouse cursor appears on top or bottom of the screen again and you can just continue to drag.

The navigation panel on the left side of the screen enables two more ways of navigating through a document:

- If you click on a page thumbnail the viewing area will be brought to that page.

- If the document has a table of contents, clicking on a table of contents item will bring the document to the page linked to that item.

- If the document has bookmarks, enable the Bookmarks view and click them to go to the associated page. If bookmarks are not only shown for the current document, you can quickly switch to bookmarks in all recently opened files.

- If the document has annotations, enable the Reviews view and click the annotations or select them with the Up Arrow and Down Arrow keys and press Return to go to the associated page.

Some documents have links. In this case you can click on them and the view will change to the page it links to. If the link is to a web page or some other document the default &kde; handler for that format will be invoked. For example, clicking on a link pointing to http://www.kde.org will open the web page in the default &kde;'s web browser.

Additionally, you may use the following functionality to quickly move to specific places in the document:

- You can go to the beginning of the document using &Ctrl;Home or using Go Beginning of the document .

- You can go to the end of the document using &Ctrl;End or using Go End of the document .

- You can go forward in the document using Space or Page Down. To go to the next page of the document use the Next Page Toolbar button or Go Next Page in the menubar.

- You can go back in the document using &Backspace; or Page Up. To go to the previous page of the document use Previous Page Toolbar button or Go Previous Page in the menubar.

### Presentation Mode

The Presentation mode represents another way to view documents in &okular;. It can be enabled in View Presentation. It shows the document on a page per page basis. The pages are shown with zoom to page, that means all the page is visible.

&PDF; documents can even specify that they are always opened in presentation mode.

When in presentation mode, you have an helper bar located on the top of the screen. Just move the mouse cursor to the top of the screen to make it appear.

&okular; in Presentation Mode
&okular; in Presentation Mode

To navigate between pages you may use the &LMB; (next page) and the &RMB; (previous page), the mouse wheel, the arrow icons or the line edit in the top bar, or the keys specified in the Navigating section.

You can exit presentation mode at any time by pressing the &Esc; key or clicking the Quit icon in the top bar.

You can also draw on the current page with a pencil. Click on the Toggle Drawing Mode icon in the top bar to enable or disable the possibility to draw in the presentation mode. The drawings are cleared automatically when leaving the presentation mode. You can also click on the Erase Drawings icon to remove the drawings in the current page.

The presentation mode has support for more than one screen in a multi-monitor configuration. With more than one screen a new button will appear in the top bar, with the icon of a screen: this is a drop down box that allows you to move the presentation to any of the other available screens.

Presentation mode has some configuration options, you can find their description in the chapter Configuring &okular;.

### Inverse Search between &latex; Editors and &okular;

Inverse search is a very useful feature when you are writing a &latex; document yourself. If everything is set up properly, you can click into &okular;'s window with the left mouse button while pressing &Shift;. After that editor loads the &latex; source file and jumps to the proper paragraph.

Inverse search cannot work unless:

- The source file has been compiled successfully.

- &okular; knows which editor you would like to use.

- The Browse Tool has to be enabled, which you can select by choosing Tools Browse Tool .

With this feature of &okular;, a left mouse click while pressing &Shift; in the &DVI; or &PDF; document will result in editor opening the corresponding &latex; document and attempt to go to the corresponding line. Remember to tell &okular; to use proper editor, in &okular;'s menu item Settings Configure Okular... (on the page Editor).

For more details on editor configuration please refer to the corresponding section of this manual.

Configuring &okular;
Configuring editor in &okular;

Configuring editor in &okular;

## &okular; Advanced Features

### Embedded Files

If the current document has some files embedded in it, when you open it a yellow bar will appear above the page view to notify you about the embedded files.

The embedded files bar
The embedded files bar

In this case, you can either click on the link in the text of the bar or choose File Embedded Files to open the embedded files dialog. The dialog allows you to view the embedded files and to extract them.

### Forms

If the current document has forms, when you open it a bar will appear above the page view where you can enable the forms.

The forms bar
The forms bar

In this case, you can either click on Show Forms in the bar or choose View Show Forms to enter data into the form fields.

### Annotations

&okular; allows you to review and annotate your documents. Annotations created in &okular; are automatically saved in the internal local data folder for each user. &okular; does not implicitly change any document it opens.

&okular;'s Annotations
&okular;'s Annotations

&okular; has two different kind of annotations:

Text annotations like Yellow Highlighter and Black Underlining for files with text like &eg; PDF.

Graphic annotations like Note, Inline Note, Green Freehand Line, Straight Yellow Line, Blue Polygon, Stamp and Cyan Ellipse for all formats supported by &okular;.

Using the context menu either in the Reviews view of the navigation panel or in the main window you can open a Pop up Note for any kind of annotation and add or edit comments.

Annotations are not only limited to PDF files, they can be used for any format &okular; supports.

Since &kde; 4.2, &okular; has the "document archiving" feature. This is an &okular;-specific format for carrying the document plus various metadata related to it (currently only annotations). You can save a "document archive" from the open document by choosing File Export As Document Archive. To open an &okular; document archive, just open it with &okular; as it would be &eg; a &PDF; document.

Since &okular; 0.15 you can also save annotations directly into PDF files. This feature is only available if &okular; has been built with version 0.20 or later of Poppler rendering library. You can use File Save As... to save the copy of &PDF; file with annotations.

It is not possible to save annotations into &PDF; file if original file was encrypted and &okular; uses Poppler libraries of version which is lower than 0.22.

If you open a &PDF; with existing annotations, your annotation changes are not automatically saved in the internal local data folder, and you need to save the modified document (using File Save As...) before closing it. Should you forget to do this &okular; will show confirmation window that allows you to save the document.

Due to DRM limitations (typically with &PDF; documents), adding, editing some properties or removing annotations could not be possible.

#### Adding annotations

To add some annotations to the document, you have to activate the annotating toolbar. This is done by either selecting Tools Review or pressing F6. Once the annotating toolbar is shown, just press one of its buttons to start constructing that annotation.

With a single &LMB; click on an annotation tool button you can use a tool once. If you &eg; want to highlight all important parts of a text, activate that tool permanently by double clicking on the tool button. Press the Esc key or click the tool button again to leave the permanent mode.

The annotating toolbar can be docked in any side of the viewing area: just drag it to move it to another place.

Activating the annotating toolbar will make you switch to the Browse Tool Mode.

You can stop the construction any time by pressing again on the button of the annotation you are constructing, or by pressing the &Esc; key.

The newly constructed annotation will have as author the author you set in the Identity page in &okular;s configuration dialog.

Using stamps a single click just places a square stamp (useful for icons). To add a rectangular stamp you can click with the &LMB; and hold to place the top-left point, then drag to place the bottom-right one.

#### Removing annotations

To remove an annotation, just click on it with the &RMB;, and select Delete.

When removing the annotation, its window will be closed if open.

This option could not be enabled because the document does not allow removing annotations.

#### Editing annotations

To edit an annotation, click on it with the &RMB; and select Properties. A dialog will appear with the general annotation settings (like color and opacity, author, &etc;) and the settings specific to that annotation type.

Annotation Property Dialog
Annotation Property Dialog

To move an annotation, hold down the &Ctrl; key, move the mouse pointer on it and then start dragging with the &LMB;.

Depending on the document permissions (typically with &PDF; documents), some options can be disabled.

### Bookmark Management

&okular; has a very flexible bookmark system. &okular; saves the position on the page in bookmark and allows you to define more than one bookmark per page.

To manage bookmarks in &okular; you can use Bookmarks view from Navigation Panel, Bookmarks menu or context menu of document view (click with &RMB; to open it).

#### Bookmarks view

To open Bookmarks view click on Bookmarks item on the Navigation Panel. If the Navigation Panel is not shown, use F7 Settings Show Navigation Panel main menu item to make it visible.

Bookmark view context menu
Bookmark view context menu

The filter bar at the top of Bookmarks view can be used to filter the content of bookmark list pane according to the text in the box.

The list pane permits to view the bookmark list in a tree-like fashion: each document in the list can be expanded or collapsed by clicking on the < or v icon next to it.

Click on icon below the list to show only the bookmarks from the current document.

Right-click menu of document item can be used to open document, rename its item or remove it from the list. Remember that the removal of a document item leads to the removal of all bookmarks in the corresponding document.

Right-click menus of individual bookmark items allow you to go to the bookmark, rename or remove it.

### Command Line Options

Though &okular; may most often be started from the &kde; program menu, or a desktop icon, it can also be opened at the command line prompt of a terminal window. There are a few useful options that are available when doing this.

#### Specify a File

By specifying the path and name of a particular file the user can have &okular; open that file immediately upon startup. This option might look something like the following:

    % okular /home/myhome/docs/mydoc.pdf

For &PDF; documents, the name can be given as document_name#named_destination where named_destination is a particular named destination embedded in the document.

#### Other Command Line Options

The following command line help options are available

``okular` `--help``

  This lists the most basic options available at the command line.

``okular` `--help-qt``

  This lists the options available for changing the way &okular; interacts with &Qt;.

``okular` `--help-kde``

  This lists the options available for changing the way &okular; interacts with &kde;.

``okular` `--help-all``

  This lists all of the command line options.

``okular` `--author``

  Lists &okular;'s authors in the terminal window

``okular` `-v, --version``

  Lists version information for &Qt;, &kde;, and &okular;. Also available through ``okular` `-v``

``okular` `--license``

  Shows license information.

``okular` `--page number``

  Open a page with a given number in the document. Also available through ``okular` `-p number``

``okular` `--presentation``

  Start the document in presentation mode.

``okular` `--unique``

  Unique instance control.

``okular` `--``

  End of options.

## The Menubar

### The File Menu

&Ctrl;O File Open...

  Open a supported file or &okular; archive. If there is already an opened file it will be closed. For more information, see the section about Opening Files.

File Open Recent

  Open a file which was used previously from a submenu. If a file is currently being displayed it will be closed. For more information, see the section about Opening Files.

File Import PostScript as &PDF;...

  Open a PostScript file and convert it to &PDF;.

File Save As...

  Save the currently open file under a different name using the document backend. With the &PDF; backend (Poppler >= 0.8 required) it is possible to save the document with the changed values of the form fields. It can be possible (provided that the data were not secured using DRM) to save annotations with &PDF; files (Poppler >= 0.22 required).

File Save Copy As...

  Save a copy of the currently open file under a different name without using the current document backend.

F5 File Reload

  Reload the currently open file.

&Ctrl;P File Print...

  Print the currently displayed document.

File Print Preview...

  Show a preview of how the currently displayed document would be printed with the default options.

File Properties

  Display some basic information about the document, such as title, author, creation date, and details about the fonts used. The available information depends on the type of document.

File Embedded Files...

  Show the files embedded in the document, if the document has any. For more information, see the section about the Embedded Files.

File Export As

  This item contains the export formats the current document can be exported to. The first entry for all kind of documents is always Plain Text...

  The second entry is Document Archive, which allows you to save the document with your annotations into an &okular;-specific archive format. Thus it is easily possible to share the original document and your annotations with other &okular; users or work with them collaboratively.

&Ctrl;Q File Quit

  Close &okular;.

### The Edit Menu

&Ctrl;C Edit Copy

  Copy the currently selected text in Text Selection mode to the clipboard.

&Ctrl;A Edit Select All

  Selects all the text (if the document provides it). This works only in Text Selection mode.

&Ctrl;F Edit Find...

  Show the find bar on the bottom of the viewing area that allows you to search for a string in the document.

F3 Edit Find Next

  Try to find the previous searched string again in the document.

&Shift;F3 Edit Find Previous

  Goes to the previous occurrence of the search string in the document.

### The View Menu

&Ctrl;&Shift;P View Presentation

  Activates the Presentation Mode. For more information, see the section about Presentation Mode.

&Ctrl;+ View Zoom In

  Increase the magnification of the document view.

&Ctrl;- View Zoom Out

  Decrease the magnification of the document view.

View Fit Width

  Change the magnification of the document view to a value that makes the pages' width equal to the document view's width.

View Fit Page

  Change the magnification of the document view to a value that makes at least one whole page visible.

View Continuous

  Enable the continuous page mode. In continuous mode, all pages of the document are shown, and you can scroll through them without having to use the Go Previous Page and Go Next Page options.

View View Mode

  This submenu makes you choose the view mode for the pages. The possible options are: Single Page (only one page per row), Facing Pages (two pages per row, in a book style), Facing Pages (Center First Page) and Overview (the number of columns is the one specified in the &okular; settings).

View Orientation

  This submenu allows you to changes the orientation of the pages of the document.

  The rotation is applied to the orientation of every page.

  You can select Original Orientation to restore the orientation of the document, discarding all the rotations applied manually.

View Page Size

  Changes the size of the pages of the document.

  This submenu is active only if the current type of document supports different page sizes.

View Trim Margins

  Remove the white border of pages when viewing pages.

View Show/Hide Forms

  Show or hides the display of the form fields of the document.

  This menu item is active only if the current document has form fields.

### The Go Menu

Go Previous Page

  View the previous page of the document.

Go Next Page

  View the next page of the document.

&Ctrl;Home Go Beginning of the document

  Go to the beginning of the document.

&Ctrl;End Go End of the document

  Go to the end of the document.

&Alt;&Shift;Left Go Back

  Go back to the previous view of the document.

&Alt;&Shift;Right Go Forward

  Move forward to the next view of the document. This only works if you have already moved back before.

&Ctrl;G Go Go to Page...

  Open a dialog which allows you to go to any page of the document.

### The Bookmarks Menu

&Ctrl;B Bookmarks Add/Remove Bookmark

  Add or remove a bookmark for the current position.

Bookmarks Rename Bookmark

  Rename a bookmark for the current position.

Bookmarks Previous Bookmark

  Go to the previous bookmark, or do nothing if there are no bookmarks prior to the current one.

Bookmarks Next Bookmark

  Go to the next bookmark, or do nothing if there are no bookmarks after the current one.

Bookmarks No Bookmarks

  This is an always disabled action that appears in this menu only if the current document has no bookmarks. Otherwise a list of all bookmarks is displayed here. Clicking on these bookmarks allows you to go directly to the associated position.

### The Tools Menu

&Ctrl;1 Tools Browse Tool

  The mouse will have its normal behavior, &LMB; for dragging the document and following links and &RMB; for adding bookmarks and fit to width.

&Ctrl;2 Tools Zoom Tool

  The mouse will work as a zoom tool. Clicking &LMB; and dragging will zoom the view to the selected area, clicking &RMB; will bring the document back to the previous zoom.

&Ctrl;3 Tools Selection Tool

  The mouse will work as a select tool. In that mode clicking &LMB; and dragging will give the option of copying the text/image of current selected area to the clipboard, speak a text or to save an image to a file.

&Ctrl;4 Tools Text Selection Tool

  The mouse will work as a text selection tool. In that mode clicking &LMB; and dragging will give the option of selecting the text of the document. Then, just click with the &RMB; to copy to the clipboard or speak the current selection.

&Ctrl;5 Tools Table Selection Tool

  Draw a rectangle around the text for the table, then use the click with the &LMB; to divide the text block into rows and columns. A &LMB; click on a existing line removes it and merges the adjacent rows or columns.

F6 Tools Review

  Open the review toolbar. The review toolbar allows you to add annotations on the document you are reading. For more information, please see the section about Annotations.

Tools Speak Whole Document
Tools Speak Current Page
Tools Stop Speaking

  These items allow you to speak the whole document or just the current page and stop speaking using the &kde; Text-to-Speech system Jovie.

  The Speak ... actions are enabled only if &jovie; is available in the system.

### The Settings Menu

&Ctrl;M Settings Show Menubar

  Toggle the Menubar display on and off. Once hidden it can be made visible using the shortcut &Ctrl;M again. If the menubar is hidden, the context menu opened with a right mouse button click anywhere in the view area has an extra entry Show Menubar.

Settings Show Toolbar

  Toggle the Toolbar display on and off.

F7 Settings Show Navigation Panel

  Toggle the navigation panel on and off.

Settings Show Page Bar

  Toggle the page bar at the bottom of document area on and off to save vertical place in &okular; window.

&Ctrl;&Shift;F Settings Full Screen Mode

  Enables the full screen mode. Note that full screen mode is different from presentation mode insofar as the only peculiarity of full screen mode is that it hides the window decorations, the menubar and the toolbar.

Settings Configure Shortcuts...

  Opens a window that lets you configure the keyboard shortcuts for many menu commands.

Settings Configure Toolbars...

  Opens a window that lets you choose which icons are visible in the toolbar.

Settings Configure Backends...

  Opens the Backend Configuration window.

Settings Configure &okular;...

  Opens the Configure window.

### The Help Menu

&help.menu.documentation;

## Configuring &okular;

### General configuration

You can configure &okular; by choosing Settings Configure &okular;.... The configuration dialog is split into six sections. This chapter describes the available options in detail.

- General

- Accessibility

- Performance

- Presentation

- Identity

- Editor

The configuration dialog
The configuration dialog

Depending on the currently installed backends, the Settings Configure Backends... menu item could be enabled. This particular configuration dialog holds the configurations of the backends that can actually be configured.

### General

Show scrollbars

  Whether to show scrollbars for the document view.

Link the thumbnails with the page

  Whether the thumbnails view should always display the current page or not.

Show hints and info messages

  Whether to show some informative messages on startup, file load, &etc;.

Display document title in title bar if available

  Whether to show the current document title in the title bar of &okular; window. If no metadata for title found in the document or this item is unchecked &okular; shows filename of the document.

When not displaying document title

  You can choose any of two options, Display file name only or Display full file path.

Obey DRM limitations

  Whether &okular; should obey DRM (Digital Rights Management) restrictions. DRM limitations are used to make it impossible to perform certain actions with &PDF; documents, such as copying content to the clipboard. Note that in some configurations of &okular;, this option is not available.

Reload document on file change

  Whether opened files should be automatically checked for changes and updated, if necessary.

Show backend selection dialog

  Whether &okular; should ask the user which backend to use in case of more than one backend able to open the current file. If unchecked, &okular; will use the backend with the highest priority.

Overview columns

  This option represents the number of columns to use in the overview mode.

Page Up/Down overlap

  Here you can define the percentage of the current viewing area that should be visible after pressing Page Up/Page Down keys.

Default Zoom

  This options specifies the default zoom mode for file which were never opened before. For those files which were opened before the previous zoom mode is applied.

### Accessibility

Draw border around links

  Whether to draw a border around links.

Change colors

  Enables the color changing options.

Invert Colors

  Inverts colors on the view, &ie; black objects will be shown white.

Change Paper Color

  Changes the paper's color, &ie; the document's background.

Change Dark & Light Colors

  Changes the dark and light color to your preference, that means black will not be rendered as black but as the selected dark color and white will not be rendered as white but as the selected light color.

Convert to Black & White

  Converts the document to black and white. You can set the threshold and the contrast. Setting the threshold to a higher value by moving it to the right will result in lighter grays used.

### Performance

Enable transparency effects

  Draw selections and other special graphics using transparency effects. Disable the option to draw them using outline or opaque fill styles and increase speed on selections.

Memory Usage

  &okular; can achieve best performance by tuning the memory usage, based on your system and your tastes. The more memory you let it to use, the faster the program will behave. The Default profile is good for every system, but you can prevent &okular; from using more memory than necessary by selecting the Low profile, or let it get the most out of your system using Aggressive. Use Greedy profile to preload all pages without risk of system memory overfull (only 50% of total memory or free memory will be used).

### Presentation

Advance every

  Enables automatic advancing of pages given a time period.

Loop after last page

  When navigating on presentation mode and going past the last page the first page will appear.

Background color

  The color that will fill the part of the screen not covered by the page when on presentation mode.

Pencil color

  The color of the pencil used when drawing on the pages during the presentation mode.

Mouse cursor

  Whether the mouse should be always hidden, always shown or hidden after a small time of inactivity.

Show progress indicator

  Whether to show a progress circle that shows the current page and the total number of pages on the upper right corner of the presentation screen every time you change the page.

Show summary page

  Whether to show a summary page at the beginning of the presentation with the title, author and number of pages of the document.

Enable transitions

  Use this checkbox to enable or disable transition effects between pages.

Default transition

  The transition effect between page and page if the document does not specify one. Set this to Random Transition to make &okular; randomly choose one of the available effects.

Placement

  In this section you can select the Screen used to display the presentation.

  Current Screen is same screen of the &okular; window that starts the presentation mode.

  Default Screen is the screen marked as default in the xinerama configuration.

  Screen 0, Screen 1 &etc; are the available screens.

### Identity

Author

  The author of the contents added on a document. Default is the name from the Password & User Account page of the &systemsettings; module Account Details.

### Editor

Editor

  Choose the editor you want to launch when &okular; wants to open a source file. This is the case when the document has references to the various points (usually row and column number) of sources it was generated from. The &DVI; format supports natively the addition of the information about the sources the LaTeX document was generated from. A similar system exists for &PDF; documents, called pdfsync, which stores these extra information in an external file named after the &PDF; file itself (for example `mydocument.pdfsync` for `mydocument.pdf`).

  &okular; ships with preconfigured settings for the following editors: &kate;, Kile, SciTE, Emacs client, and LyX client.

  To use inverse search in Kile, you have to compile your &latex; file with the Modern configuration.

Command

  This is the command and its parameters to invoke the selected editor with the source file of the actual document.

  This field will be filled automatically if you use one of the preconfigured editors. Otherwise, please choose Custom Text Editor in Editor drop-down list and refer to the documentation on your favorite editor to find the proper command.

  You can use the following placeholders:

  - %f - the file name

  - %l - the line of the file to be reached

  - %c - the column of the file to be reached

  If %f is not specified, then the document name is appended to the specified command.

## Credits and License

### Program Copyright:

- Albert Astals Cid aacid@kde.org Current maintainer

- Pino Toscano pino@kde.org

- Enrico Ros eros.kde@email.it &kpdf; developer

### Documentation Copyright:

- Albert Astals Cid aacid@kde.org Author

- Titus Laska titus.laska@gmx.de Some updates and additions

- Pino Toscano pino@kde.org

&underFDL; &underGPL;

## Installation

### How to obtain &okular;

&install.intro.documentation;

### Compilation and Installation

If you are reading this help in the &khelpcenter;, &okular; has already been installed on this system and you do not need install it anymore.

&install.compile.documentation;
&documentation.index;