Table of Contents
- I. Document purpose
- II. PDFEdit general overview
- III. Installation
- IV. Command line
- V. Graphical user interface (GUI)
- 3. Command console
- 4. Page space
- 5. Object tree, Stream, Selection and Property editor
- 6. Menu, toolbars and on-click functions
- 7. Settings
- VI. Scripting documentation for PDF Editor
List of Tables
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 itself is divided into several parts:
- Part II, “PDFEdit general overview” which focuses on global view of application.
- Part III, “Installation” which focuses on instalation of PDFEdit. Describes what is need and how to configure instalation for specific user.
- Part IV, “Command line” which describes commandline parameters of program.
- Part V, “Graphical user interface (GUI)” which describes graphical user interface. Usage and simple manipulation with pdf documents.
- Part VI, “Scripting documentation for PDF Editor” which describes script language used in PDFEdit, with function and classes usable for editing pdf documents.
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.
These libraries are required to build and install PDF Editor:
| qt3 | Qt GUI Toolkit (Version 3.x) |
| boost | Boost C++ Libraries (smart_ptr, iostreams) |
| xlib | X 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.
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
Table of Contents
All commandline parameters are also described on editor manpage, which is installed with the program. To see the manpage, type command: man pdfedit.
Table of Contents
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.
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
| 0 | PANIC | Critical errors |
| 1 | CRITICAL | Critical errors, but at least the program can exit somewhat gracefully |
| 2 | ERROR | Usual errors |
| 3 | WARNING | Comments about some unusual behavior |
| 4 | INFO | Information about some internal behavior |
| 5 | DEBUG | Debugging 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.
Run in commandline mode. No editor windows are opened and commandline init script is executed.
Run script with given filename. Look for the script in script path. If not found, look for the script in current directory.
Run script with given filename, but unlike -script option, script path is not searched.
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 |
Table of Contents
- 3. Command console
- 4. Page space
- 5. Object tree, Stream, Selection and Property editor
- 6. Menu, toolbars and on-click functions
- 7. Settings
Window of PDFEdit is split to 5 basic parts : Menu, Toolbars, Command part, Page space and Objects tree + property editor.
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)
Table of Contents
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
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.
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.
Table of Contents
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
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.)
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.
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.
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.
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.
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
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
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.
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
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...)
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.
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
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
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.
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
Table of Contents
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.
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()
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
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()
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
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()
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
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
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
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()
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
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()
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 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.
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.
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.
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.
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, ...)
Toolbar - Text
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.
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.
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.
Following functions are called from menu and toolbars and provide user friendly enviroment for simple editing.
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.
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).
This mode is the same as mode to select all objects except for it only selects graphical operators.
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.
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 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 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.
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.
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 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).
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
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)
In this tab you can specify what items will be visible in the object treeview.
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.
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().
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.
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.
If set, history is displayed in a combobox. This is useful when older history commands are needed.
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).
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.
In this tab, you can select look and feel of the editor
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
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.
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:
Directory
scriptsin application's data directoryDirectory
scriptsin application's binary directoryDirectory
./pdfedit/scriptsin 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.