1/* This file is part of Libspectre.
2 *
3 * Copyright (C) 2007 Albert Astals Cid <aacid@kde.org>
4 * Copyright (C) 2007 Carlos Garcia Campos <carlosgc@gnome.org>
5 *
6 * Libspectre is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2, or (at your option)
9 * any later version.
10 *
11 * Libspectre is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
19 */
20
21#ifndef SPECTRE_DOCUMENT_H
22#define SPECTRE_DOCUMENT_H
23
24#include <libspectre/spectre-macros.h>
25#include <libspectre/spectre-status.h>
26#include <libspectre/spectre-page.h>
27
28SPECTRE_BEGIN_DECLS
29
30/*! This is the object that represents a PostScript document. */
31typedef struct SpectreDocument SpectreDocument;
32
33/*! Creates a document */
34SpectreDocument *spectre_document_new (void);
35
36/*! Loads a the given file into the document. This function can fail
37 @param document the document where the file will be loaded
38 @param filename the file to loa
39 @see spectre_document_status
40*/
41void spectre_document_load (SpectreDocument *document,
42 const char *filename);
43
44/*! Returns the document status
45 @param document the document whose status will be returned
46*/
47SpectreStatus spectre_document_status (SpectreDocument *document);
48
49/*! Frees the document
50 @param document the document that will be freed
51*/
52void spectre_document_free (SpectreDocument *document);
53
54/*! Returns the number of pages of the document. This function can fail
55 @param document the document whose pages number will be returned
56 @see spectre_document_status
57*/
58unsigned int spectre_document_get_n_pages (SpectreDocument *document);
59
60/*! Returns the orientation of the document. This function can fail
61 @param document the document whose orientation will be returned
62 @see spectre_document_status
63*/
64SpectreOrientation spectre_document_get_orientation (SpectreDocument *document);
65
66/*! Returns the title of the document. It returns a null const char * if
67 the document specifies no title. This function can fail
68 @param document the document whose title will be returned
69 @see spectre_document_status
70*/
71const char *spectre_document_get_title (SpectreDocument *document);
72
73/*! Returns the creator of the document. It returns a null const char * if
74 the document specifies no creator. This function can fail
75 @param document the document whose creator will be returned
76 @see spectre_document_status
77*/
78const char *spectre_document_get_creator (SpectreDocument *document);
79
80/*! Returns the for of the document. It returns a null const char * if
81 the document specifies no for. This function can fail
82 @param document the document whose for will be returned
83 @see spectre_document_status
84*/
85const char *spectre_document_get_for (SpectreDocument *document);
86
87/*! Returns the creation date of the document. The date is copied verbatim from
88 the document, so no format can be assumed on it. It returns a null const char * if
89 the document specifies no creation date. This function can fail
90 @param document the document whose creation date will be returned
91 @see spectre_document_status
92*/
93const char *spectre_document_get_creation_date (SpectreDocument *document);
94
95/*! Returns the format of the document. This function can fail
96 @param document the document whose format will be returned
97 @see spectre_document_status
98*/
99const char *spectre_document_get_format (SpectreDocument *document);
100
101/*! Returns if the document is a Encapsulated PostScript file. This function can fail
102 @param document the document to query
103 @see spectre_document_status
104*/
105int spectre_document_is_eps (SpectreDocument *document);
106
107/*! Returns the PostScript language level of the document. It returns 0 if no
108 language level was defined on the file. This function can fail
109 @param document the document whose language level will be returned
110 @see spectre_document_status
111*/
112unsigned int spectre_document_get_language_level (SpectreDocument *document);
113
114/*! Returns a page of the document. This function can fail
115 @param document the document whose page will be returned
116 @param page_index the page index to get. First page has index 0.
117 @see spectre_document_status
118*/
119SpectrePage *spectre_document_get_page (SpectreDocument *document,
120 unsigned int page_index);
121
122/*! Returns a page of the document referenced by label. This function can fail
123 @param document the document whose page will be returned
124 @param label the label of the page to get.
125 @see spectre_document_status
126*/
127SpectrePage *spectre_document_get_page_by_label (SpectreDocument *document,
128 const char *label);
129
130/*! Convenient function for rendering documents with no pages, tipically eps.
131 When used with multi-page documents the first page will be rendered.
132 @param document the document to render
133 @rc the rendering context specifying how the document has to be rendered
134 @width the page width will be returned here, or NULL
135 @height the page height will be returned here, or NULL
136 @page_data a pointer that will point to the image data
137 @row_length the length of an image row will be returned here
138 @see spectre_document_render_full
139*/
140void spectre_document_render_full (SpectreDocument *document,
141 SpectreRenderContext *rc,
142 unsigned char **page_data,
143 int *row_length);
144
145/*! Convenient function for rendering documents with no pages, tipically eps.
146 Document will be rendered with the default options, use spectre_document_render_full
147 if you want to change any of them.
148 When used with multi-page documents the first page will be rendered.
149 @param document the document to render
150 @width the page width will be returned here, or NULL
151 @height the page height will be returned here, or NULL
152 @page_data a pointer that will point to the image data
153 @row_length the length of an image row will be returned here
154 @see spectre_document_render_full
155*/
156void spectre_document_render (SpectreDocument *document,
157 unsigned char **page_data,
158 int *row_length);
159
160/* Convenient function for getting the page size of documents with no pages, tipically eps.
161 When used with multi-page documents the size of the first page will be returned.
162 @param document the document whose page will be returned
163 @width the page width will be returned here, or NULL
164 @height the page height will be returned here, or NULL
165*/
166void spectre_document_get_page_size (SpectreDocument *document,
167 int *width,
168 int *height);
169
170/*! Save document as filename. This function can fail
171 @param document the document that will be saved
172 @param filename the path where document will be saved
173 @see spectre_document_status
174*/
175void spectre_document_save (SpectreDocument *document,
176 const char *filename);
177/* Save document as a pdf document. This function can fail
178 @param document the document that will be saved
179 @param filename the path where document will be saved as pdf
180 @see spectre_document_status
181*/
182void spectre_document_save_to_pdf (SpectreDocument *document,
183 const char *filename);
184SPECTRE_END_DECLS
185
186#endif /* SPECTRE_DOCUMENT_H */
187