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_RichMediaExecute, e_Unknown
}
 PDF supports the standard action types listed in the following table. More...
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
}
 Flags used by submit form actions. More...

Public Member Functions

 Action (SDF::Obj in_obj=0)
 A constructor.
 Action (const Action &in_action)
 Copy constructor.
Actionoperator= (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
void 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.
SDF::Obj GetNext () const
class Destination GetDest ()
bool GetFormActionFlag (FormActionFlag flag) const
void SetFormActionFlag (FormActionFlag flag, bool value)
 Set the value of a given field flag.
SDF::Obj GetSDFObj () const

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 CreateURI (SDF::SDFDoc &doc, const char *uri)
 Create a new URI action.
static Action CreateSubmitForm (const FileSpec &url)
 Creates a new 'SubmitForm'action.
static Action CreateLaunch (SDF::SDFDoc &doc, const char *path)
static Action CreateHideField (SDF::SDFDoc &doc, int list_length, const char **field_list)
static Action CreateImportData (SDF::SDFDoc &doc, const char *path)
static Action CreateResetForm (SDF::SDFDoc &doc)
static Action CreateJavaScript (SDF::SDFDoc &doc, const char *script)


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

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.

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 


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::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::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::CreateLaunch ( SDF::SDFDoc doc,
const char *  path 
) [static]

static Action pdftron::PDF::Action::CreateHideField ( SDF::SDFDoc doc,
int  list_length,
const char **  field_list 
) [static]

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

static Action pdftron::PDF::Action::CreateResetForm ( SDF::SDFDoc doc  )  [static]

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

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.

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()

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.

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

Returns:
value of the given action flag.
Action flags are currently only used by submit and reset form actions.

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

Set the value of a given field flag.

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

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

Returns:
Pointer to the underlying SDF/Cos object.


© 2002-2010 PDFTron Systems Inc.