Foxit PDF SDK
foxit::pdf::actions::AdditionalAction Class Reference
Inheritance diagram for foxit::pdf::actions::AdditionalAction:
foxit::Base

Public Types

enum  TriggerEvent {
  e_TriggerPageOpened = 0, e_TriggerPageClosed = 1, e_TriggerDocWillClose = 2, e_TriggerDocWillSave = 3,
  e_TriggerDocSaved = 4, e_TriggerDocWillPrint = 5, e_TriggerDocPrinted = 6, e_TriggerFieldKeyStroke = 7,
  e_TriggerFieldWillFormat = 8, e_TriggerFieldValueChanged = 9, e_TriggerFieldRecalculateValue = 10, e_TriggerAnnotCursorEnter = 11,
  e_TriggerAnnotCursorExit = 12, e_TriggerAnnotMouseButtonPressed = 13, e_TriggerAnnotMouseButtonReleased = 14, e_TriggerAnnotReceiveInputFocus = 15,
  e_TriggerAnnotLoseInputFocus = 16, e_TriggerAnnotPageOpened = 17, e_TriggerAnnotPageClosed = 18, e_TriggerAnnotPageVisible = 19,
  e_TriggerAnnotPageInvisible = 20
}
 Enumeration for trigger event. More...
 

Public Member Functions

 AdditionalAction (const AdditionalAction &other)
 Constructor, with another additional action object. More...
 
 AdditionalAction (const foxit::pdf::annots::Annot &annot)
 Constructor, from a PDF annotation. More...
 
 AdditionalAction (const foxit::pdf::interform::Field &field)
 Constructor, from a PDF form field. More...
 
 AdditionalAction (const foxit::pdf::PDFPage &page)
 Constructor, from a PDF page. More...
 
 AdditionalAction (const PDFDoc &doc, objects::PDFDictionary *pdf_dict=0)
 Constructor, from a PDF document or a PDF dictionary (if any). More...
 
 ~AdditionalAction ()
 Destructor.
 
bool DoJSAction (TriggerEvent trigger)
 Perform javascript action which is specified by a trigger event type. More...
 
Action GetAction (TriggerEvent trigger)
 Get an action with specified trigger event type. More...
 
objects::PDFDictionaryGetDict () const
 Get the PDF dictionary of current object. More...
 
bool IsEmpty () const
 Check whether current object is empty or not. More...
 
bool operator!= (const AdditionalAction &other) const
 Not equal operator. More...
 
AdditionalActionoperator= (const AdditionalAction &other)
 Assign operator. More...
 
bool operator== (const AdditionalAction &other) const
 Equal operator. More...
 
bool RemoveAction (TriggerEvent trigger)
 Remove an action with specified trigger event type. More...
 
bool RemoveAllActions ()
 Remove all actions. More...
 
void SetAction (TriggerEvent trigger, const Action &action)
 Set a additional-action for specified trigger event type. More...
 
- Public Member Functions inherited from foxit::Base
FS_HANDLE Handle () const
 Get the handle of current object. More...
 

Detailed Description

An annotation, page object, or (beginning with PDF 1.3) interactive form field may include an entry named "AA" which specifies an additional-actions dictionary (PDF 1.2) that extends the set of events that can trigger the execution of an action. In PDF 1.4, the document catalog dictionary may also contain an "AA" entry for trigger events affecting the document as a whole.
This class can be constructed from PDF document, PDF page, PDF form field, PDF annotation (only some types) or an existing additional-actions dictionary and can be used to get/set data from an additional-actions dictionary from PDF document, PDF page, PDF form field or PDF annotation.

Member Enumeration Documentation

◆ TriggerEvent

Enumeration for trigger event.

Values of this enumeration should be used alone.

Enumerator
e_TriggerPageOpened 

Trigger an action to be performed when the page is opened.

This represents "O" entry in a page object's additional-actions dictionary. Only applicable for additional action object constructed from PDF page.

e_TriggerPageClosed 

