Changes between Version 1 and Version 2 of Lucide-Plugin-API

Timestamp:

Sep 20, 2016, 2:46:00 PM (8 years ago)

Author:

Lewis Rosenthal

Comment:

Initial API documentation from ludoc.idl (thanks for the pointer, Eugene!)

Lucide-Plugin-API

@@ -1 @@
-None yet.
+= Lucide Plugin API =
+[[PageOutline]]
+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 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 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
+
+long:           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)
+
+void:           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
+                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
+
+boolean:        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.
+
+void:           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.
+
+boolean:        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);}}}