SetApplicationOption

Definition:

SetApplicationOption(option, value)

 

Description:

Allows you to specify various runtime options which affect the way the app operates.

 

Platforms:

All

 

Parameters:

option - required

A string specifying the option whose setting you want to modify:

"CAMERA_MEGAPIXELS"

Specify maximum size, in megapixels, for a photo taken with the device's camera.

This option doesn't affect recording videos.

 

"CAMERA_TYPE"

Allows you to determine the behaviour of the TakePhoto and TakeVideo Methods.

This option allows you to specify whether calls to TakePhoto will allow the user to take a photo or import existing images from the device's image store or, alternatively, allow the user to choose between these options each time TakePhoto is called. On Android and iOS Platforms, if you are specifying that TakePhoto will allow the user to take photos, you also specify whether this should be done using the device's native camera app or the enhanced camera facility built into the Digitise Apps Client. On the UWP and Windows Desktop Platforms, taking photos will always use the camera facility built into the Client.

By default, if you don't specify a choice by calling SetApplicationOption, TakePhoto will use the device's native camera app on Android and iOS devices and the camera functionality built into the Client on the UWP and Windows Desktop Platforms.

 

This option only affects apps running on iOS devices. On other Platforms the option will be ignored when calling TakeVideo.

On iOS devices it allows you to choose between using the device's native camera app or the enhanced camera facility built into the Digitise Apps Client when taking videos or alternatively to allow the user to import an existing video from the device's video store.

 

 

"DISABLE_TABLE_SORT"

Allows you to specify the order in which Data Sources specified in a call to the Synchronise Method should be processed.

 

"GPS_ACCURACY"

Only affects the iOS Platform.

Allows you to set the accuracy level at which you want the OnLocationChange Event to fire. This option determines the accuracy of the reading returned and hence affects the firing of the Event since location changes will be less identifiable the lower the accuracy.

 

"GPS_DISTANCE_FILTER"

Allows you to specify a minimum change in the distance between two GPS readings before the OnLocationChange Event fires.

 

"GPS_HIGH_ACCURACY"

Only affects the Windows Desktop Platform.

Specifies whether you want GPS readings to be taken using high or low accuracy.

Enabling high accuracy instructs location services to use high precision, which means on Windows devices it will use a physical GPS if it exists rather than the network location. This will give you more precise hdop and co-ordinate readings when using the GPS Methods.

The default setting is to use low precision, which means the network location will be used.

If you want to change the current setting of this option, you must call SetApplicationOption with your chosen setting specified before you call GPSStart.

 

"NOTIFICATION_PLAYSOUND_IN_FOREGROUND"

Only affects the iOS Platform.

Specifies whether you want a sound specified in the AddSystemNotification Method to play if a system notification is received whilst the Digitise app is in the foreground.

 

"PHOTO_OVERLAY_TYPE"

Allows you add a timestamp and/or GPS location to a photo taken using the TakePhoto Method.

If you specify the addition of a timestamp, the time will be added in the format dd-MM-yyy HH:mm:ss.

If you specify GPS location, the location will be added as two lines in standard GPS WSG84 coordinates, one line showing the latitude and the other the longitude.

You can determine where the timestamp and/or location information will be written using the "PHOTO_OVERLAY_HORIZONTAL_POSITION" and "PHOTO_OVERLAY_VERTICAL_POSITION" parameters below.

If you omit this parameter, no timestamp or location will be written on your photos.

This parameter has no effect when TakePhoto is configured to input a photo from the device's photo gallery.

This parameter is not relevant whan calling TakeVideo.

 

"PHOTO_OVERLAY_HORIZONTAL_POSITION"

This parameter is only relevant if you have specified adding a timestamp and/or GPS location to a photo using the "PHOTO_OVERLAY_TYPE" parameter described above.

"PHOTO_OVERLAY_HORIZONTAL_POSITION" allows you to choose the horizontal position for the timestamp and/or GPS location.

This parameter is not relevant whan calling TakeVideo.

 

"PHOTO_OVERLAY_VERTICAL_POSITION"

This parameter is only relevant if you have specified adding a timestamp and/or GPS location to a photo using the "PHOTO_OVERLAY_TYPE" parameter described above.

