image Object
The image Object, not to be confused with the Image Widget, is a JavaScript object that retrieves images as raw bytes. It provides the following API element:
Methods
The image Object contains the following methods.
Compresses an image by the specified compression ratio.
Syntax
<<imageObject>>.compress(compressionRatio);
Input Parameters
Parameter | Description |
---|---|
compressionRatio | A floating point value that specifies the amount of compression to use. |
Example
var imgObj = kony.image.createImage(rawBytes); imgObj.compress(0.8);
Return Values
None.
Remarks
This method compresses the Image object's bitmap using the JPEG compression algorithm. The floating point value in the compressionRatio parameter must be in the range of 0.0<=compressionRatio<=1.0. If compressionRatio is 0.0, this method uses the minimum amount of compression. A value of 1.0 specifies the maximum amount of compression. Values outside the allowed range will be clamped to the nearest valid value. The compression data size that this method produces will vary depending on the hardware platform.
Availability
- iOS
- Android
This method crops the bitmap contained by the Image object to the size of the input rectangle.
Syntax
cropToRect(array);
Input Parameters
Parameter | Description |
---|---|
array | An array of integers specifying the cropping rectangle in the order (x,y,width,height). |
Example
var imgObj = kony.image.createImage(rawBytes); imgObj.cropToRect([0, 0, 720, 720]);
Return Values
None.
Remarks
This method crops the current Image object's bitmap to the size of the rectangle specified in the array parameter, altering the bitmap in the process.
If there is no intersection between the Image object's bitmap and the rectangle in the array parameter, then no cropping is performed.
Availability
- iOS
- Android
Searches for and retrieves and image in the device's gallery of pictures.
Syntax
findImageInGallery(config);
Input Parameters
Parameter | Description |
---|---|
config |
A JavaScript object containing the information needed to search for the image. This object holds the following key-value pairs.
|
Example
var imgObj = kony.image.createImage("src.png"); imgObj.writeToGallery(); var uniqueImgIdentifier; function onSuccess(uniqueIdentifier) { uniqueImgIdentifier = uniqueIdentifier; } config = { ImageName: uniqueImgIdentifier }; var rawBytesObj = findImageInGallery(config);
Return Values
Returns an object of type kony.types.RawBytes that contains the RawBytes image data if the file exists, or null
if the file is not found.
Remarks
From the Quantum Visualizer 202306 release, if the Target SDK API level of the app is set as 33, and the app uses the findImageInGallery Method of the Image API, you must enable support for granular media permissions. To do so, navigate to Project Settings > Native > Android Mobile / Tablet, and add the following entries in the Permissions tab based on the type of media files you want to access:
- Enable the
READ_MEDIA_IMAGES
permission to access image files. - Enable the
READ_MEDIA_AUDIO
permission to access audio file. - Enable the
READ_MEDIA_VIDEO
permission to access video files.
Exceptions
Value | Description |
---|---|
100 | Either albumName or imageName was not of type String. |
Retrieves the image height as an integer.
Syntax
getImageAsRawBytes(encodingFormat);
Input Parameters
Parameter | Description |
---|---|
encodingFormat | A constant from the Image Format Constants in the kony.image namespace that specifies the format of the bitmap image. |
Example
var imgobj = kony.image.createimage(rawbytes); var imgobj = kony.image.createimage(form1.camera1.rawbytes); imgobj.writetomediagallery(); var uniqueimgidentifier; function onsuccess(uniqueidentifier) { uniqueimgidentifier = uniqueidentifier; } config = { imagename: uniqueimgidentifier }; var rawbytesobj = kony.image.findimageingallery(config); form1.img1.rawbytes = rawbytesobj;
Return Values
The Image object's bitmap in RawBytes format if an image format is specified. If not, this method returns the RawBytes data in a platform-specific formats.
Availability
- iOS
- Android
Retrieves the image height as an integer.
Syntax
getImageHeight();
Example
var imgObj = kony.image.createImage(rawBytes); var imgHeight = imgObj.getImageHeight(); kony.print("Image height is:" + imgHeight); form1.img1.rawbytes = rawbytesobj;
Input Parameters
None
Return Values
An integer that specifies the height of the Image.
Availability
- iOS
- Android
Retrieves the image width as an integer.
Syntax
getImageWidth();
Example
var imgObj = kony.image.createImage(rawBytes);
var imgWidth = imgObj.getImageWidth();
kony.print("Image width is:" + imgWidth);
Input Parameters
None
Return Values
An integer that specifies the object of the Image.
Availability
- iOS
- Android
Removes the internal image from the image object.
Syntax
<<imageObject>>.releaseImage();
Example
var imgObj = kony.image.createImage(rawB); imgObj.releaseImage();
Input Parameters
None
Return Values
None
Availability
- iOS
Rotates an imageObject either in a clockwise or counter-clockwise manner, depending on the specified rotation degree.
Syntax
<<imageObject>>.rotate(degree, cropImage);
Input Parameters
Parameter | Description |
---|---|
degree [Number] - Mandatory |
The degree by which the imageObject is to be rotated. You can specify any number for the degree parameter: positive or negative.
For example, rotate(90) ,rotate(-90) , rotate(355.5), and rotate(367.5). |
Example
//Rotate image without crop filter applied
var imageObject = kony.image.createImage("Image.png");
imageObject.rotate(45);
//Rotate image without crop filter applied
var imageObject = kony.image.createImage("Image.png"); imageObject.rotate(45, true);
Return Values
None
Remarks
- The rotate API does not return a new rotated image, instead it rotates the received image.
Platform Availability
- iOS
- Android
Scales the bitmap in the current Image object to a larger or smaller size.
Syntax
scale(scaleFactor);
Input Parameters
Parameter | Description |
---|---|
scaleFactor | A floating point number that is used to scale the bitmap to a larger or smaller size. |
Example
var imgObj = kony.image.createImage(rawB); imgObj.scale(0.4);
Return Values
None
Remarks
The floating point number in the scaleFactor parameter cannot be less than zero. If it is in the range 0.0<=scaleFactor<1.0, the bitmap size will be reduced. Depending on the hardware and the size of the bitmap, distortion or blurring of the image can occur when it is reduced. If scaleFactor equals 1, this method does nothing.
When your app sets scaleFactor to a value greater than 1.0, the size of the bitmap increases. Values greater than 2.0 may result into memory warnings on some platforms. The resultant image quality may differ on platforms due to interpolation algorithms used.
Availability
- iOS
- Android
Writes an image to device's media gallery.
Syntax
writeToMediaGallery(config);
Input Parameters
config
Optional. A dictionary with configurable properties. If you do not specify the config parameter as an argument, the images will be written to the default public location based on the device's OS. You can pass the following properties in the config parameter.
Key | Description |
---|---|
albumName [Optional] | A string that specifies a sub-folder name under the media gallery folder to save images into. You can make use of the property in the following cases:
NOTE: If you do not specify the albumName property in the config parameter, the images will be written to the default public location based on the device's OS. On iOS devices, the images are saved to the On Android devices, the images are saved to the NOTE: If the value of the albumName key is not of String type, an exception is thrown with error code as '100' with the message "Invalid argument." |
imageName [Optional] | A string that specifies a name to an image with which the image should be written to the gallery. The image will be saved to the gallery with the given name without any extension. If any extension is given along with the image name, an exception is thrown with error code '100' with the message "Invalid argument." The cases defined for the albumName property is also applies to the imageName property. If no name is specified to the image, the SDK will give a name to the image, and then write to the gallery. The property is respected only in the Android platform. NOTE: If the value of the imageName key is not of String type, an exception is thrown with error code as '100' with the message "Invalid argument." |
extensionType [Optional] | A constant that specifies the file format type of the image in which the image should be saved to the gallery. The following are the file format constants that you can specify:
The default value of the property is kony.image.ENCODE_JPEG. This parameter is available on all platforms. |
handleRecoverableException [Optional] |
A Boolean value that handles the RecoverableSecurityException that occurs when the overwrite parameter is used to overwrite an image that is owned by another app.
The default value of the property is NOTE: This is an Android-specific parameter and is only applicable on Android 10 (and later) devices. |
A Boolean value that specifies whether or not to overwrite existing images.
The default value of the property is This parameter is available only for Android platform. NOTE: If the value of the overwrite key is not of Boolean type, an exception is thrown with error code as '100' with the message "Invalid argument." |
|
onSuccess [Optional] | A callback function that is invoked when writing the image to the media gallery is successful. You can define your own logic in the callback function. For example, you can define an alert message stating "your photo saved successfully." This parameter is available on all platforms. On IOS, a local device-specific unique identifier (910E7DBE-1DB0-455F-93B3-4500AA93042F/L0/001) is a string of the written image from the media gallery. In case of Android platform, the image name is returned. |
onFailure [Optional] | A callback function is invoked when this function has failed to write an image to the media gallery. When it is invoked, the callback is passed a failure status and an error message. The failure status values can be one of the following.
This parameter is available on all platforms. Example (onFailure) if (statusOfFailure == kony.application.PERMISSION_DENIED) { { } else if (statusOfFailure == kony.image.SAVE_FAILED) { } else if (statusOfFailure == kony.image.INSUFFICIENT_STORAGE) { } kony.print("reason for the failure" + errorMessage); } |
Example
var config = { albumName: "MyAlbum", extensionType: kony.image.ENCODE_PNG, onSuccess: successCallback2, onFailure: failureCallback2 }; var imgName = "sample.png"; var img = kony.image.createImage(imgName); img.writeToMediaGallery(config);
Return Values
None
Remarks
You can make use of the writeToImageGallery
function when end user wants to save an image from your app to device's gallery. The image gets saved to media gallery based on the properties you pass in the config
parameter. If you do not pass the config
parameter to the function, the image gets saved to the device's public location.
On iOS, there is no loss of image quality when you call the writeToImageGallery
function.
Your app may require runtime permissions to access the device's media gallery. For more information on checking, requesting, and obtaining runtime permissions, please see Runtime Permissions API.
From the Quantum Visualizer 202306 release, if the Target SDK API level of the app is set as 33, and the app uses the writeToMediaGallery Method of the Image API, you must enable support for granular media permissions. To do so, navigate to Project Settings > Native > Android Mobile / Tablet, and add the following entries in the Permissions tab based on the type of media files you want to access:
- Enable the
READ_MEDIA_IMAGES
permission to access image files. - Enable the
READ_MEDIA_AUDIO
permission to access audio file. - Enable the
READ_MEDIA_VIDEO
permission to access video files.
Limitations
iOS
To use the writeToImageGallery
function for the iOS platform, open the the app's Info.plist and define the key NSPhotoLibraryUsageDescription. Add reason for accessing the media gallery as a string value to the key. Otherwise, the app crashes.
Android
The directory path of the primary external storage is dependent on the device. When your app calls the writeToImageGallery
function , the function accesses the device's external storage to save the image. Generally, the external storage is an SD card inserted into the device that can store relatively large amount of data. There is also the possibility that the devices uses built-in storage that is distinct from the protected internal storage. The writeToImageGallery
function uses the directory path of the external storage provided by the device's OS for saving images.
Platform Availability
- Android
- iOS 8 and later versions