pdfedit
PDFedit pdf manipulation library, gui, tools

PDFedit user documentation

Table of Contents

I. Document purpose
II. PDFEdit general overview
III. Installation
IV. Command line
1. PDF Editor Commandline parameters
Option --help
Option --version
Option -d (n)
Option -console
Option -script (filename)
Option -run (filename)
Option -eval (code)
Option -s (filename)
Option --
2. Localization
V. Graphical user interface (GUI)
3. Command console
4. Page space
Changing page information
Popup menu
5. Object tree, Stream, Selection and Property editor
Purpose and usage
Object tree start objects
Catalog
Pages
Outlines
Adding and deleting objects
Creating pdf files
Controls
Multiselect
Object tree
Property mode
Adding and deleting properties
Property editor
Editing properties
Selection
Text selection
Graphical objects selection
Deleting objects
Stream
Operator description
Operator modes
Adding and deleting properties
6. Menu, toolbars and on-click functions
Toolbars
Main
Page
Selection modes
Draw
Text
Operator
Dynamic
Treeview
Revision
Functions in menu and toolbars
Selection modes
Drawing and adding new objects
7. Settings
Editor tab
Advanced mode
Show hidden properties
Allow editing read-only properties
Remember path of last opened/saved file
Length units
Character encoding
Paths tab
Icon path
Script path
Scripts to run on start
Console log file
Object tree tab
Document dictionary
Object dictionaries
Graphic objects
Annotations
Pages
Outlines
Content streams
Simple objects
Sort dictionary items alphabetically
Commandline tab
Show return value of executed script in console
Show return value also for complex type
Show errors from event handlers
Show command editor
Show command line
Editable command line
History option
Toolbars tab
Look and Feel tab
Aplication font
Console font
Statusbar font
Style
Icon theme
Use big icons
VI. Scripting documentation for PDF Editor

Document purpose

This document describes usage of PDFedit, how to install and run program and how to work in commandline or graphical mode (GUI). It also describes using and writing user scripts.

Document organization

Document itself is divided into several parts:

PDFEdit general overview

Pdf Editor is primary created for simple editation and manipulation with objects of documents in PDF format and storing them as new version of document. Editation and manipulation with objets is by graphical and by commandline interface too. For simple use command line is using script language, which is usefull in graphical interface too.

Installation

Required libraries

These libraries are required to build and install PDF Editor:

qt3Qt GUI Toolkit (Version 3.x)
boostBoost C++ Libraries (smart_ptr, iostreams)
xlibX Window System libraries

Modified version of qsa library (Qt Script for Applications), version 1.1.4 is included in the source tree

We tested compiling with various g++ versions - 3.x and 4.x were fine, it may compile on older versions like 2.95, but it was not tested. Program uses extensively RTTI, so the compiler used to build the program must support it.

For building kernel tests, you need to have CPPunit installed

For rebuilding documentation from DocBook .xml files, gmake (GNU make) is required and you also need:

  • For generating HTML : xsltproc from libxslt and docbook stylesheets

  • For generating PDF : xsltproc from libxslt, docbook stylesheets and Apache FOP from http://xmlgraphics.apache.org/fop/

If some of the required dependencies is missing, documentation in appropriate format will not be generated. In distributed archive, HTML documentation is already generated.

For rebuilding programmer reference, doxygen is required.

Compiling and installing from source

Prerequisites.  Make sure you have all needed libraries (qt3, boost and xlib) along with their headers. You also need the environment variable QTDIR to be set to directory in which the Qt toolkit (version 3) is installed. Many distributions already set this when installing Qt, but some of them don't. In that case, you have to set the QTDIR manually. Usually it is set to something like /usr/qt/3 or /usr/share/qt3 Also, QMAKESPEC have to be set to match your system type. For most linuxes is is linux-g++, on BSD systems it can differ. If QTDIR is set in your distribution, this environment variable is probably set too. Once you set QTDIR, you may try typing ls $QTDIR/mkspecs - QMAKESPEC need to be set to name of one of the directories that are in mkspecs subdirectory in the Qt directory.

Configuration.  First step is to run configuration script, it will do some checks of required libraries and environment. Also, it allow to alter default settings (which is that the application will be installed in /usr/local directory tree) In CVS root (or root of distribution archive) type ./configure [parameters] to run configuration

With parametr --prefix you can specify where to install the program, so if you do not have root privileges, you can install somewhere in your home directory, for example by specifying --prefix=$HOME/pdfedit . Type ./configure --help to show all parameters of the configure script.

Compiling.  After running configure, type make to compile PDF Editor and re-genereate documentation (if needed, in the distribution archive the documentation is already pre-generated in HTML format, if you have proper tools installed (xstlproc, apache fop), then PDF version of documentation is also generated, if not, it is simply skipped as it is not essential)

Installing.  In CVS root (or root of distribution archive) type make install to install PDF Editor. It will check whether the project is compiled (if not, it will compile it) and install the editor.

