source: trunk/Lucide/plugins/ludoc/ludoc.idl @ 542

Last change on this file since 542 was 450, checked in by Silvan Scherrer, 11 years ago

fixes ticket:190

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