"PHOTO_OVERLAY_VERTICAL_POSITION" allows you to choose the vertical position for the timestamp and/or GPS location.

This parameter is not relevant whan calling TakeVideo.

 

"PROGRESS_ALLOW_CANCEL"

Specify whether the user is allowed to cancel an operation involving communications with the App Server when the progress bar or busy indicator is displayed – see Notes below for more details.

 

"PROGRESS_MODE"

Specify whether you want the Digitise Apps Client to indicate when it's busy by displaying a progress bar or the busy indicator and if using a progress bar whether you want the full messages displayed or a reduced display.

 

"VIDEO_RESOLUTION"

Specify the resolution at which videos should be recorded.

This option is only relevant on Android devices.

 

"VIDEO_TIMEOUT"

Allows you to specify a maximum time, in seconds, for which a video can be recorded to help reduce the size of recorded videos. The default time is 60 seconds. At the end of the specified time period the video will automatically stop recording. Specify 0, zero, for no time limit.

This option is not supported on Android and there is no default timeout on this Platform.

 

"VIDEO_HAS_AUDIO"

Allows you to enable and disable sound recording when recording a video.

On the iOS Platform, this setting only works when using the advanced built-in camera, i.e. when SetApplicationOption is called with the "CAMERA_TYPE" option (see above) set to "BUILTIN".

This option is not supported on Android or Windows Desktop Platforms, but does work on the Windows Universal Platform.

 

 

 

value - required

The value parameter allows you to specify the value you want to set for the option specified in the option parameter. Each option has its own set of possible values:

"CAMERA_MEGAPIXELS"

Specify the maximum size for photos taken with the device's camera in megapixels, e.g. 1.1. When a user takes a photo, the app will attempt to select a camera resolution which will produce an image equal to or larger than the size specified here.

The default size is 2.1 megapixels.

If a photo is larger than the size specified here, it will be downscaled so that it is equal to or less than the size specified here. When converting a photo taken by the device down to your maximum size, the image retains its height/width ratio.

If the value specified here is greater than the camera's maximum resolution, photos will be taken at the camera's maximum size.

If this value is set to 0 (zero) or below, the default value of 2.1 will be used.

This option does not affect video recordings.

 

"CAMERA_TYPE"

For TakeVideo, the CAMERA_TYPE option is only actioned on iOS devices.

The value specified for this option can be one of the following:

"NATIVE"

Android devices

TakePhoto will use the device's native camera app to take photos.

iOS devices

TakePhoto or TakeVideo will use the device's native camera app to take photos or record videos.

Universal Windows and Windows Desktop Platforms

TakePhoto will use the camera functionality built into the Digitise Apps Client to take photos.

This is the default option if you don't call SetApplicationOption specifying the "CAMERA_TYPE" option.

 

"BUILTIN"

Android devices

TakePhoto will use the enhanced camera features built into the Digitise Apps Client to take photos, instead of the device's default camera app. Requires Android v12 or above.

iOS devices

TakePhoto or TakeVideo will use the enhanced camera features built into the Digitise Apps Client to take photos or record videos, instead of the device's default camera app.

Universal Windows and Windows Desktop Platforms

This option is equivalent to specifying "NATIVE".

 

"GALLERY"

TakePhoto and TakeVideo will allow the user to import an existing photograph or video, respectively, from the device's image store.

Android devices

With TakePhoto, the user will be presented with a choice of image management apps available on the device, such as Photos and Gallery, to use to select the image. They can opt to use their choice of app for the current picture only and, therefore, be allowed to choose again the next time TakePhoto is called, or to permanently select this app for use with this Digitise app.

iOS devices

The user will be presented with a standard iOS picture browser from which they can select the required image or video, as appropriate for the called Method.

Universal Windows and Windows Desktop Platforms

The user will be presented with a standard Windows file browser window from which they can select the required image.

 

"CHOOSE"

The user will be asked which of the above resources to use each time a call to TakePhoto or TakeVideo is made.

The value specified here will affect all subsequent calls to both TakePhoto and TakeVideo until another call to SetApplicationOption specifying this option with a different value or the app is stopped.

 

"DISABLE_TABLE_SORT"

When you make a call to the Synchronise Method, you specify the Data Source(s) you want to be processed by the call. This option allows you to specify the order in which the specified Data Sources will be processed by the Digitise Apps Server:

