#include <Action.h>

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_RichMediaExecute, e_Unknown }

enum	FormActionFlag { e_exclude = 0, e_include_no_value_fields = 1, e_export_format = 2, e_get_method = 3, e_submit_coordinates = 4, e_xfdf = 5, e_include_append_saves = 6, e_include_annotations = 7, e_submit_pdf = 8, e_canonical_format = 9, e_excl_non_user_annots = 10, e_excl_F_key = 11, e_embed_form = 13 }

Public Member Functions
	Action (SDF::Obj in_obj=0)

	Action (const Action &in_action)

Action &	operator= (const Action &in_action)

bool	operator== (const Action &in_action)

bool	IsValid () const

Type	GetType () const

void	Execute ()

KeyStrokeActionResult	ExecuteKeyStrokeAction (const KeyStrokeEventData &data)

bool	NeedsWriteLock ()

SDF::Obj	GetNext () const

class Destination	GetDest ()

bool	GetFormActionFlag (FormActionFlag flag) const

void	SetFormActionFlag (FormActionFlag flag, bool value)

SDF::Obj	GetSDFObj () const

ptrdiff_t	GetHandleInternal ()

Static Public Member Functions
static Action	CreateGoto (class Destination dest)

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

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

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

static Action	CreateURI (SDF::SDFDoc &doc, const char *uri)

static Action	CreateURI (SDF::SDFDoc &doc, UString &uri)

static Action	CreateSubmitForm (const FileSpec &url)

static Action	CreateLaunch (SDF::SDFDoc &doc, const char *path)

static Action	CreateHideField (SDF::SDFDoc &sdfdoc, int list_length, const char **field)

static Action	CreateHideField (SDF::SDFDoc &sdfdoc, const std::vector< std::string > &field)

static Action	CreateImportData (SDF::SDFDoc &doc, const char *path)

static Action	CreateResetForm (SDF::SDFDoc &doc)

static Action	CreateJavaScript (SDF::SDFDoc &doc, const char *script)

static Action *	CreateInternal (ptrdiff_t impl)

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.

Definition at line 29 of file Action.h.

Member Enumeration Documentation

enum pdftron::PDF::Action::FormActionFlag

Flags used by submit form actions. Exclude flag is also used by reset form action. No other action types use flags in the current version of PDF standard (ISO 2300).

Enumerator
e_exclude
e_include_no_value_fields
e_export_format
e_get_method
e_submit_coordinates
e_xfdf
e_include_append_saves
e_include_annotations
e_submit_pdf
e_canonical_format
e_excl_non_user_annots
e_excl_F_key
e_embed_form

Definition at line 304 of file Action.h.

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_RichMediaExecute	Adobe supplement to ISO 32000; specifies a command to be sent to rich media annotation's handler.
e_Unknown	Unknown Action type.

Definition at line 222 of file Action.h.

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.
new_window	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::CreateHideField	(	SDF::SDFDoc &	sdfdoc,
		int	list_length,
		const char **	field
	)

static

Creates a new 'Show/Hide Field' action. A show/hide field action shows or hide certain fields when it's invoked.

Parameters

sdfdoc	the document in which to create the action
list_length	the number of fields to hide
field	the list of fields to hide

static Action pdftron::PDF::Action::CreateHideField	(	SDF::SDFDoc &	sdfdoc,
		const std::vector< std::string > &	field
	)

static

static Action pdftron::PDF::Action::CreateImportData	(	SDF::SDFDoc &	doc,
		const char *	path
	)

static

Creates a new 'Import Data' action. An import data action imports form data from a FDF file into a PDF document.

Parameters

doc	the document in which to create the action
path	the full path of the FDF file

static Action* pdftron::PDF::Action::CreateInternal ( ptrdiff_t impl )

static

static Action pdftron::PDF::Action::CreateJavaScript	(	SDF::SDFDoc &	doc,
		const char *	script
	)

static

Creates a new 'JavaScript' action. A javascript action executes a JavaScript script when it's invoked.

Parameters

doc	the document in which to create the action
script	the JavaScript script to be executed

static Action pdftron::PDF::Action::CreateLaunch	(	SDF::SDFDoc &	doc,
		const char *	path
	)

static

Creates a new 'Launch' action. A launch action opens up a file using the most appropriate program.

Parameters

doc	the document in which to create the action
path	the full path of the file to be opened

static Action pdftron::PDF::Action::CreateResetForm ( SDF::SDFDoc & doc )

static

Creates a new 'Reset Form' action. A reset form action reset chosen form fields to their default value.

Parameters

doc	the document in which to create the action

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.

static Action pdftron::PDF::Action::CreateURI	(	SDF::SDFDoc &	doc,
		const char *	uri
	)

static

Create a new URI action. The URI action is typically resolved by opening a URL in the default web browser.

Parameters

doc	The document in which to create the action.
uri	The uniform resource identifier to resolve, encoded in 7-bit ASCII. A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet; typically a file that is the destination of a hypertext link, although it can also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI).

static Action pdftron::PDF::Action::CreateURI	(	SDF::SDFDoc &	doc,
		UString &	uri
	)

static

Create a new URI action. The URI action is typically resolved by opening a URL in the default web browser.

Parameters

doc	The document in which to create the action.
uri	The uniform resource identifier to resolve, encoded in UTF-8. A uniform resource identifier (URI) is a string that identifies (resolves to) a resource on the Internet; typically a file that is the destination of a hypertext link, although it can also resolve to a query or other entity. (URIs are described in Internet RFC 2396, Uniform Resource Identifiers (URI).

void pdftron::PDF::Action::Execute ( )

Executes current action; this will only work for some action types that can be executed only using the information contained in the action object or the associated PDF doc. See also PDFViewCtrl::ExecuteAction()

KeyStrokeActionResult pdftron::PDF::Action::ExecuteKeyStrokeAction ( const KeyStrokeEventData & data )

Executes KeyStrokeAction, this shall be performed when the user modifies a character in a text field or combo box or modifies the selecton in a scrollable list box. This action checks the added text for validity and reject or modify it.

Parameters

data	Data that contains previous text, added text,and added position information.

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.

bool pdftron::PDF::Action::GetFormActionFlag ( FormActionFlag flag ) const

Parameters

flag	Action flag to get the value from.

Returns: boolean value of the given action flag.

Note: Action flags are currently only used by submit and reset form actions.

ptrdiff_t pdftron::PDF::Action::GetHandleInternal ( )

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

Returns: The next action dictionary, an array of action dictionaries, or NULL if there are no additional actions.

Sequences of actions can be chained together. For example, the effect of clicking a link annotation with the mouse might be to play a sound, jump to a new page, and start up a movie. Note that the Next entry is not restricted to a single action but may contain an array of actions, each of which in turn may have a Next entry of its own. The actions may thus form a tree instead of a simple linked list. Actions within each Next array are executed in order, each followed in turn by any actions specified in its Next entry, and so on recursively.

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

Returns: Pointer to the underlying SDF/Cos object.

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

Returns: The type of this Action.

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.

bool pdftron::PDF::Action::NeedsWriteLock ( )

Test if the action needs writeLock

Returns: ture if needs, otherwise false

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.

void pdftron::PDF::Action::SetFormActionFlag	(	FormActionFlag	flag,
		bool	value
	)

Set the value of a given field flag.

Parameters

flag	Action flag to get the value from.
value	Boolean to set the value of the flag to. Action flags are currently only used by submit and reset form actions.

The documentation for this class was generated from the following file:

PDF/Action.h

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation