pdftron::PDF::Action

pdftron::PDF::Action Class Reference

Actions are typically what happens when a user clicks on a link or bookmark. More...

#include <Action.h>

List of all members.

Public Types

enum Type {
  e_GoTo, e_GoToR, e_GoToE, e_Launch,
  e_Thread, e_URI, e_Sound, e_Movie,
  e_Hide, e_Named, e_SubmitForm, e_ResetForm,
  e_ImportData, e_JavaScript, e_SetOCGState, e_Rendition,
  e_Trans, e_GoTo3DView, e_Unknown
}

PDF supports the standard action types listed in the following table. More...

Public Member Functions

Action (SDF::Obj in_obj=0)

A constructor.

Action (const Action &in_action)

Copy constructor.

Action & operator= (const Action &in_action)

Sets this Action object equal to the specified Action object.

bool operator== (const Action &in_action)

Compares two Action objects for equality.

bool IsValid () const

Indicates whether the Action is valid (non-null).

Type GetType () const

Returns:
The type of this Action.

class Destination GetDest ()

Returns:
The Action’s Destination view.

SDF::Obj GetSDFObj () const

Returns:
Pointer to the underlying SDF/Cos object.

Static Public Member Functions

static Action CreateGoto (class Destination dest)

Creates a new 'GoTo'action.

static Action CreateGoto (const UChar *key, int key_sz, class Destination dest)

Creates a new 'GoTo' action using a 'Named Destination'.

static Action CreateGotoRemote (const FileSpec &file, int page_num)

Creates a new 'GoToR'action.

static Action CreateGotoRemote (const FileSpec &file, int page_num, bool new_window)

Creates a new 'GoToR'action.

static Action CreateSubmitForm (const FileSpec &url)

Creates a new 'SubmitForm'action.

Detailed Description

Actions are typically what happens when a user clicks on a link or bookmark.

Instead of simply jumping to a destination in the document, an annotation or outline item can specify an action for the viewer application to perform, such as launching an application, playing a sound, or changing an annotation’s appearance state.

Note:: Although the Action class provides utility functions for most commonly used action types, it is possible to read, write, and edit any action type using SDF API and dictionary entries described in Section 8.5 in the PDF Reference Manual.

Member Enumeration Documentation

enum pdftron::PDF::Action::Type

PDF supports the standard action types listed in the following table.

Plug-in extensions may add new action types.

Enumerator:

e_GoTo	Go to a destination in the current document.
e_GoToR	('Go-to remote') Go to a destination in another document.
e_GoToE	('Go-to embedded'; PDF 1.6) Go to a destination in an embedded file.
e_Launch	Launch an application, usually to open a file.
e_Thread	Begin reading an article thread.
e_URI	Resolve a uniform resource identifier.
e_Sound	Play a sound.
e_Movie	Play a movie.
e_Hide	Set an annotation’s Hidden flag.
e_Named	Execute an action predefined by the viewer application.
e_SubmitForm	Send data to a uniform resource locator.
e_ResetForm	Set fields to their default values.
e_ImportData	Import field values from a file.
e_JavaScript	Execute a JavaScript script.
e_SetOCGState	(PDF 1.5) Set the states of optional content groups.
e_Rendition	(PDF 1.5) Controls the playing of multimedia content.
e_Trans	Updates the display of a document, using a transition dictionary.
e_GoTo3DView	(PDF 1.6) Set the current view of a 3D annotation
e_Unknown	Unknown Action type.

Constructor & Destructor Documentation

pdftron::PDF::Action::Action ( SDF::Obj in_obj = 0 )

A constructor.

Creates an Action and initializes it using given Cos/SDF object.

Parameters:

in_obj

Pointer to the Cos/SDF object.

Note:: The constructor does not copy any data, but is instead the logical equivalent of a type cast.

pdftron::PDF::Action::Action ( const Action & in_action )

Copy constructor.

Creates a copy of the given Action object.

Parameters:

in_action

A reference to an existing Action object.

Returns:: The new Action.

Member Function Documentation

static Action pdftron::PDF::Action::CreateGoto ( class Destination dest ) [static]

Creates a new 'GoTo'action.

GoTo action takes the user to the specified Destination view located in the same document.

Parameters:

dest

A Destination for the new Action.

Note:: This method can only be used for destinations in the same document as the source document. For cross-document links use Action::CreateGotoRemote().

static Action pdftron::PDF::Action::CreateGoto	(	const UChar *	key,
		int	key_sz,
		class Destination	dest
	)			`[static]`

Creates a new 'GoTo' action using a 'Named Destination'.