Uninstalling.  In CVS root (or root of distribution archive) type make uninstall to uninstall PDF Editor. The editor must be already built (and installed) for this to work. This will remove all the files that have been installed by make install

Tested platforms

PDF Editor has been compiled and tested on following platforms:
Gentoo Linux x86 - ok
Gentoo Linux x86_64 - ok
FreeBSD 6.0 x86 - ok
Ubuntu Linux 5.10 x86 - ok
Debian unstable (sarge) x86 - ok
Debian unstable x86_64 - ok

Command line

All commandline parameters are also described on editor manpage, which is installed with the program. To see the manpage, type command: man pdfedit.

Chapter 1. PDF Editor Commandline parameters

You can specify any number of filenames as parameters on commandline. One window will be opened for each file specified. If no file is specified on commandline, editor will be loaded initially empty.

Name of files can be mixed with options (parameter that begin with a dash). Invalid option on commandline will cause editor to abort with error message. Names of options are case sensitive.

Options which require a parameter can be specified in "short form", like -d1 or "long form", like -d 1, both of these mean option -d with parameter 1.

Use -script, -eval and -run options to run any script besides the init script. These parameters are run/evaluated in the order they are specified on commandline and may be specified multiple times. If these parameters are specified in GUI mode, they are used in each window opened on program start, in commandline mode (console mode) they are used after commandline init script. After these scripts finish execution, the editor terminates.

Option --help

Print brief help about commandline options to STDOUT and exit

Option --version

Print version of editor to STDOUT and exit

Option -d (n)

Set verbosity of debugging messages reported by editor. Only messages below or equal level specified in parameter will be shown, default is debugging level 1. Also, any of symbolic constants defined below (case insensitive), or starting part of them may be given instead of corresponding number.

Table 1.1. Explanation of debugging levels

0PANICCritical errors
1CRITICALCritical errors, but at least the program can exit somewhat gracefully
2ERRORUsual errors
3WARNINGComments about some unusual behavior
4INFOInformation about some internal behavior
5DEBUGDebugging messages

Setting this to -1 mean no debug messages will be shown at all, not even the most critical ones. Debugging messages are sent to STDERR.

Option -console

Run in commandline mode. No editor windows are opened and commandline init script is executed.

Option -script (filename)

Run script with given filename. Look for the script in script path. If not found, look for the script in current directory.

Option -run (filename)

Run script with given filename, but unlike -script option, script path is not searched.

Option -eval (code)

Evaluate given script code

Option -s (filename)

This is just shortcut for -console -script (filename)

Option --

Stop processing options. Any further parameters after this one are treated as filenames. This can be useful if you want to open file, that have name beginning with a dash.

Chapter 2. Localization

PDF Editor is run in english language by default, but by setting environment variable LANG before launching the program, you can tell PDF Editor to look for specific language file. If the localization you requested is not available, english will be used instead.

Aside default english, these localizations are available:

cs - Czech
sk - Slovak

Graphical user interface (GUI)

Window of PDFEdit is split to 5 basic parts : Menu, Toolbars, Command part, Page space and Objects tree + property editor.

Layout of PDFedit's GUI

Layout of PDFedit's GUI

Chapter 3. Command console

Command console is useful for typing in your own scripts and macros. In can be set in 3 different modes of behavior (see settings of command console).

You can type your script code in the lower part of the window (the commandline or script editor, depending on settings) and observe output of your commands in upper part (console)

Chapter 4. Page space

The page space displayes one page from opened document. Page number is shown at the bottom of displayed page, as is number of pages in document. On the right the actual position of mouse cursor on page in specified units is shown.

Page space design

Page space design

Changing page information

There are two independent information in page space which must be actualized.

First is the image of the page itself and information about page count. This part is updated only if someone calls script function go() because it can be very slow (to update page after each change could be a performance problem). Reload page button in toolbars and menu (and many other useful functions) call go() automatically. But direct changes in Object tree and property editor and changes using scripting do not update the page and page count automatically.

The second is the mouse position on page. Position must be converted into internal coordinates. The position does not depend on zoom level or actual rotation of page. (If the text starts at position [x:6, y:7 cm] in 100% zoom the same position will be used to started the text in 200% zoom.)

Notice: The most common way is to have the zero in the left-bottom edge of page and to have the maximum in right-top edge.

It can happen that after a zoom change the outer page space is not updated. To corret this call either script go() function or click the reload page button.

Popup menu

Right click of a mouse displayes a menu which will be displayed near the cursor. You can choose from two functions

  • Save page as image

  • Save selected area as image

The latter one can be used only when a selection is already present.

Both functions store portion of viewed page to an image file. Format of the image file is depending on the system and version of Qt.

Save page as image stores actual viewed page to an image file. If only a part of a page is displayed, only the part of page is stored.

Save selected area as image stores only selected area. If selected area is fragmented or has not a rectangle shape, then a bounding rectangle of selected area is sotred. If selected area is bigger then actual displayed part of page, storing area is cropped with same rectangle as page is cropped in Save page as image.

