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

Last change on this file since 367 was 367, checked in by dmik, 11 years ago

Merged bramches/kmk (r294:365) to trunk.

File size: 19.2 KB
Line 
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>
13#include <luifield.idl>
14#include <lutypes.h>
15
16/**
17 * Note: all page numbers is zero-based.
18 */
19
20interface LuDocument : SOMObject
21{
22
23    typedef sequence <LuRectangle> LuRectSequence;
24    typedef sequence <LuLinkMapping> LuLinkMapSequence;
25    typedef sequence <LuFontInfo> LuFontInfoSequence;
26    typedef sequence <LuInputField> LuInputFieldSequence;
27    typedef somMToken asynchCallbackFn;
28
29    /**
30     * loadFile
31     * filename: filename of the file to load
32     * password: password to unlock the file with, or NULL
33     * errorCode: Return location for an error code, or NULL
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.
39     * Default return value: FALSE
40     *
41     * Note: error string allocated using SOMMalloc(),
42     *       use SOMFree() to free.
43     **/
44    boolean loadFile( in string filename, in string password,
45                      out long errorCode, inout string error );
46
47    /**
48     * getBpp
49     *
50     * Return value: Number of bytes per pixel used for draw.
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
55     **/
56    short getBpp();
57
58    /**
59     * isScalable
60     *
61     * (See renderPageToPixbuf(), scale)
62     *
63     * Return value: TRUE if document scalable, FALSE otherwise.
64     * Default return value: FALSE
65     **/
66    boolean isScalable();
67
68
69    /**
70     * isFixedImage
71     *
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    /**
84     * isRotable
85     *
86     * (See renderPageToPixbuf(), rotation)
87     *
88     * Return value: TRUE if document can be rotated, FALSE otherwise.
89     * Default return value: FALSE
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
100     * Default return value: 0
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
128     *           allowed values is 0, 90, 180, 270
129     *        (if isRotable() is FALSE, rotation ignored and assumed 0)
130     * pixbuf: pixbuf to render into
131     * errorCode: Return location for an error/warning code, or NULL
132     * error: Return location for an error/warning, or NULL
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     **/
138    boolean renderPageToPixbuf( in long pagenum, in long src_x, in long src_y,
139                                in long src_width, in long src_height,
140                                in double scale, in long rotation,
141                                in LuPixbuf pixbuf,
142                                out long errorCode, inout string error );
143
144
145    /**
146     * isAsynchRenderingSupported
147     *
148     * See renderPageToPixbufAsynch()
149     *
150     * Return value: TRUE if document can be rendered asynchronously.
151     * Default return value: FALSE
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 );
163     * errorCode: Return location for an error/warning code, or NULL
164     * error: Return location for an error/warning, or NULL
165     *
166     * Note: you must implement renderPageToPixbuf() also, as
167     *       it used during printing.
168     **/
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,
173                   in somToken fndata,
174                   out long errorCode, inout string error );
175
176
177    /**
178     * isRenderIntoPS
179     *
180     * See renderPageToPS()
181     *
182     * Return value: TRUE if document will render directly into
183     *               presentation space using renderPageToPS().
184     *
185     * Note: You may not implement renderPageToPixbuf() if
186     *       isRenderIntoPS() is TRUE.
187     *
188     * Default return value: FALSE
189     **/
190    boolean isRenderIntoPS();
191
192
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
203     *           allowed values is 0, 90, 180, 270
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
207     * errorCode: Return location for an error/warning code, or NULL
208     * error: Return location for an error/warning, or NULL
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     **/
214    boolean renderPageToPS( in long pagenum, in long src_x, in long src_y,
215                   in long src_width, in long src_height,
216                   in double scale, in long rotation,
217                   in unsigned long hps, in somMToken rect,
218                   out long errorCode, inout string error );
219
220
221    /**
222     * isHaveText
223     *
224     * See getSelectionRectangles(), searchText()
225     *
226     * Return value: TRUE if document contains text, which
227     *               can be selected by user, searched, etc,
228     *               FALSE otherwise.
229     * Default return value: FALSE
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
246     * Default return value: NULL
247     *
248     * Note: SOMMalloc() must be used for all memory allocations.
249     **/
250    LuRectSequence *getSelectionRectangles( in long pagenum,
251                                            in LuRectangle selection );
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
276     * Default return value: NULL
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.
288     * Default return value: FALSE
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     *
301     * Return value: A pointer to sequence of LuLinkMapping.
302     *
303     * Note: SOMMalloc() must be used for all memory allocations.
304     * Default return value: pointer to empty LuLinkMapSequence
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.
324     * Default return value: FALSE
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.
337     * Default return value: FALSE
338     **/
339    boolean saveAs( in string filename );
340
341
342    /**
343     * isPostScriptExportable
344     *
345     * Return value: TRUE if document can be exported to
346     *               PostScript, FALSE otherwise.
347     * Default return value: FALSE
348     **/
349    boolean isPostScriptExportable();
350
351
352    /**
353     * exportToPostScript
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)
362     * brkExport: pointer to boolean variable which must be checked
363     *            during generating postscript, if it's TRUE - interrupt
364     *            generation process.
365     *
366     * Create a new postscript file and render document to.
367     * Return value: TRUE if PS document was generated successfully or
368     *               generation was interrupted, FALSE otherwise.
369     * Default return value: FALSE
370     **/
371    boolean exportToPostScript( in string filename,
372                     in long first_page, in long last_page,
373                     in double width, in double height,
374                     inout boolean brkExport );
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.
384     * Default return value: FALSE
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.
399     * Default return value: NULL
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.
422     * Default return value: FALSE
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.
455     * Default return value: NULL
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.
491     * Default return value: FALSE
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.
506     * Default return value: NULL
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
522     * Default return value: NULL
523     *
524     * Note: SOMMalloc() must be used for all memory allocations.
525     **/
526    LuRectSequence *searchText( in long pagenum, in string text, in boolean caseSensitive );
527
528
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
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     *
561     * Note: The returned sequence must be allocated with SOMMalloc(),
562     * each element must be a newly created SOM object.
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
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
579#ifdef __SOMIDL__
580
581    implementation
582    {
583        releaseorder: loadFile, getBpp, isScalable, isRotable,
584                      getPageCount, getPageSize, renderPageToPixbuf,
585                      isAsynchRenderingSupported, renderPageToPixbufAsynch,
586                      isRenderIntoPS, renderPageToPS,
587                      isHaveText, getSelectionRectangles, freeRectangles,
588                      getText, isHaveLinks, getLinkMapping, freeLinkMapping,
589                      isSaveable, saveAs,
590                      isPostScriptExportable, exportToPostScript,
591                      isHaveFontInfo, getFontInfo, freeFontInfo,
592                      isHaveIndex, getIndex, getDocumentInfo,
593                      freeDocumentInfo, getThumbnailSize, getThumbnail,
594                      searchText, isFixedImage, isCreateFileThumbnail,
595                      isHaveInputFields, getInputFields, freeInputFields;
596
597
598        somDefaultInit: override, init;
599
600        freeRectangles: procedure, noself;
601        freeLinkMapping: procedure, noself;
602        freeFontInfo: procedure, noself;
603        freeDocumentInfo: procedure, noself;
604        freeInputFields: procedure, noself;
605
606        passthru C_h_before =  ""
607            ""
608            "#include <lutypes.h>"
609            "#include <lupixbuf.h>"
610            "#include <luifield.h>"
611            "#include <luinode.h>"
612            "";
613
614        passthru C_xh_before =  ""
615            ""
616            "#include <lutypes.h>"
617            "#include <lupixbuf.xh>"
618            "#include <luifield.xh>"
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.