= Lucide Plugin API =
[[PageOutline]]
A well-commented, working plugin may be seen in [/lucide/browser/trunk/Lucide/plugins/ludoc/ludoc.idl 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() [=#isScalable]
Description:
  See: [#renderPageToPixbuf_scale 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() [=#isRotable]
Description:
  See: [#renderPageToPixbuf_rotation 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() [=#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||
  ||[=#renderPageToPixbuf_scale scale]||scale specified as pixels per point (if [#isScalable isScalable()] is FALSE, scale is ignored and assumed to be 1.0)||
  ||[=#renderPageToPixbuf_rotation rotation]||rotate the document by the specified degree (allowed values are 0, 90, 180, 270) (if [#isRotable 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 renderPageToPixbufAsynch()].
Return value:
  TRUE if document can be rendered asynchronously.
Default return value:
  FALSE
Type:
  boolean
Syntax:
  {{{isAsynchRenderingSupported();}}}

=== renderPageToPixbufAsynch() [=#renderPageToPixbufAsynch]
Description:
  Same as [#renderPageToPixbuf 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 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() [=#isRenderIntoPS]
Description:
  See: [#renderPageToPS renderPageToPS()].
Return value:
  TRUE if document will render directly into presentation space using [#renderPageToPS renderPageToPS()].
Default return value:
  FALSE
Note:
  You may not implement [#renderPageToPixbuf renderPageToPixbuf()] if [#isRenderIntoPS isRenderIntoPS()] is TRUE.
Type:
  boolean
Syntax:
  {{{isRenderIntoPS();}}}

=== renderPageToPS() [=#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 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 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 getSelectionRectangles()], [#searchText searchText()].
Return value:	
  TRUE if the document contains text, which can be selected by the user, searched, etc.; FALSE otherwise.
Default return value:
  FALSE
Type:
  boolean
Syntax:
  {{{isHaveText();}}}

=== getSelectionRectangles() [=#getSelectionRectangles]
Description:	
  Returns a sequence of rectangles containing the area that would be rendered as "selected." The returned sequence must be freed with [#freeRectangles freeRectangles()].
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
Note:
  SOMMalloc() must be used for all memory allocations.
Syntax:
  {{{LuRectSequence *getSelectionRectangles( in long pagenum, in LuRectangle selection );}}}

=== freeRectangles() [=#freeRectangles]
Description:
  Deallocates a sequence of rectangles allocated by [#getSelectionRectangles getSelectionRectangles()] or [#searchText searchText()].
Type:
  void
Syntax:
  {{{freeRectangles( in LuRectSequence rectangles );}}}

=== getText() [=#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 getText()] call, or until !LuDocument object is destroyed.
Default return value:
  NULL
Note:
  Charset of returned string must be UTF-8
Type:
  string
Syntax:
  {{{getText( in long pagenum, in LuRectangle selection );}}}

=== isHaveLinks() ===
Description:
  See: [#getLinkMapping getLinkMapping()].
Return value:
  TRUE if document may contain navigable links; FALSE otherwise.
Default return value:
  FALSE
Type:
  boolean
Syntax:	
  {{{isHaveLinks();}}}

=== getLinkMapping() [=#getLinkMapping]
Description:
  Returns a sequence of !LuLinkMapping items. This sequence must be freed with [#freeLinkMapping 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() [=#freeLinkMapping]
Description:
  Frees a sequence of !LuLinkMapping allocated by [#getLinkMapping getLinkMapping()].
Parameters:
  ||mapping||A sequence of !LuLinkMapping||
Type:
  void
Syntax:
  {{{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
Type:
  boolean
Syntax:
  {{{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
Type:
  string
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
Type:
  boolean
Syntax:
  {{{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||
  ||brkExport||pointer to boolean variable which must be checked during generating !PostScript; if TRUE, interrupt generation process.||
Return value:
  TRUE if !PostScript document was generated successfully or generation was interrupted; FALSE otherwise.
Default return value:
  FALSE
Note:
  Values for width and height will end up in the !DocumentMedia, the !BoundingBox DSC comments, and other places in the generated !PostScript.
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 getFontInfo()].
Return value:
  TRUE if [#getFontInfo getFontInfo()] can return information about fonts used in the document; FALSE otherwise.
Default return value:
  FALSE
Type:
  boolean
Syntax:
  {{{isHaveFontInfo();}}}

=== getFontInfo() [=#getFontInfo]
Description:
  Returns information about fonts used in document. Returned sequence must be freed with [#freeFontInfo 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() [=#freeFontInfo]
Description:
  Frees a sequence of !LuFontInfo allocated by [#getFontInfo getFontInfo()].
Parameters:
  ||fonts||A sequence of !LuFontInfo||
Type:
  void
Syntax:
  {{{freeFontInfo( in LuFontInfoSequence fonts );}}}

=== isHaveIndex() ===
Description:
  Determines if the document has an index associated with it. See: [#getIndex getIndex()].
Return value:
  TRUE if the document has an index; FALSE otherwise.
Default return value:
  FALSE
Type:
  boolean
Syntax:
  {{{isHaveIndex();}}}

=== getIndex() [=#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() [=#getDocumentInfo]
Description:
  Returns information about the current document. Returned sequence must be freed with [#freeDocumentInfo 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() [=#freeDocumentInfo]
Description:
  Frees a !LuDocumentInfo structure allocated by [#getDocumentInfo getDocumentInfo()].
Parameters:
  ||info||!LuDocumentInfo structure allocated by [#getDocumentInfo getDocumentInfo()]||
Type:
  void
Syntax:
  {{{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() [=#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 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 a thumbnail for this file and write it into the file's EAs.
Return value:
  TRUE, if thumbnail may be created; FALSE otherwise.
Default return value:
  FALSE
Type:
  boolean
Syntax:
  {{{isCreateFileThumbnail();}}}

=== isHaveInputFields() ===
Description:
  Returns TRUE if the document contains input fields; FALSE otherwise. See: [#getInputFields getInputFields()].
Return value:
  TRUE, if the document contains input fields; FALSE otherwise.
Default return value:
  FALSE
Type:
  boolean
Syntax:
  {{{isHaveInputFields();}}}

=== getInputFields() [=#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 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() [=#freeInputFields]
Description:
  Frees the input field sequence returned by [#getInputFields getInputFields()]. Subclasses should never override this method.
Type:
  void
Syntax:
  {{{freeInputFields(in LuInputFieldSequence aInputFields);}}}