ImgDoc_CreateWithFile¶
| filePath | Text | The full (absolute) pathname to the image file. |
| options | Object | Options. |
| imgDocRef | Text | The image document reference. |
Create an image document instance referencing an existing file. The image document
reference is returned in imgDocRef.
If the method call fails for some reason, an empty string is returned and the Q2Pix error info is set accordingly.
Parameter filePath is the full (absolute) pathname to the image file. The pathname
may be in either POSIX (recommended) or System format.
If filePath is omitted or set to an empty string, the standard file dialog that
allows selection of any supported format is presented to the user. If the user selects
a file, the method tries to open that file. If the user cancels the dialog,
the error domain and code
are set to "Q2Pix" and kQ2PixErrIntr respectively and the method returns an empty string.
Note
The full pathname of the file selected by the user can be retrieved after a successful
completion of this method with a call to ImgDoc_GetFilePath.
The optional options object parameter may contain the following properties:
| Property name | Description |
|---|---|
| “Format” | The option’s value is the format identifier (a string) of the specified image document. This option does not restrict the reading of the image to the specified format, but rather acts as a ‘hint’ to the plug-in and underlying OS imaging libraries. |
| “Password” | The option’s value is the password (a string) for a protected PDF document. |
| “AllowUserInteraction” | The option’s value is a boolean denoting whether user interaction is allowed.
Default value is True. |
If the specified file or the one selected by the user is a locked PDF document and opening
it fails with an authorization error ("Q2Pix"/kQ2PixErrAuth), a password entry dialog
is presented to the user. If the user enters the correct password, the PDF document is opened
and the document reference is returned. If the user cancels the dialog, the Q2Pix error info
is set to "Q2Pix"/kQ2PixErrAuth and the method returns an empty string. If the user enters
an invalid password, the method keeps running the password request dialog until the user either
enters the correct dialog, or cancels.
The AllowUserInteraction property defaults to True, which allows this command to
present the file selection or PDF password dialog, if necessary. When calling this
method in a batch or unattended process, you may consider setting this to False so as the
process is not halted by dialogs waiting for user input.
Note
This method is a wrapper for the ImgDoc_CreateWithFile_JSN plug-in method.
In addition to converting the options object to JSON for passing to the plug-in,
it offers some extra functionality in the form of the file selection and PDF password
dialogs.