Chapter 5. Object tree, Stream, Selection and Property editor

The right side of PdfEditor consists of two main parts Object tree and Property editor. It can be further specialized to Selection and Stream windows.

Pdf file consists of objects which form a tree-like structure. There are seven simple objects

  • null

  • boolean

  • integer

  • real

  • string

  • name

  • reference

and three complex

  • array

  • dictionary

  • stream

Object tree displays the tree-like object hierarchy starting at the most important objects and Property editor displays the contents of selected object in human readable form and allows editing the objects in raw form.

There is one important object called content stream which consists of many small operators and their operands. Everything visible on a page is in these content streams. Pdf operators are the objects that contorl what is displayed on a page. The content stream is shown in Stream window in human editable form.

Last tool used to display objects is the Selection window. When some operators are selected using selection modes, those operators are displayed in the Selection window.

Object tree, Stream, Selection and Property editor

Purpose and usage

The purpose of these windows is to enable complete control over pdf objects and structure of a pdf file. It shows raw pdf objects in user friendly way with the possibility to traverse the objects using the tree like structure, select special category of operators and perform operation on resulting set, see exactly which operators were selected using graphical selection tools. It also allows editing raw objects which mostly requires knowledge of the pdf standard.

We gain complete control over pdf file with this tool. It can be used for advanced editing that almost makes PdfEditor a pdf creator. With the description of operators, object type highlighting and object importance visualization this tool can be also used by normal users for simple but powerful editions. We can add and delete objects almost at will (some top level objects are just for more human readibility and can be neither deleted nor added.)

Object tree start objects

There are three main objects in the object tree.

  • Catalog

  • Pages

  • Outlines

Catalog object is the start point of all objects. Any object can be reached from Catalog. Pages and Outlines are just shortcuts for special objects somewhere deep in Catalog object.

Catalog

Root object of all objects.

Catalog

Pages

Set of all pages and it is a shortcut to all page dictionaries.

Pages

Outlines

List of all outlines with the ability to edit the title.

Outlines

Adding and deleting objects

This feature is for very advanced users. Object tree can be used to to add and delete objects, stream and selection to delete objects. User can choose the type of object which to add. Deletion of pdf operator operands is not allowed because in most cases the result would be an invalid content stream.

Creating pdf files

The adding object feature can be used to create completely new pdf files. With the help of scripting, PdfEditor can be used as pdf creator. The advantage is that we can use arbitrary empty template pdf file created by any drawing tool and PdfEditor to add objects into it. The creation of pdf files containing text is limited because we do not support our own fonts only standard ones.

Controls

There are two ways how to to open, close and select objects. We can use either mouse or arrows. Up/down is used to go one object above/below current and right/left is used to open/close complex objects.

When an object is selected right mouse click opens a menu with operations we can perform on the object according to its type.

Mouse right click menu

We can add properties/objects using Insert key or clicking

Add button

button and delete properties/objects pressing Delete key or clicking

Delete button

button. Not always is adding and deleting possible.

Multiselect

We can use multiselect to select more objects and to perform specific action on all of them. We can use this feature in all mentioned tools (Object tree, Selection, Stream). This can dramatically increase speed of editing.

Multiselect

Object tree

There are many special objects. You can specify which of them to display and which not. And whether crucial objects should be locked to changes. In menu click Tools->Options and select Editor tab. In order to take effect reload the object tree.

Editor options

In menu click Tools->Options and select Object tree tab. In order to take effect reload the object tree.

Object tree display options

Property mode

Many pdf objects are compulsory or must contain required entries or have specified values. Incompetent manipulation with these objects can result in invalid pdf files or non predictable output. Therefore a mode is assigned to every property which indicates the importance of the property. There are

  • Unknown - mode not known

  • Normal - normal property, editing should not harm

  • Hidden - not crucial property, editing should not harm

  • Read only - not property, manual editing does not make sense

  • Advanced - crucial property, incompetent editing can make harm

When mouse cursor is over a property the property mode is displayed as text in the status bar. Hidden, read only and advanced tincture property colour to blue, gray and red. It depends on the theme used.

Visualization of object mode

These settings are stored in mode.conf file which can be easily modified to match user own pdf skills.

Adding and deleting properties

Adding and deleting objects in the object tree is possible. There are two keyboard shortcuts for this, Insert of adding, Delete for deleting

Property editor

Editing properties

Each pdf object has simple value or set of values which can be changed. Almost all pdf operators have operands which are normal pdf objects which can be changed. Implicit changing of object types is not allowed (e.g. integer object to string etc.) but this can be done by deleting and adding desired property type. When changing integer object only integers are accepted, when changing boolean values only true/false is accepted etc.

Editing a property

When editing a reference number a dialog appears which verifies whether a pdf object with specified reference number exists.

Text selection

To make a change visible perform these steps

  • edit the object value

  • press enter or click away from the property

  • reload page if the change is visible

Selection

