### QPx_SetOption

QPx_SetOption(optionName; numericValue; textValue):error
| optionName | Text | Option name
| numericValue | Real | Numeric value
| textValue | Text | Textual value
| error | Longint | Error result

Modifies internal plug-in options.

QPix has some internal settings that control various aspects of its operations. QPx_SetOption gives access to these settings, allowing the developer to fine-tune the way QPix works.

Each internal setting or option is addressed by its name. Option names are strings that look like file system pathnames. Option names are specified by the optionName parameter.

Plug-in options have either numeric or textual values, depending on the particular option. Numeric option values are specified by the numericValue parameter, and textual values by the textValue parameter.

The list of plug-in option names with descriptions and acceptable option values follows:

- TWAIN options
- Picture Transfer Protocol options
- Video options
- PDF importer options
- PDF generation options
- Progress options
- Image exporting options
- Miscellaneous options

### TWAIN options

Option name: | "/acq/twain/app-name"
Value type: | Text
Default value: | "QPix"

Option name: | "/acq/twain/app-family"
Value type: | Text
Default value: | "QPix"

Option name: | "/acq/twain/app-manufacturer"
Value type: | Text
Default value: | "Escape Information Services"

The TWAIN specification requires the hosting application to identify itself to the TWAIN software and to device drivers by using the application name, family, and manufacturer. QPix registers the 4D application with the default values listed above.

Some drivers use these settings in their own GUI. For example, some drivers install a menu that reads "Scan to XXX" or "Return to XXX", where XXX is the application name. By changing these settings, such drivers will display the correct information in their GUI elements.

Option name: | "/acq/twain/negotiation-level"
Value type: | Numeric
Default value: | 1

When starting an acquisition session with TWAIN, the application and driver must first go through a negotiation phase.

During negotiation the application examines the capabilities of the driver and establishes the settings, based on which the image will be transferred. This procedure is clearly defined in the TWAIN specification, and a properly written TWAIN driver should support capability negotiation. Unfortunately, there exist device drivers that do not comply with the specification, and such drivers might cause problems during capability negotiation.

If this option is set to 1 (the default), QPix will do capability negotiation in compliance with the TWAIN specification. If this option is set to zero, QPix will skip most of the negotiation, hopefully allowing ill-behaved drivers to be used with minimal problems.

Caution: you are advised not to change the default value of this option, unless otherwise requested by Escape support.

Option name: | "/acq/twain/buffer-size-selector"
Value type: | Numeric
Default value: | 0

When an application transfers image data from a TWAIN device, a memory buffer is used. The device driver fills this buffer with stripes of pixels, and the application reads the pixel stripes from the buffer. Depending on the characteristics and size of the acquired image, the size of the image buffer may have an impact on the overall performance of the acquisition operation.

It is the responsibility of the application to allocate this memory buffer. The device driver gives the application some hints on the size of the memory buffer that should be used for the patricular acquisition operation: the minimum, preferred, and maximum buffer size.

This option can be used to control the memory buffer size:

- To use the maximum buffer size, set this option to 1. Depending on the hardware and the characteristics of the acquired image, this may speed up the acquisition process.
- To use the minimum buffer size, set this option to -1. This will economize on memory.
- To use the driver's preferred buffer size, set this option to 0 (default).

Option name: | "/acq/twain/allow-wia-devices"
Value type: | Numeric
Default value: | 0
Used on: | Windows ME, Windows XP

Windows ME/XP may allow applications supporting TWAIN acquisition to transparently work with Windows Image Acquisition (WIA) devices. The name of such devices in the TWAIN device list has a "WIA-" prefix.

QPix by default excludes WIA devices from the TWAIN device list, because:

- QPix supports WIA natively through the PTP acquisition protocol. Listing the same device in both the PTP and TWAIN device lists would be confusing to the user.
- The implementation of the WIA bridge has some rough edges. Generally it is better to access WIA devices through WIA and TWAIN devices through TWAIN.

However, to force QPix include WIA devices in the TWAIN device list, set this option to 1.

Option name: | "/acq/twain/transfer-mechanism"
Value type: | Numeric
Default value: | 0 (= memory transfer mechanism)

The TWAIN specification defines two basic mechanisms from transfering image data from the device to the application: memory transfers, and native transfers.

The memory transfer mechanism is lower-level but more powerful, and gives the greatest flexibility to the application in handling the image data. Image data are transfered in stipes, resulting in minimal memory space requirements. QPix uses the memory transfer mechanism by default (option value = 0)

On the other hand, the native transfer mechanism is higher-level, but less flexible and more memory demanding because the data is transfered in one block, as a 'native' image for the platform: Pict on Mac OS, HDC on Windows.

It is recommended that the memory transfer mechanism be used in TWAIN acquisitions. This options only exists to work around problems in the memory transfer mechanism of some problematic TWAIN drivers. To change to the native transfer mechanism, set this option to 1.

