Lucide Plugin API

A bird's eye view of how a plugin is constructed may be seen in plugins/ludoc/ludoc.idl.

Available methods

NB: All page numbers are zero-based.

loadFile()

Description:

Loads the specified file.

Parameters:

filename	filename of the file to load
password	password if necessary, or NULL
errorCode	return location for an error code, or NULL
error	return location for an error, or NULL

Return value:

TRUE if file has loaded, FALSE otherwise.

Default return value:

FALSE

Note:

Error string is allocated using SOMMalloc(), use SOMFree() to free.

Syntax:

loadFile( in string filename, in string password, out long errorCode, inout string error );

getBpp()

Description:

Get the number of bytes per pixel used for drawing.

Return value:

Number of bytes per pixel used for drawing. Allowed values are 3 (24 bit) or 4 (32 bit). 4 bytes per pixel is the same as 3, but padded with a dummy byte.

Default return value:

0

Type:

short

Syntax:

getBpp();

isScalable()

Description:

See: renderPageToPixbuf(), scale.

Return value:

TRUE if document is scalable, FALSE otherwise.

Default return value:

FALSE

Type:

boolean

Syntax:

isScalable();

isFixedImage()

Description:

Determines if upscaling improves image quality. Must return TRUE for fixed-size images/bitmaps. Must return FALSE for documents which render fonts/vector images, to indicate that upscaling improves the quality of the rendered image. Used to determine better printing parameters.

Return value:

TRUE if document is fixed-size, FALSE otherwise.

Default return value:

TRUE

Type:

boolean

Syntax:

isFixedImage();

isRotable()

Description:

See: renderPageToPixbuf(), rotation.

Return value:

TRUE if document can be rotated, FALSE otherwise.

Default return value:

FALSE

Type:

boolean

Syntax:

isRotable();

getPageCount()

Description:

Returns the number of pages in the loaded document.

Return value:

Number of pages.

Default return value:

0

Type:

long

Syntax:

getPageCount();

getPageSize()

Description:

Gets the size of the specified page.

Parameters:

pagenum	page number
width	return the width of the page (NULL if width is not needed)
height	return the height of the page (NULL if height is not needed)

Type:

void

Syntax:

getPageSize( in long pagenum, inout double width, inout double height );

renderPageToPixbuf()

Description:

First, scale the document to match the specified pixels per point, then render the rectangle given by the upper left corner at (src_x, src_y) and src_width by src_height.

Parameters:

pagenum	the page from which we are to render
src_x	x coordinate of upper left corner
src_y	y coordinate of upper left corner
src_width	width of rectangle to render
src_height	height of rectangle to render
scale	scale specified as pixels per point (if isScalable() is FALSE, scale is ignored and assumed to be 1.0)
rotation	rotate the document by the specified degree (allowed values are 0, 90, 180, 270) (if isRotable() is FALSE, rotation is ignored and assumed to be 0)
pixbuf	pixbuf into which we are to render
errorCode	return location for an error/warning code, or NULL
error	return location for an error/warning, or NULL

Syntax:

renderPageToPixbuf( in long pagenum, in long src_x, in long src_y,
                    in long src_width, in long src_height,
                    in double scale, in long rotation,
                    in LuPixbuf pixbuf,
                    out long errorCode, inout string error );

isAsynchRenderingSupported()

Description:

See renderPageToPixbufAsynch().

Return value:

TRUE if document can be rendered asynchronously.

Default return value:

FALSE

Type:

boolean

Syntax:

isAsynchRenderingSupported();

renderPageToPixbufAsynch()

Description:

Same as renderPageToPixbuf(), but received pointers to draw function, abort function and functions data. Callback functions must be defined as long _System *asynchCallbackFn( void *data );

Parameters:

errorCode	return location for an error/warning code, or NULL
error	return location for an error/warning, or NULL

Note:

You must implement renderPageToPixbuf() also, as it is used for printing.

Type:

void

Syntax:

renderPageToPixbufAsynch( in long pagenum, in long src_x,
                          in long src_y, in long src_width, in long src_height,
                          in double scale, in long rotation, in LuPixbuf pixbuf,
                          in asynchCallbackFn fnd, in asynchCallbackFn fna,
                          in somToken fndata,
                          out long errorCode, inout string error );

isRenderIntoPS()

Description:

See: renderPageToPS().

Return value:

TRUE if document will render directly into presentation space using renderPageToPS().

Default return value:

FALSE

Note:

You may not implement renderPageToPixbuf() if isRenderIntoPS() is TRUE.

Type:

boolean

Syntax:

isRenderIntoPS();

renderPageToPS()

Description: First scale the document to match the specified pixels per point,