PdfEditor allows selecting specific operators easily using selection modes. There are two main object selection modes namely text selection and graphical object selection. The third way how to select objects is using multiselect which allows us to manually select more objects. Selection is very useful when performing an action on many objects (e.g. deleting...)

Text selection

When this mode is selected we can select only text objects.

Text selection

Note: TrueType fonts use pictures to draw letters and that makes it very difficult to compute the height of the letter. The height of a true type letter can be incorrect.

Graphical objects selection

When this mode is selected we can select only graphical objects. Many pdf creators are putting strange invisible graphical objects to page so sometimes it is difficult to select the right graphical object.

Graphical object selection

Deleting objects

Press Delete key to delete selected objects.

Stream

Page is drawn by executing operations which are equal to small changes. These changes are stored in content stream of a page. You can display these operations by clicking Pages->Page #->Stream # in Object tree. New tab is displayed which shows pdf operators and their operands.

Stream

Operator description

As mentioned above, operators control what is displayed on a page. For advanced editing, it is crucial to be able to change them. For non advanced users the operator tags are not very intuitive so a human description of each operator is shown in the status bar.

Operator description

The definition of the operators is stored in operator.hint and can be edited freely.

Operator modes

There many operators but only few worth changing manually. To allow fast search of these operators, operator modes were designed. After selecting one of the operator modes in Stream window, only those operators are shown. Currently there are four operator modes

  • operators

  • text operators

  • font operators

  • graphical objects iterators

Operator modes

Adding and deleting properties

Only deleting is possible.

Chapter 6. Menu, toolbars and on-click functions

This chapter describes only default functionality available from menu and toolbars because it is very customizable and can very differ from release to release. Removing and adding new functionality is very simple.

File

Default menu item - File

Default menu item File

File - description of items

Open...

Close currently opened docuement (if it is changed, shows question dialog whether we want to save changes) and displays open file dialog. If file is selected and contains correct pdf document, it is opened in current window.

Script equivalent: func_load()

Save

Saves changes for current document. This changes will appear as new revision after document is closed. Repeating save action will update previous Save calls. If you whant to close bunch of changes and stores them as new revision use Save new revision . This will allow you to conserve previous changes and continue in new bunch of changes.

Script equivalent: func_save()

Save copy...

Saves copy of current document in selected revision (TODO link). This feature is very usefull if you want to make changes for older revisions. This is normally not possible, because pdf documents doesn't support revision branching. So you can select desired revision and then use Save copy to create new pdf file, which contains everything up to selected revision. This file can be then opened and manipulated as usual.

Script equivalent: func_savecopy()

Save new revision

This is same as Save except that changes are closed and forms new revision which is definitivelly written to the file. All changes made after doesn't affect saved revision and goes to the currently newest one (as usual).

Script equivalent: func_saverev()

New window

Open new window of PDFedit.

Script equivalent: newwindow()

Close window

Close actual window of PDFedit. If the document is changed allows saving the changes.

Script equivalent:

Quit

Close all windows of PDFedit and quit.

Script equivalent: closeAll()

View

Default menu item - View

Default menu item View

View - description of items

First page

Show first page of viewed document.

Script equivalent: PageSpace.firstPage()

Prev page

Show previous page of viewed document.

Script equivalent: PageSpace.prevPage()

Next page

Show next page of viewed document.

Script equivalent: PageSpace.nextPage()

Last page

Show last page of viewed document.

Script equivalent: PageSpace.lastPage()

Zoom in

Zoom in the displayed page.

Script equivalent: PageSpace.zoomIn()

Zoom out

Zoom out the displayed page.

Script equivalent: PageSpace.zoomOut()

Show/Hide commandline

