source: trunk/Lucide/SOURCE/plugins/ludoc/ludoc.idl @ 155

Last change on this file since 155 was 155, checked in by Eugene Romanenko, 15 years ago

extended error reporting

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