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


Ignore:
Timestamp:
Sep 20, 2016, 4:46:00 PM (3 years ago)
Author:
lewisr
Comment:

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

Legend:

Unmodified
Added
Removed
Modified
  • Lucide-Plugin-API

    v1 v2  
    1 None yet.
     1= Lucide Plugin API =
     2[[PageOutline]]
     3A bird's eye view of how a plugin is constructed may be seen in plugins/ludoc/ludoc.idl.
     4
     5== Available methods ==
     6NB: All page numbers are zero-based.
     7
     8=== loadFile() ===
     9Description:
     10  Loads the specified file.
     11Parameters:
     12  ||filename||filename of the file to load||
     13  ||password||password if necessary, or NULL||
     14  ||errorCode||return location for an error code, or NULL||
     15  ||error||return location for an error, or NULL||
     16Return value:
     17  TRUE if file has loaded, FALSE otherwise.
     18Default return value:
     19  FALSE
     20Note:
     21  Error string is allocated using SOMMalloc(), use SOMFree() to free.
     22Syntax:
     23  {{{loadFile( in string filename, in string password, out long errorCode, inout string error );}}}
     24
     25=== getBpp() ===
     26Description:
     27  Get the number of bytes per pixel used for drawing.
     28Return value:
     29  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.
     30Default
     31return value:
     32  0
     33Type:
     34  short
     35Syntax:
     36  {{{getBpp();}}}
     37
     38=== isScalable() ===
     39Description:
     40  See: [#renderPageToPixbuf renderPageToPixbuf()], scale.
     41Return value:
     42  TRUE if document is scalable, FALSE otherwise.
     43Default return value:
     44  FALSE
     45Type:
     46  boolean
     47Syntax:
     48  {{{isScalable();}}}
     49
     50=== isFixedImage() ===
     51
     52Description:
     53  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.
     54Return value:
     55  TRUE if document is fixed-size, FALSE otherwise.
     56Default return value:
     57  TRUE
     58Type:
     59  boolean
     60Syntax:
     61  {{{isFixedImage();}}}
     62
     63=== isRotable() ===
     64
     65Description:
     66  See: [=#renderPageToPixbuf renderPageToPixbuf()], rotation.
     67Return value:
     68  TRUE if document can be rotated, FALSE otherwise.
     69Default return value:
     70  FALSE
     71Type:
     72  boolean
     73Syntax:
     74  {{{isRotable();}}}
     75
     76=== getPageCount() ===
     77
     78Description:    Returns the number of pages in the loaded document.
     79
     80Return value:   Number of pages.
     81Default
     82return value:   0
     83
     84long:           getPageCount();
     85
     86
     87
     88=== getPageSize() ===
     89
     90Description:    Gets the size of the specified page.
     91
     92Parameters:     pagenum: page number
     93                width: return the width of the page
     94                (NULL if width is not needed)
     95                height: return the height of the page
     96                (NULL if height is not needed)
     97
     98void:           getPageSize( in long pagenum, inout double width, inout double height );
     99
     100
     101[=#renderPageToPixbuf ]
     102=== renderPageToPixbuf() ===
     103
     104Description:    First, scale the document to match the specified pixels per point,
     105                then render the rectangle given by the upper left corner at
     106                (src_x, src_y) and src_width by src_height.
     107
     108Parameters:     pagenum: the page from which we are to render
     109                src_x: x coordinate of upper left corner
     110                src_y: y coordinate of upper left corner
     111                src_width: width of rectangle to render
     112                src_height: height of rectangle to render
     113                scale: scale specified as pixels per point
     114                (if isScalable() is FALSE, scale is ignored and assumed to be 1.0)
     115                rotation: rotate the document by the specified degree
     116                (allowed values are 0, 90, 180, 270)
     117                (if isRotable() is FALSE, rotation is ignored and assumed to be 0)
     118                pixbuf: pixbuf into which we are to render
     119                errorCode: return location for an error/warning code, or NULL
     120                error: return location for an error/warning, or NULL
     121
     122Syntax:         renderPageToPixbuf( in long pagenum, in long src_x, in long src_y,
     123                        in long src_width, in long src_height,
     124                        in double scale, in long rotation,
     125                        in LuPixbuf pixbuf,
     126                        out long errorCode, inout string error );
     127
     128
     129=== isAsynchRenderingSupported() ===
     130
     131Description:    See renderPageToPixbufAsynch().
     132
     133Return value:   TRUE if document can be rendered asynchronously.
     134Default
     135return value:   FALSE
     136
     137boolean:        isAsynchRenderingSupported();
     138
     139
     140=== renderPageToPixbufAsynch() ===
     141
     142Description:    Same as renderPageToPixbuf(), but received pointers to
     143                draw function, abort function and functions data.
     144                Callback functions must be defined as
     145                long _System *asynchCallbackFn( void *data );
     146
     147Parameters:     errorCode: return location for an error/warning code, or NULL
     148                error: return location for an error/warning, or NULL
     149
     150Note:           You must implement renderPageToPixbuf() also, as
     151                it is used for printing.
     152
     153void:           renderPageToPixbufAsynch( in long pagenum, in long src_x,
     154                        in long src_y, in long src_width, in long src_height,
     155                        in double scale, in long rotation, in LuPixbuf pixbuf,
     156                        in asynchCallbackFn fnd, in asynchCallbackFn fna,
     157                        in somToken fndata,
     158                        out long errorCode, inout string error );
     159
     160
     161=== isRenderIntoPS() ===
     162
     163Description:    See: renderPageToPS().
     164
     165Return value:   TRUE if document will render directly into
     166                presentation space using renderPageToPS().
     167Default
     168return value:   FALSE
     169
     170Note:           You may not implement renderPageToPixbuf() if
     171                isRenderIntoPS() is TRUE.
     172
     173boolean:        isRenderIntoPS();
     174
     175
     176=== renderPageToPS() ===
     177
     178Description:    First scale the document to match the specified pixels per point,
     179                then render the rectangle given by the upper left corner at
     180                (src_x, src_y) and src_width and src_height.
     181
     182Parameters:     pagenum: the page from which we are to render
     183                src_x: x coordinate of upper left corner
     184                src_y: y coordinate of upper left corner
     185                src_width: width of rectangle to render
     186                src_height: height of rectangle to render
     187                scale: scale specified as pixels per point
     188                (if isScalable() is FALSE, scale is ignored and assumed to be 1.0)
     189                rotation: rotate the document by the specified degree
     190                (allowed values are 0, 90, 180, 270)
     191                (if isRotable() is FALSE, rotation is ignored and assumed to be 0)
     192                hps: handle of presentation space into which we are to render
     193                rect: pointer to RECTL structure, defines render area on HPS
     194                errorCode: return location for an error/warning code, or NULL
     195                error: return location for an error/warning, or NULL
     196
     197Syntax:         renderPageToPS( in long pagenum, in long src_x, in long src_y,
     198                        in long src_width, in long src_height,
     199                        in double scale, in long rotation,
     200                        in unsigned long hps, in somMToken rect,
     201                        out long errorCode, inout string error );
     202
     203
     204=== isHaveText() ===
     205
     206Description:    See: getSelectionRectangles(), searchText().
     207
     208Return value:   TRUE if the document contains text, which
     209                can be selected by the user, searched, etc.;
     210                FALSE otherwise.
     211Default
     212return value:   FALSE
     213
     214boolean:        isHaveText();
     215
     216
     217=== getSelectionRectangles() ===
     218
     219Description:    Returns a sequence of rectangles containing the area that would
     220                be rendered as "selected."
     221                The returned sequence must be freed with freeRectangles().
     222
     223Note:           SOMMalloc() must be used for all memory allocations.
     224
     225Parameters:     pagenum: page number
     226                selection: start and end point of selection as a rectangle
     227
     228Return value:   A newly allocated LuRectSequence, or NULL if
     229                nothing is selected or the document doesn't have
     230                selectable text.
     231Default
     232return value:   NULL
     233
     234
     235Syntax:         LuRectSequence *getSelectionRectangles( in long pagenum,
     236                        in LuRectangle selection );
     237
     238
     239=== freeRectangles() ===
     240
     241Description:    Deallocates a sequence of rectangles
     242                allocated by getSelectionRectangles() or searchText().
     243
     244void:           freeRectangles( in LuRectSequence rectangles );
     245
     246
     247=== getText() ===
     248
     249Description:    Retrieves the contents of the specified rectangle as text.
     250
     251Parameters:     pagenum: page number
     252                selection: the rectangle including the text
     253
     254Return value:   A pointer to the contents of the rectangle
     255                as a string or NULL.
     256                The pointer is valid until next getText() call,
     257                or until LuDocument object is destroyed.
     258Default
     259return value:   NULL
     260
     261Note:           Charset of returned string must be UTF-8
     262
     263string:         getText( in long pagenum, in LuRectangle selection );
     264
     265
     266=== isHaveLinks() ===
     267
     268Description:    See: getLinkMapping().
     269
     270Return value:   TRUE if document may contain navigable links,
     271                FALSE otherwise.
     272Default
     273return value:   FALSE
     274
     275boolean:        isHaveLinks();
     276
     277
     278=== getLinkMapping() ===
     279
     280Description:    Returns a sequence of LuLinkMapping items.
     281                This sequence must be freed
     282                with freeLinkMapping() when done.
     283
     284Parameters:     pagenum: page number
     285
     286Return value:   A pointer to sequence of LuLinkMapping.
     287Default
     288return value:   A pointer to an empty LuLinkMapSequence.
     289
     290Note:           SOMMalloc() must be used for all memory allocations.
     291
     292Syntax:         LuLinkMapSequence *getLinkMapping( in long pagenum );
     293
     294
     295=== freeLinkMapping() ===
     296
     297Description:    Frees a sequence of LuLinkMapping allocated by
     298                getLinkMapping().
     299
     300Parameters:     mapping: A sequence of LuLinkMapping
     301
     302void:           freeLinkMapping( in LuLinkMapSequence mapping );
     303
     304
     305
     306=== isSaveable() ===
     307
     308Description:    Describes whether the current document may be saved.
     309
     310Return value:   TRUE if document can be saved in same format
     311                as original, FALSE otherwise.
     312Default
     313return value:   FALSE
     314
     315boolean:        isSaveable();
     316
     317
     318=== saveAs() ===
     319
     320Description:    Saves the current document.
     321
     322Parameters:     filename: name of file to save
     323
     324Return value:   TRUE, if the document was successfully saved,
     325                FALSE otherwise.
     326Default
     327return value:   FALSE
     328
     329Syntax:         saveAs( in string filename );
     330
     331
     332
     333=== isPostScriptExportable() ===
     334
     335Description:    Describes whether the current document may be
     336                exported to PostScript.
     337
     338Return value:   TRUE if document can be exported to
     339                PostScript, FALSE otherwise.
     340Default
     341return value:   FALSE
     342
     343boolean:        isPostScriptExportable();
     344
     345
     346=== exportToPostScript() ===
     347
     348Description:    Create a new postscript file and generate the document to it.
     349
     350Parameters:     filename: the path of the output filename
     351                first_page: the first page to print
     352                last_page: the last page to print
     353                width: the paper width in 1/72 inch
     354                height: the paper height in 1/72 inch
     355                (These values will end up in the DocumentMedia, the
     356                BoundingBox DSC comments, and other places in the
     357                generated PostScript.)
     358                brkExport: pointer to boolean variable which must be checked
     359                during generating postscript, if it's TRUE - interrupt
     360                generation process.
     361
     362Return value:   TRUE if PS document was generated successfully or
     363                generation was interrupted, FALSE otherwise.
     364Default
     365return value:   FALSE
     366
     367Syntax:         exportToPostScript( in string filename,
     368                        in long first_page, in long last_page,
     369                        in double width, in double height,
     370                        inout boolean brkExport );
     371
     372
     373=== isHaveFontInfo() ===
     374
     375Description:    See: getFontInfo().
     376
     377Return value:   TRUE if getFontInfo() can return information about
     378                fonts used in document, FALSE otherwise.
     379Default
     380return value:   FALSE
     381
     382boolean:        isHaveFontInfo();
     383
     384
     385=== getFontInfo() ===
     386
     387Description:    Returns information about fonts used in document.
     388                Returned sequence must be freed with freeFontInfo() when done.
     389
     390Return value:   A pointer to the sequence of LuFontInfo
     391                or NULL if no font information.
     392Default
     393return value:   NULL
     394
     395Note:           SOMMalloc() must be used for all memory allocations.
     396
     397Syntax:         LuFontInfoSequence *getFontInfo();
     398
     399
     400=== freeFontInfo() ===
     401
     402Description:    Frees a sequence of LuFontInfo allocated by
     403                getFontInfo().
     404
     405Parameters:     fonts: A sequence of LuFontInfo
     406
     407
     408void:           freeFontInfo( in LuFontInfoSequence fonts );
     409
     410
     411=== isHaveIndex() ===
     412
     413Description:    Determines if the document has an index associated with it.
     414                See getIndex()
     415
     416Return value:   TRUE if the document has an index, FALSE otherwise.
     417Default
     418return value:   FALSE
     419
     420boolean:        isHaveIndex();
     421
     422
     423=== getIndex() ===
     424
     425Description:    Certain documents have an index associated with them.
     426                This index can be used to help the user navigate the document,
     427                and is similar to a table of contents. Each node in the index will
     428                contain a LuLink which can be displayed to the user.
     429
     430                Here is a simple example of some code that walks the full index:
     431
     432                        void viewTree( int level, LuIndexNode *n )
     433                        {
     434                                if ( n == NULL ) {
     435                                        return;
     436                                }
     437                       
     438                                somLPrintf( level, "title: %s\n", n->getLink(ev)->title );
     439                       
     440                                LuIndexNode *cn = n->getFirstChild( ev );
     441                                while ( cn != NULL ) {
     442                                        viewTree( level + 1, cn );
     443                                        cn = n->getNextChild( ev );
     444                                }
     445                        }
     446
     447Return value:   A new LuIndexNode, which represents an index root,
     448                or NULL, if the document doesn't have an index.
     449Default
     450return value:   NULL
     451
     452Syntax:         LuIndexNode getIndex();
     453
     454
     455=== getDocumentInfo() ===
     456
     457Description:    Returns information about the current document.
     458                Returned sequence must be freed with freeDocumentInfo() when done.
     459
     460Return value:   A pointer to the sequence of LuDocumentInfo
     461                or NULL if no information is available.
     462Default
     463return value:   NULL
     464
     465
     466Syntax:         LuDocumentInfo *getDocumentInfo();
     467
     468
     469
     470=== freeDocumentInfo() ===
     471
     472Description:    Frees a LuDocumentInfo structure allocated by getDocumentInfo().
     473
     474Parameters:     info: LuDocumentInfo structure allocated by getDocumentInfo()
     475
     476void:           freeDocumentInfo( in LuDocumentInfo info );
     477
     478
     479
     480=== getThumbnailSize() ===
     481
     482Description:    Returns TRUE if the page has a thumbnail associated with it. It also
     483                fills the width and height with the those of the thumbnail.
     484                The values of width and height are not changed if no
     485                appropriate thumbnail exists.
     486
     487Parameters:     pagenum: page number
     488                suggested_width: if thumbnail doesn't have a predefined width,
     489                it will be created with suggested_width.
     490                width: value for width
     491                height: value for height
     492
     493Return value:   TRUE, if the page has a thumbnail associated with it, FALSE otherwise.
     494Default
     495return value:   FALSE
     496
     497Syntax:         getThumbnailSize( in long pagenum, in short suggested_width, inout short width, inout short height );
     498
     499
     500=== getThumbnail() ===
     501
     502Description:    Returns pointer to LuPixbuf
     503
     504Parameters:     pagenum: page number
     505                suggested_width: if thumbnail doesn't have a predefined width,
     506                it will be created with suggested_width.
     507
     508Return value:   pointer to LuPixbuf, if page has a thumbnail associated with it,
     509                or NULL.
     510Default
     511return value:   NULL
     512
     513Syntax:         LuPixbuf getThumbnail( in long pagenum, in short suggested_width );
     514
     515
     516
     517=== searchText() ===
     518
     519Description:    Returns a sequence of rectangles for each occurrence of the text
     520                found on the page.
     521                The returned sequence must be freed with freeRectangles()
     522
     523Parameters:     pagenum: page number
     524                text: the text to find (in system encoding)
     525
     526Return value:   A newly allocated LuRectSequence, or NULL if nothing found
     527Default
     528return value:   NULL
     529
     530Note:           SOMMalloc() must be used for all memory allocations.
     531
     532Syntax:         LuRectSequence *searchText( in long pagenum, in string text,
     533                        in boolean caseSensitive, in boolean findBack );
     534
     535
     536=== isCreateFileThumbnail() ===
     537
     538Description:    If this method returns TRUE, then GUI may create thumbnail for
     539                this file and write it into EAs.
     540
     541Return value:   TRUE, if thumbnail may be created, FALSE otherwise.
     542Default
     543return value:   FALSE
     544
     545boolean:        isCreateFileThumbnail();
     546
     547
     548=== isHaveInputFields() ===
     549
     550Description:    Returns TRUE if the document contains input fields, FALSE otherwise.
     551                See: getInputFields().
     552
     553Return value:   TRUE, if the document contains input fields, FALSE otherwise.
     554Default
     555return value:   FALSE
     556
     557boolean:        isHaveInputFields();
     558
     559
     560=== getInputFields() ===
     561
     562Description:    Returns a sequence of LuInputField items that may be used to enter
     563                data into the document.
     564                This sequence must be freed with freeInputFields() when done.
     565
     566Parameters:     pagenum: page number
     567
     568Return value:   A pointer to sequence of valid LuInputField items.
     569Default
     570return value:   A pointer to an empty LuInputFieldSequence.
     571
     572Note:           The returned sequence must be allocated with SOMMalloc(),
     573                each element must be a newly created SOM object.
     574
     575Syntax:         {{{LuInputFieldSequence *getInputFields( in long pagenum );}}}
     576
     577
     578=== freeInputFields() ===
     579
     580Description:    Frees the input field sequence returned by getInputFields().
     581                Subclasses should never override this method.
     582
     583void:           {{{freeInputFields(in LuInputFieldSequence aInputFields);}}}