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

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

allow printing in descending order (closes #88), small interface fixes (closes #89)

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