Trigger an action to be performed when the page is closed.

This represents "C" entry in a page object's additional-actions dictionary. Only applicable for additional action object constructed from PDF page.

e_TriggerDocWillClose 

Trigger a JavaScript action to be performed before closing a document.

This represents "WC" entry in a document catalog's additional-actions dictionary. Only applicable for additional action object constructed from PDF document.

e_TriggerDocWillSave 

Trigger a JavaScript action to be performed before saving a document.

This represents "WS" entry in a document catalog's additional-actions dictionary. Only applicable for additional action object constructed from PDF document.

e_TriggerDocSaved 

Trigger a JavaScript action to be performed after saving a document.

This represents "DS" entry in a document catalog's additional-actions dictionary. Only applicable for additional action object constructed from PDF document.

e_TriggerDocWillPrint 

Trigger a JavaScript action to be performed before printing a document.

This represents "WP" entry in a document catalog's additional-actions dictionary. Only applicable for additional action object constructed from PDF document.

e_TriggerDocPrinted 

Trigger a JavaScript action to be performed after printing a document.

This represents "DP" entry in a document catalog's additional-actions dictionary. Only applicable for additional action object constructed from PDF document.

e_TriggerFieldKeyStroke 

Trigger a JavaScript action to be performed when the user types a keystroke into a text field or combo box or modifies the selection in a scrollable list box.

This represents "K" entry in a form field's additional-actions dictionary. Only applicable for additional action object constructed from PDF form field.
The triggered action can check the keystroke for validity and reject or modify it.

e_TriggerFieldWillFormat 

Trigger a JavaScript action to be performed before the field is formatted to display its current value.

This represents "F" entry in a form field's additional-actions dictionary. Only applicable for additional action object constructed from PDF form field.
The triggered action can modify the field's value before formatting.

e_TriggerFieldValueChanged 

Trigger a JavaScript action to be performed when the field's value is changed.

This represents "V" entry in a form field's additional-actions dictionary. Only applicable for additional action object constructed from PDF form field.
The triggered action can check the new value for validity.

e_TriggerFieldRecalculateValue 

Trigger a JavaScript action to be performed to recalculate the value of this field when that of another field changes.

This represents "C" entry in a form field's additional-actions dictionary. Only applicable for additional action object constructed from PDF form field.
The order in which the document's fields are recalculated can be gotten by function interform::Form::GetFieldsInCalculationOrder.

e_TriggerAnnotCursorEnter 

Trigger an action to be performed when the cursor enters the annotation's active area.

This represents "E" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation.

e_TriggerAnnotCursorExit 

Trigger an action to be performed when the cursor exits the annotation's active area.

This represents "X" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation.

e_TriggerAnnotMouseButtonPressed 

Trigger an action to be performed when the mouse button is pressed inside the annotation's active area.

This represents "D" (stands for "Down") entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation.

e_TriggerAnnotMouseButtonReleased 

Trigger an action to be performed when the mouse button is released inside the annotation's active area.

This represents "U" (stands for "Up") entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation.

e_TriggerAnnotReceiveInputFocus 

(Applicable for widget annotation only) Trigger an action to be performed when the annotation receives the input focus.

This represents "Fo" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from a widget annotation.

e_TriggerAnnotLoseInputFocus 

(Applicable for widget annotation only) Trigger an action to be performed when the annotation loses the input focus.

This represents "Bl" (Uppercase B and lowercase L, which stands for "blurred") entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from a widget annotation.

e_TriggerAnnotPageOpened 

Trigger an action to be performed when the page containing the annotation is opened.

This represents "PO" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation. The triggered action is executed after action for AdditionalAction::e_TriggerPageOpened is triggered and open action of PDF document, if such actions present.

e_TriggerAnnotPageClosed 

Trigger an action to be performed when the page containing the annotation is closed.

This represents "PC" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation. The triggered action is executed after action for AdditionalAction::e_TriggerPageClosed is triggered, if such action present.

