PTAction

@interface PTAction : NSObject

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.

  • Creates a new ‘GoTo'action. GoTo action takes the user to the specified Destination view located in the same document.

    Note

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

    Declaration

    Objective-C

    + (PTAction *)CreateGoto:(PTDestination *)dest;

    Swift

    class func createGoto(_ dest: PTDestination!) -> PTAction!

    Parameters

    dest

    A Destination for the new Action.

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

    Declaration

    Objective-C

    + (PTAction *)CreateGotoWithNamedDestination:(NSData *)key
                                      key_sz:(int)key_sz
                                        dest:(PTDestination *)dest;

    Swift

    class func createGoto(withNamedDestination key: Data!, key_sz: Int32, dest: PTDestination!) -> PTAction!

    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.

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

    Declaration

    Objective-C

    + (PTAction *)CreateGotoRemote:(PTFileSpec *)file page_num:(int)page_num;

    Swift

    class func createGotoRemote(_ file: PTFileSpec!, page_num: Int32) -> PTAction!

    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.

  • Creates a new ‘GoToR'action. See the above method for details.

    Declaration

    Objective-C

    + (PTAction *)CreateGotoRemoteWithNewWindow:(PTFileSpec *)file
                                   page_num:(int)page_num
                                 new_window:(BOOL)new_window;

    Swift

    class func createGotoRemote(withNewWindow file: PTFileSpec!, page_num: Int32, new_window: Bool) -> PTAction!

    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.

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

    Declaration

    Objective-C

    + (PTAction *)CreateURI:(PTSDFDoc *)doc uri:(NSString *)uri;

    Swift

    class func createURI(_ doc: PTSDFDoc!, uri: String!) -> PTAction!

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

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

    Declaration

    Objective-C

    + (PTAction *)CreateSubmitForm:(PTFileSpec *)url;

    Swift

    class func createSubmitForm(_ url: PTFileSpec!) -> PTAction!

    Parameters

    url

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

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

    Declaration

    Objective-C

    + (PTAction *)CreateLaunch:(PTSDFDoc *)doc path:(NSString *)path;

    Swift

    class func createLaunch(_ doc: PTSDFDoc!, path: String!) -> PTAction!

    Parameters

    doc

    the document in which to create the action
    path

    the full path of the file to be opened

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

    Declaration

    Objective-C

    + (PTAction *)CreateHideField:(PTSDFDoc *)sdfdoc
                        field:(NSArray<NSString *> *)field;

    Swift

    class func createHideField(_ sdfdoc: PTSDFDoc!, field: [String]!) -> PTAction!

    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

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

    Declaration

    Objective-C

    + (PTAction *)CreateImportData:(PTSDFDoc *)doc path:(NSString *)path;

    Swift

    class func createImportData(_ doc: PTSDFDoc!, path: String!) -> PTAction!

    Parameters

    doc

    the document in which to create the action
    path

    the full path of the FDF file

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

    Declaration

    Objective-C

    + (PTAction *)CreateResetForm:(PTSDFDoc *)doc;

    Swift

    class func createResetForm(_ doc: PTSDFDoc!) -> PTAction!

    Parameters

    doc

    the document in which to create the action

  • Creates a new ‘JavaScript’ action. A javascript action executes a JavaScript script when it’s invoked.

    Declaration

    Objective-C

    + (PTAction *)CreateJavaScript:(PTSDFDoc *)doc script:(NSString *)script;

    Swift

    class func createJavaScript(_ doc: PTSDFDoc!, script: String!) -> PTAction!

    Parameters

    doc

    the document in which to create the action
    script

    the JavaScript script to be executed

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

    Note

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

    Declaration

    Objective-C

    - (instancetype)initWithIn_obj:(PTObj *)in_obj;

    Swift

    init!(in_obj: PTObj!)

    Parameters

    in_obj

    Pointer to the Cos/SDF object.

  • Undocumented

    Declaration

    Objective-C

    - (BOOL)isEqualTo: (PTAction*)in_action;

    Swift

    func isEqual(to in_action: PTAction!) -> Bool

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

    Note

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

    Declaration

    Objective-C

    - (BOOL)IsValid;

    Swift

    func isValid() -> Bool

    Return Value

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

  • Declaration

    Objective-C

    - (PTActionType)GetType;

    Swift

    func getType() -> PTActionType

    Return Value

    The type of this Action.

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

    Declaration

    Objective-C

    - (void)Execute;

    Swift

    func execute()

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

    Declaration

    Objective-C

    - (PTKeyStrokeActionResult *)ExecuteKeyStrokeAction:
    (PTKeyStrokeEventData *)data;

    Swift

    func executeKeyStroke(_ data: PTKeyStrokeEventData!) -> PTKeyStrokeActionResult!

    Parameters

    data

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

  • Test if the action needs writeLock

    Declaration

    Objective-C

    - (BOOL)NeedsWriteLock;

    Swift

    func needsWriteLock() -> Bool

    Return Value

    ture if needs, otherwise false

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

    Declaration

    Objective-C

    - (PTObj *)GetNext;

    Swift

    func getNext() -> PTObj!

    Return Value

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

  • Note

    This only works for Actions whose subtype is “GoTo”.

    Note

    All named destinations are automatically resolved to the explicit destination so you can access destination members directly.

    Declaration

    Objective-C

    - (PTDestination *)GetDest;

    Swift

    func getDest() -> PTDestination!

    Return Value

    The Action’s Destination view.

  • Note

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

    Declaration

    Objective-C

    - (BOOL)GetFormActionFlag:(PTFormActionFlag)flag;

    Swift

    func getForm(_ flag: PTFormActionFlag) -> Bool

    Parameters

    flag

    Action flag to get the value from.

    Return Value

    boolean value of the given action flag.

  • Set the value of a given field flag.

    Declaration

    Objective-C

    - (void)SetFormActionFlag:(PTFormActionFlag)flag value:(BOOL)value;

    Swift

    func setForm(_ flag: PTFormActionFlag, value: Bool)

    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.

  • Declaration

    Objective-C

    - (PTObj *)GetSDFObj;

    Swift

    func getSDFObj() -> PTObj!

    Return Value

    Pointer to the underlying SDF/Cos object.

  • Undocumented

    Declaration

    Objective-C

    + (PTAction*)CreateInternal: (unsigned long long)impl;

    Swift

    class func createInternal(_ impl: UInt64) -> PTAction!

  • Undocumented

    Declaration

    Objective-C

    - (unsigned long long)GetHandleInternal;

    Swift

    func getHandleInternal() -> UInt64