PDFedit user documentation - Appendix

Tries to delinearize PDF, reading from input file and writing delinearized result to output file. Does not check for overwriting output. Returns true if delinearization was successful, false in case of failure. In case of failure the error mesage is available via error() function.

string error()

Returns last error message (localized) from some operations (openFile, save, saveRevision, saveCopy, delinearize)

bool exists(string chkFileName)

Returns true if given file exists on disk, false otherwise

string[] functions(bool includeSignatures)

Debugging function usable by script developers. Returns list of all functions that are present in current script interpreter. Functions are sorted alphabetically. If includeSignatures is set, function signatures are returned, otherwise only names

string loadFile(string name)

Load content of file into string. File is expected to be in utf-8 encoding.

Pdf loadPdf(string name,bool advancedMode)

Loads a PDF file without replacing currently opened file in GUI. Scripts can manipulate the PDF file as necessary, but should close it with unloadPdf() method after it don't need to use it anymore. If advancedMode is set to true, document is opened in "advanced mode" (more advanced, but also more dangerous changes to it are possible)

string[] objects()

Debugging function usable by script developers. Returns list of all objects that are in current script interpreter

string pdftoxml (string inFile, Variant pagenums, string outFile)

Converts pdf to xml. inFile is name of PDF file to convert, pagenums is array with page numbers to convert, outFile is name of XML file to be created

void print(string str)

Outputs given string to command window, followed by newline. Useful to output various debugging or status messages

double rand()

return floating point pseudorandom value between 0 and 1 inclusive

void run(string scriptName,bool skipScriptPath)

Loads and runs script from given filename. File is looked for in the script path, unless absolute filename is given or parameter skipScriptPath is specified. If the file is not found in script path, it is searched in current directory.

bool saveFile(string name,string content)

Save string into file. File will be saved in utf-8 encoding.

void setDebugLevel(string param)

Sets new debugging verbosity level. Accepts same parameter as -d option on commandline (either number or symbolic constant).

string time(string format)

Return current date/time using given format string If format string is "ISO", return time in ISO format. If format string is not specified or empty, return in default localized format. Format string may contain following:

d	day without leading zero
dd	day with leading zero
ddd	short localized day name
dddd	long localized day name
M	month without leading zero
MM	month with leading zero
MMM	short localized month name
MMMM	long localized month name
yy	two digit year
yyyy	four digit year
h	hour without leading zero
hh	hour with leading zero
m	minute without leading zero
mm	minute with leading zero
s	second without leading zero
ss	second with leading zero
z	milliseconds without leading zeroes
zzz	milliseconds with leading zeroes
AP	use AM/PM display. AP will be replaced by either "AM" or "PM".
ap	use am/pm display. ap will be replaced by either "am" or "pm".

Anything else is left as is.

int tick()

Return "tick counter" in milliseconds, usable to measure time differences

Variant transformationMatrixDiv(Variant oldCTM,Variant newCTM)

Solve equation oldCTM * requiredCTM = newCTM (find matrix for inverse transformation). Return requiredCTM. NULL is returned if no such matrix exists All transformation matrixes are represented as array of 6 doubles.

Variant transformationMatrixMul(Variant ma,Variant mb)

Multiply vector by transformation matrix (resulting in transformad vector) or transformation matrix by another transformation matrix (joining transformations int single matrix) First parameter (ma) is vector or matrix to multiply. Second parameter (mb) is transformation matrix Transformation matrix is represented by array of 6 float numbers Vector is array of 2 float numbers

Variant transformationMatrixMul(double a0,double a1,Variant mb)

Variant of transformationMatrixMul. Multiply vector [a0,a1] by transformation matrix mb and return resulting transformed vector

string tr(string text,string context)

Translates given text to current locale. Optional parameter context can specify context of localized text. Returns translated text.

void treeNeedReload()

You can call this to explicitly request the tree to reload after the script finishes execution.

string utf8(string original)

Return string converted from utf8 encoding to unicode encoding

string[] variables()

Debugging function usable by script developers. Returns sorted list of all variables that are in current script interpreter.

string version()

Returns version of editor (in format 'major.minor.release')

Chapter 2. Static functions in GUI

Table of Contents

void processEvents()
void setItemText(string name,string newText)
string getItemText(string name)
void about()
void addAnnotation(Page page,double x1,double y1,double w,double h)
void addObjectDialog(IProperty container)
void checkItem(string name,bool check)
void clearConsole()
void closeAll()
bool closeFile(bool askSave,bool onlyAsk)
void createMenuItem(string parentName,string name,string caption,string action,string accel,string icon,string[] classes=QStringList())
void createNewWindow()
void enableItem(string name,bool enable)
string filename()
string fileOpenDialog()
string fileSaveDialog(string oldName)
string fileSaveDialogXml(string oldName)
Color getColor(string colorName);
string getEditText(string textName)
double getNumber(string name)
void help(string topic)
bool isVisible(string widgetName)
void message(string msg)
Variant mergeDialog()
Variant selectPagesDialog (string filename) const
bool modified()
bool openFile(string name)
void openFileNew(string name)
void options()
Page page()
int pageNumber()
Color pickColor();
Menu popupMenu(string menuName)
bool question(string msg)
int question_ync(string msg)
void restoreWindowState()
bool save()
bool saveCopy(string name)
bool saveRevision()
void saveWindowState()
void setColor(string colorName,Variant newColor)
void setEditText(string textName,string newText)
void setNumber(string name,double number)
void setPredefs(string name,string predefs)
void setTooltip(string name,string tip)
void setPredefs(string name,string[] predefs)
void setRevision(int revision)
void setVisible(string widgetName, bool visible)
void showItem(string name,bool show)
TreeItem treeRoot()
TreeItem treeRootMain()
void warn(string str)
TreeItem firstSelectedItem(string name)
TreeItem nextSelectedItem()
CObject firstSelected(string name)
CObject nextSelected()
QProgressBar * progressBar()

void processEvents()

Allow application to process its events, so the gui can redraw itself. Useful, it it is called periodically while doing some lenthy operation

void setItemText(string name,string newText)

Set text of all menu and toolbar items with given name to specified string. The string will be transtated according to the translation file, so it is suggested to supply english text and add corresponding localized translation into the localization file.

string getItemText(string name)

Get text of menu or toolbar item with given name. Returns untranslated (english) string, even when the application is run using another language translation. When setting back the same string, it will be re-translated according to translation file, if different GUI language is selected

void about()

Invokes "About" dialog, showing information about this program and its authors

void addAnnotation(Page page,double x1,double y1,double w,double h)

Creates dialog for annotations creation. Parameter page is page in which the annotation will be added (x1,y1) are coordinated of lower left point of annotation rectangle. W is the rectangle widht and h is its height Returns after annotation have been inserted into page, or dialog have been cancelled

void addObjectDialog(IProperty container)

Invokes dialog for adding additional objects to specified container (which must be Dictionary or Array). After invoking dialog, this function returns immediately and the dialog is left for the user to use. If given object is not specified, curently selected object in property editor is used. If the object is not Dictionary or Array, no dialog is shown.

void checkItem(string name,bool check)

Check (second parameter is true) or uncheck (false) item in toolbar and/or menu, given its name If you prefix name with slash ("/"), you will affect "class" of items - every item that belong to the specified class

Note

Toolbuttons will automatically convert to Togglable toolbuttons this way and will start togling itself automatically on each succesive click

void clearConsole()

Clear the console output window

void closeAll()

Closes all windows (and thus ends application)

bool closeFile(bool askSave,bool onlyAsk)

Closes file opened in this editor window. if askSave is true, user is asked to save the file if it is modified. if onlyAsk is true, file is not actually closed, only user is asked if he want to save work (if not specified, defaults to false). returns true in case of success, or false if user decide not to close current document and keep it open.

void createMenuItem(string parentName,string name,string caption,string action,string accel,string icon,string[] classes=QStringList())

Load one menu or toolbar item and insert it into parent menu or toolbar. If the name is "" or "-", separator is inserted on place of the item and rest of parameters are ignored. If inserting item into toolbar and the name will match one of the special items, the special item will be inserted in toolbar and rest of the parameters are ignored. Items that are loaded from settings have theyir name equal to the key in setting they are stored under.

