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

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

more comments, new method isFixedImage(), fixed keyboard selection of printer in printer dialog

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