GoTo action takes the user to the specified 'Named Destination' view located in the same document.

Parameters:

	key	- a string buffer representing the destination name. The named destination will be stored in document's '/Dest' SDF::NameTree.
	key_sz	The size in bytes of the key buffer.
	dest	The explicit destination used to create the named destination.

static Action pdftron::PDF::Action::CreateGotoRemote	(	const FileSpec &	file,
		int	page_num
	)			`[static]`

Creates a new 'GoToR'action.

A remote go-to action is similar to an ordinary go-to action but jumps to a destination in another PDF file instead of the current file.

Parameters:

	file	The file referred to by the action.
	page_num	A page number within the remote document. The first page is numbered 0. A flag specifying whether to open the destination document in a new window. If new_window is false, the destination document replaces the current document in the same window, otherwise the viewer application should behave in accordance with the current user preference.

static Action pdftron::PDF::Action::CreateGotoRemote	(	const FileSpec &	file,
		int	page_num,
		bool	new_window
	)			`[static]`

Creates a new 'GoToR'action.

See the above method for details.

Parameters:

	file	The file referred to by the action.
	page_num	A page number within the remote document. The first page is numbered 0. A flag specifying whether to open the destination document in a new window. If new_window is false, the destination document replaces the current document in the same window, otherwise the viewer application should behave in accordance with the current user preference.

static Action pdftron::PDF::Action::CreateSubmitForm ( const FileSpec & url ) [static]

Creates a new 'SubmitForm'action.

A submit-form action transmits the names and values of selected interactive form fields to a specified uniform resource locator (URL), presumably the address of a Web server that will process them and send back a response.

Parameters:

url

A URL file specification giving the uniform resource locator (URL) of the script at the Web server that will process the submission.

Action& pdftron::PDF::Action::operator= ( const Action & in_action )

Sets this Action object equal to the specified Action object.

Parameters:

in_action

Reference to a Action object that is assigned to this Action object.

Returns:: This method returns a reference to this Action object to allow cascaded assignments.

bool pdftron::PDF::Action::operator== ( const Action & in_action )

Compares two Action objects for equality.

Parameters:

in_action

A reference to an existing Action object.

Returns:: True if the both Actions share the same underlying SDF/Cos object; otherwise false.

bool pdftron::PDF::Action::IsValid ( ) const

Indicates whether the Action is valid (non-null).

Returns:: True if this is a valid (non-null) Action; otherwise false.

Note:: If this method returns false the underlying SDF/Cos object is null and the Action object should be treated as null as well.

Type pdftron::PDF::Action::GetType ( ) const

Returns:: The type of this Action.

class Destination pdftron::PDF::Action::GetDest ( )

Returns:: The Action’s Destination view.

Note:: This only works for Actions whose subtype is "GoTo".
All named destinations are automatically resolved to the explicit destination so you can access destination members directly.

SDF::Obj pdftron::PDF::Action::GetSDFObj ( ) const

Returns:: Pointer to the underlying SDF/Cos object.


Public Types
enum	Type { e_GoTo, e_GoToR, e_GoToE, e_Launch, e_Thread, e_URI, e_Sound, e_Movie, e_Hide, e_Named, e_SubmitForm, e_ResetForm, e_ImportData, e_JavaScript, e_SetOCGState, e_Rendition, e_Trans, e_GoTo3DView, e_Unknown }
	PDF supports the standard action types listed in the following table. More...
Public Member Functions
	Action (SDF::Obj in_obj=0)
	A constructor.
	Action (const Action &in_action)
	Copy constructor.
Action &	operator= (const Action &in_action)
	Sets this Action object equal to the specified Action object.
bool	operator== (const Action &in_action)
	Compares two Action objects for equality.
bool	IsValid () const
	Indicates whether the Action is valid (non-null).
Type	GetType () const
	Returns: The type of this Action.
class Destination	GetDest ()
	Returns: The Action’s Destination view.
SDF::Obj	GetSDFObj () const
	Returns: Pointer to the underlying SDF/Cos object.
Static Public Member Functions
static Action	CreateGoto (class Destination dest)
	Creates a new 'GoTo'action.
static Action	CreateGoto (const UChar *key, int key_sz, class Destination dest)
	Creates a new 'GoTo' action using a 'Named Destination'.
static Action	CreateGotoRemote (const FileSpec &file, int page_num)
	Creates a new 'GoToR'action.
static Action	CreateGotoRemote (const FileSpec &file, int page_num, bool new_window)
	Creates a new 'GoToR'action.
static Action	CreateSubmitForm (const FileSpec &url)
	Creates a new 'SubmitForm'action.