Image Widget
Image widget is used to display a graphic image such as a company logo, photo, or illustration, in PNG, JPEG,WebP or GIF format, in an application.
Following are the key concepts in Image widget:
-
Image as widget skin: Image widget can be used to display an image as a background skin for a widget. For instance, a back button in a form can have an image depicting the back arrow as its skin.
-
Image when failed and Image while downloading: An image is displayed on a screen when the remote source is not available, or when the remote source is being downloaded.
-
Company logo: Image widget is used to display the company logo in a form.
-
Profile picture: Image widget is used to set the profile picture of a user in an application. The shape of an image can also be changed using the clipView property. For instance, consider the following screen that displays the profile picture of an employee in a circular view.
-
Base 64: When you get base 64 strings from the backend, the image widget is used to display it as an image in an application. For example, in the following employee list screen, the employee images are displayed using the base 64 strings from the backend.
Widgets are normally added to your application using Quantum Visualizer, but can also be added from code. For general information on using widgets in Quantum Visualizer, see Designing an Application in the Visualizer User Guide.
For general information on the Image2 widget see the Image2 topic in the Quantum Visualizer User Guide.
This widget supports drag and drop of images for iOS 11 on iPad.
The Image widget capabilities can be broadly categorized into the following:
- Layout
- Animations
- Data Management
- User Input Handling
- 3D Touch
- UI Appearance
- Enabling RTL
- Miscellaneous
- Configurations Common To All Widgets
Layout
| Events | Description |
|---|---|
| doLayout | This event is invoked for every widget when the widget position and dimensions are computed. |
| Properties | Description |
|---|---|
| anchorPoint | Specifies the anchor point of the widget bounds rectangle using the widget's coordinate space. |
| bottom | Determines the bottom edge of the widget and is measured from the bottom bounds of the parent container. |
| centerX | Determines the center of a widget measured from the left bounds of the parent container. |
| centerY | Determines the center of a widget measured from the top bounds of the parent container. |
| left | Determines the lower left corner edge of the widget and is measured from the left bounds of the parent container. |
| margin | Defines the space around a widget. |
| marginInPixel | Indicates if the margin is to be applied in pixels or in percentage. |
| maxHeight | Specifies the maximum height of the widget and is applicable only when the height property is not specified. |
| maxWidth | Specifies the maximum width of the widget and is applicable only when the width property is not specified. |
| minHeight | Specifies the minimum height of the widget and is applicable only when the height property is not specified. |
| minWidth | Specifies the minimum width of the widget and is applicable only when the width property is not specified. |
| padding | Defines the space between the content of the widget and the widget boundaries. |
| paddingInPixel | Indicates if the padding is to be applied in pixels or in percentage. |
| referenceHeight | The reference image height in pixels. |
| referenceWidth | The reference image width in pixels. |
| top | Determines the top edge of the widget and measured from the top bounds of the parent container. |
| width | Determines the width of the widget and is measured along the x-axis. |
| zIndex | Specifies the stack order of a widget. |
Animations
| Methods | Description |
|---|---|
| animate | Applies an animation to the widget. |
| Properties | Description |
|---|---|
| transform | Contains an animation transformation that can be used to animate the widget. |
| widgetSwipeMove | Used to enable and configure the left or right swipe actions for a widget. |
Data Management
| Methods | Description |
|---|---|
| addOverlayWidgets | Takes an array of widgets as input, which are to be added as overlay widgets on the Image widget. |
| removeOverlayWidgets | Takes an array of widget references as input, which are to be removed as overlay widgets from an Image widget |
| clone | When this method is used on a container widget, then all the widgets inside the container are cloned. |
| Properties | Description |
|---|---|
| cacheConfig | Used to configure the cachePolicy and storagePolicy of the cache responses. |
| src | Specifies the source of the image to be displayed. |
3D Touch
| Methods | Description |
|---|---|
| registerForPeekandPop | Registers a widget to enable 3D Touch peek and pop gestures. |
| setOnPeek | Sets and overrides the existing onPeekCallback for the widget. |
| setOnPop | Overrides the existing onPopCallback for the widget. |
| unregisterForPeekandPop | Unregisters a widget from 3D Touch peek and pop gestures. |
User Input Handling
| Events | Description |
|---|---|
| onScrollWidgetPosition | An event callback is invoked by the platform when the widget location position gets changed on scrolling. |
| onTouchEnd | An event callback is invoked by the platform when the user touch is released from the touch surface. |
| onTouchMove | An event callback is invoked by the platform when the touch moves on the touch surface continuously until movement ends. |
| onTouchStart | An event callback is invoked by the platform when the user touches the touch surface. |
| Methods | Description |
|---|---|
| addGestureRecognizer | Allows you to set a gesture recognizer for a specified gesture for a specified widget. |
| removeGestureRecognizer | Allows you to remove the specified gesture recognizer for the specified widget. |
| setGestureRecognizer | Allows you to set a gesture recognizer for a specified gesture for a specified widget. |
| Properties | Description |
|---|---|
| zoomEnabled | This is a Boolean property that enables zooming capabilities for an Image widget. |
| zoomValue | This is a Float-value property that defines the current zoom state of an Image widget. |
UI Appearance
| Properties | Description |
|---|---|
| blur | You can enable or disable a blur-effect for a widget |
| clipView | Defines a shape to clip the widget view. |
| containerWeight | Specifies percentage of weight to be allocated by its parent widget. |
| glossyEffect | Specifies a glossy effect on an image. |
| hoverSkin | Specifies the look and feel of a widget when the cursor hovers on the widget. |
| imageScaleMode | Specifies how the rendered image's width and height are identified when those of the source image varies from the Image widget itself. |
| opacity | Specifies the opacity of the widget. |
| padding | Defines the space between the content of the widget and the widget boundaries. |
| paddingInPixel | Indicates if the padding is to be applied in pixels or in percentage. |
| renderAsAnchor | To offer an acceptable user experience, one of the image in a segment is made clickable and the onClick event for the segment is bound to a image. |
| shadowDepth | Defines the depth of the shadow effect applied to the Image Widget. |
| skin | Specifies the look and feel of the Image. |
| widgetAlignment | Indicates how a widget is to be anchored with respect to its parent. |
| tintConfig | Sets the tint color and tint mode of the widget. |
| Methods | Description |
|---|---|
| getImageAsRawBytes | Retrieves the image as rawbytes. |
| getImageHeight | Retrieves the image height as an integer. |
| getImageWidth | Retrieves the image width as an integer. |
Enabling RTL
| Properties | Description |
|---|---|
| retainContentAlignment | Helps to retain the content alignment of the widget while applying RTL. |
| retainFlexPositionProperties | Helps to retain the left, right and padding properties while applying RTL. |
| retainFlowHorizontalAlignment | Enables you to change the horizontal flow of the widget from left to right. |
Miscellaneous
| Properties | Description |
|---|---|
| base64 | Returns the base64 encoded string of the image raw bytes. |
| cursorType | Specifies the type of the mouse pointer used. |
| rawBytes | Represents the images raw bytes. |
| Methods | Description |
|---|---|
| getBadge | Enables you to read the badge value (if any) attached to the specified widget. |
| scale | Scales the bitmap in the current Image widget to a larger or smaller size. |
| setBadge | Enables you to set the badge value to the given widget at the upper, right corner of the widget. |
| Events | Description |
|---|---|
| onDownloadComplete | Triggered when the image download from the URL is complete. |
Configurations Common To All Widgets
| Methods | Description |
|---|---|
| blur | Enables you to make the widget look unfocused. |
| convertPointFromWidget | Allows you to convert the coordinate system from a widget to a point (receiver's coordinate system). |
| convertPointToWidget | Allows you to convert the coordinate system from a point (receiver's coordinate system) to a widget. |
| removeFromParent | Allows you to remove a child widget from a parent widget. |
| setEnabled | Specifies the widget that must be enabled or disabled. |
| setFocus | Specifies the widget on which there must be focus. |
| setVisibility | Sets the visibility of the widget. |
| Properties | Description |
|---|---|
| accessibilityConfig | Enables you to control accessibility behavior and alternative text for the widget. |
| enable | Allows you to make a widget visible but not actionable. |
| enableCache | Enables you to improve the performance of Positional Dimension Animations. |
| id | id is a unique identifier of Image consisting of alpha numeric characters. |
| info | A custom JSObject with the key value pairs that a developer can use to store the context with the widget. |
| isVisible | Controls the visibility of a widget on the Form. |
| parent | Helps you access the parent of the widget. |
Image Widget Basics
Creating an Image Using a Constructor: kony.ui.Image2
var myimage = new kony.ui.Image2 (basicConf, layoutConf, pspConf);
- basicConf is an object with basic properties.
- layoutConf is an object with layout properties.
- pspConf is an object with platform specific properties.
NOTE: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored.
Example
//Creating the Image with isVisible:true.
var basicConfImage = {
id: "imageIdTest",
isVisible: true,
src: "http://www.fordesigner.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png",
imageWhenFailed: "rn_icon1.png",
imageWhileDownloading: "new.png"
};
var layoutConfImage = {
containerWeight: 100
};
var PSPConfImage = {
glossyEffect: constants.MAGE_GLOSSY_EFFECT_RADIAL
};
var imageIdTest = new kony.ui.Image2(basicConfImage, layoutConfImage, PSPConfImage);
//Reading the visibility of the Image
alert("Image visibility is ::" + imageIdTest.isVisible);For backward compatibility with support for all deprecated properties and behaviors, use the constructor kony.ui.Image.
var Image1 = new kony.ui.Image(basicConf, layoutConf, pspConf)
Customizing Appearance
You can customize the appearance of the Image widget using the following properties:
- widgetAlignment: Specifies the alignment of the widget.
- margin: Defines the space around a widget.
- padding: Defines the space between the content of the widget and the widget boundaries.
Naming Conventions
To specify a local image, you must add the image file to the resources folder of the Application.
NOTE: For more information on how to add these files, see the Working with Resources section of the Quantum Visualizer User Guide.
The image can be either a bitmap or a vector graphics file.
Image files can be of GIF, animated GIF, JPG, PNG, or WebP formats.
Vector graphics are also supported for the following formats on the following platforms:
- Android supports .xml files
- iOS supports .pdf files
The files that you add must follow a particular naming convention. The following is the naming convention that you must follow:
- The file name must contain only lowercase characters.
- The file name must start only with an alphabet.
- The file name can contain numbers.
- Do not use any reserved words or keywords ( of JavaScript) as the file names for the images.
- Numerical characters.
The following table shows a few examples of valid and invalid file names for the images:
| Valid File Names | Invalid File Names | Remarks |
|---|---|---|
| myicon.PNG | Myicon.png | The file name is invalid because it contains uppercase character. |
| icon2.PNG | Icon_2.png | The file name is invalid because it contains uppercase character and an underscore. |
| accntsummary.PNG | aCCNT&summary.PNG | The file name is invalid because it contains uppercase characters and special character |
| accountdetails.png | Details.PNG | The file name is invalid because it contains uppercase character. |
| flightstatus123.png | continue.PNG | The file name contains a Java keyword. |
NOTE: Quantum Visualizer does not recognize images that have invalid file names.
Image Caching
Image caching is a feature in Quantum Visualizer V8 that ensures that the Image Widget can use URLs as a source for an image. This feature is designed to use the same URL multiple times in an application to load the image as fast as possible with minimal server sync delay.
To configure Image Caching, do the following:
- On your machine where Quantum Visualizer is installed, navigate to Quantum Visualizer project folder: <WorkspaceName>\<ProjectName>\resources\common.
- Open the infoplist_configuration.json file.
- Towards the end of the file, add the following content:
{ “imageWidgetURLCache”: { “cacheSize”:10, // Value should greater than equal to 0 // 0 for max memory “skipServerValidation”:YES //YES for once cached no need to sync with server again to check the updated resource //NO for Sync with the server to check for the updated resource. } } - Save and close the file.
Image caching is enabled in the Quantum cache mechanism.