Caution: you are advised not to change the default value of this option, unless otherwise requested by Escape support.

Option name: | "/acq/twain/event-loop-in-hidden-gui"
Value type: | Numeric
Default value: | 1 (= run event loop)

A TWAIN application typically runs a so called "event loop", where it receives events from the operating system and relays them for handling to the TWAIN driver. If an event is pertinent to the TWAIN driver, the driver handles the event and tells the application that it did so; if it isn't, the driver tells the application that the event wasn't handled, and the application typically dispatches the event through its event handling mechanism.

In addition to handling user events, the event loop is also a means of communication between the application and the TWAIN driver; when an image is ready for acquisition, the driver signals this fact to the application through the event loop, and the application starts transfering the image.

This is working fine with most TWAIN driver we have come accross. However, there is a small minority of not-so-compliant TWAIN drivers that do not signal the "trandfer ready" event to the application when acquiring with the driver's GUI hidden. This option was implemented to work around such drivers.

By default, QPix uses the standard TWAIN event loop for communicating with the driver in GUI-less acquisition sessions. If this option is set to 0, QPix will not run the event loop and will try to start transfering images right after opening and configuring the driver.

Caution: you are advised not to change the default value of this option, unless otherwise requested by Escape support.

Option name: | "/acq/twain/extended-negotiation"
Value type: | Numeric
Default value: | 3 (= when the GUI is either hidden or visible)

When preparing a TWAIN acquisition session, an application typically goes through a phase called "device capabilities negotiation". During this phase, the application examines the device's capabilities and sets them according to the options set by the user. QPix does an "extended" negotiation in order to support all the acquisition options that it handles.

This option controls in which "modes" QPix will do an extended negotiation of the device's capabilities: 3 means that it will do an extended negotiation in both GUI hidden and visible modes; 2 means that it will do an extended negotiation when the GUI is visible only; 1 means that it will do an extended negotiation when the GUI is hidden only.

Caution: you are advised not to change the default value of this option, unless otherwise requested by Escape support.

Option name: | "/acq/twain/task-4d"
Value type: | Numeric
Default value: | 1 (= give time to 4D periodically)

When running a TWAIN acquisition session, QPix will give time to 4D periodically, so that 4D's process manager and network connections are not suspended.

Setting this option to 0 will cause QPix to not give any time to 4D. This can be used to troubleshoot some problems in specific applications.

Caution: you are advised not to change the default value of this option, unless otherwise requested by Escape support.

Option name: | "/acq/twain/keep-source-open"
Value type: | Numeric
Default value: | 0 (= do not keep driver open between acquisition sessions)

When running a TWAIN acquisition session, QPix will typically open the device driver, run the acquisition, and finally close the driver.

Setting this option to 1 will cause QPix to keep the driver open when the acquisition session ends. This can be used to speed up subsequent acquisition sessions with the same device driver. If the user chooses a new driver/device for acquisition, the previous one that was kept open is closed, and the new one is opened for the next acquisition session.

This option is not enabled by default (set to 0) because not all TWAIN drivers may behave correctly while kept open between acquisition sessions.

### Picture Transfer Protocol options

Option name: | "/acq/ptp/add-custom-icon"
Value type: | Numeric
Default value: | 1
Used on: | MacOS X

When acquiring images from digital cameras with the PTP protocol on MacOS X, a preview icon is added to the image file.

To turn off the creation of such icons, set this option to 0. To reinstate the creation of preview icons, set this option to 1 (default).

Option name: | "/acq/ptp/add-finder-comment"
Value type: | Numeric
Default value: | 1
Used on: | MacOS X

When acquiring images from digital cameras with the PTP protocol on MacOS X, the file comments are updated to include the image dimensions and resolution.

To turn off the update of file comments, set this option to 0. To enable the update of file comments, set this option to 1 (default).

Option name: | "/acq/ptp/update-creation-date"
Value type: | Numeric
Default value: | 1
Used on: | MacOS X

When acquiring images from digital cameras with the PTP protocol on MacOS X, the file creation date is synchronized with the capture date of the image, based on the relevant Exif tag.

To turn off the synchronization of dates, set this option to 0. To enable date synchronization, set this option to 1 (default).

### Video options

Option name: | "/acq/video/play-shutter-sound"
Value type: | Numeric
Default value: | 1

When capturing an image from a video device, QPix plays a shutter sound.

To turn off the shutter sound, set this option to 0. To enable the shutter sound, set this option to 1 (default).

Option name: | "/acq/video/device-timeout-ticks"
Value type: | Numeric
Default value: | 180 (= 3 * 60 = 3 seconds)

When capturing an image from a video device, QPix will wait for the device to deliver a video frame within 3 seconds (3 * 60 = 180 ticks). If this time passes without receiving a video frame, QPix will stop waiting

and return an error.

Use this option to adjust this timeout value. Note that this option is expressed in ticks (1 tick = 1/60 sec).