parentName	Name of parent menu/toolbar. If NULL/empty, main menubar is the parent
name	Name of the item. Must be unique.
caption	Caption of item
action	Script to execute when the item is selected
accel	Keyboard accelerator
icon	Name of icon to use
classes	List of item classes

void createNewWindow()

Creates new editor window with empty document in it.

void enableItem(string name,bool enable)

Enable (second parameter is true) or disable (false) item in toolbar and/or menu, given its name If you prefix name with slash ("/"), you will enable or disable "class" of items - every item that belong to the specified class

string filename()

Return name of file loaded in editor window. If the file does not exist on disk (not loaded any file, or file was never saved, having no name), empty string is returned.

string fileOpenDialog()

Invokes "open file" dialog and return selected filename, or NULL if dialog was cancelled

string fileSaveDialog(string oldName)

Invokes "save file" dialog and return selected filename, or NULL if dialog was cancelled. If file selected in dialog already exists, user is asked to confirm overwriting before returing its name.

string fileSaveDialogXml(string oldName)

Invokes "save file" dialog for XML file and return selected filename, or NULL if dialog was cancelled. If file selected in dialog already exists, user is asked to confirm overwriting before returing its name.

Color getColor(string colorName);

Get color from color picker with given name. Returns false if the color picker does not exist.

string getEditText(string textName)

Get text from editbox or text selection box in toolbar with given name. Returns false if the box does not exist.

double getNumber(string name)

Get number from number editbox in toolbar with given name. Returns 0 if the number editbox does not exist.

void help(string topic)

Invokes program help. Optional parameter is topic - if invalid or not defined, help title page will be invoked

bool isVisible(string widgetName)

Check if part of the window is visible (returns true) or hidden (returns false) widgetName specifies which part:

commandline	Command line
rightside	Right side tools (Tree Window and property editor)
propertyeditor	Property editor
tree	Tree window
statusbar	Statusbar

void message(string msg)

Show simple messagebox with specified message and wait until user dismiss it

Variant mergeDialog()

Bring up "merge pages from another PDF in this document" dialog. Returns result of merge or NULL if dialog was cancelled Result is array of three elements:

First element is array with page numbers
Second element is array with page positions
Third is filename of the document to be merged in

Variant selectPagesDialog (string filename) const

Bring up "select pages" dialog. Returns result of selection or NULL if dialog was cancelled. Result is array of three elements:

First element is array with page numbers
Third is filename of the document to be merged in

bool modified()

Return true if the document was modified since it was opened or last saved, false otherwise.

bool openFile(string name)

Opens file with given name in this editor window. Opens without any questions, does not ask user to save changes to current file, etc ... Return true on success, false on failure to load file.

void openFileNew(string name)

Opens file with given name in new editor window

void options()

Invokes options dialog. Does not wait for dialog to be closed by user and return immediately.

Page page()

Return currently shown page

int pageNumber()

Return page number of currently shown page

Color pickColor();

Invoke dialog to select color and return the color that user have picked, or false if user cancelled the dialog.

Menu popupMenu(string menuName)

Create and return a Menu object. The menuName parameter specifies name of item or list from configuration, that will be used to initially fill the menu with items. If this parameter is not specified or invalid, the menu will be initially empty. See documentation for Menu object type for more info about using popup menus.

bool question(string msg)

Show Yes/No question and wait for answer. Return true if user selected "yes", or false if user selected "no"

int question_ync(string msg)

Show Yes/No/Cancel question and wait for answer. Return 1 if user selected "yes", 0 if user selected "no", -1 if user cancelled dialog (selecting Cancel)

void restoreWindowState()

Restore state of current editor window (size and position of window and elements inside it) State is restored from state saved in editor's configuration file.

bool save()

Save currently edited document. If current document have no name, user will be asked for name. If it is not possible to ask user or user presses cancel in file chooser, document is not saved. Return true if document was saved, false if it was not saved for any reason (file write error, user refused to give filename on new file ...)

bool saveCopy(string name)

Save currently edited document (with currently active revision) under different name. Return true if document was saved, false if it failed to save for any reason

bool saveRevision()

Save currently edited document, while creating new revision in the process. Return true if document was saved, false if it was not saved for any reason.

void saveWindowState()

Save state of current editor window (size and position of window and elements inside it) State is saved to editor's configuration file.

void setColor(string colorName,Variant newColor)

Set color of color picker with given name

void setEditText(string textName,string newText)

Set text in toolbar editbox with given name or set selection in text selection box. If you specify string that is not one of the items in the selection box, the current item will remain selected.

void setNumber(string name,double number)

Set number in toolbar number editbox with given name

void setPredefs(string name,string predefs)

Set list of predefined values for number edit box or select text box with given name. The values in the list must be separated by commas. For number edit box, the user is still able to type in any value not in the list.

void setTooltip(string name,string tip)

Set tooltip text for specified number edit box or select text box with given name. Tooltip text will be shown when hovering with mouse over the tool.

void setPredefs(string name,string[] predefs)

Set list of predefined values for number edit box or select text box with given name. For number edit box, the user is still able to type in any value not in the list.

void setRevision(int revision)

Change active revision in current PDF document

void setVisible(string widgetName, bool visible)

Set part of the window to be either visible or invisible, widgetName specifies which part, see isVisible for list of possible names.

void showItem(string name,bool show)

Show (second parameter is true) or hide (false) item in toolbar, given its name If you prefix name with slash ("/"), you will affect "class" of items - every item that belong to the specified class

TreeItem treeRoot()

Return root item of currently selected tree

TreeItem treeRootMain()

Return root item of main tree

void warn(string str)

Outputs given warning string to command window, followed by newline, and show this string in a messagebox to alert user.

TreeItem firstSelectedItem(string name)

