GdPicture.NET.14.API
GdPicture14 Namespace / GdPicturePDF Class / NewActionLaunch Method
The file name of the application to be launched or the document to be opened or printed, in standard Windows pathname format.
Specifies the default directory (related to the FileName and the Operation parameters) in standard DOS syntax. It is a Windows-specific parameter and it is optional, so if you are not sure, please use an empty string.
A parameter string to be passed to the application designated by the FileName parameter. It is a Windows-specific parameter and it is optional, so if you are not sure, please use an empty string.
A member of the PdfActionLaunchOperation enumeration. It is a Windows-specific parameter and it is optional, so if you are not sure, please use the value of PdfActionLaunchOperation.ActionLaunchOperationUndefined.
Specifies whether to open the related document (see the FileName parameter) in a new window. If the value is set to false, the specified document replaces the current document in the same window. This value is ignored if the specified document is not a PDF document.
Example





In This Topic
NewActionLaunch Method (GdPicturePDF)
In This Topic
Creates a new action of the type Launch. A launch action launches an application or opens or prints a document.
Syntax
'Declaration
 
Public Function NewActionLaunch( _
   ByVal FileName As String, _
   ByVal DefaultDirectory As String, _
   ByVal Parameters As String, _
   ByVal Operation As PdfActionLaunchOperation, _
   ByVal NewWindow As Boolean _
) As Integer
public int NewActionLaunch( 
   string FileName,
   string DefaultDirectory,
   string Parameters,
   PdfActionLaunchOperation Operation,
   bool NewWindow
)
public function NewActionLaunch( 
    FileName: String;
    DefaultDirectory: String;
    Parameters: String;
    Operation: PdfActionLaunchOperation;
    NewWindow: Boolean
): Integer; 
public function NewActionLaunch( 
   FileName : String,
   DefaultDirectory : String,
   Parameters : String,
   Operation : PdfActionLaunchOperation,
   NewWindow : boolean
) : int;
public: int NewActionLaunch( 
   string* FileName,
   string* DefaultDirectory,
   string* Parameters,
   PdfActionLaunchOperation Operation,
   bool NewWindow
) 
public:
int NewActionLaunch( 
   String^ FileName,
   String^ DefaultDirectory,
   String^ Parameters,
   PdfActionLaunchOperation Operation,
   bool NewWindow
) 

Parameters

FileName
The file name of the application to be launched or the document to be opened or printed, in standard Windows pathname format.
DefaultDirectory
Specifies the default directory (related to the FileName and the Operation parameters) in standard DOS syntax. It is a Windows-specific parameter and it is optional, so if you are not sure, please use an empty string.
Parameters
A parameter string to be passed to the application designated by the FileName parameter. It is a Windows-specific parameter and it is optional, so if you are not sure, please use an empty string.
Operation
A member of the PdfActionLaunchOperation enumeration. It is a Windows-specific parameter and it is optional, so if you are not sure, please use the value of PdfActionLaunchOperation.ActionLaunchOperationUndefined.
NewWindow
Specifies whether to open the related document (see the FileName parameter) in a new window. If the value is set to false, the specified document replaces the current document in the same window. This value is ignored if the specified document is not a PDF document.

Return Value

The unique action identifier of the newly created action of the type Launch. The GdPicturePDF.GetStat method can be subsequently used to determine if this method has been successful.

You can subsequently apply this identifier when creating actions using these methods: GdPicturePDF.SetViewerOpenAction, GdPicturePDF.SetBookmarkAction, GdPicturePDF.SetAnnotationAction or GdPicturePDF.SetFormFieldAction.

Remarks
This method is only allowed for use with non-encrypted documents.

It is recommend to use the GdPicturePDF.GetStat method to identify the specific reason for the method's failure, if any.

Also be careful about the PDF/A conformance of the current document. Executable file launches are forbidden in the PDF/A compliant documents.