Option name: | "/acq/video/device-warmup-ticks"
Value type: | Numeric
Default value: | 180 (= 3 * 60 = 3 seconds)

When first enabled, some video devices may need some time to deliver a clear image. When QPix is instructed to capture an image from a video device without showing the acquisition dialog, it will wait for 3 seconds for the device to warmup before capturing.

Use this option to adjust the device warmup time. This option is expressed in ticks (1 tick = 1/60 sec).

Option name: | "/acq/video/timelapse-interval-ticks"
Value type: | Numeric
Default value: | 180 (= 3 * 60 = 3 seconds)

When QPix is instructed to capture multiple images from a video device without showing the acquisition dialog, it will wait for 3 seconds between each capture.

Use this option to adjust this interval. This option is expressed in ticks (1 tick = 1/60 sec).

### PDF importer options

Option name: | "/pdf/import/component"
Value type: | Numeric
Default value: | 1 (= use new Core Graphics-based importer on Mac OS X)
Used on: | MacOS X

This option lets you specify which PDF importer will be used on Mac OS X.

By default QPix will use the new, improved, Core Graphics-based PDF importer on Mac OS X. To instruct QPix to use the old QT Movie Importer-based importer, set this option to 0.

Important note: if you are changing this option you should do so early in the "On startup" database method, before any QPix command that makes use of the PDF importer directly or indirectly is called. Once the PDF importer is registered with QuickTime, changing this option has no effect.

Option name: | "/pdf/import/horz-res"
Value type: | Numeric
Default value: | 144

Option name: | "/pdf/import/vert-res"
Value type: | Numeric
Default value: | 144

These options let you specify the rendering resolution for the PDF importer. By increading the rendering resolution you can achieve greated detail when zooming-in PDF images and higher quality in printouts, at the expense of memory.

Option name: | "/pdf/import/page-rect"
Value type: | Numeric
Default value: | 0 (= use media box)

This option lets you specify to the PDF importer which PDF rectangle constitutes the page bounds. Acceptable values are:

- 0: use media box (default)
- 1: use crop box
- 2: use bleed box
- 3: use trim box
- 4: use art box

Option name: | "/pdf/import/dll-path"
Value type: | Text
Used on: | Windows

This option lets you point QPix to the location of the AFPL Ghostscript DLL. If QPix finds the AFPL Ghostscript DLL at the specified location, it registers a PDF importer with QuickTime on Windows.

Important note: set this option early in the "On startup" database method, before any QPix command that makes use of QuickTime directly or indirectly is called. Once QuickTime is initialized, changing this option has no effect.

### PDF generation options

Option name: | "/pdf/gen/thumb-width"
Value type: | Numeric
Default value: | 256

Option name: | "/pdf/gen/thumb-height"
Value type: | Numeric
Default value: | 256

These options let you control the maximum dimensions of the thumbnails that get embedded to PDF documents generated by the QPx_CreatePDFFile and QPx_CreatePDFBLOB commands with the qpx_PDFCreateThumbnails option.

### Progress options

Option name: | "/import/progress-delay-ticks"
Value type: | Numeric
Default value: | 180 (= 3 * 60 = 3 seconds)

This option lets you specify the amount of time it takes for a progress dialog to show up when importing images.

Option name: | "/export/progress-delay-ticks"
Value type: | Numeric
Default value: | 180 (= 3 * 60 = 3 seconds)

This option lets you specify the amount of time it takes for a progress dialog to show up when exporting images.

### Image exporting options

Option name: | "/export/exif-thumb-width"
Value type: | Numeric
Default value: | 160

Option name: | "/export/exif-thumb-height"
Value type: | Numeric
Default value: | 120

These options let you control the maximum dimensions of the thumbnails that get embedded to JPEG and TIFF images exported by the QPx_ExportImageFile, QPx_ExportImageFileToBLOB, QPx_ExportPicture, QPx_ExportPictureToBLOB, QPx_ExportAreaImage, QPx_ExportImporterImage, and QPx_ExportImporterImageToBLOB commands with the qpx_ExportThumbnail option.

The default values comply with the Exif2.1/DCF specification.

### Miscellaneous options

Option name: | "/open-file-dialog/max-preview-pixmap-size"
Value type: | Numeric
Default value: | 16777216 (= 16 * 1024 * 1024 = 16 Megabytes)
Used on: | MacOS 9, Windows

This option lets you skip the creation of previews for large image files in the file selection dialog under MacOS 9 and Windows.

By default QPix will not create a preview for image pixelmaps larger than 16 Megabytes (do not confuse pixelmap size with file size; pixelmap size = width * height * depth).

To change the pixelmap size up to which QPix will cerate a preview, set this option to the corresponding value (in bytes).

Related commands

QPx_GetOption | Retrieves internal plug-in options

QPix © Escape
Generated by QDoc 2.8 on Wed, Feb 17, 2010 17:46:45