then render the rectangle given by the upper left corner at (src_x, src_y) and src_width and src_height.

Parameters: pagenum: the page from which we are to render

src_x: x coordinate of upper left corner src_y: y coordinate of upper left corner src_width: width of rectangle to render src_height: height of rectangle to render scale: scale specified as pixels per point (if isScalable() is FALSE, scale is ignored and assumed to be 1.0) rotation: rotate the document by the specified degree (allowed values are 0, 90, 180, 270) (if isRotable() is FALSE, rotation is ignored and assumed to be 0) hps: handle of presentation space into which we are to render rect: pointer to RECTL structure, defines render area on HPS errorCode: return location for an error/warning code, or NULL error: return location for an error/warning, or NULL

Syntax: renderPageToPS( in long pagenum, in long src_x, in long src_y,

in long src_width, in long src_height, in double scale, in long rotation, in unsigned long hps, in somMToken rect, out long errorCode, inout string error );

isHaveText()

Description: See: getSelectionRectangles(), searchText().

Return value: TRUE if the document contains text, which

can be selected by the user, searched, etc.; FALSE otherwise.

Default return value: FALSE

boolean: isHaveText();

getSelectionRectangles()

Description: Returns a sequence of rectangles containing the area that would

be rendered as "selected." The returned sequence must be freed with freeRectangles().

Note: SOMMalloc() must be used for all memory allocations.

Parameters: pagenum: page number

selection: start and end point of selection as a rectangle

Return value: A newly allocated LuRectSequence, or NULL if

nothing is selected or the document doesn't have selectable text.

Default return value: NULL

Syntax: LuRectSequence *getSelectionRectangles( in long pagenum,

in LuRectangle selection );

freeRectangles()

Description: Deallocates a sequence of rectangles

allocated by getSelectionRectangles() or searchText().

void: freeRectangles( in LuRectSequence rectangles );

getText()

Description: Retrieves the contents of the specified rectangle as text.

Parameters: pagenum: page number

selection: the rectangle including the text

Return value: A pointer to the contents of the rectangle

as a string or NULL. The pointer is valid until next getText() call, or until LuDocument object is destroyed.

Default return value: NULL

Note: Charset of returned string must be UTF-8

string: getText( in long pagenum, in LuRectangle selection );

isHaveLinks()

Description: See: getLinkMapping().

Return value: TRUE if document may contain navigable links,

FALSE otherwise.

Default return value: FALSE

boolean: isHaveLinks();

getLinkMapping()

Description: Returns a sequence of LuLinkMapping items.

This sequence must be freed with freeLinkMapping() when done.

Parameters: pagenum: page number

Return value: A pointer to sequence of LuLinkMapping. Default return value: A pointer to an empty LuLinkMapSequence.

Note: SOMMalloc() must be used for all memory allocations.

Syntax: LuLinkMapSequence *getLinkMapping( in long pagenum );

freeLinkMapping()

Description: Frees a sequence of LuLinkMapping allocated by

getLinkMapping().

Parameters: mapping: A sequence of LuLinkMapping

void: freeLinkMapping( in LuLinkMapSequence mapping );

isSaveable()

Description: Describes whether the current document may be saved.

Return value: TRUE if document can be saved in same format

as original, FALSE otherwise.

Default return value: FALSE

boolean: isSaveable();

saveAs()

Description: Saves the current document.

Parameters: filename: name of file to save

Return value: TRUE, if the document was successfully saved,

FALSE otherwise.

Default return value: FALSE

Syntax: saveAs( in string filename );

isPostScriptExportable()

Description: Describes whether the current document may be

exported to PostScript.

Return value: TRUE if document can be exported to

PostScript, FALSE otherwise.

Default return value: FALSE

boolean: isPostScriptExportable();

exportToPostScript()

Description: Create a new postscript file and generate the document to it.

Parameters: filename: the path of the output filename

first_page: the first page to print last_page: the last page to print width: the paper width in 1/72 inch height: the paper height in 1/72 inch (These values will end up in the DocumentMedia, the BoundingBox DSC comments, and other places in the generated PostScript.) brkExport: pointer to boolean variable which must be checked during generating postscript, if it's TRUE - interrupt generation process.

Return value: TRUE if PS document was generated successfully or

generation was interrupted, FALSE otherwise.

Default return value: FALSE

Syntax: exportToPostScript( in string filename,

in long first_page, in long last_page, in double width, in double height, inout boolean brkExport );

isHaveFontInfo()

Description: See: getFontInfo().

Return value: TRUE if getFontInfo() can return information about

fonts used in document, FALSE otherwise.

Default return value: FALSE

boolean: isHaveFontInfo();

