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

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

poppler updated to version 0.5.2, also needed changes to be compatible with new poppler

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