1 /* poppler-action.h: glib interface to poppler
2  * Copyright (C) 2004, Red Hat, Inc.
3  *
4  * This program is free software; you can redistribute it and/or modify
5  * it under the terms of the GNU General Public License as published by
6  * the Free Software Foundation; either version 2, or (at your option)
7  * any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software
16  * Foundation, Inc., 51 Franklin Street - Fifth Floor, Boston, MA 02110-1301, USA.
17  */
18 
19 #ifndef __POPPLER_ACTION_H__
20 #define __POPPLER_ACTION_H__
21 
22 #include <glib-object.h>
23 #include "poppler.h"
24 
25 G_BEGIN_DECLS
26 
27 /**
28  * PopplerActionType:
29  * @POPPLER_ACTION_UNKNOWN: unknown action
30  * @POPPLER_ACTION_NONE: no action specified
31  * @POPPLER_ACTION_GOTO_DEST: go to destination
32  * @POPPLER_ACTION_GOTO_REMOTE: go to destination in another document
33  * @POPPLER_ACTION_LAUNCH: launch app (or open document)
34  * @POPPLER_ACTION_URI: URI
35  * @POPPLER_ACTION_NAMED: predefined action
36  * @POPPLER_ACTION_MOVIE: play movies. Since 0.14
37  * @POPPLER_ACTION_RENDITION: play multimedia content. Since 0.14
38  * @POPPLER_ACTION_OCG_STATE: state of layer. Since 0.14
39  * @POPPLER_ACTION_JAVASCRIPT: Javascript. Since 0.18
40  * @POPPLER_ACTION_RESET_FORM: resets form. Since 0.90
41  *
42  * Action types
43  */
44 typedef enum
45 {
46     POPPLER_ACTION_UNKNOWN, /* unknown action */
47     POPPLER_ACTION_NONE, /* no action specified */
48     POPPLER_ACTION_GOTO_DEST, /* go to destination */
49     POPPLER_ACTION_GOTO_REMOTE, /* go to destination in new file */
50     POPPLER_ACTION_LAUNCH, /* launch app (or open document) */
51     POPPLER_ACTION_URI, /* URI */
52     POPPLER_ACTION_NAMED, /* named action*/
53     POPPLER_ACTION_MOVIE, /* movie action */
54     POPPLER_ACTION_RENDITION, /* rendition action */
55     POPPLER_ACTION_OCG_STATE, /* Set-OCG-State action */
56     POPPLER_ACTION_JAVASCRIPT, /* Javascript action */
57     POPPLER_ACTION_RESET_FORM /* ResetForm action */
58 } PopplerActionType;
59 
60 /**
61  * PopplerDestType:
62  * @POPPLER_DEST_UNKNOWN: unknown destination
63  * @POPPLER_DEST_XYZ: go to page with coordinates (left, top)
64  * positioned at the upper-left corner of the window and the contents of
65  * the page magnified by the factor zoom
66  * @POPPLER_DEST_FIT: go to page with its contents magnified just
67  * enough to fit the entire page within the window both horizontally and
68  * vertically
69  * @POPPLER_DEST_FITH: go to page with the vertical coordinate top
70  * positioned at the top edge of the window and the contents of the page
71  * magnified just enough to fit the entire width of the page within the window
72  * @POPPLER_DEST_FITV: go to page with the horizontal coordinate
73  * left positioned at the left edge of the window and the contents of the
74  * page magnified just enough to fit the entire height of the page within the window
75  * @POPPLER_DEST_FITR: go to page with its contents magnified just
76  * enough to fit the rectangle specified by the coordinates left, bottom,
77  * right, and top entirely within the window both horizontally and vertically
78  * @POPPLER_DEST_FITB: go to page with its contents magnified just enough to fit
79  * its bounding box entirely within the window both horizontally and vertically
80  * @POPPLER_DEST_FITBH: go to page with the vertical
81  * coordinate top positioned at the top edge of the window and the
82  * contents of the page magnified just enough to fit the entire width of its
83  * bounding box within the window
84  * @POPPLER_DEST_FITBV: go to page with the horizontal
85  * coordinate left positioned at the left edge of the window and the
86  * contents of the page magnified just enough to fit the entire height of its
87  * bounding box within the window
88  * @POPPLER_DEST_NAMED: got to page specified by a name. See poppler_document_find_dest()
89  *
90  * Destination types
91  */
92 typedef enum
93 {
94     POPPLER_DEST_UNKNOWN,
95     POPPLER_DEST_XYZ,
96     POPPLER_DEST_FIT,
97     POPPLER_DEST_FITH,
98     POPPLER_DEST_FITV,
99     POPPLER_DEST_FITR,
100     POPPLER_DEST_FITB,
101     POPPLER_DEST_FITBH,
102     POPPLER_DEST_FITBV,
103     POPPLER_DEST_NAMED
104 } PopplerDestType;
105 
106 /**
107  * PopplerActionMovieOperation:
108  * @POPPLER_ACTION_MOVIE_PLAY: play movie
109  * @POPPLER_ACTION_MOVIE_PAUSE: pause playing movie
110  * @POPPLER_ACTION_MOVIE_RESUME: resume paused movie
111  * @POPPLER_ACTION_MOVIE_STOP: stop playing movie
112  *
113  * Movie operations
114  *
115  * Since: 0.14
116  */
117 typedef enum
118 {
119     POPPLER_ACTION_MOVIE_PLAY,
120     POPPLER_ACTION_MOVIE_PAUSE,
121     POPPLER_ACTION_MOVIE_RESUME,
122     POPPLER_ACTION_MOVIE_STOP
123 } PopplerActionMovieOperation;
124 
125 /**
126  * PopplerActionLayerAction:
127  * @POPPLER_ACTION_LAYER_ON: set layer visibility on
128  * @POPPLER_ACTION_LAYER_OFF: set layer visibility off
129  * @POPPLER_ACTION_LAYER_TOGGLE: reverse the layer visibility state
130  *
131  * Layer actions
132  *
133  * Since: 0.14
134  */
135 typedef enum
136 {
137     POPPLER_ACTION_LAYER_ON,
138     POPPLER_ACTION_LAYER_OFF,
139     POPPLER_ACTION_LAYER_TOGGLE
140 } PopplerActionLayerAction;
141 
142 /* Define the PopplerAction types */
143 typedef struct _PopplerActionAny PopplerActionAny;
144 typedef struct _PopplerActionGotoDest PopplerActionGotoDest;
145 typedef struct _PopplerActionGotoRemote PopplerActionGotoRemote;
146 typedef struct _PopplerActionLaunch PopplerActionLaunch;
147 typedef struct _PopplerActionUri PopplerActionUri;
148 typedef struct _PopplerActionNamed PopplerActionNamed;
149 typedef struct _PopplerActionMovie PopplerActionMovie;
150 typedef struct _PopplerActionRendition PopplerActionRendition;
151 typedef struct _PopplerActionOCGState PopplerActionOCGState;
152 typedef struct _PopplerActionJavascript PopplerActionJavascript;
153 typedef struct _PopplerActionResetForm PopplerActionResetForm;
154 
155 /**
156  * PopplerDest:
157  * @type: type of destination
158  * @page_num: page number
159  * @left: left coordinate
160  * @bottom: bottom coordinate
161  * @right: right coordinate
162  * @top: top coordinate
163  * @zoom: scale factor
164  * @named_dest: name of the destination (#POPPLER_DEST_NAMED only)
165  * @change_left: whether left coordinate should be changed
166  * @change_top: whether top coordinate should be changed
167  * @change_zoom: whether scale factor should be changed
168  *
169  * Data structure for holding a destination
170  *
171  * Note that @named_dest is the string representation of the named
172  * destination. This is the right form to pass to poppler functions,
173  * e.g. poppler_document_find_dest(), but to get the destination as
174  * it appears in the PDF itself, you need to convert it to a bytestring
175  * with poppler_named_dest_to_bytestring() first.
176  * Also note that @named_dest does not have a defined encoding and
177  * is not in a form suitable to be displayed to the user.
178  */
179 struct _PopplerDest
180 {
181     PopplerDestType type;
182 
183     int page_num;
184     double left;
185     double bottom;
186     double right;
187     double top;
188     double zoom;
189     gchar *named_dest;
190     guint change_left : 1;
191     guint change_top : 1;
192     guint change_zoom : 1;
193 };
194 
195 /**
196  * PopplerActionLayer:
197  * @action: a #PopplerActionLayerAction
198  * @layers: (element-type PopplerLayer): list of #PopplerLayer<!-- -->s
199  *
200  * Action to perform over a list of layers
201  */
202 struct _PopplerActionLayer
203 {
204     PopplerActionLayerAction action;
205     GList *layers;
206 };
207 
208 /**
209  * PopplerActionAny:
210  * @type: action type
211  * @title: action title
212  *
213  * Fields common to all #PopplerAction<!-- -->s
214  */
215 struct _PopplerActionAny
216 {
217     PopplerActionType type;
218     gchar *title;
219 };
220 
221 /**
222  * PopplerActionGotoDest:
223  * @type: action type (%POPPLER_ACTION_GOTO_DEST)
224  * @title: action title
225  * @dest: destination
226  *
227  * Go to destination
228  */
229 struct _PopplerActionGotoDest
230 {
231     PopplerActionType type;
232     gchar *title;
233 
234     PopplerDest *dest;
235 };
236 
237 /**
238  * PopplerActionGotoRemote:
239  * @type: action type (%POPPLER_ACTION_GOTO_REMOTE)
240  * @title: action title
241  * @file_name: file name
242  * @dest: destination
243  *
244  * Go to destination in another document
245  */
246 struct _PopplerActionGotoRemote
247 {
248     PopplerActionType type;
249     gchar *title;
250 
251     gchar *file_name;
252     PopplerDest *dest;
253 };
254 
255 /**
256  * PopplerActionLaunch:
257  * @type: action type (%POPPLER_ACTION_LAUNCH)
258  * @title: action title
259  * @file_name: file name
260  * @params: parameters
261  *
262  * Launch app (or open document)
263  */
264 struct _PopplerActionLaunch
265 {
266     PopplerActionType type;
267     gchar *title;
268 
269     gchar *file_name;
270     gchar *params;
271 };
272 
273 /**
274  * PopplerActionUri:
275  * @type: action type (%POPPLER_ACTION_URI)
276  * @title: action title
277  * @uri: URI
278  *
279  * URI
280  */
281 struct _PopplerActionUri
282 {
283     PopplerActionType type;
284     gchar *title;
285 
286     char *uri;
287 };
288 
289 /**
290  * PopplerActionNamed:
291  * @type: action type (%POPPLER_ACTION_NAMED)
292  * @title: action title
293  * @named_dest: named destination
294  *
295  * Predefined action
296  */
297 struct _PopplerActionNamed
298 {
299     PopplerActionType type;
300     gchar *title;
301 
302     gchar *named_dest;
303 };
304 
305 /**
306  * PopplerActionMovie:
307  * @type: action type (%POPPLER_ACTION_MOVIE)
308  * @title: action title
309  * @operation: operation
310  * @movie: movie
311  *
312  * Play movies.
313  *
314  * Since: 0.14
315  */
316 struct _PopplerActionMovie
317 {
318     PopplerActionType type;
319     gchar *title;
320 
321     PopplerActionMovieOperation operation;
322     PopplerMovie *movie;
323 };
324 
325 /**
326  * PopplerActionRendition:
327  * @type: action type (%POPPLER_ACTION_RENDITION)
328  * @title: action title
329  * @op: operation
330  * @media: media
331  *
332  * Play multimedia content.
333  *
334  * Since: 0.14
335  */
336 struct _PopplerActionRendition
337 {
338     PopplerActionType type;
339     gchar *title;
340 
341     gint op;
342     PopplerMedia *media;
343 };
344 
345 /**
346  * PopplerActionOCGState:
347  * @type: action type (%POPPLER_ACTION_OCG_STATE)
348  * @title: action title
349  * @state_list: (element-type PopplerActionLayer): list of #PopplerActionLayer<!-- -->s
350  *
351  * State of layer.
352  *
353  * Since: 0.14
354  */
355 struct _PopplerActionOCGState
356 {
357     PopplerActionType type;
358     gchar *title;
359 
360     GList *state_list;
361 };
362 
363 /**
364  * PopplerActionJavascript:
365  * @type: action type (%POPPLER_ACTION_JAVASCRIPT)
366  * @title: action title
367  * @script: javascript
368  *
369  * Javascript.
370  *
371  * Since: 0.18
372  */
373 struct _PopplerActionJavascript
374 {
375     PopplerActionType type;
376     gchar *title;
377 
378     gchar *script;
379 };
380 
381 /**
382  * PopplerActionResetForm:
383  * @type: action type (%POPPLER_ACTION_RESET_FORM)
384  * @title: action title
385  * @fields: (element-type utf8) (nullable): list of field names to
386  *   reset / retain
387  * @exclude: whether to reset all but the listed fields
388  *
389  * Resets some or all fields within a PDF form.
390  *
391  * The default behavior resets only the list of @fields, but setting
392  * @exclude to %TRUE will cause the action to reset all fields but those
393  * listed. Providing an empty list of fields resets the entire form.
394  *
395  * Since: 0.90
396  */
397 struct _PopplerActionResetForm
398 {
399     PopplerActionType type;
400     gchar *title;
401 
402     GList *fields;
403     gboolean exclude;
404 };
405 
406 /**
407  * PopplerAction:
408  *
409  * A generic wrapper for actions that exposes only #PopplerActionType.
410  */
411 union _PopplerAction {
412     PopplerActionType type;
413     PopplerActionAny any;
414     PopplerActionGotoDest goto_dest;
415     PopplerActionGotoRemote goto_remote;
416     PopplerActionLaunch launch;
417     PopplerActionUri uri;
418     PopplerActionNamed named;
419     PopplerActionMovie movie;
420     PopplerActionRendition rendition;
421     PopplerActionOCGState ocg_state;
422     PopplerActionJavascript javascript;
423     PopplerActionResetForm reset_form;
424 };
425 
426 #define POPPLER_TYPE_ACTION (poppler_action_get_type())
427 #define POPPLER_ACTION(obj) (G_TYPE_CHECK_INSTANCE_CAST((obj), POPPLER_TYPE_ACTION, PopplerAction))
428 
429 POPPLER_PUBLIC
430 GType poppler_action_get_type(void) G_GNUC_CONST;
431 
432 POPPLER_PUBLIC
433 void poppler_action_free(PopplerAction *action);
434 POPPLER_PUBLIC
435 PopplerAction *poppler_action_copy(PopplerAction *action);
436 
437 #define POPPLER_TYPE_DEST (poppler_dest_get_type())
438 POPPLER_PUBLIC
439 GType poppler_dest_get_type(void) G_GNUC_CONST;
440 
441 POPPLER_PUBLIC
442 void poppler_dest_free(PopplerDest *dest);
443 POPPLER_PUBLIC
444 PopplerDest *poppler_dest_copy(PopplerDest *dest);
445 
446 POPPLER_PUBLIC
447 char *poppler_named_dest_from_bytestring(const guint8 *data, gsize length);
448 
449 POPPLER_PUBLIC
450 guint8 *poppler_named_dest_to_bytestring(const char *name, gsize *length);
451 
452 G_END_DECLS
453 
454 #endif /* __POPPLER_GLIB_H__ */
455