"TRUE" - Turns off automatic sorting and instructs the Digitise Apps Server to process the Data Sources in the order they are specified in the call parameters. This option allows you to specify the order in which you want the Data Sources to be processed. Note this means that where you have Foreign Key relationships, you will need to specify the tables to be uploaded in a suitable order, with the Primary Key tables first followed by the tables containing the Foreign Keys referring to the Primary Keys. If the order is incorrect, Foreign Key values will not be updated correctly.

"FALSE" - Turns on automatic sorting, which means the Digitise Apps Server will automatically process the Data Sources in an order which allows Primary and Foreign Key relationships to be maintained.

This is the default value if this parameter is not specified or if the Data Sources are not included in a call parameter.

 

"GPS_ACCURACY"

This option only affects the iOS Platform.

The value specified for this option can be one of the following:

"ACCURACY_BEST"

"ACCURACY_NEAREST_TEN_METRES"

"ACCURACY_HUNDRED_METRES"

"ACCURACY_KILOMETRE"

"ACCURACY_THREE_KILOMETRE"

You must set this option before calling the GPSStart Method, otherwise it will not take effect. The values you specify are passed to the GPS device but are not always strictly adhered to. However, increasing the distance travelled between location updates may help reduce battery drain and improve device performance.

 

"GPS_DISTANCE_FILTER"

The value of this option specifies the distance in metres and can be an integer value from 10 upwards.

You must set this option before calling the GPSStart Method, otherwise it will not take effect. The values you specify are passed to the GPS device but are not always strictly adhered to. However, increasing the distance travelled between location updates may help reduce battery drain and improve device performance.

 

"GPS_HIGH_ACCURACY"

This option only affects the Windows Desktop Platform.

The value specified for this option can be one of the following:

"TRUE" - Enables high precision for GPS readings.

"FALSE" - Returns to low precision for GPS readings. This is the default setting, if the option hasn't been specified.

 

"NOTIFICATION_PLAYSOUND_IN_FOREGROUND"

The value specified for this option can be one of the following:

"TRUE" - The sound will play if a system notification is received when the app is in the foreground.

"FALSE" - The sound will not play if a system notification is received when the app is in the foreground. This is the default setting, if the option hasn't been specified.

 

"PHOTO_OVERLAY_TYPE" - The value specified for this option can be one of the following:

"NONE"

Time and location data will not be added to photos taken using the TakePhoto Method. This is the default setting, if the option hasn't been specified.

 

"LOCATION"

Standard GPS WGS84 coordinates will be added to photos taken using the TakePhoto Method.

 

"TIMESTAMP"

A timetamp will be added to photos taken using the TakePhoto Method.

 

"LOCATION_AND_TIMESTAMP"

Both standard GPS WGS84 coordinates and a timestamp will be added to photos taken using the TakePhoto Method.

This option does not affect video recordings.

 

"PHOTO_OVERLAY_HORIZONTAL_POSITION"

The value specified for this option determines the horizontal positioning of the location and timestamp information added to a photo taken using TakePhoto:

"LEFT"

Time and/or date data, if added to a photo, will be added on the left of the image.

This is the default value if this parameter is not specified.

 

"MIDDLE"

Time and/or date data, if added to a photo, will be added in the middle of the image.

 

"RIGHT"

Time and/or date data, if added to a photo, will be added on the right of the image.

 

The value specified here will be combined with the value specified in the "PHOTO_OVERLAY_VERTICAL_POSITION" to determine the overall position of the time and/or location data.

This option does not affect video recordings.

 

"PHOTO_OVERLAY_VERTICAL_POSITION"

The value specified for this option determines the vertical positioning of the location and timestamp information superimposed on a photo taken using TakePhoto:

"TOP"

Time and/or date data, if added to a photo, will be added towards the top of the image.

 

"MIDDLE"

Time and/or date data, if added to a photo, will be added in the middle of the image.

 

"BOTTOM"

Time and/or date data, if added to a photo, will be added on the right of the image.

This is the default value if this parameter is not specified.

 

The value specified here will be combined with the value specified in the "PHOTO_OVERLAY_HORIZONTAL_POSITION" to determine the overall position of the time and/or location data.

This option does not affect video recordings.

 

"PROGRESS_ALLOW_CANCEL"

