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

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

First import

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