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

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

Prevent getLinkMapping() call on every redraw if no links on page.

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     *
290     * Note: SOMMalloc() must be used for all memory allocations.
291     * Default return value: pointer to empty LuLinkMapSequence
292     **/
293    LuLinkMapSequence *getLinkMapping( in long pagenum );
294
295
296    /**
297     * freeLinkMapping
298     * mapping: A sequence of LuLinkMapping
299     *
300     * Frees a sequence of LuLinkMapping allocated by
301     * getLinkMapping().
302     **/
303    void freeLinkMapping( in LuLinkMapSequence mapping );
304
305
306    /**
307     * isSaveable
308     *
309     * Return value: TRUE if document can be saved in same format
310     *               as original, FALSE otherwise.
311     * Default return value: FALSE
312     **/
313    boolean isSaveable();
314
315
316    /**
317     * saveAs
318     * filename: name of file to save
319     *
320     * Saves document.
321     *
322     * Return value: TRUE, if the document was successfully saved,
323     *               FALSE otherwise.
324     * Default return value: FALSE
325     **/
326    boolean saveAs( in string filename );
327
328
329    /**
330     * isPostScriptExportable
331     *
332     * Return value: TRUE if document can be exported to
333     *               PostScript, FALSE otherwise.
334     * Default return value: FALSE
335     **/
336    boolean isPostScriptExportable();
337
338
339    /**
340     * exportToPostScript
341     * filename: the path of the output filename
342     * first_page: the first page to print
343     * last_page: the last page to print
344     * width: the paper width in 1/72 inch
345     * height: the paper height in 1/72 inch
346     *        (These values will end up in the DocumentMedia, the
347     *        BoundingBox DSC comments and other places in the
348     *        generated PostScript)
349     * brkExport: pointer to boolean variable which must be checked
350     *            during generating postscript, if it's TRUE - interrupt
351     *            generation process.
352     *
353     * Create a new postscript file and render document to.
354     * Return value: TRUE if PS document was generated successfully or
355     *               generation was interrupted, FALSE otherwise.
356     * Default return value: FALSE
357     **/
358    boolean exportToPostScript( in string filename,
359                     in long first_page, in long last_page,
360                     in double width, in double height,
361                     inout boolean brkExport );
362
363
364    /**
365     * isHaveFontInfo
366     *
367     * See getFontInfo()
368     *
369     * Return value: TRUE if getFontInfo() can return information about
370     *               fonts used in document, FALSE otherwise.
371     * Default return value: FALSE
372     **/
373    boolean isHaveFontInfo();
374
375
376    /**
377     * getFontInfo
378     *
379     * Returns information about fonts used in document.
380     *
381     * Return value: A pointer to sequence of LuFontInfo
382     *               or NULL if no font information.
383     *
384     * Returned sequence must be freed with freeFontInfo() when done.
385     * Note: SOMMalloc() must be used for all memory allocations.
386     * Default return value: NULL
387     **/
388    LuFontInfoSequence *getFontInfo();
389
390
391    /**
392     * freeFontInfo
393     * fonts: A sequence of LuFontInfo
394     *
395     * Frees a sequence of LuFontInfo allocated by
396     * getFontInfo().
397     **/
398    void freeFontInfo( in LuFontInfoSequence fonts );
399
400
401    /**
402     * isHaveIndex
403     *
404     * Determines if document have an index associated with it.
405     *
406     * See getIndex()
407     *
408     * Return value: TRUE if document have index, FALSE otherwise.
409     * Default return value: FALSE
410     **/
411    boolean isHaveIndex();
412
413
414    /**
415     * getIndex
416     *
417     * Certain documents have an index associated with them.
418     * This index can be used to help the user navigate the document,
419     * and is similar to a table of contents. Each node in the index will
420     * contain a LuLink that can be displayed to the user.
421     *
422     * Here is a simple example of some code that walks the full index:
423     *
424     * void viewTree( int level, LuIndexNode *n )
425     * {
426     *     if ( n == NULL ) {
427     *         return;
428     *     }
429     *
430     *     somLPrintf( level, "title: %s\n", n->getLink(ev)->title );
431     *
432     *     LuIndexNode *cn = n->getFirstChild( ev );
433     *     while ( cn != NULL )
434     *     {
435     *         viewTree( level + 1, cn );
436     *         cn = n->getNextChild( ev );
437     *     }
438     * }
439     *
440     * Return value: a new LuIndexNode, which represents an index root,
441     *               or NULL, if document doesn't have an index.
442     * Default return value: NULL
443     **/
444    LuIndexNode getIndex();
445
446
447    /**
448     * getDocumentInfo
449     *
450     * Return value: a new LuDocumentInfo.
451     **/
452    LuDocumentInfo *getDocumentInfo();
453
454
455    /**
456     * freeDocumentInfo
457     * info: LuDocumentInfo structure allocated by getDocumentInfo()
458     *
459     * Frees a LuDocumentInfo structure allocated by getDocumentInfo().
460     **/
461    void freeDocumentInfo( in LuDocumentInfo info );
462
463
464    /**
465     * getThumbnailSize
466     * pagenum: page number
467     * suggested_width: if thumbnail doesn't have predefined width,
468     *                  it will be created with suggested_width.
469     * width: return location for width
470     * height: return location for height
471     *
472     * Returns TRUE if page has a thumbnail associated with it. It also
473     * fills in width and height with the width and height of the
474     * thumbnail. The values of width and height are not changed if no
475     * appropriate thumbnail exists.
476     *
477     * Return value: TRUE, if page has a thumbnail associated with it.
478     * Default return value: FALSE
479     **/
480    boolean getThumbnailSize( in long pagenum, in short suggested_width, inout short width, inout short height );
481
482
483    /**
484     * getThumbnail
485     * pagenum: page number
486     * suggested_width: if thumbnail doesn't have predefined width,
487     *                  it will be created with suggested_width.
488     *
489     * Returns pointer to LuPixbuf
490     *
491     * Return value: pointer to LuPixbuf, if page has a thumbnail associated with it
492     *               or NULL.
493     * Default return value: NULL
494     **/
495    LuPixbuf getThumbnail( in long pagenum, in short suggested_width );
496
497
498    /**
499     * searchText
500     * pagenum: page number
501     * text: the text to search for (in system encoding)
502     *
503     * Returns a sequence of rectangles for each occurance of the text
504     * found on the page.
505     * The returned sequence must be freed with freeRectangles()
506     *
507     * Return value: a newly allocated LuRectSequence, or NULL if
508     *               nothing found
509     * Default return value: NULL
510     *
511     * Note: SOMMalloc() must be used for all memory allocations.
512     **/
513    LuRectSequence *searchText( in long pagenum, in string text, in boolean caseSensitive );
514
515
516#ifdef __SOMIDL__
517
518    implementation
519    {
520        releaseorder: loadFile, getBpp, isScalable, isRotable,
521                      getPageCount, getPageSize, renderPageToPixbuf,
522                      isAsynchRenderingSupported, renderPageToPixbufAsynch,
523                      isRenderIntoPS, renderPageToPS,
524                      isHaveText, getSelectionRectangles, freeRectangles,
525                      getText, isHaveLinks, getLinkMapping, freeLinkMapping,
526                      isSaveable, saveAs,
527                      isPostScriptExportable, exportToPostScript,
528                      isHaveFontInfo, getFontInfo, freeFontInfo,
529                      isHaveIndex, getIndex, getDocumentInfo,
530                      freeDocumentInfo, getThumbnailSize, getThumbnail,
531                      searchText, isFixedImage;
532
533
534        somDefaultInit: override, init;
535
536        freeRectangles: procedure, noself;
537        freeLinkMapping: procedure, noself;
538        freeFontInfo: procedure, noself;
539        freeDocumentInfo: procedure, noself;
540
541
542        passthru C_h_before =  ""
543            ""
544            "#include <lutypes.h>"
545            "#include <lupixbuf.h>"
546            "#include <luinode.h>"
547            "";
548
549        passthru C_xh_before =  ""
550            ""
551            "#include <lutypes.h>"
552            "#include <lupixbuf.xh>"
553            "#include <luinode.xh>"
554            "";
555
556    };
557
558#endif // __SOMIDL__
559
560};
561
562#endif // ludoc_idl
563
Note: See TracBrowser for help on using the repository browser.