Return first selected tree item. Set internal selected item pointer to first selected item For getting other selected tree items (in case more than one is selected, repeat calling nextSelectedItem() until NULL is returned (no more items)

Example 2.1. Getting through list of selected tree items

 treeItem=firstSelectedItem();
 while (treeItem) {
  doSomething(treeItem);
  treeItem=nextSelectedItem();
 }

You can optionally specify different tree as parameter (by default, selected items from currently shown tree are taken) Specify "main" for main tree, "select" for selected operators or use number to specify number for Nth tree (indexed from zero). Omitting the parameter or specifying "current" will use currently shown tree If specified tree does not exist or its name is invalid, NULL is returned

TreeItem nextSelectedItem()

Return next selected tree item. Move internal selected item pointer to next selected item (or invalidate it if no more selected items is found)

CObject firstSelected(string name)

Return object held in first selected tree item. Set internal selected item pointer to first selected item For getting other selected tree items (in case more than one is selected, repeat calling nextSelected() until NULL is returned (no more items)

Example 2.2. Getting through list of selected items

 treeObject=firstSelected();
 while (treeObject) {
  doSomething(treeObject);
  treeObject=nextSelected();
 }

CObject nextSelected()

Return object held in next selected tree item. Move internal selected item pointer to next selected item (or invalidate it if no more selected items is found)

QProgressBar * progressBar()

Returns progress bar which can be used to provide visualization of progress. Uses common progress bar from PdfEditWindow class. User should keep in mind, that also someone alse can use this progress bar in same time and he should set total steps before each setProgress method.

Chapter 3. Static functions in command line

Table of Contents

void exit(int returnCode=0)
string[] parameters()
string takeParameter()

void exit(int returnCode=0)

Terminate the application. You can specify return code of application in parameter

string[] parameters()

Return list of commandline parameters (excluding any possible switches processed by pdfeditor itself)

string takeParameter()

Return first parameter from list of parameters and remove it from the list. Other parameters are shifted to take the empty space. If there is no parameter to take, NULL is returned

Chapter 4. Callback functions

Table of Contents

onChangeRevision()
onConsoleStart()
onEmptyFile()
onLoad()
onLoadUser()
onLoadError()
onPageChange()
onPageDelete()
onPageRightClick()
onTreeLeftClick()
onTreeRightClick()
onTreeMiddleClick()
onTreeDoubleClick()
onTreeSelectionChange()
onValueChange(name)

These are functions called from editor on certain events. Return value (if any) is ignored. If the callback function does not exist, it is skipped

onChangeRevision()

This function is called after active revision of document is changed

onConsoleStart()

This function is called in commandline mode after calling all scripts specified in commanline parameters - unless some of the scripts exit the application prematurely, for example by calling exit().

onEmptyFile()

This function is called after the editor is opened without specifying any document on commandline (without opening any file) or if the current file is closed.

onLoad()

This function is called after document is opened

onLoadUser()

This function is called after document is opened (after onLoad() is called)

onLoadError()

This function is called after an error occured while trying to load a document

onPageChange()

This function is called after changing to another page in the preview window.

onPageDelete()

This function is called after pressing "delete" key while in preview window

onPageRightClick()

This function is called after clicking with right mouse button in window with page preview.

onTreeLeftClick()

This function is called after clicking with left mouse button on any item in tree window.

onTreeRightClick()

This function is called after clicking with right mouse button on any item in tree window.

onTreeMiddleClick()

This function is called after clicking with middle mouse button on any item in tree window.

onTreeDoubleClick()

This function is called after doubleclicking with left mouse button on any item in tree window.

onTreeSelectionChange()

This function is called after selection in tree changes.

onValueChange(name)

This function is called after some of special tools change its value because of interaction. Parameter is name of the special tool. Color selection tool calls this after user select some color in it, edit tool calls this after user presses enter or leaves the control, number tool calls this after user presses enter or selects some of predefined numbers, select tool calls this after changing the selection.

Chapter 5. Objects exported to scripting

Table of Contents

settings

string settings.read(string key,string default=NULL)
bool settings.readBool(string key,bool default=false)
string settings.readExpand(string key,string default=NULL)
string settings.expand(string)
string settings.write(string key,string value)
string settings.remove(string key)
void settings.flush()

document

settings

This object hold application settings and can be used to read or write them.

string settings.read(string key,string default=NULL)

Returns application setting with given key. The parameter default specify default value returned when the setting does not exist. It can be omitted, in that case NULL will be returned.

bool settings.readBool(string key,bool default=false)

Returns application setting with given key - treating it as boolean value. The parameter default specify default value returned when the setting does not exist. It can be omitted, in that case false will be returned.

string settings.readExpand(string key,string default=NULL)

Returns application setting with given key. Environment variable references are expanded (see expand). The parameter default specify default value returned when the setting does not exist. It can be omitted, in that case NULL will be returned.

string settings.expand(string)

Return string with environment variable references (in form $VARIABLE and ${VARIABLE}) Any character preceded with backslash (especially $ character) is not processed in expansion.

Note

Some internal variables (all of them beginning with $PDFEDIT_) can override corresponding environment variables. This function will use the internal variable in expansion if both internal and environment variables exist.

Table 5.1. List of internal variables

$PDFEDIT_BIN	Full path to directory in which the binary file resides
$PDFEDIT_DATA	Full path to directory with editor data files - usually something like `/usr/share/pdfedit` or `/usr/local/share/pdfedit` unless configured diferently when building editor.

string settings.write(string key,string value)

Write application setting with given key and value

string settings.remove(string key)

Remove key from user settings, effectively restoring the setting to its default value

void settings.flush()

Write all unsaved settings to disk. Unsaved settings are automatically writen to disk on application exit, but this can flush them to disk explicitly.

Document-related objects in scripting

These objects are set to reflect currently edited document

document

This object represents currently edited PDF document. Type of this object is Pdf

Chapter 6. Object types (common and PDF objects)

Table of Contents

Annotation

Dict getDictionary()
Page getPage()
bool remove()
string getType()
string getTypeName()

Array

void add(int index,IProperty ip)
void add(int index,string ip)
void add(int index,int ip)
void add(IProperty ip)
void add(string ip)
void add(int ip)
CObject child(string name)
int count()
void delProperty(int index)
string getText()
CObject property(int index)

CObject

string type()

ContentStream

bool equals(QObject* otherObject)
void deleteOperator(PdfOperator op,bool indicateChange=true)
string getText()
void insertOperator(PdfOperator op,PdfOperator newOp,bool indicateChange=true)
void replace(PdfOperator oldOp,PdfOperator newOp,bool indicateChange=true)
void saveChange()
PdfOperator getFirstOperator()
PdfOperator getLastOperator()
bool isEmpty()

Dict

void add(string name,IProperty ip)
void add(string name,string ip)
void add(string name,int ip)
CObject child(string name)
int count()
void delProperty(string name)
bool exist(string name)
string getText()
CObject property(string name)
CObject propertyDef(string name,int defValue)
CObject propertyDef(string name,string defValue)
string[] propertyNames()

IProperty

bool equals(QObject* otherObject)
Variant value()
string getText()
CObject ref()
int getInt()
string getType()
string getTypeName()
void set(string value)
void set(int value)
void set(double value)
void set(bool value)

IPropertyArray

void append(IProperty prop)
void clear()
int count()
CObject property(int index)

Page

void moveAbove(ContentStream cs)
void moveBelow(ContentStream cs)
void moveAbove(int csi)
void moveBelow(int csi)
void addAnnotation(Annotation an)
void setTransformMatrix(Variant tMatrix)
void prependContentStream(PdfOperatorStack opStack)
void appendContentStream(PdfOperatorStack opStack)
string getFontId(string fontName)
string[] getFontIdsAndNames(bool onlyNames)
void addSystemType1Font(string fontName)
ContentStream getContentStream(int streamNumber)
void removeContentStream(int streamNumber)
int getContentStreamCount()
ContentStream getChange(int changeNumber)
int getChangeCount()
void loadContentStreams()
Dict getDictionary()
string getText()
double[] mediabox();
void setMediabox(double x1,double y1,double x2,double y2)
void setMediabox(Rect rc)

Pdf

string encryption()
bool isLinearized()
bool isValid()
void unloadPdf()
bool saveAs(string name)
bool save(bool newRevision)
Dict getDictionary()
void removePage(int position)
int getPagePosition(Page page)
int getPageCount()
Page insertPage(Page page, int position)
Page getPage(int position)
Page getFirstPage()
Page getLastPage()
Page getNextPage(Page page)
Page getPrevPage(Page page)
bool hasNextPage(Page page)
bool hasPrevPage(Page page)
int getRevisionsCount()
int getActualRevision()

PdfOperator

bool equals(QObject* otherObject)
double[4] getBBox ();
PdfOperator getLastOperator()
bool containsNonStrokingOperator()
bool containsStrokingOperator()
PdfOperatorIterator iterator()
PdfOperatorIterator graphicalIterator(bool forwardDir=true)
PdfOperatorIterator inlineImageIterator(bool forwardDir=true)
PdfOperatorIterator textIterator(bool forwardDir=true)
PdfOperatorIterator changeableIterator(bool forwardDir=true)
PdfOperatorIterator strokingIterator(bool forwardDir=true)
PdfOperatorIterator nonStrokingIterator(bool forwardDir=true)
PdfOperatorIterator fontIterator(bool forwardDir=true)
PdfOperatorStack childs()
int childCount()
string getText()
string getName()
IPropertyArray params()
int paramCount()
void pushBack(PdfOperator op,PdfOperator prev)
void remove()
void setNext(PdfOperator op)
void setPrev(PdfOperator op)
PdfOperator clone()
ContentStream stream()

PdfOperatorIterator

PdfOperator current()
PdfOperatorIterator copy()
PdfOperatorIterator next()
PdfOperatorIterator prev()
ContentStream stream()
bool isEnd()
bool isBegin()
bool valid()

PdfOperatorStack

int count()
void append(PdfOperator prop)
void prepend(PdfOperator prop)
CObject first()
CObject last()
void removeFirst()
void removeLast()
CObject element(int index)

Stream

void setBuffer(ByteArray a)
void setBuffer(string s)
void setRawBuffer(ByteArray a)
void setRawBuffer(string s)
bool loadBuffer(string fileName)
bool loadRawBuffer(string fileName)
string getBufferString()
ByteArray getBuffer()
bool saveBuffer(string fileName)
string getDecoded()

Annotation

Ancestor type: CObject

This type represent one annotation in page

Dict getDictionary()

Returns anotation dictionary

Page getPage()

Returns page in which this annotation is, or NULL, if it is not in any page

bool remove()

Remove this annotation from its page, if it is in a page. Returns true if it was removed.

string getType()

Return type identifier of annotation

string getTypeName()

Return human-readable, localized type identifier of annotation

Array

Ancestor type: IProperty

This type represents an array in PDF document. It hold zero or more values indexed by positive integer, starting from zero. Values can be of any type, either simple types (int, bool, float, string) or complex types (Dict, Array)

void add(int index,IProperty ip)

Insert element at given index in array

void add(int index,string ip)

Insert String element at given index in array

void add(int index,int ip)

Insert Int element at given index in array

void add(IProperty ip)

Append element at end of array

void add(string ip)

Append String element at end of array

void add(int ip)

Append Int element at end of array

CObject child(string name)

Get Dict/Array property recursively Will take the name as slash-separated list of childs to traverse to get to target property, going through Dicts and Arrays. Any references on the way are automatically dereferenced

int count()

Return size of this array (number of elements)

void delProperty(int index)

Delete element with given index from this array. Elements with higher index (if any) are shifted to occupy the space

string getText()

Return string representation of this array

CObject property(int index)

Get element with given index from this array

CObject

Base class for all PDF objects used in scripts

string type()

return name of this object's type

ContentStream

Ancestor type: CObject

This type of object represents content stream in document (in page)

bool equals(QObject* otherObject)

Return true, if this object is equal to specified object (i.e. if they internally point to the same item) Reference is compared, not the value of objects

void deleteOperator(PdfOperator op,bool indicateChange=true)

Delete specified operator from this content stream. If parameter indicateChange is true (which is default), changes are immediately written to underlying stream.

string getText()

Return text representation of this content stream

void insertOperator(PdfOperator op,PdfOperator newOp,bool indicateChange=true)

Insert specified operator newOp in this content stream, after operator op. If parameter indicateChange is true (which is default), changes are immediately written to underlying stream.

void replace(PdfOperator oldOp,PdfOperator newOp,bool indicateChange=true)

Replace old operator oldOp with new operator newOp in this stream. If parameter indicateChange is true (which is default), changes are immediately written to underlying stream.

void saveChange()

Write any unwritten changes to operators to underlying stream.

PdfOperator getFirstOperator()

Return first operator in this contentstream. If not contains any operator, return NULL.

PdfOperator getLastOperator()

Return last operator in this contentstream. If not contains any operator, return NULL.

bool isEmpty()

Check if contentstream contains some operator.

Dict

Ancestor type: IProperty

This type represents a dictionary in PDF document. It hold keys (String) and values. Each key is corresponding to one value. Keys are strings, values can be of any type, either simple types (int, bool, float, string) or complex types (Dict, Array)

void add(string name,IProperty ip)

Add property with given name to this dictionary

void add(string name,string ip)

Add string property with given name to this dictionary

void add(string name,int ip)

Add integer property with given name to this dictionary

CObject child(string name)

int count()

Return number of properties held in this dictionary

void delProperty(string name)

Delete property with given name from this dictionary

bool exist(string name)

Check for existence of property with given name in this dictionary. If it exists, returns true

string getText()

Return string representation of this dictionary

CObject property(string name)

Get property with given name from this dictionary

CObject propertyDef(string name,int defValue)

Get property with given name from this dictionary. If the property does not exist, add it to the dictionary with given defValue (as Int) and return it

CObject propertyDef(string name,string defValue)

Get property with given name from this dictionary. If the property does not exist, add it to the dictionary with given defValue (as String) and return it

string[] propertyNames()

Return array containig names of all properties

IProperty

Ancestor type: CObject

This object represent one property in dictionary or array

bool equals(QObject* otherObject)

Return true, if this object is equal to specified object (i.e. if they internally point to the same item) Reference is compared, not the value of objects

Variant value()

Return value store inside the property, if it is a simple type. For complex types (Array, Dict, Stream), NULL is returned

string getText()

Return text representation of this property

CObject ref()

Return reference to this property, but if the property is a reference, return the reference target. This way you will always get dereferenced property for correct manipulation

int getInt()

Get integer representation of this property's value, return 0 if it cannot be represented as integer

string getType()

Get type identifier of this Property. Can be one of: Null, Bool, Int, Real, String, Name, Ref, Array, Dict, Stream

string getTypeName()

Get human readable and localized name of type of this Property

void set(string value)

Set value of this property. Work only on Bool, Int, Real, String or Name types, automatically converts value if type of property is different than type of parameter Will do nothing if called on different types (Dict, Array, etc ...)

void set(int value)

Overloaded variant of set method

void set(double value)

Overloaded variant of set method

void set(bool value)

Overloaded variant of set method

IPropertyArray

Ancestor type: CObject

This type represents arbitrary array of IProperty items It hold zero or more values indexed by positive integer, starting from zero. Values can be of any type, either simple types (int, bool, float, string) or complex types (Dict, Array)

void append(IProperty prop)

append one IProperty element to end of array.

void clear()

Delete all elements in the array

int count()

Return size of this array (number of elements)

CObject property(int index)

Get IProperty element with given index from this array

Page

Ancestor type: CObject

This type of object represents one page in document.

void moveAbove(ContentStream cs)

Move specified content stream in this page one level up in painting order.

void moveBelow(ContentStream cs)

Move specified content stream in this page one level down in painting order.

void moveAbove(int csi)

Move content stream with specified index in this page one level up in painting order.

void moveBelow(int csi)

Move content stream with specified index in this page one level down in painting order.

void addAnnotation(Annotation an)

Add copy of given annotation to this page

void setTransformMatrix(Variant tMatrix)

Set transform matrix of this page. Expects array with 6 real numbers as the matrix.

void prependContentStream(PdfOperatorStack opStack)

Add new content stream to page, created from provided stack of PDF operators. They must form a valid content stream Content stream is prepended before other content streams

void appendContentStream(PdfOperatorStack opStack)

Add new content stream to page, created from provided stack of PDF operators. They must form a valid content stream Content stream in appended after other content streams

string getFontId(string fontName)

For given font name (case sensitive) return it's ID if present on page. If the font is not present, returns NULL

string[] getFontIdsAndNames(bool onlyNames)

Return list of all font id's and base names from resource dictionary of a page. For each font id and name pair there are two consecutive elements in returned array, first one containing font id and second one containing the name, so number of elements in output array is always even. If parametr onlyNames is true, id's are ommited and only list of names is returned instead.

void addSystemType1Font(string fontName)

Add new Type 1 font to this page resource dictionary with specified font name It is supposed that you insert standard system font name that should be avaiable to all PDF viewers.

ContentStream getContentStream(int streamNumber)

Returns content stream with given number from this page Use data fetched by loadContentStreams method, if it wasn't called, it is called before returning the stream

void removeContentStream(int streamNumber)

Removes content stream with given number from page.

int getContentStreamCount()

Returns number of content streams in this page Use data fetched by loadContentStreams method, if it wasn't called, it is called before returning the count

ContentStream getChange(int changeNumber)

Return change with given number as content stream

int getChangeCount()

Return number of changes

void loadContentStreams()

Get all content streams from page and store them. Get the streams with getContentStreamCount and getContentStream functions. Usually it is not necessary to call this method, as these funtions will call it automatically on first need, but you may call it explicitly to reload the streams stored in this object from the page

Dict getDictionary()

Returns page dictionary

string getText()

Return text representation of this page

double[] mediabox();

Return media box of this page as array (x1,y1,x2,y2). The mediabox is a rectangle from (x1,y1) to (x2,y2)

void setMediabox(double x1,double y1,double x2,double y2)

Set media box of this page to given rectangle - from (x1,y1) to (x2,y2)

void setMediabox(Rect rc)

Set media box of this page to given rectangle

Pdf

Ancestor type: CObject

This type of object represents entire document. Note to page manipulation - page numbers start from number 1 (not from zero as some programmers may expect), number of last page is equal to count of pages.

string encryption()

Return name of filter used to encrypt the document, or NULL if document is not encrypted

bool isLinearized()

Return true, if document is linearized PDF, false otherwise

bool isValid()

Check for PDF validity - return true, if this object is valid PDF document, false if the PDF document was closed or not yet opened (so the object is invalid)

void unloadPdf()

Close the document. If the document was opened directly in editor window (with openFile function), it won't be closed, you must use closeFile() function for this. However, all documents loaded with loadPdf function should be closed using this function.

bool saveAs(string name)

Save this document under different name. Does not modify name of file in editor, original file is still edited, not this one. Does not check for file existence - it will overwrite the file without warning if it already exists Return true if document was saved, false if it failed to save for any reason

bool save(bool newRevision)

Save document to disk under original name If newRevision is true, create new revision while saving. Return true if saved successfully, false if failed to save because of any reason

Dict getDictionary()

Get document dictionary (object catalog)

void removePage(int position)

Remove page with given number from document.

int getPagePosition(Page page)

Get position of given page in document or -1 in case of error (page not in document, invalid page, etc...)

int getPageCount()

Get number of pages in document

Page insertPage(Page page, int position)

Insert given page in document, at given position. Return inserted page.

Page getPage(int position)

Return page from document, given its page number.

Page getFirstPage()

Return first page in document.

Page getLastPage()

Return last page in document.

Page getNextPage(Page page)

Return next page in document, relative to specified page.

Page getPrevPage(Page page)

Return previous page in document, relative to specified page.

bool hasNextPage(Page page)

Return true, if there is next page in document for given page.

bool hasPrevPage(Page page)

Return true, if there is previous page in document for given page.

int getRevisionsCount()

Return number of available revisions in document

int getActualRevision()

Return number of currently active revisions

PdfOperator

Ancestor type: CObject

This type of object represents pdf operator in content stream

bool equals(QObject* otherObject)

Return true, if this object is equal to specified object (i.e. if they internally point to the same item) Reference is compared, not the value of objects

double[4] getBBox ();

Return bounding box (rectangle) of this PDF operator

PdfOperator getLastOperator()

Return last operator if a this operator is a composite

bool containsNonStrokingOperator()

Tries to find first non stroking operator. (some operators are modified by stroking operators, some by nonestroking) Return true if non stroking operator found, false otherwise.

bool containsStrokingOperator()

Tries to find first stroking operator. (some operators are modified by stroking operators, some by nonestroking) Return true if stroking operator found, false otherwise.

PdfOperatorIterator iterator()

Return PDF Operator iterator, initially pointing at this operator

PdfOperatorIterator graphicalIterator(bool forwardDir=true)

Return PDF Graphical Operator iterator, initialialized from this operator Graphical iterator iterate only through Graphical operators in content stream

PdfOperatorIterator inlineImageIterator(bool forwardDir=true)

Return PDF Inline Image Operator iterator, initialialized from this operator Inline Image iterator iterate only through inline image operators in content stream

PdfOperatorIterator textIterator(bool forwardDir=true)

Return PDF Text Operator iterator, initialialized from this operator Text iterator iterate only through text operators in content stream

PdfOperatorIterator changeableIterator(bool forwardDir=true)

Return PDF Changeable Operator iterator, initialialized from this operator Font iterator iterate only through changeable operators in content stream

PdfOperatorIterator strokingIterator(bool forwardDir=true)

Return PDF Stroking Operator iterator, initialialized from this operator Font iterator iterate only through stroking operators in content stream

PdfOperatorIterator nonStrokingIterator(bool forwardDir=true)

Return PDF Non stroking Operator iterator, initialialized from this operator Font iterator iterate only through non-stroking operators in content stream

PdfOperatorIterator fontIterator(bool forwardDir=true)

Return PDF Font Operator iterator, initialialized from this operator Font iterator iterate only through font operators in content stream

PdfOperatorStack childs()

Returns stack with all child operators

int childCount()

Returns number of child operators under this pdf operator

string getText()

Return text representation of this pdf operator

string getName()

Return name of this pdf operator

IPropertyArray params()

Returns parameters of this operator in array

int paramCount()

Returns number of parameters in this pdf operator

void pushBack(PdfOperator op,PdfOperator prev)

Add an operator oper to the end of composite operator prev The operator will be added after operator prev. Second parameter is optional and will default to null operator if not specified

void remove()

Remove this PDF operator from its ContentStream. After calling this function, this object became invalid and must not be used further, doing so may result in an exception

void setNext(PdfOperator op)

Set next operator

void setPrev(PdfOperator op)

Set previous operator

PdfOperator clone()

Clone this object

ContentStream stream()

Return content stream in which this operator is contained May return NULL if the stream is not known or if this operator is not contained in any content stream

PdfOperatorIterator

Ancestor type: CObject

This type of object represents pdf operator in content stream

PdfOperator current()

Returns current operator from this iterator, or NULL if the iterator is at invalid position (after end, before beginning)

PdfOperatorIterator copy()

Create and return copy of this iterator, initially pointing to the same item

PdfOperatorIterator next()

Move the iterator to next operator. Return reference to itself, or NULL, if we are after last valid item

PdfOperatorIterator prev()

Move the iterator to previous operator Return reference to itself, or NULL, if we are before first valid item

ContentStream stream()

Return content stream in which the initial operator used to construct the iterator was contained. May return NULL, if operator is not contained in any content stream or if content stream is not known at time of creation

bool isEnd()

Return true, if we are at the end of the operator list (this means after last valid item, so calling current() will return NULL )

bool isBegin()

Return true, if we are at the beginning of the operator list (this means before first valid item, so calling current() will return NULL )

bool valid()

Return true, if current position is valid (not before beginning or after end of list) (calling current() will return valid item, not NULL)

PdfOperatorStack

Ancestor type: CObject

This type represents arbitrary array of PDFOperator items It hold zero or more values indexed by positive integer, starting from zero. You can add pdf operators to beginning or end of the array, so the array can behave like double-ended stack

int count()

Return size of the stack (number of operators)

void append(PdfOperator prop)

append one PdfOperator element to end of stack.

void prepend(PdfOperator prop)

prepend one PdfOperator element at beginning of stack.

CObject first()

Return first element in stack (from beginning of stack)

CObject last()

Return last element in stack (from end of stack)

void removeFirst()

Remove first element from stack (from beginning of stack)

void removeLast()

Remove last element from stack (from end of stack)

CObject element(int index)

Get PdfOperator element with given index from stack

Stream

Ancestor type: IProperty

This type of object represents stream in document (in page)

void setBuffer(ByteArray a)

Sets buffer of this stream from given byte array

void setBuffer(string s)

Sets buffer of this stream from given string (overloaded method)

void setRawBuffer(ByteArray a)

Sets raw buffer of this stream from given byte array

void setRawBuffer(string s)

Sets raw buffer of this stream from given string (overloaded method)

bool loadBuffer(string fileName)

Loads buffer of this stream from given file. Return true on success, false on failure while loading

bool loadRawBuffer(string fileName)

Loads raw buffer of this stream from given file. Return true on success, false on failure while loading

string getBufferString()

Gets buffer of this stream as string

ByteArray getBuffer()

Gets buffer of this stream

bool saveBuffer(string fileName)

Saves buffer of this stream to given file. Return true on success, false on failure while saving

string getDecoded()

Return decoded text representation of this property

Chapter 7. Object types (GUI objects)

These object types do not have direct corespondence to any object inside PDF document, but some of them may allow you to manipulate them indirectly. Main focus of these types is to interact with user.

TreeItem

Ancestor type: CObject

This type of object represents one item in treeview. One item in tree usually corespond to one object in PDF document

void setSelected(bool selected=true)

Select or unselect this item (true to select, false to unselect)

bool selected()

Check if this item is selected Return true if the item is selected, false if not

bool valid()

Check if the tree item wrapper is valid, i.e. if corresponding tree item still exist in the tree view. Using most of invalid wrapper's functions will result in exception Return true if valid, false if not

void setOpen(bool opened)

Set the item to be opened or closed. Specify true if the item is to be opened, false if closed.

CObject item()

Get object contained in this tree item

CObject itemref()

Get object inside this tree item, as item() does, but with one exception: If the object is reference, return reference target instead of the reference

string itemtype()

Get type of object contained in this tree item (shortcut for .item().type())

TreeItem child(string name)

Return child of this tree item with given name, or NULL if this item have no child with such name

string[] getChildNames()

Get names of all visible childs items of this treeitem Childs that are not shown in tree (because of treeview settings, etc ...) are not returned. Childs that are "not yet known" (unopened references) are not returned too.

TreeItem parent()

Return parent of this tree item, or NULL if this item have no parent

string id()

Return name of this tree item

string text()

Return caption of this tree item (sometimes can differ from name)

string path()

Return path of this tree item (sequence of names from root item to this item, separated by slashes: "/" )

void reload()

Explicitly reload contents of this item and its subtree from current state of PDF document

void remove()

Remove object in this tree item (and also any possible subitems) from document

TreeItemContentStream

Ancestor type: TreeItem

This type of object represents one item in treeview representing content stream.

void setMode(string newMode)

Set mode of this tree item, i.e. what operators to show as children. Can be:

all	Show all operators
text	Show only text operators
font	Show only font operators
graphic	Show only graphic operators

string getMode()

Get mode of this tree item, i.e. what operators to show as children. See setMode for list of modes it can return.

Chapter 8. QSA Utility Framework

Table of Contents

File Class Reference

Enums
Static Functions
Constructor
Properties
Member Functions

Dir Class Reference

Enums
Static Properties
Static Functions
Constructor
Properties
Member Functions

Process Class Reference

Static Properties
Static Functions
Constructor
Properties
Member Functions

The QSA Utility Framework is a set of classes that extends QSA to enable the user to read and write files, access directory structures and start processes synchronously and asynchronously.

File Class Reference

The File class provides functionallity for reading and writing binary and text files. A File can be instantiated as an object, giving the scripter complete flexibility when reading and writing files. In addition, the File class provides a set of static convenence functions for reading and writing files in one go. Typical use of a File is:

// Reads an entire file in one go
var log = File.read('file.log');
// Writes an entire file in one go
File.write('copy_of_file.log', log);

// Read and write a file line by line
var infile = new File('file.log');
infile.open(File.ReadOnly);

var outfile = new File('copy_of_file.log');
outfile.open(File.WriteOnly);

while (!infile.eof) {
    var line = infile.readLine();
    outfile.write( line );
}

infile.close();
outfile.close();

Enums

AccessMode

The enum AccessMode is used in conjunction with File.open to specify the mode in which the file is opened.

ReadOnly; Opens the file in read-only mode.
WriteOnly; Opens the file in write-only mode. If this flag is used with Append, the file is not truncated; but if used on its own (or with Truncate), the file is truncated.
ReadWrite; Opens the file in read/write mode. The file is not truncated.
Append; Opens the file in append mode. (You must actually use (WriteOnly | Append) to make the file writable and to go into append mode.) This mode is very useful when you want to write something to a log file. The file index is set to the end of the file. Note that the result is undefined if you position the file index manually using at() in append mode.
Truncate; Truncates the file.
Translate; Enables carriage returns and linefeed translation for text files under Windows.

Static Functions

exists( fileName : String ) : Boolean; Returns true if fileName exists; otherwise returns false.
remove( fileName : String ); Deletes the file fileName if possible; otherwise throws an exception.
write( fileName : String, content : String ); Writes the string content to the file fileName if possible (completely replacing the original contents if the file already exists); otherwise throws an exception.
read( fileName : String ) : String; Reads and returns the contents of the file fileName if possible; otherwise throws an exception.
isFile( fileName : String ) : Boolean; Returns true if fileName is a file; otherwise returns false.
isDir( fileName : String ) : Boolean; Returns true if fileName is a directory; otherwise returns false.

Constructor

File( fileName : String ); Creates a file object with the with fileName. If fileName is missing or is not a String, an exception is thrown.

Properties

The File object's properties are read-only.

name : String; The name of the file including the extension.
path : String; The path of the file.
fullName : String; The fullName of the file, including path, name, and extension.
baseName : String; The name of the file, excluding its path and extension.
extension : String; The file name's extension.
symLink : String; The expansion of the symlink if the file is a symlink; otherwise empty;
exists : Boolean; True if the file exists; otherwise false.
readable : Boolean; True if the file is readable; otherwise false.
writable : Boolean; True if the file is writable; otherwise false.
executable : Boolean; True if the file is executable; otherwise false.
hidden : Boolean; True if the file is hidden; otherwise false.
eof : Boolean; True if reading has reached the end of the file; otherwise false.
created : Date; The creation time of the file.
lastModified : Date; The last modification time of the file.
lastRead : Date; The last time the file was read.
size : Number; The size of the file, in bytes.

Member Functions

open( accessMode : Number ); Opens the file in the mode accessMode if possible; otherwise throws an exception.
close(); Closes the file.
remove((); Deletes the file if possible; otherwise throws an exception.
readByte() : Number; Reads one byte from the file if possible; otherwise throws an exception.
read() : String; Returns the entire content of the file as a string if it can be read; otherwise throws an exception.
readLine() : String; Reads one line from file if possible; otherwise throws an exception. Retains any trailing whitespace.
readLines() : String[]; Returns the contents of the file as an array of Strings, one for each line. Linebreaks are strippped from the strings. If the file could not be read, an exception is thrown.
writeByte( byte : Number ); Writes a byte to the file is possible; otherwise throws an exception.
write( data : String, length : Number ); Writes length number of characters from data to the file if possible; otherwise throws an exception.
writeLine( data : String ); Writes the line data to the file and adds a linebreak. If the file could not be written error is returned.

Dir Class Reference

The Dir class provides access to directory structures and their contents in a platform-independent way. It provides a means of listing directory content, creating filenames with proper path separators, etc. An example use of the Dir class is:

var dir = new Dir;
var codeFiles = dir.entryList('*.cpp');
for (var i = 0; i < codeFiles.length; ++i) 
    print(codeFiles[i]);

Enums

FilterSpec

This enum describes the filtering options available to Dir for entryList(). The filter value is specified by OR-ing together values from the following list.

Dirs; List directories only.
Files; List files only.
Drives; List disk drives only.
NoSymLinks; Do not list symbolic links (ignored by operating systems that don't support symbolic links).
All; List directories, files, drives and symlinks (this does not list broken symlinks unless you specify System).
TypeMask; A mask for the the Dirs, Files, Drives and NoSymLinks flags.
Readable; List files for which the application has read access.
Writable; List files for which the application has write access.
Executable; List files for which the application has execute access. Executables must be combined with Dirs or Files.
RWEMask; A mask for the Readable, Writable and Executable flags.
Modified; Only list files that have been modified (ignored under Unix).
Hidden; List hidden files (on Unix, files starting with a .).
System; List system files (on Unix, FIFOs, sockets, and device files)
AccessMask; A mask for the Readable, Writable, Executable Modified, Hidden and System flags

SortSpec

This enum describes the sort options available to Dir for entryList(). The sort value is specified by OR-ing together values from the following list:

Name; Sort by name.
Time; Sort by time (modification time).
Size; Sort by file size.
Unsorted; Do not sort.
SortByMask; A Mask for Name, Time and Size.
DirsFirst; Put the directories first, then the files.
Reversed; Reverse the sort order.
IgnoreCase; Sort case-insensitively.

Static Properties

current : String; The current directory.
home : String; The home directory.
root : String; The root directory.
drives : String[]; An array of strings containing the drive names (c:, d:, etc); empty on Unix.

Static Functions

Qt uses "/" as a directory separator throughout (although it understands the conventions of the platform it is used on). If you are working with paths, use "/" within your code, and use convertSeparators() when you want to display a path to the user.

cleanDirPath( filePath : String ) : String; Removes all multiple directory separators "/" and resolves any "."s or ".."s found in the path, filePath.
convertSeparators( pathName : String ) : String; Returns pathName with the "/" separators converted to separators that are appropriate for the underlying operating system.

Constructor

Dir( path : String ); Creates a directory object for path path. If path is empty, the current directory is used.

Properties

name : String; Contains the name of the directory; this is not the same as the path, e.g. a directory with the name "mail", might have the path "/var/spool/mail"
path : String; Contains the path, this may contain symbolic links, but never contains redundant ".", "..", or multiple separators.
absPath : String; Contains the absolute path (a path that starts with "/" or with a drive specification), which may contain symbolic links, but never contains redundant ".", "..", or multiple separators.
canonicalPath : String; Contains the canonical path, i.e. a path without symbolic links or redundant "." or ".." elements.
readable : Boolean; True if the directory is readable; otherwise false.
exists : Boolean; True if the directory exists; otherwise false.

Member Functions

filePath( fileName : String ) : String; Returns the path name of the file fileName in the directory.
absFilePath( fileName : String ) : String; Returns the absolute path name of the file fileName in the directory.
cd( dirName : String ); Changes the Dir's directory to dirName if possible; otherwise throws an exception.
cdUp(); Changes directory by moving one directory up from the Dir's current directory if possible; otherwise throws an exception.
entryList( filter : String, filterSpec : Number, sortSpec : Number ) : String[]; Returns a list of the names of all the files and directories in the directory, ordered in accordance with sortSpec and filtered in accordance with filterSpec.
mkdir( dirName : String ); Creates the directory dirName if possible; otherwise throws an exception.
mkdir(); Creates this directory if possible possible; otherwise throws an exception.
mkdirs( dirName : String ); Creates the directory tree dirName if possible; otherwise throws an exception.
mkdirs(); Creates this directory tree if possible; otherwise throws an exception.
rmdir( dirName : String ); Deletes the directory dirName if possible; otherwise throws an exception.
rmdir(); Deletes this directory if possible; otherwise throws an exception.
rmdirs( dirName : String ); Deletes the directory structure dirName if possible; otherwise throws an exception.
rmdirs(); Deletes this directory structure if possible; otherwise throws an exception.
fileExists( fileName : String ) : Boolean; Returns true if the file fileName exists; otherwise returns false.
setCurrent(); Sets the application's current working directory to this directory if possible; otherwise throws an exception.

Process Class Reference

The Process class is used to start external programs and to communicate with them. The Process class can start programs synchronously using Process.execute(), and asynchronously using {new Process(...).start()}.

Static Properties

stdout : String; Contains the data sent to stdout during the last call to Process.execute(). This property is read-only.
stderr : String; Contains the data sent to stderr during the last call to Process.execute(). This property is read-only.

Static Functions

execute( command : String, stdin : String ); Executes command synchronously and passes stdin to its standard input if specified. When the program ends its output is accessible through Process.stdout and Process.stderr. command can contain both the program and command line arguments, e.g. "ls -la" . The function returns the executed commands return code on exit.
execute( command : String[], stdin : String ); Same as above, except that command is an array of strings, where the first item is the name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you. Note that if the user passes an array of only one element this function behaves like the overload taking a string, thus splitting it into "command" and "arguments". \ executeNoSplit( command : String[], stdin : String ); Same as above, except that command is an array of strings, where the first item is the name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you. This function never splits the first argument, regardless of the number of strings in the command array.

Constructor

Process(); Creates a Process object without specifying the program or any arguments. This does not start a process.
Process( command : String ); Creates a Process object that will execute command. This does not start the process.
Process( command : String[] ); Same as above, except that command is an array of strings, where the first item is the name of the program and the following items are command line arguments. This version is useful if you have arguments that contain spaces or other characters that would need to be quoted if you just passed a single string command line, since it takes care of the quoting for you.

Properties

arguments : String[]; Contains an array of strings where the first item is the program to execute and the following items are the command line arguments.
workingDirectory : String; Contains the working directory for the process.
running : Boolean; True if the process is currently running; otherwise false. This property is read-only.
exitStatus : Number; Contains the exitStatus of the program when it has finished. This property is read-only.

Member Functions

start( env : String[] ); Tries to run a process for the command and arguments that were specified with the argument property or that were specified in the constructor. The command is searched for in the path for executable programs; you can also use an absolute path in the command itself. If env is not specified, the process is started with the same environment as the starting process. If env is specified, then the values in the env stringlist are interpreted as environment setttings of the form VARIABLE=VALUE and the process is started with these environment settings. If the program could not be started, an exception is thrown.
launch( stdin : String, env : String[] ); Runs the process and writes the data stdin to the process's standard input. If all the data is written to standard input, standard input is closed. The command is searched for in the path for executable programs; you can also use an absolute path in the command itself. If env is unspecified, the process is started with the same environment as the starting process. If env is specified, then the values in the string list are interpreted as environment setttings of the form VARIABLE=VALUE and the process is started with these environment settings. If the program could not be started, an exception is thrown.
readStdout() : String; Reads what is currently available on the process's standard output.
readSterr() : String; Reads what is currently available on the process's standard error.
canReadLineStdout() : Boolean; Returns true if a line can be read from the process's standard output.
canReadLineStderr() : Boolean; Returns true if a line can be read from the process's standard error.
readLineStdout() : String; Reads one line of text from the process's standard output if available; otherwise returns an empty string.
readLineStderr() : String; Reads one line of text from the process's standard error if available; otherwise returns an empty string.
tryTerminate(); Asks the process to terminate. Processes can ignore this if they wish. If you want to be certain that the process really terminates, you can use kill() instead.
kill(); Terminates the process. This is not a safe way to end a process since the process will not be able to do any cleanup. tryTerminate() is safer, but processes can ignore tryTerminate().
writeToStdin( buffer : String ); Writes the data buffer to the process's standard input. The process may or may not read this data.
closeStdin(); Closes the process's standard input.

Chapter 9. QSA Input Dialog Framework

The QSA Input Dialog Framework is a set of classes to enable the user to create dialogs using Qt Script. The QSA Input Dialog Framework provides two types of classes. The first types are the ones that can be used to build up complex input dialogs. These classes include, Dialog, CheckBox, GroupBox, LineEdit, TextEdit, etc. These classes each have a set of properties for describing how they appear and some of them also provide functions. The following is a simple example on how to use the Input Dialog Framework to create a dialog that will query the user for their first and last name, and echo the values they entered:

var dialog = new Dialog;
dialog.caption = "Name reading dialog";
dialog.okButtonText = "Done"
dialog.cancelButtonText = "Abort";

var first = new LineEdit;
first.label = "First name: ";
dialog.add( first );

var last = new LineEdit;
last.label = "Last name: ";
dialog.add( last );

if( dialog.exec() ) {
    var fullName = last.text + ", " + first.text;
    print( "Full name is: " + fullName );
}

Below is a list of the classes available from the Input Dialog Framework. Each class has a short description and a list of its properties and functions. For String properties the default is an empty string, and for Number properties the default is 0, unless stated otherwise.

CheckBox

The CheckBox widget provides a checkbox with a text label. CheckBox is an option button; it can be switched on (checked) or off (unchecked).

Properties

checked : Boolean; This property holds whether the checkbox is checked. The default is unchecked, i.e. false.
text : String; This property holds the text shown on the button.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

ComboBox

The ComboBox widget is a combined button and drop-down list. A combobox is a selection widget which displays the current item and can drop down a list of items. A combobox may be editable in which case the user can enter arbitrary strings.

Properties

currentItem : String; This property is used in two ways: To specify the default selected item in the combobox; and to get the value the user selected in the combobox when the dialog is closed. The default is the first item in the list.
editable : Boolean; This property holds whether the combobox is editable. The default is false.
itemList : Array; The list of items in the combobox.
label : String; The label for the combobox.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

DateEdit

The DateEdit class provides a date editor. DateEdit allows the user to edit dates by using the keyboard or the arrow keys to increase/decrease date values. The arrow keys can be used to move from section to section within the DateEdit box. Dates appear in accordance with the local date/time settings or in year, month, day order if the system doesn't provide a local date order.

Properties

date : Date; This property holds the editor's date value. The default is today.
label : String; The label for the date.
maximum : Date; This property holds the editor's maximum value. The default maximum date is 8000-12-31.
minimum : Date; This property holds the editor's minimum value. The default minimum date is 1752-09-14.
order : Order; This property holds the order in which the year, month and day appear. The default order is locale dependent.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

Dialog

The Dialog class is the base class of dialog windows. A dialog window is a top-level window mostly used for short-term tasks and brief communications with the user. Dialogs may be modal or modeless.

Properties

caption : String; This property holds the window caption (title). The default is the application's name.
cancelButtonText : String; This property holds the text shown on the cancel button. The default is "Cancel".
okButtonText: String; This property holds the text shown on the ok button. The default is "Ok".
width : Number; This property holds the width of the widget excluding any window frame. The default is set by the layout.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

Functions

add( widget : QSWidget ); Adds a widget to the dialog. Widgets are placed vertically, from top to bottom.
addSpace( space : Number ); Adds vertical space, measured in pixels between, the previous and next added widget.
exec() : Boolean; Executes the dialog. This opens the dialog as a modal dialog, blocking the application until the user presses the OK button or the Cancel button to close the dialog. The function returns true of the user pressed OK; otherwise it returns false.
newColumn(); Creates a new column in the dialog. All widgets subsequently added to the dialog will be placed (vertically, from top to bottom), in the new column.
newTab( label : String ); Creates a new tab in the dialog with the given label. All widgets subsequently added to the dialog will be placed in the newly created tab, (vertically, from top to bottom).

GroupBox

The GroupBox widget provides a group box frame with a title and can displays other widgets inside itself.

Properties

title : String; This property holds the group box's title text.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

Functions

add( widget : QSWidget ); Adds a widget to this groupbox.
addSpace( space : Number ); Adds vertical space, measured in pixels, between the previous and the next widget that is added.
newColumn(); Creates a new column within this groupbox. All widgets that are added subsequently will be placed in the new column.
addSpace()

LineEdit

The QLineEdit widget is a single-line text editor.

Properties

label : String; The label text for this line edit.
text : String; This property holds the line edit's text.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

NumberEdit

The NumberEdit class provides range checking of floating-point numbers. NumberEdit provides an upper bound, a lower bound and a limit on the number of digits after the decimal point.

Properties

decimals : Number; This property holds the number edits's maximum number of digits after the decimal point.
label : String; The label text for this number edit.
maximum : Number; This property holds the number edit's maximum acceptable value. The default is 2,147,483,647.
minimum : Number; This property holds the number edit's minimum acceptable value. The default is -2,147,483,647.
value : Number; This property holds the number edit's input value. The default is 0.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

RadioButton

The RadioButton widget provides a radio button with a text label. RadioButton is an option button; it can be switched on (checked) or off (unchecked). Sets of Radio buttons grouped together (for example in a GroupBox), are mutually exclusive.

Properties

checked : Boolean; This property holds whether the radio button is checked. The default is unchecked (false).
text : String; This property holds the text shown on the button.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

SpinBox

The SpinBox class provides a spin box widget (spin button). SpinBox allows the user to choose an integer value either by clicking the up/down buttons to increase/decrease the value currently displayed or by typing the value directly into the spin box. If the value is entered directly into the spin box, Enter (or Return) must be pressed to apply the new value.

Properties

label : String; This property holds the spinbox's label text.
maximum : Number; This property holds the maximum value of the spin box. The default maximum value is 2,147,483,647.
minimum : Number; This property holds the minimum value of the spin box. The default minimum value is -2,147,483,648.
value : Number; This property holds the value of the spin box.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

TextEdit

The QTextEdit widget provides a multi-line text editor.

Properties

text : String; This property holds the text of the TextEdit.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

TimeEdit

The TimeEdit class provides a time editor. TimeEdit allows the user to edit times by using the keyboard or the arrow keys to increase/decrease time values. The arrow keys can be used to move from section to section within the TimeEdit box.

Properties

label : String; This property holds the time edit's label text.
maximum : Time; This property holds the maximum time value.
minimum : Time; This property holds the minimum time value.
showAMPM : Boolean; If this property is false (the default), the time edit uses the 24 hour clock; otherwise the time edit uses the 12 hour clock and displays AM or PM as appropriate.
showSeconds : Boolean; If this property is true (the default), the time edit displays seconds; otherwise it does not display seconds.
time : Time; This property holds the editor's time value.
tooltip : String; This property holds the tool tip (balloon help) for the widget.
whatsThis : String; This property holds a simple description of the widget.

Convenience Classes

The convenience classes provide static functions to obtain a value from the user without using any complex widget hierarchies. Because the functions are static they can be called directly without the need to create an instance of the class. For example, to get a filename all that is necessary is to call FileDialog.getOpenFileName().

The MessageBox class

This class provides a simple way of popping up a message box window for the user. The following lines of code present a pop up messagebox with a warning and query the user to click Yes or No.

var ans = MessageBox.warning( "Do you wish to save the data?", MessageBox.Yes, MessageBox.No );
if (ans == MessageBox.Yes) {
    save();
}

Button types

The button types are used to describe what the text of the buttons should be. The following are available.

NoButton; No button is displayed.
Ok; Displays an 'OK' button.
Cancel; Displays a 'Cancel' button.
Yes; Displays a 'Yes' button.
No; Displays a 'No' button.
Abort; Displays an 'Abort' button.
Retry; Displays a 'Retry' button.
Ignore; Displays an 'Ignore' button.

Functions

The following is a list of message box functions. The button1, button2 and button3 parameters can be any of the Button types described above and specify which button types will be shown in the message box. Each function returns the button type that the user pressed.

information( label : String, button1 : ButtonType, button2 : ButtonType, button3 : ButtonType, title : String ); Displays an information message box with the content specified in label.
warning( label : String, button1 : ButtonType, button2 : ButtonType, button3 : ButtonType, title : String ); Displays a warning message box with the content specified in label.
critical( label : String, button1 : ButtonType, button2 : ButtonType, button3 : ButtonType, title : String ) Displays a critical error message box with the content specified in label.

The FileDialog class

This class provides dialogs that allow users to select files or directories. The following function call will open a file dialog with that will display files with the extension .txt.

var filename = FileDialog.getOpenFileName( "*.txt" );
if (filename) {
    processfile(filename);
}

Functions

getOpenFileName( filter : String, title : String ); Opens an "Open" dialog. If filter is specified (e.g. "textfiles (*.txt)"), only those files which match the filter are shown. The function returns a string with the selected filename, or undefined if the user canceled.
getSaveFileName( filter : String, title : String ); Opens an "Save As" dialog. If filter is specified (e.g. "textfiles (*.txt)"), only those files which match the filter are shown. The function returns a string with the filename selected or entered, or undefined if the user canceled.
getExistingDirectory( dir : String, title : String ); Opens a "Find Directory" dialog for the user to select an existing directory. The parameter dir can be used to specify the initial directory. Returns the name of the selected directory or undefined if the user canceled.
getOpenFileNames( dir : String, filter : String, title : String ); Opens an "Open" dialog for the user to select and open one or more existing files. If dir is specified it specifies the initial directory. If filter is specified (e.g. "textfiles (*.txt)"), only those files which match the filter are shown. The function returns a list of string string with the selected filenames, or undefined if the user canceled.

The Input class

This class provides convenience functions for getting simple input from the user. The following code can be used to open a dialog that queries the user for a text:

var name = Input.getText( "What is your surname? " );
if (name) {
    processname(name);
}

Functions

getText( label : String, text : String, title : String ); Asks the user for a text. label specifies the descriptive label and text specifies the default text. The function returns the text entred by the user or undefined if the user canceled.
getNumber( label : String, value : Number, decimals : Number, minValue : Number, maxValue : Number, title : String ); Asks the user for a number. label specifies the descriptive label, value specifies the default value, decimals specifies the number of decimals allowed, minValue specifies the minimum value and maxValue specifies the maximum value. The function returns the value entered by the user or undefined if the user canceled.
getItem( label : String, itemList : Array, current : String, editable : Boolean, title : String ); Asks the user to select an item from a predefined list of values specified by itemList. The descriptive label is specified with label. current specifies the value that is selected when the dialog starts. If editable is true, the user is allowed to enter a value that is not in the itemList. The function returns the value selected or entered by the user or undefined if the user canceled.