Example
How to create a form field of the type button with the associated Launch action. Clicking this button in the created PDF document results in the opening of the Notepad.exe application.
Dim gdpicturePDF As New GdPicturePDF()
Dim failedMethod As String = "NewPDF()"
If gdpicturePDF.NewPDF() = GdPictureStatus.OK Then
    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft)
    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter)
    failedMethod = "NewPage() or SelectPage()"
    If (gdpicturePDF.NewPage(21, 29.7F) = GdPictureStatus.OK) AndAlso (gdpicturePDF.SelectPage(1) = GdPictureStatus.OK) Then
        failedMethod = "AddStandardFont()"
        Dim fontResName As String = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontCourier)
        If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
            failedMethod = "AddPushButtonFormField()"
            Dim fieldID As Integer = gdpicturePDF.AddPushButtonFormField(1, 1, 5, 1, "Submit", "Open notepad.exe", fontResName, 6, 255, 0, 0)
            If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
                failedMethod = "NewActionLaunch()"
                Dim actionID As Integer = gdpicturePDF.NewActionLaunch("notepad.exe", "", "", PdfActionLaunchOperation.ActionLaunchOperationUndefined, True)
                If gdpicturePDF.GetStat() = GdPictureStatus.OK Then
                    failedMethod = "SetFormFieldAction() or SaveToFile()"
                    If (gdpicturePDF.SetFormFieldAction(fieldID, actionID) = GdPictureStatus.OK) AndAlso (gdpicturePDF.SaveToFile("button_action.pdf") = GdPictureStatus.OK) Then
                        failedMethod = ""
                        MessageBox.Show("The PDF document containing the button associated with the Launch action has been saved successfully.", "Example: NewActionLaunch")
                    End If
                End If
            End If
        End If
    End If
End If
If failedMethod <> "" Then
    MessageBox.Show("The " + failedMethod + " method has failed. The presumed status: " + gdpicturePDF.GetStat().ToString(), "Example: NewActionLaunch")
End If
gdpicturePDF.Dispose()
GdPicturePDF gdpicturePDF = new GdPicturePDF();
string failedMethod = "NewPDF()";
if (gdpicturePDF.NewPDF() == GdPictureStatus.OK)
{
    gdpicturePDF.SetOrigin(PdfOrigin.PdfOriginTopLeft);
    gdpicturePDF.SetMeasurementUnit(PdfMeasurementUnit.PdfMeasurementUnitCentimeter);
    failedMethod = "NewPage() or SelectPage()";
    if ((gdpicturePDF.NewPage(21, 29.7f) == GdPictureStatus.OK) &&
        (gdpicturePDF.SelectPage(1) == GdPictureStatus.OK))
    {
        failedMethod = "AddStandardFont()";
        string fontResName = gdpicturePDF.AddStandardFont(PdfStandardFont.PdfStandardFontCourier);
        if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
        {
            failedMethod = "AddPushButtonFormField()";
            int fieldID = gdpicturePDF.AddPushButtonFormField(1, 1, 5, 1, "Submit", "Open notepad.exe", fontResName, 6, 255, 0, 0);
            if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
            {
                failedMethod = "NewActionLaunch()";
                int actionID = gdpicturePDF.NewActionLaunch("notepad.exe", "", "", PdfActionLaunchOperation.ActionLaunchOperationUndefined, true);
                if (gdpicturePDF.GetStat() == GdPictureStatus.OK)
                {
                    failedMethod = "SetFormFieldAction() or SaveToFile()";
                    if ((gdpicturePDF.SetFormFieldAction(fieldID, actionID) == GdPictureStatus.OK) &&
                        (gdpicturePDF.SaveToFile("button_action.pdf") == GdPictureStatus.OK))
                    {
                        failedMethod = "";
                        MessageBox.Show("The PDF document containing the button associated with the Launch action has been saved successfully.", "Example: NewActionLaunch");
                    }
                }
            }
        }
    }
}
if (failedMethod != "")
    MessageBox.Show("The " + failedMethod + " method has failed. The presumed status: " + gdpicturePDF.GetStat().ToString(), "Example: NewActionLaunch");
gdpicturePDF.Dispose();
See Also