Show or hide command console (see layout of PDFedit's gui).

Script equivalent: showHide("commandline","hideCmd")

Show/Hide property editor

Show or hide property editor (see layout of PDFedit's gui).

Script equivalent: showHide("propertyeditor","hideProp")

Show/Hide object tree

Show or hide object tree (see layout of PDFedit's gui).

Script equivalent: showHide("tree","hideTree")

Show/Hide status bar

Show or hide status bar (see layout of PDFedit's gui).

Script equivalent: showHide("statusbar","hideStatus")

Find text

Find dialog for text search is executed. It searches text on current page.

Search dialog

Search dialog

This simple dialog allows us to search for all occurrences of text on actual page and to select them.

Note: Usually the text structure (paragraphs, lines, words) is not kept. More words can create one operator or more operators can create one word. If the text is found the smallest possible operator is higlighted which can be bigger than searched text.

Script equivalent: findText()

Tools

Default menu item - Tools

Default menu item Tools

Tools - description of items

Options

This menu item opens options dialog. (see settings).

Script equivalent: options()

Insert pages from other document

This tool enables page insertion from arbitrary pdf document. After item selection a dialog is opened. This dialog works in 3 steps:

  • Select pdf file from which we want to insert pages. When the file is selected, Open button should be pressed. Then the middle part is enabled and current top part is disabled (file can't be changed after Open is pressed).

  • Move pages which should be inserted from right item list into the left list in which are pages from current document. Use << button to move currently selected page from right list to left (before selected item in left list). If you want't to move page back, use >> button. Inserted pages can be moved in left list by Up and down buttons.

    Note

    Original pages (in left list) can not be moved or removed.

    Items lists allows multiselection.

  • When all pages which we want to insert are in their correct position among pages from current document, press OK button for insertion. You can press Cancel button anytime to skip this dialog.
    Insert pages dialog

    Insert pages dialog

Script equivalent: mergeDocument()

Delinearize

This tool converts linearized pdf files to normal pdf files. When executed, a file open dialog is displayed. Linearized pdf file should be selected. After open file is selected save dialog is opened for output (delinearized) file. After both files are selected, delinearization process starts. This may fail if input file is not linearized or it is not valid pdf document. In this case an error dialog is displayed.

Script equivalent: delinearize_gui()

Page

Default menu item - Page

Default menu item Page

Page - description of items

Save page as image...

Save page to image file. For more details see popup menu for page space.

Script equivalent: savePageImage( false )

Reload page

Reload page and information about page count in opened document. For more details see refreshing page.

Script equivalent: go()

Extract text from page

Extract text from page into dialog.

Dialog with extracted text from page

Dialog with extracted text from page

If text is not readable or has bad encoding try setting another (see settings). Some Pdf files does not contain information aboud text encoding.

Script equivalent: viewPageText()

Rotate page 270 degrees

Rotate page about 270 degrees.

Script equivalent: rotatePage(-90)

Rotate page 90 degrees

Rotate page about 90 degrees.

Script equivalent: rotatePage(-90)

Edit page metrics

Execute dialog to change page metrics. Values in the dialog are converted into default units (see settings).

Dialog to change page metrics

Dialog to change page metrics

Script equivalent: editPageMediaBox()

Add system font to page

Because page must have text font defined in its resources (see PdfReference) otherwise the font can not be used. This function adds one system font into a page. Specify which font to add from a list of all possible fonts.

Dialog to add system font to page

Dialog to add system font to page

Note: When adding text onto a page the selected font is automatically added to the page if not already present.

Script equivalent: addSystemFont()

Set page transformation matrix

With this dialog user can change the transformation of a page (e.g. to half size and rotate about 90 degrees). For details see to PdfReference.

Script equivalent: setPageTm()

Draw line

See mode to drawing line.

Script equivalent: onSelectMode_drawLine()

Draw rectangle

See mode to drawing rectangles.

Script equivalent: onSelectMode_drawRect()

Add text

See mode to add new text.

Script equivalent: onSelectMode_addText()

Strike through

See mode to strike trough of text.

Script equivalent: onSelectMode_strikeThrough()

Highlighting text

See mode to highlighting text.

Script equivalent: onSelectMode_highlightingText()

Edit

Default menu item - Edit

Default menu item Edit

Edit - description of items

Select all objects

See mode to select all objects.

Script equivalent: onSelectMode_AllObjects()

Select graphical operators

See mode to select graphical operators.

Script equivalent: onSelectMode_GraphicalOperators()

Select text

See mode to select text.

Script equivalent: onSelectMode_Text()

Select annotations

See mode to select annotations.

Script equivalent: onSelectMode_Annot()

Set color

Set actual foreground color and background color to all selected operators in Stream or Selection tab of Object tree and property editor.

Script equivalent: setOpColor()

Set font

Set actual font and font size to all selected operators in Stream or Selection tab of Object tree and property editor.

Script equivalent: editFontProps()

Set relative position of operator

Set delta move position of every selected operator. Operators must be selected in order for this function to be avaliable. Useful when moving single operators on a page (see selection modes).

Script equivalent: moveOperPos()

Change relative position

Set delta move position of a text block. Text operators must be selected in order for this function to be avaliable. Useful when moving text paragraphs on a page (see selection modes).

Script equivalent: moveTextPos()

Set line dash style

Set dash pattern of graphical objects. Graphical objects must be selected in order for this function to be avaliable.

Dash pattern dialog

Dash pattern dialog

After choosing the dash pattern this dash pattern will be set to all selected graphical operators.

Note: Changing dash pattern may result in changing dash pattern of other graphical operators (see PdfReference).

Script equivalent: setDashPattern()

Set line width

Set line width to all selected graphical operators.

Note: Changing line width may result in changing line width of other graphical operators (see PdfReference).

Script equivalent: setLineWidth()

Help

Default menu item - Help

Default menu item Help

Help - description of items

About

Shows About dialog box.

Script equivalent: about()

Help

Shows help dialog which includes

  • Commandline usage

  • Keyboard shortcuts

  • Scripting help

  • Utility Framework documentation

  • Input Dialog Framework documentation

Script equivalent: help()

Menu item from test plugin

Menu item for debugging purposes.

Script equivalent: testplugin()

Toolbars

Toolbars are shortcut for functions found either in menu, or by right clicking on specific objects. Menu items can be either in enabled or disabled state. Some operations have no effect when a document is not open so they are disabled. Also some operations are not avaliable when specific objects from specific windows are not selected.

Main

Toolbar - Main

Toolbar - Main

Open ...
See open file.
Save
See save file.
Options
See settings.
Close window
See close window.
Show/hide commandline
See show/hide commandline.

Page

Toolbar - Page

Toolbar - Page

First page
See first page.
Prev page
See prev page.
Page position
Actual page number which can be changed. To load the page press enter.
Next page
See next page.
Last page
See last page.
Rotate page 270 degrees
See rotate page 270 degrees.
Rotate page 90 degrees
See rotate page 90 degrees.
Edit page metrics
See edit page metrics.
Add system font to page
See add system font to page.
Set page transformation metrics
See set page transformation matrix.
Extract text from page
See extract text from page.
Zoom out
See zoom out.
Zoom
Manual selection of zoom level.
Zoom in
See zoom in.
Move page up
Move displayed page one level up which means the page number will decrement.
Move page down
Move displayed page one level down which means the page number will increment.
Remove page
Remove displayed page from the document.

Selection modes

Toolbar - Selection Mode

Toolbar - Selection Mode

Select all objects
See select all objects.
Select graphical operators
See select graphical operators.
Select text
See select text.
Select annotations
See select annotations.

Draw

Toolbar - Draw

Toolbar - Draw

Draw line
See draw line.
Draw rectangle
See draw rectangle.
Add text
See add text.
Strike through
See starting through.
Highlighting text
See highlighting text.
Foreground colour
This is the default foreground colour. Many operations use this colour to draw objects (e.g. lines, rectangles,...)
Background colour
This is the default background colour. Many operations use this colour to draw objects (e.g. rectangle background,...)
Line width
This is the default line width. Many operations use this number to specify object property (e.g. line width, ...)

Text

Toolbar - Text

Toolbar - Text

Font
According to pdf specifications, pdf viewers must support several standard fonts. The selected font is used as the default in operations where font name is needed (e.g. inserting text lines, ...)
Font size

Operator

Toolbar - Operator

Toolbar - Operator

Set color
See set color.
Set font
See set font.
Set line width
See set line width.

Dynamic

Toolbar - Dynamic

Toolbar - Dynamic

This toolbar contain dynamic items and its content is updated based on context, i.e. what are you doing now. It can contain field used to edit text in PDF operators or icons used to filter displayed operators in current stream. There are four modes available for filtering operators. First and default mode is to show all operators. The other three modes are to show only text, only font and only graphical operators. The filter settings are per stream, so you can set diffrnent filterig in different streams.

Treeview

Toolbar - Treeview

Toolbar - Treeview

When changing pdf file using Object tree, Selection or Stream tab we can add and remove objects using either keyboard or these two buttons.

Revision

Toolbar - Revision

Toolbar - Revision

When a document is changed it can be saved either as new copy, to old file or to new revision. The last option saves all changes made to the document. The history of changes is embedded in the document itself. We can choose which revision we want to have displayed. Only the last revision can be edited. Otherwise we have to save it before editing.

Functions in menu and toolbars

Following functions are called from menu and toolbars and provide user friendly enviroment for simple editing.

Selection modes

Modes in this section can be used to select objects on the displayed page. All modes support move and resize of selected objects, but the real functionality depends on implemented scripts, which perform real action with selected objects (e.g. moving nongraphical operators (text, pictures) and moving annotation activation rectangle, but moving graphical operators (line, rectangle, ...) is not implemented).

When moving selected objects cursor must be in the selected region (cursor pointer will change to cross from arrows pointer). After pressing the mouse left button selection region can be moved. After releasing mouse left button script moving function is executed on the selected operators.

When resizing objects cursor must be moved to the edge of bounding rectangle of selected region (cursor will change to two arrow oriented from each other direction - there are four possibilities how to resize: left-right, top-bottom, (left-top)-(right-bottom) and (left-bottom)-(right-top)). After pressing the left mouse button selected region is resized by cursor movement. Script function for resizing is executed when mouse left button is released.

When cancelling started action press Esc key before releasing left mouse button. If Esc key is pressed during no action all objects on the page are unselected.

Selecting all objects

This mode is usefull when selecting page objects (without annotations - see mode to select annotations) which are not text (see mode to select text) or graphical (see mode to select graphical operators) operator (line, rectangle, but not image).

When this mode is activated,nonempty areas can be selected pressing the mouse left button, dragging the mouse and releasing left button. All objects within selected area will be selected.

When clicked only once, the one top level object on the page is seleceted. If clicked again the second top most object is selected etc. User doesn't need to know the size of desired object.

This mode is very usefull when because only few objects have the same size Object tree and property editor.

To activate this selection mode just click on appropriate place in the toolbar toolbar Selection modes) or select it in menu (see menu item Edit).

Selecting graphical operators

This mode is the same as mode to select all objects except for it only selects graphical operators.

Selecting text

This mode is useful when selecting text on page. It behaves like expected from text selecting. Word and line order is respected on pages with horizontal text lines (most of pdf files).

Text selection is very simple using this mode. The selection starts when mouse left button is pressed on a text element. (If the mouse is over a text element the cursor changes to ibeam.) When dragging, text is selected line by line. The selection is limited in how the text elements are stored in the pdf document (some documents have text elements equal to letters, to words, to lines or arbitrary).

Note: When a text on one line is written using different fonts it is very likely that it will be parsed into more lines. This is due to the fact that the base vertical positions are different and without wild guessing it is almost impossible to distinguish between text on one with different fonts and text on more lines with different fonts.

Selecting annotations

This mode displayes and enables selecting of annotations on a page. When activated each annotation is displayed as a rectangle (shows activation rectangle for each of annotations). It's very useful because user can see all the annotations on a page and does not need to search for (annotations can be hidden). Only very few viewers support this feature.

An annotations is selected when the mouse cursor is over. It is selected until the mouse cursor get over another annotation or till Esc key is not pressed.

Drawing and adding new objects

Drawing lines

Drawing lines is easy with this mode. First set default properties in the toolbar: foreground color, line width and dash style. Then by pressing the mouse left button and dragging a line is created. After releasing mouse button the line is drawn. The line drawn during dragging is only informative. The viewed part of the page is updated after each added line.

To cancel line drawing press Esc key before releasing the mouse button.

Drawing rectangles

Drawing rectangles and rectangles with background is easy with this mode. First set default properties in the toolbar: background color. Then by pressing the mouse left button and dragging a new rectangle is crated. After releasing mouse button the rectangle is drawn. The rectangle drawn during dragging is only informative. The viewed part of the page is updated after each added line.

To cancel rectangle drawing press Esc key before releasing the mouse button.

Adding text

This mode enables adding text lines onto the page. First set some default properties on the toolbar like foreground color, font and font size. Then by clicking mouse left button on page an edit box is shown where the added text is written. After pressing Enter the text will be displayed on the page. The viewed part of the page is updated after text addition.

The text is added to the page also if the text edit line losts focus (this can be unpleasant for window managers that set focus to windows under the mouse cursor). To cancel text addition press Esc key.

Note: When pages are rotated the text can appear unrotated. This is because the text uses own transformation matrix than the whole page.

Strike through text

You can easily strike through words, lines with this mode.

Selecting of text is the same as by mode to select text. After endind the selection scipt function is called which draws a line through selected text default colour, dash style and line width (for more details see mode to drawing line).

Highlighting text

Highlighting of text is a very desired feature. This mode can highlight selected text.

After activating this mode user can select text the same way as by mode to select text. After ending the selection script function is called which draws filled rectangle under each text operator with default background colour (for more details see mode to drawing rectangles).

Chapter 7. Settings

Settings options in PDFEdit is very easy. Options can be set are in gui or directly in configuration file pdfeditrc in ~/.pdfedit and in PDFEdit home directory. If exist diferent setting for some option, is use setting in ~/.pdfedit/pdfeditrc.

To execute options dialog in gui click to menu on Tools/Options. Or type to command console options(). Or click to options icon in toolbars.

Execute options dialog from menu

Execute options dialog from menu

Editor tab

Editor tab

Advanced mode

Open files in advanced mode, allowing some more advanced, but also potentially more destructive changes to be made to the file.

Show hidden properties

If checked, properties that are marked as hidden by configuration in mode.conf will be shown.

Allow editing read-only properties

If checked, properties that are marked as read-only by configuration in mode.conf will be fully editable.

Remember path of last opened/saved file

If checked, editor will remember path of last opened or saved file and when opening or saving file, the dialog will start in that directory. If unchecked, current directory is used.

Length units

This option allow to choose prefered length units. These will be used for showing coordinates in the preview window and also in some other places, like when editing size of the page.

Character encoding

Specify character encoding to use when editing text properties

Paths tab

Paths tab

You can set paths to various files here. The path is semicolon-separated list of directories, each of them can contain environment variablesm, which will be automatically expanded, such as $HOME (which will expand to user's home directory) or $LANG (which can expand to name of selected locale) There are also two special variables, $PDFEDIT_DATA will expand to directory with editor datafiles (/usr/local/share/pdfedit by default) and $PDFEDIT_BIN will expand to directory where the editor binary is located (/usr/local/bin by default)

Icon path

Paths in which to look for application icons.

Script path

Paths in which to look for script files.

Scripts to run on start

List of files which will be run on start.

Console log file

Name of file in which all console commands and output will be logged. If empty, logging will be turned off.

Object tree tab

Object tree tab

In this tab you can specify what items will be visible in the object treeview.

Document dictionary

This option toggles showwing of main document dictionary (called "document catalog") in tree.

Object dictionaries

This option toggles showwing of dictionaries of various objects (like pages) in tree.

Graphic objects

This option toggles showwing of graphic objects in tree.

Annotations

This option toggles showwing of outlines in tree.

Pages

This option toggles showwing of outlines in tree.

Outlines

This option toggles showwing of outlines in tree.

Content streams

This option toggles showwing of content streams in tree.

Simple objects

This option toggles showwing of simple objects (int,bool,real,string,name) in tree.

Sort dictionary items alphabetically

This specify whether items in dictionaries should be sorted alphabetically (checked) or in order they appear in PDF file (unchecked)

Commandline tab

The appereance of command editor can be customized in options dialog on tab "commandline". To execute options dialog click Tools/Options in menu or type options() in command editor or click the options icon in toolbar.

Commandline tab

Show return value of executed script in console

If this setting is checked, command console will print return value of last command after executing it. It has basically the same effect as if last command was a parameter of function print().

Show return value also for complex type

This will toggle displaying the return value for complex types, such as arrays, which are likely to produce lot of output, as arrays tend to be large.

Show errors from event handlers

Check this if you want to see error from callback handlers. If there is error in callback handler which is called very often, like handler for current item in tree being changed, it can produce lot of output.

Show command editor

If set, command editor is shown.

Command console without / with command editor

Command console without / with command editor

Show command line

If set, history is displayed in a combobox. This is useful when older history commands are needed.

Editable command line

If set, editable command line is shown in history combobox. This is usefull when small space for typing command is needed. (set command editor hidden).

History option

If set, history is saved and loaded to the command line. You can specify the maximum number of lines to store.

Note: History is saved when PDFedit's window is closed.

Toolbars tab

Toolbars tab

Each checkbox on this tab represent one toolbar in the program. You can toggle visibility of each toolbar here, if the checkbox before toolbar name is checked, the toolbar will be visible. If unchecked, the toolbar will be hidden.

Look and Feel tab

Look and Feel tab

In this tab, you can select look and feel of the editor

Aplication font

Specify font used in application, in all components except console window and statusbar, for which the fonts are set separately

Console font

Specify font that will be used in console window

Statusbar font

Specify font that will be used in statusbar

Style

You can select visual style used for decorating editor windows.

Icon theme

Select icon theme used for icons in menus and toolbars. There are two predistributed icon sets, default and hicolor. adding new set is easy, just add subdirectory with your icons to any directory in icon path.

Default icon theme

Hicolor icon theme

Use big icons

If checked, big icons (32x32) will be used. If unchecked, small icons (20x20) are used. If the icons in the set you are using have "wrong" size, they are automatically scaled.

Scripting documentation for PDF Editor

Introduction

PDFEditor have support for scripting. Evey item in menu (or toolbar) runs a script (mostly just short call of function, but using complex scripts from menu is possible), and also user can type script commands directly into commandline. Every invocation of script from menu will echo the command to the commandline, so user can learn how to do things in menu directly from commandline if he wants.

QSA is used for scripting, which is based on ECMAScript standard (if you don't know what ECMAScript is, it is basically the same syntax as JavaScript)

This documentation will not explain the language syntax, but will document all functions and objects that are exported from the application to the scripting engine so they may be used in scripts and menus. Also how the scripting work in general and how it can be configured will be explained.

Note

Scripts are not "secure" by design, as the API contain functions to read or write arbitrary files and directories and to execute external processes. See http://doc.trolltech.com/qsa-1.1.4/extensions-2.html for description of File, Dir and Process classes, which are available to script.

Startup scripts

When new editor window is launched (but before the document is loaded or created), file init.qs from application's data directory is run, then file userinit.qs from users's application configuration directory (which is $HOME/.pdfedit) is run, if it exists [1] . These files should contain declaration of all functions used in toolbars or menus and may also contain any startup code to be run before loading or creating new document.

In commandline mode, file init_console.qs from application's data directory is run instead, then file userinit_console.qs from users's application configuration directory (which is $HOME/.pdfedit) is run, if it exists [1]

After running these init scripts, any "plugin" scripts from directories specified in configuration are run. By default, these directories are:

  1. Directory scripts in application's data directory

  2. Directory scripts in application's binary directory

  3. Directory ./pdfedit/scripts in user's home directory

For "plugin scripts" in commandline mode, scripts are searched in console subdirectory of above directories instead.

Scripts are run in alphabetical order (by their filename, case sensitive) and if the same script is encountered in more than one directory, only the one in directory later in list is executed. This ensures that if user install newer version of some script in his home directory, only his version will get executed.

After that, the document is loaded (if it was not specified on commandline, the window will be initially empty without any document)

Note

Init script should not load a document while starting, as it will be replaced by new one as soon as the script finishes. If functionality such as "automatic loading of a document on startup" is desired, appropriate code should be added to onEmptyFile() function, which will be triggered after starting the editor with empty document. Alternatively, onLoad, onLoadUser or onLoadError fnuctions may be used for this.

Scripting API documentation

Scripting API documentation is included in Appendix