e_TriggerAnnotPageVisible 

Trigger an action to be performed when the page containing the annotation becomes visible in the viewer application's user interface.

This represents "PV" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation.

e_TriggerAnnotPageInvisible 

Trigger an action to be performed when the page containing the annotation is no longer visible in the viewer application's user interface.

This represents "PI" entry in an annotation's additional-actions dictionary. Only applicable for additional action object constructed from PDF annotation.

Constructor & Destructor Documentation

◆ AdditionalAction() [1/5]

foxit::pdf::actions::AdditionalAction::AdditionalAction ( const PDFDoc doc,
objects::PDFDictionary pdf_dict = 0 
)
explicit

Constructor, from a PDF document or a PDF dictionary (if any).

Parameters
[in]docA valid PDF document object.
[in]pdf_dictA PDF dictionary which represents an additional action dictionary. If this parameter is NULL, that means just to construct an Additional action object with PDF document. If this parameter is not NULL, that means to construct an Additional action object from this PDF dictionary should have existed in the specified PDF document and represents the additional action dictionary. Default value: NULL.

◆ AdditionalAction() [2/5]

foxit::pdf::actions::AdditionalAction::AdditionalAction ( const foxit::pdf::PDFPage page)
explicit

Constructor, from a PDF page.

Parameters
[in]pageA valid PDF page object.

◆ AdditionalAction() [3/5]

foxit::pdf::actions::AdditionalAction::AdditionalAction ( const foxit::pdf::interform::Field field)
explicit

Constructor, from a PDF form field.

Parameters
[in]fieldA valid PDF form field.

◆ AdditionalAction() [4/5]

foxit::pdf::actions::AdditionalAction::AdditionalAction ( const foxit::pdf::annots::Annot annot)
explicit

Constructor, from a PDF annotation.

Parameters
[in]annotA valid PDF annotation. Currently, only support widget and screen annotation. For other types of annotations, this function will throw exception foxit::e_ErrUnsupported.

◆ AdditionalAction() [5/5]

foxit::pdf::actions::AdditionalAction::AdditionalAction ( const AdditionalAction other)

Constructor, with another additional action object.

Parameters
[in]otherAnother additional action object.

Member Function Documentation

◆ DoJSAction()

bool foxit::pdf::actions::AdditionalAction::DoJSAction ( TriggerEvent  trigger)

Perform javascript action which is specified by a trigger event type.

If current object is constructed with a valid PDF dictionary, current function will return false directly because Foxit PDF SDK cannot know which kind of object the additional action dictionary is associated with.

Parameters
[in]triggerThe input trigger event type. It should be:
Returns
true means success , while false means failure or current object is constructed from PDF dictionary.

◆ GetAction()

Action foxit::pdf::actions::AdditionalAction::GetAction ( TriggerEvent  trigger)

Get an action with specified trigger event type.

Parameters
[in]triggerThe input trigger event type. It should be:
  • If current additional-action is constructed from PDF dictionary, the trigger value can be one of values defined in enum class TriggerEvent.
  • If current additional-action is constructed from PDF page, the trigger value must be one of values starting from AdditionalAction::e_TriggerPageOpened (with same prefix name).
  • If current additional-action is constructed from PDF document, the trigger value must be one of values starting from AdditionalAction::e_TriggerDocWillClose (with same prefix name).
  • If current additional-action is constructed from PDF form field, the trigger value must be one of values starting from AdditionalAction::e_TriggerFieldKeyStroke (with same prefix name).
  • If current additional-action is constructed from PDF annotation, the trigger value must be one of values starting from AdditionalAction::e_TriggerAnnotCursorEnter (with same prefix name).
Returns
An action object.

◆ GetDict()

objects::PDFDictionary* foxit::pdf::actions::AdditionalAction::GetDict ( ) const

Get the PDF dictionary of current object.

Returns
The PDF dictionary.If there is any error, this function will return NULL.

◆ IsEmpty()

