Changes between Version 4 and Version 5 of Lucide-Plugin-API


Ignore:
Timestamp:
Sep 21, 2016, 3:48:47 AM (8 years ago)
Author:
Lewis Rosenthal
Comment:

More formatting

Legend:

Unmodified
Added
Removed
Modified

  • Lucide-Plugin-API

    v4 v5  
    11= Lucide Plugin API =
    22[[PageOutline]]
    3 A bird's eye view of how a plugin is constructed may be seen in plugins/ludoc/ludoc.idl.
     3A well-commented, working plugin may be seen in [/lucide/browser/trunk/Lucide/plugins/ludoc/ludoc.idl ludoc.idl].
    44
    55== Available methods ==
    … …  
    1515  ||error||return location for an error, or NULL||
    1616Return value:
    17   TRUE if file has loaded, FALSE otherwise.
     17  TRUE if file has loaded; FALSE otherwise.
    1818Default return value:
    1919  FALSE
    … …  
    3636  {{{getBpp();}}}
    3737
    38 === isScalable() ===
    39 Description:
    40   See: [#renderPageToPixbuf renderPageToPixbuf()], scale.
    41 Return value:
    42   TRUE if document is scalable, FALSE otherwise.
     38=== isScalable() [=#isScalable]
     39Description:
     40  See: [#renderPageToPixbuf_scale renderPageToPixbuf(), scale].
     41Return value:
     42  TRUE if document is scalable; FALSE otherwise.
    4343Default return value:
    4444  FALSE
    … …  
    5252  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.
    5353Return value:
    54   TRUE if document is fixed-size, FALSE otherwise.
     54  TRUE if document is fixed-size; FALSE otherwise.
    5555Default return value:
    5656  TRUE
    … …  
    6060  {{{isFixedImage();}}}
    6161
    62 === isRotable() ===
    63 Description:
    64   See: [=#renderPageToPixbuf renderPageToPixbuf()], rotation.
    65 Return value:
    66   TRUE if document can be rotated, FALSE otherwise.
     62=== isRotable() [=#isRotable]
     63Description:
     64  See: [#renderPageToPixbuf_rotation renderPageToPixbuf(), rotation].
     65Return value:
     66  TRUE if document can be rotated; FALSE otherwise.
    6767Default return value:
    6868  FALSE
    … …  
    9696  {{{getPageSize( in long pagenum, inout double width, inout double height );}}}
    9797
    98 [=#renderPageToPixbuf ]
    99 === renderPageToPixbuf() ===
     98=== renderPageToPixbuf() [=#renderPageToPixbuf]
    10099Description:
    101100  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.
    … …  
    106105  ||src_width||width of rectangle to render||
    107106  ||src_height||height of rectangle to render||
    108   ||scale||scale specified as pixels per point (if isScalable() is FALSE, scale is ignored and assumed to be 1.0)||
    109   ||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)||
     107  ||[=#renderPageToPixbuf_scale scale]||scale specified as pixels per point (if [#isScalable isScalable()] is FALSE, scale is ignored and assumed to be 1.0)||
     108  ||[=#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)||
    110109  ||pixbuf||pixbuf into which we are to render||
    111110  ||errorCode||return location for an error/warning code, or NULL||
    … …  
    118117                    in LuPixbuf pixbuf,
    119118                    out long errorCode, inout string error );
    120 }}}
     119  }}}
    121120
    122121=== isAsynchRenderingSupported() ===
    … …  
    132131  {{{isAsynchRenderingSupported();}}}
    133132
    134 [=#renderPageToPixbufAsynch ]
    135 === renderPageToPixbufAsynch() ===
    136 Description:
    137   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 );
     133=== renderPageToPixbufAsynch() [=#renderPageToPixbufAsynch]
     134Description:
     135  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 );}}}.
    138136Parameters:
    139137  ||errorCode||return location for an error/warning code, or NULL||
    … …  
    153151  }}}
    154152
    155 === isRenderIntoPS() ===
     153=== isRenderIntoPS() [=#isRenderIntoPS]
    156154Description:
    157155  See: [#renderPageToPS renderPageToPS()].
    … …  
    161159  FALSE
    162160Note:
    163   You may not implement renderPageToPixbuf() if isRenderIntoPS() is TRUE.
     161  You may not implement [#renderPageToPixbuf renderPageToPixbuf()] if [#isRenderIntoPS isRenderIntoPS()] is TRUE.
    164162Type:
    165163  boolean
    … …  
    167165  {{{isRenderIntoPS();}}}
    168166
    169 [=#renderPageToPS ]
    170 === renderPageToPS() ===
     167=== renderPageToPS() [=#renderPageToPS]
    171168Description:
    172169  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.
    … …  
    177174  ||src_width||width of rectangle to render||
    178175  ||src_height||height of rectangle to render||
    179   ||scale||scale specified as pixels per point (if isScalable() is FALSE, scale is ignored and assumed to be 1.0)||
    180   ||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)||
     176  ||scale||scale specified as pixels per point (if [#isScalable isScalable()] is FALSE, scale is ignored and assumed to be 1.0)||
     177  ||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)||
    181178  ||hps||handle of presentation space into which we are to render||
    182179  ||rect||pointer to RECTL structure, defines render area on HPS||
    … …  
    204201  {{{isHaveText();}}}
    205202
    206 [=#getSelectionRectangles ]
    207 === getSelectionRectangles() ===
     203=== getSelectionRectangles() [=#getSelectionRectangles]
    208204Description:   
    209205  Returns a sequence of rectangles containing the area that would be rendered as "selected." The returned sequence must be freed with [#freeRectangles freeRectangles()].
    … …  
    212208  ||selection||start and end point of selection as a rectangle||
    213209Return value:
    214   A newly allocated LuRectSequence, or NULL if nothing is selected or the document doesn't have selectable text.
     210  A newly allocated !LuRectSequence, or NULL if nothing is selected or the document doesn't have selectable text.
    215211Default return value:
    216212  NULL
    … …  
    220216  {{{LuRectSequence *getSelectionRectangles( in long pagenum, in LuRectangle selection );}}}
    221217
    222 [=#freeRectangles ]
    223 === freeRectangles() ===
     218=== freeRectangles() [=#freeRectangles]
    224219Description:
    225220  Deallocates a sequence of rectangles allocated by [#getSelectionRectangles getSelectionRectangles()] or [#searchText searchText()].
    … …  
    229224  {{{freeRectangles( in LuRectSequence rectangles );}}}
    230225
    231 === getText() ===
     226=== getText() [=#getText]
    232227Description:
    233228  Retrieves the contents of the specified rectangle as text.
    … …  
    236231  ||selection||the rectangle including the text||
    237232Return value:
    238   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.
     233  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.
    239234Default return value:
    240235  NULL
    … …  
    250245  See: [#getLinkMapping getLinkMapping()].
    251246Return value:
    252   TRUE if document may contain navigable links, FALSE otherwise.
     247  TRUE if document may contain navigable links; FALSE otherwise.
    253248Default return value:
    254249  FALSE
    … …  
    258253  {{{isHaveLinks();}}}
    259254
    260 [=#getLinkMapping ]
    261 === getLinkMapping() ===
    262 Description:
    263   Returns a sequence of LuLinkMapping items. This sequence must be freed with [#freeLinkMapping freeLinkMapping()] when done.
    264 Parameters:
    265   ||pagenum||page number||
    266 Return value:
    267   A pointer to sequence of LuLinkMapping.
    268 Default return value:
    269   A pointer to an empty LuLinkMapSequence.
     255=== getLinkMapping() [=#getLinkMapping]
     256Description:
     257  Returns a sequence of !LuLinkMapping items. This sequence must be freed with [#freeLinkMapping freeLinkMapping()] when done.
     258Parameters:
     259  ||pagenum||page number||
     260Return value:
     261  A pointer to sequence of !LuLinkMapping.
     262Default return value:
     263  A pointer to an empty !LuLinkMapSequence.
    270264Note:
    271265  SOMMalloc() must be used for all memory allocations.
    … …  
    273267   {{{LuLinkMapSequence *getLinkMapping( in long pagenum );}}}
    274268
    275 [=#freeLinkMapping ]
    276 === freeLinkMapping() ===
    277 Description:
    278   Frees a sequence of LuLinkMapping allocated by [#getLinkMapping getLinkMapping()].
    279 Parameters:
    280   ||mapping||A sequence of LuLinkMapping||
     269=== freeLinkMapping() [=#freeLinkMapping]
     270Description:
     271  Frees a sequence of !LuLinkMapping allocated by [#getLinkMapping getLinkMapping()].
     272Parameters:
     273  ||mapping||A sequence of !LuLinkMapping||
    281274Type:
    282275  void
    … …  
    288281  Describes whether the current document may be saved.
    289282Return value:
    290   TRUE if document can be saved in same format as original, FALSE otherwise.
     283  TRUE if document can be saved in same format as original; FALSE otherwise.
    291284Default return value:
    292285  FALSE
    … …  
    303296
    304297Return value:
    305   TRUE, if the document was successfully saved, FALSE otherwise.
     298  TRUE, if the document was successfully saved; FALSE otherwise.
    306299Default return value:
    307300  FALSE
    … …  
    313306=== isPostScriptExportable() ===
    314307Description:
    315   Describes whether the current document may be exported to PostScript.
    316 Return value:
    317   TRUE if document can be exported to PostScript, FALSE otherwise.
     308  Describes whether the current document may be exported to !PostScript.
     309Return value:
     310  TRUE if document can be exported to !PostScript; FALSE otherwise.
    318311Default return value:
    319312  FALSE
    … …  
    325318=== exportToPostScript() ===
    326319Description:
    327   Create a new postscript file and generate the document to it.
     320  Create a new !PostScript file and generate the document to it.
    328321Parameters:
    329322  ||filename||the path of the output filename||
    … …  
    332325  ||width||the paper width in 1/72 inch||
    333326  ||height||the paper height in 1/72 inch||
    334   ||brkExport||pointer to boolean variable which must be checked during generating postscript; if TRUE, interrupt generation process.||
    335 Return value:
    336   TRUE if PS document was generated successfully or generation was interrupted, FALSE otherwise.
    337 Default return value:
    338   FALSE
    339 Note:
    340   Values for width and height will end up in the DocumentMedia, the BoundingBox DSC comments, and other places in the generated PostScript.
     327  ||brkExport||pointer to boolean variable which must be checked during generating !PostScript; if TRUE, interrupt generation process.||
     328Return value:
     329  TRUE if !PostScript document was generated successfully or generation was interrupted; FALSE otherwise.
     330Default return value:
     331  FALSE
     332Note:
     333  Values for width and height will end up in the !DocumentMedia, the !BoundingBox DSC comments, and other places in the generated !PostScript.
    341334Syntax:
    342335{{{
    … …  
    351344  See: [#getFontInfo getFontInfo()].
    352345Return value:
    353   TRUE if getFontInfo() can return information about fonts used in the document, FALSE otherwise.
     346  TRUE if [#getFontInfo getFontInfo()] can return information about fonts used in the document; FALSE otherwise.
    354347Default return value:
    355348  FALSE
    … …  
    359352  {{{isHaveFontInfo();}}}
    360353
    361 [=#getFontInfo ]
    362 === getFontInfo() ===
     354=== getFontInfo() [=#getFontInfo]
    363355Description:
    364356  Returns information about fonts used in document. Returned sequence must be freed with [#freeFontInfo freeFontInfo()] when done.
    365357Return value:
    366   A pointer to the sequence of LuFontInfo or NULL if no font information.
     358  A pointer to the sequence of !LuFontInfo or NULL if no font information.
    367359Default return value:
    368360  NULL
    … …  
    372364  {{{LuFontInfoSequence *getFontInfo();}}}
    373365
    374 [=#freeFontInfo ]
    375 === freeFontInfo() ===
    376 Description:
    377   Frees a sequence of LuFontInfo allocated by [#getFontInfo getFontInfo()].
    378 Parameters:
    379   ||fonts||A sequence of LuFontInfo||
     366=== freeFontInfo() [=#freeFontInfo]
     367Description:
     368  Frees a sequence of !LuFontInfo allocated by [#getFontInfo getFontInfo()].
     369Parameters:
     370  ||fonts||A sequence of !LuFontInfo||
    380371Type:
    381372  void
    … …  
    385376=== isHaveIndex() ===
    386377Description:
    387   Determines if the document has an index associated with it. See [#getIndex getIndex()].
    388 Return value:
    389   TRUE if the document has an index, FALSE otherwise.
    390 Default return value:
    391   FALSE
    392 Type:
    393   boolean
    394 Syntax:
    395   isHaveIndex();
    396 
    397 [=#getIndex ]
    398 === getIndex() ===
    399 Description:
    400   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.
     378  Determines if the document has an index associated with it. See: [#getIndex getIndex()].
     379Return value:
     380  TRUE if the document has an index; FALSE otherwise.
     381Default return value:
     382  FALSE
     383Type:
     384  boolean
     385Syntax:
     386  {{{isHaveIndex();}}}
     387
     388=== getIndex() [=#getIndex]
     389Description:
     390  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.
    401391 
    402392  Here is a simple example of some code that walks the full index:
    … …  
    418408  }}}
    419409Return value:
    420   A new LuIndexNode, which represents an index root, or NULL, if the document doesn't have an index.
     410  A new !LuIndexNode, which represents an index root, or NULL, if the document doesn't have an index.
    421411Default return value:
    422412  NULL
    … …  
    424414  {{{LuIndexNode getIndex();}}}
    425415
    426 [=#getDocumentInfo ]
    427 === getDocumentInfo() ===
     416=== getDocumentInfo() [=#getDocumentInfo]
    428417Description:
    429418  Returns information about the current document. Returned sequence must be freed with [#freeDocumentInfo freeDocumentInfo()] when done.
    430419Return value:
    431   A pointer to the sequence of LuDocumentInfo or NULL if no information is available.
     420  A pointer to the sequence of !LuDocumentInfo or NULL if no information is available.
    432421Default return value:
    433422  NULL
    … …  
    435424  {{{LuDocumentInfo *getDocumentInfo();}}}
    436425
    437 [=#freeDocumentInfo ]
    438 === freeDocumentInfo() ===
    439 Description:
    440   Frees a LuDocumentInfo structure allocated by [#getDocumentInfo getDocumentInfo()].
    441 Parameters:
    442   ||info||LuDocumentInfo structure allocated by [#getDocumentInfo getDocumentInfo()]||
     426=== freeDocumentInfo() [=#freeDocumentInfo]
     427Description:
     428  Frees a !LuDocumentInfo structure allocated by [#getDocumentInfo getDocumentInfo()].
     429Parameters:
     430  ||info||!LuDocumentInfo structure allocated by [#getDocumentInfo getDocumentInfo()]||
    443431Type:
    444432  void
    … …  
    455443  ||height||value for height||
    456444Return value:
    457   TRUE, if the page has a thumbnail associated with it, FALSE otherwise.
     445  TRUE, if the page has a thumbnail associated with it; FALSE otherwise.
    458446Default return value:
    459447  FALSE
    … …  
    463451=== getThumbnail() ===
    464452Description:
    465   Returns pointer to LuPixbuf.
     453  Returns pointer to !LuPixbuf.
    466454Parameters:
    467455  ||pagenum||page number||
    468456  ||suggested_width||if thumbnail doesn't have a predefined width, it will be created with suggested_width.||
    469457Return value:
    470   Pointer to LuPixbuf, if page has a thumbnail associated with it, or NULL.
     458  Pointer to !LuPixbuf, if page has a thumbnail associated with it, or NULL.
    471459Default return value:
    472460  NULL
    … …  
    474462  {{{LuPixbuf getThumbnail( in long pagenum, in short suggested_width );}}}
    475463
    476 [=#searchText ]
    477 === searchText() ===
     464=== searchText() [=#searchText]
    478465Description:
    479466  Returns a sequence of rectangles for each occurrence of the text found on the page. The returned sequence must be freed with [#freeRectangles freeRectangles()].
    … …  
    482469  ||text||the text to find (in system encoding)||
    483470Return value:
    484   A newly allocated LuRectSequence, or NULL if nothing found
     471  A newly allocated !LuRectSequence, or NULL if nothing found
    485472Default return value:
    486473  NULL
    … …  
    497484  If this method returns TRUE, then GUI may create a thumbnail for this file and write it into the file's EAs.
    498485Return value:
    499   TRUE, if thumbnail may be created, FALSE otherwise.
     486  TRUE, if thumbnail may be created; FALSE otherwise.
    500487Default return value:
    501488  FALSE
    … …  
    507494=== isHaveInputFields() ===
    508495Description:
    509   Returns TRUE if the document contains input fields, FALSE otherwise. See: [#getInputFields getInputFields()].
    510 Return value:
    511   TRUE, if the document contains input fields, FALSE otherwise.
     496  Returns TRUE if the document contains input fields; FALSE otherwise. See: [#getInputFields getInputFields()].
     497Return value:
     498  TRUE, if the document contains input fields; FALSE otherwise.
    512499Default return value:
    513500  FALSE
    … …  
    517504  {{{isHaveInputFields();}}}
    518505
    519 [=#getInputFields ]
    520 === getInputFields() ===
    521 Description:
    522   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.
    523 Parameters:
    524   ||pagenum||page number||
    525 Return value:
    526   A pointer to sequence of valid LuInputField items.
    527 Default return value:
    528   A pointer to an empty LuInputFieldSequence.
     506=== getInputFields() [=#getInputFields]
     507Description:
     508  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.
     509Parameters:
     510  ||pagenum||page number||
     511Return value:
     512  A pointer to sequence of valid !LuInputField items.
     513Default return value:
     514  A pointer to an empty !LuInputFieldSequence.
    529515Note:
    530516  The returned sequence must be allocated with SOMMalloc(), each element must be a newly created SOM object.
    … …  
    532518  {{{LuInputFieldSequence *getInputFields( in long pagenum );}}}
    533519
    534 [=#freeInputFields ]
    535 === freeInputFields() ===
     520=== freeInputFields() [=#freeInputFields]
    536521Description:
    537522  Frees the input field sequence returned by [#getInputFields getInputFields()]. Subclasses should never override this method.