getFontInfo()

Description: Returns information about fonts used in document.

Returned sequence must be freed with freeFontInfo() when done.

Return value: A pointer to the sequence of LuFontInfo

or NULL if no font information.

Default return value: NULL

Note: SOMMalloc() must be used for all memory allocations.

Syntax: LuFontInfoSequence *getFontInfo();

freeFontInfo()

Description: Frees a sequence of LuFontInfo allocated by

getFontInfo().

Parameters: fonts: A sequence of LuFontInfo

void: freeFontInfo( in LuFontInfoSequence fonts );

isHaveIndex()

Description: Determines if the document has an index associated with it.

See getIndex()

Return value: TRUE if the document has an index, FALSE otherwise. Default return value: FALSE

boolean: isHaveIndex();

getIndex()

Description: Certain documents have an index associated with them.

This index can be used to help the user navigate the document, and is similar to a table of contents. Each node in the index will contain a LuLink which can be displayed to the user.

Here is a simple example of some code that walks the full index:

void viewTree( int level, LuIndexNode *n ) {

if ( n == NULL ) {

return;

}

somLPrintf( level, "title: %s\n", n->getLink(ev)->title );

LuIndexNode *cn = n->getFirstChild( ev ); while ( cn != NULL ) {

viewTree( level + 1, cn ); cn = n->getNextChild( ev );

}

}

Return value: A new LuIndexNode, which represents an index root,

or NULL, if the document doesn't have an index.

Default return value: NULL

Syntax: LuIndexNode getIndex();

getDocumentInfo()

Description: Returns information about the current document.

Returned sequence must be freed with freeDocumentInfo() when done.

Return value: A pointer to the sequence of LuDocumentInfo

or NULL if no information is available.

Default return value: NULL

Syntax: LuDocumentInfo *getDocumentInfo();

freeDocumentInfo()

Description: Frees a LuDocumentInfo structure allocated by getDocumentInfo().

Parameters: info: LuDocumentInfo structure allocated by getDocumentInfo()

void: freeDocumentInfo( in LuDocumentInfo info );

getThumbnailSize()

Description: Returns TRUE if the page has a thumbnail associated with it. It also

fills the width and height with the those of the thumbnail. The values of width and height are not changed if no appropriate thumbnail exists.

Parameters: pagenum: page number

suggested_width: if thumbnail doesn't have a predefined width, it will be created with suggested_width. width: value for width height: value for height

Return value: TRUE, if the page has a thumbnail associated with it, FALSE otherwise. Default return value: FALSE

Syntax: getThumbnailSize( in long pagenum, in short suggested_width, inout short width, inout short height );

getThumbnail()

Description: Returns pointer to LuPixbuf

Parameters: pagenum: page number

suggested_width: if thumbnail doesn't have a predefined width, it will be created with suggested_width.

Return value: pointer to LuPixbuf, if page has a thumbnail associated with it,

or NULL.

Default return value: NULL

Syntax: LuPixbuf getThumbnail( in long pagenum, in short suggested_width );

searchText()

Description: Returns a sequence of rectangles for each occurrence of the text

found on the page. The returned sequence must be freed with freeRectangles()

Parameters: pagenum: page number

text: the text to find (in system encoding)

Return value: A newly allocated LuRectSequence, or NULL if nothing found Default return value: NULL

Note: SOMMalloc() must be used for all memory allocations.

Syntax: LuRectSequence *searchText( in long pagenum, in string text,

in boolean caseSensitive, in boolean findBack );

isCreateFileThumbnail()

Description: If this method returns TRUE, then GUI may create thumbnail for

this file and write it into EAs.

Return value: TRUE, if thumbnail may be created, FALSE otherwise. Default return value: FALSE

boolean: isCreateFileThumbnail();

isHaveInputFields()

Description: Returns TRUE if the document contains input fields, FALSE otherwise.

See: getInputFields().

Return value: TRUE, if the document contains input fields, FALSE otherwise. Default return value: FALSE

boolean: isHaveInputFields();

getInputFields()

Description: Returns a sequence of LuInputField items that may be used to enter

data into the document. This sequence must be freed with freeInputFields() when done.

Parameters: pagenum: page number

Return value: A pointer to sequence of valid LuInputField items. Default return value: A pointer to an empty LuInputFieldSequence.

Note: The returned sequence must be allocated with SOMMalloc(),

each element must be a newly created SOM object.

Syntax: LuInputFieldSequence *getInputFields( in long pagenum );

freeInputFields()

Description: Frees the input field sequence returned by getInputFields().

Subclasses should never override this method.

void: freeInputFields(in LuInputFieldSequence aInputFields);