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
25G_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 */
44typedef 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 */
92typedef 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 */
117typedef 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 */
135typedef 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 */
143typedef struct _PopplerActionAny PopplerActionAny;
144typedef struct _PopplerActionGotoDest PopplerActionGotoDest;
145typedef struct _PopplerActionGotoRemote PopplerActionGotoRemote;
146typedef struct _PopplerActionLaunch PopplerActionLaunch;
147typedef struct _PopplerActionUri PopplerActionUri;
148typedef struct _PopplerActionNamed PopplerActionNamed;
149typedef struct _PopplerActionMovie PopplerActionMovie;
150typedef struct _PopplerActionRendition PopplerActionRendition;
151typedef struct _PopplerActionOCGState PopplerActionOCGState;
152typedef struct _PopplerActionJavascript PopplerActionJavascript;
153typedef 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 */
179struct _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 */
202struct _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 */
215struct _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 */
229struct _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 */
246struct _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 */
264struct _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 */
281struct _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 */
297struct _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 */
316struct _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 */
336struct _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 */
355struct _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 */
373struct _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 */
397struct _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 */
411union _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
429POPPLER_PUBLIC
430GType poppler_action_get_type(void) G_GNUC_CONST;
431
432POPPLER_PUBLIC
433void poppler_action_free(PopplerAction *action);
434POPPLER_PUBLIC
435PopplerAction *poppler_action_copy(PopplerAction *action);
436
437#define POPPLER_TYPE_DEST (poppler_dest_get_type())
438POPPLER_PUBLIC
439GType poppler_dest_get_type(void) G_GNUC_CONST;
440
441POPPLER_PUBLIC
442void poppler_dest_free(PopplerDest *dest);
443POPPLER_PUBLIC
444PopplerDest *poppler_dest_copy(PopplerDest *dest);
445
446POPPLER_PUBLIC
447char *poppler_named_dest_from_bytestring(const guint8 *data, gsize length);
448
449POPPLER_PUBLIC
450guint8 *poppler_named_dest_to_bytestring(const char *name, gsize *length);
451
452G_END_DECLS
453
454#endif /* __POPPLER_GLIB_H__ */
455

source code of poppler/glib/poppler-action.h