Loading...
Searching...
No Matches
pdftron::PDF::Action Class Reference

`#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 31 of file Action.h.

## Member Enumeration Documentation

## ◆ FormActionFlag

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 306 of file Action.h.

## ◆ Type

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 224 of file Action.h.

## Constructor & Destructor Documentation

## ◆ Action() [1/2]

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.

## ◆ Action() [2/2]

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

## ◆ CreateGoto() [1/2]

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

## ◆ CreateGoto() [2/2]

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.

## ◆ CreateGotoRemote() [1/2]

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. @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.

## ◆ CreateGotoRemote() [2/2]

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.

## ◆ CreateHideField() [1/2]

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

## ◆ CreateHideField() [2/2]

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

## ◆ CreateImportData()

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

## ◆ CreateInternal()

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

## ◆ CreateJavaScript()

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

## ◆ CreateLaunch()

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

## ◆ CreateResetForm()

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

## ◆ CreateSubmitForm()

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.

## ◆ CreateURI() [1/2]

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

## ◆ CreateURI() [2/2]

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

## ◆ Execute()

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

## ◆ ExecuteKeyStrokeAction()

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.

## ◆ GetDest()

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.

## ◆ GetFormActionFlag()

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.

## ◆ GetHandleInternal()

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

## ◆ GetNext()

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.

## ◆ GetSDFObj()

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

Returns
  Pointer to the underlying SDF/Cos object.

## ◆ GetType()

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

Returns
  The type of this Action.

## ◆ IsValid()

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.

## ◆ NeedsWriteLock()

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

Test if the action needs writeLock

Returns
  ture if needs, otherwise false

## ◆ operator=()

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.

## ◆ operator==()

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.

## ◆ SetFormActionFlag()

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