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

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

postscript printing updates, ability to abort PS generation, gcc support changes

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