The value specified for this option determines whether a user can cancel the current operation where the operation involves communicating with the App Server and the progress bar or busy indicator is displayed. It can take one of the following values:

"DEFAULT" - Digitise Apps Client decides if current operation can be cancelled.

"TRUE" - User is allowed to cancel current operation.

"FALSE" - User is NOT allowed to cancel current operation.

 

"PROGRESS_MODE"

The value specified for this option can be one of the following:

"FULL"

Displays a progress bar to indicate program busy with full information display including messages indicating current action and item count.

 

"SIMPLE"

Displays a progress bar to indicate program busy with title but no other information displayed.

 

"MINIMAL"

Displays a progress bar to indicate program busy with no title or information displayed.

 

"INDETERMINATE"

Display busy indicator instead of progress bar to indicate program busy. The device's standard busy indicator will be used.

 

"VIDEO_RESOLUTION"

This option is only relevant on Android devices and will be ignored on iOS and Windows Universal Platforms. This option is not relevant on the Windows Desktop Platform as you can't record videos on this Platform.

 

The option allows you to specify the resolution at which you want videos to be recorded. Possible values are:

"SMALL"

Digitise Apps will choose the lowest resolution available on the device.

 

"MEDIUM"

Digitise Apps will choose a mid-range resolution from the resolutions available on the device.

 

"LARGE"

Digitise Apps will choose the highest resolution available on the device, up to 1080p.

 

"QVGA" - equivalent to "SMALL"

 

"VGA" - equivalent to "MEDIUM"

 

"HD720"

 

"HD1080" - equivalent to "LARGE"

 

At runtime, if your chosen resolution isn't supported by the device, the nearest resolution below that specified will be used.

The default value is "SMALL".

 

 

"VIDEO_TIMEOUT"

Specify the number of seconds you want to set as the maximum time for which a video can be recorded. The default value is 60 seconds. At the end of the specified time period the video will automatically stop recording.

This option is not supported on Android and there is no default timeout on this Platform.

This option is not relevant on the Windows Desktop Platform as you cannot record videos on this Platform.

 

"VIDEO_HAS_AUDIO"

Only relevant to the iOS Platform when using the advanced built-in camera, i.e. when SetApplicationOption is called with the "CAMERA_TYPE" option (see above) set to "BUILTIN", and to the UWP Platform, this option allows you to enable and disable sound recording when recording a video.

"TRUE" - Enables sound for video recordings. This is the default value, if SetApplicationOption is not called specifying a value for the "VIDEO_HAS_AUDIO" option.

"FALSE" - Disables sound for video recordings.

 

 

Returns:

nothing

 

Notes:

  • You can only include one option per call to SetApplicationOption. If you want to modify multiple options, you will need to make a separate call to SetApplicationOption for each one.

  • If you specify the "PROGRESS_ALLOW_CANCEL" option with a value of either "DEFAULT" or "TRUE", this may allow a user to cancel an operation when a progress bar or busy indicator is displayed and the operation involves communication with the App Server:

    On Android devices, to cancel the operation you can press the Back button on the Digitise Apps Client's toolbar at the bottom of the screen. This action is available for both progress bar and busy indicator. If the Cancel action is not allowed, pressing the Back button will have no effect.

     

    On iOS devices, the operation can only be cancelled when a progress bar is displayed and is cancelled by tapping the Picture showing the Cancel operation button. button displayed to the right of the progress bar.

     

    On the Windows Universal Platform, the operation can be cancelled when a progress bar is displayed by choosing the X button to the right of the progress bar or when the busy indicator is displayed by pressing the device's Back button.

    On the Windows Desktop Platform, the operation can only be cancelled when a progress bar is displayed and is cancelled by choosing the Cancel button in the progress dialog box.

     

  • If you specify the "NOTIFICATION_PLAYSOUND_IN_FOREGROUND" option with a value of "TRUE", no sound will play, when a system notification is received, if the "NO_FOREGROUND_ALERT" option in the AddSystemNotification Scripting Method has been specified.

  • If you specify an unsupported option on any Platform, the call to SetApplicationOption will simply be ignored.

  • Once an option has been set using SetApplicationOption, the value specified will continue in operation until either the app is closed or SetApplicationOption is called again specifying a different setting.