bool foxit::pdf::actions::AdditionalAction::IsEmpty ( ) const

Check whether current object is empty or not.

When the current object is empty, that means current object is useless.

Returns
true means current object is empty, while false means not.

◆ operator!=()

bool foxit::pdf::actions::AdditionalAction::operator!= ( const AdditionalAction other) const

Not equal operator.

Parameters
[in]otherAnother additional action object. This function will check if current object is not equal to this one.
Returns
true means not equal, while false means equal.

◆ operator=()

AdditionalAction& foxit::pdf::actions::AdditionalAction::operator= ( const AdditionalAction other)

Assign operator.

Parameters
[in]otherAnother additional action object, whose value would be assigned to current object.
Returns
Reference to current object itself.

◆ operator==()

bool foxit::pdf::actions::AdditionalAction::operator== ( const AdditionalAction other) const

Equal operator.

Parameters
[in]otherAnother additional action object. This function will check if current object is equal to this one.
Returns
true means equal, while false means not equal.

◆ RemoveAction()

bool foxit::pdf::actions::AdditionalAction::RemoveAction ( TriggerEvent  trigger)

Remove an action with specified trigger event type.

If there is no action for input trigger event type when it is valid, this function will return true directly.

Parameters
[in]triggerThe input trigger event type. It should be:
  • If current additional-action is constructed from PDF dictionary, the trigger value can be one of values defined in enum class TriggerEvent.
  • If current additional-action is constructed from PDF page, the trigger value must be one of values starting from AdditionalAction::e_TriggerPageOpened (with same prefix name).
  • If current additional-action is constructed from PDF document, the trigger value must be one of values starting from AdditionalAction::e_TriggerDocWillClose (with same prefix name).
  • If current additional-action is constructed from PDF form field, the trigger value must be one of values starting from AdditionalAction::e_TriggerFieldKeyStroke (with same prefix name).
  • If current additional-action is constructed from PDF annotation, the trigger value must be one of values starting from AdditionalAction::e_TriggerAnnotCursorEnter (with same prefix name).
Returns
true means success , while false means failure.

◆ RemoveAllActions()

bool foxit::pdf::actions::AdditionalAction::RemoveAllActions ( )

Remove all actions.

Returns
true means success , while false means failure.

◆ SetAction()

void foxit::pdf::actions::AdditionalAction::SetAction ( TriggerEvent  trigger,
const Action action 
)

Set a additional-action for specified trigger event type.

Parameters
[in]triggerThe input trigger event type. It should be:
  • If current additional-action is constructed from PDF dictionary, the trigger value can be one of values defined in enum class TriggerEvent.
  • If current additional-action is constructed from PDF page, the trigger value must be one of values starting from AdditionalAction::e_TriggerPageOpened (with same prefix name).
  • If current additional-action is constructed from PDF document, the trigger value must be one of values starting from AdditionalAction::e_TriggerDocWillClose (with same prefix name).
  • If current additional-action is constructed from PDF form field, the trigger value must be one of values starting from AdditionalAction::e_TriggerFieldKeyStroke (with same prefix name).
  • If current additional-action is constructed from PDF annotation, the trigger value must be one of values starting from AdditionalAction::e_TriggerAnnotCursorEnter (with same prefix name).
[in]actionAn action object to be set.
If current additional-action is constructed from PDF document or PDF form field, the type of this action should be Action::e_TypeJavaScript.
If current additional-action is constructed from PDF page, PDF annotation, or PDF dictionary, please refer to comment of the trigger event to check if only specified type of action can be used. Usually, support following types as the new action:
Action::e_TypeGoto, Action::e_TypeURI, Action::e_TypeJavaScript, Action::e_TypeNamed, Action::e_TypeGoToR, Action::e_TypeGoToE, Action::e_TypeSubmitForm, Action::e_TypeResetForm, Action::e_TypeHide, Action::e_TypeLaunch, Action::e_TypeImportData, Action::e_TypeRendition.
Returns
None.