Kony Widget User Guide

Kony Studio
Cloud and On-Premises Widget

Guide
Release 5.6
Kony Widget User Guide - Ver 17.0
Copyright 2012 Kony, Inc.

All Rights Reserved.
September, 2014
This document contains information proprietary to Kony, Inc., is bound by the Kony license agreements and
may not be used except in the context of understanding the use and methods of Kony Inc, software without
prior, express, written permission. Kony, Empowering Everywhere, Kony MobileFabric, and Kony Visualizer
are trademarks of Kony, Inc. Microsoft, the Microsoft logo, Internet Explorer, Windows, and Windows Vista
are registered trademarks of Microsoft Corporation. Apple, the Apple logo, iTunes, iPhone, iPad, OS X,
Objective-C, Safari, and Xcode are registered trademarks of Apple, Inc. Google, the Google logo, Android,
and the Android logo are registered trademarks of Google, Inc. Chrome is a trademark of Google, Inc.
BlackBerry, PlayBook, Research in Motion, and RIM are registered trademarks of BlackBerry. All other
terms, trademarks, or service marks mentioned in this document have been capitalized and are to be
considered the property of their respective owners.
Copyright 2012 Kony, Inc. All Rights Reserved.Page 2 of 1824
Revision History
Date
Document Version Description of Modifications/Release
31/08/2012
1.0
20/09/2012
09/11/2012
2.0
Document Release. 2D/3DChart wizard is dropped in 5.0 and

future versions will have support for revamped and sophisticated
charts.
Updated onDestroy event for Form and Popup.
3.0
Updated Windows 8 and Desktop Web platform.
14/12/2012
4.0
11/01/2013
5.0
05/03/2013
6.0
05/31/2013
06/20/2013
7/10/2013
8/30/2013
7.0
Updated MenuContainer and enhancements of SegmentedUI

and TabPane.
Updated Windows Phone and minor changes.
New methods added for ScrollBox widget, and info added for
Map V2 for Map Widget. Added SignatureCapture Widget
Updated Windows support for Switch widget.
8.0
New Properties and Methods added for Camera Widget.
9.0
Added Windows 7 Kiosk platform
10.0
9/24/2013
11.0
10/25/2013
12/3/2013
2/21/2014
3/28/2014
12.0
New event added for Browser widget and minor enhancements

Updated 5.5 features. New features added for Calendar, Slider,
SegmentedUi, Map, TextBox, Popup, ScrollBox,
SignatureCapture and Tabpane widgets.
Added BlackBerry 10 platform
13.0
Document Release for 5.5
14.0
Document Release for 5.5.2. Charts widget updated
15.0
Added onCancel event for TextBox
5/13/2014
16.0
Added Accessibility properties for applicable widgets
Widget Level Animation
Minor enhancements for SegmentedUI and ScrollBox

widgets.
iOS7 support for Form, Popup, Slider,RadioButton,

ComboBox, ListBox, and App Menu widgets.
Date
Document Version Description of Modifications/Release

Added new properties in the following widgets for 5.6.2
release:
8/1/2014
17.0
ScrollBox
TabPane
Popup
Calendar
CheckBox
ComboBox
DataGrid
ListBox
RadioButton
TextArea
TextBox
Browser
SegmentedUI
Table of Contents
1. Overview
61
1.1 Scope
61
1.2 Intended Audience
61
1.3 Typographical Conventions
61
1.4 Reference Documents
62
1.5 Contact Us
62
2. Working with Widgets
63
2.1 Widget Classification
64
2.1.1 Container Widgets
64
2.1.2 Basic Widgets
64
2.1.3 Advanced Component Widgets
65
2.2 Widget Methods
65
2.2.1 setVisibility
66
2.2.2 setFocus
69
2.2.3 setEnabled
70
2.2.4 setGestureRecognizer
71
2.2.5 removeGestureRecognizer
75
2.2.6 setBadge
76
2.2.7 getBadge
77
2.3 Widget Skins
79
2.3.1 Dynamic Skinning
80
2.3.2 Platform Specific Skin Limitations
82
3. Container Widgets
85
4. Form
86
4.1 Form - Basic Properties
90
4.1.1 enabledForIdleTimeout
91
4.1.2 footers
92
4.1.3 headers
93
4.1.4 id
94
4.1.5 info
95
4.1.6 menuFocusSkin
96
4.1.7 menuItems
97
4.1.8 menuNormalSkin
98
4.1.9 needAppMenu
99
4.1.10 skin
100
4.1.11 title
101
4.1.12 type
102
4.2 Form - Layout Properties
103
4.2.1 displayOrientation
103
4.2.2 gridCell
105
4.2.3 layoutMeta
106
4.2.4 layoutType
107
4.2.5 padding
108
4.2.6 paddingInPixel
110
4.3 Form - Platform Specific Properties
112
4.3.1 actionBarIcon
113
4.3.2 animateHeaderFooter
113
4.3.3 bounces
114
4.3.4 captureGPS
115
4.3.5 contextPath
117
4.3.6 configureExtendTop
118
4.3.7 configureExtendBottom
118
4.3.8 configureBarStyle
119
4.3.9 defaultIndicatorColor
120
4.3.10 enablePeekGesture
120
4.3.11 extendTop
121
4.3.12 extendBottom
122
4.3.13 statusBarStyle
123
4.3.14 footerOverlap
124
4.3.15 formTransparencyDuringPostShow
125
4.3.16 headerOverlap
126
4.3.17 inputAccessoryViewType
127
4.3.18 inTransitionConfig
130
4.3.19 layout
134
4.3.20 maxAppMenuButtons
135
4.3.21 menuPosition
135
4.3.22 needsIndicatorDuringPostShow
136
4.3.23 noCache
137
4.3.24 outTransitionConfig
138
4.3.25 retainScrollPosition
142
4.3.26 scrollDirection
143
4.3.27 secureData
144
4.3.28 showBottomActionBar
145
4.3.29 showActionBar
146
4.3.30 showActionBarIcon
147
4.3.31 showMiniAppMenu
147
4.3.32 submitSecure
149
4.3.33 titleBar
150
4.3.34 titleBarConfig
151
4.3.35 titleBarSkin
152
4.3.36 viewConfig
153
4.3.37 windowSoftInputMode
155
4.4 Form - Events
157
4.4.1 addWidgets
157
4.4.2 init
158
4.4.3 onActionBarBack
159
4.4.4 onHide
160
4.4.5 onOrientationChange
161
4.4.6 onDeviceBack
161
4.4.7 onDeviceMenu
162
4.4.8 onDestroy
163
4.4.9 preShow
164
4.4.10 postShow
165
4.4.11 onLoadJS
166
4.4.12 unLoadJS
167
4.5 Form - Methods
169
4.5.1 add
169
4.5.2 addAt
170
4.5.3 show
173
4.5.4 destroy
174
4.5.5 remove
175
4.5.6 removeAt
176
4.5.7 replaceAt
179
4.5.8 widgets
182
4.5.9 setTitleBarLeftSideButtonSkin
183
4.5.10 setTitleBarRightSideButtonSkin
183
4.5.11 setTitleBarSkin
184
4.5.12 showTitleBar
185
4.5.13 hideTitleBar
185
4.5.14 scrollToWidget
186
4.5.15 scrollToBeginning
187
4.5.16 scrollToEnd
4.6 Form - Deprecated Properties and Events
187
188
4.6.1 Dockable Appmenu
189
4.6.2 Dockable Header
189
4.6.3 Dockable Footer
190
4.6.4 Enable Back
190
4.6.5 Ignore Escape
191
4.6.6 masterdataload
191
4.6.7 menu Renderer
191
4.6.8 transactionaldataload()
192
4.6.9 undockappheader
192
4.6.10 undockappfooter
193
5. HBox
5.1 HBox - Basic Properties
194
195
5.1.1 focusSkin
195
5.1.2 id
196
5.1.3 info
197
5.1.4 isVisible
198
5.1.5 orientation
199
5.1.6 position
200
5.1.7 skin
202
5.2 HBox - Layout Properties
203
5.2.1 containerWeight
203
5.2.2 gridCell
204
5.2.3 layoutMeta
205
5.2.4 layoutType
206
5.2.5 layoutAlignment
207
5.2.6 margin
208
5.2.7 marginInPixel
210
5.2.8 padding
211
213
5.2.10 percent
214
5.2.11 vExpand
216
5.2.12 widgetAlignment
217
5.3 HBox - Platform Specific Properties
219
5.3.1 blockedUISkin
219
5.3.2 borderCollapse
220
5.3.3 contextMenu
221
5.3.4 hoverSkin
225
5.3.5 viewConfig
226
5.4 HBox - Events
228
5.4.1 onClick
228
5.4.2 onHover
229
5.4.3 onRightClick
232
5.4.4 preOnclickJS
233
5.4.5 postOnclickJS
234
5.5 HBox - Methods
235
5.5.1 add
235
5.5.2 addAt
236
5.5.3 remove
239
5.5.4 removeAt
240
5.5.5 replaceAt
243
5.5.6 widgets
246
5.6 Context Menu- Templates
247
5.6.1 What is a Template for a Context Menu
247
5.6.2 Where to use a Context MenuTemplate
247
5.6.3 Creating a Template for Context Menu
247
5.6.4 Using Context Menu Template
247
6. VBox
6.1 VBox - Basic Properties
249
250
6.1.1 focusSkin
250
6.1.2 id
251
6.1.3 info
252
6.1.4 isVisible
253
6.1.5 orientation
254
6.1.6 skin
255
6.2 VBox - Layout Properties
256
256
6.2.2 gridCell
257
6.2.3 layoutMeta
258
6.2.4 layoutType
260
261
6.2.6 margin
262
6.2.7 marginInPixel
264
6.2.8 padding
265
267
268
6.3 VBox - Platform Specific Properties
270
6.3.1 blockedUISkin
270
271
6.3.3 contextMenu
272
6.3.4 hoverSkin
276
6.3.5 viewConfig
277
6.4 VBox - Events
278
6.4.1 onClick
278
6.4.2 onHover
279
6.4.3 onRightClick
282
6.4.4 preOnclickJS
283
6.4.5 postOnclickJS
284
6.5 VBox - Methods
285
6.5.1 add
285
6.5.2 addAt
286
6.5.3 remove
289
6.5.4 removeAt
290
6.5.5 replaceAt
293
6.5.6 widgets
296
298
298
298
298
298
7. ScrollBox
300
7.1 ScrollBox - Basic Properties
302
7.1.1 enableScrollByPage
302
7.1.2 id
303
7.1.3 info
304
7.1.4 isVisible
305
7.1.5 orientation
306
7.1.6 position
307
7.1.7 pullToRefreshI18NKey
308
7.1.8 pullToRefreshSkin
309
7.1.9 pushToRefreshI18NKey
310
7.1.10 pushToRefreshSkin
310
7.1.11 releaseToPullRefreshI18NKey
311
7.1.12 releaseToPushRefreshI18NKey
312
312
7.1.14 showScrollbars
313
7.1.15 skin
314
7.2 ScrollBox - Layout Properties
315
7.2.1 containerHeight
316
7.2.2 containerHeightReference
317
318
319
7.2.5 margin
320
7.2.6 marginInPixel
322
7.2.7 padding
323
325
7.2.9 percent
326
7.3 ScrollBox - Platform Specific Properties
327
7.3.1 bounces
327
7.3.2 contextMenu
328
7.3.3 scrollArrowConfig
330
7.3.4 viewConfig
331
7.4 ScrollBox - Events
333
7.4.1 scrollingEvents
333
7.5 ScrollBox - Methods
336
7.5.1 add
336
7.5.2 addAt
337
7.5.3 remove
338
7.5.4 removeAt
339
340
7.5.6 scrollToEnd
341
342
7.5.8 widgets
343
8. TabPane
8.1 TabPane - Basic Properties
345
348
8.1.1 activeFocusSkin
348
8.1.2 activeSkin
349
8.1.3 activeTabs
350
8.1.4 id
351
8.1.5 inactiveSkin
352
8.1.6 info
353
8.1.7 isVisible
354
8.1.8 retainPositionInTab
355
8.1.9 screenLevelWidget
356
8.1.10 viewConfig
357
8.1.11 viewType
359
8.2 TabPane - Layout Properties
360
361
362
363
8.2.4 gridCell
364
8.2.5 layoutMeta
365
8.2.6 layoutType
367
8.2.7 margin
368
8.2.8 marginInPixel
370
8.2.9 padding
371
373
8.3 TabPane - Platform Specific Properties
374
8.3.1 pageSkin
374
8.3.2 progressIndicatorColor
376
8.3.3 showProgressIndicator
377
8.3.4 tabHeaderTemplate
378
8.3.5 tabHeaderHeight
378
8.4 TabPane - Events
380
8.4.1 onTabClick
380
8.4.2 preOnclickJS
381
8.4.3 postOnclickJS
382
8.5 TabPane - Methods
384
8.5.1 addTab
384
8.5.2 addTab
385
8.5.3 addTabAt
386
8.5.4 removeTabAt
387
8.5.5 removeTabByld
388
8.6 Tab header - Templates
390
8.6.1 What is a Template for tabHeader and where to use it
390
8.6.2 Creating a Template for tabHeader
390
8.6.3 Using tabHeader Template
390
9. Popup
9.1 Popup - Basic Properties
392
394
9.1.1 footers
395
9.1.2 headers
396
9.1.3 id
396
9.1.4 info
397
9.1.5 isModal
398
9.1.6 skin
399
9.1.7 title
400
9.1.8 transparencyBehindThePopup
401
9.2 Popup - Layout Properties
403
403
404
405
9.2.4 gridCell
406
9.2.5 layoutMeta
407
9.2.6 layoutType
408
9.2.7 padding
409
411
9.3 Popup - Platform Specific Properties
413
9.3.1 bounces
413
9.3.2 captureGPS
414
9.3.3 contextPath
416
416
9.3.5 draggable
417
9.3.6 extendTop
418
9.3.7 footerOverlap
419
9.3.8 headerOverlap
420
420
423
9.3.11 layout
426
9.3.12 minimizeOnLostFocus
427
9.3.13 noCache
428
429
9.3.15 popupStyle
431
9.3.16 resizable
432
9.3.17 secureData
433
434
9.3.19 submitSecure
435
436
9.3.21 viewConfig
437
439
9.4 Popup - Events
441
9.4.1 addWidgets
441
9.4.2 init
441
9.4.3 onHide
442
9.4.4 onDeviceBack
443
9.4.5 onLoadJS
444
9.4.6 unLoadJS
445
9.5 Popup - Methods
447
9.5.1 add
447
9.5.2 addAt
448
9.5.3 destroy
449
9.5.4 dismiss
450
9.5.5 navigateTo
451
9.5.6 remove
452
9.5.7 removeAt
453
454
9.5.9 scrollToEnd
455
455
9.5.11 setContext
456
458
459
460
9.5.15 showTitleBar
461
9.5.16 hideTitleBar
462
9.5.17 show
462
9.5.18 widgets
463
9.6 Popup - Deprecated Properties
464
9.6.1 closureLeftSideView
465
9.6.2 closureRightSideView
466
9.6.3 dockableAppMenu
466
9.6.4 imageLeftSideView
466
9.6.5 imageRightSideView
467
9.6.6 nift
467
467
9.6.8 orientationmode
468
9.6.9 renderTitleText
468
9.6.10 reset Focus to top of the Form
468
9.6.11 skin Around Popup
469
9.6.12 titleBar
469
9.6.13 titleBarLeftSideView
470
9.6.14 titleBarRightSideView
470
10. Basic Widgets
471
11. Button
472
11.1 Button - Basic Properties
475
11.1.1 focusSkin
475
11.1.2 id
476
11.1.3 info
477
11.1.4 isVisible
478
11.1.5 rawBytes
479
11.1.6 skin
480
11.1.7 text
11.2 Button - Layout Properties
481
482
482
11.2.2 contentAlignment
483
11.2.3 displayText
485
11.2.4 hExpand
486
11.2.5 margin
488
11.2.6 marginInPixel
490
11.2.7 padding
491
493
11.2.9 vExpand
494
495
11.3 Button - Platform Specific Properties
497
11.3.1 blockedUISkin
497
11.3.2 contextMenu
498
11.3.3 externalURL
500
11.3.4 glowEffect
501
11.3.5 hoverSkin
502
11.3.6 pressedSkin
503
504
11.3.8 submitURL
505
11.3.9 toolTip
506
11.4 Button - Events
507
11.4.1 onClick
507
11.4.2 preOnclickJS
508
11.4.3 postOnclickJS
509
11.5 Button - Deprecated Properties

11.5.1 focusimage
510
510
11.5.2 image
511
11.5.3 normalimage
511
12. Calendar
12.1 Calendar - Basic Properties
512
519
12.1.1 calendarIcon
519
12.1.2 dateComponents
520
12.1.3 dateFormat
522
12.1.4 day
523
12.1.5 focusSkin
524
12.1.6 formattedDate
525
12.1.7 hour
526
12.1.8 id
527
12.1.9 info
528
12.1.10 isVisible
529
12.1.11 minutes
530
12.1.12 month
531
12.1.13 placeholder
532
12.1.14 seconds
533
12.1.15 skin
534
12.1.16 validStartDate
535
12.1.17 validEndDate
536
12.1.18 viewConfig
537
12.1.19 viewType
539
12.1.20 year
541
12.2 Calendar - Layout Properties
541
542
543
12.2.3 hExpand
544
12.2.4 margin
546
548
12.2.6 padding
549
551
12.2.8 vExpand
552
554
12.3 Calendar-Platform Specific Properties
555
12.3.1 cellTemplate
556
557
558
12.3.4 dateEditable
559
12.3.5 data
560
12.3.6 dayTextAlignmentInCell
562
12.3.7 displayedMonth
563
12.3.8 hideDaysHeader
564
12.3.9 hideMonthsHeader
565
12.3.10 hoverSkin
566
12.3.11 mode
567
12.3.12 noOfMonths
568
12.3.13 titleOnPopup
569
12.3.14 toolTip
570
12.3.15 widgetDataMapForCell
571
12.4 Calendar - Event
573
12.4.1 onSelection
573
12.5 Calendar - Methods
574
12.5.1 clear
574
12.5.2 clearData
575
12.5.3 enableRangeOfDates
576
12.5.4 navigateToPreviousMonth
577
12.5.5 navigateToNextMonth
578
12.5.6 removeDataAt
579
12.5.7 setData
580
12.5.8 setDataAt
581
12.5.9 setEnabled
582
12.5.10 setEnableAll
584
12.5.11 setDatesSkin
585
12.6 Calendar - Deprecated Properties
586
12.6.1 date
586
12.6.2 format
588
12.6.3 monthI18Nkey
588
12.6.4 weekdayI18Nkey
589
12.7 gridcalender - Templates
589
12.7.1 What is a Template for gridcalendar
589
12.7.2 Where to use a gridcalendar Template
590
12.7.3 Creating a Template for gridcalendar
590
12.7.4 Using gridcalendar Template
590
13. CheckBoxGroup
13.1 CheckBox - Basic Properties
592
596
13.1.1 focusSkin
596
13.1.2 id
597
13.1.3 info
598
13.1.4 isVisible
599
13.1.5 masterData
600
13.1.6 masterDataMap
602
13.1.7 selectedKeys
604
13.1.8 selectedKeyValues
605
13.1.9 skin
13.2 CheckBox - Layout Properties
605
606
607
13.2.2 itemOrientation
607
13.2.3 margin
608
610
13.2.5 padding
611
613
614
13.3 CheckBox - Platform Specific Properties
616
13.3.1 focusTickedImage
616
13.3.2 focusUnTickedImage
617
13.3.3 groupCells
617
13.3.4 hoverSkin
619
13.3.5 tickedImage
619
13.3.6 toolTip
620
13.3.7 unTickedImage
621
13.3.8 viewType
622
13.3.9 wheelBackgroundColor
625
13.4 CheckBox - Events
627
13.4.1 onSelection
627
13.4.2 preOnclickJS
628
629
14. ComboBox
14.1 ComboBox - Basic Properties
631
635
14.1.1 focusSkin
636
14.1.2 id
637
14.1.3 info
638
14.1.4 isVisible
639
14.1.5 masterData
640
642
14.1.7 selectedKey
643
14.1.8 selectedKeyValue
644
14.1.9 skin
645
14.2 ComboBox - Layout Properties
646
646
647
14.2.3 hExpand
648
14.2.4 margin
649
651
14.2.6 padding
652
654
14.2.8 vExpand
655
657
14.3 ComboBox - Platform Specific Properties
659
659
14.3.2 dropDownImage
660
14.3.3 groupCells
661
14.3.4 hoverSkin
662
14.3.5 placeholder
663
14.3.6 popupFocusSkin
664
14.3.7 popupSkin
665
14.3.8 popupTitle
665
14.3.9 tickedImage
666
14.3.10 toolTip
667
668
14.3.12 viewType
669
14.3.13 viewConfig
673
675
14.4 ComboBox- Events
676
14.4.1 onSelection
676
14.4.2 preOnclickJS
677
678
14.5 ComboBox - Deprecated Properties

14.5.1 placeholderi18nKey
15. DataGrid
15.1 DataGrid - Basic Configuration Properties
678
679
680
684
15.1.1 columnHeadersConfig
684
15.1.2 data
686
15.1.3 gridHeight
689
15.1.4 headerSkin
690
15.1.5 id
691
15.1.6 info
692
15.1.7 isMultiSelect
693
15.1.8 isVisible
695
15.1.9 rowAlternateSkin
696
15.1.10 rowCount
697
15.1.11 rowFocusSkin
698
15.1.12 rowNormalSkin
699
15.1.13 scrollable
700
15.1.14 selectedIndex
701
15.1.15 selectedIndices
702
15.1.16 selectedItem
703
15.1.17 selectedItems
705
15.1.18 showColumnHeaders
706
15.2 DataGrid - Layout Properties
707
707
708
15.2.3 margin
710
15.2.4 padding
712
714
15.3 DataGrid - Platform Specific Properties
717
717
15.3.2 containerHeightInPixel
718
15.3.3 dockingHeader
719
15.3.4 enableScrollBar
720
15.3.5 gridlineColor
721
15.3.6 hoverSkin
722
15.3.7 selectedCellItem
723
15.3.8 selectedCellIndex
724
15.3.9 toolTip
725
15.4 DataGrid - Events

15.4.1 onRowSelected
15.5 DataGrid - Methods
727
727
729
15.5.1 addAll
729
15.5.2 addDataAt
730
15.5.3 applyCellSkin
731
15.5.4 removeAll
733
15.5.5 removeAt
734
15.5.6 selectAllRows
735
15.5.7 setCellDataAt
736
15.5.8 setData
737
15.5.9 setDataAt
15.6 DataGrid - Templates
739
741
15.6.1 What is a Template for DataGrids
741
15.6.2 Where to use a Grid Template
741
15.6.3 Creating a Template for DataGrid
741
15.6.4 Using Grid Template
742
16. Image
16.1 Image - Basic Properties
743
745
16.1.1 base64
746
16.1.2 id
747
16.1.3 imageWhenFailed
748
16.1.4 imageWhileDownloading
749
16.1.5 info
750
16.1.6 isVisible
751
16.1.7 rawBytes
752
16.1.8 src
753
16.2 Image - Layout Properties
754
754
16.2.2 imageScaleMode
755
16.2.3 margin
760
762
16.2.5 padding
763
765
16.2.7 referenceHeight
766
16.2.8 referenceWidth
767
768
16.3 Image - Platform Specific Properties

16.3.1 glossyEffect
770
770
16.3.2 hoverSkin
771
16.3.3 renderAsAnchor
772
16.3.4 skin
773
16.3.5 toolTip
774
16.4 Image - Events
775
16.4.1 onDownloadComplete
775
16.5 Image - Deprecated Properties
776
16.5.1 hExpand
776
16.5.2 scaleMode
777
16.5.3 vExpand
778
17. Label
17.1 Label - Basic Properties
780
782
17.1.1 id
782
17.1.2 info
783
17.1.3 isVisible
784
17.1.4 skin
785
17.1.5 text
786
17.1.6 toolTip
787
17.2 Label - Layout Properties
788
788
789
17.2.3 hExpand
791
17.2.4 margin
793
795
17.2.6 padding
796
798
17.2.8 vExpand
799
800
17.3 Label - Platform Specific Properties
802
17.3.1 hoverSKin
802
17.3.2 pasteboardType
803
804
17.3.4 textCopyable
805
17.3.5 toolTip
806
17.3.6 wrapping
807
18. Line
18.1 Line - Basic Properties
809
811
18.1.1 id
811
18.1.2 info
812
18.1.3 isVisible
813
18.1.4 skin
814
18.2 Line - Layout Properties
815
18.2.1 margin
815
817
18.2.3 thickness
818
18.3 Line - Platform Specific Properties
819
18.3.1 toolTip
819
18.3.2 Line - Platform Specific Properties
821
19. Link
19.1 Link - Basic Properties
822
825
19.1.1 focusSkin
825
19.1.2 id
826
19.1.3 info
827
19.1.4 isVisible
828
19.1.5 skin
829
19.1.6 text
830
19.1.7 toolTip
831
19.2 Link - Layout Properties
832
832
833
19.2.3 hExpand
835
19.2.4 margin
836
838
19.2.6 padding
839
841
842
19.3 Link - Platform Specific Properties
844
844
19.3.2 contextMenu
845
19.3.3 externalURL
847
19.3.4 glowEffect
848
19.3.5 hoverSkin
849
850
19.3.7 submitURL
851
19.3.8 toolTip
852
19.4 Link - Events
854
19.4.1 onClick
854
19.4.2 preOnclickJS
855
856
19.5 Link - Deprecated Properties
857
19.5.1 focusImage
857
19.5.2 image
858
19.5.3 normalImage
858
20. ListBox
859
20.1 ListBox - Basic Properties
860
20.1.1 focusSkin
861
20.1.2 id
862
20.1.3 info
863
20.1.4 isVisible
864
20.1.5 masterData
865
867
20.1.7 selectedKey
869
20.1.8 selectedKeys
870
870
871
20.1.11 skin
872
20.2 ListBox - Layout Properties
873
874
874
20.2.3 hExpand
876
20.2.4 margin
877
879
20.2.6 padding
880
882
20.2.8 vExpand
883
885
20.3 ListBox - Platform Specific Properties
887
20.3.1 applySkinsToPopup
887
889
890
20.3.4 groupCells
891
20.3.5 hoverSkin
892
20.3.6 multiSelect
893
20.3.7 multiSelectRows
894
20.3.8 nativeListFieldSkin
894
20.3.9 nativeListFieldFocusSkin
895
20.3.10 placeholder
896
20.3.11 placeholderSkin
898
20.3.12 popupIcon
898
20.3.13 popupTitle
900
20.3.14 tickedImage
901
20.3.15 toolTip
902
902
20.3.17 viewType
903
20.3.18 viewConfig
907
908
20.4 ListBox - Events
910
20.4.1 onSelection
910
20.4.2 preOnclickJS
911
912
20.5 ListBox - Deprecated Properties
913
20.5.1 listStyle
913
20.5.2 multiple
914
915
20.5.4 selectedKey
915
916
21. MenuContainer
21.1 MenuContainer - Basic Properties
917
921
21.1.1 activeSkin
921
21.1.2 data
923
21.1.3 hoverSkin
925
21.1.4 id
926
21.1.5 info
928
21.1.6 isVisible
929
21.1.7 menuItemTemplate
930
21.1.8 orientation
932
21.1.9 selectedMenuIndex
933
21.1.10 selectedMenuItem
934
21.1.11 skin
936
21.1.12 widgetDataMap
938
21.2 MenuContainer - Layout Properties
939
939
21.2.2 margin
941
943
21.2.4 padding
944
947
948
21.3 MenuContainer - Platform Specific Properties
949
21.3.1 contextMenu
950
21.3.2 collapsedImage
952
21.3.3 expandedImage
954
21.3.4 viewType
955
21.4 MenuContainer - Event
958
21.4.1 onClick
958
21.4.2 onRightClick
960
21.5 MenuContainer - Methods
963
21.5.1 addAll
963
21.5.2 addDataAt
965
21.5.3 removeAll
967
21.5.4 removeAt
968
21.5.5 setData
970
21.5.6 setDataAt
972
21.6 Menu - Templates
975
21.6.1 What is a Template for Menu
975
21.6.2 Where to use a Menu Template
975
21.6.3 Creating a Template for Menu
975
21.6.4 Using Menu Templates
976
22. MenuItem
22.1 MenuItem - Basic Properties
978
980
22.1.1 focusImage
980
22.1.2 id
981
22.1.3 info
981
22.1.4 image
982
22.1.5 title
983
22.1.6 type
983
22.2 Menuitem - Event
985
22.2.1 onClick
985
23. RadioButtonGroup
986
23.1 RadioButtonGroup - Basic Properties
990
23.1.1 focusSkin
990
23.1.2 id
991
23.1.3 info
992
23.1.4 isVisible
993
23.1.5 masterData
994
996
23.1.7 selectedKey
998
23.1.9 skin
23.2 RadioButtonGroup - Layout Properties
999
1000
1001
1001
23.2.2 hExpand
1002
1003
23.2.4 margin
1005
1007
23.2.6 padding
1008
1010
23.2.8 vExpand
1011
1013
23.3 RadioButtonGroup - Platform Specific Properties
1015
1015
1016
1017
23.3.4 groupCells
1018
23.3.5 hoverSkin
1019
23.3.6 placeholder
1020
23.3.7 tickedImage
1021
23.3.8 toolTip
1022
1023
23.3.10 viewType
1024
23.3.11 viewConfig
1028
1029
23.4 RadioButtonGroup - Events
1031
23.4.1 onSelection
1031
23.4.2 preOnclickJS
1032
24. RichText
24.1 RichText - Basic Properties
1033
1035
1038
24.1.1 id
1039
24.1.2 info
1039
24.1.3 isVisible
1040
24.1.4 linkSkin
1041
24.1.5 skin
1042
24.1.6 text
1043
24.2 RichText - Layout Properties
1044
1044
1045
24.2.3 hExpand
1047
24.2.4 margin
1048
1050
24.2.6 padding
1051
1053
24.2.8 vExpand
1054
1056
24.3 RichText - Platform Specific Properties
1057
24.3.1 hoverSkin
1057
24.3.2 linkFocusSkin
1058
24.3.3 superScriptSkin
1059
24.3.4 telephoneLinkSkin
1060
24.3.5 toolTip
1061
24.3.6 wrapping
1061
24.4 RichText - Events

24.4.1 onClick
1064
1064
24.4.2 preOnclickJS
1065
1066
25. Slider
25.1 Slider - Basic Configuration Properties
1068
1070
25.1.1 focusThumbImage
1071
25.1.2 id
1072
25.1.3 info
1072
25.1.4 isVisible
1074
25.1.5 leftSkin
1075
25.1.6 max
1076
25.1.7 min
1077
25.1.8 rightSkin
1078
25.1.9 selectedValue
1079
25.1.10 step
1080
25.1.11 thumbImage
1081
25.2 Slider - Layout Properties
1082
1083
25.2.2 margin
1084
1086
1087
25.3 Slider - Platform Specific Properties
1089
25.3.1 enableThumbTintColor
1089
25.3.2 maxLabel
1090
25.3.3 maxLabelSkin
1091
25.3.4 maxValueImage
1092
25.3.5 minLabel
1093
25.3.6 minLabelSkin
1094
25.3.7 minValueImage
1095
25.3.8 orientation
1096
25.3.9 thickness
1097
25.3.10 thumbOffset
1098
25.3.11 thumbTintColor
1099
25.3.12 viewType
1100
25.4 Slider - Events
1102
25.4.1 onSelection
1102
25.4.2 onSlide
1103
26. TextArea
26.1 TextArea - Basic Properties
1105
1108
26.1.1 autoCapitalize
1108
26.1.2 focusSkin
1109
26.1.3 id
1110
26.1.4 info
1111
26.1.5 isVisible
1112
26.1.6 keyBoardStyle
1113
26.1.7 maxTextLength
1116
26.1.8 numberOfVisibleLines
1117
26.1.9 placeholder
1118
26.1.10 secureTextEntry
1119
26.1.11 skin
1120
26.1.12 text
1121
26.1.13 textInputMode
1122
26.2 TextArea - Layout Properties
1124
1124
1125
26.2.3 hExpand
1126
26.2.4 margin
1128
1130
26.2.6 padding
1131
1133
1134
26.3 TextArea - Platform Specific Properties
1137
26.3.1 autoCorrect
1137
1138
26.3.3 closeButtonText
1139
26.3.4 hoverSkin
1141
26.3.5 keyboardActionLabel
1142
1143
1145
26.3.8 showCloseButton
1146
1148
26.3.10 toolTip
1149
26.4 TextArea - Events
1149
26.4.1 onDone
1150
26.4.2 onBeginEditing
1151
26.4.3 onEndEditing
1152
26.4.4 onKeyUp
1153
26.4.5 onKeyDown
1154
26.4.6 onTextChange
1154
26.5 TextArea - Deprecated Properties
1155
26.5.1 editable
1155
26.5.2 No of Rows
1156
27. TextBox
27.1 TextBox - Basic Properties
1157
1160
1160
27.1.2 focusSkin
1162
27.1.3 id
1163
27.1.4 info
1164
27.1.5 isVisible
1165
1166
1169
27.1.8 placeholder
1170
1171
27.1.10 skin
1172
27.1.11 text
1173
1174
27.1.13 toolTip
1175
27.2 TextBox - Layout Properties
1177
1177
1178
27.2.3 containerHeightMode
1179
1180
1181
27.2.6 hExpand
1182
27.2.7 margin
1184
1186
27.2.9 padding
1187
1189
1190
27.3 TextBox - Platform Specific Properties
1192
27.3.1 autoComplete
1192
27.3.2 autoCorrect
1194
27.3.3 autoFilter
1195
1197
1198
27.3.6 filterList
1200
27.3.7 hoverSkin
1201
1201
27.3.9 leftViewImage
1203
1204
1205
1206
1207
27.3.14 showClearButton
1209
1210
1212
27.3.17 toolTip
1213
27.3.18 viewType
1213
27.4 TextBox - Events
1215
27.4.1 onCancel
1216
27.4.2 onDone
1217
1218
27.4.4 onEndEditing
1218
27.4.5 onKeyUp
1220
27.4.6 onKeyDown
1221
27.4.7 onTextChange
1222
27.4.8 preOnclickJS
1223
1223
27.5 TextBox - Deprecated Properties
1224
27.5.1 inputStyle
1224
27.5.2 keyBoardType
1225
27.5.3 Type
1228
28. Advanced Widgets
1229
29. Browser
1230
29.1 Browser - Basic Properties
1234
29.1.1 detectTelNumber
1234
29.1.2 enableZoom
1235
29.1.3 htmlString
1236
29.1.4 id
1237
29.1.5 info
1238
29.1.6 isVisible
1239
29.1.7 requestURLConfig
1240
1241
29.2 Browser - Layout Properties
1243
1243
1244
1245
29.2.4 margin
1246
1248
29.3 Browser - Events
1249
29.3.1 handleRequest
1249
29.3.2 onFailure
1250
29.3.3 onSuccess
1251
1252
29.4 Browser - Methods
1254
29.4.1 canGoBack
1255
29.4.2 canGoForward
1256
29.4.3 clearHistory
1256
29.4.4 goBack
1257
29.4.5 goForward
1258
29.4.6 reload
1259
29.5 Browser - Deprecated Properties

29.5.1 masterData
30. Camera
30.1 Camera - Basic Properties
1260
1260
1262
1266
30.1.1 base64
1266
30.1.2 compressionLevel
1267
30.1.3 focusSkin
1268
30.1.4 id
1269
30.1.5 info
1270
30.1.6 isVisible
1271
30.1.7 maxSideOfTheImage
1272
30.1.8 rawBytes
1273
30.1.9 scaleFactor
1274
30.1.10 skin
1275
30.1.11 text
1276
30.2 Camera - Layout Properties
1276
1277
1278
30.2.3 hExpand
1279
30.2.4 margin
1281
1283
30.2.6 padding
1284
1286
30.2.8 vExpand
1287
1288
30.3 Camera - Platform Specific Properties
1289
30.3.1 accessMode
1290
30.3.2 cameraOptions
1291
30.3.3 captureOrientation
1293
30.3.4 enableOverlay
1294
30.3.5 enablePhotoCropFeature
1295
30.3.6 hoverSkin
1296
30.3.7 imageFormat
1297
30.3.8 nativeUserInterface
1298
30.3.9 overlayConfig
1299
30.3.10 toolTip
1301
30.4 Camera - Event
1302
30.4.1 onCapture
1302
30.5 Camera - Methods
1302
30.5.1 closeCamera
1303
30.5.2 releaseRawBytes
1304
30.5.3 takePicture
1305
30.6 Camera - Deprecated Properties
1306
30.6.1 Auto store to disk
1306
30.6.2 mode
1307
31. HorizontalImageStrip
31.1 HorizontalImageStrip - Basic Properties
1310
1312
31.1.1 arrowConfig
1313
31.1.2 data
1314
31.1.3 focusSkin
1315
31.1.4 id
1316
1317
1318
31.1.7 info
1319
31.1.8 isVisible
1320
1321
1322
31.1.11 showArrows
1323
1324
31.1.13 skin
1325
31.1.14 spaceBetweenImages
1326
31.1.15 viewConfig
1327
31.1.16 viewType
1328
31.2 HorizontalImageStrip - Layout Properties
1333
1333
1334
31.2.3 margin
1339
1341
31.2.5 padding
1342
1345
1346
1347
1348
31.3 HorizontalImageStrip - Platform Specific Properties
1349
31.3.1 hoverSkin
1349
31.3.2 toolTip
1350
31.4 HorizontalImageStrip - Events
1352
31.4.1 onSelection
1352
31.4.2 preOnclickJS
1353
1354
31.5 HorizontalImageStrip - Methods

31.5.1 addAll
1356
1356
31.5.2 addDataAt
1357
31.5.3 removeAll
1358
31.5.4 removeAt
1359
31.5.5 setData
1360
31.5.6 setDataAt
1362
31.6 HorizontalImageStrip - Deprecated
1363
31.6.1 frameHeight
1363
31.6.2 height
1363
31.6.3 viewConfig
1364
31.6.4 width
1365
32. ImageGallery
32.1 ImageGallery - Basic Properties
1366
1368
32.1.1 data
1368
32.1.2 focusSkin
1369
32.1.3 id
1370
1371
1372
32.1.6 info
1372
32.1.7 isVisible
1374
1375
32.1.9 selectedItem
1376
32.1.10 skin
1376
1377
32.2 ImageGallery - Layout Properties
1378
1378
1379
32.2.3 margin
1384
1386
1387
1388
32.3 ImageGallery - Platform Specific Properties
1390
32.3.1 hoverSkin
1390
32.3.2 itemsPerRow
1391
32.3.3 navigationBarPosition
1391
32.3.4 noofRowsPerPage
1392
32.3.5 viewType
1393
32.3.6 viewConfig
1394
32.4 ImageGallery - Events
1396
32.4.1 onSelection
1396
32.4.2 preOnclickJS
1397
1398
32.5 ImageGallery - Methods
1400
32.5.1 addAll
1400
32.5.2 addDataAt
1401
32.5.3 removeAll
1402
32.5.4 removeAt
1403
32.5.5 setData
1403
32.5.6 setDataAt
1405
32.6 ImageGallery - Deprecated Properties
1406
32.6.1 frameHeight
1406
32.6.2 height
1407
32.6.3 width
1407
32.6.4 showItemCount
1408
33. Map
1409
33.1 Map - Basic Properties
1417
33.1.1 calloutTemplate
1418
33.1.2 calloutWidth
1418
33.1.3 defaultPinImage
1419
33.1.4 id
1420
33.1.5 info
1421
33.1.6 isVisible
1422
33.1.7 locationData
1423
33.1.8 mapKey
1424
33.1.9 provider
1425
1426
33.1.11 widgetDataMapForCallout
1427
33.2 Map - Layout Properties
1428
1428
1429
1430
33.2.4 margin
1431
1433
33.3 Map - Platform Specific Properties
1435
33.3.1 address
1435
33.3.2 mapHeight
1436
33.3.3 mapSource
1437
33.3.4 mapWidth
1438
33.3.5 mode
1439
33.3.6 navControlsImageConfig
1442
33.3.7 showCurrentLocation
1443
33.3.8 showZoomControl
1444
33.3.9 zoomLevel
1445
33.4 Map - Events
1447
33.4.1 onClick
1447
33.4.2 onPinClick
1448
33.4.3 onSelection
1449
33.5 Map - Methods
1450
33.5.1 addPolyline
1450
33.5.2 clear
1452
33.5.3 dismissCallout
1453
33.5.4 getBounds
1453
33.5.5 navigateTo
1454
33.5.6 navigateToLocation
1455
33.5.7 removePolyline
1457
33.6 Map - Templates
1458
33.6.1 What is a Template for Map callout
1458
33.6.2 Where to use a Map callout Template
1458
33.6.3 Creating a Template for Map callout
1458
33.6.4 Using Map callout Template
1458
33.7 Appendix: Generating and Configuring Map API Keys
1459
33.7.1 Application Level Map Widget Key
1459
33.7.2 Google Map Key for Android
1461
33.7.3 Bing Map Key for Windows
1463
33.7.4 Appendix: Generating and Configuring Map API Keys
1463
1467
1471
34. ObjectSelector3D
34.1 ObjectSelector3D - Basic Properties
1476
1479
34.1.1 focusSkin
1479
34.1.2 id
1480
34.1.3 info
1481
34.1.4 isVisible
1482
34.1.5 skin
1483
34.1.6 text
1484
34.2 ObjectSelector3D - Layout Properties
1485
1485
1486
34.2.3 hExpand
1487
34.2.4 margin
1489
1491
34.2.6 padding
1492
1494
34.2.8 vExpand
1495
1496
34.3 ObjectSelector3D - Event

34.3.1 onSelectionDone
34.4 ObjectSelector3D - Methods
1498
1498
1499
34.4.1 addModel
1499
34.4.2 clearAllData
1500
34.4.3 defineSpecialModels
1501
34.4.4 getSelectedCells
1502
34.4.5 setCameraProperties
1503
34.4.6 setMapData
1504
34.4.7 setRequiredSelectionsCount
1505
34.4.8 setSelectedCells
1506
35. Phone
35.1 Phone - Basic Properties
1508
1510
35.1.1 focusSkin
1510
35.1.2 id
1511
35.1.3 isVisible
1511
35.1.4 skin
1512
35.1.5 text
1512
35.2 Phone - Layout Properties
1513
1513
1514
35.2.3 hExpand
1515
35.2.4 margin
1516
1518
35.2.6 padding
1519
1520
35.2.8 vExpand
1521
1522
36. PickerView
36.1 PickerView - Basic Properties
1524
1527
36.1.1 focusSkin
1527
36.1.2 id
1529
36.1.3 info
1530
36.1.4 isVisible
1531
36.1.5 masterData
1532
1534
36.1.7 selectedKeys
1536
1537
36.1.9 skin
1538
36.2 PickerView - Layout Properties
1539
1539
36.2.2 hExpand
1540
36.2.3 margin
1542
1544
1545
36.3 PickerView - Event
1546
36.3.1 onSelection
1546
36.4 PickerView - Methods
1547
36.4.1 setComponentData
1548
36.4.2 setSelectedKeyInComponent
1549
37. SegmentedUI
37.1 SegmentedUI - Basic Properties
1551
1558
37.1.1 alternateRowSkin
1559
37.1.2 data
1560
37.1.3 groupCells
1563
37.1.4 id
1565
37.1.5 info
1566
37.1.6 isVisible
1567
37.1.7 needPageIndicator
1568
37.1.8 orientation
1569
37.1.9 pageOnDotImage
1571
37.1.10 pageOffDotImage
1572
1573
1573
1574
1575
1576
1576
37.1.17 retainSelection
1577
37.1.18 rowSkin
1578
1579
37.1.20 rowTemplate
1580
1581
37.1.22 sectionHeaderSkin
1583
37.1.23 sectionHeaderTemplate
1584
37.1.24 selectedRowIndex
1586
37.1.25 selectedRowIndices
1587
37.1.26 selectedRowItems
1589
37.1.27 selectionBehavior
1589
37.1.28 selectionBehaviorConfig
1591
37.1.29 separatorColor
1592
37.1.30 separatorRequired
1593
37.1.31 separatorThickness
1594
1595
37.1.33 viewType
1596
37.1.34 viewConfig
1602
1604
37.1.36 widgetSkin
1606
37.2 SegmentedUI - Layout Properties
1607
1607
1608
1609
37.2.4 gridCell
1610
37.2.5 layoutMeta
1611
37.2.6 layoutType
1613
1614
37.2.8 margin
1615
1617
37.2.10 padding
1618
1620
37.3 SegmentedUI - Platform Specific Properties
1622
1622
37.3.2 border
1623
37.3.3 bounces
1625
37.3.4 contextMenu
1626
37.3.5 defaultSelection
1629
37.3.6 dockSectionHeaders
1630
37.3.7 editStyle
1631
37.3.8 enableDictionary
1633
37.3.9 indicator
1635
37.3.10 pressedSkin
1636
1637
37.3.12 searchBy
1639
37.3.13 searchCriteria
1640
1642
37.3.15 viewConfig
1643
37.4 SegmentedUI - Events
1645
37.4.1 onDidFinishDataLoading
1645
37.4.2 onEditing
1646
37.4.3 onRowClick
1647
37.4.4 onSwipe
1648
1650
37.4.6 preOnclickJS
1652
1653
37.5 SegmentedUI - Methods
1655
37.5.1 addAll
1655
37.5.2 addDataAt
1656
37.5.3 addSectionAt
1658
37.5.4 removeAll
1659
37.5.5 removeAt
1660
37.5.6 removeSectionAt
1662
37.5.7 setData
1663
37.5.8 setDataAt
1664
37.5.9 setSectionAt
1665
37.6 Segment - Deprecated Properties
1667
37.6.1 addAt
1667
37.6.2 editable
1668
37.6.3 focusedIndex
1669
37.6.4 focusedItem
1669
37.6.5 navigationSkin
1669
37.6.6 needSectionHeader
1670
1670
1672
37.6.9 ondeleteclick
1673
37.6.10 oninsertclick
1673
37.6.11 onselect
1674
37.6.12 retainHeaderFooter
1674
1675
37.6.14 spaceBetweenSections
1676
37.6.15 viewConfig
1676
37.7 SegmentedUI - Templates
1678
37.7.1 What is a Template for SegmentedUI
1678
37.7.2 Where to use a SegmentedUI (section) Template
1678
37.7.3 Creating a Template for SegmentedUI
1678
37.7.4 Using SegmentedUI Section Template
1679
38. Switch
1680
38.1 Switch - Basic Properties
1682
38.1.1 id
1682
38.1.2 info
1683
38.1.3 isVisible
1684
38.1.4 leftSideText
1685
38.1.5 Left Text i18n Key
1686
38.1.6 rightSideText
1687
38.1.7 Right Text i18n Key
1688
1689
38.1.9 skin
1690
38.2 Switch - Layout Properties
1691
1691
38.2.2 margin
1692
1694
1695
38.3 Switch - Events
1698
38.3.1 onSlide
1698
39. SignatureCapture
1700
39.1 SignatureCapture - Basic Properties
1701
39.1.1 base64
1701
39.1.2 id
1702
39.1.3 info
1703
39.1.4 isVisible
1704
39.1.5 penWidth
1705
39.1.6 rawBytes
1706
39.1.7 skin
1707
39.2 SignatureCapture - Layout Properties

1707
1708
39.2.2 hExpand
1709
39.2.3 margin
1710
1712
39.2.5 padding
1713
1715
39.2.7 vExpand
1716
1718
39.3 SignatureCapture - Platform Specific Properties

39.3.1 accessMode
39.4 SignatureCapture - Event
39.4.1 onCapture
39.5 SignatureCapture - Methods
1719
1719
1721
1721
1722
39.5.1 clear
1722
39.5.2 getAsRawBytes
1723
39.5.3 save
1723
40. Video
40.1 Video - Basic Properties
1725
1728
40.1.1 id
1728
40.1.2 isVisible
1729
40.1.3 skin
1730
40.1.4 source
1731
40.1.5 text
1732
40.2 Video - Layout Properties
1733
1733
40.2.2 margin
1734
40.2.3 padding
1736
1738
40.3 Video - Platform Specific Properties
1740
40.3.1 controls
1740
40.3.2 poster
1741
41. App Menu

41.1 Common Properties
1742
1744
41.1.1 Skin
1744
41.1.2 Focus Skin
1745
41.1.3 ID
1745
41.1.4 Title
1745
41.1.5 Icon
1746
41.1.6 Render
1746
41.1.7 i18n Key
1747
41.1.8 Event
1747
41.2 App Menu - Platform Specific Properties
1748
41.2.1 Needs Separator
1748
41.2.2 Appbar Button Style
1749
41.2.3 Position
1749
41.3 Methods
1750
41.3.1 createAppMenu
1750
41.3.2 setCurrentAppMenu
1752
41.3.3 getCurrentAppMenu
1753
41.3.4 setAppMenuFocusByID
1754
41.3.5 addAppMenuItemAt
1755
41.3.6 removeAppMenuItemAt
1756
41.3.7 setAppMenuBadgeValue
1757
41.3.8 getAppMenuBadgeValue
1758
41.4 Methods
1759
41.4.1 setAppMenu
1759
41.4.2 setAppMenuFocusIndex
1761
41.4.3 showAppMenuItems
1762
41.4.4 hideAppMenuItems
1762
42. Accessibility (508 Compliance)
1764
42.1 Defining accessibilityConfig for a Widget in Kony Studio
1766
42.2 Widget Behavior When Accessibility is Enabled
1769
42.3 Container Widgets
1770
42.3.1 Form
1770
42.3.2 HBox
1771
42.3.3 VBox
1772
42.3.4 ScrollBox
1773
42.3.5 Popup
1774
42.4 Basic Widgets
1775
42.4.1 Button
1776
42.4.2 Calendar
1776
42.4.3 CheckBox
1777
42.4.4 ComboBox
1778
42.4.5 Image
1779
42.4.6 Label
1780
42.4.7 Line
1780
42.4.8 Link
1780
42.4.9 ListBox
1781
42.4.10 RadioButton
1782
42.4.11 RichText
1783
42.4.12 Slider
1784
42.4.13 TextArea
1784
42.4.14 TextBox
1785
42.5 Advanced Widgets

42.5.1 Alert
1785
1785
42.5.2 Camera
1786
42.5.3 Hz Image Strip
1786
42.5.4 PickerView
1787
42.5.5 SegmentedUI - TABLEVIEW
1788
42.5.6 SegmentedUI - PAGEVIEW
1789
42.5.7 Switch
1790
42.6 Accessibility Best Practices
1790
42.7 Accessibility:Platform Specific Limitations
1790
42.7.1 SPA
43. Widget Level Animation
1791
1792
43.1 Layout Animation
1793
43.2 Animation Limitations
1795
44. Appendix A: Layout
1797
44.1 HBox Behavior
1798
44.1.1 Scenario 1 (General Layout)
1798
44.1.2 Scenario 2 (Alignment)
1801
44.2 VBox Behavior
1808
44.2.1 Scenario 1
1808
45. Appendix B: Platform Specific Limitations
1812
45.1 DesktopWeb Limitations
1812
45.2 SPA Limitations
1813
45.3 Windows 7/8/8.1 Kiosk
1814
45.4 BlackBerry 10
1814
46. Glossary
1817
1. Overview
Widgets are visual components that enhance development of mobile applications through minimal coding
effort. When the widgets are combined with an application, the widgets hold all the applications data and the
available interactions with this data.
Widgets often take the form of on-screen tools. The developers use different implementations of the widgets
available in the Integrated Development Environment (IDE) to build Graphical User Interfaces (GUI). All the
widgets described in this document are drag-and-drop widgets
All the Kony supported devices, development languages, and browsers are listed at, Supported Devices and
Browsers.
1.1 Scope
This document describes the usability of widgets, properties, and events within the IDE. This document
explains the classification and structure of all the widgets within the IDE and also describes the Layout.
1.2 Intended Audience

This document is targeted at the developers who want to have an understanding of the widget properties and
are familiar with the Kony Studio.
1.3 Typographical Conventions

The following are the typographical conventions used throughout the document:
Conventions
Monospace
Italic
Bold
Explanation
n
User input text, system prompts and responses
File Path
Commands
Program Code
File Names.
Emphasis
Names of Books and Documents
New Terminology.
Windows
Menus
Buttons
Icons
Fields
Tabs
Folders.
URL
Active link to a URL.
Note:
Provides helpful hints or additional information.
1.4 Reference Documents

1. Kony Studio Installation Guide
2. Kony Server Installation Guides
3. Kony Studio User Guide
4. Kony API Reference Guide
1.5 Contact Us
We welcome your feedback on our documentation. Write to us at techpubs@kony.com.For technical
questions, suggestions, comments, or to report problems on Kony's product line, contact
productsupport@kony.com.
2. Working with Widgets

Kony Studio widgets exploit the full capabilities of high-end mobile devices while scaling down gracefully on
smaller and less powerful mobile handsets. A complex and visually rich interface widget is scalable for
simpler devices; but you cannot scale up an under-designed interface. Hence, it is always a best approach to
design for the high-end and test on the low-end mobile devices.
Kony Studio widgets are small chunks of code that are re-used without additional compilation. Some widgets
support interaction with the user (for example: Button, Label, Checkbox, and so on). Others act as containers
that group the widgets added to them (for example: Form, Row, Column, and so on).
A software library containing a collection of widgets that collaborate in designing or development of
applications is known as Palette.
The following is a snapshot of a Palette:
The widgets are based on a common behavior definition and are made available across all supported native
and browser platforms, enabling you to deliver a consistent user experience across all devices using these
reusable components.
Kony Client libraries also include support for platform specific properties. The platform specific properties
allow you to have a native look and feel on the respective platforms. The IDE enables the development of
common functionality across all platforms, but also offers the ability for you to customize device specific
properties that are available only on certain platforms. Using this capability, you can maintain one code base,
but still deliver an optimized application experience for a specific device by configuring additional device or
platform properties provided by the platform.
Windows Platform Classification:
Follow are the supported OS versions supported in Windows Channels
Windows Phone
Windows Phone 7.5
Windows Phone 8
Windows Phone 8.1
Windows Tablet
Windows 8.1
Windows Kiosk
Windows 7 Kiosk
Windows 8 Kiosk
Windows 8.1 Kiosk
2.1 Widget Classification

Widgets are categorized as Containers, Components, and Advanced Components based on the behavior and
characteristics of the widgets.
The following is a structural classification of the widgets:
1. Composite Widgets: Form and Popup
2. Command Input Widgets: Button and MenuItem
3. Data Input and Output Widgets: CheckBox, ComboBox, Link, ListBox, RadioButtonGroup,
RichText, TextArea, TextBox, and Switch.
4. Informational Widgets: Calendar, Hz Image Strip, Image, Image Gallery, Label, Line, and Slider.
5. Advanced Widgets: Browser, Camera, Hz Image Strip, Image Gallery, Map, Phone, PickerView,
Segment, Switch, Video, and Signature.
The following sections describe the behavioral classification of the widgets:
2.1.1 Container Widgets

These are a set of widgets that hold component widgets within them. The container widgets trigger events
upon receiving user actions. The following is a list of Container Widgets:
l
Form
HBox
VBox
TabPane
Popup
ScrollBox
2.1.2 Basic Widgets

These widgets are components that act independently of the Container Widgets. The following is a list of
Basic Widgets:
Button
Calendar
CheckBoxGroup
ComboBox
DataGrid
Image
Label
Line
Link
ListBox
MenuItem
RadioButtonGroup
RichText
Slider
TextArea
TextBox
2.1.3 Advanced Component Widgets

The following is a list of Advanced Component Widgets:
l
Browser
Camera
Chart
Hz Image Strip
ImageGallery
Map
ObjectSelector3D
Phone
PickerView
Segment
Switch
SignatureCapture
Video
2.2 Widget Methods

The methods which are common for all the widgets are as follows:
setVisibility
setFocus
setEnabled
setGestureRecognizer
removeGestureRecognizer
setBadge
getBadge
2.2.1 setVisibility
Use this method to set the visibility of the widget. The property animationConfig is supported only on the
following widgets:
l
HBox
VBox
Button
Calendar
Image
Label
SegmentedUI
Default : true
Syntax
JavaScript: setVisibility (visible, animationConfig)
Note: The parameter animationConfig is supported only on iOS (version 5.0 and above) and Android
(version 2.3 and above) platforms.
Lua: setvisibility (widget, visible)
Note: This method is not applicable on Form, Popup, and Alert. It is also not applicable if the widget is
placed in a Segment.
When the widget is placed in a Segment, the default Visibility is set to true. If you want to change the value
to false, you can do so by using the Segment methods.
Input Parameters
visible [Boolean] - Mandatory
True -Indicates visibility is true.
False - Indicates visibility is false.
animationConfig [JSObject] - Optional
Specifies the animation configuration object. Following are the parameters of the JSObject:
Note: A non dictionary object or passing a null to animationConfig is ignored

and will be treated as widget without any animation. Passing an empty
dictionary will make the API assume the defaults for each of the supported key
in the animation configuration.
animEffect - Optional
Specifies the animation effect. Following are the available options of animation effect:
l
constants.ANIMATION_EFFECT_EXPAND:This is applicable when the

visibility is turned on. Specifies the widget must expand gradually by
increasing the height of the widget.
constants.ANIMATION_EFFECT_COLLAPSE: This is applicable when

the visibility is turned off. Specifies the widget must collapse gradually by
decreasing the height of the widget.
constants.ANIMATION_EFFECT_REVEAL:This is applicable when the

visibility is turned on. Specifies the widget must appear gradually by
decreasing the transparency of the widget.
constants.ANIMATION_EFFECT_FADE:This is applicable when the

visibility is turned off. Specifies the widget must disappear gradually by
increasing the transparency of the widget.
constants.ANIMATION_EFFECT_NONE:This is the default option.

Specifies animation should not be applied to the widget. However the
layout animations are applied on the Form.
animDuration - Optional
Specifies the duration of the animation effect in seconds. The default value is 1 second. The
negative values are ignored and defaulted to 1 second.
animDelay - Optional
Specifies the delay of the animation effect in seconds. The default value is 0 second. The
animCurve - Optional
Specifies the animation curve to be applied while playing the animation. An animation curve
defines the speed of the animations at different intervals of the animation duration. Following are
the available options of animation curve:
l
constants.ANIMATION_CURVE_EASEIN:Specifies the animation

effect to start slow in the beginning.
constants.ANIMATION_CURVE_EASEOUT: Specifies the animation

effect to slowdown towards the end.
constants.ANIMATION_CURVE_EASEINOUT:Specifies the animation

effect to start slow and slowdown towards the end.
constants.ANIMATION_CURVE_LINEAR:This is the default value.

Specifies the animation effect to continue with the same speed from start
to end.
animCallBacks - Optional
It is a JS dictionary containing the events invoked by the platform during the animation life
cycle. Following are the available events:
l
animStarted:Invoked at the beginning of the animation without any

parameters. Following is the signature of the event:
function animStarted()
animEnded:Invoked at the end of the animation without any parameters.

Following is the signature of the event:
function animEnded()
Note: Passing an invalid type other than the above events lead to run time
exceptions/ crashes.
widget [widgetref] - Mandatory
Handle to the widget instance.
Return Values
None
Exceptions
Error
JavaScript Example
//Creating a form.
var frmBasicConf= {id:"form",title:"Form for kony Common widget API
Test",isVisibile:true};
var form = new kony.ui.Form2(frmBasicConf,{},{});
//Creating a button.
var btnBasic ={id:"btn",text:"button",isVisible:true};
var btn =new kony.ui.Button(btnBasic, {}, {});
//Adding button to the form.
form.add(btn);
//setVisibility method call on the button.
form.btn.setVisibility(false,
{
"animEffect":constants.ANIMATION_EFFECT_COLL
APSE,
"animDuration":1,
"animDelay":0,
"animCurve":constants.ANIMATION_CURVE_LINEAR,
"animCallBacks":{
"animStarted":startCallBackFun
c,
"animEnded":endCallBackFunc
}
}
);
Platform Availability
Available on all platforms except on Server side Mobile Web platforms
2.2.2 setFocus
This method specifies the widget on which there must be focus.
Note: We recommend you not to call this method in preShow of a form as it is not respected by all
platforms. In Android platform, this method is not respected in preShow of a form. You can give focus to a
particular widget only after it is rendered on the screen, hence it should be called in postShow of a form.
Default : true
Syntax
JavaScript: setFocus(focus)
Lua: setfocus(widget, focus)
Note: This method is not applicable in Form widget. On BlackBerry platform to get the focus away from a
widget you need to setFocus to another widget. This is default SDK behavior.
Input Parameters
This method has the following input parameters:
focus [Boolean] - Mandatory

True -Indicates focus is set on a widget.
False - Indicates focus is not set on a widget.
Return Values
None
Exceptions
Error
JavaScript Example
//Creating a form.
var frmBasicConf= {id:"form",title:"Form for kony Common widget API Test",
isVisibile:true};
form.add(btn);
//setFocus method call on the button.
form.btn.setFocus(true);
2.2.3 setEnabled
This method specifies the widget that must be enabled or disabled.
Syntax
JavaScript: setEnabled (enabled)
Lua: setenabled (widget, enabled)
Note: Browser widget does not support this method in Server side Mobile Web, SPA, and Desktop Web
platforms.
Note: This method is not applicable in Map widget.
Input Parameters
enabled [Boolean] - Mandatory
True -Indicates widget is enabled.
False - Indicates widget is disabled.
Return Values
None
Exceptions
Error
Example
//Creating a form.
var frmBasicConf= {id:"form",title:"Form for kony Common widget API Test",
isVisibile:true};
form.add(btn);
//setEnabled method call on the button.
form.btn.setEnabled(false);
Available on all platforms except on SPA and BlackBerry 10 platforms.
2.2.4 setGestureRecognizer
This method allows you to set a gesture recognizer for a specified gesture for a specified widget. You can set
a Gesture recognizer only for a Form, a Box, and a Scroll Box.
Note: This method is applicable on Form, Box, and ScrollBox widgets only.
Syntax
JavaScript: setGestureRecognizer (gestureType, setupParams, gestureHandler)
Lua: setgesturerecognizer (widget, gestureType, setupParams, gestureHandler)
Input Parameters
gestureType [Number] - Mandatory
Specifies the type of gesture that needs to be detected on the widget. The following are possible
values:
l
1 for TAP
2 for SWIPE
3 for LONGPRESS
setupParams [array of arrays] - Mandatory

Specifies an object that has the configuration parameters needed to setup a gesture recognizer.
The configuration parameters vary based on the type of the gesture.
This parameter has the following parameters:
Gesture Type:TAP
l
fingers [number] - specifies the maximum number of fingers that must be

respected for a gesture. Possible values are: 1. Default value is 1.
taps [number] - specifies the maximum number of taps that must be respected
for a gesture. Possible values are: 1 or 2. Default value is 1.
For example,{fingers:1,taps:1}
Gesture Type:SWIPE
l
fingers [number] - specifies the maximum number of fingers that must be

respected for a gesture. Possible values are: 1. Default value is 1.
swipedistance [number] - specifies the distance between the pixel from where
the swipe started to the pixel where the swipe stopped (finger is moved up or
removed). The default value is 50 pixels.
Note: This parameter is applicable only on Android.
swipevelocity [number] - specifies the velocity of the swipe measured in pixels

per second. The default value is 75.
Note: This parameter is applicable only on Android.
For example,
{fingers:1,swipedistance:50,swipevelocity:75}
Gesture Type :LONGPRESS
pressDuration [number] - specifies the minimum time interval (in seconds)

after which the gesture is recognized as a LONGPRESS.
For example, if the pressDuration is 2 seconds, any continued press is

recognized as LONGPRESS only if it lasts for at least 2 seconds. Default
value is 1.
Note: This parameter is not customizable on Android platform. The default
value on Android platform is 500 ms. Any value you pass to this parameter is
ignored and the default value is used.
For example,{pressDuration:1}
gestureHandler [function] - Mandatory

Specifies the function that needs to be executed when a gesture is recognized. This function has
the following signature:
onGesturefunction(widgetRef,gestureInfo)
l
widgetRef - specifies the handle to the widget on which the gesture was
recognized.
gestureInfo - specifies an array that provides information about the gesture.

The contents of this array vary based on the gesture type.
The Kony platform populates the details in the gestureInfo array. This array has the
following key-value pairs:
l
gestureType [number] - indicates the gesture type; 1 for TAP, 2 for SWIPE, and
3 for LONGPRESS.
gesturesetUpParams [object] - this array is the set up parameters passed

while adding the gesture recognizer.
gesturePosition [number] - indicates the position where the gesture was

recognized. Possible values are: 1 for TOPLEFT, 2 for TOPCENTER, 3 for
TOPRIGHT, 4 for MIDDLELEFT, 5 for MIDDLECENTER, 6 for MIDDLERIGHT,
7 for BOTTOMLEFT, 8 for BOTTOMCENTER, 9 for BOTTOMRIGHT, 10 for
CENTER.
Note: This parameter is applicable only on iPhone.
swipeDirection [number] -indicates the direction of swipe. This parameter is

applicable only if the gesture type is SWIPE. Possible values are: 1 for LEFT, 2
for RIGHT, 3 for TOP, 4 for BOTTOM.
gestureX [number] - specifies the X coordinate of the point (in pixels) where
the gesture has occurred. The coordinate is relative to the widget coordinate
system.
gestureY [number] - specifies the Y coordinate of the point (in pixels) where
the gesture has occurred. The coordinate is relative to the widget coordinate
system.
widgetWidth [number] - specifies the width of the widget (in pixels).

widgetHeight [number] - specifies the height of the widget (in pixels).


Return Values
String - Reference(uniqueidentifier) to the gesture is returned.
Exceptions
Error
Example
//The below function will get invoked when a gesture is recognized.
function myTap(myWidget,gestureInfo)
{
alert(" Tap Gesture detected");
alert("gestureType :"+gestureInfo.gestureType);
alert("gesturePosition :"+gestureInfo.gesturePosition);
//write any further logic here
}
//Setting Gesture configuration.
var setupTblTap = {fingers:1,taps:2};//double tap gesture
//To add a TAP gesture recognizer on a hbox with ID hbx1 placed on a form
frm1
var tapGesture=frm1.hbx1.setGgestureRecognizer(1,setupTblTap,myTap);
l
iPhone/iPad
Android
BlackBerry
Windows Phone
SPA
2.2.5 removeGestureRecognizer
This method allows you to remove a specified gesture recognizer for a specified widget. You can remove the
gesture recognizer from a Form, a Box, and a Scroll Box.
Note: This method is applicable on Form, Box, and ScrollBox widgets only.
Syntax
JavaScript: removeGestureRecognizer(uniqueIdentifier)
Lua: removegesturerecognizer(widget, uniqueIdentifier)
Input Parameters
uniqueIdentifier - Mandatory
Indicates the type of gesture added to the form.
Return Values
None
Exceptions
Error
Example
//The below function will get invoked when a gesture is recognized.
function myTap(myWidget,gestureInfo)
{
alert(" Tap Gesture detected");
alert("gestureType :"+gestureInfo.gestureType);
alert("gesturePosition :"+gestureInfo.gesturePosition);
//write any further logic here
}
//Setting Gesture configuration.
var setupTblTap = {fingers:1,taps:2};//double tap gesture
//To add a TAP gesture recognizer on a hbox with ID hbx1 placed on a form
frm1
var tapGesture=frm1.hbx1.setGestureRecognizer(1,setupTblTap,myTap)
//To remove the TAP gesture recognizer on a hbox with ID hbx1 placed on a
form frm1
frm1.hbx1.removeGestureRecognizer(tapGesture);
l
iPhone/iPad
Android
BlackBerry
Windows Phone
SPA
2.2.6 setBadge
This method enables you to set the badge value to the given widget at the upper, right corner of the widget.
The color for badge can be defined using a skin.
Note: For iOS platform, this method is applicable on Box, Label, Button, Image, TextBox, and TextArea
widgets only.
Note: For Android platform, this method is applicable on Button and Image widgets only.
Syntax
JavaScript: setBadge(badgeText, skin)
Lua: setbadge(widget, badgeText, skin)
Input Parameters
badgeText [String] - Mandatory
Specifies the Text value that appears within the badge. If the length of the badgeText is greater
than 1 the badge is a rounded rectangle. For example, if you specify the text of the badge as 88, the
number appears in a rounded rectangular badge. If the length of the badge text is 1, the badge is
always a circle. The badge can occupy up to 70% of the width of the parent widget. For example, on
a button with a width of 100 pixels, a badge with about 100 characters will occupy only 70 pixels of
the button width. The badge text is truncated and shows about 30 characters followed by three
dots.
skin [String] - Optional
Specifies the background color for the badge. The default color is red.

Return Values
None
Exceptions
Error
Example
//To set a badge value with skin "badgeSkin" on a box with ID hbx1 placed
on a form frm1, use the following code:
frm1.hbx1.setBadge("2","badgeSkin");
l
iPhone/iPad
Android/Android Tablet
For more information about the badge APIs refer the Kony API Reference Document.
2.2.7 getBadge
This method enables you to read the badge value (if any) attached to the given widget.
Note: For iOS platform, this method is applicable on Box, Label, Button, Image, TextBox, and TextArea
widgets only.
Note: For Android platform, this method is applicable on Button and Image widgets only.
Syntax
JavaScript: getBadge()
Lua: getbadge(widget)
Input Parameters
Return Values
String - Reference to the gesture is returned.
Exceptions
Error
Example
//To get a badge value on a box with ID hbx1 placed on a form frm1, use the
following code:
var badgeVal =frm1.hbx1.getBadge();
alert("badge value is::"+badgeVal);
l
iPhone/iPad
For more information about the badge APIs refer the Kony API Reference Document.
2.3 Widget Skins

A widget skin defines the look and feel of the widget when it is rendered on the form in an application. You can
specify different skins for different widgets, or different skins for different platforms. The IDE allows you to
create skins and specify skins for widgets while setting the properties.
When you add a widget to a form, the widget uses the default skin unless you specify a skin for the widget in
the widget skin properties.
For more information about creating skins, see the section Configuring Widget Skins in the Kony Studio User
Guide.
The following sections describe the support for Dynamic Skinning and Platform Specific Skin Limitations.
2.3.1 Dynamic Skinning

A widget can have more than one skin defined (for example, normal skin, focus skin, etc.) Dynamic Skinning
allows you to change the skin of a widget during runtime.
This means that you can set a skin for a widget dynamically through code.
For example, for a button in a Phone Widget, if you want to display different skins for successful and
unsuccessful dial attempts, enter the following:
function clickphone()
local retvalue = phone.dial("555-2368");
if retvalue == -1 then
frm1.btn1.skin = errorskin;
else
frm1.btn1.skin = successskin;
end
end
In the above code snippet, if the dial attempt is a failure, the errorskin is applied on the button. If the dial
attempt is a success, the successskin is applied.
Note: For Dynamic Skinning, you must ensure that the skin exists for the widget in the IDE before the code
is executed. JavaScript is not supported on Windows 6.x platform.
The following table lists the widgets and platforms which support dynamic skinning:
Widget
Windows
Android/
iPhone Mango/
Android BlackBerry
/iPad Windows
Tablet
6.x
Mobile
Web
SPA/Playbook
Form
Yes
Yes
Yes
Yes
Yes
Yes
HBox
Yes
Yes
Yes
Yes
Yes
Yes
VBox
Yes
Yes
Yes
Yes
Yes
Yes
Button
Yes
Yes
Yes
Yes
Yes
Yes
Calendar
Yes
Yes
Yes
Yes
Yes
CheckBoxGroup
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
ComboBox
Image
Yes
Label
Yes
Line
Yes
Link
Yes
Yes
ListBox
Yes
Yes
Yes
Yes
Yes
RadioButtonGroup Yes
Yes
Yes
Yes
Yes
Yes
Yes
Rich Text
Yes
Yes
Yes
Yes
Yes
Widget
Windows
Android/
iPhone Mango/
Android BlackBerry
/iPad Windows
Tablet
6.x
Mobile
Web
SPA/Playbook
TextArea
Yes
Yes
Yes
Yes
TextBox
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
ScrollBox
Signature
Video
Yes
Yes
Yes
(supported
on 6.x)
2.3.2 Platform Specific Skin Limitations

There are few Platform Specific Skin limitations.
The following is the list of platform specific skin limitations:
iPhone
l
Supports only squared borders (plain).
Supports a skin for SegmentedUI only when the groupCells property is set to false.
Does not support Font weight and style attributes for skins.
Does not support adding skins for the default App Menu items.
J2ME
Do not support transparency for widgets (background, font, and border).

BlackBerry
Supports transparency for background and borders. Transparency is not supported for Fonts.
If the skin style is set as transparent and a border is specified, the border color fills up the entire widget.
Therefore we recommend not using the skin type transparent along with a border.
The form will ignore styles for widgets, when the size or the number of elements exceeds certain limit
(depending on blackberry device). For example, when there are 4 elements in a segment and 15 data
points are available, then segment may not apply style of the form or the CSS style depending on the
type of blackberry device.
Android
Platforms do not support adding skins for the default App Menu items.
Mobile Web
Basic and BJS versions does not support rounded borders.
Does not support Focus Skin.
Devices that support BJS do not support vertical split and gradient attributes in the skin.
Windows Phone browser (IE 7 browser) does not support transparency because the RGBA property is
not supported.
Hence, for the widgets accessed from Mobile Web on Windows Phone, transparency for widgets
(background, font, and border) is not supported.
Windows Phone
Do not support transparency for widgets (background, font, and border).
not supported.
Hence, for the widgets accessed from Mobile Web on Windows Phone, transparency for widgets
(background, font, and border) is not supported.
Symbian
Skins are only supported for Form, Box, Label, and Button widgets to a limited extent.
l
For box widgets, an on-focus skin is not implemented
In button widget you can only change font color
Mobile Web Basic Devices

The following skin attributes are not supported on Mobile Web Basic devices:
l
Margins and Padding for all the widgets.
Transparency in font color, background color, and border colors.
Borders for Label, Link, RichText, CheckBox, and RadioButton widgets.
Focus skins for all widgets.
Rounded corners for borders for all widgets.
Skin with background image (dynamically) for a button. Even if you set the background image, it will
not be affected while the rest of the properties of the skin are affected.
Underline for all widgets where the click is represented as an anchor. For example, Link, Phone, and
Segmented UI. The text attributes in the skin for these widgets is set to none by default. But based on
some browser limitations on some devices, the underline will still be shown irrespective of the above
property.
If you specify borders with higher number of pixels, the borders may go out of the screen depending on
the layout used. In this case, you must reduce the borders. This limitation is because of the % layout
used by the platform and there is no mechanism to determine the % occupied by the border in the
overall screen width. On advanced devices, this issue does not arise as they use CSS layout
mechanisms.
The font sizes specified by the developer are mapped to the font ranges of xx-small and small. The mapping of
font sizes is as follows:
l
If font % is < 100 then it is mapped to xx-small category.
If font % is >= 100 then it is mapped to small category.

Note: These units are used because support for pt or px based font is not uniform across basic
devices.
Mobile Web BJS Devices

The following skin attributes are not supported on Mobile Web BJS devices:
l
Transparency in font colors.
Focus skins for all widgets.
Rounded corners for borders for all widgets.
Vertical split and gradient for all widgets.
If you specify borders with higher number of pixels, the borders may go out of the screen depending on
the layout used. In this case, you must reduce the borders. This limitation is because of the % layout
used by the platform and there is no mechanism to determine the % occupied by the border in the
overall screen width. On advanced devices, this issue does not arise as they use CSS layout
mechanisms.
Mobile Web Advanced Devices

The following are the restrictions for skin attributes for mobile Web Advanced platform:
l
In the case of form backgrounds for gradients, the gradient is applied only up to the point where the
form ends. In cases where the form size is less than the screen height, a white background will appear
to cover the rest of the screen. This is only in case of BB Torch & Android devices less than 2.3
versions. To overcome this problem, the developer can provide an empty HBox or VBox with
padding/margin to the top and the bottom of the widget to cover the full screen size of the device. This
may cause a side effect of causing the form to scroll down.
Focus skin for all widgets is not supported.
not supported. Hence, for the widgets accessed from Mobile Web on Windows Phone, transparency
for widgets (background, font, and border) is not supported.
3. Container Widgets
Container widgets are a set of widgets that can hold component widgets within them.
This section describes the following container widgets:
l
Form
HBox
VBox
TabPane
Popup
ScrollBox
4. Form
Form is a visual area (basic application screen) that holds other widgets. You can use a form to set a title and
scroll content (similar to a web browser). The entire contents of the form except the headers and footers scroll
together. A form is the top most container widget. A form can contain any number of widgets but cannot
contain another form.
The screen width occupied by the form is the total available width of the mobile device; the virtual height is
determined by the number of widgets on the form (the total height of the form is sum of the virtual heights of its
first level visible child widgets).
Note: A form-level menu is not applicable on all versions of Mobile Web.
For example, if Form1 has Button1, Button2, Button3, and an HBox (the height of the box in turn is the sum of
the heights of its child widgets), then the height of Form1 is the sum of the heights of Button1, Button2,
Button3, and an HBox. Form1 Width is the available screen width of the phone.
Form Lifecycle
A form lets you add other container and widgets to create a widget hierarchy. A form fills the device screen
provided for an application (excluding the device level screen controls like status bar).
Form stacking:
Typically a form is shown by a user action on another form. That means the navigation between forms happen
by the events on another form. All the navigation actions are pushed into the stack to track the navigation
path, so that the user can navigate back to the previous forms in the exact reverse order of its forward
navigation. When navigation to a form that is already visited and available in the middle of the stack, the target
form is brought back to the top of the stack by popping all the above forms out of the stack. Currently this
stack is not exposed directly to the developers and in future there will be APIs around manipulating this stack
directly.
Lifecycle Methods:
A form is defined to have a lifecycle method that gets called at appropriate events. These events allow you to
manage the application for better resource handling.
The following are the lifecycle methods of a form:
addWidgets - called when the form is used for first time either
l
for accessing its widgets,
accessing its properties,
for showing the form through the show method,
for any other method that invokes the form.
For example,
Any of the following can trigger the addWidgets method of form1 if form1 is not yet initialized:
l
form1.label1
form1.title
form1.show()
init - called immediately after an addWidgets event for any initializations required for the form. Init initializes
the form and any widgets.
In case of Server side Mobile Web and SPA, addWidgets and init events gets called as soon as the form is
created. In case of native platforms, as an optimization, these events are deferred until the first access.
preShow - called just before a form is visible on the screen. A form can be made visible by explicitly calling
the show method of the form.
postShow - called immediately after the form is visible on the screen. A form is made visible by explicitly
calling the show method of the form.
onHide - called when the form goes out of the screen. A form can go out of the screen when another form is to
be shown.
onDestroy - called when a form is destroyed. A form is destroyed when the developer explicitly calls destroy
and this event gets called before destroying the form.
The following image illustrates the lifecycle of a form:
Click here to view the Application Life Cycle events.

A form provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
Events, and Methods.
Deprecated properties are provided with their alternative properties in the Deprecated section.
Basic Properties
Layout Properties
Platform Specific Properties
enabledForIdleTimeout
displayOrientation
actionBarIcon
footers
headers
id
info
menuFocusSkin
menuItems
menuNormalSkin
needAppMenu
skin
gridCell
layoutMeta
layoutType
padding
paddingInPixel
animateHeaderFooter
bounces
captureGPS
contextPath
configureExtendTop
configureExtendBottom
configureBarStyle
defaultIndicatorColor
enablePeekGesture
extendTop
extendBottom
statusBarStyle
footerOverlap
formTransperencyDuringPostShow
headerOverlap
inputAccessoryViewType
inTransitionConfig
layout
maxAppMenuButtons
menuPosition
needsIndicatorDuringPostShow
noCache
outTransitionConfig
retainScrollPosition
scrollDirection
secureData
showBottomActionBar
showActionBar
showActionBarIcon
showMiniAppMenu
submitSecure
titleBar
titleBarConfig
titleBarSkin
windowSoftInputMode
title
type
Events
Methods
Deprecated
addWidgets
init
onActionBarBack
onHide
onOrientationChange
onDeviceBack
onDeviceMenu
onDestroy
preShow
postShow
add
addAt
show
destroy
remove
removeAt
replaceAt
widgets
setTitleBarLeftSideButtonSkin
setTitleBarRightSideButtonSkin
dockableAppMenu
dockableHeader
dockableFooter
enableback
IgnoreEscape
masterdataload
menuRenderer
transactionaldataload
Undock App Header
Undock App Footer
Events
Methods
onLoadJS
unLoadJS
setTitleBarSkin
showTitleBar
hideTitleBar
scrollToWidget
scrollToBeginning
scrollToEnd
Deprecated
Creating a Form using a constructor: kony.ui.Form2

var form1 = new kony.ui.Form2(basicConf, layoutConf, pspConf)
l
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.
JavaScript Example
//Defining properties for a form.
var basicConf = {id : "formHome", title:"Form Home", addWidgets:addwidgets
frmNew, skin:"frmskn"};
var layoutConf = {contentAlignment : constants.CONTENT_ALIGN_TOP_CENTER, c
ontainerWeight:100, hExpand: true, vExpand:true};
var pspConf = {titleBar: true, titleBarSkin: "skntitlebar"};
//Creating the form.
var myForm = new kony.ui.Form2(basicConf,layoutConf,pspConf)
For backward compatibility with support for all deprecated properties and behaviors, use the constructor
kony.ui.Form.
var form1 = new kony.ui.Form(basicConf, layoutConf, pspConf)
Form Types
Kony platform allows you to develop truly native applications (which use native widgets) or Hybrid
applications. Hybrid applications are a version of the native application where some forms of the application
are rendered in the WebView while others are rendered using the native SDK. You can choose the forms to be
either native or web-based. The web-based forms can either be statically packaged (Static) along with the
application or loaded from a URL(Dynamic).
Depending on the nature of the application developed, the developer can choose one of the following form
types when creating a new form:
Native
Web-based
l
Static
Dynamic
The characteristics of each type of form are listed in the table below:
Form Type
Characteristics
Web-based
Native
Static
Dynamic
Rendering engine used

Native SDK
to display form
UIWebView
UIWebView
UI definition (the
widget layout and
skins)
packaged along with the

application

application
downloaded from the

server
UI logic (logic that

alters the user
experience based on
business rules)

application

application
downloaded from the

server
Business Data
downloaded from the

server
downloaded from the server
downloaded from the

server
How is the child widgets laid out on the Form?

The form lays out the first level child widgets one below the other. Each widget occupies the same width as
form and the height is determined by the preferred height of the widget.
The algorithm works as follows for each widget in the list:
1. Assign width to widget (same as form width)
2. Get the preferred height of the widget (Child widgets request the required height (preferred height))
3. A form considers the preferred height request and assigns the same to the child widgets
4. Stack the widget
5. End
Note: For a form, there is no limit set on the vertical height and hence a form never declines the child
widgets request for preferred height.
4.1 Form - Basic Properties

The basic properties for Form Widget are as follows:
l
enabledForIdleTimeout
footers
headers
id
info
menuFocusSkin
menuItems
menuNormalSkin
needAppMenu
skin
title
type
4.1.1 enabledForIdleTimeout
Idle time indicates the amount of time that a user has not interacted with the application. Some of the
applications require a notification to be raised when a user has not interacted with the form for a specified
amount of time. For example, a banking app might require a notification after 5 minutes of inactivity by the
user. At the same time, applications also need an ability to not raise this notification for certain forms in the
application. For example, ATM Locator forms in a banking app, enabledForIdleTimeout property indicates, if
the form is going to raise the notification after a specific period of inactivity (set using the API
kony.application.registerForIdleTimeout.)
Default: false (the session will not expire after a period of inactivity).
If you want the session to expire after a period of inactivity (for example, you might require a Bank Accounts
page of a site to expire after a period of inactivity), you can enable the time out period set in code by selecting
the checkbox.
For more information about enabled for idle timeout, see API kony.application.registerForIdleTimeout in the
Kony API User Guide.
Syntax
JavaScript: enabledForIdleTimeout
Lua: enabledforidletimeout
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with enabledForIdleTimeout:true
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE, title:"Welcome",
skin:"frmSkin", enabledForIdleTimeout:true, headers:[hbox1,hbox2]};
var frmLayout ={displayOrientation:constants.FORM_DISPLAY_ORIENTATION_BOTH,

paddingInPixel:false, padding:[5,5,5,5]};
var frmPSP ={};
//Creating a form.
var frm =new kony.ui.Form2(frmBasic, frmLayout, frmPSP);
Accessible from IDE

Yes
Available on all platforms
4.1.2 footers
A footer is a section of the form that is docked at the bottom of the form (does not scroll along with the content
of the form). It accepts an array of kony.ui.Box object references with horizontal orientation that are added as
footer docked at the bottom of the Form. These footers can be reused across forms.
Syntax
JavaScript: footers
Lua: footers
Type
JavaScript: Array(kony.ui.Box)
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining a form with footers:[hbox3,hbox4], Where hbox3 and hbox4 are the
horizontal boxes which were created and made accessible and btn2 is present
in hbox3.
skin:"frmSkin", needAppMenu:true, enabledForIdleTimeout:true, headers:[hbo
x1,hbox2], footers:[hbox3,hbox4], menuNormalSkin:"mSkin", menuFocusSkin:"m
FSkin", menuItems:[menu1,menu2]};
var frmPSP ={};

//Creating a form.
//Accessing widgets present in footers of a form.
frm.footers[0].btn2 //btn2 is a button widget present in hbox3.
Accessible from IDE

Yes
Available on all platforms except Desktop Web
4.1.3 headers
A header is a section of the form that is docked at the top of the form (does not scroll along with the content of
the form). It accepts an array of kony.ui.Box object references with horizontal orientation that are added as
header docked at the top of the Form. These headers can be reused across forms.
Syntax
JavaScript: headers
Lua: headers
Type
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining a form with headers:[hbox1,hbox2], Where hbox1 and hbox2 are the
horizontal boxes which were created and made accessible and btn1 is present
in hbox1.
var frmPSP ={};

//Creating a form.
//Accessing widgets present in headers of a form.
frm.headers[0].btn1 //btn1 is a button widget present in hbox1.
Accessible from IDE

Yes
Available on all platforms except Desktop Web
4.1.4 id
id is a unique identifier of form consisting of alpha numeric characters. Every Form should have a unique id
within an application.
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String - [Mandatory]
Lua: String - [Mandatory]
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a form with id:"frm"
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE , title:"Welcome",
var frmPSP ={};
//Creating a form.

//Reading id of the form.
alert("form id::"+frm.id);
Accessible from IDE

Yes
4.1.5 info
A custom JSObject with the key value pairs that a developer can use to store the context with the widget.
This will help in avoiding the globals to most part of the programming.
Note: This is a non-Constructor property. You cannot set this property through widget constructor. But you
can read and write data to it.
Info property holds any JSObject. Post assigning the JSObject to info property, the JSObject should not be
modified. For example,
var inf = {a: 'hello'};
widget.info = inf; //works
widget.info.a = 'hello world'; //This will not update the widget info a pr
operty to Hello world. widget.info.a will have old value as hello.
Syntax
JavaScript: info
Lua: info
Type
JavaScript: JSObject
Lua: UserData
Read / Write
Yes - (Read and Write)
JavaScript Example
//Defining the properties for a form with info property.
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE , title:"Welcom
e", skin:"frmSkin", needAppMenu:true, enabledForIdleTimeout:true, headers:
[hbox1,hbox2], footers:[hbox3,hbox4], menuNormalSkin:"mSkin", menuFocusSki
n:"mFSkin", menuItems:[menu1,menu2]};
var frmPSP ={};
//Creating a form.
frm.info = {key:"FORM"};
//Reading info of the form.
alert("form info is ::"+frm.info);
Accessible from IDE

No
4.1.6 menuFocusSkin
This is a skin property of a form level menu and it determines the look and feel of the Menu Item when
focused.
Note: For BlackBerry (7 and below) and J2ME, this property is applicable only if the property Show Tab
Style Form Menu is set to true.
Note: For Desktop Web platform, use MenuContainer widgets to get menu related features.
Syntax
JavaScript: menuFocusSkin
Lua: menufocusskin
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Write only) [Applicable on BlackBerry, J2ME, and Window Phone (Mango) platforms]
JavaScript Example
//Defining a form with menuFocusSkin:"mFSkin",Skin with the same name shou
ld be created.
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
Window Phone (Mango)
4.1.7 menuItems
menuItems represents the list of items to be displayed in the device menu control. Unlike application menu
items, which are available across all the forms, these items are only available for a specific form.
Syntax
JavaScript: menuItems
Lua: menuitems
Type
Lua: Table
Read / Write
Yes - (Write only) [Applicable on BlackBerry and Windows platforms]
JavaScript Example
//Defining a form with menuItems:[menu1,menu2]
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
Available on all platforms except iOS, SPA, Desktop Web, Windows Kiosk, and Windows Tablet
4.1.8 menuNormalSkin
This is a skin property and it determines the look and feel of a menu items when not in focus.
Syntax
JavaScript: menuNormalSkin
Lua: menunormalskin
Type
JavaScript: String
Lua: String
Read / Write
Yes (Write only)
JavaScript Example
//Defining a form with menuNormalSkin:"mSkin",Skin with the same name shou
ld be created.
skin:"frmSkin", needAppMenu:true, headers:[hbox1,hbox2], footers:[hbox3,hb

ox4], menuNormalSkin:"mSkin", menuFocusSkin:"mFSkin", menuItems:[menu1,men
u2]};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
Available on all platforms except Windows Tablet, Windows Kiosk, and Desktop Web
4.1.9 needAppMenu
Specifies if the application menu items should be displayed as a part of the menu controls on the form.
Default: true (Indicates that the application menu must be displayed.)
false - indicates that the application menu must not be displayed.
Syntax
JavaScript: needAppMenu
Lua: needappmenu
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with needAppMenu:true
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE, title:"Welcome",

var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
4.1.10 skin
Specifies a background skin for Form widget.
Note: Server side Mobile Web (basic ) and SPA (BB NTH) devices does not support Vertical gradient and
Vertical split skins. Transparent skin is not supported on SPA(Windows) platform.
Note: Server side Mobile Web (BB xhtml) does not support Image skin.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining a form with skin:"frmSkin",Skin with the same name should be cr
eated.
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE , title:"Welcome",
paddingInPixel:false,
var frmPSP ={};
padding:[5,5,5,5]};
//Creating a form.
Accessible from IDE

Yes
4.1.11 title
Specifies the title of the form.
Syntax
JavaScript: title
Lua: title
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a form with title:"Welcome"
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE ,title:"Welcome",
x1,hbox2],
footers:[hbox3,hbox4], menuNormalSkin:"mSkin", menuFocusSkin:"mFSkin", men
uItems:[menu1,menu2]};
var frmPSP ={};
//Creating a form.
//Reading title of the form

alert("form title::"+frm.title);
Accessible from IDE

Yes
4.1.12 type
Specifies the type of Form. The following are the available types of Form:
l
FORM_TYPE_NATIVE (default)
FORM_TYPE_STATIC
FORM_TYPE_DYNAMIC
Note: Windows Phone (Mango) and Desktop Web platforms support only FORM_TYPE_NATIVE option.
Syntax
JavaScript: type
Lua: type
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining a form with type:constants.FORM_TYPE_NATIVE
e", skin:"frmSkin", needAppMenu:true, enabledForIdleTimeout:true, headers:
[hbox1,hbox2], footers:[hbox3,hbox4], menuNormalSkin:"mSkin", menuFocusSki
n:"mFSkin", menuItems:[menu1,menu2]};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
4.2 Form - Layout Properties

The layout properties for Form Widget are as follows:
l
displayOrientation
gridCell
layoutMeta
layoutType
padding
paddingInPixel
4.2.1 displayOrientation
Specifies the orientation of the form when displayed.
Following are the options available:
l
FORM_DISPLAY_ORIENTATION_PORTRAIT - On the device the form is always displayed such

that the horizontal sides are shorter than vertical sides.
FORM_DISPLAY_ORIENTATION_LANDSCAPE - On the device the form is always turned sideways

so that the height of the screen becomes width.
FORM_DISPLAY_ORIENTATION_BOTH - On the device the form is displayed based on the device

orientation. If the device orientation is vertical, portrait is applied and if the orientation is horizontal,
landscape is applied.
Default: Portrait (iPhone, iPad, BlackBerry)

Default: Both (Windows Phone, and Android)
To know more about iPad Orientations and FAQ's, see iPad_Orientations in Kony Studio User Guide.
Note: For BlackBerry, you must be aware of the following:
- BlackBerry platform recommends that you override the onDeviceBack event for the form which is in
Landscape mode and can be changed to portrait mode. You must typically display an alert "Please rotate the
phone to go back".
- If a service call is required before displaying a new form, BlackBerry platform recommends that you display
an interstitial loading form before displaying the new form.
Note: For iOS, in general, and BlackBerry, the orientation mode is respected only if the device is in that
orientation already. For example, if a form orientation is set as landscape, it will display the form in
landscape mode only if the device is already in the landscape mode. Generally the user is asked to rotate
the device in the landscape mode before displaying a form which is marked as landscape.
Note: For Windows Phone 8 and Windows 8.1, irrespective of the orientation, if the image has to be appear
as it was capture, set the displayOrientation as FORM_DISPLAY_ORIENTATION_BOTH. If you set
displayOrientation as FORM_DISPLAY_ORIENTATION_PORTRAIT and the image is captured in
landscape mode, then the captured image is tilted by 90 degrees when the device is rotated.
The following image illustrates both portrait and landscape orientation:
Syntax
JavaScript: displayOrientation
Lua: displayorientation
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining a form with displayOrientation:constants.FORM_DISPLAY_ORIENTATI
ON_BOTH
skin:"frmSkin", needAppMenu:true, menuNormalSkin:"mSkin", menuItems:[menu1
,menu2]};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Windows Kiosk, Desktop Web, and SPA (all
channels)
4.2.2 gridCell
Note: This property is applicable only when a widget is placed inside a container widget with Grid Layout
applied.
Represents the grid cell details in the sequence colSpan, rowSpan, rowNo, colNo. Description of the details
are as follows:
l
colSpan: Specifies the number of columns that a grid should span. Default value is 1.
rowSpan: Specifies the number of rows that a grid should span. Default value is 1.
rowNo: Specifies the row number in where the widget is placed in a grid layout.
colNo: Specifies the column number in where the widget is placed in a grid layout.
Note: Layout type is not visible as a property. It is set when the user applies XYLayout or GridLayout on a
form. The default option is XYLayout. To set GridLayout, right-click on the form and select Apply
GridLayout.
Syntax
JavaScript: gridCell
Lua: gridCell
Type
Lua:table
Read / Write
JavaScript Example
//Defining a form with layoutType:CONTAINER_LAYOUT_GRID.
e"};
paddingInPixel:false, padding:[5,5,5,5], layoutType: constants.CONTAINER_L
AYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}, gridcell:{"colSpan":1, "rowSpan":1, "rowNo":1, "colNo":1}};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
4.2.3 layoutMeta
A custom JSObject with the key, value pairs that developer can use to provide the meta info about the grid
layout. The following are the mandatory keys required to be part of the Meta.
Note: The data for layoutmeta data is set when you set grid layout view properties for rows and columns.
This property can be set using Kony Studio Grid Layout view. To set the view, go to Window > Show View >
Others and select GridLayout View from Kony Studio folder.
rows : no of grid rows
cols : no of grid cols
colmeta: [{width : "width in %"}]
The sum total of percentage(%) widths of each of the columns in the grid layout should add up to 100%.
Syntax
JavaScript: layoutMeta
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining a form with layoutMeta.
e"};
AYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
4.2.4 layoutType
Defines the type of the layout of widget. Following are the available options:
l
CONTAINER_LAYOUT_BOX: This is the default options on both Windows Tablet and Desktop Web
platforms.
CONTAINER_LAYOUT_GRID: In grid layout the form is split it to rows and columns.
form. From the IDE, the default option is XYLayout. To set GridLayout, right-click on the form and select
Apply GridLayout.
Syntax
JavaScript: layoutType
Lua: layouttype
Type
Lua:String - [Mandatory]
Read / Write
Yes - (Read only)
JavaScript Example
//Defining a form with layoutType:CONTAINER_LAYOUT_GRID.
e"};
AYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
4.2.5 padding
Defines the space between the content of the widget and the widget boundaries. You can use this option to
define the top, left, right, and bottom distance between the widget content and the widget boundary.
To define the padding values for a platform, click the (
) button against the property to open the
Padding screen. Select the checkbox against the platform for which you want to define the padding's and
enter the top, left, right, and bottom padding values.
If you want to use the padding values set for a platform across other platforms, you can click the Apply To
button and select the platforms on which you want the padding values to be applied. The Array accepts the
values in the sequence [left, top, right, bottom].
Note: Due to Browser restrictions, you cannot apply Padding for a ComboBox, Form and ListBox widgets
on Mobile Web platform. Padding is not supported by Windows Mobile browser for Box and Image Gallery.
Note: If no skin is applied to a Button, then Padding is not supported on iPhone. This is due to iOS Safari
browser limitation. If you want the padding to be applied, apply a skin to the button and then apply padding.
The following image illustrates the window to define the padding's for platforms:
The following image illustrates a widget with a defined padding:
Syntax
JavaScript: padding
Lua: padding
Type
JavaScript: Array of Numbers
Lua: Table
Read / Write
JavaScript Example
//Defining a form with padding:[5,5,5,5](percentage based padding)
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE ,title:"Welcome",
x1,hbox2],
footers:[hbox3,hbox4], menuNormalSkin:"mSkin", menuFocusSkin:"mFSkin", men
uItems:[menu1,menu2]};
var frmPSP ={};
//Creating a form.
//Reading the padding of form.
alert("form padding is ::"+frm.padding);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web
Indicates if the padding is to be applied in pixels or in percentage.
Default: false
If set to true, the padding is applied in pixels.
If set to false, the padding is applied as set in padding property.
Note: This property can be set to true or false only for iPhone, iPad, Android and Windows Phone. On other
platforms this property does not give any results even when set to true.
Note: For backward compatibility on older projects, this property is will be made true for iPhone, iPad,
Android and Windows Phone and for other platforms it will be false.
Syntax
JavaScript: paddingInPixel
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with paddingInPixel:true
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE, title:"Welcome",
skin:"frmSkin", needAppMenu:true, menuItems:[menu1,menu2]};
paddingInPixel:true, padding:[5,5,5,5]};
var frmPSP ={};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
BlackBerry 10
4.3 Form - Platform Specific Properties

The platform specific properties for Form Widget are as follows:
l
actionBarIcon
animateHeaderFooter
bounces
captureGPS
contextPath
configureExtendTop
configureExtendBottom
configureBarStyle
defaultIndicatorColor
enablePeekGesture
extendTop
extendBottom
statusBarStyle
footerOverlap
formTransperencyDuringPostShow
headerOverlap
inTransitionConfig
layout
maxAppMenuButtons
menuPosition
needsIndicatorDuringPostShow
noCache
outTransitionConfig
retainScrollPosition
scrollDirection
secureData
showBottomActionBar
showActionBar
showActionBarIcon
showMiniAppMenu
submitSecure
titleBar
titleBarConfig
titleBarSkin
viewConfig
windowSoftInputMode
4.3.1 actionBarIcon
Specifies the image for action bar icon. It is displayed on the left side of the action bar.
Note: This property is displayed in the widget properties list only when you select SDK versions 3.0 and
above in the Application Properties > Native >Android > SDK Versions section.
Note: The application icon is displayed, when the image for action bar icon is not selected but the
showActionBarIcon is set to true.
Syntax
JavaScript: actionBarIcon
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining a form with actionBarIcon:"acticon"
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE, title:"Welcom
e"};
var frmPSP ={actionBarIcon:"acticon", showActionBarIcon: true};
//Creating a form.
Accessible from IDE

Yes
This property is available on Android/Android tablet only
4.3.2 animateHeaderFooter
Specifies if the headers and footers of the Form must slide up and down respectively away from the view
when the Form is in transition.
Note: The headers and footers will animate only if the headers and footers of the transitioning Forms are
different and have the property set to true.
Default: false (the header and footers do not animate)
If you want to allow animation of headers and footers, set the value to true.
Syntax
JavaScript: animateHeaderFooter
Lua: animateheaderfooter
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with animateHeaderFooter:false
e"};
var frmPSP ={animateHeaderFooter:false};
//Creating a form.
Accessible from IDE

Yes
This property is available on Windows Phone and Windows Kiosk platforms.
4.3.3 bounces
Specifies whether the scroll view bounces past the edge of the content and back again.
Default:true
If set to false, the scroll view bounce is not applied.
If set to true, the scroll view bounce is applied.
Syntax
JavaScript: bounces
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining a form with bounces:true
e"};
var frmPSP ={bounces:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.4 captureGPS
Specifies if the Form must display a popup seeking permission from the user to access the location details.
Note: For this property to work, you must have selected Requires GPS functionality in the Project
Properties of the Application (For more information, see the Configuring Project Properties section of the
Kony Studio User Guide) to enable the application to use the GPS functionality.
Default: false (the checkbox is not selected and the popup does not appear when you navigate to the Form)
If you want the popup to appear when you navigate to the specified Form, set the value to true (select the
checkbox).
The following image illustrates the popup to access the location details:
Syntax
JavaScript: captureGPS
Lua: capturegps
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with captureGPS:true
e"};
var frmPSP ={captureGPS:true};
//Creating a form.
Accessible from IDE

Yes
This property is available on Mobile Web (advanced)
4.3.5 contextPath
Specifies the context path to be displayed in the address field of the browser. For more information about
specifying a context path, refer the Kony Studio Users Guide.
Default: none
Note: This field is only populated when you specify a Context ID and a corresponding Context Path in the
Site Minder tab under Mobile web in the Project properties window.
Syntax
JavaScript: contextPath
Lua: contextpath
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining a form with contextPath:"https://www.xyz.com"
e"};
var frmPSP ={contextPath:"https://www.xyz.com"};
//Creating a form.
Accessible from IDE

Yes
l
Server side Mobile Web (basic)
Server side Mobile Web (BJS)
Server side Mobile Web (advanced)
This property enables you to configure extendTop property.
Default:false
If set to true, the property extendTop is displayed.
If set to false, the property extendTop is not displayed.
Syntax
None. Its an IDE only property
Read / Write
No
Accessible from IDE

Yes
l
iPhone
iPad
4.3.7 configureExtendBottom
This property enables you to configure extendBottom property.
Default:false
If set to true, the property extendBottom is displayed.
If set to false, the property extendBottom is not displayed.
Syntax
Read / Write
No
Accessible from IDE

Yes
l
iPhone
iPad
4.3.8 configureBarStyle
This property enables you to configure statusBarStyle property.
Default:false
If set to true, the property statusBarStyle is displayed.
If set to false, the property statusBarStyle is not displayed.
Syntax
JavaScript: configureBarStyle
Type
JavaScript: Boolean
Read / Write
No
JavaScript Example
//Defining a form with extendBottom:true
e"};
var frmPSP ={statusBarStyle:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.9 defaultIndicatorColor
This property enables you to set color to the progress indicator when it is show on the form. It overrides the
application level setting set using setApplicationbehavior() for this form.
Default:color in RGBA hex code
Syntax
JavaScript: defaultIndicatorColor
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining a form properties.
e"};
var frmPSP ={statusBarStyle:true};
//Creating a form.
Accessible from IDE

No
l
Android
Android Tablet
4.3.10 enablePeekGesture
Specifies if the peek gesture must be enabled on the form.
Default:true
If set to true, the peek gesture is enabled.
If set to false, the peek gesture is disabled.
Syntax
JavaScript: enablePeekGesture
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining a form properties
e"};
var frmPSP ={};
//Creating a form.
form.enablePeekGesture = true;
Accessible from IDE

No
This property is available on BlackBerry10 platform only
4.3.11 extendTop
Specifies the form content to scroll under the App Menu. This property is supported in iOS7 and above only.
This property is also applicable on the Application Level properties under Application Properties > Native
>iPhone/iPad > Platform Settings. The property set at form level takes precedence over Application level.
Default:false
If set to true, the form scroll under the App Menu.
Note: This property is applicable on form level headers and footers, app level headers and footers, title bar,
and app menu.
Syntax
JavaScript: extendTop
Type
JavaScript: Boolean
Read / Write
Yes (Read and Write)
JavaScript Example
//Defining a form with extendTop:true
e"};
var frmPSP ={extendTop:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.12 extendBottom
This property enables you to configure extendBottom property. This property is supported in iOS7 and above
only. This property is also applicable on the Application Level properties under Application Properties > Native
>iPhone/iPad > Platform Settings. The property set at form level takes precedence over Application level.
Default:false
If set to true, the property extendBottom is displayed.
Note: This property is applicable on form level headers and footers, app level headers and footers, title bar,
and app menu.
Syntax
JavaScript: extendBottom
Type
JavaScript: String
Read / Write
No
JavaScript Example
e"};
var frmPSP ={extendBottom:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.13 statusBarStyle
This property enables you to set the status bar style.
Following are the available options:
l
constants.STATUS_BAR_STYLE_DEFAULT: The status bar contents are displayed in black color

suitable for a light background.
constants.STATUS_BAR_STYLE_LIGHT_CONTENT: The status bar contents are displayed in white

color suitable for a dark background.
Syntax
JavaScript: statusBarStyle
Type
JavaScript: String
Read / Write
No
JavaScript Example
e"};
var frmPSP ={statusBarStyle:constants.STATUS_BAR_STYLE_LIGHT_CONTENT};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.14 footerOverlap
Specifies if the footer must overlap the form. For example, every time you scroll the form, the footer is fixed
and the footer overlap the form as specified in the Footer Overlap field. If this field is selected, the form scrolls
behind the footer background and a part of the footer background is transparent.
Default: false
Syntax
JavaScript: footerOverlap
Lua: footeroverlap
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with footerOverlap:true
e"};

var frmPSP ={footerOverlap:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.15 formTransparencyDuringPostShow
Specifies the transparency in percentage when a form is loaded.
Normally, when a form is loading, the user interface is blocked. You can use this property to specify the
percentage of transparency.
Default: 100
The following image illustrates the transparency as 0 during post show:
Syntax
JavaScript: formTransparencyDuringPostShow
Lua: formtransparencyduringpostshow
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining a form with formTransparencyDuringPostShow:0
e"};
var frmPSP ={formTransparencyDuringPostShow:0};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.16 headerOverlap
Specifies if the header must overlap the form. For example, every time you scroll the form, the header is fixed
and the header overlap the form as specified in the header overlap field. If this field is selected, the form
scrolls behind the header background and a part of the header background is transparent.
Default: false
Syntax
JavaScript: headerOverlap
Lua: headeroverlap
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with headerOverlap:true
e"};
var frmPSP ={headerOverlap:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
When building iPhone applications that support or provide text input, it's often necessary to create some extra
buttons (or other controls) beyond the ones provided by the default keyboard interface. Kony Platform by
default, adds the Previous, Next and Done buttons to the applicable input controls. These buttons allow
specific operations needed by your application, such as moving to the next or previous text field, make the
keyboard disappear. The area above the keyboard is known as Input Accessory View.
This property, allows you to specify the type of accessory view that will be shown for all the input controls on
this form.
Note: The inputAccessoryViewType defined in the form level takes precedence over the
inputAccessoryViewType defined in application level settings.
Note: For iOS, by default header with "Prev" and "Next" buttons will be prepended to the keypad. This
header can be turned off at two levels Application Level and Form Level.
To turn on/off the header at Application Level, follow these steps:
1. Go to Applications view.
2. Right-click on the application and select Properties.
3. Navigate to Native App tab, under Platform Settings change the value to none.
To turn on/off the header at Form Level, follow these steps:
1. Select the form and go to Widget Properties .
2. Under iPhone properties, select inputAccessoryViewType and set the value to FORM_
INPUTACCESSORYVIEW_NONE.
Default: FORM_INPUTACCESSORYVIEW_DEFAULT
l
FORM_INPUTACCESSORYVIEW_NONE: Use this option if you do not want to specify the toolbar.
This option should be used carefully, as setting this option for widgets like calendar leaves the user
with no option to select and drop-down a wheel calendar.
FORM_INPUTACCESSORYVIEW_DEFAULT: Specifies that the toolbar that is defined in the

Application level settings. To set the Application level settings, right-click on the project and navigate
to Properties> Native App>iPhone/iPad.
FORM_INPUTACCESSORYVIEW_NEXTPREV: Specifies the navigation options as Next,

Previous, and Done for a form. The below image illustrates the nextprevtoolbar set for a Textbox. The
highlighted toolbar is achieved by setting the Keyboard Type as Default for a Textbox and Input
Accessory View Type as nextprevtoolbar to the Form.
FORM_INPUTACCESSORYVIEW_CANCEL: Specifies that the input accessory view has a cancel

button. This option does not trigger any events.
Syntax
JavaScript: inputAccessoryViewType
Lua: inputaccessoryviewtype
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining a form with inputAccessoryViewType:constants.nextprevtoolbar
e"};
var frmPSP ={inputAccessoryViewType:constants.FORM_INPUTACCESSORYVIEW_NEXT
PREV};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
Specifies the configuration to be used when the user arrives on this form. It accepts hash values.
Following are the properties available for iPhone and iPad:
Note: On iOS platform, In Transition is the transition that gets applied as the form enters the navigation
stack. Every form.show either results in push into navigation stack (enter the navigation stack) or if the form
is already in stack, results popping up all the forms including the current form from the navigation stack. This
is done to be in sync with the iOS native semantics of form (UIView Controller) transitions.
transitionDirection: Specifies the direction from which the From is displayed. The available options are:
1. none - Use this option if you do not want to specify a transition direction.
2. fromRight - Specifies that the Form must appear from the right.
3. fromLeft - Specifies that the Form must appear from the left.
4. fromBottom - Specifies that the Form must appear from the bottom.
5. fromTop - Specifies that the Form must appear from the top.
transitionEffect: Specifies the effect from which the form is displayed. The available options are:
2. transitionFade - Specifies that the form must fade when it is transitioned to a hidden or an invisible
state.
3. transitionMoveIn - Specifies that the form must slide over the existing content in the direction as
specified in the transitionDirection.
4. transitionPush - Specifies that the form must push the existing content in the direction as specified in
the transitionDirection and take its place.
5. transitionFlip - Specifies that the form must be rotated along the Y-axis as the content is being
displayed. It supports transition directions fromRight and fromLeft only.
6. transitionReveal - Specifies that the form must be revealed gradually in the direction as specified in the
transitionDirection.
7. transitionCurl - Specifies that the form must be curled or folded (look and feel is similar to turning of a
page in a book) as the content is being displayed. It supports transition directions fromTop and
fromBottom only.
8. transitionTwoSplitHorizontalIn - Specifies the form which is split horizontally into two parts rejoins
when the transition takes place.
9. transitionTwoSplitVerticalIn - Specifies the form which is split vertically into two parts rejoins when the
transition takes place.
10. transitionFourSplitIn - Specifies the form which is split in four parts rejoins when the transition takes
place.
11. transitionFourSplitRotateIn - Specifies the form which is split in four parts rejoins by rotating the parts
12. transitionTwoSplitHorizontalOut - Specifies the form which is split horizontally into two parts and move
away when the transition takes place.
13. transitionTwoSplitVerticalOut - Specifies the form which is split vertically into two parts and move
14. transitionFourSplitRotateOut - Specifies the form which is split in four parts move away by rotating the
parts when the transition takes place.
15. transitionSwitchLeft - Specifies that the form must go out of the view in 3D circular space along the Yaxis towards left as the content is being displayed.
16. transitionSwitchRight - Specifies that the form must go out of the view in 3D circular space along the
Y-axis towards right as the content is being displayed.
17. transitionCloth - Specifies the present form must go out of screen animating as if a cloth is removed.
18. transitionFlipRight - Specifies that the form must be rotated along the Y-axis as the content is being
displayed giving an illusion of a page is turned towards right in a book.
19. transitionFlipLeft - Specifies that the form must be rotated along the Y-axis as the content is being
displayed giving an illusion of a page is turned towards left in a book.
20. transitionDoor - Specifies that the form must be revealed giving an illusion of a opening a door.
21. transitionRotateExchange - Specifies that the form must be rotated along the X-axis as the content is
being displayed.
The below effects applicable to Android platform:
1. default/none - The constant value is 0. The default device effect is applied or none of the effect is
applied.
2. bottom-top - The constant value is 1. It specifies that the form must slide-in from the bottom and
proceed towards the top.
3. from left - The constant value is 2. It specifies that the form must slide-in from the left with a fade
effect.
4. from right - The constant value is 3. It specifies that the form must slide-in from the right with a fade
effect.
5. to right - The constant value is 4. It specifies that the form must slide-out to the right with a fade effect.
6. to left - The constant value is 5. It specifies that the form must slide-out to the left with a fade effect.
7. from center - The constant value is 6. It specifies that the form must grow from the center with a fade
effect.
8. topright-bottom - The constant value is 7. It specifies that the form must slide-in from the top-right
corner and proceed towards the bottom.
9. bottomleft-top - The constant value is 8. It specifies that the form must slide-in from the bottom-left
corner and proceed towards the top.
10. bottom-top style1 - The constant value is 9. It specifies that the form must shrink from the bottom
towards the top.
11. top down - The constant value is 10. It specifies that the form must slide-in from the top and proceed
towards the bottom.
//sample code to set inTransitionConfig with the option bottom-top.

frm.inTransitionConfig= {formAnimation: 1 };
Following are the properties available for Windows Phone (Mango):

transitionMode: Specifies the direction from which the From is displayed. The available options are:
1. Default (none) - The default device effect is applied or none of the effect is applied.
2. Sequential- The transition of the Form going out of the view completes first and then the transition of
the Form coming into the view takes place.
3. Parallel- The transition of the Form going out of the view and the transition of the Form coming into the
view takes place simultaneously.
inTransition: Specifies the effect from which the From is displayed. The available options are:
1. Default (none) - Specifies that the Form must slide horizontally into the view.
2. Rotate3DSingle - Specifies that the Form must be rotated along the center Y-Axis when coming into
the view.
3. Rotate3DDual - Specifies that the Form must be shown making a circle around the screen from the
background before coming into the view.
4. Slide - Specifies that the Form must slide horizontally into the view.
5. Pop - Specifies that the Form must emerge from center-bottom of the screen and gradually occupy the
complete screen.
6. Squeeze - Specifies that the Form must be expanded horizontally from an initial width of zero.
transitionSpeed: Specifies the speed at which the From is transitioned. The value must be specified in
seconds.
On Symbian Platform, Default Transition can be set to true or false. When set to true, the default transition is
applied.
On SPA and Desktop Web Platforms, Transition has the below options to set:
1. None- Use this option if you do not want to specify a transition direction.
2. Top Center - Specifies that the form must appear from the top center.
3. Bottom Center - Specifies that the form must appear from the bottom center.
4. Right Center - Specifies that the form must appear from the right center.
5. Left Center - Specifies that the form must appear from the left center.
Syntax
JavaScript: inTransitionConfig
Lua: intransitionconfig
Type
Lua: Table
Read / Write
JavaScript Example
//Defining a form with inTransitionConfig:{transitionDirection:"topCenter"}
e"};
var frmPSP ={inTransitionConfig:{transitionDirection:"topCenter"}};
//Creating a form.
Accessible from IDE

Yes
Available on all platforms except BlackBerry, Server side Mobile Web, and Windows Tablet.
4.3.19 layout
Specifies if the arrangement of the widgets either in horizontal or vertical direction.
Default: Vertical
l
Vertical : The navigation happens in vertical direction.
Horizontal : The navigation happens in horizontal direction.
Syntax
JavaScript: layout
Lua: layout
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining a form with layout:horizontal
e"};
var frmPSP ={layout:constants.Horizontal};
//Creating a form.
Accessible from IDE

Yes
This property is available on Windows Tablet
4.3.20 maxAppMenuButtons
Specifies the number of appmenu buttons should be displayed on the screen.
Default: 4
Syntax
JavaScript: maxAppMenuButtons
Type
JavaScript: Number
Read / Write
No
JavaScript Example
//Defining a form with maxAppMenuButtons:4
e"};
var frmPSP ={maxAppMenuButtons:4};
//Creating a form.
Accessible from IDE

Yes
l
Windows Phone
Windows Tablet
Windows Kiosk
4.3.21 menuPosition
Specifies if the application menu is shown or hidden in the application. In some platforms, form menu items
appear along with app menu items. This property allows developer to configure weather to append at the end
of application menu list or inserted at beginning of the application menus.
Default : FORM_MENU_POSITION_AFTER_APPMENU
FORM_MENU_POSITION_BEFORE_APPMENU
FORM_MENU_POSITION_AFTER_APPMENU
Syntax
JavaScript: menuPosition
Lua: menuposition
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining a form with menuPosition:
e"};
var frmPSP ={menuPosition:constants.FORM_MENU_POSITION_BEFORE_APPMENU};
//Creating a form.
Accessible from IDE

Yes
This property is available on Android/Android Tablet and BlackBerry
4.3.22 needsIndicatorDuringPostShow
Specifies if there must be an indication to the user that the form content is being loaded.
You can use this property typically for forms that require network calls during post show.
Default: true
If set to false, the progress indicator is not displayed.
If set to true, the progress indicator is displayed.
The following image illustrates the loading indicator:
Syntax
JavaScript: needsIndicatorDuringPostShow
Lua: needsindicatorduringpostshow
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with needsIndicatorDuringPostShow:true
e"};
var frmPSP ={needsIndicatorDuringPostShow:true};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
4.3.23 noCache
A web cache is a mechanism for the temporary storage (caching) of web documents, such as HTML pages
and images, to reduce bandwidth usage, server load, and perceived lag. This property indicates that if the
form is enabled for caching on the device browser.
Default: true
If set to false, appropriate Cache control headers are included in the HTTP response.
If set to true, cache control headers are not included in the HTTP response.
Syntax
JavaScript: noCache
Lua: nocache
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with noCache:false
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE , title:"Welcom
e"};
var frmPSP ={noCache:false};
//Creating a form.
Accessible from IDE

Yes
l
Specifies the type of transition effect to be applied when the Form is going out of view. It accepts hash values.
Note: On iOS platform, Out Transition is the transition that gets applied as the form leaves the navigation
stack. Every form.show either results in push into navigation stack (enter the navigation stack) or if the form
is already in stack, results popping up all the forms including the current form from the navigation stack. This
is done to be in sync with the iOS native semantics of form (UIView Controller) transitions.
transitionDirection: Specifies the direction from which the form must disappear in a view. You can choose
one of the following options:
2. fromRight - Specifies that the Form must disappear from the right.
3. fromLeft - Specifies that the Form must disappear from the left.
4. fromBottom - Specifies that the Form must disappear from the bottom.
5. fromTop - Specifies that the Form must disappear from the top.
transitionEffect: Specifies the type of transition effect to be applied when the Form disappears in the view.
You can choose one of the following transition effects:
2. transitionFade - Specifies that the form must fade when it is transitioned to a hidden or an invisible
state.
3. transitionMoveIn - Specifies that the form must slide over the existing content in the direction as
4. transitionPush - Specifies that the form must push the existing content in the direction as specified in
5. transitionFlip - Specifies that the form must be rotated along the Y-axis as the content is being
displayed. It supports transition directions fromRight and fromLeft only.
6. transitionReveal - Specifies that the form must be revealed gradually in the direction as specified in the
7. transitionCurl - Specifies that the form must be curled or folded (look and feel is similar to turning of a
page in a book) as the content is being displayed. It supports transition directions fromTop and
fromBottom only.
8. transitionTwoSplitHorizontalIn - Specifies the form which is split horizontally into two parts rejoins
9. transitionTwoSplitVerticalIn - Specifies the form which is split vertically into two parts rejoins when the
transition takes place.
10. transitionFourSplitIn - Specifies the form which is split in four parts rejoins when the transition takes
place.
11. transitionFourSplitRotateIn - Specifies the form which is split in four parts rejoins by rotating the parts
12. transitionTwoSplitHorizontalOut - Specifies the form which is split horizontally into two parts and move
13. transitionTwoSplitVerticalOut - Specifies the form which is split vertically into two parts and move
14. transitionFourSplitRotateOut - Specifies the form which is split in four parts move away by rotating the
parts when the transition takes place.
15. transitionSwitchLeft - Specifies that the form must go out of the view in 3D circular space along the Yaxis towards left as the content is being displayed.
16. transitionSwitchRight - Specifies that the form must go out of the view in 3D circular space along the
Y-axis towards right as the content is being displayed.
17. transitionCloth - Specifies the present form must go out of screen animating as if a cloth is removed.
18. transitionFlipRight - Specifies that the form must be rotated along the Y-axis as the content is being
displayed giving an illusion of a page is turned towards right in a book.
19. transitionFlipLeft - Specifies that the form must be rotated along the Y-axis as the content is being
displayed giving an illusion of a page is turned towards left in a book.
20. transitionDoor - Specifies that the form must be revealed giving an illusion of a opening a door.
21. transitionRotateExchange - Specifies that the form must be rotated along the X-axis as the content is
being displayed.
applied.
2. bottom-top - The constant value is 1. It specifies that the form must slide-out from the bottom and
3. from left - The constant value is 2. It specifies that the form must slide-out from the left with a fade
effect.
4. from right - The constant value is 3. It specifies that the form must slide-out from the right with a fade
effect.
5. to right- The constant value is 4. It specifies that the form must slide-in to the right with a fade effect.
6. to left- The constant value is 5. It specifies that the form must slide-in to the left with a fade effect.
7. from center- The constant value is 6. It specifies that the form must grow from the center with a fade
effect.
8. topright-bottom - The constant value is 7. It specifies that the form must slide-in from the top-right
9. bottomleft-top - The constant value is 8. It specifies that the form must slide-in from the bottom-left
10. bottom-top style1 - The constant value is 9. It specifies that the form must shrink from the bottom
towards the top.
11. top down - The constant value is 10. It specifies that the form must slide-in from the top and proceed
towards the bottom.
//sample code to set outTransitionConfig with the option top down.

frm.outTransitionConfig= {formAnimation: 10 };

transitionMode: Specifies the direction from which the From is displayed. The available options are:
1. Default (none)- The default device effect is applied or none of the effect is applied.
2. Sequential- The transition of the Form going out of the view completes first and then the transition of
the Form coming into the view takes place.
3. Parallel- The transition of the Form going out of the view and the transition of the Form coming into the
outTransition: Specifies the effect from which the From is displayed. The available options are:
1. Default (none)- Specifies that the Form must slide horizontally into the view.
2. Rotate3DSingle - Specifies that the Form must be rotated along the center Y-Axis when coming into
the view.
3. Rotate3DDual - Specifies that the Form must be shown making a circle around the screen from the
4. Slide - Specifies that the Form must slide horizontally into the view.
5. Pop - Specifies that the Form must emerge from center-bottom of the screen and gradually occupy the
complete screen.
6. Squeeze - Specifies that the Form must be expanded horizontally from an initial width of zero.
transitionSpeed: Specifies the speed at which the From is transitioned. The value must be specified in
seconds.
applied.
On SPA and Desktop Web Platforms, Transition has the below options to set:
2. Top Center - Specifies that the form must disappear from the top center.
3. Bottom Center - Specifies that the form must disappear from the bottom center.
4. Right Center - Specifies that the form must disappear from the right center.
5. Left Center - Specifies that the form must appear from the left center.
Syntax
JavaScript: outTransitionConfig
Lua: outtransitionconfig
Type
Lua: Table
Read / Write
JavaScript Example
//Defining a form with outTransitionConfig:{transitionDirection:"topCente
r"}
e"};
var frmPSP ={outTransitionConfig:{transitionDirection:"topCenter"}};
//Creating a form.
//Reading outTransitionConfig of the form
alert("form outTransitionConfig::"+frm.outTransitionConfig);
Accessible from IDE

Yes
Available on all platforms except BlackBerry, Server side Mobile Web, and Windows Tablet.
4.3.25 retainScrollPosition
Specifies if the Form must remember the scroll position when the user revisits the Form.
Default: false (Form does not remember the scroll position)
If set to true, the scroll position of the Form is retained at the same location when the Form was last visited.
If set to false, the Form scroll position will be set to top.
Syntax
JavaScript: retainScrollPosition
Lua: retainscrollposition
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with retainScrollPosition:true
e"};
var frmPSP ={retainScrollPosition:true};
//Creating a form.
Accessible from IDE

Yes
Available on all platforms except on Server side Mobile Web and Windows Phone platforms.
Specifies the direction in which the form should scroll.
Default : SCROLL_VERTICAL
l
SCROLL_VERTICAL: Specifies the form to scroll in vertical direction.
SCROLL_NONE: Specifies the form not to scroll in any direction.
Syntax
JavaScript: scrollDirection
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining a form with scrollDirection:constants.SCROLL_VERTICAL
e"};
var frmPSP ={scrollDirection:constants.SCROLL_VERTICAL};

//Creating a form.
Accessible from IDE

No
l
iPhone
iPad
4.3.27 secureData
Specifies if the browser must retain and use the information that you have filled in a form (for example,
username and password) and use it during the POST request made when you refresh the browser or use the
back button on the browser.
Default: the option is not selected (the browser will retain data and use it during POST request)
If you do not want the browser to use the information during the POST request made when you refresh the
browser or use the back button on the browser, select the checkbox.
Syntax
JavaScript: secureData
Lua: securedata
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with secureData:true
e"};
var frmPSP ={secureData:true};

//Creating a form.
Accessible from IDE

Yes
l
4.3.28 showBottomActionBar
Specifies if the bottom action bar must be displayed.
Default:true
If set to true, the bottom action bar is displayed.
If set to false, the bottom action bar is not displayed.
Syntax
JavaScript: showBottomActionBar
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining a form properties
e"};
var frmPSP ={};
//Creating a form.
form.showBottomActionBar = true;
Accessible from IDE

No
This property is available on BlackBerry10 platform only
4.3.29 showActionBar
Specifies if the action bar should be displayed.
Default: true
If set to true, the action bar is displayed.
If set to false, the action bar is not displayed.
Syntax
JavaScript: showActionBar
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining a form with showActionBar:true
e"};
var frmPSP ={showActionBar:true, showActionBarIcon: true, actionBarIcon: "
acticon"};
//Creating a form.
Accessible from IDE

Yes
4.3.30 showActionBarIcon
Specifies the icon to be displayed for the action bar.
Default: true
If set to true, the action bar icon is displayed.
If set to false, the action bar icon is not displayed.
Syntax
JavaScript: showActionBarIcon
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining a form with showActionBarIcon:true
e"};
var frmPSP ={actionBarIcon:"acticon", showActionBarIcon: true};
//Creating a form.
Accessible from IDE

Yes
Specifies if the application menu is shown or hidden in the application.
Default: false
The below image illustrates the default mode of an application menu of the form:
Mini
If you set the value to mini the application menu is minimized in the application.
The below image illustrates the Mini mode of an application menu of the form:
Syntax
JavaScript: showMiniAppMenu
Lua: showminiappmenu
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with showMiniAppMenu:true
e"};
var frmPSP ={showMiniAppMenu:true};
//Creating a form.
Accessible from IDE

Yes
This property is available on Windows Phone.
4.3.32 submitSecure
Specifies if the information must be sent using secure connection (https) or insecure connection (http).
This property is useful in scenarios where you want the information sent to be secure. For example, credit
card user credentials, transactions etc.
Default: false (the checkbox is not selected and the information sent is not secure)
To send information securely, set the value to true (select the checkbox).
Note: If you have marked a form to be submitted through a secure protocol, then the popup that is displayed
on the form is also submitted through secured protocol.
Syntax
JavaScript: submitSecure
Lua: submitsecure
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining a form with submitSecure:true
e"};
var frmPSP ={submitSecure:true};
//Creating a form.
Accessible from IDE

Yes
l
4.3.33 titleBar
Specifies the title bar must be displayed on the form.
Default: true
For Tablet channels, following is applicable:
Default: true for android and windows Tablet and false for iPad.
Following are the available options for Windows Tablet:
l
Show Form Titlebar : Specifies if the form title must be visible or invisible.
Show Back button : Specifies if the back button must be displayed in the Form.
You can set the skins for the above two options using the respective drop down box.
We recommend the below image size for form title bar on iOS platform:
iPhone/iPod (3rd and
4th Generations
Portrait Mode (Non-Retina)
Portrait Mode(Retina)
Landscape Mode (Non-Retina)
Landscape Mode (Retina)
iPhone 5th
Generation
iPad (1st, 2nd, and 3rd

Generations)
320x44 px
NA
768x44 px
640x88 px
640x88 px
1024x44 px
480x32 px
NA
1536x88 px
960x64 px
1136x64 px
2048x88 px
Note: If the title bar image is not of the above recommended size, then the image is scaled to that of the
above sizes for respective devices and it leads to low quality or blur image for title bar.
Note: For retina devices, it is must to provide retina images with @2x suffix.
Syntax
JavaScript: titleBar
Lua: titlebar
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
Yes
JavaScript Example
//Defining a form with titleBar:true
e"};
var frmPSP ={titleBar:true};
//Creating a form.
Accessible from IDE

Yes
l
iPad
iPhone
Android
BlackBerry
BlackBerry 10
Windows Tablet
Specifies the position of the title bar of the form.
To set the configuration for a platform, follow the below steps:
1. Click the Ellipsis (
) button of the titleBar property to open the Title Bar screen.
2. Select the checkbox against the platform and click in the Value box.
) button to open the titleBarConfig screen for the respective platform.

l
renderTitleText
titleBarRightSideView
closureRightSideView
titleBarLeftSideView
closureLeftSideView
imageRightSideView
imageLeftSideView
Following are the available options for Windows Tablet:
Show Form Titlebar : Specifies if the form title must be visible or invisible.
Show Back button : Specifies if the back button must be displayed in the Form.
You can set the skins for the above two options using the respective drop down box.
Syntax
JavaScript: titleBarConfig
Lua: titlebarconfig
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining a form with titleBarConfig:{renderTitleText:"text"}
e"};
var frmPSP ={titleBarConfig:{renderTitleText:"text"}};
//Creating a form.
Accessible from IDE

Yes
l
iPhone
iPad
Android
Windows Tablet
4.3.35 titleBarSkin
Specifies the skin to be applied to the titleBar of the form.
Default: None
Syntax
JavaScript: titleBarSkin
Lua: titlebarskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining a form with titleBarSkin:"titleBarSkin"
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE ,title:"Welcome"};
var frmPSP ={titleBarSkin:"titleBarSkin"};
//Creating a form.
//Reading titleBarSkin of the form
alert("form titleBarSkin::"+frm.titleBarSkin);
Accessible from IDE

Yes
l
iPhone
Android
BlackBerry
4.3.36 viewConfig
View Configuration is applicable only when container widget layout is grid.
Note: For more information on applying the Grid layout please refer Kony Studio User Guide.
ViewConfig displays two types of views:
l
Normal view
Grid view
The type of view will be determined by the Reference Width and Reference Height of the view config property,
if reference height and width are greater than 0, then view set is grid view.
For example, if you set an onClick to a box, the onClick event will be executed whenever you click each cell.
Set righttap event using setGestureRecognizer to a box and you can see right click behavior on each cell of
grid view.
Possible value for Reference width and Height:
Default application displays 0,you can give any number greater than 0 to get grid view type of a widget.
Syntax
JavaScript: viewConfig
Lua: viewconfig
Type
JavaScript:JSObject
Lua: table
Read / Write
No
JavaScript Example
//Defining properties for a form with viewConfig
e"};
var frmPSP ={viewConfig: {
referenceHeight: 40,
sizeMode: constants.GRID_TYPE_FIXED,
referenceWidth: 30
};
};
//Creating a form.
Accessible from IDE

Yes
This property is available on Windows Tablet platform.
This property defines how the main Form interacts with the window containing the on-screen soft keyboard. It
determines the adjustments made to the Form whether it is resized smaller to make room for the soft
keyboard or whether its contents pan to make the current focus visible when part of the Form is covered by
the soft keyboard.
l
FORM_ADJUST_RESIZE: Specifies the form is resized and when you click or start typing within the
widget which requires an input, the form scrolls up and the widget which requires an input is not
overlapped by the keypad or footer.
FORM_ADJUST_PAN: Specifies the widget which requires an input is placed at the bottom of the
popup is overlapped by the keypad. The main Form is not resized to make room for the soft keyboard.
Rather, the contents of the Form are automatically panned so that the current focus is never obscured
by the keyboard and users can always see what they are typing. This is generally less desirable than
resizing, because the user may need to close the soft keyboard to get at and interact with obscured
parts of the Form.
The below image illustrates the above two options:
Default: FORM_ADJUST_RESIZE
Syntax
JavaScript: windowSoftInputMode
Lua: windowsoftinputmode
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining a form with windowSoftInputMode:constants.FORM_ADJUST_PAN
e"};
var frmPSP ={windowSoftInputMode:constants.FORM_ADJUST_PAN};
//Creating a form.
Accessible from IDE

Yes
l
BlackBerry 10
4.4 Form - Events

Form Widget has the following events associated:
Note: In Server side Mobile Web platform, only the last event form.show or an alert will be displayed. For
example, If there are 3 alert statements and an event form.show in the end, then form is displayed. Alert will
not be displayed. Similarly you call a form.show and in subsequent statements or in form pre/post events
you call alert then that alert will be displayed but not the form.
l
addWidgets
init
onActionBarBack
onHide
onOrientationChange
onDeviceBack
onDeviceMenu
onDestroy
preShow
postShow
onLoadJS
unLoadJS
4.4.1 addWidgets
An event callback invoked by the platform when the form is accessed for first time after its construction. This
function gets executed only once on in lifetime of the form. If a destroyed form is accessed, the form is reinitialized and this callback is once again invoked. Forms can be destroyed using destroy method.
Signature
JavaScript: addWidgets
Lua: addwidgets
Read / Write
JavaScript Example
//The below function is the callback function for addWidgets event of the
form.
function addWidgetsCalBck(form)
{
//Write your logic here.
}
//Defining a form with addWidgets:addWidgetsCalBck, Where addWidgetsCalBck

is the call back.
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE , title:"Title",
addWidgets:addWidgetsCalBck};
var frmPSP ={};
//Creating a form.
4.4.2 init
This event gets called only once in form life cycle that is when the form is ready with its widget hierarchy. This
will get called after addwidgets method allowing user for any one-time initializations.
When form is destroyed and reused again, init gets called as a part of form lifecycle.
Signature
JavaScript: init
Lua: init
Read / Write
JavaScript Example
//The below function is the callback function for init event of the form
function initCalBck(form)
{
}
//Defining a form with init:initCalBck,Where initCalBck is the call back.
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE , title:"Title",
init:initCalBck};
var frmPSP ={};
//Creating a form.
4.4.3 onActionBarBack
An event callback that is invoked by the platform when the back button is pressed on an action bar. The back
button exists on the left side of the action bar with UP caret symbol. It is enabled only when onActionBarBack
callback is registered on form and showActionBarIcon is set to true.
Note: This event is displayed in the widget properties list only when you select SDK versions 3.0 and above
in the Application Properties > Native >Android > SDK Versions section.
Signature
JavaScript: onActionBarBack
Read / Write
JavaScript Example
//The below function is the callback function for onActionBarBack event of
the form
function onActionBarBackCalBck(form)
{
}
//Defining a form with init:initCalBck,Where initCalBck is the call back.
onActionBarBack :onActionBarBackCalBck};
var frmPSP ={};
//Creating a form.
Available on Android/Android tablet only
4.4.4 onHide
Specifies an Event which is triggered when a form goes completely out of view.
This event is triggered in the following scenarios:
l
form.show (another form) is called
User hits the device back button or key
This event is not triggered in the following scenarios:

l
The form is partially or completely covered by the Popup.
The form is partially or completely covered by the Application Menu.
Signature
JavaScript: onHide
Lua: onhide
Read / Write
JavaScript Example
//The below function is the callback function for onHide event of the form.
function onHideCalBck(form)
{
}
//Defining a form with onHide:onHideCalBck,Where onHideCalBck is the call
back.
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE , title:"Title",
onHide:onHideCalBck};
var frmPSP ={};
//Creating a form.
Specifies an Event which is triggered when there is a change in orientation of the form from portrait to
landscape or vice versa.
Note: Blackberry devices will raise these event only if the displayOrientation mode of the form is set to
FORM_ DISPLAY_ORIENTATION_BOTH.
For more information about defining an action sequence for this event, see Event Editor in the Kony Studio
User Guide.
Signature
JavaScript: onOrientationChange
Lua: onorientationchange
Read / Write
JavaScript Example
//The below function is the callback function for onOrientationChange event
of the form.
function onOrChngCalBck(form)
{
}
//Defining a form with onOrientationChange:onOrChngCalBck, Where onOrChngC
alBck is the call back.
onOrientationChange:onOrChngCalBck};
var frmPSP ={};
//Creating a form.
Available on all platforms except Server side Mobile Web, Windows Kiosk, and Desktop Web
4.4.6 onDeviceBack
Specifies an event which is triggered when the user uses the back button on the device.
For more information see Event Editor in the Kony Studio User Guide.
Signature
JavaScript: onDeviceBack
Lua: ondeviceback
Read / Write
JavaScript Example
//The below function is the callback function for onDeviceBack event of the
form.
function onDevBckCal(form)
{
}
//Defining a form with onDeviceBack:onDevBckCal, Where onDevBckCal is the
call back.
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE, title:"Title"};
var frmPSP ={onDeviceBack:onDevBckCal};
//Creating a form.
//Reading the the onDeviceBack event of the form.
alert("onDeviceBack is ::"+frm.onDeviceBack);
l
BlackBerry
BlackBerry 10
Desktop Web
SPA (iPhone/Android/BlackBerry/Windows NTH)
4.4.7 onDeviceMenu
Signature
JavaScript: onDeviceMenu
Lua: ondevicemenu
Read / Write
JavaScript Example
//The below function is the callback function for onDeviceMenu event of the
form.
function onDevMenCalBck(form)
{
}
//Defining a form with onDeviceMenu:onDevMenCalBck,Where onDevMenCalBck is
the call back.
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE, title:"Title"};
var frmPSP ={onDeviceMenu:onDevMenCalBck};
//Creating a form.
//Reading the the onDeviceMenu event of the form
alert("onDeviceMenu is ::"+frm.onDeviceMenu);
l
BlackBerry 10
4.4.8 onDestroy
Specifies an event which is triggered when the form is destroyed.
Signature
JavaScript: onDestroy
Lua: ondestroy
Read / Write
JavaScript Example
//The below function is the callback function for onDestroy event of the f
orm.
function onDestroycalBck(form)
{
}
//Defining a form with onDestroy:onDestroycalBck, where onDestroycalBck is
the call back.
var frmBasic = {id:"frm",type:constants.FORM_TYPE_NATIVE, title:"Title"};
var frmPSP ={onDestroy:onDestroycalBck};
//Creating a form.
//Reading the the onDestroy event of the form
alert("onDestroy is ::"+frm.onDestroy);
Available on all platforms except BlackBerry 10
4.4.9 preShow
preShow is executed every time a form is to be displayed. This event is called even on device back or while
navigating back to the form through title bar navigation items.
In case of Server side Mobile Web, preShow and postShow will not get executed when navigate using the
browser "back".
Signature
JavaScript: preShow
Lua: preshow
Read / Write
JavaScript Example
//The below function is the callback function for preShow event of the for
m.
function preShowCalBck(form)
{

}
//Defining a form with preShow:preShowCalBck,Where preShowCalBck is the ca
ll back.
preShow:preShowCalBck};
var frmPSP ={};
//Creating a form.
4.4.10 postShow
postShow is invoked after a form is displayed. Gets called even on device back or while navigating back to
the form through title bar navigation items.
In case of Server side Mobile Web, preShow and postShow will not get executed when navigate using the
browser "back". In preShow and postShow of the startup form, Alerts should be avoided. If any alerts are
present in the events of the form, the last alert gets executed and form will never render.
Note: If there are any network calls in postshow, you cannot perform any operation on the form and a busy
indication is displayed until the postshow execution is complete.
Signature
JavaScript: postShow
Lua: postshow
Read / Write
JavaScript Example
//The below function is the callback function for postShow event of the fo
rm.
function postShowCalBck(form)
{
}
//Defining a form with postShow:postShowCalBck,Where postShowCalBck is the

call back.
postShow:postShowCalBck};
var frmPSP ={};
//Creating a form.
4.4.11 onLoadJS
Specifies the name of function to be executed when a form is loaded. The function must exist in the javascript
folder. For more information on defining the onLoadJS event, refer to Kony Studio User Guide.
Signature
JavaScript: onLoadJS
Lua: onloadjs
Read / Write
JavaScript Example
//The below function is the callback function for onLoadJS event of the fo
rm.
function onLoadJSCalBck(form)
{
}
//Defining a form with onLoadJS:onLoadJSCalBck,Where onLoadJSCalBck is the
call back.
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE , title:"Title"};
var frmPSP ={onLoadJS:onLoadJSCalBck};
//Creating a form.
//Reading the the onLoadJS event of the form.

alert("onLoadJS is ::"+frm.onLoadJS);
Accessible from IDE

Yes
Available on Server side Mobile Web (BJS and Advanced) platform
4.4.12 unLoadJS
Specifies the name of function to be executed when a form is unloaded. The function must exist in a javascript
file. For more information on defining the unLoadJS event, refer to Kony Studio User Guide.
Signature
JavaScript: unLoadJS
Lua: unloadjs
Read / Write
JavaScript Example
//The below function is the callback function for unLoadJS event of the fo
rm.
function unLoadJSCalBck(form)
{
}
//Defining a form with unLoadJS:unLoadJSCalBck,Where unLoadJSCalBck is the
call back.
var frmBasic = {id:"frm", type:constants.FORM_TYPE_NATIVE, title:"Title"};
var frmPSP ={unLoadJS:unLoadJSCalBck};
//Creating a form.
//Reading the the unLoadJS event of the form.
alert("unLoadJS is ::"+frm.unLoadJS);
Accessible from IDE

Yes
Available on Server side Mobile Web (Advanced) platform
4.5 Form - Methods

Form Widget has the following methods associated with it:
l
add
addAt
show
destroy
remove
removeAt
replaceAt
widgets
setTitleBarSkin
showTitleBar
hideTitleBar
scrollToWidget
scrollToBeginning
scrollToEnd
4.5.1 add
This method is used to add widgets to the form. When the widgets are added to the current visible form, then
the changes will reflect immediately. Adding a widget to the Form or Box hierarchy, which is already a part of
the other widget hierarchy, will lead to undefined behaviors. You have to explicitly remove the widget from one
hierarchy before adding it to another Form or Box.
Signature
JavaScript: add(widgetArray)
Lua: form.add(formid, widgetArray)
Input Parameters
widgetArray [JSObject]- Mandatory
Comma separated list of widgets.
formid [widgetref] - Mandatory
Return Values
No values are returned.
Exceptions
WidgetError
JavaScript Example
//Procedure to create an OK button.
var basicConfBut = {id : "buttonForOk", text:"OK", isVisible:true,onClick:
gotofrmNext, setEnabled:true, skin: "btnskn", focusSkin: "btnfocusskn"};
var layoutConfBut = {contentAlignment : constants.CONTENT_ALIGN_BOTTOM_RIG
HT, containerWeight:100};
var buttonForOk = new kony.ui.Button(basicConfBut, layoutConfBut, {});
//Procedure to create a Cancel button.
var basicConfBut = {id : "buttonForCancel", text:"Cancel", isVisible:true,
onClick:gotofrmPrevious, setEnabled:true, skin: "btnskn", focusSkin: "btnf
ocusskn"};
var layoutConfBut = {contentAlignment : constants.CONTENT_ALIGN_BOTTOM_LEF
T, containerWeight:100};
var buttonForCancel = new kony.ui.Button(basicConfBut, layoutConfBut, {});
//Method to add an OK and a Cancel button.
frmHome.add(buttonForOk, buttonForCancel);
4.5.2 addAt
This method is used to add widgets to the Form container at the specified index. Widget is prepended if index
<0 and appended at the end of the container if the index > size+1. Size is the number of widgets already
present in the container. If a new widget is added or removed will reflect immediately from the form hierarchy
model perspective, however the changes are displayed when the Form appears. When the widgets are added
to the current visible form, then the changes will reflect immediately. Adding a widget to the Form or Box
hierarchy, which is already a part of the other widget hierarchy, will lead to undefined behaviors. You have to
explicitly remove the widget from one hierarchy before adding it to another Form or Box.
Signature
JavaScript: addAt(widgetref, index, animationConfig)
Lua: form.addAt(formid, widgetref, index)
Input Parameters
widgetref - Mandatory
Reference of the name of the widget.
index [Number] - Mandatory

Index number at which the widget is to be added.
l
constants.ANIMATION_EFFECT_EXPAND:Specifies the widget must

expand gradually by increasing the height of the widget.
constants.ANIMATION_EFFECT_REVEAL: Specifies the widget must

appear gradually by decreasing the transparency of the widget.

layout animations are applied on the Form. The animation events are not
triggered when this option is set.
l




to end.
l


Return Values
Exceptions
WidgetError
JavaScript Example
//Defining animation configuration.
var withAnimConfig=
{
"animEffect":constants.ANIMATION_EFFECT_EXPAND,
"animDuration":1.5,
"animDelay":0.4,
"animCallBacks":{
"animStarted":startCallBackFunc,
}
}
//Method to add an OK button at index 1.
frmHome.addAt(buttonForOk, 1, withAnimConfig);
4.5.3 show
This method is used to display the form.
Signature
JavaScript: show()
Lua: form.show(formid, formname)
Input Parameters
formname - Mandatory
Reference of the name of the Form.
Return Values
None
Exceptions
None
JavaScript Example
//Defining properties of a form.
var basicConf = {id : "formHome", title:"Form Home for FORM",addWidgets:ad
dwidgetsfrmNew, skin:"frmskn"};
var layoutConf = {contentAlignment : constants.CONTENT_ALIGN_TOP_CENTER,
containerWeight:100};
//Creating a form using the properties defined above.
var myForm = new kony.ui.Form(basicConf,layoutConf,pspConf)
//Showing a form using show method.
myForm.show()
4.5.4 destroy
This method is used to destroy any unwanted forms at any point in time, and allows increasing the application
life by reducing the memory usage.
Note: Destroying the current form might lead to unexpected behavior.
Signature
JavaScript: destroy()
Lua: form.destroy(formid, formname)
Input Parameters
formname- Mandatory
Reference of the name of the Form.
Return Values
None
Exceptions
None
JavaScript Example
ontainerWeight:100};

//Destroying a form using destroy method.
myForm.destroy()
4.5.5 remove
This method removes a widget from the form container. If a widget is removed from a form, will reflect
immediately from the Form hierarchy model perspective; however the changes are displayed when the Form
appears. When the widgets are removed from the current visible Form, then the changes will reflect
immediately.
Signature
JavaScript: remove(widgetref)
Lua: form.remove(formid, widgetref)
Input Parameters
Return Values
The current Form handle is returned.
Exceptions
WidgetError
JavaScript Example

//Removing a form using remove method.
myForm.remove(buttonForOk)
4.5.6 removeAt
This method removes a widget at the given index from the Form container. If a widget is removed from the
form, will reflect immediately from the Form hierarchy model perspective; however the changes are displayed
when the Form appears. When the widgets are removed from the current visible Form, then the changes will
reflect immediately.
Note: If the index is not within the limits then removeAt will be silent and doesn't yield any result.
Signature
JavaScript: removeAt(index, animationConfig)
Lua: form.removeat(formid, index)
Input Parameters
Specifies the position in number format.

l
constants.ANIMATION_EFFECT_COLLAPSE:Specifies the widget

must collapse gradually by decreasing the height of the widget. This option
is applicable only when visibility is turned on.
constants.ANIMATION_EFFECT_FADE: Specifies the widget must

disappear gradually by increasing the transparency of the widget.

l




to end.
l

parameters. Following is the signature of the event.

Following is the signature of the event.
Return Values
Reference of the name of the widget to be removed.
Exceptions
WidgetError
JavaScript Example
var withAnimConfig1=
{
"animEffect":constants.ANIMATION_EFFECT_COLLAPSE,
"animDuration":1,
"animDelay":0,
}


//Removing a form using remove method at index 1.
myForm.removeAt(1, withAnimConfig1);
4.5.7 replaceAt
This method replaces a widget with another widget in a form. If a widget is replaced from the form, will reflect
immediately from the Form hierarchy model perspective; however the changes are displayed when the Form
appears.
Note: Post this operation widget that was replaced will get garbage collected unless you hold explicitly a
reference to the replaced widget.
Signature
JavaScript: replaceAt(widgetref, index, animationConfig)
Input Parameters
Specifies the position in number format. Following are the rules applicable for index:
l
If the index < 0, then first widget in the container gets replaced.
If the index > size -1, then the last widget in the container widget gets replaced. The term
size refers to the number of widgets present in the container widget.

constants.ANIMATION_EFFECT_FLIP_RIGHT:Specifies the widget

must flip from right to left.
constants.ANIMATION_EFFECT_FLIP_LEFT: Specifies the widget must

flip from left to right.

Specifies animation should not be applied to the widget, but layout
animations are applied on the Form that may be change the current
widgets layout. The animation events are not triggered when this option is
set.
l




to end.
l

l

Return Values
Exceptions
WidgetError
JavaScript Example
{
"animEffect":constants.ANIMATION_EFFECT_FLIP_RIGHT,
"animDuration":2,
"animDelay":3,
"animCallBacks":{
}
}
//Method to replaceAt.
myForm.replaceAt(buttonForOK,2,withAnimConfig2);
l
iOS
Android
4.5.8 widgets
This method returns an array of the widget references which are direct children of Form.
Signature
JavaScript: widgets()
Lua: form.widgets(formid)
Input Parameters
Return Values
This method returns Read only array of widget references. Modifying the array and changing the position
of widgets in this array doesn't reflect in the Form hierarchy, however you can get handle to the widgets
through this array and modify the widgets through widget level methods as exposed by individual
widgets.
Exceptions
WidgetError
JavaScript Example
var layoutConfBut = {contentAlignment : constants.CONTENT_ALIGN_BOTTOM_
RIGHT, containerWeight:100};
//Method to return myForm widgets.
myForm.widgets();
This method enables you to set the properties for a left-side button of a titlebar.
Signature
JavaScript: setTitleBarLeftSideButtonSkin(text,skin,callBack)
Lua: form.settitlebarleftsidebutton(formid,text,skin,callBack)
Input Parameters
text [String] - Mandatory
Specifies the text of the title bar left side button.
skin [String]- Mandatory
Specifies the skin of the button. It supports fontColor, fontSize, and Image properties.
callBack [event call back]- Mandatory
Specifies the event call back to be invoked on tapping left button.
Return Values
None
Exceptions
None
This method is available on iPhone/iPad.
This method enables you to set the properties for a right-side button of a titlebar.
Signature
JavaScript: setTitleBarRightSideButtonSkin(text,skin,callBack)
Lua: form.settitlebarrightsidebutton(formid,text,skin,callBack)
Input Parameters
Specifies the text of the title bar right side button.
Specifies the skin of the button. It can support fontColor, fontSize, and Image.
callBack [event call back]- Mandatory
Specifies the event call back to be invoked on tapping right button.
Return Values
None
Exceptions
None
This method enables you to set the skin for a titlebar of a form.
Signature
JavaScript: setTitleBarSkin()
Lua: form.settitlebarskin(formid)
Input Parameters
Return Values
None
Exceptions
None
4.5.12 showTitleBar
This method gives you the control to show a titlebar within a form.
Signature
JavaScript: showTitleBar()
Lua: form.showtitlebar(formid)
Input Parameters
Return Values
None
Exceptions
None
4.5.13 hideTitleBar
This method gives you the control to hide a titlebar within a form.
Signature
JavaScript: hideTitleBar()
Lua: form.hidetitlebar(formid)
Input Parameters
Return Values
None
Exceptions
None
This method gives you the control to scroll the form up to the position of selected widget.
Note: In iOS platform, this method brings the widget to viewable area on the form.
Signature
JavaScript: scrollToWidget(widgetref)
Lua: form.scrolltowidget(formid, widgetref)
Input Parameters
Return Values
None
Exceptions
WidgetError
JavaScript Example
//Procedure to create a label for OK button.
var basicConfLbl = {id : "buttonForOk", text:"OK", isVisible:true};
var layoutConfLbl = {contentAlignment : constants.CONTENT_ALIGN_BOTTOM_RIG
var labelForOk = new kony.ui.Label(basicConfLbl, layoutConfLbl, {});
var basicConf = {id : "formHome", title:"My Form"};
var layoutConf = {padding: [20,20,20,20]};
//Creating a form with the properties defined above.
var frmScrollToWidget= new kony.ui.Form(basicConf, layoutConf, {} );
//Method to scroll the form upto label.

frmScrollToWidget.scrollToWidget(labelForOk);
Available on all platforms except Server side Mobile Web.
This method gives you the control to scroll to the beginning of the form.
Signature
JavaScript: scrollToBeginning()
Lua: form.scrolltobeginning(formid)
Input Parameters
Return Values
None
Exceptions
WidgetError
JavaScript Example
//Method to scroll to the beginning of the form.
4.5.16 scrollToEnd
This method gives you the control to scroll to the end of the form.
Signature
JavaScript: scrollToEnd()
Lua: form.scrolltoend(formid)
Input Parameters
Return Values
None
Exceptions
WidgetError
JavaScript Example
//Method to scroll to the end of the form.
4.6 Form - Deprecated Properties and Events

The deprecated properties for Form widget are as follows:
l
dockableAppMenu
dockableHeader
dockableFooter
enableback
Ignore Escape
masterdataload
menuRenderer
undockappheader
undockappfooter
Deprecated Properties
dockableAppMenu
dockableHeader
dockableFooter
enableback
ignoreescape
masterdataload
menuRenderer
undockappheader
undockappfooter
Alternative Property to be
used
By default appmenu should dock
headers
footers
na
na
init
na
init
4.6.1 Dockable Appmenu

Enables you to dock or place the Appmenu at the bottom of the screen. As you scroll the content of the form,
the Appmenu remains docked at the bottom of the screen.
Default: False
Type
String
Read / Write
No
Accessible from IDE

Yes
Available on Mobile Web (advanced).
4.6.2 Dockable Header

Enables you to dock or place the Header at the top of the form. As you scroll the content of the form, the
header stays docked at the top of the screen.
Note: This property is enabled only if you create a header template and specify the template in the Header
field.
Default: False
Type
String
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
J2ME
4.6.3 Dockable Footer

Enables you to dock or place the footer at the bottom of the form. As you scroll the content of the form, the
footer stays docked at the bottom of the screen.
Note: This property is enabled only if you create a footer template and specify the template in the Footer
field. If you specify a Dockable Appmenu, the footer is docked above the Appmenu on the screen.
Default: False
Type
String
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
J2ME
4.6.4 Enable Back

Specifies if the Back button on the device must be enabled or disabled.
Default: the option is selected (The back button is enabled on the device)
If you do not want to enable the back button (for example, in a transaction processing form), clear the
checkbox.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
Available on Windows Phone/Windows Kiosk
4.6.5 Ignore Escape

Specifies if the escape key event on the form must be ignored. This is helpful in scenarios when navigation to
the previous form is not advisable (for example, navigation from Account Summary form to a Login form).
Default: The option is not selected (escape key event is not ignored)
If you select the option, the escape key event is ignored.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
4.6.6 masterdataload
masterdataload is the first function or closure that gets executed in a form life cycle.
Note: This function gets executed only once in a form life cycle and hence any form initializations are
recommended to be placed in the masterdataload.
When this event is raised, the widget tree is created and Load_master_data event is raised.
Available on all platforms.
4.6.7 menu Renderer

Specifies if the application menu code must be included in the code generated for the platform.
Default: true (the checkbox is selected) (The application menu code is included in the code generated for the
platform)
If you do not want to include the application menu code in the code generated for the platform, set the value to
false (clear the checkbox).
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
4.6.8 transactionaldataload()
transactionaldataload is the second function or closure that gets executed in a form life cycle.
Note: This function gets executed only once in a form life cycle. However, the function can be invoked by
using appreset().
Available on all platforms except Mobile Web (basic) and Win Mobile6x.
4.6.9 undockappheader
Enables you to undock or remove the Header from the top of the form.
Default: False
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
J2ME
4.6.10 undockappfooter
Enables you to undock or remove the footer from the bottom of the form.
Default: False
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
J2ME
5. HBox
An (HBox) is used to layout widgets in a single horizontal orientation. It can contain any number of widgets.
However, due to form size limitations, it is advisable not to place many widgets in a HBox.
An HBox provides you with an option to set basic properties, layout properties for all platforms and properties
for specific platforms. You can also call/set Events and Methods on platforms as mentioned in the respective
sections.
For information regarding the behavior exhibited by the HBox, see Box Behavior.
Platform Specific
Properties
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
orientation
position
skin
containerWeight
gridCell
layoutMeta
layoutType
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
percent
vExpand
widgetAlignment
blockedUISkin
borderCollapse
contextMenu
hoverSkin
viewConfig
Events
Methods
Deprecated
onClick
onHover
onRightClick
preOnclickJS
postOnclickJS
add
addAt
remove
removeAt
replaceAt
widgets
Creating an HBox using a constructor: kony.ui.Box

var box1 = new kony.ui.Box(basicConf, layoutConf, pspConf)
l
basicConf is an object with configuration properties.
layoutConf is an object with layout specific configuration properties.
pspConf is an object with platform specific configuration properties.
they are ignored.
JavaScript Example
function boxOnClickEventTest(box)
{
alert("OnClick event is invoked successfully");

}
//Defining the properties for a box with the ID :"boxIdTest"
var basicConfBox = {id : "boxIdTest", isVisible:true, orientation:constant
s.BOX_LAYOUT_HORIZONTAL, onClick:boxOnClickEventTest};
var layoutConfBox = {containerWeight:80, percent:false, layoutAlignment:co
nstants.BOX_LAYOUT_ALIGN_FROM_LEFT, contentAlignment : constants.CONTENT_A
LIGN_TOP_CENTER, padding:[10,10,10,10], margin:[0,5,0,5], vExpand:true};
var pspConfBox = {borderCollapse:true, blockedUISkin:"blockUISkin" };
//creating the box.
boxTest = new kony.ui.Box(basicConfBox, layoutConfBox, pspConfBox);
5.1 HBox - Basic Properties

The basic properties for HBox Widget are as follows:
l
focusSkin
id
info
isVisible
orientation
position
skin
5.1.1 focusSkin
This is a skin property and it determines the look and feel when there is focus on a widget.
For more information on how to create and work with skins, see the Working with Applications section of the
Kony Studio User Guide.
Note: You must be aware of the following:
1. On J2ME, if you do not specify the Focus skin, it is not possible to identify the focus change between the
widgets.
2. Mobile Web does not support this property; instead browser specific focus will be applied.
Syntax
JavaScript: focusSkin
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a box with focusSkin:"boxGrayFocus"
var basicConfBox = {id : "boxFocusSkinTest", isVisible:true, orientation:c
onstants.BOX_LAYOUT_HORIZONTAL, kin:"boxGray", focusSkin:"boxGrayFocus"};
var layoutConfBox = {contentAlignment : constants.CONTENT_ALIGN_TOP_CENTER,
containerWeight:100, vExpand:true};
//Creating the box.
boxFocusSkinTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the focusSkin property of the box.
alert("box focusSkin is ::"+boxFocusSkinTest.focusSkin);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and SPA (Windows Tablet only)
5.1.2 id
id is a unique identifier of a Box consisting of alpha numeric characters. Every Box widget should have a
unique id within a Form.
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Creating the box with the ID :"boxIdTest".
s.BOX_LAYOUT_HORIZONTAL};
//Creating the box.
boxIdTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the id of the box.
alert("box id is ::"+boxIdTest.id);
Accessible from IDE

Yes
5.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Creating the box with the info property.
//Creating the box.
boxIdTest.info = {key:"Boxnumber"};
//Reading the info of the box.
alert("box info is ::"+boxIdTest.info);
Accessible from IDE

No
5.1.4 isVisible
This property controls the visibility of a widget on the form.
Default: true
If set to false, the widget is not displayed.
If set to true, the widget is displayed.
Note: This property is not applicable if the widget is placed in a Segment. When the widget is placed in a
Segment, the default Visibility is set to true. If you want to change the value to false, you can do so by using
the Segment Methods.
Syntax
JavaScript: isVisible
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a box with isVisible:true.
var basicConfBox = {id : "boxisVisibleTest", isVisible:true, orientation:c
onstants.BOX_LAYOUT_HORIZONTAL};
//Creating the box.
boxisVisibleTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Defining the properties for a box with isVisible:false.
basicConfBox = {id : "boxisVisibleTestFalse", isVisible:false, orientation
:constants.BOX_LAYOUT_HORIZONTAL}; layoutConfBox = {contentAlignment : con
stants.CONTENT_ALIGN_TOP_CENTER, containerWeight:100, vExpand:true};
//Creating the box.
boxisVisibleTestFalse = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the isVisible property of the box
alert("Box visibility is ::"+boxisVisibleTestFalse.isVisible);
alert("Second box visibility is ::"+boxisVisibleTest.isVisible);
Note: You can set the visibility of a widget dynamically from code by using the setVisibility method.
Accessible from IDE

Yes (Except for form/popup)
Available on all platforms except Server side Mobile Web (basic) and Win Mobile6x.
5.1.5 orientation
Specifies the orientation of the HBox. The widgets placed in a HBox are aligned horizontally.
Default: BOX_LAYOUT_HORIZONTAL
Note: To set the value through code, prefix the option with constants. such as constants.<option> .
Syntax
JavaScript: orientation
Lua: orientation
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Creating the box with the orientation:constants.BOX_LAYOUT_HORIZONTAL.
//Creating the box.
//Reading the orientation of the box.
alert("box orientation is ::"+boxIdTest.orientation);
Accessible from IDE

No
5.1.6 position
Specifies the position of the box as header or footer of the form. When you set this property the box is docked
along with header or footer.
Note: This property is applicable for immediate child widgets placed on a Form.
Default: BOX_POSITION_AS_NORMAL
l
BOX_POSITION_AS_NORMAL: The original position of the box is retained.
BOX_POSITION_AS_HEADER: The box is fixed at the top of the form.
BOX_POSITION_AS_FOOTER: The box is fixed at the bottom of the form.
BOX_POSITION_AS_SCREENLEVEL_SEG_HEADER: This option is useful to fix the position of the

box to the top of the form when the box is placed inside a SegmentedUI with screenLevelWidget set to
true. This property is treated as normal 1 when a box is not placed in a segment. This option is not
supported on Windows platforms.
l
BOX_POSITION_AS_SCREENLEVEL_SEG_FOOTER: This option is useful to fix the position of the

box to the bottom of the form when a box is placed inside a SegmentedUI with screenLevelWidget set
to true. This property is treated as normal2 when a box is not placed in a segment. This option is not
supported on Windows platforms.
Syntax
JavaScript: position
Lua: position
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a box with position:BOX_POSITION_AS_HEADER
var basicConfBox = {id : "boxPositionTest", isVisible:true, orientation:co
nstants.BOX_LAYOUT_HORIZONTAL, position:constants.BOX_POSITION_AS_HEADER};
//Creating the box.
boxPositionTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Defining the properties for a box with position:BOX_POSITION_AS_FOOTER
basicConfBox = {id : "boxPositionTestFooter", isVisible:true, orientation:
constants.BOX_LAYOUT_HORIZONTAL, position:constants.BOX_POSITION_AS_FOOTE
R};
layoutConfBox = {contentAlignment : constants.CONTENT_ALIGN_TOP_CENTER, co
ntainerWeight:100, vExpand:true};
//Creating the box.
boxPositionTestFooter = new kony.ui.Box(basicConfBox, layoutConfBox, {});
1BOX_POSITION_AS_NORMAL where the original position of the box is
retained.
2BOX_POSITION_AS_NORMAL where the original position of the box is
retained.
Accessible from IDE

Yes
Available on all platforms except SPA and Desktop Web platforms.
5.1.7 skin
Specifies the look and feel of the widget when not in focus.
Note: In BlackBerry platform, HBox background image (in the skin) does not get expanded. Image is
displayed as per the original size. Its a limitation in BlackBerry.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a box with skin:"boxGray"
var basicConfBox = {id : "boxSkinTest", isVisible:true, orientation:consta
nts.BOX_LAYOUT_HORIZONTAL, skin:"boxGray"};
//Creating the box.
boxSkinTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the skin property of the box.
alert("box skin is ::"+boxSkinTest.skin);
Accessible from IDE

Yes
5.2 HBox - Layout Properties

The layout properties for HBox Widget are as follows:
l
containerWeight
gridCell
layoutMeta
layoutType
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
percent
vExpand
widgetAlignment
Specifies percentage of width to be allocated by its parent widget. The parent widget space is distributed to its
child widgets based on this weight factor. All its child widgets should sum up to 100% of weight except when
placed in kony.ui.ScrollBox.
For example, a Form has Label1, Button1, and Button2 and the container weight could be 30 each for Label1
and Button1 and 40 for Button2, so that the sum of the container weight is 100.
Syntax
JavaScript: containerWeight
Lua: containerweight
Type
JavaScript: Number (less than or equal to 100)
Lua: Number (less than or equal to 100)
Read / Write
JavaScript Example
//Defining the properties for a box with containerWeight:50 (box will occu
py half of its parent widget).
var basicConfBox = {id : "boxContainerWeightTest", isVisible:true, orienta
tion:constants.BOX_LAYOUT_HORIZONTAL, skin:"gradroundbox"};
var layoutConfBox = {containerWeight:50,margin:[0,5,0,5]};
//Creating the box.
boxContainerWeightTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

No
5.2.2 gridCell
applied.
are as follows:
l
GridLayout.
Syntax
Lua: gridCell
Type
Lua:table
Read / Write
JavaScript Example
//Defining properties for a box with gridCell.
var basicConfBox = {id : "boxLayoutAlignmentLeftTest", isVisible:true, ori
entation:constants.BOX_LAYOUT_HORIZONTAL,skin:"gradroundbox"};
var layoutConfBox = {containerWeight:100, percent:false, layoutType: const
ants.CONTAINER_LAYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
},gridCell:{"colSpan":1, "rowSpan":1, "rowNo":1, "colNo":1} };
//Creating the box.
boxLayoutAlignmentLeftTest = new kony.ui.Box(basicConfBox, layoutConfBox,
{});
Accessible from IDE

Yes
l
Windows Phone
Desktop Web
5.2.3 layoutMeta
Syntax
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a box with layoutMeta.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
//Creating the box.
{});
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
5.2.4 layoutType
Defines the type of the layout of container widget. Following are the available options:
l
platforms.
Apply GridLayout.
Syntax
Lua: layouttype
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a box with layoutType:CONTAINER_LAYOUT_GRID.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
//Creating the box.
{});
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
This property is applicable if the percent property is set to false. Specifies the direction in which the widgets
are laid out.
Default: BOX_LAYOUT_ALIGN_FROM_LEFT
l
BOX_LAYOUT_ALIGN_FROM_LEFT: The widgets placed inside a box are aligned left.
BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets placed inside a box are aligned center.
BOX_LAYOUT_ALIGN_FROM_RIGHT: The widgets placed inside a box are aligned right.
Syntax
JavaScript: layoutAlignment
Lua: layoutalignment
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a box with layoutAlignment:BOX_LAYOUT_ALIGN_FROM_
LEFT(If percent property is false then this property is considered).
var layoutConfBox = {containerWeight:100, percent:false, layoutAlignment:c
onstants.BOX_LAYOUT_ALIGN_FROM_LEFT};
//Creating the box.
{});
Accessible from IDE

Yes
5.2.6 margin
Defines the space around a widget. You can use this option to define the left, top, right, and bottom distance
between the widget and the next element.
To define the margin values for a platform, click the (
Margin screen. Select the checkbox against the platform for which you want to define the margins and enter
the top, left, right, and bottom margin values.
If you want to use the margin values set for a platform across other platforms, you can click the Apply To
button and select the platforms on which you want the margin values to be applied.
The following image illustrates the window to define the margins for platforms:
The following image illustrates a widget with a defined margin:
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties of a box with margin:[0,5,0,5], Directions :left
,top,right,bottom respectively.
var basicConfBox = {id : "boxMarginTest", isVisible:true, orientation:cons
tants.BOX_LAYOUT_HORIZONTAL};
var layoutConfBox = {containerWeight:100, margin:[0,5,0,5]};
//Creating the box
boxMarginTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web platforms.
5.2.7 marginInPixel
Indicates if the margin is to be applied in pixels or in percentage.
Default: false
If set to true, the margins are applied in pixels.
If set to false, the margins are applied as set in margin property.
Syntax
JavaScript: marginInPixel
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a box with margin in pixels.
tants.BOX_LAYOUT_HORIZONTAL};
var layoutConfBox = {containerWeight:100, margin:[0,5,0,5], marginInPixel
:true};
//Creating the box
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
5.2.8 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties of a box with padding:[10,10,10,10], Directions
:left,top,right,bottom respectively.
var basicConfBox = {id : "boxPaddingTest", isVisible:true, orientation:con
stants.BOX_LAYOUT_HORIZONTAL};
var layoutConfBox = {containerWeight:100, padding:[10,10,10,10]};
//Creating the box.
boxPaddingTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
Limitations
l
iPhone - Not supported for Button unless a skin is specified.
Windows Phone/Windows Kiosk - Not supported for Box, Image Gallery due to Browser limitation.
Mobile Web (BJS) - Not supported for ComboBox, Form, and ListBox due to Browser limitations.
Mobile Web (advanced) - Not supported for ComboBox, Form, and ListBox due to Browser limitations.
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a box with padding in pixels.
var layoutConfBox = {containerWeight:100, padding:[10,10,10,10], paddingI
nPixel:true};
//Creating the box.
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone (Mango)
5.2.10 percent
Specifies if the child widgets weight factor must be considered during layout. When the widgets do not have
enough space to accommodate inside non-percentage HBox, then the behavior of these widgets inside an
HBox is undefined.
Note: In kony.application.setApplicationBehaviors API the parameter retainSpaceOnHide is only applicable
when percent property is set to True for HBox.
Note: On Server side Mobile Web, SPA, and Desktop Web platforms, when you place multiple VBoxes
inside a non percentage HBox, VBoxes are adjusted automatically.
Note: On BlackBerry 10 platform, when percent property set to false, text on the widgets may fade or width
of the widgets may expand or reduce.
Default: true
If set to false, the layoutAlignment is considered.
If set to true, the containerWeight is considered.
Syntax
JavaScript: percent
Lua: percent
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a box with Percent:false(child widgets weight
factor (containerWeight property) is not considered).
var basicConfBox = {id:"boxPercentTest", isVisible:true, orientation:const
ants.BOX_LAYOUT_HORIZONTAL};
var layoutConfBox = {containerWeight:100, percent:false, margin:[0,5,0,5]};
//Creating the box
boxPercentTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Defining the properties of a box with Percent:true(child widgets weight
factor (containerweight property) is to be considered).
basicConfBox = {id : "boxPercentTestTrue", isVisible:true, orientation:con
layoutConfBox = {ontainerWeight:100, percent:true, margin:[0,5,0,5]};
//Creating the box.
boxPercentTestTrue = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
5.2.11 vExpand
Specifies the widget expansion in the vertical direction.
Default: false
If set to true, the widget occupies the entire available height.
If set to false, the widget occupies the preferred height.
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a box with vExpand:true.
var basicConfBox = {id : "boxvExpandTrueTest", isVisible:true, orientation
:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
var layoutConfBox = {containerWeight:99, vExpand:true};
//Creating the box.
boxvExpandTrueTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Defining the properties of a box with vExpand:false.
var basicConfBox = {id : "boxvExpandTrueTest", isVisible:true, orientation
var layoutConfBox = {containerWeight:99, vExpand:false};
//Creating the box.
boxvExpandFalseTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
Available on all platforms except Desktop Web and Server side Mobile Web platforms.
Indicates how a widget is to be anchored with respect to its parent. Each of these below options have a
horizontal alignment attribute and a vertical alignment attribute. For example, WIDGET_ALIGN_TOP_LEFT
specifies the vertical alignment as TOP and horizontal alignment as LEFT.
Default: WIDGET_ALIGN_CENTER
l
WIDGET_ALIGN_TOP_LEFT - (BlackBerry 10 supports this option)
WIDGET_ALIGN_TOP_CENTER
WIDGET_ALIGN_TOP_RIGHT
WIDGET_ALIGN_MIDDLE_LEFT
WIDGET_ALIGN_CENTER - (BlackBerry 10 supports this option)
WIDGET_ALIGN_MIDDLE_RIGHT
WIDGET_ALIGN_BOTTOM_LEFT
WIDGET_ALIGN_BOTTOM_CENTER
WIDGET_ALIGN_BOTTOM_RIGHT - (BlackBerry 10 supports this option)
Syntax
JavaScript: widgetAlignment
Type
JavaScript: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties of a box with widgetAlignment:constants.WIDGET_A
LIGN_TOP_LEFT.
var basicConfBox = {id : "boxwidgetAlignment", isVisible:true, orientation
var layoutConfBox = {containerWeight:99, hExpand:true, widgetAlignment:con
stants.WIDGET_ALIGN_TOP_LEFT};
//Creating the box.
boxwidgetAlignment = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
l
Server side Mobile Web
SPA
Desktop Web
5.3 HBox - Platform Specific Properties

The platform specific properties for HBox Widget are as follows:
l
blockedUISkin
borderCollapse
contextMenu
hoverSkin
viewConfig
5.3.1 blockedUISkin
Specifies the skin that must be used to block the interface until the action in progress (for example, a service
call) is completed.
Default: None (No skin is applied)
To specify a skin, select a skin from the list.
Note: For the skin to be available in the list, you must add a skin for Blocked UI under Widget Skins.
Syntax
JavaScript: blockedUISkin
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Call back for box onClick event
function boxblockedUISkinTCSPAPlayClick(box)
{
//Call the service here to observe blockedUI skin
}
//The below two functions will explain how to use blockedUISkin property f
or Box widget.
var basicConf = {id : "lblblockedUISkin", text:"Click this Box to see bloc
kedUI skin while calling the service", isVisible:true};
var layoutConf = {contentAlignment :constants.CONTENT_ALIGN_CENTER,
containerWeight:100, widgetAlignment:constants.WIDGET_ALIGN_CENTER,hExpand:
true,vExpand:true};
//Creating the Label.
var lblblockedUISkin = new kony.ui.Label(basicConf, layoutConf, {});
//onClick event is triggered when user clicks on the box ,In this case we
are calling the service inside the callback to observe the blockedUI skin.
var basicConfBox = {id : "boxblockedUISkin", isVisible:true, orientation:c
onstants.BOX_LAYOUT_HORIZONTAL,onClick:boxblockedUISkinTCSPAPlayClick};
//Creating the Box
var boxblockedUISkin = new kony.ui.Box(basicConfBox, layoutConfBox, {block
edUISkin:"blockUISkin"});
//Adding label to box.
boxblockedUISkin.add(lblblockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
Specifies if the space between the Box and its child widgets is considered.
Default: false
If set to true, the default space between the parent and the child widget reduces.
If set to false, the default space between the parent and the child widget retained.
Syntax
JavaScript: borderCollapse
Lua: bordercollapse
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the box with borderCollapse:true .(If you set the Border-Collap
se value to true, the default space between the parent and the child widget
reduces else not.)
var basicConfBox = {id : "boxBorderCollapse", isVisible:true, orientation:
constants.BOX_LAYOUT_HORIZONTAL};
var PSPConfBox = {borderCollapse:true}
//Creating the box.
var boxBorderCollapse = new kony.ui.Box(basicConfBox, layoutConfBox, PSPCo
nfBox );
Accessible from IDE

Yes
l
5.3.3 contextMenu
Shows the list of actions (appropriate to the widget in focus) as menu items.
Note: Due to BlackBerry platform limitation, to display a context menu for an Box, you must define an
onclick event for the Box.
The following are the characteristics of a context menu on BlackBerry platform:
l
You can invoke the context menu either by clicking on the widget (applicable only on BlackBerry
versions 6.x and above) or by a long press on the screen (or trackpad).
You can choose to add icons to indicate the menu items in the context menu (applicable only on
BlackBerry versions 6.x and above).
BlackBerry layouts menu items in a 3 item grid view. The menu items Switch Application, Help, Close,
and Full Menu are added automatically based on the number of menu items added in the context menu.
For example, If you add a context menu with 2 items, it will display Full Menu item along with the items
added. If you add a context menu with 3 items, it will display Full Menu, Help, Switch Application items
along with the items added.
If the focus is on a widget that has a context menu; and if you click the "menu key", the Full Menu
appears along with the context menu items.
On Blackberry Non-Touch Devices, only Full Menu item is displayed irrespective of number of items
added in the context menu.
Note: The context menu items in the Full Menu will disappear if the focus is shifted from the widget which
has the context menu.
The following images illustrate the context menu on various BlackBerry devices:
BlackBerry 6.x
BlackBerry Touch Device

(<6.x)
BlackBerry Non-Touch
Device (<6.x)
The below description and procedure is applicable to Desktop Web platform only.
The context specific menu will be displayed with the array of menu items (appropriate to the widget in focus)
on right-click mouse.
Default:None
A series of steps to be followed to use contextMenu:
1. Define a menutemplate under project > templates >menus.
a. Go to Applications View.
b. Expand the application for which you want to create a menu template.
c. Navigate to templates and expand menus, right-click desktop and select New Menu Template.
The Create a New Menu window appears.
d. Enter a Name for the template and click Finish.
e. A new form is created. Drag-drop an HBox and then a VBox within an HBox. You can add other
widgets within these widgets.
2. Define a contextmenu template under project > templates >contexmenus.

b. Expand the application for which you want to create a contextmenu template.
c. Navigate to templates and expand contextmenus, right-click desktop and select New
ContextMenu Template. The Create a New ContextMenu window appears.
d. Enter a Name for the template and click Finish. A new form is created
e. Drag-drop a menucontainer. You can drag-drop a menucontainer widget only.
f. (optional) Select menuItemTemplate from the drop down.
g. Define data using the data property.
3. Go to your project and then to desired form and drag-drop a hbox and navigate to Desktop Web
properties in Widget Properties window.
4. Select the contextmenu template from the dropdown.
Syntax
JavaScript: contextMenu
Lua: contextmenu
Type
JavaScript: Array (kony.ui.Menuitem)
Lua: Table
Read / Write
JavaScript Example
//Defining contextMenu items for Windows platform.
var appMenu1 = {id:"appmenuitemid1", text:"Add", image:"tc.png", onclick:c
allbackMenuItem1 };
var appMenu2 = {id:"appmenuitemid2", text:"Remove", image:"tc.png", onclic
k:callbackMenuItem2 };
var appMenu3 = {id:"appmenuitemid3", text:"Edit", image:"tc.png", onclick:
callbackMenuItem3};
var appMenu4 = {id:"appmenuitemid4", text:"Close", image:"tc.png", onclick:
callbackMenuItem4};
function callbackMenuItem1()
{
alert("Clicked on First menu item");
}
{
alert("Clicked on Second menu item");
}
{
alert("Clicked on Third menu item");
}
{
alert("Clicked on Fourth menu item");
}
//Defining the box with contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]
var PSPConfBox = {contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]};
//Creating the box.
nfBox );
The below example is applicable to Desktop Web platform only.

//Defining contextMenu template.
function initializeaddtoabc() {
menucontainer12068 = new kony.ui.MenuContainer({
"id": "menucontainer12068", "isVisible": true,
"data": [
{template: hbox12068, "label12068": {"text": "India"},
children: [{template: hbox12068, "label12068": {"text": "Mu
mbai"},
"image212068": {}, children: [] }]
}, {template: hbox12068, "label12068": {"text": "Srilanka" },
"image212068": {}
}],
"widgetDataMap": {"label12068": "label12068","image212068": "image
212068"},
"menuItemTemplate": hbox12068}, {"widgetAlignment": constants.WIDG
ET_ALIGN_CENTER,
"containerWeight": "50", "margin": [0, 0, 0, 0],
"padding": [0, 0, 0, 0], "marginInPixel": false,
"paddingInPixel": false
}, {
"viewType": constants.MENU_CONTAINER_VIEW_TYPE_CONTEXTVIEW
});
};
//Defining the box with contextMenu:menucontainer12068
var PSPConfBox = {contextMenu:menucontainer12068};
//Creating the box.
nfBox );
Accessible from IDE

No. But for Desktop Web platform you can access it through IDE.
l
BlackBerry
Windows Phone
Desktop Web
5.3.4 hoverSkin
Specifies the look and feel of a widget when the cursor hovers on the widget.
Syntax
JavaScript: hoverSkin
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the box with hoverSkin:"hskin"
var PSPConfBox = {hoverSkin:"hskin"}
//Creating the box.
nfBox );
Accessible from IDE

Yes
Availability on platforms
l
Windows Tablet
Desktop Web
5.3.5 viewConfig
l
Normal view
Grid view
grid view.
Syntax
Lua: viewconfig
Type
JavaScript:JSObject
Lua: table
Read / Write
No
JavaScript Example
//Defining the properties for a Box with the fixedHeightRow:true.
var PSPConfBox = {viewConfig: {
referenceHeight: 0,
sizeMode: "constants.GRID_TYPE_FIXED",
referenceWidth: 0
}
};
//Creating the box.
boxIdTest = new kony.ui.Box(basicConfBox, layoutConfBox, PSPConfBox );
Accessible from IDE

Yes
This property is available on Windows Phone platform.
5.4 HBox - Events

HBox Widget has the following event associated with it:
l
onClick
onHover
onRightClick
preOnclickJS
postOnclickJS
Note: In Server side Mobile Web, for the events preOnclickJS and postOnclickJS you will not be able to
access application model or APIs, as these functions are executed in browser whereas the remaining JS
modules are executed in server. For these events you can access browser objects (window, document
etc..) to change UI or perform some validation before server event. If the event preOnclickJS returns true,
only then the request is sent to server for subsequent action.
You have to specify the modules to be loaded in browser using import JS tab, only then these files get
included in html script tag otherwise you will not be able to access the objects defined in those modules.
5.4.1 onClick
An event callback is invoked by the platform when the user performs a click action on the widget.
Note: If both onClick and a single tab gesture has been defined for a box then the behavior is undefined.
Syntax
JavaScript: onClick
Lua: onclick
The onClick event callback accepts additional parameters when a HBox is placed in a segment row or section
template.
Signature
JavaScript: onClick (context)
The argument context has the following parameters.
Input Parameters
rowIndex [Number] - Optional
Index of the row that contains the HBox. It is not available if the HBox is placed in a section header.
sectionIndex [Number] - Mandatory
Index of the section row that contains the HBox.
widgetInfo [widgetref] - Mandatory
Handle to the parent widget instance(segment) that contains the HBox.
Read / Write
JavaScript Example
//The below function is callBack for onClick event
{
}
//Defining the properties for a Box
var basicConfBox = {id : "boxOnClickTest", isVisible:true, orientation:con
stants.BOX_LAYOUT_HORIZONTAL, onClick:boxOnClickEventTest};
//Creating the Box.
var boxOnClickTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
5.4.2 onHover
An event callback is invoked by the platform based on the below actions:
l
When the mouse enters into the widget region.
When the mouse moves with in the widget region.
When the mouse leaves from the widget region.
Note: When the event callback is invoked, corresponding widget state is not updated as
selected/unselected.
Important Considerations
Below are the points to be considered while using onHover event.
l
To remove onHover event on a widget, set it to null.

widget.onHover = null;
Data / computing intense operations should not be performed in onHover callback.
Avoid network calls in onHover event as it affects the performance.
Use this event to update the skin.
When an onHover event is defined to both parent and child widgets, the onHover event executes as
follows:
When mouse moves into parent widget, then MOUSE_ENTER event gets fired on the parent
widget.
When mouse moves inside the parent widget, then MOUSE_MOVE event is fired continuously
till mouse moves inside the parent widget.
When mouse moves into the child widget area, then MOUSE_ENTER event gets fired on the
child widget.
When mouse moves inside the child widget area, then MOUSE_MOVE event is fired on child
widget and also on the parent widget.
When mouse moves out of the child widget area, then MOUSE_LEAVE event gets fired on
child widget and MOUSE_MOVE event gets fired on the parent widget.
When mouse moves out of the parent widget, then MOUSE_LEAVE event gets fired on the
parent widget.
Signature
JavaScript: onHover (widget, context)
Input Parameters
Handle to the widget instance that raised the event.
context [Object] - Mandatory
Specifies the JSObject with the following key values.
eventType [Constant] - Mandatory
constants.ONHOVER_MOUSE_ENTER - When the mouse enters
into the widget region.
constants.ONHOVER_MOUSE_MOVE - When the mouse move
within the widget region.
constants.ONHOVER_MOUSE_LEAVE - When the mouse leaves
from the widget region.
sectionIndex [Number] - Optional
Specifies the index of the section where the current focused row belongs. It is
applicable only if parent is SegmentedUI.
Specifies the index of the current focused row relative to its section. It is
applicable only if parent is SegmentedUI or DataGrid.
columnIndex [Number] - Optional
Specifies the index of the cell in DataGrid where the mouse exists. It is applicable
only if parent is DataGrid.
selectionState [Boolean] - Optional
Specifies the selection state when the widget is placed inside a segmentedUI and
its selectionBehavior property is set as SEGUI_MULTI_BEHAVIOR or SEGUI_
SINGLE_SELECT_BEHAVIOR to indicate the current focused rows checked or
unchecked state.
index [Number] - Optional
Specifies the index of the current focused image in ImageGallery or
HorizontalImageStrip widgets. It is applicable only for ImageGallery or
HorizontalImageStrip widgets.
key [String] - Optional
Specifies the key of the element in a CheckBoxGroup or RadioButton widgets.
pageX [Number] - Mandatory
Specifies the horizontal coordinate of the onHover event relative to the whole
document.
pageY [Number] - Mandatory
Specifies the vertical coordinate of the onHover event relative to the whole
document.
screenX [Number] - Mandatory
Specifies the horizontal coordinate of the onHover event relative to the screen
width.
screenY [Number] - Mandatory
Specifies the vertical coordinate of the onHover event relative to the screen
height.
JavaScript Example
//Sample code to use onHover event
function onHoverEventCallback(widget,context)
{
console.log("button hover event executed" + context.eventType);
if (context.eventType == constants.ONHOVER_MOUSE_ENTER)
{
widget.skin = "yellow";
}
else if (context.eventType == constants.ONHOVER_MOUSE_MOVE)
{
}
else if (context.eventType == constants.ONHOVER_MOUSE_LEAVE)
{
widget.skin = "blue";
}
}
function addHoverEvent()
{
console.log("registering hover events");
form1.button1.onHover = onHoverEventCallback;
}
function removeHoverEvent()
{
console.log("removing hover events");
form1.button1.onHover = null;
}
Available on Desktop Web platform only
5.4.3 onRightClick
An event callback is invoked by the platform when the user performs a right click action on the widget.
Note: This event is enabled only when you select a template for contextMenu property.
Syntax
JavaScript: onRightClick
Read / Write
JavaScript Example
//The below function is callBack for onRightClick event
function boxOnRightClickEventTest(box)
{
alert("OnRightClick event is invoked successfully");
}
var basicConfBox = {id : "boxOnRightClickTest", isVisible:true, orientatio
n:constants.BOX_LAYOUT_HORIZONTAL, onRightClick:boxOnRightClickEventTest};
//Creating the Box.
5.4.4 preOnclickJS
This event allows the developer to execute custom javascript function before the onClick callback of the box
is invoked. This is applicable only for Mobile Web channel. The function must exist in a javascript file under
project>module>js folder.
Syntax
JavaScript: preOnclickJS
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is callBack for preOnClickJS event
function preOnClickJSCallBack(box)
{
alert("PreOnclickJs called successfully");
}
//The below two functions will test the preOnclickJS event.
var basicConf = {id : "lblPreEventSkinTC", text:"Click here to test PreOnC
lick JS so that JS function will get called", isVisible:true};
var layoutConf = {contentAlignment :constants.CONTENT_ALIGN_CENTER, contai
nerWeight:100, widgetAlignment:constants.WIDGET_ALIGN_CENTER,
vExpand:true};
//Creating the Label
var lblPreEventSkinTC = new kony.ui.Label(basicConf, layoutConf, {});
//Defining the properties for a Box.
var basicConfBox = {id : "boxPreEventSkinTC", isVisible:true, orientation:
//Creating the box.
var boxPreEventSkinTC = new kony.ui.Box(basicConfBox, layoutConfBox, {preO
nclickJS:preOnClickJSCallBack});
boxPreEventSkinTC.add(lblPreEventSkinTC);
Available on Server side Mobile Web (BJS and Advanced) platform only
5.4.5 postOnclickJS
This event allows the developer to execute custom javascript function after the onClick callback of the widget
Syntax
JavaScript: postOnclickJS
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is callBack for postOnclickJS event
function PostOnclickJSCallBack(box)
{
}
//The below two functions will test the postOnclickJS event.
var basicConf = {id : "lblPostEventSkinTC", text:"Click here to test postO
nclick JS so that JS function will get called", isVisible:true};
containerWeight:100, widgetAlignment:constants.WIDGET_ALIGN_CENTER, vExpan

d:true};
var lblPostEventSkinTC = new kony.ui.Label(basicConf, layoutConf, {});
var basicConfBox = {id : "boxPostEventSkinTC", isVisible:true, orientation
:constants.BOX_LAYOUT_HORIZONTAL};
//Creating the Box.
var boxPostEventSkinTC = new kony.ui.Box(basicConfBox, layoutConfBox, {pos
tOnclickJS:PostOnclickJSCallBack});
boxPostEventSkinTC.add(lblPostEventSkinTC);
Available on Server side Mobile Web (Advanced) platform only
5.5 HBox - Methods

HBox Widget has the following methods associated with it:
l
add
addAt
remove
removeAt
replaceAt
widgets
5.5.1 add
This method is used to add widgets to the box container. When the widgets are added to the current visible
form, then the changes will reflect immediately. Adding a widget to the Box hierarchy, which is already a part
of the other widget hierarchy, will lead to undefined behaviors. You have to explicitly remove the widget from
one hierarchy before adding it to another Box.
Signature
JavaScript: add ()
Lua:box.add (boxid )
Input Parameters
boxid [widgetref] - Mandatory
Return Values
None
Exceptions
WidgetError
JavaScript Example
//Defining the properties for a Box properties.
var basicConfBox = {id : "boxAddMethodTest", isVisible:true, orientation:c
onstants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
var layoutConfBox = {containerWeight:100};
//Creating the Box.
var boxAddMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Adding label ,button widgets to the box Here label and button widgets sh
ould be created already and accessible as well.
boxAddMethodTest.add(lbl,btn);
5.5.2 addAt
This method is used to add widgets to the Box container at the specified index. Widget is prepended if index
present in the container. If a new widget is added or removed will reflect immediately from the Box hierarchy
Signature
JavaScript: addAt (widgetref, index, animationConfig)
Lua:box.addat (boxid, widgetref, index)
Input Parameters
Reference of the widget to be added
l



Specifies animation should not be applied to the widget, but layout
animations are applied on the Form that may be change the current
widgets layout. The animation events are not triggered when this option is
set.




to end.
l


Return Values
None
Exceptions
WidgetError
JavaScript Example
var withAnimConfig=
{
"animDuration":1.5,
"animDelay":0.4,
"animCallBacks":{
}
}
var basicConfBox = {id : "boxAddAtMethodTest", isVisible:true, orientation
//Creating the Box.
var boxAddAtMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Adding label to the box at 15th index Position.Here label should be crea
ted already and accessible as well.
boxAddAtMethodTest.addAt(lbl,15, withAnimConfig);
5.5.3 remove
This method removes a widget from the Box container. If a new widget is removed will reflect immediately
from the Box hierarchy model perspective, however the changes are displayed when the Box appears. When
the widgets are added to the current visible Box, then the changes will reflect immediately.
Signature
JavaScript: remove (widgetref)
Lua:box.remove (boxid, widgetref)
Input Parameters
Reference of the widget to be removed.
Return Values
Exceptions
WidgetError
JavaScript Example
var basicConfBox = {id : "boxRemoveMethodTest", isVisible:true, orientatio
n:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
//Creating the Box.
var boxRemoveMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Removing label widget from the box .Here label should be created already
and added inside the box.
boxRemoveMethodTest.remove(lbl);
5.5.4 removeAt
This method removes a widget at the given index from the Box container. If a new widget is removed will
reflect immediately from the Box hierarchy model perspective, however the changes are displayed when the
Box appears. When the widgets are added to the current visible Box, then the changes will reflect
immediately.
Signature
JavaScript: removeAt (index, animationConfig)
Lua:box.removeat (boxid, index)
Input Parameters
Index number at which the widget is to be removed.

l

must collapse gradually by decreasing the height of the widget.


l




to end.
l


Return Values
Exceptions
WidgetError
JavaScript Example
{
"animDuration":1,
"animDelay":0,
}

var basicConfBox = {id : "boxRemoveAtMethodTest", isVisible:true, orientat
ion:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
//Creating the Box.

var boxRemoveAtMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {
});
//Removing label from the box at 15th index Position. Here label should be
created and added at 15th index position of the box.
boxRemoveAtMethodTest.removeAt(15, withAnimConfig1);
5.5.5 replaceAt
This method replaces a widget with another widget in the HBox. If a widget is replaced from the HBox, will
reflect immediately from the HBox hierarchy model perspective; however the changes are displayed when the
HBox appears.
Signature
Input Parameters
l
animationConfig[JSObject] - Optional



l




to end.
l

l

Return Values
Exceptions
WidgetError
JavaScript Example
{
"animDuration":2,
"animDelay":3,
"animCallBacks":{
}
}
//Creating the Box.
});
//Replacing label from the box at 15th index Position. Here label should be
boxRemoveAtMethodTest.removeAt(lbl,15,withAnimConfig2);
l
iOS
Android
5.5.6 widgets
This method returns an array of the widget references which are direct children of Box.
Signature
JavaScript: widgets ()
Lua:box.widgets ()
Input Parameters
None
Return Values
of widgets in this array doesn't reflect in the Box hierarchy, however you can get handle to the widgets
widgets.
Exceptions
WidgetError
JavaScript Example
var wigArr = new Array();
var basicConfBox = {id : "boxWidgetsMethodTest", isVisible:true, orientati
on:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
//Creating the Box.
var boxWidgetsMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {}
);
//Collecting all the widgets of the box into array and displaying the refe
rences.
wigArr = boxWidgetsMethodTest.widgets();
alert("Widgets are::"+wigArr);

Note: Context Menu templates are supported only on Desktop Web platform.

In Desktop Web, when you right click a Menu Container or a Box the context specific menu will be displayed
with the array of menu items. A Context Menu Template is essentially a template having a Menu Container in
which the developer customizes the overall look and feel of the context menu.

Context Menu Templates are used to display how the data is presented to the end user when a context menu
pops up.

When you want the same template to be displayed across all the Context Menus in the application, you have
a provision to add a Context Menu Template using Kony Studio.
To create a context menu template at the application-level, follow these steps:
1. Go to Applications View.
2. Expand the application for which you want to create the Context Menu Template.
3. Navigate to templates > contextmenus, right-click desktop and select New ContextMenu Template.
The Create a New Menu dialog appears.
i. Enter a Name for the template.
ii. Click Finish. A new form is created.
iii. Drag and drop a Menu container in the form.
iv. Set the required properties and click Save. A Context Menu template is created.

You can create separate templates for each context menu using the above process. In Desktop Web, when
you right click a Menu Container or a Box the context specific menu will be displayed with the array of menu
items.
To use Context Menu Template in an application, follow these steps:
2. Expand the application for which you want to use Context Menu.
3. Navigate to forms > desktop, right-click desktop and select New Form. The Create a New Form
window appears.
4. Enter a name for the Form and click Finish. A new form is created.
5. Drag-drop a Box or a Menu container on the form and set data using the contextMenu property under
Desktop Web.
6. VBox
A (VBox) is used to layout widgets in a single vertical orientation. It can contain any number of widgets.
However, due to form size limitations, it is advisable not to place many widgets in a VBox.
A VBox provides you with an option to set basic properties, layout properties for all platforms and properties
for specific platforms. You can also call/set Events and Methods on platforms as mentioned in the respective
sections.
For information regarding the behavior exhibited by the VBox, see VBox Behavior.
Platform Specific
Properties
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
orientation
skin
containerWeight
gridCell
layoutMeta
layoutType
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
blockedUISkin
borderCollapse
contextMenu
hoverSkin
viewConfig
Events
Methods
Deprecated
onClick
onHover
onRightClick
preOnclickJS
postOnclickJS
add
addAt
remove
removeAt
replaceAt
widgets
Creating a VBox using a constructor: kony.ui.Box

var box1 = new kony.ui.Box(basicConf, layoutConf, pspConf)
l
basicConf is an object with configuration properties.
layoutConf is an object with layout specific configuration properties.
pspConf is an object with platform specific configuration properties.
they are ignored.
JavaScript Example
{
}
//Defining the properties for a box with the ID :"boxIdTest"

s.BOX_LAYOUT_VERTICAL, onClick:boxOnClickEventTest};
var layoutConfBox = {containerWeight:80, percent:false, layoutAlignment:co
nstants.BOX_LAYOUT_ALIGN_FROM_LEFT, contentAlignment : constants.CONTENT_A
LIGN_TOP_CENTER, padding:[10,10,10,10], margin:[0,5,0,5]};
var pspConfBox = {borderCollapse:true, blockedUISkin:"blockUISkin" };
//Creating the box.
boxTest = new kony.ui.Box(basicConfBox, layoutConfBox, pspConfBox);
6.1 VBox - Basic Properties

The basic properties for VBox Widget are as follows:
l
focusSkin
id
info
isVisible
orientation
skin
6.1.1 focusSkin
1. On J2ME, if you do not specify the Focus skin, it is not possible to identify the focus change between the
widgets.
2. Mobile Web does not support this property; instead browser specific focus will be applied.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a box with focusSkin:"boxGrayFocus"
var basicConfBox = {id : "boxFocusSkinTest", isVisible:true, orientation:c
onstants.BOX_LAYOUT_VERTICAL, kin:"boxGray", focusSkin:"boxGrayFocus"};
//Creating the box.
boxFocusSkinTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the focusSkin property of the box.
alert("box focusSkin is ::"+boxFocusSkinTest.focusSkin);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and SPA (Windows Tablet only)
6.1.2 id
id is a unique identifier of a Box consisting of alpha numeric characters. Every Box widget should have a
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Creating the box with the ID :"boxIdTest".
s.BOX_LAYOUT_VERTICAL};
//Creating the box.
//Reading the id of the box.
alert("box id is ::"+boxIdTest.id);
Accessible from IDE

Yes
6.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Creating the box with the info property.
//Creating the box.
boxIdTest.info = {key:"Boxnumber"};
//Reading the info of the box.
alert("box info is ::"+boxIdTest.info);
Accessible from IDE

No
6.1.4 isVisible
Default: true
Segment, the default Visibility is set to true. If you want to change the value to false, you can do so by using
the Segment Methods.
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a box with isVisible:true.
var basicConfBox = {id : "boxisVisibleTest", isVisible:true, orientation:c
onstants.BOX_LAYOUT_VERTICAL};
//Creating the box.
boxisVisibleTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Defining the properties for a box with isVisible:false.
basicConfBox = {id : "boxisVisibleTestFalse", isVisible:false, orientation
:constants.BOX_LAYOUT_HORIZONTAL}; layoutConfBox = {contentAlignment : con
stants.CONTENT_ALIGN_TOP_CENTER, containerWeight:100};
//Creating the box.
boxisVisibleTestFalse = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the isVisible property of the box
alert("Box visibility is ::"+boxisVisibleTestFalse.isVisible);
alert("Second box visibility is ::"+boxisVisibleTest.isVisible);
Accessible from IDE

Available on all platforms except Server side Mobile Web (basic) platform.
6.1.5 orientation
Specifies the orientation of the VBox. The widgets placed in a VBox are aligned vertically.
Default: BOX_LAYOUT_VERTICAL
Syntax
Lua: orientation
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Creating the box with the orientation:constants.BOX_LAYOUT_VERTICAL.
//Creating the box.
//Reading the orientation of the box.
alert("box orientation is ::"+boxIdTest.orientation);
Accessible from IDE

No
6.1.6 skin
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a box with skin:"boxGray"
var basicConfBox = {id : "boxSkinTest", isVisible:true, orientation:consta
nts.BOX_LAYOUT_VERTICAL, skin:"boxGray"};
//Creating the box.
boxSkinTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Reading the skin property of the box.
alert("box skin is ::"+boxSkinTest.skin);
Accessible from IDE

Yes
6.2 VBox - Layout Properties

The layout properties for VBox Widget are as follows:
l
containerWeight
gridCell
layoutMeta
layoutType
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
For example, a Form has Label1, Button1, and Button2 and the container weight could be 30 each for Label1
and Button1 and 40 for Button2, so that the sum of the container weight is 100.
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a box with containerWeight:50 (box will occu
py half of its parent widget).
var basicConfBox = {id : "boxContainerWeightTest", isVisible:true, orienta
tion:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
var layoutConfBox = {containerWeight:50,margin:[0,5,0,5]};
//Creating the box.
boxContainerWeightTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

No
6.2.2 gridCell
applied.
are as follows:
l
GridLayout.
Syntax
Lua: gridCell
Type
Lua:table
Read / Write
JavaScript Example
//Defining properties for a box with gridCell.
entation:constants.BOX_LAYOUT_VERTICAL,skin:"gradroundbox"};
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
//Creating the box.
{});
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
6.2.3 layoutMeta
Syntax
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a box with layoutMeta.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
//Creating the box.
{});
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
6.2.4 layoutType
l
platforms.
Apply GridLayout.
Syntax
Lua: layouttype
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a box with layoutType:CONTAINER_LAYOUT_GRID.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
//Creating the box.
{});
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
This property is applicable if the percent property is set to false. Specifies the direction in which the widgets
are laid out.
l
BOX_LAYOUT_ALIGN_FROM_LEFT: The widgets placed inside a box are aligned left.
BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets placed inside a box are aligned center.
BOX_LAYOUT_ALIGN_FROM_RIGHT: The widgets placed inside a box are aligned right.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a box with layoutAlignment:BOX_LAYOUT_ALIGN_FROM_
LEFT(If percent property is false then this property is considered).
var layoutConfBox = {containerWeight:100, percent:false, layoutAlignment:c
onstants.BOX_LAYOUT_ALIGN_FROM_LEFT};
//Creating the box.
{});
Accessible from IDE

Yes
6.2.6 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties of a box with margin:[0,5,0,5], Directions :left
,top,right,bottom respectively.
tants.BOX_LAYOUT_VERTICAL};
var layoutConfBox = {containerWeight:100, margin:[0,5,0,5]};
//Creating the box
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic)
6.2.7 marginInPixel
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a box with margin in pixels.
tants.BOX_LAYOUT_VERTICAL};
var layoutConfBox = {containerWeight:100, margin:[0,5,0,5], marginInPixel
:true};
//Creating the box
Accessible from IDE

Yes
l
iPhone
iPad
6.2.8 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties of a box with padding:[10,10,10,10], Directions
:left,top,right,bottom respectively.
stants.BOX_LAYOUT_VERTICAL};
var layoutConfBox = {containerWeight:100, padding:[10,10,10,10]};
//Creating the box.
Accessible from IDE

Yes
Limitations
l
iPhone - Not supported for Button unless a skin is specified.
Windows Phone/Windows Kiosk - Not supported for Box, Image Gallery due to Browser limitation.
Mobile Web (BJS) - Not supported for ComboBox, Form, and ListBox due to Browser limitations.
Mobile Web (advanced) - Not supported for ComboBox, Form, and ListBox due to Browser limitations.
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a box with padding in pixels.
stants.BOX_LAYOUT_VERTICAL};
var layoutConfBox = {containerWeight:100, padding:[10,10,10,10], paddingI
nPixel:true};
//Creating the box.

Accessible from IDE

Yes
l
iPhone
iPad
l
Syntax
Type
JavaScript: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties of a box with widgetAlignment:constants.WIDGET_A
LIGN_TOP_LEFT.
var basicConfBox = {id : "boxwidgetAlignment", isVisible:true, orientation
var layoutConfBox = {containerWeight:99, widgetAlignment:constants.WIDGET_
ALIGN_TOP_LEFT};
//Creating the box.
boxwidgetAlignment = new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
l
SPA
Desktop Web
6.3 VBox - Platform Specific Properties

The platform specific properties for VBox Widget are as follows:
l
blockedUISkin
borderCollapse
contextMenu
hoverSkin
viewConfig
6.3.1 blockedUISkin
call) is completed.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Call back for box onClick event
function boxblockedUISkinTCSPAPlayClick(box)
{
//Call the service here to observe blockedUI skin
}
//The below two functions will explain how to use blockedUISkin property f
or Box widget.
var basicConf = {id : "lblblockedUISkin", text:"Click this Box to see bloc
kedUI skin while calling the service", isVisible:true};
containerWeight:100, widgetAlignment:constants.WIDGET_ALIGN_CENTER};
var lblblockedUISkin = new kony.ui.Label(basicConf, layoutConf, {});
//onClick event is triggered when user clicks on the box ,In this case we
are calling the service inside the callback to observe the blockedUI skin.
var basicConfBox = {id : "boxblockedUISkin", isVisible:true, orientation:c
onstants.BOX_LAYOUT_VERTICAL,onClick:boxblockedUISkinTCSPAPlayClick};
//Creating the Box
var boxblockedUISkin = new kony.ui.Box(basicConfBox, layoutConfBox, {block
edUISkin:"blockUISkin"});
boxblockedUISkin.add(lblblockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
Specifies if the space between the Box and its child widgets is considered.
Default: false
If set to true, the default space between the parent and the child widget reduces.
If set to false, the default space between the parent and the child widget retained.
Syntax
JavaScript: borderCollapse
Lua: bordercollapse
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Creating the box with borderCollapse:true .(If you set the Border-Collap
se value to true, the default space between the parent and the child widget
reduces else not.)
constants.BOX_LAYOUT_VERTICAL};
var PSPConfBox = {borderCollapse:true}
//Creating the box.
nfBox );
Accessible from IDE

Yes
l
6.3.3 contextMenu
Note: Due to BlackBerry platform limitation, to display a context menu for an Box, you must define an
onclick event for the Box.
l
added. If you add a context menu with 3 items, it will display Full Menu, Help, and Switch Application
items along with the items added.
BlackBerry 6.x

(<6.x)
Device (<6.x)
The below description and procedure is applicable to Desktop Web platform only.
Default: None
Series of steps to be followed to use contextMenu:
2. Define a contextmenu template under project > templates >contexmenus.

d. Enter a Name for the template and click Finish. A new form is created.
e. Drag-drop a menucontainer. You can drag-drop a menucontainer widget only.
Syntax
Lua: contextmenu
Type
Lua: Table
Read / Write
JavaScript Example
//Defining contextMenu items for Windows 8 platform.
allbackMenuItem1 };
callbackMenuItem3};
callbackMenuItem4};
{
}
{
}
{
}
{
}
//Defining the box with contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]
var PSPConfBox = {contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]};
//Creating the box.
nfBox );
The below example is applicable to Desktop Web platform only.

function initializeaddtoabc() {
"data": [
{template: hbox12068, "label12068": {"text": "India"},
children: [{template: hbox12068, "label12068": {"text": "Mu
mbai"},
"image212068": {}, children: [] }]
}, {template: hbox12068, "label12068": {"text": "Srilanka" },
"image212068": {}
}],
212068"},
"menuItemTemplate": hbox12068}, {"widgetAlignment": constants.WIDG
ET_ALIGN_CENTER,
"containerWeight": "50", "margin": [0, 0, 0, 0],
"padding": [0, 0, 0, 0], "marginInPixel": false,
}, {
"viewType": constants.MENU_CONTAINER_VIEW_TYPE_CONTEXTVIEW
});
};
//Defining the box with contextMenu:menucontainer12068
//Creating the box.
nfBox );
Accessible from IDE

No. But for Desktop Web platform you can access it through IDE.
l
BlackBerry
Windows Tablet
Desktop Web
6.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
6.3.5 viewConfig
l
Normal view
Grid view
grid view.
Syntax
Lua: viewconfig
Type
JavaScript:Object
Lua: table
Read / Write
No
Accessible from IDE

Yes
6.4 VBox - Events

The VBox Widget has the following event associated with it:
l
onClick
onHover
onRightClick
preOnclickJS
postOnclickJS
6.4.1 onClick
An event callback is invoked by the platform when the user performs a click action on the widget.
Note: If both onClick and a single tab gesture has been defined for a box then the behavior is undefined.
Syntax
JavaScript: onClick
Lua: onclick
The onClick event callback accepts additional parameters when a VBox is placed in a segment row or section
template.
Signature
Input Parameters
Index of the row that contains the VBox. It is not available if the VBox is placed in a section header.
Index of the section row that contains the VBox.
Handle to the parent widget instance(segment) that contains the VBox.
Read / Write
JavaScript Example
//The below function is callBack for onClick event
{
}
var basicConfBox = {id : "boxOnClickTest", isVisible:true, orientation:con
stants.BOX_LAYOUT_VERTICAL, onClick:boxOnClickEventTest};
//Creating the Box.
Available on all platforms except on all Mobile Web platforms.
6.4.2 onHover
An event callback is invoked by the platform based on the below actions:
l
When the mouse enters into the widget region.
When the mouse moves with in the widget region.
When the mouse leaves from the widget region.
Note: When the event callback is invoked, corresponding widget state is not updated as
selected/unselected.
Below are the points to be considered while using onHover event.
l
To remove onHover event on a widget, set it to null.

widget.onHover = null;
Data / computing intense operations should not be performed in onHover callback.
Avoid network calls in onHover event as it affects the performance.
Use this event to update the skin.
When an onHover event is defined to both parent and child widgets, the onHover event executes as
follows:
When mouse moves into parent widget, then MOUSE_ENTER event gets fired on the parent
widget.
When mouse moves inside the parent widget, then MOUSE_MOVE event is fired continuously
till mouse moves inside the parent widget.
When mouse moves into the child widget area, then MOUSE_ENTER event gets fired on the
child widget.
When mouse moves inside the child widget area, then MOUSE_MOVE event is fired on child
widget and also on the parent widget.
When mouse moves out of the child widget area, then MOUSE_LEAVE event gets fired on
child widget and MOUSE_MOVE event gets fired on the parent widget.
When mouse moves out of the parent widget, then MOUSE_LEAVE event gets fired on the
parent widget.
Signature
JavaScript: onHover (widget, context)
Input Parameters
Handle to the widget instance that raised the event.
context [Object] - Mandatory
Specifies the JSObject with the following key values.
eventType [Constant] - Mandatory
constants.ONHOVER_MOUSE_ENTER - When the mouse enters
into the widget region.
constants.ONHOVER_MOUSE_MOVE - When the mouse move
within the widget region.
constants.ONHOVER_MOUSE_LEAVE - When the mouse leaves
from the widget region.
Specifies the index of the section where the current focused row belongs. It is
applicable only if parent is segmentedUI.
Specifies the index of the current focused row relative to its section. It is
applicable only if parent is SegmentedUI or DataGrid.
columnIndex [Number] - Optional
Specifies the index of the cell in DataGrid where the mouse exists. It is applicable
only if parent is DataGrid.
selectionState [Boolean] - Optional
Specifies the selection state when the widget is placed inside a segmentedUI and
its selectionBehavior property is set as SEGUI_MULTI_BEHAVIOR or SEGUI_
SINGLE_SELECT_BEHAVIOR to indicate the current focused rows checked or
unchecked state.
index [Number] - Optional
Specifies the index of the current focused image in ImageGallery or
HorizontalImageStrip widgets. It is applicable only for ImageGallery or
HorizontalImageStrip widgets.
key [String] - Optional
Specifies the key of the element in a CheckBoxGroup or RadioButton widgets.
pageX [Number] - Mandatory
Specifies the horizontal coordinate of the onHover event relative to the whole
document.
pageY [Number] - Mandatory
Specifies the vertical coordinate of the onHover event relative to the whole
document.
screenX [Number] - Mandatory
Specifies the horizontal coordinate of the onHover event relative to the screen
width.
screenY [Number] - Mandatory
Specifies the vertical coordinate of the onHover event relative to the screen
height.
JavaScript Example
//Sample code to use onHover event
function onHoverEventCallback(widget,context)
{
console.log("button hover event executed" + context.eventType);
if (context.eventType == constants.ONHOVER_MOUSE_ENTER)
{
}
else if (context.eventType == constants.ONHOVER_MOUSE_MOVE)
{
}
else if (context.eventType == constants.ONHOVER_MOUSE_LEAVE)
{
widget.skin = "blue";
}
}
function addHoverEvent()
{
console.log("registering hover events");
form1.button1.onHover = onHoverEventCallback;
}
function removeHoverEvent()
{
console.log("removing hover events");
form1.button1.onHover = null;
}
6.4.3 onRightClick
An event callback is invoked by the platform when the user performs a right click action on the widget.
Note: This event is enabled only when you select a template for contextMenu property.
Syntax
JavaScript: onRightClick
Read / Write
JavaScript Example
//The below function is callBack for onRightClick event
function boxOnRightClickEventTest(box)
{
alert("OnRightClick event is invoked successfully");
}
var basicConfBox = {id : "boxOnRightClickTest", isVisible:true, orientatio
n:constants.BOX_LAYOUT_VERTICAL, onRightClick:boxOnRightClickEventTest};
//Creating the Box.
6.4.4 preOnclickJS
This event allows the developer to execute custom JavaScript function before the onClick callback of the box
is invoked. This is applicable only for Mobile Web channel. The function must exist in a JavaScript file under
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is callBack for preOnClickJS event
function preOnClickJSCallBack(box)
{
}
//The below two functions will test the preOnclickJS event.
var basicConf = {id : "lblPreEventSkinTC", text:"Click here to test PreOnC
lick JS so that JS function will get called", isVisible:true};
var layoutConf = {contentAlignment :constants.CONTENT_ALIGN_CENTER, contai
nerWeight:100, widgetAlignment:constants.WIDGET_ALIGN_CENTER,
vExpand:true};
//Creating the Label
var lblPreEventSkinTC = new kony.ui.Label(basicConf, layoutConf, {});
var basicConfBox = {id : "boxPreEventSkinTC", isVisible:true, orientation:
//Creating the box.
var boxPreEventSkinTC = new kony.ui.Box(basicConfBox, layoutConfBox, {preO
nclickJS:preOnClickJSCallBack});
boxPreEventSkinTC.add(lblPreEventSkinTC);
6.4.5 postOnclickJS
This event allows the developer to execute custom JavaScript function after the onClick callback of the
widget is invoked. This is applicable only for Mobile Web channel. The function must exist in a JavaScript file
under project>module>js folder.
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is callBack for postOnclickJS event
function PostOnclickJSCallBack(box)
{
}
//The below two functions will test the postOnclickJS event.
var basicConf = {id : "lblPostEventSkinTC", text:"Click here to test postO
nclick JS so that JS function will get called", isVisible:true};
containerWeight:100, widgetAlignment:constants.WIDGET_ALIGN_CENTER};
var lblPostEventSkinTC = new kony.ui.Label(basicConf, layoutConf, {});
var basicConfBox = {id : "boxPostEventSkinTC", isVisible:true, orientation
:constants.BOX_LAYOUT_VERTICAL};
//Creating the Box.
var boxPostEventSkinTC = new kony.ui.Box(basicConfBox, layoutConfBox, {pos
tOnclickJS:PostOnclickJSCallBack});
boxPostEventSkinTC.add(lblPostEventSkinTC);
6.5 VBox - Methods

VBox Widget has the following methods associated with it:
l
add
addAt
remove
removeAt
replaceAt
widgets
6.5.1 add
This method is used to add widgets to the box container. When the widgets are added to the current visible
form, then the changes will reflect immediately. Adding a widget to the Box hierarchy, which is already a part
of the other widget hierarchy, will lead to undefined behaviors. You have to explicitly remove the widget from
one hierarchy before adding it to another Box.
Signature
JavaScript: add()
Lua:box.add(boxid )
Input Parameters
Return Values
Exceptions
WidgetError
JavaScript Example
var basicConfBox = {id : "boxAddMethodTest", isVisible:true, orientation:c
onstants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
//Creating the Box.
var boxAddMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Adding label ,button widgets to the box Here label and button widgets sh
ould be created already and accessible as well.
boxAddMethodTest.add(lbl,btn);
6.5.2 addAt
This method is used to add widgets to the Box container at the specified index. Widget is prepended if index
present in the container. If a new widget is added or removed will reflect immediately from the Box hierarchy
Signature
JavaScript: addAt(widgetref, index, animationConfig)
Lua:box.addat(boxid, widgetref, index)
Input Parameters
Reference of the widget to be added
l







to end.
l


Return Values
None
Exceptions
WidgetError
JavaScript Example
var withAnimConfig=
{
"animDuration":1.5,
"animDelay":0.4,
"animCallBacks":{
}
}
var basicConfBox = {id : "boxAddAtMethodTest", isVisible:true, orientation
//Creating the Box.
var boxAddAtMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Adding label to the box at 15th index Position.Here label should be crea
ted already and accessible as well.
boxAddAtMethodTest.addAt(15, withAnimConfig);
6.5.3 remove
This method removes a widget from the Box container. If a new widget is removed will reflect immediately
from the Box hierarchy model perspective, however the changes are displayed when the Box appears. When
the widgets are added to the current visible Box, then the changes will reflect immediately.
Signature
Lua:box.remove(boxid, widgetref)
Input Parameters
Reference of the widget to be removed.
Return Values
Exceptions
WidgetError
JavaScript Example
var basicConfBox = {id : "boxRemoveMethodTest", isVisible:true, orientatio
n:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
//Creating the Box.
var boxRemoveMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {});
//Removing label widget from the box .Here label should be created already
and added inside the box.
boxRemoveMethodTest.remove(lbl);
6.5.4 removeAt
This method removes a widget at the given index from the Box container. If a new widget is removed will
reflect immediately from the Box hierarchy model perspective, however the changes are displayed when the
Box appears. When the widgets are added to the current visible Box, then the changes will reflect
immediately.
Signature
JavaScript: removeAt(index, animationConfig)
(version 3.0 and above) platforms. It is supported in Kony Studio version 5.6 and above only.
Lua:box.removeat(boxid, index)
Input Parameters
Index number at which the widget is to be removed.

l

must collapse gradually by decreasing the height of the widget. This option
is applicable only when visibility is turned on.


l




to end.
l


Return Values
Exceptions
WidgetError
JavaScript Example
{
"animDuration":1,
"animDelay":0,
}

//Creating the Box.

});
//Removing label from the box at 15th index Position. Here label should be
boxRemoveAtMethodTest.removeAt(15,withAnimConfig1);
6.5.5 replaceAt
This method replaces a widget with another widget in a VBox. If a widget is replaced from the VBox, will
reflect immediately from the VBox hierarchy model perspective; however the changes are displayed when the
VBox appears.
Signature
Input Parameters
l
animationConfig[JSObject] - Optional



l




to end.
l

l

Return Values
Exceptions
WidgetError
JavaScript Example
{
"animDuration":2,
"animDelay":3,
"animCallBacks":{
}
}

//Creating the Box.
});
//Replacing label from the box at 15th index Position. Here label should be
boxRemoveAtMethodTest.removeAt(newWidget,15,withAnimConfig2);
l
iOS
Android
6.5.6 widgets
This method returns an array of the widget references which are direct children of Box.
Signature
Lua:box.widgets(boxid)
Input Parameters
Return Values
of widgets in this array doesn't reflect in the Box hierarchy, however you can get handle to the widgets
widgets.
Exceptions
WidgetError
JavaScript Example
var wigArr = new Array();
var basicConfBox = {id : "boxWidgetsMethodTest", isVisible:true, orientati
on:constants.BOX_LAYOUT_VERTICAL, skin:"gradroundbox"};
//Creating the Box.
var boxWidgetsMethodTest = new kony.ui.Box(basicConfBox, layoutConfBox, {}
);
//Collecting all the widgets of the box into array and displaying the refe
rences.
wigArr = boxWidgetsMethodTest.widgets();

Note: Context Menu templates are supported only on Desktop Web platform.

In Desktop Web, when you right click a Menu Container or a Box the context specific menu will be displayed
with the array of menu items. A Context Menu Template is essentially a template having a Menu Container in
which the developer customizes the overall look and feel of the context menu.

Context Menu Templates are used to display how the data is presented to the end user when a context menu
pops up.

When you want the same template to be displayed across all the Context Menus in the application, you have
a provision to add a Context Menu Template using Kony Studio.
To create a context menu template at the application-level, follow these steps:
2. Expand the application for which you want to create the Context Menu Template.
3. Navigate to templates > contextmenus, right-click desktop and select New ContextMenu Template.
The Create a New Menu dialog appears.
iii. Drag and drop a Menu container in the form.
iv. Set the required properties and click Save. A Context Menu template is created.

You can create separate templates for each context menu using the above process. In Desktop Web, when
you right click a Menu Container or a Box the context specific menu will be displayed with the array of menu
items.
To use Context Menu Template in an application, follow these steps:
2. Expand the application for which you want to use Context Menu.
window appears.
5. Drag-drop a Box or a Menu container on the form and set data using the contextMenu property under
Desktop Web.
7. ScrollBox
A ScrollBox is a scrollable container which allows you to scroll the content within horizontally and vertically.
A ScrollBox can contain any widget except a Tab pane. It can contain any number of widgets within it.
Note: In Desktop Web platform, ScrollBox is displayed in browser native mode.
ScrollBox provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Properties, an Event, and Methods.
Basic Properties
Layout Properties
enableScrollByPage
id
info
isVisible
orientation
position
pullToRefreshI18NKey
pullToRefreshSkin
pushToRefreshI18NKey
pushToRefreshSkin
releaseToPullRefreshI18NKey
releaseToPushRefreshI18NKey
scrollDirection
showScrollBars
skin
containerHeight
containerHeightReference
containerWeight
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
percent
bounces
contextMenu
scrollArrowConfig
viewConfig
Methods
Events
Deprecated
add
addAt
remove
removeAt
scrollToBeginning
scrollToEnd
scrollToWidget
widgets
scrollingEvents
fixedHeight
heightReference
scrollOption
sizePercent
WidgetDirection
Use widget size %
Creating a ScrollBox using a constructor: kony.ui.ScrollBox

var scrollbox1 = new kony.ui.ScrollBox(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Defining properties for a ScrollBox.
var scrollBasic = {id :"scrollBox",skin:"scrlSkin", isVisible:true, orient
ation:constants.BOX_LAYOUT_HORIZONTAL, position:constants.BOX_POSITION_AS_
FOOTER, scrollDirection:constants.SCROLLBOX_SCROLL_VERTICAL};
var scrollLayout = {padding:[2,2,2,2], containerWeight:100, margin:[5,5,5,
5], containerHeight:100, percent:true};
var scrollPSP = {scrollArrowConfig:["leftArrow.png", "topArrow.png", "rig
htArrow.png", "bottomArrow.png"]};
//Creating the ScrollBox.
var scrollBox = new kony.ui.ScrollBox(scrollBasic, scrollLayout, scrollPS
P);
Adding a ScrollBox Widget using IDE

The steps involved in adding a ScrollBox widget are as follows:
1. From the IDE, drag and drop the ScrollBox widget onto a form or any other container widget.
2. ScrollBox widget enables horizontal scrolling by default. You can stack all the widgets horizontally
when the orientation is set as horizontal. To stack widget vertically within the ScrollBox, set the
orientation as vertical.
3. Drag and drop the required number of other widgets into the Scroll Box widget.
4. Set the scrollDirection as horizontal, vertical, both, or, none. Using the Scroll option, you can define the
scrolling direction of the ScrollBox.
Customizing Appearance
You can customize the appearance of the ScrollBox by using the following properties:
l
margin: Defines the space around a widget.
padding: Defines the space between the content of the widget and the widget boundaries.
skin: Specify the skin to be applied to the ScrollBox widget.
Important Considerations:
The following are the important considerations of a ScrollBox:
l
For a good user experience, you must place the ScrollBox using a percentage layout. In a nonpercentage layout the width of the ScrollBox varies across platforms.
If you set the scrollDirection as SCROLLBOX_SCROLL_VERTICAL or SCROLLBOX_SCROLL_

BOTH, specifying a containerHeight is mandatory.
When a widget is placed inside a horizontal parent widget. For example: Box, Segment, it will take
40% of the parent widget or the available free space of the widget.
For BlackBerry platforms, to navigate the contents within a ScrollBox, arrows are used instead of
scrollbars.
Only Horizontal Scrolling is applicable for BlackBerry.
7.1 ScrollBox - Basic Properties

The basic properties of ScrollBox Widget are as follows:
l
enablesScrollByPage
id
info
isVisible
orientation
position
pullToRefreshSkin
pushToRefreshSkin
scrollDirection
showScrollbars
skin
7.1.1 enableScrollByPage
Enables the scrolling of the content in increments of the width of the scrollbox on swipe gesture.
Default: false
If set to true, the scroll by page is enabled.
If set to false, the scroll by page is disabled.
Syntax
JavaScript: enableScrollByPage
Lua: enablescrollbypage
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with enableScrollByPage:true
ation:constants.BOX_LAYOUT_HORIZONTAL, enableScrollByPage:true};
var scrollLayout
= {padding:[2,2,2,2], containerWeight:100, margin:[5,5,
5,5], containerHeight:100, percent:true};
var scrollPSP = {};
P);
Accessible from IDE

Yes
l
iPhone
iPad
7.1.2 id
id is a unique identifier of a ScrollBox consisting of alpha numeric characters. Every ScrollBox should have a
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a ScrollBox with id:"scrollBox"
ation:constants.BOX_LAYOUT_HORIZONTAL};
var scrollLayout
var scrollPSP = {};
P);
Accessible from IDE

Yes
7.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with info property.
var scrollBasic = {id :"scrollBox", skin:"scrlSkin", isVisible:true, orien
tation:constants.BOX_LAYOUT_HORIZONTAL};
var scrollLayout
var scrollPSP = {};
P);
scrollBox.info = {key:"SCROLL"};
Accessible from IDE

No
7.1.4 isVisible
Specifies the visibility of the widget.
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with isVisible:true
var scrollLayout
= {padding:[2,2,2,2], containerWeight:100,margin:[5,5,5
,5], containerHeight:100, percent:true};
var scrollPSP = {};
//Creating the ScrollBox
P);
Accessible from IDE

Yes
7.1.5 orientation
Specifies how you can stack the widgets within the ScrollBox. You can set the orientation of the ScrollBox as
horizontal or vertical.
Note: ScrollBox with a vertical orientation cannot be placed directly on a form. It has to be placed inside an
HBox and only then you can place a ScrollBox with vertical orientation.
l
BOX_LAYOUT_HORIZONTAL: Enables you to stack the content within the scrollbox horizontally.
BOX_LAYOUT_VERTICAL: Enables you to stack the content within the scrollbox vertically.
Syntax
Lua: orientation
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a ScrollBox with orientation:constants.BOX_LAYOU
T_HORIZONTAL
var scrollPSP = {};
P);
Accessible from IDE

Yes
7.1.6 position
Specifies if the ScrollBox must be positioned as a header or footer of the form.
Default: BOX_POSITION_AS_NORMAL.
l
BOX_POSITION_AS_HEADER: Specifies the position of the ScrollBox is fixed at the top of the Form.
BOX_POSITION_AS_FOOTER: Specifies the position of the ScrollBox is fixed at the bottom of the
Form.
BOX_POSITION_AS_NORMAL: Retains the original position of the ScrollBox.
BOX_POSITION_AS_SCREENLEVEL_SEG_HEADER: This option is useful if the box is placed on

a form with a Segment on it. You must set the screenLevelWidget property of the particular segment to
true. The scrollbox attaches itself to the Segment as a header and scrolls along with the segment. If
the screelLevelWidget property of the particular segment is not set, then this value is ignored and the
box is treated as normal. This option is not supported on all Windows platforms.
BOX_POSITION_AS_SCREENLEVEL_SEG_FOOTER: This option is useful if the box is placed on a

form with a Segment on it. You must set the screenLevelWidget property of the particular segment to
true. The scrollbox attaches itself to the Segment as footer and scrolls along with the segment. If the
screelLevelWidget property of the particular segment is not set, then this value is ignored and the box
is treated as normal. This option is not supported on all Windows platforms.
This property is respected only for immediate child box (with horizontal orientation) of Form container.
Syntax
JavaScript: position
Lua: position
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with position:constants.BOX_POSITION_
AS_FOOTER
tation:constants.BOX_LAYOUT_HORIZONTAL, position:constants.BOX_POSITION_AS_
FOOTER};
var scrollPSP = {};
P);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and Desktop Web platforms.
Specifies the i18N key for "pull to refresh" title. The platforms get the value from the existing application locale
specific i18N resource bundle. If the key is not found in the resource bundle, then platforms use the default
(english locale) title text.
Note: This property is supported when the orientation is set as BOX_LAYOUT_VERTICAL.
Syntax
JavaScript: pullToRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Available on all platforms except BlackBerry, BlackBerry 10, Desktop Web, Windows Kiosk, and Server
side Mobile Web platforms
Specifies the skin to be applied to the pull to refresh title.
Following are the skin definition properties:
l
font_weight
font_style
font_size
font_color
font_name
background_color
bg_type
background_style
Note: The "release to refresh" title picks the skin of "pull to refresh" or "release to refresh" respectively.
Syntax
JavaScript: pullToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the i18N key for "push to refresh" title. The platforms get the value from the existing application
locale specific i18N resource bundle. If the key is not found in the resource bundle, then platforms use the
default (english locale) title text.
Syntax
JavaScript: pushToRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the skin to be applied to the push to refresh title.
l
font_weight
font_style
font_size
font_color
font_name
background_color
bg_type
background_style
Syntax
JavaScript: pushToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the i18N key for "release to refresh" title that appears for pull to refresh. The platforms get the value
from the existing application locale specific i18N resource bundle. If the key is not found in the resource
bundle, then platforms use the default (english locale) title text.
Syntax
JavaScript: releaseToPullRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the i18N key for "release to refresh" title that appears for push for refresh. The platforms get the
value from the existing application locale specific i18N resource bundle. If the key is not found in the resource
Syntax
JavaScript: releaseToPushRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies how you can scroll the content within the ScrollBox.
Default: SCROLLBOX_SCROLL_HORIZONTAL
l
SCROLLBOX_SCROLL_HORIZONTAL: Enables you to scroll the content within the ScrollBox

horizontally.
SCROLLBOX_SCROLL_VERTICAL: Enables you to scroll the content within the ScrollBox vertically.
(Applicable on iPhone and Android platforms only)
SCROLLBOX_SCROLL_BOTH: Enables you to scroll the content within the ScrollBox horizontally as
well as vertically. (Applicable on iPhone and Android platforms only)
SCROLLBOX_SCROLL_NONE: Disables scrolling of the content in the ScrollBox.
Note: On SPA and BlackBerry10 platforms, SCROLLBOX_SCROLL_HORIZONTAL is not supported

when the orientation is set as BOX_LAYOUT_VERTICAL and SCROLLBOX_SCROLL_VERTICAL is not
supported when the orientation is set as BOX_LAYOUT_HORIZONTAL.
Syntax
JavaScript: scrollDirection
Lua: scrolldirection
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with scroll direction as vertical.
tation:constants.BOX_LAYOUT_HORIZONTAL, scrollDirection:constants.SCROLLBO
X_SCROLL_VERTICAL};
var scrollPSP = {};
P);
Accessible from IDE

Yes
Specifies the visibility of the ScrollBars. If you set the scrollDirection to other than none and setting
showScrollbars property to true, enables you to view the scrollbars.
Default: true
If set to false, the scrollbars are not displayed.

If set to true, the scrollbars are displayed.
Note: On iPhone platform scrollbars are visible while scrolling and become invisible once you stop scrolling.
Syntax
JavaScript: showScrollbars
Lua: showscrollbars
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with showScrollbars:true
tation:constants.BOX_LAYOUT_HORIZONTAL, showScrollbars:true};
var scrollLayout
var scrollPSP = {};
P);
Accessible From IDE

Yes
Available on all platforms except on all Server side Mobile Web, BlackBerry 10, and Windows Kiosk
platforms.
7.1.15 skin
Specifies a background skin for ScrollBox widget.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with skin:"scrlSkin"
var scrollLayout
var scrollPSP = {};
P);
Accessible From IDE

Yes
Available on all platforms except on all Server side Mobile Web platforms
7.2 ScrollBox - Layout Properties

The Layout properties of ScrollBox Widget are as follows:
l
containerHeight
containerWeight
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
percent
Specifies the available height of the container in terms of percentage. The percentage is with reference to the
value of containerHeightReference property.
For example, On a Form you have a ScrollBox with 5 labels and 5 buttons in it and a CloseButton below the
ScrollBox. If the containerHeight is set as 100 (percentage) and containerHeightReference is set as
SCROLLBOX_HEIGHT_BY_FORM_REFERENCE, then the ScrollBox occupies the height of the Form
excluding the height occupied by the CloseButton.
Default: If not configured, the value may vary depending on the platforms
Syntax
JavaScript: containerHeight
Lua: containerheight
Type
JavaScript: Number
Lua: Number
Read / Write
Yes- (Read and Write)
JavaScript Example
//Defining properties for a ScrollBox with enableScrollByPage:true
ation:constants.BOX_LAYOUT_HORIZONTAL, enableScrollByPage:true};
var scrollLayout
var scrollPSP = {};
P);
Accessible form IDE

No
Platform availability
This property is enabled when you set the containerHeight. The widget height percentage is calculated based
on the following options.
Default: CONTAINER_HEIGHT_BY_FORM_REFERENCE
The container height percentage is calculated based on the below options.
l
CONTAINER_HEIGHT_BY_FORM_REFERENCE: The scrollbox height is percentage calculated

based on the height of the Form excluding headers and footers. This property doesn't have any effect if
the scrollbox is placed inside a popup or headers/footers.
CONTAINER_HEIGHT_BY_PARENT_WIDTH: Use this option if the scrollbox is placed inside a

Box. The width is calculated based on the width of the Box. The BlackBerry10 platform supports this
option only.
Syntax
JavaScript: containerHeightReference
Lua: containerheightreference
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with containerHeightReference:consta
nts.SCROLLBOX_HEIGHT_BY_PARENT_WIDTH
var scrollLayout
5,5], containerHeight:100, percent:true, containerHeightReference:constant
s.CONTAINER_HEIGHT_BY_PARENT_WIDTH};
var scrollPSP = {};
P);
//Reading the containerHeightReference of the ScrollBox.
alert("ScrollBox containerHeightReference
::"+scrollBox.containerHeightReference);
Accessible from IDE

Yes
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with containerWeight:100
var scrollPSP = {};
P);
//Reading the containerWeight of the ScrollBox.
alert("ScrollBox containerWeight ::"+scrollBox.containerWeight);
Accessible from IDE

Yes
This property is enabled when you set the percent property as false. Specifies the direction in which the
widgets are laid out.
l
BOX_LAYOUT_ALIGN_FROM_LEFT: The widgets are aligned from left in the scrollbox.
BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets are aligned center.
BOX_LAYOUT_ALIGN_FROM_RIGHT: The widgets are aligned from right.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//creating ScrollBox with layoutAlignment:constants.BOX_LAYOUT_ALIGN_FROM_
CENTER
var scrollLayout
5,5], containerHeight:100, percent:false, layoutAlignment:constants.BOX_LA
YOUT_ALIGN_FROM_CENTER};
var scrollPSP = {};
var scrollBox = new kony.ui.ScrollBox(scrollBasic, scrollLayout,
scrollPSP);
Accessible from IDE

Yes
7.2.5 margin
Syntax
JavaScript: margin
Lua: margin
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with margin:[5,5,5,5]
var scrollLayout
var scrollPSP = {};
P);
Accessible from IDE

Yes
7.2.6 marginInPixel
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with margin in pixels.
var scrollLayout
5,5], containerHeight:100, percent:true, marginInPixel:true};
var scrollPSP = {};
//Creating a ScrollBox.
P);
Accessible from IDE

Yes
l
iPhone
iPad
7.2.7 padding
button and select the platforms on which you want the padding values to be applied.
on Mobile Web platform.
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a ScrollBox with padding:[2,2,2,2]
var scrollPSP = {};
P);
Accessible from IDE

Yes
Default: false
If set to true, the padding are applied in pixels.
If set to false, the padding are applied as set in padding property.
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with padding in pixels.
5], containerHeight:100, percent:true, paddingInPixel: true};
var scrollPSP = {};
P);
Accessible from IDE

Yes
l
iPhone
iPad
7.2.9 percent
Specifies if the child widgets weight factor must be considered during layout.
Note: In kony.application.setApplicationBehaviors API the parameter retainSpaceOnHide is only applicable
when percent property is set to True for ScrollBox.
Default: true
If set to false, the layoutAlignment is considered.
If set to true, the containerWeight is considered.
Syntax
JavaScript: percent
Lua: percent
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with percent:true
var scrollPSP = {};
P);
Accessible from IDE

Yes
7.3 ScrollBox - Platform Specific Properties

The platform specific properties of ScrollBox Widget are as follows:
l
bounces
contextMenu
scrollArrowConfig
viewConfig
7.3.1 bounces
Default:true
Syntax
JavaScript: bounces
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with bounces:true
var scrollLayout
var scrollPSP = {bounces:true };
P);
Accessible from IDE

Yes
l
iPhone
iPad
7.3.2 contextMenu
Note: The property is available only on BlackBerry platform.
l
The following images illustrates the context menu on various BlackBerry devices:
BlackBerry 6.x
Device
Syntax
Lua: contextmenu
Type
Lua: Table
Read / Write
JavaScript Example
//Defining contextMenu items for Windows 8 platform.
allbackMenuItem1 };
callbackMenuItem3};
callbackMenuItem4};
{
}
{
}
{
}
{
}
//Defining properties for a ScrollBox with contextMenu:
[appMenu1,appMenu2,appMenu3,appMenu4]
var scrollLayout
var scrollPSP = {contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]};
P);
Accessible from IDE

No
l
BlackBerry
Windows Tablet
7.3.3 scrollArrowConfig
Specifies the images to indicate the scroll arrows of the ScrollBox in four directions. Use the below options to
set the appropriate value:
l
leftArrow : Specifies the image location of the left arrow.
rightArrow : Specifies the image location of the right arrow.
topArrow : Specifies the image location of the top arrow.
bottomArrow : Specifies the image location of the bottom arrow.
Syntax
JavaScript: scrollArrowConfig
Lua: scrollarrowconfig
Type
JavaScript: Array
Lua: Table
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with scrollArrowConfig:["leftArrow.p
ng", "topArrow.png", "rightArrow.png", "bottomArrow.png"]
var scrollLayout
var scrollPSP = {scrollArrowConfig:["leftArrow.png", "topArrow.png", "rig
htArrow.png", "bottomArrow.png"] };
P);
Accessible from IDE

Yes
l
Desktop Web
7.3.4 viewConfig
l
Normal view
Grid view
grid view.
Syntax
Lua: viewconfig
Type
JavaScript:Object
Lua: table
Read / Write
No
JavaScript Example
//Defining properties for a ScrollBox with scrollArrowConfig:["leftArrow.p
ng", "topArrow.png", "rightArrow.png", "bottomArrow.png"]
var scrollLayout
var scrollPSP = {viewConfig: {
referenceHeight: 0,
sizeMode: "constants.GRID_TYPE_FIXED",
referenceWidth: 0
}
};
P);
Accessible from IDE

Yes
7.4 ScrollBox - Events

ScrollBox has the following event associated with it:
l
scrollingEvents
Specifies the scrolling events which gets called when scrolling reaches beginning of the widget, end of the
widget, when the user tries to pull or push the scrolling beyond the vertical boundaries of the widget.
Following are the events and their callback signature:
onReachingBegining: Gets called when scrolling reaches the beginning of the ScrollBox
widget.
Signature
JavaScript: onReachingBegining(scrollBox, scrollDirection)
Lua: onreachingbegining(scrollBox, scrollDirection)
onReachingEnd: Gets called when scrolling reaches the end of the ScrollBox widget.
Signature
JavaScript: onReachingEnd(scrollBox, scrollDirection)
Lua: onreachingend(scrollBox, scrollDirection)
onPull: Gets called when ScrollBox is pulled from top.

Signature
JavaScript: onPull(scrollBox, scrollDirection)
Lua: onpull(scrollBox, scrollDirection)
onPush: Gets called when ScrollBox is pushed from bottom.

Signature
JavaScript: onPush(scrollBox, scrollDirection)
Lua: onpush(scrollBox, scrollDirection)
Input Parameters
scrollBox [widgetref] - Mandatory
Handle to the widget reference.
scrollDirection - Mandatory
Specifies the direction in which the scroll box must scroll. Following are the available options:
l
SCROLLBOX_SCROLL_VERTICAL: Specifies the scroll box must scroll vertical

direction.
SCROLLBOX_SCROLL_BOTH: Specifies the scroll box must scroll in both horizontal

and vertical direction.
Note: To set the value through code, prefix the option with constants. such as
constants.<option> .
Type
Lua: UserData
Read / Write
JavaScript Example
//The below is the callback function for onReachingBegining event which co
mes under scrollingEvents.
function onReachingBeginingCallBack(scrollBox, scrollDirection)
{
alert("onReachingBegining event triggered");
}
//The below is the callback function for onReachingEnd event which comes u
nder scrollingEvents.
function onReachingEndFunCallBack(scrollBox, scrollDirection)
{
alert("onReachingEnd event triggered");
}
//The below is the callback function for onPull event which comes under sc
rollingEvents.
function onPullCallBack(scrollBox, scrollDirection)
{
alert("onPull event triggered");
}
//The below is the callback function for onPush event which comes under sc
rollingEvents.
function onPushCallBack(scrollBox, scrollDirection)
{
alert("onPush event triggered");
}
//Defining properties for a ScrollBox with enableScrollByPage:true.

var scrollBasic = {id :"scrollBox", skin:"scrlSkin", isVisible:true, scrol
lingEvents:{onReachingBegining:onReachingBeginingCallBack, onReachingEnd:o
nReachingEndCallBack, onPull:onPullCallBack, onPush:onPushCallBack}};
var scrollPSP = {};
P);
//Reading the scrollingEvents of the ScrollBox.
alert("ScrollBox scrollingEvents ::"+scrollBox.scrollingEvents);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, BlackBerry 10, and Desktop Web
platforms.
7.5 ScrollBox - Methods

ScrollBox has the following methods associated with it:
l
add
addAt
remove
removeAt
scrollToBeginning
scrollToEnd
scrollToWidget
widgets
7.5.1 add
This method is used to add widgets to the ScrollBox. When the widgets are added to the current visible
ScrollBox , then the changes will reflect immediately. Adding a widget to the ScrollBox hierarchy, which is
already a part of the other widget hierarchy, will lead to undefined behaviors. You have to explicitly remove the
widget from one hierarchy before adding it to another Box.
Signature
JavaScript: add(widgets)
Lua: box.add(boxref, widgets)
Input Parameters
widgets [widgetrefs]- Mandatory
boxref [widgetref]- Mandatory
Return Values
Exceptions
WidgetError
JavaScript Example
var scrollLayout
var scrollPSP = {};
P);
//Adding label and button widgets to the scrollBox. Here label and button
widgets should be created already and made accessible.
scrollBox.add(lbl,btn);
7.5.2 addAt
This method is used to add widgets to the ScrollBox container at the specified index. Widget is prepended if
index <0 and appended at the end of the container if the index > size+1. Size is the number of widgets already
present in the container. If a new widget is added or removed will reflect immediately from the form hierarchy
model perspective, however the changes are displayed when the ScrollBox appears. When the widgets are
added to the current visible ScrollBox, then the changes will reflect immediately. Adding a widget to the
ScrollBox hierarchy, which is already a part of the other widget hierarchy, will lead to undefined behaviors.
You have to explicitly remove the widget from one hierarchy before adding it to another ScrollBox.
Signature
JavaScript: addAt(widgetref, index)
Lua: box.addat(boxref, widgetref, index)
Input Parameters
widgetref [widgetref] - Mandatory
Reference of the widget that need to be added to the box.
boxref [widgetref] - Mandatory
Return Values
Exceptions
Widget Error
JavaScript Example
var scrollLayout
var scrollPSP = {};
P);
//Adding label to the scrollBox at 15th index Position. Here label should
be created already and made accessible.
scrollBox.addAt(lbl,15);
7.5.3 remove
This method removes a widget from the ScrollBox container. If a new widget is removed will reflect
immediately from the ScrollBox hierarchy model perspective, however the changes are displayed when the
ScrollBox appears. When the widgets are added to the current visible ScrollBox, then the changes will reflect
immediately.
Signature
Lua: box.remove(boxref, widgetref)
Input Parameters
widgetref [Number] - Mandatory
Return Values
Exceptions
WidgetError
JavaScript Example
var scrollLayout
= {padding:[2,2,2,2], containerWeight:100,margin:[5,5,5
,5], containerHeight:100, percent:true};
var scrollPSP = {};
P);
//Removing label widget from the scrollBox .Here label should be created a
lready and added inside the scrollBox.
scrollBox.remove(lbl)
7.5.4 removeAt
This method removes a widget at the given index from the ScrollBox container. If a new widget is removed will
reflect immediately from the ScrollBox hierarchy model perspective, however the changes are displayed when
the ScrollBox appears. When the widgets are added to the current visible ScrollBox, then the changes will
reflect immediately.
Signature
JavaScript: removeAt(index)
Lua: box.removeat(boxref, index)
Input Parameters
Index number of the widget to be removed.
Return Values
Reference of the removed widget.
Exceptions
WidgetError
JavaScript Example
var scrollLayout = {padding:[2,2,2,2], containerWeight:100,margin:[5,5,5,
var scrollPSP = {};
P);
//Removing label from the scrollBox at 15th index Position. Here the label
should be created and added at 15th index position of the scrollBox.
scrollBox.removeAt(15);
This method gives you the control to scroll to the beginning of the ScrollBox.
Signature
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
var scrollPSP = {};

P);
//Method to scroll to the beginning of the ScrollBox.
scrollbox.scrollToBeginning();
l
iOS
Android
SPA(iPhone/Android)
Windows Tablet
BlackBerry10
7.5.6 scrollToEnd
This method gives you the control to scroll to the end of the ScrollBox.
Signature
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
var scrollPSP = {};
P);
//Method to scroll to the end of the ScrollBox.
scrollbox.scrollToEnd();
l
iOS
Android
SPA(iPhone/Android)
Windows Tablet
BlackBerry10
This method gives you the control to scroll the ScrollBox up to the position of selected widget.
Note: On Windows Phone platform, scrollToWidget will not work when scrollDirection is set to
SCROLLBOX_SCROLL_NONE.
Signature
JavaScript: scrollToWidget()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
var scrollPSP = {};
P);
//Method to scroll the ScrollBox upto label.
scrollbox.scrollToWidget(labelForOk);
l
iOS
Android
Windows Tablet
Windows Phone
BlackBerry10
7.5.8 widgets
This method returns an array of the widget references which are direct children of ScrollBox.
Signature
Lua: box.widgets(boxref)
Input Parameters
Return Values
of widgets in this array doesn't reflect in the ScrollBox hierarchy. However, you can get handle to the
widgets through this array and modify the widgets through widget level methods as exposed by individual
widgets.
Exceptions
None
JavaScript Example
var scrollPSP = {};
P);
//Collecting all the widgets of the scrollBox into array and displaying the
references.
wigArr = scrollBox.widgets();
8. TabPane
TabPane widget is a container widget that allows you to organize multiple tabs within it. Each Tab will in turn
hold a collection of widgets within the same area of the Form. You can only view one Tab a time, and every
Tab in the TabPane widget consists of a certain type of information and is displayed when the user selects the
corresponding Tab.
Note: TabPane widget is not supported in BlackBerry 10 platform.
Click here to view TabPane features specific to Desktop Web platform
TabPane widget provides you an option to set Basic Properties, Layout Properties, Platform Specific
Properties, and Events. Deprecated properties are provided with their alternative properties in the Deprecated
section.
Basic Properties
Layout Properties
activeFocusSkin
activeSkin
activeTabs
id
inactiveSkin
info
isVisible
retainPositionInTab
screenLevelWidget
viewConfig
viewType
containerHeight
containerWidget
gridCell
layoutMeta
layoutType
margin
marginInPixel
padding
paddingInPixel
pageSkin
progressIndicatorColor
showProgressIndicator
tabHeaderTemplate
tabHeaderHeight
Events
Methods
onTabClick
preOnclickJS
postOnclickJS
addTab
addTab
addTabAt
removeTabAt
removeTabByld
Creating a TabPane using a constructor: kony.ui.TabPane

var tab = new kony.ui.TabPane (basicConf, layoutConf, pspConf)
l
layoutConf is an object with layout specific properties.
they are ignored.
JavaScript Example
//The below is the callback for onTabClick event.

function onTabClick(tabpane, tabIndex)
{
/* Write your logic here*/
}
//Defining the properties for TabPane.
var tabBasic = {id:"tPane",info:{key:"TabPane"}, activeSkin:"aSkin", activ
eFocusSkin:"aFSkin", inactiveSkin:"inActiveSkin", viewType:constants.TABPA
NE_VIEW_TYPE_TABVIEW , screenLevelWidget:true, isVisible:true, retainPosit
ionInTab:true, needPageIndicator:true, selectedTabIndex:0, onTabClick:onTa
bClick};
var tabLayout ={padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:true,
marginInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, conta
inerWeight:99};
var tabPSP={};
//Creating the TabPane.
var tabPane = new kony.ui.TabPane(tabBasic, tabLayout, tabPSP);
Adding a TabPane Widget from IDE

The steps involved in adding a TabPane widget are as follows:
1. From the IDE, drag and drop the TabPane widget onto a form (occupies 100% of the screen width).
2. TabPane widget consists of only one Tab by default. Drag and drop the required number of Tab widgets
into the TabPane widget.
3. Specify the Tab that must be displayed as the default open Tab by using the activeTabs property.
4. Specify the appearance of the TabPane (tab view, page view, etc.) using the viewType property.
You can customize the appearance of the TabPane widget by using the following properties:
l
widgetAlignment: Specifies the alignment of the widget.
margin: Defines the space around the widget.
activeSkin: Specifies the skin that must be applied to an active tab.
activeFocusSkin: Specifies the skin that must be applied to the Tab in focus.
inactiveSkin: Specifies the skin that must be applied to a Tab that is inactive.
TabPane features specific to Desktop Web Platform

For Desktop Web platform, tab widget accepts a Header Box that enables the developer to design the tab
header based on requirements. The Header Box is valid and applicable when the tab is in default and
collapsible view modes. A separate copy of the Header Box should be added to each of the tabs to which it is
assigned. The widgets inside the Header Box can be accessed in the same manner as the widgets inside the
tab widget. Kony Studio provides the ability to define Header Boxes for the tab widget by allowing the
developer to place any one or combination of the following widgets:
l
Label
Image
Link
Button
HBox
VBox
RichText
Events defined on individual widgets within the header template are respected and the focus skins as defined
by these widgets are applied. When clicked on any other area which does not have its own event, the tab's
onTabClick event is fired. The signature of every event raised by the widgets in the header will have the
following parameters tabID, tabPaneID, currentWidget.
Accessing widgets in a tabpane header
The widgets in the tab <form>.<tabpane>.<widgetID>
The widgets in the tab header will be accessed using <form><tabpane><tabid>.header.<widgetID>
header is a property of the individual tab widget.
TabPane widget has the following considerations:
l
The TabPane widget occupies 100% of the screen width.

o
You can navigate within the TabPane using only the down key.
If you press the down key, the focus shifts to the next widget in the TabPane.
If you press the down key while you are on the last widget in the TabPane, you are taken to the
top most widget in the TabPane.
If you press the right or the left arrow keys, you move to next or previous tabs.
Tab cycling is supported (i.e, if you are on the last tab and you press the right arrow, you move
to the first tab)
On devices which have a navigation key, the following are applicable:
Each Tab has a context menu. This menu is displayed in the menu options whenever the Tab is in
focus. The MenuItems must be placed on other Form specific MenuItems.
Tab remembers the control on which there was focus. For example, if control 2 of Tab2 is in focus, and
you navigate to Tab1, when you navigate back to Tab2, control 2 will be in focus and not the first item
in the Tab.
To avoid jumping effect on BlackBerry and J2ME, we suggest that you not to place lengthy textual
content above the tab bar while you switch the Tabs.
TabPane allows you to build the container with multiple tabs and each tab holding a different structure and
content. The TabPane widget provides you with an option to set Basic Properties, Layout Properties, Platform
Specific Properties, Events, and Methods. Deprecated properties are provided with their alternative properties
in the Deprecated section.
8.1 TabPane - Basic Properties

The basic properties for TabPane Widget are as follows:
l
activeFocusSkin
activeSkin
activeTabs
id
inactiveSkin
info
isVisible
retainPositionInTab
screenLevelWidget
viewConfig
viewType
8.1.1 activeFocusSkin
This is a skin property. This property specifies the skin that is to be applied when a TabPane is active and
focused.
Syntax
JavaScript: activeFocusSkin
Lua: activefocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for TabPane with activeFocusSkin:"aFSkin"
var tabBasic = {id:"tPane", info:{key:"TabPane"}, activeSkin:"aSkin", isVi
sible:true, activeFocusSkin:"aFSkin", selectedTabIndex:0, viewType:constan
ts.TABPANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true,
retainPositionInTab:true, needPageIndicator:true, inactiveSkin:"inActiveSk

in"};
var tabLayout ={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel:true, m
arginInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, contai
nerWeight:99};
var tabPSP={};
//Reading activeFocusSkin of the TabPane.
alert("TabPane activeFocusSkin is ::"+tabPane.activeFocusSkin);
Accessible from IDE

Yes
8.1.2 activeSkin
This is a skin property. Skin to be applied when a TabPane is active.
Syntax
JavaScript: activeSkin
Lua: activeskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for TabPane with activeSkin:"aSkin"
ts.TABPANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true, retainPositionInTab:
true, needPageIndicator:true, inactiveSkin:"inActiveSkin"};
var tabLayout ={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel:true,

inerWeight:70};
var tabPSP={};
//Reading activeSkin of the TabPane.
alert("TabPane activeSkin is ::"+tabPane.activeSkin);
Accessible from IDE

Yes
8.1.3 activeTabs
Indicates the selected Tabs indices. Index starts from 0. Specifies the Tab that must be displayed as the
default open Tab.
Default: 1 (Tab 1 will be displayed as the Active Tab)
If you want to set another Tab as Active Tab, select that Tab in the drop-down list. Multiple indices in
activeTabs is only appropriate for collapsible view currently. For all the remaining views,activeTabs always
respects only one selected item i.e first element in the array.
Syntax
JavaScript: activeTabs
Lua: activetabs
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for TabPane with activeTabs:[0,1,2,3,4]
sible:true, activeFocusSkin:"aFSkin", selectedTabIndex:0,
viewType:constants.TABPANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true, reta

inPositionInTab:true, needPageIndicator:true, inactiveSkin:"inActiveSkin",
activeTabs:[0,1,2,3,4]};
nerWeight:70};
var tabPSP={};
//Reading activeTabs of the TabPane.
alert("TabPane activeTabs is ::"+tabPane.activeTabs);
Accessible from IDE

Yes
8.1.4 id
id is a unique identifier of a TabPane consisting of alpha numeric characters. Every TabPane should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for TabPane with id:"tPane"
ts.TABPANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true,
retainPositionInTab:true, needPageIndicator:true, inactiveSkin:"inActiveSk

in"};
nerWeight:70};
var tabPSP={};
//Reading id of the TabPane.
alert("TabPane id is ::"+tabPane.id);
Accessible from IDE

Yes
8.1.5 inactiveSkin
Skin to be applied for all inactive tabs.
Syntax
JavaScript: inactiveSkin
Lua: inactiveskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for TabPane with inactiveSkin:"inActiveSkin"
var tabLayout ={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel:true,

inerWeight:70};
var tabPSP={};
//Reading inactiveSkin of the TabPane.
alert("TabPane inactiveSkin is ::"+tabPane.inactiveSkin);
Accessible from IDE

Yes
8.1.6 info
A custom JS Object with the key value pairs that a developer can use to store the context with the widget.
Note: This is a non-Constructor property. You cannot set this property through widget constructor. But
you can always read and write data to it.
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for TabPane with info property.
var tabBasic = {id:"tPane", activeSkin:"aSkin", isVisible:true, activeFocu
sSkin:"aFSkin", selectedTabIndex:0, viewType:constants.TABPANE_VIEW_TYPE_T
ABVIEW, screenLevelWidget:true, retainPositionInTab:true, needPageIndicato
r:true, inactiveSkin:"inActiveSkin"};
nerWeight:70};
var tabPSP={};
tabPane.info = {key:"TabPane"};
//Reading info of the TabPane.
alert("TabPane info is ::"+tabPane.info);
Accessible from IDE

No
8.1.7 isVisible
This property controls the visibility of the TabPane on the form.
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for TabPane with isVisible:true.
nerWeight:70};
var tabPSP={};
//Reading isVisible of the TabPane.
alert("TabPane isVisible is ::"+tabPane.isVisible);
Accessible from IDE

Yes
8.1.8 retainPositionInTab
Indicates whether each individual tab should retain its scroll position when the TabPanes are switched over.
Default:false
Syntax
JavaScript: retainPositionInTab
Lua: retainpositionintab
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for TabPane with retainPositionInTab:true.
nerWeight:70};
var tabPSP={};
Accessible from IDE

Yes
Available on all platforms except Windows Tablet and BlackBerry 10 platforms
Specifies whether the widget should occupy the whole container or not.
Note: You cannot place more than one TabPane as a screen level widget inside a form. Also, if you choose
to make a TabPane a Screen Level Widget, we recommend that you place only one TabPane in the form and
do not place any other widgets in the form.
Note: Do not set the screen level widget property to true for more than one widget in the form. If you have
multiple widgets with this property set as true, there may be issues with how information is displayed along
with some scrolling issues.
Default: false
If set to true, the widget occupies the whole container.
If set to false, the widget does not occupy the whole container.
Syntax
JavaScript: screenLevelWidget
Lua: screenlevelwidget
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for TabPane with screenLevelWidget:true.
var tabBasic = {id:"tPane",info:{key:"TabPane"},activeSkin:"aSkin", active
FocusSkin:"aFSkin", inactiveSkin:"inActiveSkin", viewType:constants.TABPAN
E_VIEW_TYPE_PANORAMAVIEW, viewConfig:{"panoramaTitle":"paranoma", "panoram
aTitleImage":"p.png", "panoramaImage":"par.png"}, screenLevelWidget:true,
isVisible:true, retainPositionInTab:true, needPageIndicator:true, selected
TabIndex:0};
inerWeight:70};
var tabPSP={};
//Reading screenLevelWidget of the TabPane.
alert("TabPane screenLevelWidget is ::"+tabPane.screenLevelWidget);
Accessible from IDE

Yes
Available on all platforms except Desktop Web, BlackBerry, and BlackBerry 10 platforms
8.1.10 viewConfig
The view configuration for different view types.
Below are the view configuration properties in Desktop Web and mobile channel platforms when the viewType
is set as
l
TABPANE_VIEW_TYPE_COLLAPSIBLEVIEW:It accepts JSObject with the below key-value pairs.

expandedImage:String value indicates the name of the image when the tab is
expanded.
collapsedImage:String value indicates the name of the image when the tab is
collapsed.
imagePosition: Specifies the position of the image on the tab. Following are the
available options:
l
TABPANE_COLLAPSIBLE_IMAGE_POSITION_LEFT
TABPANE_COLLAPSIBLE_IMAGE_POSITION_RIGHT
tabNameAlignment: Specifies the alignment to the text on the tab. Following
are the available options:
TABPANE_COLLAPSIBLE_TABNAME_ALIGNMENT_LEFT
TABPANE_COLLAPSIBLE_TABNAME_ALIGNMENT_RIGHT
toggleTabs: Boolean value indicates whether the content of a tab will still be
displayed if you click on some other tab.
TABPANE_VIEW_TYPE_PAGEVIEW:It accepts a JSObject with the below key-value pairs.

needPageIndicator - Boolean value indicates whether the page indicator required or not.
pageOnDotImage - Name of the image. Valid only if needPageIndicator is true.
pageOffDotImage - Name of the image. Valid only if needPageIndicator is true.
TABPANE_VIEW_TYPE_PANORAMAVIEW:It accepts a JSObject with the below key-value pairs.

panoramaTitle - String value indicates the title of the panorama.
panoramaTitleImage - String value indicates the name of the image to be displayed in
the title.
panoramaImage - String value indicates the name of the panorama image.
TABPANE_VIEW_TYPE_TABVIEW:It accepts JSObject with the below key-value pairs.

headerPosition:Specifies the position of the header.Following are the available
options:
l
TAB_HEADER_POSITION_TOP
TAB_HEADER_POSITION_BOTTOM
TAB_HEADER_POSITION_LEFT
TAB_HEADER_POSITION_RIGHT
headerContainerWeight: Specifies percentage of width to be allocated to the
header.
Type:Number
Default:50%
Syntax
Lua: viewconfig
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for TabPane with viewConfig:{"panoramaTitle":"pa
ranoma", "panoramaTitleImage":"p.png", "panoramaImage":"par.png"}
var tabBasic = {id:"tPane",info:{key:"TabPane"},activeSkin:"aSkin", active
FocusSkin:"aFSkin", inactiveSkin:"inActiveSkin", viewType:constants.TABPAN
E_VIEW_TYPE_PANORAMAVIEW, viewConfig:{"panoramaTitle":"panorama", "panoram
aTitleImage":"p.png", "panoramaImage":"par.png"}, screenLevelWidget:true,
isVisible:true, retainPositionInTab:true, needPageIndicator:true, selected
TabIndex:0};
inerWeight:70};
var tabPSP={};
Accessible from IDE

Yes
8.1.11 viewType
Specifies the view type the Tab Pane should display.
Default: TABPANE_VIEW_TYPE_TABVIEW
l
TABPANE_VIEW_TYPE_TABVIEW
TABPANE_VIEW_TYPE_COLLAPSIBLEVIEW
TABPANE_VIEW_TYPE_PAGEVIEW (supported on iOS, Android, and Desktop Web only)
TABPANE_VIEW_TYPE_PANORAMAVIEW (supported on Windows Phone only)
Note: Sections are supported only when the viewType is set as TABPANE_VIEW_TYPE_TABVIEW.
Note: TABPANE_VIEW_TYPE_PAGEVIEW is always screen level irrespective of weather the value for
screenLevelWidget property is set to true or false.
Syntax
JavaScript: viewType
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for TabPane with viewType:constants.TABPANE_VIEW_
TYPE_TABVIEW
var tabBasic = {id:"tPane", info:{key:"TabPane"}, activeSkin:"aSkin", acti
veFocusSkin:"aFSkin", inactiveSkin:"inActiveSkin", viewType:constants.TABP
ANE_VIEW_TYPE_TABVIEW ,screenLevelWidget:true, isVisible:true, retainPosit
ionInTab:true, needPageIndicator:true, selectedTabIndex:0};
arginInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT,contain
erWeight:99};
var tabPSP={};
//Reading viewType of the TabPane
alert("TabPane viewType is ::"+tabPane.viewType);
Accessible from IDE

Yes
8.2 TabPane - Layout Properties

The layout properties for TabPane Widget are as follows:
containerHeight
containerWeight
gridCell
layoutMeta
layoutType
margin
marginInPixel
padding
paddingInPixel
Note: When screenLevelWidget property is set to false, the TabPane widget occupies the child
widget/content height. When screenLevelWidget property is set to true, the below table is applicable:
View Type
TABPANE_VIEW_TYPE_TABVIEW
TABPANE_VIEW_TYPE_COLLAPSIBLEVIEW
TABPANE_VIEW_TYPE_PAGEVIEW
Windows
Phone
Windows
Tablet
Occupies form
height
Occupies
content height
Occupies
content height
Occupies
content height
Occupies form
height
Not Applicable
Occupies form
Not Applicable
height
Default: If not configured, the value may vary depending on the platforms.
TABPANE_VIEW_TYPE_PANORAMAVIEW
Windows
Kiosk
Not Applicable
Occupies
content height
Not Applicable
Not Applicable
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for TabPane with containerHeight : 100
var tabBasic = {id:"tPane", info:{key:"TabPane"}, activeSkin:"aSkin",
activeFocusSkin:"aFSkin", inactiveSkin:"inActiveSkin", viewType:constants.

TABPANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true, isVisible:true, retainP
ositionInTab:true, needPageIndicator:true, selectedTabIndex:0};
var tabLayout ={padding:[5,5,5,5], margin:[5,5,5,5],paddingInPixel:true, m
nerHeight:100, containerWeight:70, containerHeightReference: constants.CON
TAINER_HEIGHT_BY_DEVICE_REFERENCE};
var tabPSP={};
//Reading containerHeight of the TabPane
alert("TabPane containerHeight is ::"+tabPane.containerHeight);
Accessible form IDE

No
Available on all platforms except on all Server side Mobile Web and Windows Kiosk platforms.
on the below options when the viewType is set as TABPANE_VIEW_TYPE_PAGEVIEW or TABPANE_
VIEW_TYPE_PAGEVIEW or TABPANE_VIEW_TYPE_COLLAPSIBLEVIEW.
Default: constants.CONTAINER_HEIGHT_BY_FORM_REFERENCE
l
constants.CONTAINER_HEIGHT_BY_FORM_REFERENCE: The TabPane height is calculated

based on the height of the Form excluding headers and footers. This property doesn't have any effect if
the scrollbox is placed inside a popup or headers/footers.
constants.CONTAINER_HEIGHT_BY_PARENT_WIDTH: Use this option if the TabPane is placed

inside a Box. The width is calculated based on the width of the Box.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for TabPane with containerHeightReference: const
ants.CONTAINER_HEIGHT_BY_DEVICE_REFERENCE
ANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true, isVisible:true, retainPosit
nerHeight:100, containerWeight:70, containerHeightReference: constants.CON
TAINER_HEIGHT_BY_DEVICE_REFERENCE};
var tabPSP={};
//Reading containerHeight of the TabPane
alert("TabPane containerHeight is ::"+tabPane.containerHeight);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and Windows Kiosk platforms.
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for TabPane with containerWeight : 70
nerWeight:70};
var tabPSP={};
//Reading containerWeight of the TabPane
alert("TabPane containerWeight is ::"+tabPane.containerWeight);
Accessible from IDE

Yes
8.2.4 gridCell
applied.
are as follows:
l
GridLayout.
Syntax
Lua: gridCell
Type
Lua:table
Read / Write
JavaScript Example
//Defining the properties for TabPane with gridCell.
ANE_VIEW_TYPE_TABVIEW, screenLevelWidget:true, isVisible:true,retainPositi
onInTab:true, needPageIndicator:true, selectedTabIndex:0};
inerWeight:70}, layoutType: constants.CONTAINER_LAYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}, gridCell:{"colSpan":1, "rowSpan":1, "rowNo":1, "colNo":1}};
var tabPSP={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
8.2.5 layoutMeta

Syntax
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for TabPane with layoutMeta.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var tabPSP={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
8.2.6 layoutType
l
platforms.
Apply GridLayout.
Syntax
Lua: layouttype
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for TabPane with layoutType:CONTAINER_LAYOUT_GRI
D.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var tabPSP={};
//Reading margin of the TabPane
alert("TabPane margin is ::"+tabPane.margin);
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
8.2.7 margin
between the widget and the next element. Array format [left, top, right, bottom] ex: [10,10,10,10].
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for TabPane with margin : [5,5,5,5]
inerWeight:70};
var tabPSP={};
//Reading margin of the TabPane
alert("TabPane margin is ::"+tabPane.margin);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic) and BlackBerry 10 platforms
8.2.8 marginInPixel
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for TabPane with marginInPixel : true
inerWeight:99};
var tabPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
8.2.9 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for TabPane with padding :[5,5,5,5]
inerWeight:99};
var tabPSP={};
//Reading padding of the TabPane
alert("TabPane padding is ::"+tabPane.padding);
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for TabPane with paddingInPixel : true
var tabBasic = {id:"tPane", activeSkin:"aSkin", activeFocusSkin:"aFSkin",
inactiveSkin:"inActiveSkin", viewType:constants.TABPANE_VIEW_TYPE_TABVIEW,
screenLevelWidget:true, isVisible:true, retainPositionInTab:true, needPage
Indicator:true, selectedTabIndex:0};
inerWeight:99};
var tabPSP={};

Accessible from IDE

Yes
l
iPhone
iPad
8.3 TabPane - Platform Specific Properties

The platform specific properties for TabPane Widget are as follows:
l
pageSkin
tabHeaderTemplate
tabHeaderHeight
8.3.1 pageSkin
Specifies the skin for page indicator. This property is applicable only when viewType is set as TABPANE_
VIEW_TYPE_PAGEVIEW and images are selected for pageOnDotImage and pageOffDotImage.
Default: Skin Defaults (blue color strip is applied for the page indicator)
Syntax
JavaScript: pageSkin
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for TabPane with pageSkin:"pskin".
inactiveSkin:"inActiveSkin", viewType:constants.TABPANE_VIEW_TYPE_PAGEVIEW,
Indicator:true, selectedTabIndex:0, viewConfig:{pageOnDotImage:"buleimg",
pageOffDotImage:"redimg"}};
inerWeight:70};
var tabPSP={progressIndicatorColor:constants.PROGRESS_INDICATOR_COLOR_GREY,
pageSkin:"pskin"};
Accessible from IDE

Yes
l
iPhone
iPad
Specifies the color of the progress indicator as white or grey.
Default: PROGRESS_INDICATOR_COLOR_WHITE
l
PROGRESS_INDICATOR_COLOR_WHITE: The progress indicator is white in color.
PROGRESS_INDICATOR_COLOR_GREY: The progress indicator is grey in color.
Syntax
JavaScript: progressIndicatorColor
Lua: progressindicatorcolor
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for TabPane with progressIndicatorColor : consta
nts.PROGRESS_INDICATOR_COLOR_GREY.
inerWeight:70};
var tabPSP={progressIndicatorColor:constants.PROGRESS_INDICATOR_COLOR_
GREY};
Accessible from IDE

Yes
l
iPhone
iPad
Specifies if the progress indicator must be displayed.
Default: true
If set to false, the progress indicator is not displayed on the widget.
If set to true, the progress indicator is displayed on the widget.
Syntax
JavaScript: showProgressIndicator
Lua: showprogressindicator
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for TabPane with showProgressIndicator : true
ANE_VIEW_TYPE_TABVIEW , screenLevelWidget:true, isVisible:true, retainPosi
tionInTab:true, needPageIndicator:true, selectedTabIndex:0};
inerWeight:70};
var tabPSP={showProgressIndicator:true};
Accessible from IDE

Yes
l
iPhone
iPad
8.3.4 tabHeaderTemplate
Accepts reference to a box widget which represents a UI template for a custom tab header. The box template
is allowed to have only Label, Link, Richtext, Button and Image widgets.
Syntax
JavaScript: tabHeaderTemplate
Lua: tabHeaderTemplate
Type
JavaScript: kony.ui.Box
Lua: UserData
Read / Write
Accessible from IDE

Yes
Available on Desktop Web
8.3.5 tabHeaderHeight
Specifies the height of the Tab header in pixels.
Default: 64
Note: This property is applicable only when the viewType is set as TABPANE_VIEW_TYPE_TABVIEW.
Syntax
JavaScript:tabHeaderHeight
Lua:tabHeaderHeight
Type
JavaScript: Number
Lua: Number
Read / Write
Yes
JavaScript Example
//Defining the properties for TabPane with tabHeaderHeight: 64
inerWeight:70};
var tabPSP={tabHeaderHeight:64};
Accessible from IDE

Yes
This property is available on Android/Android Tablet platform.
8.4 TabPane - Events

TabPane has the following events associated with it:
l
onTabClick
preOnclickJS
postOnclickJS
8.4.1 onTabClick
Event callback invoked when the tab is clicked. This event is triggered when you expand or collapse any Tab.
Syntax
JavaScript: onTabClick(tabPane, tabIndex)
Lua: ontabclick(tabpane, tabindex)
Input Parameters
tabpane [String] - Mandatory
Reference to the TabPane widget that raised the event.
tabIndex [Number] - Mandatory
Specifies the Index number of a tab in the tabPane.
Read / Write
JavaScript Example
//The below is the callback for onTabClick event.
function onTabClick(tabpane, tabIndex)
{
/* Write your logic here*/
}
var tabBasic = {id:"tPane",info:{key:"TabPane"}, activeSkin:"aSkin",
activeFocusSkin:"aFSkin", inactiveSkin:"inActiveSkin", viewType:constants.

TABPANE_VIEW_TYPE_TABVIEW , screenLevelWidget:true, isVisible:true, retain
PositionInTab:true, needPageIndicator:true, selectedTabIndex:0, onTabClick
:onTabClick};
inerWeight:99};
var tabPSP={};
Accessible from IDE

Yes
8.4.2 preOnclickJS
This event allows the developer to execute custom JavaScript function before the onTabClick callback of the
TabPane is invoked. This is applicable only for Mobile Web channel. The function must exist in a JavaScript
file under project>module>js folder.
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the callback for preOnclickJS event
function mypreOnclickJS (tab)
{
/*Write your logic here*/
}

inerWeight:99};
var tabPSP={preOnclickJS : mypreOnclickJS};
Accessible from IDE

Yes
8.4.3 postOnclickJS
This event allows the developer to execute custom JavaScript function after the onTabClick callback of the
TabPane is invoked. This is applicable only for Mobile Web channel.The function must exist in a JavaScript
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the callback for postOnclickJS event
function mypostOnclickJS (tab)
{
}
inerWeight:99};
var tabPSP={postOnclickJS : mypostOnclickJS};

Accessible from IDE

Yes
8.5 TabPane - Methods

This section describes the methods associated with the TabPane widget. You can use these methods across
all platforms.
l
addTab
addTab (applicable only on Desktop Web platform)
addTabAt
removeTabAt
removeTabByld
8.5.1 addTab
This method is used to add a tab to the TabPane widget.
Signature
JavaScript: addTab(tabId, tabName, tabImage, box, masterDataLoad)
Lua: tabpane.addtab(tabpaneid, tabid, tabname, tabimage, box, masterdataload)
Input Parameters
tabId [String] - Mandatory
Specifies the id of the tab.
tabName [String] - Mandatory
Specifies the name of the tab.
tabImage [String] - Mandatory
Specifies the image of the tab.
box [Array] - Mandatory
Represents the layout and the widgets inside the tab
tabpaneid [widgetref]- Mandatory
masterDataLoad
Deprecated. Works only for backward compatibility.
Return Values
None
JavaScript Example
inactiveSkin:"inActiveSkin", viewType:constants.TABPANE_VIEW_TYPE_TABVIEW ,
inerWeight:99};
var tabPSP={};
//addTab method call
tabPane.addTab("tPane","LocTAB","app.png", box1, masterDataLoad:{}); //ima
ge should already be made available.
Error Codes
None
8.5.2 addTab
This method is applicable only on Desktop Web platform. It is an overloaded method used to add a tab to the
TabPane widget. This method accepts headerbox template that is to be displayed as part of tab both in default
and collapsible mode.
For example, form1.tabpane1.tab1.header.widget1 is one of the widgets inside the tab header template.
Signature
JavaScript: addTab(tabId, box, headerBox)
Input Parameters
box [Array] - Mandatory
Represents the layout and the widgets inside the tab.
headerBox[widgetref]- Mandatory
Return Values
None
Error Codes
None
Available only on Desktop Web platform
8.5.3 addTabAt
This method is used to add a tab at the specified index to the TabPane. The new tab is placed before the
specified index.
If the row Index mentioned is greater than "N", then row is added at the end of the tabpane ui and if it is less
than zero, it will be added at the beginning of the TabPane.
Signature
JavaScript: addTabAt(tabId, tabName, tabImage, box, index)
Lua: tabpane.addtabat(tabpaneid, tabname, tabimage, box, index)
Input Parameters
tabId
tabName
Specifies the name of the tab.
tabImage
Specifies the image of the tab.
box
Specifies the reference of the box.
tabpaneid [widgetref]- Mandatory
Return Values
None
JavaScript Example
var tabPaneBasic = {id:"tPane", activeSkin:"aSkin",activeFocusSkin:"aFSki
n", inactiveSkin:"inActiveSkin", viewType:constants.TABPANE_VIEW_TYPE_TABV
IEW , screenLevelWidget:true, isVisible:true,retainPositionInTab:true, nee
dPageIndicator:true, selectedTabIndex:0};
var tabPaneLayout ={padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:tr
ue, marginInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, c
ontainerWeight:99};
var tabPanePSP={};
var tabPane = new kony.ui.TabPane(tabPaneBasic, tabPaneLayout, tabPanePSP);
//Defining the properties for Tab

var tabBasicConfig = {"id": "tabNew", "tabName": "TabDynamic","spacing":
1, "widgetDirection": 1,"isVisible": true,"orientation": constants.BOX_LAY
OUT_VERTICAL }
var tabLayoutConfig = {"margin": [0, 0, 0, 0],"padding": [0, 0, 0, 0],"m
arginInPixel": false,"paddingInPixel": false,"containerWeight": 93,"layout
Type": constants.CONTAINER_LAYOUT_BOX}
var tabPspConfig =
{"image": null }
//Creating the Tab

var tabNew = new kony.ui.Box(tabBasicConfig,tabLayoutConfig,tabPspConfig)
//addTabAt method call
tabPane.addTabAt("tabNew","TabDynamic", "TabImage.png",tabNew ,0);
should already be made available.
//image
Error Codes
None
8.5.4 removeTabAt
This method is used to remove a tab based on the index on the TabPane.
Signature
JavaScript: removeTabAt(index)
Lua: tabpane.removetabat(tabpaneid, index)
Input Parameters
Index represents the tabindex in the order in which the tab originally was added. Index is zero based
in JavaScript and one based on Lua. It should be less than "N", where "N" is the number of existing
tabs with in the tab. If the index is not within the limits then removeTabAt will be silent and doesn't
yield any results.
An active tab (currently selected tab) can be removed. If an active Tab is removed, then the first
index in activeTabs property will be selected/focused. If active Tabs has only one element, or view
doesn't have more than one active tab, then if the active tab is closed, the 0th position will be
selected by default.
tabpaneid [widgetref] - Mandatory
Return Values
None
JavaScript Example
inerWeight:99};
var tabPSP={};
//removeTabAt method call.
tabPane.removeTabAt(2);
Error Codes
None
8.5.5 removeTabByld
This method is used to remove a tab based on the tabid on the TabPane.
Signature
JavaScript: removeTabByld(tabld)
Lua: tabpane.removetabbyid(tabpaneid, tabld)
Input Parameters
An active tab (currently selected tab) can be removed. If an active Tab is removed, then the first
index in activeTabs property will be selected/focused. If active Tabs has only one element, or view
doesn't have more than one active tab, then if the active tab is closed, the 0th position will be
selected by default.
tabpaneid [widgetref] - Mandatory
Return Values
None
JavaScript Example
inerWeight:99};
var tabPSP={};
//removeTabById method call.
tabPane.removeTabById("tPane")
Error Codes
None
8.6 Tab header - Templates

Note: Tab header templates are supported only on Desktop Web platform.
8.6.1 What is a Template for tabHeader and where to use it

Tab header template enables you to define a template for tab headers with specified widgets. You can use the
template on individual tab headers of a Tab pane. This is primarily useful for developers to achieve common
look and feel of the tab headers of a Tab Pane widget.
Tab header templates are used in the following cases:
l
To have uniform look and feel of the tab headers with the specified widgets.
To display different tab headers for different Tab panes.
To perform an action on a tab header.
8.6.2 Creating a Template for tabHeader

When you want information to be displayed or customized in a tab header of a Tab pane in the application, you
have a provision to add a tab headers template using Kony Studio. For more information about tab headers
templates refer Kony Studio User Guide.
To create a TabHeader template at the application-level, follow these steps:
2. Expand the application for which you want to create the TabHeader template.
3. Navigate to templates > tabheaders, right-click desktop and select New TabHeader Template. The
Create a New TabHeader window appears.
iii. Drag and drop an HBox and a VBox onto the Form.
Note: Only HBox and VBox are supported on the form. You can add other widgets
within these widgets.
iv. Drag and drop the required widgets onto the HBox/VBox. Set the properties of these
widgets. For more information, see Kony Widget User Guide.
v. A TabHeader template is created.
8.6.3 Using tabHeader Template

You can define only one template for each map using the above process.
To use TabHeader template in an application, follow these steps:
2. Expand the application for which you want to use section template.
3. Navigate to forms > desktop , right-click and select New Form. The Create a New Form window
appears.
4. Enter a name for the Form and click Finish. A new Form is created.
5. Drag-drop a TabPane and add Tabs to it as required. Click Save.
6. To set the template to a Tab, select the Tab and go to Properties window.
7. Select tabHeaderTemplate and Select/Search map Template window opens. Select the template,
which you want to set to the Tab.
8. Click OK.
9. Popup
Popup is a visual component that displays content on top of existing content, within the bounds of the
application window.
Generally a popup is displayed in the center of the screen on top of the Form from which you have invoked the
popup. It does not span the entire screen width.Popups allow you to partition UI design into smaller parts.
Popup provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
Events and Methods.
Platform Specific
Properties
Basic Properties
Layout Properties
footers
headers
id
info
isModal
skin
title
transparencyBehindThePopup
containerHeight
containerWeight
gridCell
layoutMeta
layoutType
padding
paddingInPixel
Events
Methods
Deprecated
addWidgets
add
addAt
destroy
dismiss
navigateTo
remove
removeAt
scrollToBeginning
scrollToEnd
scrollToWidget
setContext
closureLeftSideView
dockableAppMenu
imageLeftSideView
imageRightSideView
nift
onOrientationChange
orientationmode
renderTitleText
Reset Focus to top of the Form
Skin Around Popup
titleBar
init
onHide
onDeviceBack
onLoadJS
unLoadJS
bounces
captureGPS
contextPath
configureExtendTop
draggable
extendTop
footerOverlap
headerOverlap
inTransitionConfig
layout
minimizeOnLostFocus
noCache
outTransitionConfig
popupStyle
resizable
secureData
showMiniAppMenu
submitSecure
titleBarConfig
viewConfig
windowSoftInputMode
Events
Methods
Deprecated
setTitleBarRightSideButtonSkin titleBarLeftSideView
setTitleBarSkin
showTitleBar
hideTitleBar
show
widgets
Creating a Popup using a constructor: kony.ui.popup

var popup = new kony.ui.Popup(basicConf, layoutConf, pspConf)
they are ignored.
JavaScript Example
//Defining properties for a Popup.
var popBasic ={id:"popUp", title:"PopUP", skin:"popSkin", headers:[box1,bo
x2], Footers:[box3,box4], isModal:true, transparencyBehindThePopup:80};
var popLayout ={containerWeight:100,padding:[5,5,5,5]};
var popPSP ={footerOverlap:true, captureGPS:true, windowSoftInputMode:cons
tants.POPUP_ADJUST_RESIZE};
//Creating the popup.
var popUp=new kony.ui.Popup(popBasic, popLayout, popPSP);
//Reading the transparencyBehindThePopup of the popUp
alert("PopUp transparencyBehindThePopup ::"+PopUp.transparencyBehindThePop
up );
Note: Before you place a widget in a Popup that exceeds the Popup width, ensure that you set the Popup
width manually using the containerWeight property for a Popup. IDE representation for continerWeight is
Size (Width). For example if you select the viewType property as CALENDAR_VIEW_TYPE_ GRID_
ONSCREEN for a Calender placed within a Popup, ensure you set the Popup width to a minimum of 90%
otherwise the Calendar does not appear completely within the popup.
Note: Display orientation (LANDSCAPE, PORTRAIT) of the popup always follows the orientation of the
current form and also the on orientation change event gets called only on the current form and there is no
orientation change event at the popup level.
For information about how you can add a Popup to an Application, see the Section Adding Popups to an
Application in the Kony Studio User Guide.
Behavior
A Popup goes through the following states:
1. Creation (Adding a popup to an application)
2. Initialization
3. Destroy (using destroy)
After a Popup is created , you can initialize the Popup using one of the following:
l
show
Accessing one of the popup widgets
//For example, if you want to access an HBox with ID HBox1 which is in a P

opup whose ID is pop1, enter the following:
local var = pop1.HBox1.id
alert ("HBox id is :");
alert (var);
Behavior on Mobile Web

The behavior of Popups on Mobile Web Advanced, BJS, and Basic is as follows:
Advanced
l
In all Advanced versions of Mobile Web, the Popups appear on the screen where the popup has been
invoked using show.
By default, all Popups are in full screen mode. The Popups are not positioned based on the widget
context.
Fixed headers and footers are not supported in BB NTH devices. The header / footer (for a popup) are
always docked to the top / bottom of the browser and should not be used unless otherwise the popup
has large content.
BJS and Basic

l
Popups are displayed as a separate page on a new screen.
9.1 Popup - Basic Properties

The basic properties for Popup Widget are as follows:
l
footers
headers
id
info
isModal
skin
title
transparencyBehindThePopup
9.1.1 footers
A footer is a section of the Popup that is docked at the bottom of the Popup (does not scroll along with the
content of the Popup). It accepts an array of kony.ui.Box object references with horizontal orientation that are
added as footer docked at the bottom of the Popup. These footers can be reused across forms.
Syntax
JavaScript: footers
Lua: footers
Type
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a Popup with Footers:[box3,box4], where box3 and
box4 are boxes and these boxes should be created and made available for ac
cess.
x2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:100};
var popLayout ={containerWeight:100, padding:[5,5,5,5]};
var popPSP ={};
//Creating the Popup.
Accessible from IDE

Yes
9.1.2 headers
A header is a section of the Popup that is docked at the top of the Popup (does not scroll along with the
content of the Popup). It accepts an array of kony.ui.Box object references with horizontal orientation that are
added as header docked at the top of the Popup. These headers can be reused across Popups.
Syntax
JavaScript: headers
Lua: headers
Type
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a Popup with headers:[box1,box2],Where box1 and
box2 are boxes and these boxes should be created and made available for ac
cess.
var popPSP ={};
Accessible from IDE

Yes
9.1.3 id
id is a unique identifier of Popup consisting of alpha numeric characters. Every Popup should have a unique id
within an application.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
No
JavaScript Example
//Defining properties for a Popup with id:"popUp1"
var popBasic ={id:"popUp1", title:"PopUP",skin:"popSkin", headers:[box1,bo
var popPSP ={};
var popUp1=new kony.ui.Popup(popBasic, popLayout, popPSP);
Accessible from IDE

Yes
9.1.4 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a Popup with info property.
var popPSP ={};
popUp.info = {key:"text of popup"};
//Reading the info of the popUp.
alert("popUp info is ::"+popUp.info);
Accessible from IDE

No
9.1.5 isModal
In user interface design, a modal window, which is a child window that requires users to interact with it before
they can return to operating the parent application, thus preventing the workflow on the application main
window.
This property indicates whether the popup is to be shown as modal window or a non-modal window.
Default: false
If set to true, the popup is shown as modal window.
If set to false, the popup is shown as non-modal window.
Syntax
JavaScript: isModal
Lua: ismodal
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining properties for a Popup with isModal:true
var popBasic ={id:"popUp", title:"PopUP",skin:"popSkin", headers:[box1,box
2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:100};
var popPSP ={};
//Reading the isModal of the popUp
alert("popUp isModal::"+popUp.isModal);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and BlackBerry 10 platforms
9.1.6 skin
Specifies a background skin for Popup.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a Popup with skin:"popSkin", skin should be crea
ted with the same name through IDE or handcode.
var popPSP ={};
//Reading the skin of the popUp
alert("popUp skin::"+popUp.skin);
Accessible from IDE

Yes
9.1.7 title
Specifies a general or descriptive text that will be shown as the title for the Popup.
Note: For Desktop Web platform, the title is displayed on the browser window.
Syntax
JavaScript: title
Lua: title
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a Popup with title:"PopUP Title"
var popBasic ={id:"popUp", title:"PopUP Title", skin:"popSkin", headers:[b
ox1,box2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:1
00};
var popPSP ={};
//Reading the title of the popUp
alert("popUp title::"+popUp.title);
Accessible from IDE

Yes
Available on all platforms except SPA platform
9.1.8 transparencyBehindThePopup
Indicates the transparency to be used behind the popup, default is 100% transparent. This can be used to
have dim effect behind the popup when a popup is shown.
Syntax
JavaScript: transparencyBehindThePopup
Lua: transparencybehindthepopup
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a Popup with transparencyBehindThePopup:80
2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:80};
var popPSP ={};

//Reading the transparencyBehindThePopup of the popUp.
alert("popUp transparencyBehindThePopup ::"+popUp.transparencyBehindThePop
up);
Accessible from IDE

Yes
9.2 Popup - Layout Properties

The layout properties for Popup Widget are as follows:
l
containerHeight
containerWeight
gridCell
layoutMeta
layoutType
padding
paddingInPixel
Note: In Windows platforms, popup occupies the child widget/content height.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining properties for a Popup with containerHeight:80
var popLayout ={containerHeight:80,padding:[5,5,5,5]};
var popPSP ={};
//Reading the containerHeight of the popUp
alert("popUp containerHeight::"+popUp.containerHeight);
Accessible form IDE

No
Available on all platforms except on all Server side Mobile Web and Desktop Web
on the following options:
l
CONTAINER_HEIGHT_BY_FORM_REFERENCE: The Popup height is calculated based on the

height of the Form excluding headers and footers. This property doesn't have any effect if the scrollbox
is placed inside a popup or headers/footers.
CONTAINER_HEIGHT_BY_PARENT_WIDTH: Use this option if the Popup is placed inside a Box.

The width is calculated based on the width of the Box.
CONTAINER_HEIGHT_BY_DEVICE_REFERENCE: Specifies the height of the popup as that of the

height of the device/screen height.
Note: To set the value through code, prefix the option with constants. such as constants.<option>.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Popup with containerHeightReference: constan
ts.CONTAINER_HEIGHT_BY_DEVICE_REFERENCE
var popLayout ={containerHeight:80,padding:[5,5,5,5], containerHeightRefer
ence: constants.CONTAINER_HEIGHT_BY_DEVICE_REFERENCE};
var popPSP ={};
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and Desktop Web
Specifies percentage of width to be occupied by the Popup with respect to its parent form width.
Syntax
Type
Read / Write
JavaScript Example
//Defining properties for a Popup with containerWeight:80
var popPSP ={};
//Reading the containerWeight of the popUp
alert("popUp containerWeight::"+popUp.containerWeight);
Accessible from IDE

Yes
9.2.4 gridCell
applied.
are as follows:
l
GridLayout.
Syntax
Lua: gridCell
Type
Lua:table
Read / Write
JavaScript Example
//Defining properties for a Popup with gridCell.
var popLayout ={containerWeight:80,padding:[5,5,5,5], layoutType: constant
s.CONTAINER_LAYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
var popPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
9.2.5 layoutMeta
Syntax
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Popup with layoutMeta.
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
var popPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
9.2.6 layoutType
l
platforms.
Apply GridLayout.
Syntax
Lua: layouttype
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a Popup with layoutType:CONTAINER_LAYOUT_GRID.
var popBasic ={id:"popUp", title:"PopUP", skin:"popSkin", headers:
[box1,box2], footers:[box3,box4], isModal:true, transparencyBehindThePopup

:100};
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}, gridCell:{"colSpan":1, "rowSpan":1, "rowNo":1, "colNo":1} };
var popPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
9.2.7 padding
Note: Due to Browser restrictions, you cannot apply padding for a ComboBox, Form and ListBox widgets on
Mobile Web platform. Padding is not supported by Windows Mobile browser for Box and Image Gallery.
Note: If no skin is applied to a Button, then padding is not supported on iPhone. This is due to iOS Safari
Syntax
JavaScript: padding
Lua: padding
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Popup with padding:[5,5,5,5]
x2], footers:[box3,box4], isModal:true, transparencyBehindThePopup :100};
var popPSP ={};
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with padding in pixels.
x2], footers:[box3,box4], isModal:true, transparencyBehindThePopup :100};
var popLayout ={containerWeight:100, padding:[5,5,5,5], paddingInPixel: tr
ue};
var popPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
9.3 Popup - Platform Specific Properties

The platform specific properties for Popup Widget are as follows:
l
bounces
captureGPS
contextPath
configureExtendTop
draggable
extendTop
footerOverlap
headerOverlap
inTransitionConfig
layout
minimizeOnLostFocus
noCache
outTransitionConfig
popupStyle
resizable
secureData
showMiniAppMenu
submitSecure
titleBarConfig
viewConfig
windowSoftInputMode
9.3.1 bounces
Default:true
Syntax
JavaScript: bounces
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining properties for a Popup with bounces:true
var popBasic ={id:"popUp", title:"PopUP", skin:"popSkin", isModal:true};
var popPSP ={bounces:true};
Accessible from IDE

Yes
l
iPhone
iPad
9.3.2 captureGPS
Specifies if the Popup must display a dialog seeking permission from the user to access the location details.
Note: For this property to work, you must have selected Requires GPS functionality in the Project
Properties of the Application (For more information, see the Configuring Project Properties section of the
Kony Studio User Guide) to enable the application to use the GPS functionality.
Default: false
If set to true, the dialog appears when you navigate to the specified Popup.
If set to false, the dialog does not appear when you navigate to the specified Popup.
set the value to true (select the checkbox).
The following image illustrates the popup to access the location details:
Syntax
JavaScript: captureGPS
Lua: captureGPS
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with captureGPS:true
var popPSP ={captureGPS:true};
Accessible from IDE

Yes
Available on Server side Mobile Web (advanced) platform only
9.3.3 contextPath
Specifies the context path to be displayed in the address field of the browser. For more information about
specifying a context path, refer the Kony Studio Users Guide.
Default: empty
Note: This field is only populated when you specify a Context ID and a corresponding Context Path in the
Site Minder tab under Mobile web in the Project properties window.
Syntax
JavaScript: contextPath
Lua: contextpath
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for a Popup with contextPath:"https://www.xyz.com"
var popPSP ={contextPath:"https://www.xyz.com"};
Accessible from IDE

Yes
l
This property enables you to configure extendTop property.
Default:false
If set to true, the property extendTop is displayed.
If set to false, the property extendTop is not displayed.
Syntax
Read / Write
No
Accessible from IDE

Yes
l
iPhone
iPad
9.3.5 draggable
Specifies the weather the popup can be dragged across the browser screen.
Default: false
If set to true, the popup window can be dragged.
if set to false, the popup window cannot be dragged.
Syntax
JavaScript: draggable
Type
JavaScript:Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with draggable:true.
var popPSP ={draggable:true};
Accessible from IDE

Yes
This property is available on Desktop Web platform.
9.3.6 extendTop
Specifies the popup content to scroll under the App Menu. This property is supported in iOS7 and above only.
This property is also applicable on the Application Level properties under Application Properties > Native
>iPhone/iPad > Platform Settings. The property set at popup level takes precedence over Application level.
Default:false
If set to true, the popup scroll under the App Menu.
Note: This property is applicable on popup level headers and footers, app level headers and footers, title bar,
and app menu.
Syntax
JavaScript: extendTop
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining a popup with extendTop:true
var popPSP ={extendTop:true};
Accessible from IDE

Yes
l
iPhone
iPad
9.3.7 footerOverlap
Specifies if the footer must overlaps the Popup. For example, every time you scroll the Popup, the footer is
fixed and the footer overlaps the Popup as specified in the Footer Overlap field. If this field is selected, the
Popup scrolls behind the footer background and a part of the footer background is transparent.
Default: false
Syntax
JavaScript: footerOverlap
Lua: footeroverlap
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with footerOverlap:true
var popPSP ={footerOverlap:true};
Accessible from IDE

Yes
l
iPhone
iPad
9.3.8 headerOverlap
Specifies if the header must overlaps the Popup. For example, every time you scroll the Popup, the header is
fixed and the header overlaps the Popup as specified in the header overlap field. If this field is selected, the
Popup scrolls behind the header background and a part of the header background is transparent.
Default: false
Syntax
JavaScript: headerOverlap
Lua: headeroverlap
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with headerOverlap:true
var popPSP ={headerOverlap:true};
Accessible from IDE

Yes
l
iPhone
iPad
When building iPhone applications that support or provide text input, it's often necessary to create some extra
buttons (or other controls) beyond the ones provided by the default keyboard interface. Kony Platform by
default, adds the Previous, Next and Done buttons to the applicable input controls. These buttons allow
specific operations needed by your application, such as moving to the next or previous text field, make the
keyboard disappear. The area above the keyboard is known as Input Accessory View.
This property, allows you to specify the type of accessory view that will be shown for all the input controls on
this Popup.
Note: The Input Accessory View Type defined in the form level takes precedence over the Input Accessory
View Type defined in application level settings.
You can select one of the following view types:
Default: FORM_INPUTACCESSORYVIEW_DEFAULT
l
FORM_INPUTACCESSORYVIEW_NONE: Use this option if you do not want to specify the toolbar.
This option should be used carefully, as setting this option for widgets like calendar leaves the user
with no option to select and drop-down a wheel calendar.
FORM_INPUTACCESSORYVIEW_DEFAULT: Specifies that the toolbar that is defined in the

Application level settings. To set the Application level settings, right-click on the project and navigate
to Properties> Native App>iPhone/iPad.
FORM_INPUTACCESSORYVIEW_NEXTPREV: Specifies the navigation options as Next,

Previous, and Done for a popup. The below image illustrates the nextprevtoolbar set for a Textbox. The
highlighted toolbar is achieved by setting the Keyboard Type as Default for a Textbox and Input
Accessory View Type as nextprevtoolbar to the popup.
FORM_INPUTACCESSORYVIEW_CANCEL: Specifies that the input accessory view has a cancel

button. This option does not trigger any events. Specifies that the input accessory view has a cancel
button. This option does not trigger any events.
Note: This option (none) should be used carefully, as setting this option for widgets like calendar leaves the
user with no option to select and drop-down a wheel calendar.
Syntax
JavaScript: inputAccessoryViewType
Lua: inputaccessoryviewtype
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a Popup with inputAccessoryViewType as nextprevt
oolbar
var popPSP ={inputAccessoryViewType:constants.nextprevtoolbar};
Accessible from IDE

Yes
l
iPhone
iPad
Specifies the configuration to be used when the user arrives on this form. It accepts hash values.
transitionDirection: Specifies the direction from which the popup is displayed. The available options are:
2. fromRight - Specifies that the popup must appear from the right.
3. fromLeft - Specifies that the popup must appear from the left.
4. fromBottom - Specifies that the popup must appear from the bottom.
5. fromTop - Specifies that the popup must appear from the top.
transitionEffect: Specifies the effect from which the popup is displayed. The available options are:
2. transitionMoveIn - Specifies that the popup must slide over the existing content in the direction as
3. transitionPush - Specifies that the popup must push the existing content in the direction as specified in
4. transitionReveal - Specifies that the popup must be revealed gradually in the direction as specified in
the transitionDirection.
applied.
2. bottom-top - The constant value is 1. Specifies that the popup must slide-in from the bottom and
3. from left - The constant value is 2. Specifies that the popup must slide-in from the left with a fade
effect.
4. from right- The constant value is 3. Specifies that the popup must slide-in from the right with a fade
effect.
5. to right- The constant value is 4. Specifies that the popup must slide-out to the right with a fade effect.
6. to left- The constant value is 5. Specifies that the popup must slide-out to the left with a fade effect.
7. from center- The constant value is 6. Specifies that the popup must grow from the center with a fade
effect.
8. topright-bottom - The constant value is 7. Specifies that the popup must slide-in from the top-right
9. bottomleft-top - The constant value is 8. Specifies that the popup must slide-in from the bottom-left
10. bottom-top style1 - The constant value is 9. Specifies that the popup must shrink from the bottom
towards the top.
11. top down - The constant value is 10. Specifies that the popup must slide-in from the top and proceed
towards the bottom.
//sample code to set inTransitionConfig with the option bottom-top.

popup1.inTransitionConfig= {popupAnimation: 1 };

transitionMode: Specifies the direction from which the form is displayed. The available options are:
1. Default(none)- The default device effect is applied or none of the effect is applied.
2. Sequential- The transition of the popup going out of the view completes first and then the transition of
the popup coming into the view takes place.
3. Parallel- The transition of the popup going out of the view and the transition of the popup coming into
the view takes place simultaneously.
inTransition: Specifies the effect from which the popup is displayed. The available options are:
1. Default(none)- Specifies that the popup must slide horizontally into the view.
2. Rotate3DSingle - Specifies that the popup must be rotated along the center Y-Axis when coming into
the view.
3. Rotate3DDual - Specifies that the popup must be shown making a circle around the screen from the
4. Slide - Specifies that the popup must slide horizontally into the view.
5. Pop - Specifies that the popup must emerge from center-bottom of the screen and gradually occupy the
complete screen.
6. Squeeze - Specifies that the popup must be expanded horizontally from an initial width of zero.
transitionSpeed: Specifies the speed at which the Popup is transitioned. The value must be specified in
seconds.
applied.
On SPA Platform, Transition has the below options to set:
2. Top Center - Specifies that the popup must appear from the top center.
3. Bottom Center - Specifies that the popup must appear from the bottom center.
4. Right Center - Specifies that the popup must appear from the right center.
5. Left Center - Specifies that the popup must appear from the left center.
Syntax
JavaScript: inTransitionConfig
Lua: intransitionconfig
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a Popup with inTransitionConfig:{transitionDirec
tion:"topCenter"}
var popPSP ={inTransitionConfig:{transitionDirection:"topCenter"}};
//Reading the inTransitionConfig of the popUp
alert("popUp inTransitionConfig::"+popUp.inTransitionConfig);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web platforms, Windows Kiosk, and Windows
Tablet
9.3.11 layout
Specifies if the arrangement of the widgets either in horizontal or vertical direction.
Default : Vertical
l
Vertical : The navigation happens in vertical direction.
Horizontal : The navigation happens in horizontal direction.
Syntax
JavaScript: layout
Lua: layout
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for a Popup with layout:Vertical
var popPSP ={layout:constants.Vertical};
Accessible from IDE

Yes
9.3.12 minimizeOnLostFocus
Indicates the popup window should minimize when the focus moves out of the popup. This property is
applicable only for non-modal popup.
Default: false
If set to true, the popup window is minimized.
if set to false, the popup window is not minimized.
Syntax
JavaScript: minimizeOnLostFocus
Type
JavaScript: Boolean
Read / Write
No
JavaScript Example
//Defining a Popup with layoutType
var popBasic = {id:"popup", type:constants.POPUP_TYPE_NATIVE , title:"Welc
ome"};
var popLayout ={displayOrientation:constants.POPUP_DISPLAY_ORIENTATION_BOT
H, paddingInPixel:false, padding:[5,5,5,5]};
var popPSP ={layoutType: constants.CONTAINER_LAYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}, minimizeOnLostFocus:true};
//Creating a POPUP.
var frm =new kony.ui.Popup(popBasic, popLayout, popPSP);
Accessible from IDE

Yes
This property is available on Desktop Web
9.3.13 noCache
A web cache is a mechanism for the temporary storage (caching) of web documents, such as HTML pages
and images, to reduce bandwidth usage, server load, and perceived lag. This property indicates that if the
form is enabled for caching on the device browser.
Default: true
If set to false, appropriate Cache control headers are included in the HTTP response.
If set to true, cache control headers are not included in the HTTP response.
Syntax
JavaScript: noCache
Lua: nocache
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with noCache:false
var popBasic ={id:"popUp", type:constants.POPUP_TYPE_NATIVE, title:"PopUP",
skin:"popSkin", isModal:true};
var popPSP ={noCache:false};
Accessible from IDE

Yes
l
Specifies the type of transition effect to be applied when the popup is going out of view. It accepts hash
values.
transitionDirection: Specifies the direction from which the popup must disappear in a view. You can choose
one of the following options:
2. fromRight - Specifies that the popup must disappear from the right.
3. fromLeft - Specifies that the popup must disappear from the left.
4. fromBottom - Specifies that the popup must disappear from the bottom.
5. fromTop - Specifies that the popup must disappear from the top.
transitionEffect: Specifies the type of transition effect to be applied when the form disappears in the view.
You can choose one of the following transition effects:
2. transitionFade - Specifies that the popup must fade when it is transitioned to a hidden or an invisible
state.
3. transitionMoveOut - Specifies that the popup must slide away in the direction as specified in the
4. transitionMoveIn - Specifies that the popup must slide over the existing content in the direction as
Following are the properties available for Android platform:
applied.
2. bottom-top - The constant value is 1. Specifies that the popup must slide-out from the bottom and
3. from left- The constant value is 2. Specifies that the popup must slide-out from the left with a fade
effect.
4. from right - The constant value is 3. Specifies that the popup must slide-out from the right with a fade
effect.
5. to right - The constant value is 4. Specifies that the popup must slide-in to the right with a fade effect.
6. to left - The constant value is 5. Specifies that the popup must slide-in to the left with a fade effect.
7. from center - The constant value is 6. Specifies that the popup must grow from the center with a fade
effect.
8. topright-bottom - The constant value is 7. Specifies that the popup must slide-in from the top-right
9. bottomleft-top - The constant value is 8. Specifies that the popup must slide-in from the bottom-left
10. bottom-top style1 - The constant value is 9. Specifies that the popup must shrink from the bottom
towards the top.
11. top down - The constant value is 10. Specifies that the popup must slide-in from the top and proceed
towards the bottom.
//sample code to set outTransitionConfig with the option top down.

popup1.outTransitionConfig= {popupAnimation: 10 };

transitionMode: Specifies the direction from which the popup is displayed. The available options are:
1. Default(none)- The default device effect is applied or none of the effect is applied.
2. Sequential- The transition of the popup going out of the view completes first and then the transition of
the form coming into the view takes place.
3. Parallel- The transition of the popup going out of the view and the transition of the form coming into the
outTransition: Specifies the effect from which the popup is displayed. The available options are:
1. Default(none)- Specifies that the popup must slide horizontally into the view.
2. Rotate3DSingle - Specifies that the popup must be rotated along the center Y-Axis when coming into
the view.
3. Rotate3DDual - Specifies that the popup must be shown making a circle around the screen from the
4. Slide - Specifies that the popup must slide horizontally into the view.
5. Pop - Specifies that the popup must emerge from center-bottom of the screen and gradually occupy the
complete screen.
6. Squeeze - Specifies that the popup must be expanded horizontally from an initial width of zero.
transitionSpeed: Specifies the speed at which the popup is transitioned. The value must be specified in
seconds.
applied.
On SPA Platform, Transition has the below options to set:
2. Top Center - Specifies that the popup must disappear from the top center.
3. Bottom Center - Specifies that the popup must disappear from the bottom center.
4. Right Center - Specifies that the popup must disappear from the right center.
5. Left Center - Specifies that the popup must appear from the left center.
Syntax
JavaScript: outTransitionConfig
Lua: outtransitionconfig
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a Popup with outTransitionConfig:{transitionDire
ction:"topCenter"}
var popPSP ={outTransitionConfig:{transitionDirection:"topCenter"}};
//Reading the outTransitionConfig of the popUp.
alert("popUp outTransitionConfig::"+popUp.outTransitionConfig);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web platforms, Windows Kiosk, and Windows
Tablet.
9.3.15 popupStyle
Specifies the popup style to be displayed in the application.
l
POPUP_TYPE_KONY_STYLE : This is the default popup provided by kony.
POPUP_TYPE_NATIVE_STYLE : This option is applicable for iPad only. Using this style, the popup
is rendered as popover.
Syntax
JavaScript: popupStyle
Lua: popupstyle
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a Popup with outTransitionConfig:{transitionDire
ction:"topCenter"}
var popPSP ={popupStyle:constants.POPUP_TYPE_NATIVE_STYLE}};
//Reading the Popup style.
alert("popUp style is ::"+popUp.popupStyle);
Accessible from IDE

Yes
Available on iPad platform only.
9.3.16 resizable
Specifies the weather the popup can be resized across the browser screen.
Default: false
If set to true, the popup window can be resized.
if set to false, the popup window cannot be resized.
Syntax
JavaScript: resizable
Type
JavaScript:Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with resizable:true.
var popPSP ={resizable:true};
Accessible from IDE

Yes
9.3.17 secureData
Specifies if the browser must retain and use the information that you have filled in a form (for example,
username and password) and use it during the POST request made when you refresh the browser or use the
back button on the browser.
Default: the option is not selected (the browser will retain data and use it during POST request)
If you do not want the browser to use the information during the POST request made when you refresh the
browser or use the back button on the browser, select the checkbox.
Syntax
JavaScript: secureData
Lua: securedata
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with secureData:true
var popPSP ={secureData:true};
Accessible from IDE

Yes
l
Specifies if the application menu is shown or hidden in the application.
Default: false
The below image illustrates the default mode of an application menu of the Popup:
Mini
If you set the value to mini the application menu is minimized in the application.
The below image illustrates the Mini mode of an application menu of the Popup:
Syntax
JavaScript: showMiniAppMenu
Lua: showminiappmenu
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with mangoMode:true
var popPSP ={showMiniAppMenu:true};
Accessible from IDE

Yes
Available on Windows Mango platform only.
9.3.19 submitSecure
Specifies if the information must be sent using secure connection (https) or insecure connection (http).
This property is useful in scenarios where you want the information sent to be secure. For example, credit
card user credentials, transactions etc.
Default: false (the checkbox is not selected and the information sent is not secure)
To send information securely, set the value to true (select the checkbox).
Note: If you have marked all the Forms to be submitted through a secure protocol, then the popup must also
be secured.
Syntax
JavaScript: submitSecure
Lua: submitsecure
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Popup with submitSecure:true
var popPSP ={submitSecure:true};
Accessible from IDE

Yes
l
Specifies the configuration properties for title bar for Desktop Web platform.
minIcon:Represents the URL of the icon to be used for displaying the minimize option for the popup window.
The default icon is "-".
Type: String
maxIcon:Represents the URL of the icon to be used for displaying the maximize option for the popup
window. The default icon is "+".
Type: String
closeIcon: Represents the URL of the icon to be used to close the popup window. The default icon is "X".
Type: String
skin: Specifies the skin to be applied on the browser window.
Type: String
template:Specifies the template for the browser window there the developer can arrange the images and the
titles.
Syntax
JavaScript: titleBarConfig
Type
JavaScript:JSObject
Read / Write
JavaScript Example
//Defining properties for a Popup with titleBarConfig properties.
var popPSP ={titleBarConfig: {
minIcon: \\resources\desktopweb\min.png,
maxIconsizeMode: \\resources\desktopweb\max.png,
closeIcon \\resources\desktopweb\close.png,
skin: titlebarconfskin
}
};
Accessible from IDE

Yes
9.3.21 viewConfig
l
Normal view
Grid view
grid view.
Syntax
Lua: viewconfig
Type
JavaScript:JSObject
Lua: Table
Read / Write
No
JavaScript Example
//Defining properties for a Popup with the viewConfig
var popPSP ={viewConfig: {
referenceHeight: 40,
sizeMode: constants.GRID_TYPE_FIXED,
referenceWidth: 30
};
};
Accessible from IDE

Yes
This property defines how the main Popup interacts with the window containing the on-screen soft keyboard.
It determines the adjustments made to the Popup whether it is resized smaller to make room for the soft
keyboard or whether its contents pan to make the current focus visible when part of the Popup is covered by
the soft keyboard.
Default: POPUP_ADJUST_RESIZE
l
POPUP_ADJUST_RESIZE: Specifies the popup is resized and when you click or start typing within
the widget which requires an input, the popup scrolls up and the widget which requires an input is not
overlapped by the keypad or footer.
POPUP_ADJUST_PAN: Specifies the widget which requires an input is placed at the bottom of the
popup is overlapped by the keypad. The main Popup is not resized to make room for the soft keyboard.
Rather, the contents of the Popup are automatically panned so that the current focus is never obscured
by the keyboard and users can always see what they are typing. This is generally less desirable than
resizing, because the user may need to close the soft keyboard to get at and interact with obscured
parts of the Popup.
Syntax
JavaScript: windowSoftInputMode
Lua: windowsoftinputmode
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a Popup with windowSoftInputMode:constants.POPUP_
ADJUST_RESIZE
var popPSP ={windowSoftInputMode:constants.POPUP_ADJUST_RESIZE};
Accessible from IDE

Yes
Available on Android platform only
9.4 Popup - Events

Popup has the following events associated with it:
l
addWidgets
init
onHide
onDeviceBack
onLoadJS
unLoadJS
9.4.1 addWidgets
An event callback invoked by the platform when show method of popup is called for first time after its
construction. This is called only once in a lifetime of the popup between creation and destruction. This method
is also called when destroyed popup is shown again. Popups can be destroyed using destroy method.
Signature
JavaScript: addWidgets(popupref)
Lua: addwidgets(popupref)
Read / Write
Yes - (Write only)
JavaScript Example
//Defining properties for a Popup with addWidgets:addWidgetsCallBck
2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:100, add
Widgets:addWidgetsCallBck};
var popPSP ={};
9.4.2 init
This event gets called only once in popup life cycle that is when the popup is ready with its widget hierarchy.
This will get called after addwidgets method allowing user for any one-time initializations.
When popup is destroyed and reused again, init gets called as a part of popup lifecycle.
Signature
JavaScript: init(popupref)
Lua: init(popupref)
Read / Write
JavaScript Example
//The below function is the callback function for init event.
function initCallBck(popup)
{
//Write your logic here
}
//Defining properties for a Popup with init:initCallBck.
x2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:100, in
it:initCallBck};
var popPSP ={};
9.4.3 onHide
Specifies an Event which is triggered when a popup goes out of view.
This event is triggered in the following scenarios:
l
form.show (another form) is called
User hits the device back button or key
This event is not triggered in the following scenarios:

l
The form is partially or completely covered by the Popup.
The form is partially or completely covered by the Application Menu.
Signature
JavaScript: onHide(popupref)
Lua: onhide(popupref)
Read / Write
JavaScript Example
function onHideCallBck(popup)
{
}
//Defining properties for a Popup with onHide:onHideCallBck.
x2], footers:[box3,box4], isModal:true, transparencyBehindThePopup:100, on
Hide:onHideCallBck};
var popPSP ={};
Available on all platforms except Server side Mobile Web platforms
9.4.4 onDeviceBack
Signature
JavaScript: onDeviceBack(popupref)
Lua: ondeviceback(popupref)
Read / Write
JavaScript Example
//The below function is the callback function for onDeviceBack event.
function onDeviceBackCallBck(popup)
{
}
//Defining properties for a Popup with onDeviceBack:onDeviceBackCallBck

var popPSP ={onDeviceBack:onDeviceBackCallBck};
l
BlackBerry
9.4.5 onLoadJS
Specifies the name of function to be executed when a popup is loaded. The function must exist in a
JavaScript file under project>module>js folder.
Syntax
JavaScript: onLoadJS
Lua: onloadjs
Read / Write
JavaScript Example
//The below function is the callback function for onLoadJS event
function onLoadJSCallBck(popup)
{
}
//Defining properties for a Popup with onLoadJS:onLoadJSCallBck
var popPSP ={onLoadJS:onLoadJSCallBck};
//Reading the onLoadJS of the popUp
alert("popUp onLoadJS::"+popUp.onLoadJS);
Accessible from IDE

Yes
Available on Server side Mobile Web (BJS and Advanced) platform
9.4.6 unLoadJS
Specifies the name of function to be executed when a popup is unloaded. The function must exist in a
JavaScript file under project>module>js folder.
Syntax
JavaScript: unLoadJS
Lua: unloadjs
Read / Write
JavaScript Example
//The below function is the callback function for unLoadJS event
function unLoadJSCallBck(popup)
{
}
//Defining properties for a Popup with unLoadJS:unLoadJSCallBck
var popPSP ={unLoadJS:unLoadJSCallBck};
//Reading the unLoadJS of the popUp
alert("popUp unLoadJS::"+popUp.unLoadJS);
Accessible from IDE

Yes
Available on Server side Mobile Web (Advanced) platform
9.5 Popup - Methods

Popup has the following methods associated with it:
l
add
addAt
destroy
dismiss
navigateTo
remove
removeAt
scrollToBeginning
scrollToEnd
scrollToWidget
setContext
setTitleBarSkin
showTitleBar
hideTitleBar
show
widgets
9.5.1 add
This method is used to add widgets to the Popup. When the widgets are added to the current visible Popup,
then the changes will reflect immediately. Adding a widget to the Popup or Box hierarchy, which is already a
part of the other widget hierarchy, will lead to undefined behaviors. You have to explicitly remove the widget
from one hierarchy before adding it to another Popup or Box.
Signature
JavaScript: add(widgets)
Lua: popup.add(popupname, widgets)
Input Parameters
widgets - Mandatory
popupname [UserData] - Mandatory
Reference to the popup.
Return Values
None
Exceptions
WidgetError
JavaScript Example
var popBasic ={id:"popUp", title:"PopUP",skin:"popSkin",isModal:true, tran
sparencyBehindThePopup:100};
var popPSP ={};
//Adding a label and a button widgets to the popUp. Here label and button
widgets should be created already and made accessible.
popUp.add(lbl,btn);
9.5.2 addAt
This method is used to add widgets to the Popup container at the specified index. Widget is prepended if index
present in the container. If a new widget is added or removed will reflect immediately from the Popup hierarchy
model perspective, however the changes are displayed when the Popup appears. When the widgets are
added to the current visible Popup, then the changes will reflect immediately. Adding a widget to the Popup or
Box hierarchy, which is already a part of the other widget hierarchy, will lead to undefined behaviors. You have
to explicitly remove the widget from one hierarchy before adding it to another Popup or Box.
Signature
JavaScript: addAt(widgetref, index)
Lua: popup.addAt(popupname, widgetref, index)
Input Parameters
widgetref [JSObject] - Mandatory

Return Values
None
Exceptions
WidgetError
JavaScript Example
var popBasic ={id:"popUp", title:"PopUP", skin:"popSkin", isModal:true, tr
ansparencyBehindThePopup:100};
var popPSP ={};
//Adding label to the popUp at 15th index Position. Label should be created
already and made accessible .
popUp.addAt(lbl,15);
9.5.3 destroy
This method is used to destroy any unwanted Popups at any point in time, and allows increasing the
application life by reducing the memory usage.
Signature
JavaScript: destroy()
Lua: popup.destroy(popupname)
Input Parameters
Return Values
None
Exceptions
None
JavaScript Example
var popBasic ={id:"popUp", title:"PopUP", skin:"popSkin",isModal:true, tra
nsparencyBehindThePopup:100};
var popPSP ={};
//destroy method call
popUp.destroy();
9.5.4 dismiss
This method is used to dismiss the popup on which this method is called.
Signature
JavaScript: dismiss()
Lua: popup.dismiss(popupname)
Input Parameters
Return Values
None
Exceptions
None
JavaScript Example

var popPSP ={};
//Dismiss method call.
popUp.dismiss();
9.5.5 navigateTo
This method is used to navigate from one popup to other popup. The popup on which this method is called
remains displayed while the content of the popup changes from current popup to given popup.
Note: This method is applicable only when the popupStyle is set as POPUP_TYPE_NATIVE_STYLE.
Signature
JavaScript: navigateTo(popupinstance, config)
Input Parameters
popupinstance [UserData] - Mandatory
config[UserData] - optional
For future releases. Not configurable as of now.
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};

//NavigateTo method call.
popUp.navigateTo(popupinstance);
Available on iOS (iPad only) platform
9.5.6 remove
This method removes a widget from the Popup container. If a new widget is removed will reflect immediately
from the Popup hierarchy model perspective, however the changes are displayed when the Popup appears.
When the widgets are added to the current visible Popup, then the changes will reflect immediately.
Signature
Lua: popup.remove(popupname, widgetref)
Input Parameters
widgetref [JSObject] - Mandatory
popupname [widgetref] - Mandatory
Return Values
The current Popup handle is returned.
Exceptions
WidgetError
JavaScript Example
var popPSP ={};
//Removing label ,button widgets to the popUp. Here label and button
widgets should be created and added to the popUp.

popUp.remove(lbl,btn);
9.5.7 removeAt
This method removes a widget at the given index from the Popup container. If a new widget is removed will
reflect immediately from the Popup hierarchy model perspective, however the changes are displayed when
the Popup appears. When the widgets are added to the current visible Popup, then the changes will reflect
immediately.
Signature
Lua: popup.removeat(popupname, index)
Input Parameters
index [Number]- Mandatory
Specifies the index of the popup.
Return Values
Exceptions
WidgetError
JavaScript Example
var popBasic ={id:"popUp", type:constants.POPUP_TYPE_NATIVE,title:"PopUP",
skin:"popSkin", isModal:true, transparencyBehindThePopup:100};
var popPSP ={};
//Removing widget from the popUp at 15th index Position.

popUp.removeAt(15);
This method gives you the control to scroll to the beginning of the Popup.
Signature
Lua: popup.scrolltobeginning(popupname)
Input Parameters
Return Values
None
Exceptions
WidgetError
JavaScript Example
var popBasic ={id:"popUp", title:"PopUP", skin:"popSkin",isModal:true, tra
var popPSP ={};
//scrollToBeginning method call.
popUp.scrollToBeginning();
9.5.9 scrollToEnd
This method gives you the control to scroll to the end of the Popup.
Signature
Lua: popup.scrolltoend(popupname)
Input Parameters
Return Values
None
Exceptions
WidgetError
JavaScript Example
var popPSP ={};
//scrollToEnd method call.
popUp.scrollToEnd();
This method gives you the control to scroll the widget in the Popup.
Signature
JavaScript: scrollToWidget()
Lua: popup.scrolltowidget(popupname)
Input Parameters
Return Values
None
Exceptions
WidgetError
JavaScript Example
var popBasic ={id:"popUp", title:"PopUP",skin:"popSkin", isModal:true, tra
var popPSP ={};
//Scrolling the popUp to the Label lbl.
popUp.scrollToWidget(lbl);
9.5.11 setContext
Specifies the popup that must be displayed for the context and also helps you to position the popup on the
screen. The popup can be positioned relative to a widget on the screen and setcontext enables you to do that.
The context contains information regarding the widget for which the popup must be shown and also the
anchoring of the popup on the widget (left, right, center, top, or bottom).
Additionally for the iPhone platform, you can choose to specify the sizetoanchorwidth, a boolean property. If
you set the value to true, the popup width is made equal to the width of the anchor. If the value is false (default
value), the popup takes the width allocated in the popup properties.
Signature
JavaScript: setContext(context)
Lua: popup.setcontext(popupname, context)
Input Parameters
context [JSObject] - Mandatory
Set of key value pairs providing information about the widget and the anchoring used to position the
popup on the screen.
Following are the key value pairs of this JSObject:
sizetoanchorwidth [Boolean] - Mandatory (applicable on iPhone)
Specifies if the width of the popup has to be the same as that of the widget relative to
which it has been anchored.
anchor [String] - Mandatory
It is a set of flags that are used to anchor the popup with respect to the dimensions of
the widget. Possible values are ("top", "bottom", "right", "left"). Additionally
native popupover style (POPUP_TYPE_NATIVE_STYLE) on iPad supports "any".
When you set this property, the popup is anchored to the best possible position
around another widget.
widget (widgetref) - Mandatory
Reference to an existing widget with respect to which the Popup has to be anchored
(Pass the Formid if the popup is to be positioned with respect to a Form. This Form is
assumed to be the form on which the popup will be overlaid).
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};
//Defining the context Object
var context1={"widget":frmApis.label22,"anchor":"bottom","sizetoanchorwidt
h":false};
//setContext method call
popUp.setContext(context1);
Available on all platforms except BlackBerry, BlackBerry 10, and Server side Mobile Web platforms
This method enables you to set the properties for a left-side button of a titlebar.
Signature
JavaScript: setTitleBarLeftSideButton(text, skin, callback)
Input Parameters
Specifies the text of the title bar left side button.
callback [JSObject] - Mandatory
An event callback is invoked by the platform when the user performs a click action.
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};
h":false};
//setTitleBarLeftSideButton method call
popUp.setTitleBarLeftSideButton(title, image, handler);
This method enables you to set the properties for a right-side button of a titlebar.
Signature
JavaScript: setTitleBarRightSideButton(title, image, handler)
Input Parameters
Specifies the text of the title bar right side button.
callback [JSObject] - Mandatory
An event callback is invoked by the platform when the user performs a click action.
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};
h":false};
//setTitleBarRightSideButton method call
popUp.setTitleBarRightSideButton(title, image, handler);
This method enables you to set the skin for a titlebar of a popup.
Signature
JavaScript: setTitleBarSkin(skin)
Input Parameters
skin [String] - Mandatory
Reference to the skin.
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};

h":false};
//setTitleBarSkin method call
popUp.setTitleBarSkin(skin);
9.5.15 showTitleBar
This method gives you the control to show a titlebar within a popup.
Signature
JavaScript: showTitleBar()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};
h":false};
//showTitleBar method call
popUp.showTitleBar();
9.5.16 hideTitleBar
This method gives you the control to hide a titlebar within a popup.
Signature
JavaScript: hideTitleBar()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};
h":false};
//hideTitleBar method call
popUp.hideTitleBar();
9.5.17 show
Displays the popup on to the screen.
Signature
JavaScript: show()
Lua: popup.show(popupname)
Input Parameters
Return Values
None
Exceptions
None
JavaScript Example
var popPSP ={};
//show method call
popUp.show();
This method is available on iPhone/iPad, BlackBerry 10, and Windows Kiosk platforms.
9.5.18 widgets
Returns an array of the widget references which are direct children of the popup.
Signature
Lua: popup.widgets(popupname)
Input Parameters
Return Values
of widgets in this array doesn't reflect in the Form hierarchy, however you can get handle to the widgets
widgets.
Exceptions
WidgetError
JavaScript Example
var popPSP ={};
//Collecting all the widgets of the PopUp into array and displaying the re
ferences.
wigArr = popUp.widgets();
9.6 Popup - Deprecated Properties

The deprecated properties for Popup widget are as follows:
l
closureLeftSideView
defaulttransition
dockableAppMenu
formanimation
formtransition
imageLeftSideView
imageRightSideView
inTransitKey
inTransitMode
nift
onOrientationChange
orientationmode
outTransitKey
outTransitMode
renderTitleText
Reset_Focus_to_top_of_the_Form
Skin_Around_Popup
titleBar
titleBarLeftSideView
transition
transitionDirection
transitionEffect
Alternative Properties
defaulttransition
formanimation
formtransition
inTransitKey
inTransitMode
outTransitKey
outTransitMode
transition
transitionDirection
transitionEffect
Mapped to InTransitionConfig
Mapped to OutTransitionConfig
Mapped to OutTransitionConfig
9.6.1 closureLeftSideView
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
This method is available on iPhone/iPad platform.
9.6.2 closureRightSideView
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.3 dockableAppMenu
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
Mobile Web (basic)
Mobile Web (BJS)
Mobile Web (advanced)
9.6.4 imageLeftSideView
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.5 imageRightSideView
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.6 nift
"Fixed number of Item from top" is the display name in IDE
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
Black Berry
Windows Phone
Specifies an Event which is triggered when there is a change in orientation of the Popup from portrait to
landscape or vice versa.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.8 orientationmode
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.9 renderTitleText
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.10 reset Focus to top of the Form

Type
Boolean
Read / Write
No
Accessible from IDE

Yes
This method is available on Windows Phone/Symbian platform.
9.6.11 skin Around Popup

This is a skin property. This property specifies the skin that must be applied around a popup.
Type
Object
Read / Write
No
Accessible from IDE

Yes
l
Black Berry
J2ME
9.6.12 titleBar
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
iPhone/iPad
Android
9.6.13 titleBarLeftSideView
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
9.6.14 titleBarRightSideView
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
10. Basic Widgets

Basic Widgets are components that act independently of the Container Widgets.
This section describes the following component widgets:
l
Button
Calendar
CheckBoxGroup
ComboBox
DataGrid
Image
Label
Line
Link
ListBox
MenuContainer
MenuItem
RadioButtonGroup
RichText
Slider
TextArea
TextBox
11. Button
A Button is a control that you can use to provide input to an application or trigger an event. For example,
navigating to a form, interacting with a dialog box, or confirming an action.
A button can display either a text with a background color, text with a background image, or just an image.
Button provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
and Events.
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
rawBytes
skin
text
containerWeight
contentAlignment
displayText
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Events
Deprecated
onClick
preOnclickJS
postOnclickJS
focusimage
image
normalimage
Platform Specific
Properties
blockedUISkin
contextMenu
externalURL
glowEffect
hoverSkin
pressedSkin
submitURL
toolTip
Creating a Button using a constructor: kony.ui.Button

var button1 = new kony.ui.Button(basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//The below function is the callback function for onClick event call.
function onClickCallBack()
{
}
//Defining the button with onClick:onClickCallBck.
var btnBasic ={id:"Onbutton", isVisible:true, skin:"btnSkin",
focusSkin:"btnFSkin", text:"Click Here", onClick:onClickCallBck};

var btnLayout ={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5],
hExpand:true, vExpand:false, displayText:true};
var btnPSP ={pressedSkin:"presSkin", externalURL: http://www.konysolutions
.com, submitURL:http://www.konysolutions.com, glowEffect:true };
//Creating the button.
var Onbutton = new kony.ui.Button(btnBasic, btnLayout, btnPSP);
Widget Appearance on Platforms

The appearance of the button widget on various platforms is as follows:
Platform
Appearance
iPhone
Android
BlackBerry
Windows Phone
Platform
Appearance
Mobile Web (Advanced)
Mobile Web (BJS)
Adding a Button Widget from IDE

Follow the below steps to add a button widget:
1. From the IDE, drag and drop the button widget onto a form (occupies the complete available width). Or,
based on your requirements, you can choose to perform any of the following options:
a. If you want to resize the button in the horizontal direction, place an HBox on the Form
and drag and drop the button inside the HBox and resize accordingly (you can also
choose to place multiple buttons in the Box). Now apply hExpand property to expand the
button in horizontal direction.
b. If you want to resize the button in the vertical direction, place an HBox on the Form and
place a VBox inside the HBox; and drag-and-drop the button inside the VBox and resize
accordingly (you can also choose to place multiple buttons in the VBox). Now apply
vExpand property to expand the button in vertical direction.
2. Use the text property and specify the text to be displayed on the button.
3. Define an onClick event.
You can customize the appearance of the button by using the following properties:
l
skin: Specifies the skin.
focusSkin: Specifies the focus skin.
hExpand: Expand the button horizontally.
vExpand: Expand the button vertically.
Button has the following considerations:
l
You can specify a background image for a Button. You can set the image from the Button skin for both
normal and focus skins.
To avoid jumping effect or to avoid overlap of neighboring widgets, you must ensure that the image for
normal and focus skins are of the same size.
11.1 Button - Basic Properties

The basic properties for Button Widget are as follows:
l
focusSkin
id
info
isVisible
rawBytes
skin
text
toolTip
11.1.1 focusSkin
Specifies the look and feel of the Button when in focus.

1. On J2ME non-touch devices, if you do not specify the Focus skin, it is not possible to identify the focus
change between the widgets.
2. Mobile Web does not support this property, instead browser specific focus will be applied.
3. On BlackBerry 10 patform, focusSkin for native button is not supported. It is supported only if the button
background is set as image.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a button with focusSkin:"btnFSkin".
var btnBasic={id:"button1", isVisible:true, skin:"btnSkin", focusSkin:"btn
FSkin", text:"Click Here"};
var btnLayout={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5], h
Expand:true, vExpand:false, displayText:true};
var btnPSP={};
var button1 = new kony.ui.Button(btnBasic, btnLayout, btnPSP);
//Reading focusSkin of the button
alert("Button focusSkin ::"+button1.focusSkin);
Accessible from IDE

Yes
11.1.2 id
id is a unique identifier of button consisting of alpha numeric characters. Every Button should have a unique id
within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a button with id:"button1".
var btnPSP={};
//Reading id of the button.
alert("Button Id ::"+button1.id);
Accessible from IDE

Yes
11.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a button with info property.
var btnBasic={id:"button1", skin:"btnSkin", focusSkin:"btnFSkin", text:"Cl
ick Here"};
var btnPSP={};
button1.info = {key:"buttonname"};
//Reading info of the button.
alert("Button info ::"+button1.info);
Accessible from IDE

No
11.1.4 isVisible
Default: true
Segment, the Visibility of the widget is controlled by the data property of the segment.
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a button with isVisible:true
var btnPSP={};
//Reading isVisible of the button
alert("Button isVisible ::"+button1.isVisible);
Note: In addition, the visibility of the widget can be controlled by using the setVisibility method.
Accessible from IDE

Yes
11.1.5 rawBytes
Specifies the rawbytes representing an Image (usually the image captured from the camera) that can be used
as a background for the button. You cannot assign rawBytes directly to a button widget. The rawBytes has to
be assigned to an Image widget or Button widget that has image skin.
Syntax
JavaScript: rawBytes
Lua: rawbytes
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a button with rawBytes:"11111"(This data sho
uld be returned from camera).
var btnBasic={id:"button1",isVisible:true, skin:"btnSkin", focusSkin:"btnF
Skin", text:"Click Here", rawBytes:"11111"};
var btnLayout={containerWeight:100,padding:[5,5,5,5], margin:[5,5,5,5], hE
xpand:true, vExpand:false, displayText:true};
var btnPSP={};
//Reading rawBytes of the button
alert("Button rawBytes ::"+button1.rawBytes);
Accessible from IDE

No
Available on all platforms except on all Server side Mobile Web and SPA
11.1.6 skin
Specifies the look and feel of the Button when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a button with skin:"btnSkin".
Skin", text:"Click Here"};
var btnLayout={containerWeight:100, padding:[5,5,5,5],margin:[5,5,5,5], hE
xpand:true, vExpand:false,displayText:true};
var btnPSP={};
//Reading skin of the button.
alert("Button skin ::"+button1.skin);
Accessible from IDE

Yes
11.1.7 text
Specifies a general or descriptive text for the Button widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a button with text:"Click Here".
var btnBasic={id:"button1", isVisible:true, skin:"btnSkin",
focusSkin:"btnFSkin", text:"Click Here"};

var btnLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hEx
pand:true, vExpand:false, displayText:true};
var btnPSP={};
//Reading text of the button.
alert("Button text ::"+button1.text);
Accessible from IDE

Yes
11.2 Button - Layout Properties

The layout properties for Button Widget are as follows:
l
containerWeight
contentAlignment
displayText
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Specifies the percentage of the parent width that should allocated to the widget. The parent widget space is
distributed to its child widgets based on this weight factor. All its child widgets should sum up to 100% of
width except when placed in kony.ui.ScrollBox.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a button with containerWeight:100
var btnPSP={};
/Creating the button.
//Reading containerWeight of the button.
alert("Button containerWeight ::"+button1.containerWeight); //ContainerName
is the name of the container widget under which the button is placed.
Accessible from IDE

No
Specifies the alignment of the text on the Button with respect to its boundaries. A default value CONTENT_
ALIGN_CENTER is assigned for all platforms. To choose another alignment, click the drop-down arrow and
select the desired alignment. However, to change the default value on a particular platform, select the button
next to the drop-down and select respective platform and choose the value.
Default: CONTENT_ALIGN_CENTER (the default value for all platforms is center; content is aligned at the
center of the button)
The following are the available options:
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the button.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the button.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the button.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the button.
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the button.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the button.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the button.
CONTENT_ALIGN_BOTTOM_CENTER- Specifies the text should align at bottom center of the

button.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the button.
Syntax
JavaScript: contentAlignment
Lua: contentalignment
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a button with Content Alignment as TOP_LEFT.
var btnBasic={id:"button1",isVisible:true,skin:"btnSkin", focusSkin:"btnFS
kin", text:"Click Here"};
Expand:true, vExpand:false, displayText:true, contentAlignment:constants.C
ONTENT_ALIGN_TOP_LEFT};
var btnPSP={};
Accessible from IDE

Yes
Available on all platforms except BlackBerry 10 platform
11.2.3 displayText
Specifies if the text (present in text property) to be rendered or not.
Default: true
If set to false, the text is not displayed.
If set to true, the text is displayed.
Syntax
JavaScript: displayText
Lua: displaytext
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with displayText:true
var btnBasic={id:"button1",isVisible:true,skin:"btnSkin",focusSkin:"btnFSk
in", text:"Click Here"};
var btnPSP={};
Accessible from IDE

Yes
11.2.4 hExpand
Specifies if the widget should occupy all the width available to it.
Note: Mobile Web does not support the Expand property. This is because a widget in a Mobile Web cannot
expand or contract based on the neighboring widget (default behavior of a widget in a Mobile Web).
Note: In BlackBerry 10 platform, hExpand as false is not supported.
Default: true
If set to false, the widget occupies the preferred width. The preferred width of a widget is the sum of its
contents width, padding and margin.
If set to true, the widget ensures that the entire width available to it, is occupied.
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a buttonn with Horizontal Expand as true
var btnPSP={};
Accessible from IDE

Yes
Available on all platforms except Mobile Web, Desktop Web, and SPA.
11.2.5 margin
between the widget and the next widget.
Syntax
JavaScript: margin
Lua: margin
Type
JavaScript: Array of numbers
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a button with margin:[5,5,5,5]
var btnPSP={};
Accessible from IDE

Yes
Default: false
If set to true, the margin is applied in pixels.
If set to false, the margin is applied as set in margin property.
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with margin in pixels.
var btnBasic={id:"button1", isVisible:true,skin:"btnSkin", focusSkin:"btnF
Expand:true, vExpand:false, marginInPixel:true};
var btnPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
11.2.7 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a button with padding:[5,5,5,5]
var btnPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic) and BlackBerry 10.
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with padding in pixels.
Expand:true, vExpand:false, paddingInPixel:true};
var btnPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
11.2.9 vExpand
Specifies if the widget has to occupy all the vertical space available to it.
Default: false
If set to false, the widget occupies the preferred height. The preferred height of a widget is the sum of its
contents height, padding and margin.
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with vExpand:false
var btnPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, BlackBerry 10, and Desktop Web platforms.
Horizontal alignment attributes are only applicable if hExpand is false. Similarly vertical alignment attributes
are only applicable if vExpand is false.
l
Syntax
Lua: widgetalignment
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a button with widgetAlignment:constants.WIDG
ET_ALIGN_TOP_RIGHT
xpand:true, vExpand:false, displayText:true, widgetAlignment:constants.WID
GET_ALIGN_TOP_RIGHT};
var btnPSP={};
Accessible from IDE

Yes
11.3 Button - Platform Specific Properties

The platform specific properties for Button Widget are as follows:
l
blockedUISkin
contextMenu
externalURL
glowEffect
hoverSkin
pressedSkin
submitURL
tooltip
call) is completed.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a button with blockedUISkin:"blkUISkin"
var btnBasic={id:"button1", isVisible:true, skin:"btnSkin", text:"Click He
re"};
var btnPSP={blockedUISkin:"blkUISkin"};
//Reading blockedUISkin of the button
alert("Button blockedUISkin ::"+button.blockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
11.3.2 contextMenu
A context menu is a menu that appears upon clicking a button. A context menu typically offers a limited set of
choices that are applicable for that button. Usually these choices are actions, related to the button.
If you define a context menu for a button, the steps involved to invoke the context menu on a platform and the
appearance of the context menu varies.
In Desktop Web, on right-click mouse the context specific menu will be displayed with the array of menu
items.
l
BlackBerry 6.x
BlackBerry Touch
Device (<6.x)
Device (<6.x)
The following are the characteristics of a context menu on Android platform:

l
You can invoke the context menu by a long press on the widget.
The menu items are displayed as text (no support for icons).
There is no support for sub-menus in a context menu.
The following image illustrates the context menu on Android platform:
Syntax
Lua: contextmenu
Type
JavaScript: Array(kony.ui.MenuItem)
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a button with contextMenu:[menuItem1, menuIt
em2, menuItem3], Where these menu items should be created and made accessi
ble.

var btnPSP={contextMenu:[menuItem1,menuItem2,menuItem3]};
Note: On Android platform, the image icon, separator, and submenu properties are not supported.
Accessible from IDE

No
l
BlackBerry
Windows Tablet
11.3.3 externalURL
Specifies that the URL must be opened directly from the web site without having to contact the Kony Server.
For example, in a Banking Application, for Terms and Conditions section, you can provide an external URL
which will open the required section in a new window rather than opening the section in the same window.
Note: If you specify an External URL, the URL opens in a new window.
Syntax
JavaScript: externalURL
Lua: externalurl
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for a button with externalURL: http://www.konyso
lutions.com.
var btnPSP={externalURL: http://www.konysolutions.com };
Accessible from IDE

Yes
Available on Server side Mobile Web (advanced) platform only.
11.3.4 glowEffect
Specifies if there must be glow effect when you touch the button.
Default: false
If set to false, the button will not have glow effect.
If set to true, the button will have glow effect.
Note: The glow appears on the button only for a moment on touch and disappears.
The following image illustrates a button with and without the glow effect:
Syntax
JavaScript: glowEffect
Lua: gloweffect
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with glowEffect:true.
var btnPSP={glowEffect:true};
Accessible from IDE

Yes
l
iPad
iPhone
11.3.5 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
11.3.6 pressedSkin
Specifies the skin to indicate that the Button is pressed or clicked.
Note: If you do not specify pressedSkin, the focusSkin is applied.
Syntax
JavaScript: pressedSkin
Lua: pressedskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a button with pressedSkin:"presSkin"
var btnPSP={pressedSkin:"presSkin"};
Accessible from IDE

Yes
Available on Android/Android Tablet
Specifies if the progress indicator must be displayed when the button is clicked. This is typically set to true, if
it is known at design time that the button onClick event handling is going to trigger a long running call.
Default: true
The following image illustrates the progress indicator on iPhone:
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with showProgressIndicator:true
var btnPSP={showProgressIndicator:true};
Accessible from IDE

Yes
l
iPad
iPhone
11.3.8 submitURL
Specifies the URL to which the current Form data should be submitted, without contacting Kony Server. This
is typically required when the data collection is done using Kony Studio Form but is actually posted to a thirdparty site.
Default: false
If set to false, then the URL is submitted contacting the Kony Server.
If set to true, then the URL is submitted without contacting the Kony Server.
For example, for an application that requires the user to provide confidential data, you can route the data
directly to the server of the website without contacting the Kony Server using the externalURL property. Doing
so, opens the resultant site in the same window rather than opening it in a new window.
Syntax
JavaScript: submitURL
Lua: submiturl
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a button with submitURL:http://www.konysolut
ions.com
var btnPSP={submitURL:http://www.konysolutions.com };
Accessible from IDE

Yes
Available on Server side Mobile Web (advanced) platform only.
11.3.9 toolTip
Specifies the hint text when the cursor hovers over a widget, without clicking it. The text entered in the tooltip
appears as a small box when the cursor hovers over a widget.
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a button with toolTip:sample text
FSkin", text:"Click Here" };
var btnPSP={toolTip:"sample text"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
11.4 Button - Events

Button has the following events associated with it:
l
onClick
preOnclickJS
postOnclickJS
11.4.1 onClick
An event callback is invoked by the platform when the user performs a click action on the button.
Signature
JavaScript: onClick
Lua: onclick
The onClick event callback accepts additional parameters when a button is placed in a segment row or
section template.
Signature
Input Parameters
Index of the row that contains the button. It is not available if the button is placed in a section
header.
Index of the section row that contains the button.
Handle to the widget instance that contains the button.
Read / Write
JavaScript Example
//The below function is the callback function for onClick event call.
function onClickCallBack(button)
{
}
//Defining the properties for a button with onClick:onClickCallBck.
FSkin", text:"Click Here", onClick:onClickCallBck};
var btnPSP={};
Accessible from IDE

Yes
11.4.2 preOnclickJS
This event allows the developer to execute custom JavaScript function before the onClick callback of the
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for preOnclickJS event call.
function preOnclickJSCalBck(button)
{
}
//Defining the properties for a button with preOnclickJS:preOnclickJSCalBc
k.
var btnPSP={preOnclickJS:preOnclickJSCalBck};
//Reading preOnclickJS of the button.
alert("Button preOnclickJS ::"+button1.preOnclickJS);
Accessible from IDE

Yes
This event allows the developer to execute custom JavaScript function after the onClick callback of the
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for postOnclickJS event call.
function postOnclickJSCalBck(button)
{
}
//Defining the properties for a button with postOnclickJS:postOnclickJSCal
Bck
var btnPSP={postOnclickJS:postOnclickJSCalBck};
//Reading postOnclickJS of the button
alert("Button postOnclickJS ::"+button1.postOnclickJS);
Accessible from IDE

Yes
11.5 Button - Deprecated Properties

The deprecated properties for Button widget are as follows:
l
focusimage
image
normalimage
11.5.1 focusimage
This is a skin property and it determines the look and feel of the button when there is focus.
You can also choose to specify a background focus image for the button.
Type
Object
Read / Write
Yes (Write only)
Accessible from IDE

Yes
11.5.2 image
Specifies the image to be applied to a button as background image.
Type
Object
Read / Write
Yes (Write only)
Accessible from IDE

Yes
11.5.3 normalimage
This is a skin property and it determines the look and feel of the button when the button is not focussed.
Type
Object
Read / Write
Yes (Write only)
Accessible from IDE

Yes
12. Calendar
Calendar widget allows you to select a date from a graphical calendar. The calendar widget appears as a label
with a small calendar icon (icon does not appear on Mobile Web platforms) and displays the date or the date
format specified by you. You can interact with the calendar widget by clicking on it.
Note: When the native calendar view is used the individual dates cannot be set as enabled or disabled using
the setEnable API. Also the user cannot be restricted to dates only within the validStartDate and
validEndDate range.
When the calendar widget is clicked, a grid like calendar widget is displayed (The appearance is not the same
on all platforms. For exact appearance, see UI Behavior). The grid like calendar allows you to select a single
date and move back-and-forth between months and years.
Calendar provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
Events, and Methods.
Platform Specific
Properties
Basic Properties
Layout Properties
calenderIcon
dateComponents
dateFormat
day
focusSkin
formattedDate
hour
id
info
isVisible
minutes
month
placeholder
seconds
skin
validStartDate
validEndDate
viewConfig
viewType
year
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
cellTemplate
containerHeight
dateEditable
data
dayTextAlignmentInCell
displayedMonth
hideDaysHeader
hideMonthsHeader
hoverSkin
mode
noOfMonths
titleOnPopup
toolTip
widgetDataMapForCell
Events
Methods
Deprecated
onSelection
clear
clearData
enableRangeOfDates
navigateToPreviousMonth
navigateToNextMonth
removeDataAt
setData
setDataAt
setEnabled
date
format
monthI18Nkey
weekdayI18Nkey
Events
Methods
Deprecated
setEnableAll
setDateSkin
Creating a Calendar using a constructor: kony.ui.Calendar

var mycal = new kony.ui.Calendar(basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//The below function is the callback function for onSelection event
function onSelectionCallBck(calendar)
{
alert("onSelection event triggered");
}
//Defining the properties for Calendar with onSelection:onSelectionCallBck
var calBasicConf = {id: "calID", isVisible:true, skin:"konytextar", focusS
kin:"calFocus", dateFormat:"dd/MM/yyyy", viewType:constants.CALENDAR_VIEW_
TYPE_GRID_POPUP, validStartDate:[01,01,2012], validEndDate:[31,12,2012], p
laceholder:"JSCalendar", calendarIcon:"cal.png", onSelection:onSelectionCa
llBck};
var calLayoutConf = {padding : [2,2,2,2], margin:[5,5,5,5],containerWeight
:100, hExpand:true, vExpand:true};
var calPSPConf = {titleOnPopup:"CalenderPopUpTitle"};
//Creating the Calendar.
var Calendar = new kony.ui.Calendar(calBasicConf, calLayoutConf, calPSPCon
f);
//Reading the titleOnPopup property of calendar widget
alert("Calendar titleOnPopup ::"+Calendar.titleOnPopup);

The appearance of the calendar widget on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
iPhone
Windows Phone
Mobile Web (BJS)
UI Behavior
When you click a calendar widget, the UI behavior is not the same on all the platforms.
The UI behavior of a calendar widget on various platforms is as follows:
Platform
UI Behavior
Android
BlackBerry
Platform
UI Behavior
iPhone
Windows Phone
Platform
UI Behavior
Mobile Web (BJS)
Adding a Calendar Widget from IDE

The steps involved in adding a calendar widget are as follows:
1. From the IDE, drag and drop the calendar widget onto a form (occupies the complete available width).
Or, based on your requirements, you can choose to perform any of the following options:
a. If you want to resize the calendar widget in the horizontal direction, place an HBox on the
Form and drag and drop the calendar widget inside the HBox and resize accordingly.
b. If you want to resize the calendar widget in the vertical direction, place an HBox on the
Form and place a VBox inside the HBox; and drag and drop the calendar widget inside
the VBox and resize accordingly.
2. (Optional) Use the dateComponents property to specify the default date that must appear in the Date
field.
3. Use the dateFormat property to specify the date format.
You can customize the appearance of the calendar widget by using the following properties:
l
The Calendar widget has the following important considerations for Mobile Web:
l
The default height of calendar widget is 28px.
If you apply padding to a Calendar widget for Mobile web the default height set for a calendar widget
(28px) is ignored.
If you do not specify an image for popup view then a default image is provided.
On BlackBerry platform, when the native calendar view is used the individual dates cannot be set as
enabled or disabled using the setEnable API. Also the user cannot be restricted to dates only within the
validStartDate and validEndDate range.
On Android platform, restricting the date selection between validStartDate and validEndDate is not
possible with Native Calendar View.
On Desktop Web and SPA platforms, a valid calendar year selection range is from 1900 to 2099. If you
select an year beyond the range shows an alert message (you can customize this error message).
12.1 Calendar - Basic Properties

The basic properties of Calendar Widget are as follows:
l
calendarIcon
dateComponents
dateFormat
day
focusSkin
formattedDate
hour
id
info
isVisible
minutes
month
placeholder
seconds
skin
validStartDate
validEndDate
viewConfig
viewType
year
12.1.1 calendarIcon
Replaces the system default calendar icon. It is applicable only when the viewType is set as CALENDAR_
VIEW_TYPE_GRID_POPUP.
Syntax
JavaScript: calendarIcon
Lua: calendaricon
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with calendarIcon:"cal.png".
var calBasicConf = {id : "calID", isVisible:true, skin:"konytextar",focusS
laceholder:"JSCalendar", calendarIcon:"cal.png"};
var calLayoutConf = {containerWeight:100};
var calPSPConf = {};
//Creating the Calendar
f);
//Reading the calendar.Icon property of calendar widget.
alert("Calendar Icon is ::"+Calendar.calendarIcon;
Accessible from IDE

Yes
Available on all platforms except Windows Phone, Windows Tablet, and BlackBerry 10.
12.1.2 dateComponents
Specifies the default date that must appear in the Date field. The value should be an array object with six
elements in [dd, mm, yyyy, hh, mm, ss] format.
If a platform or the particular calendar view doesn't support the user to set the hh, mm, ss then they always
are set 00:00:00 by default irrespective of what developer sets. Individual platforms need to cross check this
per view basis and add it to the final documentation.
To specify a date for the calendar
) button against the Date property. The following popup appears:
2. Clear the Set date and time to 'NONE' option. The following popup appears:
3. Select the require date and time (optional and applicable only for iPhone). Click OK.
The selected date will appear in the calendar when rendered.
Syntax
JavaScript: dateComponents
Lua: datecomponents
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Calendar with date:[31,12,2012]
var calBasicConf = {id : "calID", isVisible:true, dateComponents:[31,12,20
12,04,30,55], skin:"konytextar", focusSkin:"calFocus", dateFormat:"dd/MM/y
yyy", viewType:constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:[01
,01,2012], validEndDate:[31,12,2012], date:[31,12,2012], placeholder:"JSCa
lendar", calendarIcon:"cal.png"};
f);
//Reading the dateComponents property of calendar widget.
alert("Calendar dateComponents ::"+Calendar.dateComponents);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web platform.
12.1.3 dateFormat
The date format in which the selected date must appear on the display and when accessed programmatically
the "date" property.
The possible supported date formats are:
l
MM/dd/yyyy
dd/MM/yyyy (default)
MM/dd/yy
Note: Above are the date formats that will be shown in IDE, but developer can pass the format as any one of
the Unicode supported Date Formats.
For list of standard characters and formats, please see the following link.
http://unicode.org/reports/tr35/tr35-6.html#Date_Format_Patterns
Syntax
JavaScript: dateFormat
Lua: dateformat
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with dateFormat:"dd/MM/yyyy"
12,04,30,55],skin:"konytextar", focusSkin:"calFocus", dateFormat:"dd/MM/yy
yy", viewType:constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:[01,
01,2012], validEndDate:[31,12,2012], date:[31,12,2012], placeholder:"JSCal
endar", calendarIcon:"cal.png"};
f);
//Reading the dateFormat property of calendar widget
alert("Calendar dateFormat ::"+Calendar.dateFormat);
Accessible from IDE

Yes
Available on all platforms except Windows Kiosk and BlackBerry 10 platforms
12.1.4 day
Reads the day portion of the currently selected date.
Syntax
JavaScript: day
Lua: day
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
var calBasicConf = {id : "calID", isVisible:true, skin:"konytextar", focus
Skin:"calFocus", dateFormat:"dd/MM/yyyy", viewType:constants.CALENDAR_VIEW_
TYPE_GRID_POPUP, validStartDate:[01,01,2012], validEndDate:[31,12,2012],da
te:[31,12,2012], placeholder:"JSCalendar", calendarIcon:"cal.png"};
f);
//Reading the day property of calendar widget
alert("Calendar day ::"+Calendar.day);
Accessible from IDE

Yes
12.1.5 focusSkin
1. On J2ME, if you do not specify the Focus skin, it will not possible to identify the traversal.
2. Mobile Web does not support this property. For Advanced Mobile Web platforms, a platform specific
progress indicator is displayed. For other Mobile Web platforms (Basic and BJS), the screen is refreshed.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with focusSkin:"calFocus"
f);
//Reading the focusSkin property of calendar widget
alert("Calendar focusSkin ::"+Calendar.focusSkin);
Accessible from IDE

Yes
Available on all platforms except on all Mobile Web, BlackBerry 10, and Windows Kiosk
12.1.6 formattedDate
Currently selected data as String the format that is set through "dateFormat" property.
Syntax
JavaScript: formattedDate
Lua: formatteddate
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Calendar with dateFormat:"dd/MM/yyyy".
f);
//Reading the formattedDate property of calendar widget.
alert("Calendar formattedDate ::"+Calendar.formattedDate);
Accessible from IDE

Yes
12.1.7 hour
Reads the hour portion of the currently selected date.
Syntax
JavaScript: hour
Lua: hour
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
var calBasicConf = {id : "calID", isVisible:true,
skin:"konytextar",focusSkin:"calFocus", dateFormat:"dd/MM/yyyy", viewType:

constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:[01,01,2012], vali
dEndDate:[31,12,2012], date:[31,12,2012], placeholder:"JSCalendar",calenda
rIcon:"cal.png"};
f);
//Reading the hour property of calendar widget.
alert("Calendar hour ::"+Calendar.hour);
Accessible from IDE

Yes
Available on all platforms except Windows Phone, BlackBerry 10, and Windows Kiosk platform.
12.1.8 id
Defines a string of alpha numeric characters that uniquely identifies a calendar widget within an application.
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Calendar with id:"calendar1".
var calBasicConf = {id : "calendar1", isVisible:true, skin:"konytextar",fo
cusSkin:"calFocus", dateFormat:"dd/MM/yyyy", viewType:constants.CALENDAR_V
IEW_TYPE_GRID_POPUP, validStartDate:[01,01,2012], validEndDate:[31,12,201
2], placeholder:"JSCalendar", calendarIcon:"cal.png"};

var calendar1 = new kony.ui.Calendar(calBasicConf, calLayoutConf, calPSPCo
nf);
//Reading the id property of calendar widget
alert("Calendar Id ::"+calendar1.id);
Accessible from IDE

Yes
12.1.9 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Calendar with info property.
var calendar1 = new kony.ui.Calendar(calBasicConf, calLayoutConf, calPSPCo
nf);
calendar1.info = {key:"caldate"};
//Reading the info property of calendar widget.
alert("Calendar info is ::"+calendar1.info);
Accessible from IDE

No
12.1.10 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Calendar with isVisible:true.
var calBasicConf = {id : "calendar1", isVisible:true, skin:"konytextar", f
ocusSkin:"calFocus", dateFormat:"dd/MM/yyyy", viewType:constants.CALENDAR_
VIEW_TYPE_GRID_POPUP, validStartDate:[01,01,2012], validEndDate:[31,12,201
var calendar1= new kony.ui.Calendar(calBasicConf, calLayoutConf, calPSPCon
f);
//Reading the isVisible property of calendar widget
alert("Calendar isVisible ::"+calendar1.isVisible);
Accessible from IDE

12.1.11 minutes
Reads the minutes portion of the currently selected date.
Syntax
JavaScript: minutes
Lua: minutes
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
var calBasicConf = {id : "calendar1", isVisible:true,
skin:"konytextar",focusSkin:"calFocus", dateFormat:"dd/MM/yyyy", viewType:

constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:[01,01,2012], vali
dEndDate:[31,12,2012], date:[31,12,2012], placeholder:"JSCalendar", calend
arIcon:"cal.png"};
f);
//Reading the minutes property of calendar widget.
alert("Calendar minutes ::"+calendar1.minutes);
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango), BlackBerry 10, and Windows Kiosk platform.
12.1.12 month
Reads the month portion of the currently selected date.
Syntax
JavaScript: month
Lua: month
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
2], date:[31,12,2012], placeholder:"JSCalendar", calendarIcon:"cal.png"};

f);
//Reading the month property of calendar widget
alert("Calendar month ::"+calendar1.month);
Accessible from IDE

Yes
12.1.13 placeholder
Specifies the temporary or substitute text that must be displayed until a date is selected.
For example, you can display the placeholder text on the calendar widget as "Enter your date of travel", until
the user clicks the calendar widget and selects a date.
Syntax
JavaScript: placeholder
Lua: placeholder
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with placeholder:"JSCalendar".
var calBasicConf = {id : "calendar1", isVisible:true, dateComponents:[31,1
2,2012,04,30,55], skin:"konytextar", focusSkin:"calFocus", dateFormat:"dd/
MM/yyyy", viewType:constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:
[01,01,2012], validEndDate:[31,12,2012], date:[31,12,2012], placeholder:"J
SCalendar", calendarIcon:"cal.png"};

f);
//Reading the placeholder property of calendar widget
alert("Calendar placeholder ::"+calendar1.placeholder);
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango) (IE9 version), Windows Kiosk, BlackBerry
10, and on Server side Mobile Web (WindowsNTH, Basic, and BJS)
12.1.14 seconds
Reads the seconds portion of the currently selected date.
Syntax
JavaScript: seconds
Lua: seconds
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
var calendar1= new kony.ui.Calendar(calBasicConf, calLayoutConf,
calPSPConf);
//Reading the seconds property of calendar widget.
alert("Calendar seconds ::"+calendar1.seconds);
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango), BlackBerry 10, and Windows Kiosk
platforms.
12.1.15 skin
Specifies a background skin for Calendar.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with skin:"konytextar"
f);
//Reading the skin property of calendar widget
alert("Calendar skin ::"+calendar1.skin);
Accessible from IDE

Yes
12.1.16 validStartDate
Array representing the day, month and year portions of the date in the same order. The valid start date,
accepts Array of [dd, mm, yyyy, hh, mm, ss]
If a platform or the particular calendar view doesn't support the user to set the hh,mm,ss then they always are
set 00:00:00 by default irrespective of what developer sets. Individual platforms need to cross check this per
view basis and add it to the final documentation.
For backward compatibility atleast three elements [dd,mm,yyyy] are mandatory from all the six elements.
Syntax
JavaScript: validStartDate
Lua: validstartdate
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Calendar with validStartDate:[01,01,2012]
var calendar1= new kony.ui.Calendar(calBasicConf, calLayoutConf,
calPSPConf);
//Reading the validStartDate property of calendar widget
alert("Calendar validStartDate ::"+calendar1.validStartDate);
Accessible from IDE

Yes
Available on all platforms except Windows Kiosk platform
12.1.17 validEndDate
Array representing the day, month and year portions of the date in the same order. The valid end date, accepts
Array of [dd, mm, yyyy, hh,mm,ss]
If a platform or the particular calendar view doesn't support the user to set the hh,mm,ss then they always are
set 00:00:00 by default irrespective of what developer sets. Individual platforms need to cross check this per
view basis and add it to the final documentation.
For backward compatibility atleast three elements [dd,mm,yyyy] are mandatory from all the six elements.
Syntax
JavaScript: validEndDate
Lua: validenddate
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Calendar with validEndDate:[31,12,2012]
f);
//Reading the validEndDate property of calendar widget
alert("Calendar validEndDate ::"+calendar1.validEndDate);
Accessible from IDE

Yes
12.1.18 viewConfig
The view configuration for different viewtypes. Each view will have a key representing the view name and the
value being the hash of key, value configurations.
Note: For iOS platform, the option "allowWeekendSelectable" is not applicable when the calendar view
type is set as wheelCalendar.
Possible hash of key value configurations for Grid Views:
l
CALENDAR_VIEW_TYPE_ GRID_ONSCREEN
CALENDAR_VIEW_TYPE_ GRID_POPUP
The possible keys are defined below:

"gridSkin" - The skin for grid calendar
"gridCellSkin" - The grid calendar cell skin
"gridCellFocusSkin" - The grid calendar cell focus skin
"gridCellSelectedSkin" - The grid calendar cell selected skin
"gridCellTodaySkin" - The grid calendar today cell skin
"gridCellWeekendSkin" - The grid calendar skin for weekend days
"gridCellInactiveDaysSkin" - The grid calendar skin for non-working inactive days

"leftNavigationImage" - The image to be set on the button that moves calendar to previous month
"rightNavigationImage" - The image to be set on the button that moves calendar to next month
"allowWeekendSelectable" - The Boolean flag to disable or enable the weekend days. If the value is false
i.e., disabled, then gridCellInactiveDaysSkin is applied.
"doneButtonSkin" - The skin to be applied on the Done button that appear on a calendar popup, which ever
platform done button is applicable. It is not supported on Windows Phone (Mango) platform.
"cancelButtonSkin" - The skin to be applied on a Cancel button that appear on a calendar popup, which ever
platform cancel button is applicable. It is not supported on Windows Phone (Mango) platform.
Syntax
Lua: viewconfig
Type
Lua: UserData
Read / Write
JavaScript Example
//Creating viewConfig object for gridView type
var gridConfig = {gridConfig:{gridSkin:"gridSkin", gridCellSkin:"gridCellS
kin", gridCellFocusSkin:"gridCellFocusSkin", gridCellSelectedSkin:"gridCel
lSelectedSkin", gridCellTodaySkin:"gridCellTodaySkin", gridCellWeekendSkin
:"gridCellWeekendSkin", gridCellInactiveDaysSkin:"gridCellInactiveDaysSki
n", gridDaysSkin:"gridDaysSkin", gridMonthSkin:"gridMonthSkin", allowWeeke
ndSelectable:false}}
//Defining the properties for Calendar with viewConfig:gridConfig.
var calBasicConf = {id : "basicCalFrmt", isVisible:true, skin:"calFocus",
focusSkin:"konytextar", dateFormat:"dd/MM/yy", viewType:constants.CALENDAR_
VIEW_TYPE_GRID_ONSCREEN, viewConfig:gridConfig, validStartDate:[01,01,201
2], validEndDate:[31,12,2012], placeholder:"JSCalendar", calendarIcon:"cal
.png"};
var calLayoutConf = {padding : [2,2,2,2], margin:[5,5,5,5], widgetAlignmen
t:constants.WIDGET_ALIGN_TOP_RIGHT, containerWeight:100, hExpand:true, vEx
pand:true};
f);
Accessible from IDE

Yes
12.1.19 viewType
Specifies the view type of the Calendar.
Note: On Android and BlackBerry platforms, when the viewType is set as CALENDAR_VIEW_TYPE_
DEFAULT, the user cannot be restricted to select the dates within the validStartDate and validEndDate.
The below table shows the list of view types and their availability in different platforms:
viewType
Android /
iOS BlackBe
rry
Windows
Phone
Server side Server side

Mobile Web Mobile Web
(BJS)
(Advanced)
SPA
/Desktop
Web
/Windows
Kiosk
CALENDAR_VIEW_TYPE_DEFAULT
Yes
Yes
Yes*
Yes*
Yes*
Yes *
CALENDAR_VIEW_TYPE_GRID_
ONSCREEN
Yes
Yes
Yes
No
No
No
CALENDAR_VIEW_TYPE_GRID_POPUP
Yes
Yes*
Yes
No
Yes
Yes
viewType
CALENDAR_VIEW_TYPE_WHEEL_
ONSCREEN
CALENDAR_VIEW_TYPE_WHEEL_
POPUP
CALENDAR_VIEW_TYPE_LISTBOXES_
ONSCREEN
CALENDAR_VIEW_TYPE_LISTBOXES_
POPUP
CALENDAR_VIEW_TYPE_METRO
Android /
iOS BlackBe
rry
Windows
Phone
Server side Server side

Mobile Web Mobile Web
(BJS)
(Advanced)
SPA
/Desktop
Web
/Windows
Kiosk
Yes
No
No
No
No
No
Yes*
No
No
No
No
No
No
No
No
Yes
Yes
No
No
No
No
No
No
No
No
No
Yes
No
No
No
Note: * indicates the default option in respective platforms.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Calendar with viewType as GRID_POPUP
[01,01,2012], validEndDate:[31,12,2012],date:[31,12,2012], placeholder:"JS
Calendar", calendarIcon:"cal.png"};
f);
//Reading the viewType property of calendar widget
alert("Calendar viewType ::"+calendar1.viewType);
Accessible from IDE

Yes
Available on all platforms except BlackBerry 10 and Windows Kiosk platforms
12.1.20 year
Reads the year portion of the currently selected date.
Syntax
JavaScript: year
Lua: year
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
f);
//Reading the year property of calendar widget.
alert("Calendar year ::"+calendar1.year);
Accessible from IDE

Yes
12.2 Calendar - Layout Properties

The Layout properties for Calendar Widget are as follows:
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a calendar with containerWeight:80.
t:constants.WIDGET_ALIGN_TOP_RIGHT, containerWeight:80, hExpand:true,vExpa
nd:true};
//Creating the calendar.
f);
Accessible from IDE

No
Specifies the alignment of the text on the Calendar with respect to its boundaries. A default value CONTENT_
center of the Calendar)
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the Calendar.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the Calendar.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the Calendar.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the Calendar.
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the Calendar.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the Calendar.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the Calendar.

Calendar.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the Calendar.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a calendar with contentAlignment as MIDDLE_L
EFT
t:constants.WIDGET_ALIGN_TOP_RIGHT, containerWeight:100, hExpand:true,vExp
and:true,contentAlignment:constants.CONTENT_ALIGN_MIDDLE_LEFT};
f);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (Blackberry BJS device) and BlackBerry 10
platforms.
12.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a calendar with hExpand:true
pand:true};
var Calendar = new kony.ui.Calendar(calBasicConf, calLayoutConf,
calPSPConf);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and SPA.
12.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a calendar with margins [5,5,5,5].
Skin:"calFocus", dateFormat:"dd/MM/yyyy", placeholder:"JSCalendar", calend
arIcon:"cal.png"};
pand:true};
f);
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a calendar with margin in pixels.
Skin:"calFocus", dateFormat:"dd/MM/yyyy", placeholder:"JSCalendar", calend
arIcon:"cal.png"};
and:true, marginInPixel: true};
f);
Accessible from IDE

Yes
l
iPhone
iPad
12.2.6 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a calendar with padding : [2,2,2,2]
and:true};
f);
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a calendar with padding in pixels.
pand:true, paddingInPixel:true};
f);
Accessible from IDE

Yes
l
iPhone
iPad
12.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a calendar with vExpand:true
and:true};

f);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and BlackBerry 10 platforms. On BlackBerry
platform, this property is not supported if the view mode is set as CALENDAR_VIEW_TYPE_WHEEL_
ONSCREEN.
Horizontal alignment attributes are only applicable if hExpand is false.
l
WIDGET_ALIGN_MIDDLE_CENTER
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a calendar with widgetAlignmentas TOP_RIGHT
var calLayoutConf = {padding : [2,2,2,2],
widgetAlignment:con
stants.WIDGET_ALIGN_TOP_RIGHT, containerWeight:100, hExpand:true,vExpand:t
rue};
f);
Accessible from IDE

Yes
12.3 Calendar-Platform Specific Properties

The Platform Specific Properties of Calendar Widget are as follows:
l
cellTemplate
containerHeight
dateEditable
data
dayTextAlignmentInCell
displayedMonth
hideDaysHeader
hideMonthsHeader
hoverSkin
mode
noOfMonths
titleOnPopup
toolTip
widgetDataMapForCell
12.3.1 cellTemplate
This property is available only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or
CALENDAR_VIEW_TYPE_GRID_ONSCREEN. It specifies the common template to be used for a
Calendar Day cell. A template can be used only when the data is present for a Calendar Day cell set through
data property or setData method. If the data is not set to a cell, the cell is displayed with the default look
without any template.
Default: None
Syntax
JavaScript: cellTemplate
Type
JavaScript: kony.ui.Box - [Mandatory]
Read / Write
JavaScript Example
//Defining the properties for Calendar with cellTemplate:calcellTemplate
TYPE_WHEEL_ONSCREEN, validStartDate:[01,01,2012], validEndDate:[31,12,201
and:true};
var calPSPConf = {titleOnPopup:"CalenderPopUpTitle", mode:constants.CALEDE
R_WHEEL_ONLY_TIME, hideDaysHeader:false, cellTemplate:calcellTemplate};
f);
//Reading the cellTemplate property of calendar widget
alert("Calendar cellTemplate::"+Calendar.cellTemplate);
Accessible from IDE

Yes
l
iPhone
iPad
CALENDAR_VIEW_TYPE_GRID_ONSCREEN. It specifies the available height of the container in terms of
percentage. The percentage is with reference to the value of containerHeightReference property.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Calendar with containerHeight:100
and:true};
R_WHEEL_ONLY_TIME, hideDaysHeader:false, containerHeight:100, containerHei
ghtReference: constants.CALENDAR_HEIGHT_BY_FORM_REFERENCE, cellTemplate:ca
lcellTemplate};
f);
Accessible form IDE

Yes
l
iPhone
iPad
CALENDAR_VIEW_TYPE_GRID_ONSCREEN and when you set the containerHeight.
Default: HEIGHT_BY_FORM_REFERENCE
l
HEIGHT_BY_FORM_REFERENCE: The Calendar height is percentage calculated based on the

height of the Form excluding headers and footers.
HEIGHT_BY_PARENT_WIDTH: Use this option if the Calendar is placed inside a Box. The width is
calculated based on the width of the Box.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Calendar with containerHeightReference: cons
tants.HEIGHT_BY_FORM_REFERENC
and:true};
ghtReference: constants.HEIGHT_BY_FORM_REFERENCE, cellTemplate:calcellTemp
late};
f);
//Reading the containerHeightReference property of calendar widget
alert("Calendar containerHeightReference::"+Calendar.containerHeightRefere
nce);
Accessible from IDE

Yes
l
iPhone
iPad
12.3.4 dateEditable
This property determines whether the calendar date must be entered in the calendar textbox. Normally a user
can enter date by choosing the date icon or entering the date in the textbox. Set this property to false, to avoid
user from entering the date in textbox and allow the user to select the date only through icon.
Default: true
If set to true, the calendar textbox is editable.
If set to false, the calendar textbox is not editable.
Syntax
JavaScript: dateEditable
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for Calendar with dateEditable: false
and:true};
ghtReference: constants.HEIGHT_BY_FORM_REFERENCE, dateEditable:false};
f);
//Reading the dateEditable property of calendar widget
alert("Calendar dateEditable::"+Calendar.dateEditable);
Accessible from IDE

No
This property is available on Desktop Web platform
12.3.5 data
A JSObjects that represents the actual data to be rendered in each cell.
Format of the data is as follows:
var data1 = {
"12/11/2012":{
template:newBox
lblAppointments:"4",
lblTasks:"2"
},
"02/01/2012":{
"lblAppointments":"4",
"lblTasks":"21"
}
}
frmHome.mycal.setData(data1);
To specify the data, follow these steps:

window appears.
) button against the cellTemplate property. The Select/Search gridCalendars
2. Select the template and click OK. The template is now assigned to a calendar.
appears.
4. Click
) button against the data property.The Master Data for GridCalendar window
button to add a row and select the Date and then update Template Data.
5. Click OK.
Syntax
JavaScript: data
Type
Read / Write
JavaScript Example
//Defining the properties for Calendar with data.
Accessible from IDE

Yes
l
iPhone
iPad
12.3.6 dayTextAlignmentInCell
CALENDAR_VIEW_TYPE_GRID_ONSCREEN. It specifies the alignment of the text for a Calendar Day
cell with respect to its boundaries. The default value is CONTENT_ALIGN_CENTER. To choose another
alignment, click the drop-down arrow next to the property and select the desired alignment.
Default: CONTENT_ALIGN_CENTER (content is aligned at the center of the Calendar)
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the Calendar Day
cell.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the Calendar Day
cell.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the Calendar Day cell.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the Calendar Day
cell.
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the Calendar Day cell.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the Calendar
Day cell.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the Calendar
Day cell.

Calendar Day cell.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the Calendar
Day cell.
Syntax
JavaScript: dayTextAlignmentInCell
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Calendar with dayTextAlignmentInCell:constan
ts.CONTENT_ALIGN_MIDDLE_LEFT
and:true};
R_WHEEL_ONLY_TIME, hideDaysHeader:false, dayTextAlignmentInCell:constants.
CONTENT_ALIGN_MIDDLE_LEFT};
f);
//Reading the dayTextAlignmentInCell property of calendar widget
alert("Calendar dayTextAlignmentInCell::"+Calendar.dayTextAlignmentInCell);
Accessible from IDE

Yes
l
iPhone
iPad
12.3.7 displayedMonth
This property is applicable only when viewType is set as CALENDAR_VIEW_TYPE_GRID_POPUP or
CALENDAR_VIEW_TYPE_GRID_ONSCREEN. It sets or gets the current displayed month and year of the
calendar. Using this property you can change the current month and year. For example, if you want to show
January, 2013 using displayedMonth is displayed as [1,2013].
Default: The default value is as defined in dateComponents and get modified each time when the date is
changed in dateComponents.
Note: Modifying the displayedMonth will not have any influence on dateComponent property.
Syntax
JavaScript: displayedMonth
Type
JavaScript: Array with month and year
Read / Write
JavaScript Example
//Defining the properties for Calendar with displayedMonth:[1,2013]
and:true};
R_WHEEL_ONLY_TIME, hideDaysHeader:false, displayedMonth:[1,2013]};
f);
//Reading the dayTextAlignmentInCell property of calendar widget
alert("Calendar dayTextAlignmentInCell::"+Calendar.dayTextAlignmentInCell);
Accessible from IDE

No
l
iPhone
iPad
12.3.8 hideDaysHeader
CALENDAR_VIEW_TYPE_GRID_ONSCREEN. It indicates if the weekdays are hidden on the header for
grid calendar.
Default: false
If set to true, the weekdays are hidden and are not displayed.
If set to false, the weekdays are displayed.
Syntax
JavaScript: hideDaysHeader
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for Calendar with hideDaysHeader:false
TYPE_GRID_ONSCREEN, validStartDate:[01,01,2012], validEndDate:[31,12,2012],
placeholder:"JSCalendar", calendarIcon:"cal.png"};
and:true};
R_WHEEL_ONLY_TIME, hideDaysHeader:false};
f);
//Reading the hideDaysHeader property of calendar widget
alert("Calendar hideDaysHeader::"+Calendar.hideDaysHeader);
Accessible from IDE

Yes
l
iPhone
iPad
12.3.9 hideMonthsHeader
CALENDAR_VIEW_TYPE_GRID_ONSCREEN. It indicates if the months header is hidden for grid calendar
including the navigation buttons.
Default: false
If set to true, the months header is hidden and the navigation buttons are not displayed.
If set to false, the months header is displayed.
Syntax
JavaScript: hideMonthsHeader
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for Calendar with hideMonthsHeader:false.
TYPE_GRID_ONSCREEN, validStartDate:[01,01,2012], validEndDate:[31,12,2012],
and:true};
R_WHEEL_ONLY_TIME, hideMonthsHeader:false};
f);
//Reading the hideMonthsHeader property of calendar widget
alert("Calendar hideMonthsHeader::"+Calendar.hideMonthsHeader);
Accessible from IDE

Yes
l
iPhone
iPad
12.3.10 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE

Yes
12.3.11 mode
Specifies the mode in which the calendar is used.
l
CALENDAR_VIEW_TYPE_WHEEL_ONSCREEN (applicable on WHEEL mode only)
CALENDAR_VIEW_TYPE_WHEEL_POPUP (applicable on WHEEL mode only)
CALENDAR_WHEEL_ONLY_DATE (Default)
CALENDAR_WHEEL_ONLY_TIME
CALENDAR_WHEEL_BOTH_DATETIME
Syntax
JavaScript: mode
Lua: mode
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with mode:constants.CALEDER_WHEEL_O
NLY_TIME

and:true};
R_WHEEL_ONLY_TIME};
f);
//Reading the mode property of calendar widget
alert("Calendar mode ::"+Calendar.mode);
Accessible from IDE

Yes
l
iPhone
iPad
12.3.12 noOfMonths
Specifies the number between 1 and 12 which indicates the number of months to be displayed when the
calendar is selected. It is supported only on Desktop Web platform.
Syntax
JavaScript: noOfMonths
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Calendar with noOfMonths:5
TYPE_WHEEL_ONSCREEN, validStartDate:[01,01,2012], validEndDate:
[31,12,2012], placeholder:"JSCalendar", calendarIcon:"cal.png"};

and:true};
R_WHEEL_ONLY_TIME, noOfMonths:5};
f);
//Reading the noOfMonths property of calendar widget
alert("Calendar noOfMonths::"+Calendar.noOfMonths);
Accessible from IDE

Yes
12.3.13 titleOnPopup
Specifies the title text to be displayed on the calendar popup.
Syntax
JavaScript: titleOnPopup
Lua: titleonpopup
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Calendar with titleOnPopup:"Calender PopUp T
itle"
TYPE_GRID_POPUP,validStartDate:[01,01,2012], validEndDate:[31,12,2012],
and:true};
var calPSPConf = {titleOnPopup:"Calender PopUp Title"};
f);
Accessible from IDE

Yes
l
Desktop Web
SPA
Server side Mobile Web (BJS and Advanced)
12.3.14 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a calendar with toolTip:sample text
var calBasic={id:"calendar1", isVisible:true, skin:"calSkin", focusSkin:"c
alFSkin", text:"Click Here", toolTip:"sample text"};
var calLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hEx
var calPSP={};
var calendar1 = new kony.ui.Calendar(calBasic, calLayout, calPSP);
Accessible from IDE

Yes
12.3.15 widgetDataMapForCell
Specifies the mapping information between the widget id's and the keys in the data.
Note: It is the developer responsibility to ensure that widget data map to accommodate all the widget ids
required including the widgets referred in dynamic templates.
{
widgetID1:
widgetId2:
widgetId3:
widgetId4:
widgetId5:
}
"dataId1",
"dataId2",
"dataId3",
"secDataId1"
"secDataId2"
Syntax
JavaScript: widgetDataMapForCell
Type
JavaScript: Array with month and year
Read / Write
JavaScript Example
//Defining the properties for a calendar with widgetDataMapForCell
var calBasic={id:"calendar1", isVisible:true, skin:"calSkin", focusSkin:"c
alFSkin", text:"Click Here", toolTip:"sample text"};
var calLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hEx
var calPSP={widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", widge
tId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2"}};
var calendar1 = new kony.ui.Calendar(calBasic, calLayout, calPSP);
Accessible from IDE

No
l
iPhone
iPad
12.4 Calendar - Event

Calendar has the following event associated with it:
l
onSelection
12.4.1 onSelection
This event is triggered when an item is selected or deselected.
Note: On Android platform, this event works only from Android OS version 4.0 and above.
Signature
JavaScript: onSelection
Lua: onselection
Read / Write
JavaScript Example
function onSelectionCallBck(calendar)
{
}
//Defining the properties for Calendar with onSelection:onSelectionCallBck
var calBasicConf = {id: "calID", isVisible:true, skin:"konytextar", focusS
kin:"calFocus", dateFormat:"dd/MM/yyyy",viewType:constants.CALENDAR_VIEW_T
YPE_GRID_POPUP, validStartDate:[01,01,2012], validEndDate:[31,12,2012],pla
ceholder:"JSCalendar",calendarIcon:"cal.png",
onSelection:onSelectionCallBck};
var calLayoutConf = {padding : [2,2,2,2], margin:[5,5,5,5],containerWeight
:100, hExpand:true, vExpand:true};
var calPSPConf = {titleOnPopup:"CalenderPopUpTitle"};
f);
Available on all platforms except Server side Mobile Web platform.
12.5 Calendar - Methods

Calendar has the following methods associated with it:
l
clear
clearData
enableRangeOfDates
navigateToPreviousMonth
navigateToNextMonth
removeDataAt
setData
setDataAt
setEnabled
setEnableAll
setDatesSkin
12.5.1 clear
This method allows you to enables you to clear the date in the calendar and the date format is shown. But
when you use a placeholder, then placeholder text is shown instead of date format.
Note: On BlackBerry10 platform, if you use this method, the date gets cleared and validStartDate is
displayed. If validStartDate is not set then current date is displayed.
Signature
JavaScript: clear()
Lua: calendar.clear(calwidget)
Input Parameters
calwidget [widgetref] - Mandatory
Return Values
None
Exceptions
None
JavaScript Example
//Defining the properties for Calendar
f);
//Calendar clear Method call.
Calendar.clear();
12.5.2 clearData
This method allows you to remove the data that is set through setData method.
Signature
JavaScript: clearData()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example

f);
//Calendar clearData Method call.
Calendar.clearData();
l
iPhone
iPad
12.5.3 enableRangeOfDates
This method allows you to enable/disable the range of dates that fall between the startdate and enddate and
disables/enables the rest of the dates.
Note: On Windows Phone platform, this method is supported only when you set viewType as CALENDAR_
VIEW_TYPE_GRID_ONSCREEN or CALENDAR_VIEW_TYPE_GRID_POPUP.
Signature
JavaScript: enableRangeOfDates(startDate, enddate, skin, enable)
Lua: calendar.enablerangeofdates(calwidget, startDate, enddate, skin, enable)
Input Parameters
startDate [JSObject] - Mandatory
Specifies the start date in a tabular format which follows {dd,mm,yyyy} convention.
endDate [JSObject] - Mandatory
Specifies the end date in a tabular format which follows {dd,mm,yyyy} convention.
Specifies the skin to be used to represent the enabled or disabled dates.
enable [Boolean] - Mandatory
Specifies the Boolean value that indicates if the dates listed must be enabled or disabled.
Return Values
None
Exceptions
None
JavaScript Example
f);
//EnableRangeOfDates Method call.
Calendar.enableRangeOfDates([07,04,2012], [21,04,2012], skin:"konytextar",
true);
12.5.4 navigateToPreviousMonth
This method allows you to navigate to previous month of the calendar widget.
Signature
JavaScript: navigateToPreviousMonth()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
f);
//navigateToPreviousMonth Method call.
Calendar.navigateToPreviousMonth();
l
iPhone
iPad
12.5.5 navigateToNextMonth
This method allows you to navigate to next month of the calendar widget.
Signature
JavaScript: navigateToNextMonth()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Example
,01,2012], validEndDate:[31,12,2012], date:[31,12,2012],
f);
//navigateToNextMonth Method call.
Calendar.navigateToNextMonth();
l
iPhone
iPad
12.5.6 removeDataAt
This method allows you to remove data set in a specific argument.
Signature
JavaScript: removeDataAt("date")
Input Parameters
date[String] - Mandatory
Specifies the date in a tabular format which follows {dd,mm,yyyy} convention.
Return Values
None
Exceptions
None
JavaScript Example

f);
//removeDataAt Method call.
Calendar.removeDataAt("31,12,2012");
l
iPhone
iPad
12.5.7 setData
This method allows you to set new data to the widgets as specified in the widgetDataMap.
Dictionary is of format: {"dd/mm/yyyy": {widget data confirming to widgetDataMapForCell } }
var data1 = {
"12/11/2012":{
template:newBox
lblTasks:"2"
},
"02/01/2012":{
"lblTasks":"21"
}
}
frmHome.mycal.setData(data1);
Signature
JavaScript: setData(dictionary)
Input Parameters
dictionary [JSObject]- Mandatory
Specifies the dates in a table format which follows {dd,mm,yyyy} convention.
Return Values
None
Exceptions
None
JavaScript Example
f);
//setData Method call.
Calendar.setData({
"12/11/2012":{
template:newBox
lblTasks:"2"
},
"02/01/2012":{
"lblTasks":"21"
}
});
l
iPhone
iPad
12.5.8 setDataAt
This method allows you to set new data to the segment. When you set new data, the existing data will be
replaced with the new data. If the calendar has no data, the new data is placed in the calendar.
Signature
JavaScript: setDataAt("date", data)
Input Parameters
date[String]- Mandatory
data [JSObject] - Mandatory
Data should confirm to widgetDataMapForCell.
Return Values
None
Exceptions
None
JavaScript Example
f);
//setDataAt Method call.
Calendar.setDataAt("31,12,2012", {
template:newBox
lblTasks:"2"
});
l
iPhone
iPad
12.5.9 setEnabled
This method allows you to enable/disable a list of dates if the startdate and enddate are not set in the
calendar, then this API is used to enable/disable any date in the calendar.
This method clears the dates that have been enabled/disabled earlier and considers the dates used in the
method as the latest dates. When the enable flag is true, the dates passed in this method are enabled and
remaining dates between startdate and enddate are disabled. When the enable flag is false, the dates passed
in this method are disabled and remaining dates between startdate and enddate are enabled.
Note: On BlackBerry platform, when the viewType is set as CALENDAR_VIEW_TYPE_DEFAULT, the
individual dates cannot be set as enabled or disabled.
Signature
JavaScript: setEnabled(dates, skin, enable)
Lua: calendar.setenabled(calwidget, dates, skin, enable)
Input Parameters
dates [JSObject]- Mandatory
enable [Boolean] - Mandatory
Specifies the Boolean value that indicates if the dates listed must be enabled or disabled.
Return Values
None
Exceptions
None
JavaScript Example
f);
//setEnabled Method call
Calendar.setEnabled([[07,04,2012], [27,04,2012],[1,04,2012],[15,04,2012],
[18,04,2012],[21,04,2012]], skin:"konytextar", true);
12.5.10 setEnableAll
This method allows you to enable all the dates that fall between the startdate and enddate. The look and feel
of the dates is configured by the cell skin.
Signature
JavaScript: setEnableAll()
Lua: calendar.setenableall(calwidget)
Input parameters
Return Values
None
Exceptions
None
JavaScript Example
f);
//setEnableAll Method call
Calendar.setEnableAll();
12.5.11 setDatesSkin
This method allows you to set the skin and control the look and feel of each cell in the calendar. This API
works on all the dates of the calendar. The dates need not be between startdate and enddate.
Signature
JavaScript: setDatesSkin(dates, skin)
Lua: calendar.setdatesskin(calwidget, dates, skin)
Input parameters
dates [JSObject]- Mandatory
Return Values
None
Exceptions
None
JavaScript Example
12,04,30,55],skin:"konytextar", focusSkin:"calFocus", dateFormat:"dd/MM/yy
yy", viewType:constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:[01,
01,2012], validEndDate:[31,12,2012], date:[31,12,2012], placeholder:"JSCal
endar", calendarIcon:"cal.png"};
f);
//setDateSkin Method call.
Calendar.setDateSkin([[27,04,2012],[30,04,2012],[01,04,2012]], skin:"konyt
extar");
12.6 Calendar - Deprecated Properties

The deprecated properties for Calendar widget are as follows:
l
date
format
monthI18Nkey
weekdayI18Nkey
12.6.1 date
Specifies the default date that must appear in the Date field.
Default: No date is specified. The calendar will display the value set in the Format property.
To specify a date for the calendar
) button against the Date property. The following popup appears:
2. Clear the Set date and time to NONE option. The following popup appears:
3. Select the require date and time (optional and applicable only for iPhone). Click OK.
The selected date will appear in the calendar when rendered.
Type
Object
Read / Write
To set the date as 24th February, 2011, in a calendar with id cal1, enter the following:
cal1.date = {24,02,2011}
Note: If you enter an invalid date, the calendar date will remain unchanged. The order of the digits
entered in the above code snippet is not dependent on the display format.
You can also read the day, month, and year set in the Date of the calendar cal1 by using the following:
Day:
local var = cal1.day
print (var);
Month
local var = cal1.month
print (var);
Year
local var = cal1.year
print (var);
Note: If the day, month, or year is not set, nil is returned.
Accessible from IDE

Yes
12.6.2 format
Specifies the format in which the date must appear. You can choose to display the date in one of the following
formats:
l
dd/MM/yyyy (Default)
MM/dd/yyyy
MM/dd/yy
Note: If you clear the date set in the calendar using calendar.clear()API, the calendar label will display the
value set in the "Format" field and the date will be reset to nil. To clear the date of a calendar with id cal1 in a
Form frm1, enter the following:
calendar.clear(frm1.cal1);
Note: The calendar will display the value set in the "Format" field and the date will be reset to nil.
Type
String
Read / Write
No
Accessible from IDE

Yes
12.6.3 monthI18Nkey
Specifies the i18n key for a month. The i18n key for a month has to be specified in the Internationalization
dialog box. For more information refer the Kony Studio User Guide.
Type
String
Read / Write
No
Accessible from IDE

Yes
12.6.4 weekdayI18Nkey
Specifies the i18n key for a week. The i18n key for a weekday has to be specified in the Internationalization
dialog box. For more information refer the Kony Studio User Guide.
Type
String
Read / Write
No
Accessible from IDE

Yes
12.7 gridcalender - Templates

12.7.1 What is a Template for gridcalendar
gridcalendar template enables you to define a template for Calendar Day cell. Only one template can be used
for each Calendar. This is primarily useful for developers to achieve custom look and feel of Calendar Day
cell. You can define a template using the following widgets:
l
HBox
VBox
Button
Image
Label
12.7.2 Where to use a gridcalendar Template

gridcalendar templates are used to achieve custom look and feel of Calendar Day cell.
The gridcalendar templates are used:
l
to define a Calendar Day cell with custom look and feel.
to achieve the behavior of having widgets such as an Image and a label for a Calendar Day cell.
to perform an action on the event of an onclick of a Calendar Day cell.
12.7.3 Creating a Template for gridcalendar

When you want the pre-designed information to be displayed for a Calendar Day cell in the application, you
have a provision to add a gridcalendar Template using KonyOne Studio. For more information about section
headers refer KonyOne Studio User Guide.
To create a gridcalendar template at the application-level, follow these steps:
2. Expand the application for which you want to create the gridcalendar Template.
3. Navigate to templates > gridcalendar , right-click mobile/tablet and select New GridCalendar
Template. The Create a New GridCalendar window appears.
iii. Drag and drop an HBox onto the form.
Note: Only HBox is supported on the form. You can add other widgets within
this widgets.
iv. Drag and drop the required widgets onto the HBox. Set the properties of these widgets
and click Save.
v. A gridcalendar template is created.
12.7.4 Using gridcalendar Template

You can define only one template for each calendar using the above process.
To use gridcalendar template in an application, follow these steps:
2. Expand the application for which you want to use gridcalendar template.
3. Navigate to forms > mobile/tablet, right-click and select New Form. The Create a New Form
window appears.
5. Drag-drop a Calendar on the Form and click Save.

6. To set the template to a Calendar, select the Calendar and go to Properties window.
7. Select cellTemplate and Select/Search Segment Template window appears. Select the template,
which you want to set to the Calendar.
8. Click OK.
13. CheckBoxGroup
The CheckBoxGroup widget allows you to make one or more selections from a group of check boxes. If you
select a check box, a check mark appears inside the check box to indicate the selection.
You can use a CheckBoxGroup widget to provide a selection of choices in groups from which the user can
select one or more choices.
Note: To provide only a single selection option to the user, use a ComboBox widget or a RadioButtonGroup
widget.
CheckBoxGroup provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Properties, and Events.
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKeys
selectedKeyValues
skin
containerWeight
itemOrientation
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
focusTickedImage
focusUnTickedImage
groupCells
hoverSkin
tickedImage
toolTip
unTickedImage
viewType
Events
onSelection
preOnclickJS
postOnclickJS
Creating a CheckBox using a constructor: kony.ui.CheckBoxGroup

var checkBox = new kony.ui.CheckBoxGroup(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//The below function is the callback function for onSelction event.
function onSelCallBck(chkBox)
{
alert("on selection event triggered");
}
//Define CheckBox config.
var basicConf = {id: "checkBox", isVisible: true, skin:"chkSkin", focusSk
in:"chkFocusSkin", onSelection:onSelCallBck}
var layoutConf = {containerWeight:80, margin:[10,10,10,10], itemOrientatio
n:constants.CHECKBOX_ITEM_ORIENTATION_VERTICAL}
var pspConf = {focusTickedImage:"focTikImg.png", focusUnTickedImage:"focUn
TikImg.png", viewType:constants.CHECKBOX_VIEW_TYPE_LISTVIEW};
//Create a new Checkbox.
var checkBox = new kony.ui.CheckBoxGroup(basicConf, layoutConf, pspConf);
Adding a CheckBoxGroup Widget from IDE

The steps involved in adding a CheckBoxGroup widget are as follows:
1. From the IDE, drag and drop the CheckBoxGroup widget onto a form (occupies the complete available
width). Or, based on your requirements, you can choose to perform any of the following options:
a. If you want to resize a CheckBoxGroup widget in the horizontal direction, place an HBox
on the form and drag and drop the CheckBoxGroup widget inside the HBox and resize
accordingly.
b. If you want to resize a CheckBoxGroup widget in the vertical direction, place an HBox on
the form and place a VBox inside the HBox; and drag and drop the CheckBoxGroup
widget inside the VBox and resize accordingly.
2. Specify the values to be displayed in the CheckBoxGroup widget from the IDE by using the
masterData property or from code by using the masterDataMap property.
3. (Optional) If you set the values from the code, you can use the selectedKeys property to specify the
values to be displayed as selected.
4. (Optional) For programming purposes, if you want to find the values selected by a user, use the
selectedKeyValues property.
5. (Optional) The check boxes in the CheckBoxGroup widget are aligned vertically by default. You can
choose to align them horizontally (not applicable on iPhone and iPad) by using the itemOrientation
property.
6. (Optional) Define an onSelection event.
You can customize the appearance of the CheckBoxGroup widget by using the following properties:
l
skin: Used to specify the skin.
focusSkin: Used to specify the focus skin.
The following are the important considerations for the CheckBoxGroup widget.
All Platforms
l
CheckBoxGroup widget is always a group widget.
Limit the number of choices in the widget. If you need to display several choices (above
15 choices), consider using a ListBox widget.
Android
l
If you set the itemOrientation to horizontal, the given number of checkboxes should not
exceed the width of device screen. If they exceed, only the number of checkboxes equal
to the width of the device are displayed.
If the checkboxes on the screen do not have enough space available to align
themselves, then they may look distorted.
iPhone
l
You cannot apply skins in the on-off switch view.
BlackBerry and J2ME

l
For non-touch devices, you can specify focus images for ticked and unTicked images.

l
Focus skin is not supported.
The onSelection event is not supported on the Basic version of Mobile Web as the Java
script is not supported on browsers of basic devices.
To achieve a functionality similar to an onSelection, event you must create an additional
button for the Basic version of the Mobile Web with an onclick event and attach an
onselection closure.
A tick ("") symbol is provided with white background as default image for checked in
android devices. In Android devices default check-box size is very small, hence you
have provided this look.

The appearance of the CheckBoxGroup widget on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
iPhone
Windows Phone
Platform
Appearance
13.1 CheckBox - Basic Properties

The basic properties of CheckBox Widget are as follows:
l
focusSkin
id
info
isVisible
masterData
masterDataMap
selected Keys
selected KeyValues
skin
13.1.1 focusSkin
Specifies the look and feel of the CheckBox when in focus.
3. On Windows Platform, focusSkin is applied only to the selected item, but not to the entire widget when in
focus.
4. On BlackBerry platform, focusSkin is applied only to the text associated with the checkbox.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for CheckBox with focusSkin:"chkFocusSkin", skin
should be created with the same name through IDE or handcode.
var chkBasic = {id: "checkBox", isVisible: true, skin:"chkSkin", focusSki
n:"chkFocusSkin"}
var chkLayout = {containerWeight:100}
//Creating the CheckBox.
var checkBox = new kony.ui.CheckBoxGroup(chkBasic, chkLayout,{});
//Reading the focusSkin of CheckBox
alert("CheckBox focusSkin is ::"+checkBox.focusSkin);
Accessible from IDE

Yes
13.1.2 id
id is a unique identifier of CheckBox consisting of alpha numeric characters. Every CheckBox should have a
unique id within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for CheckBox with id: "checkBox"
var chkBasic = {id: "checkBox", isVisible: true}
var checkBox = new kony.ui.CheckBoxGroup(chkBasic,chkLayout,{});
//Reading the ID of CheckBox
alert("CheckBox id is ::"+checkBox.id);
Accessible from IDE

Yes
13.1.3 info
This will help in avoiding the globals to most part of the programming .
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for CheckBox with info property.
var chkBasic = {id: "checkBox", isVisible: true }
checkBox.info = {key:"checkboxitems"};
//Reading the info of CheckBox
alert("CheckBox info is ::"+checkBox.info);
Accessible from IDE

No
13.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for CheckBox with isVisible: true
//Reading the visibility of CheckBox
alert("CheckBox visibility is ::"+checkBox.isVisible);
Note: You can also set the visibility of a widget dynamically from code by using the setVisibility method.
Accessible from IDE

Yes
13.1.5 masterData
Specifies the set of values that must be displayed for the user to make a selection from the available choices.
Default: User Defined (You must specify the key and the display value)
To specify the set of values, click the Ellipsis (
CheckBox window.
) button against the property to open the MasterData for
In the Master Data window, you can specify the Key, Display Value, i18n Key, and the Accessibility Config.
You can use the Selected column to specify the choice to be shown as selected when rendered. You can do
this by selecting true against the choice that you wish to show as selected.
The following image illustrates the MasterData for CheckBox window:
Note: Select the Use as test data in preview mode option if you want to see the data you enter in the Master
Data when you use the quick preview feature of the IDE. (For more information on Quick Preview, see the
Note: If the key or the display value is nil, the value will not be listed as one of the available choices.
Note: The accessibilityConfigObject is optional and the object should contain the keys as defined in the
accessibilityConfig property.
//Format of the masterData property
[
["key1","value1",accessibilityConfigObject],
["key2","value2",accessibilityConfigObject],......,
["keyn","valuen",accessibilityConfigObject]
]
Syntax
JavaScript: masterData
Lua: masterdata
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for CheckBox with masterData:[["A","Asia"],["E"
,"Europe"]]
var chkBasic = {id: "checkBox", isVisible: true, masterData:[["A","Asia",
accessibilityConfigObject],["E","Europe", accessibilityConfigObject]], ski
n:"chkSkin", focusSkin:"chkFocusSkin"}
//Reading the masterData of CheckBox
alert("CheckBox masterData ::"+checkBox.masterData);
Accessible from IDE

Yes
Specifies the set of values from which you can make one or more selections. You must set the values from
the code.
can always read and write data to it.
This property is applicable only if the masterData is not set. You must use either the masterData or the
masterDataMap to set data for the CheckBox.
You must specify a key, value, and the accessibilityConfig in a master data map.
//Format of the masterDataMap property
[
[
{"mykey":"item1","myvalue":"Item One","accessibilityConfig":acObject},
{"mykey":"item2","myvalue":"Item
Two","accessibilityConfig":acObject},...,
["mykey":"itemn","myvalue":"Item N","accessibilityConfig":"acObject}
],
"mykey",
"myvalue"
]
Note: The accessibilityConfig is the standard key expected in each items data array. It is optional and the
object should contain the keys as defined in the accessibilityConfig property.
Note: If the key or the value is null/nil, the value will not be listed as one of the available choices.
Syntax
JavaScript: masterDataMap
Lua: masterdatamap
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for CheckBox with masterDataMap:[[{"mykey":"key
1", "myvalue":"value1"}, {"mykey":"key2", "myvalue":"value2"},{"mykey":"ke
y3","myvalue":"value3"}],"mykey", "myvalue"].
var chkBasic = {id: "checkBox", isVisible: true, masterDataMap:[[{"mykey"
:"key1", "myvalue":"value1", "accessibilityConfig":acObject}, {"mykey":"ke
y2", "myvalue":"value2", "accessibilityConfig":acObject},{"mykey":"key3",
"myvalue":"value3", "accessibilityConfig":acObject}], "mykey","myvalue"],
skin:"chkSkin", focusSkin:"chkFocusSkin"}
//Reading the masterData of CheckBox.
alert("CheckBox masterDataMap ::"+checkBox.masterDataMap);
Accessible from IDE

No
13.1.7 selectedKeys
If you create a CheckBox with multiple values, you can choose to show specific values as selected when the
CheckBox is rendered.
If you set the selectedkeys to null/nil, the selection is cleared.
Syntax
JavaScript: selectedKeys
Lua: selectedkeys
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for CheckBox with selectedKeys:["key1","key2"]
n:"chkFocusSkin", masterDataMap:[[{"mykey":"key1", "myvalue":"value1"}, {"
mykey":"key2", "myvalue":"value2"}, {"mykey":"key3", "myvalue":"value3"}],
"mykey","myvalue"], selectedKeys:["key1","key2"]}
//Reading the selectedKeys of CheckBox
alert("CheckBox selectedKeys are ::"+checkBox.selectedKeys);
Accessible from IDE

No
Returns the array of selected key-value pairs.
If you do not select a value, the return value is null/nil.
Syntax
JavaScript: selectedKeyValues
Lua: selectedkeyvalues
Type
JavaScript: Array
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for CheckBox with selectedKeyValues:[["key1","v
alue1"],["key2","value2"]]
n:"chkFocusSkin", selectedKeyValues:[["key1","value1"], ["key2","value2"]]}
//Reading the selectedKeyValues of CheckBox.
alert("CheckBox selectedKeyValues are ::"+checkBox.selectedKeyValues);
Accessible from IDE

No
13.1.9 skin
Specifies the look and feel of the CheckBox when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for CheckBox with skin:"chkSkin",skin should be
created with the same name through IDE or handcode
var chkBasic = {id: "checkBox", isVisible: true, skin:"chkSkin"}
//Reading the skin of CheckBox
alert("CheckBox skin is ::"+checkBox.skin);
Accessible from IDE

Yes
13.2 CheckBox - Layout Properties

The Layout properties for CheckBox Widget are as follows:
l
containerWeight
itemOrientation
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for CheckBox with containerWeight:50
Accessible from IDE

No
Specifies the alignment of the check boxes as horizontal or vertical.
l
CHECKBOX_ITEM_ORIENTATION_VERTICAL (default)
CHECKBOX_ITEM_ORIENTATION_HORIZONTAL. This option is not supported in BlackBerry 10

platform.
Syntax
JavaScript: itemOrientation
Lua: itemorientation
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for CheckBox with itemOrientation as VERTICAL
var chkLayout = {containerWeight:80, margin:[10,10,10,10], itemOrientation
:constants.CHECKBOX_ITEM_ORIENTATION_VERTICAL}
Accessible from IDE

Yes
Available on all platforms except iPhone and iPad
13.2.3 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for CheckBox with margin:[10,10,10,10]
var chkLayout = {containerWeight:100, margin:[10,10,10,10]}
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a CheckBox with margin in pixels.
var chkBasic = {id : "checkBox", isVisible:true};
var chkLayout = {containerWeight:100, margin:[0,5,0,5],
marginInPixel:true};
checkBox= new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
13.2.5 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for CheckBox with padding:[10,10,10,10]
var chkLayout = {containerWeight:100,padding:[10,10,10,10]}
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic) and BlackBerry 10
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a CheckBox with margin in pixels.
var chkBasic = {id : "checkBox", isVisible:true};
var chkLayout = {containerWeight:100, padding:[10,10,10,10], paddingInPixe
l:true};
checkBox= new kony.ui.Box(basicConfBox, layoutConfBox, {});
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a CheckBox with widgetAlignment as LEFT.
var chkBasic = {id: "checkBox", isVisible: true};
var chkLayout = {containerWeight:80, percent:false, widgetAlignment:consta
nts.WIDGET_ALIGN_MIDDLE_LEFT};
Accessible from IDE

Yes
Available on all platforms except Windows Kiosk
13.3 CheckBox - Platform Specific Properties

The platform specific properties for CheckBox Widget are as follows:
l
focusTickedImage
focusUnTickedImage
groupCells
hoverSkin
tickedImage
toolTip
unTickedImage
viewType
wheelBackgroundColor
Specifies the image to be displayed when you make a selection on non-touch devices.
Syntax
JavaScript: focusTickedImage
Lua: focustickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for CheckBox with focusTickedImage:"focTikImg.pn
g"
var chkLayout = {containerWeight:100};
var chkPSP = {focusTickedImage:"focTikImg.png"};
var checkBox = new kony.ui.CheckBoxGroup(chkBasic,chkLayout,chkPSP);
Accessible from IDE

Yes
l
BlackBerry
J2ME
Specifies the image to be displayed when you clear a selection on non-touch devices.
Syntax
JavaScript: focusUnTickedImage
Lua: focusuntickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for CheckBox with focusUnTickedImage:"focUnTikIm
g.png"
var chkPSP = {focusUnTickedImage:"focUnTikImg.png"};
Accessible from IDE

Yes
l
BlackBerry
J2ME
13.3.3 groupCells
Specifies if the group cells style must be applied. when the style is applied the items in the checkbox are
grouped and they are indicated with a round corner rectangle box.
Default: false
If set to true, the group cells style is applied.

If set to false, the group cells style is not applied.
Note: This property is applicable only when viewType is set as CHECKBOX_VIEW_TYPE_TABLEVIEW.
Syntax
JavaScript: groupCells
Lua: groupcells
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for CheckBox with groupCells:true
var chkPSP = {groupCells:true};
Accessible from IDE

Yes
l
iPad
iPhone
13.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
13.3.5 tickedImage
Specifies the image to be displayed when you make a selection.
Note: If you specify a tickedImage, ensure that you also specify an unTickedimage. If not defined, the
behavior will be undefined.
Syntax
JavaScript: tickedImage
Lua: tickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for CheckBox with tickedImage:"tickedImg.png"
var chkPSP = {tickedImage:"tickedImg.png"};
Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
J2ME
Windows Phone
Windows Kiosk
13.3.6 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a CheckBox with toolTip:sample text
var chkBasic={id:"checkbox1", isVisible:true, skin:"chkSkin", focusSkin:"c
hkFSkin", text:"Click Here", toolTip:"sample text"};
var chkLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hEx
var chkPSP={};
var checkbox1 = new kony.ui.CheckBox(chkBasic, chkLayout, chkPSP);
Accessible from IDE

Yes
l
Windows Phone
Windows Tablet
Windows Kiosk
Specifies the image to be displayed when a selection is cleared.
Note: If you specify an unTickedImage, ensure that you also specify a tickedImage. If not specified, the
Syntax
JavaScript: unTickedImage
Lua: untickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for CheckBox with unTickedImage:"UntickedImg.png"
var chkPSP = {unTickedImage:"UntickedImg.png"};

Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
J2ME
Windows Phone
Windows Tablet
Windows Kiosk
13.3.8 viewType
Specifies the view type of the CheckBox.
Default: CHECKBOX_VIEW_TYPE_ONOFFSWITCH
Following are the available options on different platforms:
l
CHECKBOX_VIEW_TYPE_ONOFFSWITCH
CHECKBOX_VIEW_TYPE_TABLEVIEW
CHECKBOX_VIEW_TYPE_ONSCREENWHEEL
Note: For toggleView you can further select the ViewStyle as plain, bordered, or bar.
The following images illustrate the modes:
TABLEVIEW
ONOFFSWITCH
ONSCREENWHEEL
The below image illustrate the nextprevtoolbar set to a check box. The highlighted toolbar is achieved on
setting the Mode as onscreenwheel to the Check Box and Input Accessory View Type as nextprevtoolbar
to the Form.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for CheckBox with viewType:CHECKBOX_VIEW_TYPE_ON
OFFSWITCH
var chkPSP = {viewType:constants.CHECKBOX_VIEW_TYPE_ONOFFSWITCH };
Accessible from IDE

Yes
l
iPad
iPhone
Specifies the background color for the wheel that is displayed when you click the CheckBox. This property is
applicable only when you set the viewType as CHECKBOX_VIEW_TYPE_ONSCREENWHEEL.
Syntax
JavaScript: wheelBackgroundColor
Type
Read / Write
JavaScript Example
//Defining the properties for CheckBox with viewType:CHECKBOX_VIEW_TYPE_ON
OFFSWITCH
var chkPSP = {viewType:constants.CHECKBOX_VIEW_TYPE_ONSCREENWHEEL};
//Setting the color for wheelbackground
form.checkBox.wheelBackgroundColor = "0000ff00";
Accessible from IDE

No
l
iPad
iPhone
13.4 CheckBox - Events

CheckBox has the following event associated with it:
l
onSelection
preOnclickJS
postOnclickJS
13.4.1 onSelection
An event callback that is invoked by the platform when an item is selected or deselected.
Note: For Server side Mobile Web (Basic devices), this event is fired only when you make a selection and
then write an onClick event for a button.
Signature
Lua: onselection
Read / Write
JavaScript Example
//The below function is the callback function for onSelction event
function onSelCallBck(chkBox)
{
alert("on selection event triggered");
}
//Defining the properties for CheckBox with onSelection:onSelCallBck
var chkBasic = {id: "checkBox", isVisible: true, masterData:[["key1","val
ue1"], ["key2","value2"]], skin:"chkSkin", focusSkin:"chkFocusSkin", onSel
ection:onSelCallBck}

This property is available on all platforms except Server side Mobile Web (basic)
13.4.2 preOnclickJS
This event allows the developer to execute custom javascript function before the onSelection callback of the
CheckBox is invoked. This is applicable only for Mobile Web channel. The function must exist in a javascript
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for preOnclickJS event
function preOnclickJSCallBck(chkBox)
{
alert("preOnclickJS event triggered");
}
//Defining the properties for CheckBox with preOnclickJS:preOnclickJSCallB
ck
var chkBasic = {id: "checkBox", isVisible: true, masterData:[["key1", "va
lue1"],["key2","value2"]], skin:"chkSkin", focusSkin:"chkFocusSkin",
onSelection:onSelCallBck}
var chkPSP = {preOnclickJS:preOnclickJSCallBck}
var checkBox = new kony.ui.CheckBoxGroup(chkBasic,chkLayout,chkPSP );
Accessible from IDE

Yes
This event allows the developer to execute custom javascript function after the onSelection callback of the
CheckBox is invoked. This is applicable only for Mobile Web channel.The function must exist in a javascript
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for postOnclickJS event
function posOnclkJSCallBck(chkBox)
{
alert("postOnclickJS event triggered");
}
//Defining the properties for CheckBox with postOnclickJS:posOnclkJSCallBck
var chkBasic = {id: "checkBox", isVisible: true, masterData:[["key1","val
ue1"], ["key2","value2"]], skin:"chkSkin", focusSkin:"chkFocusSkin", onSel
ection:onSelCallBck}
var chkLayout = {containerWeight:100, }
var chkPSP = {postOnclickJS:posOnclkJSCallBck}
Accessible from IDE

Yes
14. ComboBox
A ComboBox is a widget that allows you to select a single item from a drop-down list.
If you select the drop-down arrow on a ComboBox, a drop-down list containing a list of items (values) is
displayed. When you select an item from the drop-down list, the selected item is displayed on the ComboBox.
A ComboBox is similar to a ListBox. However, unlike the ListBox, you can only select a single item at a time.
You can use a ComboBox widget when you require a user to select a single item from a list of items (greater
than 1 item) while occupying relatively lesser space as compared to a RadioButton widget (a radio button
displays all the available options to make a single selection and hence takes more space).
A ComboBox provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKey
selectedKeyValue
skin
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Events
Deprecated
onSelection
preOnclickJS
postOnclickJS
placeholderi18nkey
Platform Specific
Properties
blockedUISkin
dropDownImage
groupCells
hoverSkin
placeholder
popupFocusSkin
popupSkin
popupTitle
tickedImage
toolTip
unTickedImage
viewType
viewConfig
Creating a ComboBox using a constructor: kony.ui.ComboBox

var mycombobox = new kony.ui.ComboBox (basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//The below function is preOnclickJS event callback function

function preOnclickJSCallBck(combobox)
{
alert("Inside preOnclickJS event callback");
}
//The below function is postOnclickJS event callback function
function postOnclickJSCallBck(combobox)
{
alert("Inside postOnclickJS event callback");
}
//The below function is onSelection event callback function
function onSelCallBck(combobox)
{
alert("Inside onSelection event callback");
}
//Creating the ComboBox
var comboBasic ={id:"combobox1", isVisible:true, masterDataMap:[[{"mykey":
"key1", "myvalue":"value1"}, {"mykey":"key2", "myvalue":"value2"}], "mykey
","myvalue"], skin:"comboSkin", selectedKey:"key1", onSelection:onSelCallB
ck};
var comboLayout = {containerWeight:80, widgetAlignment:constants.WIDGET_AL
IGN_MIDDLE_LEFT, padding:[10,10,10,10], margin:[10,10,10,10], hExpand:true,
vExpand:false};
var comboPSP= {viewType:constants.COMBOBOX_VIEW_TYPE_TABLEVIEW, contentAli
gnment:constants.CONTENT_ALIGN_MIDDLE_LEFT, placeholder:"Please select a v
alue", placeholderI18NKey:"plcHolder", popupTitle:"ComboPopUp", groupCells
:true, preOnclickJS:preOnclickJSCallBck, postOnclickJS:postOnclickJSCallBc
k};
combo = new kony.ui.ComboBox(comboBasic, comboLayout, comboPSP);
//Reading the selectedKeyValue of the ComboBox
alert("ComboBox selectedKeyValue is ::"+.combo.selectedKeyValue);
Appearance of the ComboBox

The appearance of the ComboBox with the default properties on various platforms is as follows:
Platform
Default Appearance
Android
BlackBerry
iPhone
Platform
Default Appearance
Windows Phone
Mobile Web (BJS)
UI Behavior
When you click a ComboBox, the UI behavior is not the same on all the platforms.
The UI behavior of a ComboBox on various platforms is as follows:
Platform
UI Behavior
Android
BlackBerry
iPhone
Windows Phone
Platform
UI Behavior
Mobile Web (BJS)
Adding a ComboBox from IDE

The steps involved in adding a ComboBox widget are as follows:
1. From the IDE, drag and drop the ComboBox onto a form (occupies the complete available width). Or,
a. If you want to resize ComboBox in the horizontal direction, place a Box on the form and
drag and drop the ComboBox inside the HBox and resize accordingly.
b. If you want to resize a ComboBox in the in the vertical direction, place a Box on the form
and place a VBox inside the HBox; and drag and drop the ComboBox inside the VBox
and resize accordingly.
2. Specify the values to be displayed in the ComboBox from the IDE by using the masterData property or
from code by using the masterDataMap property.
3. (Optional) If you have set the values from the code, you can use the selectedKey property to specify to
show any value of your choice as selected.
4. (Optional) For programming purposes, if you want to find the value selected by a user, use the
selectedKeyValue property.
You can customize the appearance of the ComboBox by using the following properties:
l
widgetAlignment: To specify the alignment of the widget.
skin: Used to specify the skin.
focusSkin: Used to specify the focus skin.
Pitfalls
The following are the pitfalls to avoid for a ComboBox:
You must not use a ComboBox if you require the user to make multiple selections. If you require a user
to make multiple selections, use a CheckBox or a ListBox widget.
(Optional) You must first fetch the data for the ComboBox before showing the form. You must do so
because if a form is shown and the ComboBox has no values, an empty ComboBox is displayed
resulting in a bad user experience.
Limitations
The following are the limitations of the ComboBox widget across all platforms and individual platforms:
l
All platforms: You cannot place a ComboBox inside a Segment.
All platforms: You cannot place images inside a ComboBox.
Android: The skin and focusSkin are not applied to the default ComboBox that appears on a Form
when rendered. These skins are applied to the ComboBox items in the popup (appears when you click
the ComboBox widget).
Work Around
To apply the skin and focusSkin to the default appearance of the ComboBox widget, do the following:
1. Create two NinePatchDrawable images and name them as "combo_box_normal_skin.9.png"
for Normal skin and "combo_box_focus_skin.9.png" for Focus skin. Place these images in
"<drive>:\workspace\<project name>\resources\mobilerichclient\android\" directory.
2. Build the Application for Android. The Normal and Focus skins will be applied to the default
ComboBox appearance.
For information on NinePatchDrawable images, see the following links:
l
http://developer.android.com/guide/topics/graphics/2d-graphics.html#nine-patch
http://developer.android.com/guide/developing/tools/draw9patch.html
J2ME platform: If you do not specify the focusSkin, it is not possible to identify the traversal.
Mobile Web:
l
The onSelection event is not supported on the Basic version of Mobile Web as the Java script is
not supported on browsers of basic devices.
To achieve the functionality similar to an onSelection event, you must create an additional
button for the Basic version of the Mobile Web with an onclick event and attach an onSelection
closure.
Due to Browser restriction, you cannot apply padding for a ComboBox.
The hExpand property is not applicable.
focusSkin is not supported.
14.1 ComboBox - Basic Properties

The basic properties of ComboBox widget are as follows:
l
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKey
selectedKeyValue
skin
14.1.1 focusSkin
Specifies the look and feel of the ComboBox when in focus.
1. On J2ME non-touch devices, if you do not specify the focusSkin, it is not possible to identify the focus
3. On Windows Platform, focusSkin is applied only to the selected item, but not to the entire widget when in
focus.
Note: In Desktop Web platform, Chrome browser does not support if the properties defined in font tab are
different for skin and focusSkin.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the focusSkin:"comboFSkin".
var comboBasic ={id:"combobox1", isVisible:true, skin:"comboSkin", focusSk
in:"comboFSkin"};
var comboLayout = {containerWeight:100};
var comboPSP= {};
//Creating the ComboBox.
//Reading the focusSkin of the ComboBox
alert("ComboBox focusSkin is ::"+combo.focusSkin);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and BlackBerry 10 platforms.
14.1.2 id
id is a unique identifier of button consisting of alpha numeric characters. Every ComboBox should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for ComboBox with the id:"combobox1"
var comboBasic ={id:"combobox1", isVisible:true};
var comboPSP= {};
//Reading the id of the ComboBox
alert("ComboBox ID is ::"+combo.id);
Accessible from IDE

Yes
14.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the info property.
var comboBasic ={id:"combobox1", isVisible:true };
var comboPSP= {};
combo.info = {key:"comboboxitems"};
//Reading the info of the ComboBox
alert("ComboBox info is ::"+combo.info);
Accessible from IDE

No
14.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the isVisible:true.
var comboPSP= {};
//Reading the visibility of the ComboBox
alert("ComboBox visibility is ::"+combo.isVisible);
Accessible from IDE

Yes
14.1.5 masterData
ComboBox window.
The following image illustrates the MasterData for ComboBox window:
Note: If the key or the display value is nil, the value will not be listed as one of the available choices.
[
]
Syntax
Lua: masterdata
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the masterData:[["A","Asia"],
["E","Europe"], ["AU","Australia"], ["NA","North America"]].
var comboBasic ={id:"combobox1", isVisible:true, masterData:[["A","Asia",
accessibilityConfigObject], ["E","Europe", accessibilityConfigObject], ["A
U","Australia", accessibilityConfigObject], ["NA","North America", accessi
bilityConfigObject]]};
var comboPSP= {};
//Reading the masterData of the ComboBox
alert("ComboBox masterData is ::"+combo.masterData);
Accessible from IDE

Yes
Specifies the set of values from which you can make a selection. You must set the values from the code.
masterDataMap property to set data for the ComboBox.
[
[
{"mykey":"item2","myvalue":"Item Two","accessibilityConfig":acObjec
t},...,
],
"mykey",
"myvalue"
]
Syntax
Lua: masterdatamap
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the masterDataMap:[[{"mykey":"
key1", "myvalue":"value1"}, {"mykey":"key2", "myvalue":"value2"},
{"mykey":"key3","myvalue":"value3"}],"mykey", "myvalue"].
var comboBasic ={id:"combobox1", isVisible:true, masterDataMap:[[{"mykey":

"key1", "myvalue":"value1", "accessibilityConfig":acObject}, {"mykey":"key
2", "myvalue":"value2", "accessibilityConfig":acObject},{"mykey":"key3", "
myvalue":"value3", "accessibilityConfig":acObject}], "mykey","myvalue"]};
var comboPSP= {};
//Reading the masterDataMap of the ComboBox
alert("ComboBox masterDataMap is ::"+combo.masterDataMap);
Accessible from IDE

No
14.1.7 selectedKey
Specifies the value to be shown as selected.
Note: On Android platform, if you do not select a value, the first item in the ComboBox is selected.
If you create a ComboBox with multiple values, you can choose to show a specific value as selected when
the ComboBox is rendered.
Syntax
JavaScript: selectedKey
Lua: selectedkey
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the selectedKey:"key1".
var comboBasic ={id:"combobox1", isVisible:true, selectedKey:"key1"};
var comboPSP= {};
//Reading the selectedKey of the ComboBox.
alert("ComboBox selectedKey is ::"+combo.selectedKey);
Accessible from IDE

No
Available on all platforms except Server side Mobile Web (Basic)
Returns the array of selected key-value pair.
Syntax
JavaScript: selectedKeyValue
Lua: selectedkeyvalue
Type
JavaScript: Array
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for ComboBox with the selectedKeyValue:[["key1",
"value1"], ["key2","value2"]].
var comboBasic ={id:"combobox1", isVisible:true, selectedKeyValue:[["key1"
,"value1"], ["key2","value2"]]};
var comboPSP= {};

//Reading the selectedKeyValue of the ComboBox
alert("ComboBox selectedKeyValue is ::"+combo.selectedKeyValue);
Accessible from IDE

No
14.1.9 skin
Specifies the look and feel of the ComboBox when not in focus.
Note: In Android platform, you can apply skin only to the dropdown list that displays when ComboBox is
clicked.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the skin:"comboSkin"
var comboBasic ={id:"combobox1", isVisible:true, skin:"comboSkin"};
var comboPSP= {};
//Reading the skin of the ComboBox

alert("ComboBox skin is ::"+combo.skin);
Accessible from IDE

Yes
14.2 ComboBox - Layout Properties

The layout properties of ComboBox widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the containerWeight:80.
var comboPSP= {};
Accessible from IDE

No
Specifies the alignment of the text for a ComboBox with respect to its boundaries.
Note: This property is applicable only when the view is set as wheel type.
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the ComboBox.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the ComboBox.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the ComboBox.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the contentAlignment:constants
.CONTENT_ALIGN_TOP_LEFT
var comboLayout = {containerWeight:80, contentAlignment:constants.CONTENT_

ALIGN_TOP_LEFT, hExpand:true};
var comboPSP= {};
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, SPA, and Desktop Web platforms
14.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the hExpand:true
var comboLayout = {containerWeight:80, hExpand:true};
var comboPSP= {};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Desktop Web, and SPA.
14.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties of a ComboBox with the margin:[10,10,10,10]
var comboBasic ={id:"combo", isVisible:true};
var comboLayout = {containerWeight:80,margin:[10,10,10,10]};
var comboPSP= {};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a ComboBox with margin in pixels.
var comboLayout = {containerWeight:80,margin:[10,10,10,10], marginInPixel:
true};
var comboPSP= {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
14.2.6 padding
on Server side Mobile Web, Desktop Web, and SPA platforms. Padding is not supported by Windows
Mobile browser for Box and ImageGallery.
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties of a ComboBox with padding [10,10,10,10].
var comboLayout = {containerWeight:80, padding:[10,10,10,10]};
var comboPSP= {};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Desktop Web, SPA, and BlackBerry 10.
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties of a ComboBox with padding in pixels.
var comboLayout = {containerWeight:80, padding:[10,10,10,10], paddingInPix
el:true};
var comboPSP= {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
14.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the vExpand:true
var comboLayout = {containerWeight:80, vExpand:true};
var comboPSP= {};
Accessible from IDE

Yes
Available on all platforms except BlackBerry, BlackBerry 10, Desktop Web, and Server side Mobile Web
platforms.
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the widgetAlignment:WIDGET_ALI
GN_MIDDLE_LEFT
var comboLayout = {containerWeight:80, widgetAlignment:constants.WIDGET_AL

IGN_MIDDLE_LEFT};
var comboPSP= {};
Accessible from IDE

Yes
14.3 ComboBox - Platform Specific Properties

The platform specific properties for ComboBox widget are as follows:
l
blockedUISkin
dropDownImage
groupCells
hoverSkin
placeholder
popupFocusSkin
popupSkin
popupTitle
tickedImage
toolTip
unTickedImage
viewType
viewConfig
call) is completed.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the blockedUISkin:"blkUISkn",
Skin should be created with the same name through IDE or handcode.
var comboPSP= {blockedUISkin:"blkUISkn"};
//Reading the blockedUISkin of the ComboBox
alert("ComboBox blockedUISkin is ::"+combo.blockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
Specifies the image to be used for the drop-down box indicator (inverted triangle by default). The image you
specify is used to depict the drop-down box. If you do not specify an image, the drop-down box displays the
default image (inverted triangle).
Note: For iOS platform, the drop down image should be of size 20px * 33px for non retina devices and for
retina devices the image size should be 40px * 66px.
Syntax
JavaScript: dropDownImage
Lua: dropdownimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the dropDownImage:"ddimage".
var comboPSP= {dropDownImage:"ddimage"};
Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
J2ME
14.3.3 groupCells
Specifies if the group cells style must be applied.
Default: false
If set to true, the group cells style is applied.
If set to false, the group cells style is not applied.
Note: This property is applicable only when viewType is set as COMBOBOX_VIEW_TYPE_TABLEVIEW.
Syntax
Lua: groupcells
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the groupCells:true.
var comboPSP= {groupCells:true};
Accessible from IDE

Yes
l
iPad
iPhone
14.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
14.3.5 placeholder
Specifies the temporary or substitute text (a hint provided as a word or phrase) that must be displayed on the
ComboBox until the actual selection is made.
If you do not specify the placeholder text, the first option in the list is shown as the selected value.
Note: On iPhone platform, placeholder is supported only when the viewType is set as COMBOBOX_
VIEW_TYPE_LISTVIEW.
Syntax
Lua: placeholder
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
If you specify a value for the placeholder property and set selectedkey=nil or selectedkeyvalue=nil, then
the specified placeholder is displayed to the user when the Combo Box is rendered.
//Defining the properties for ComboBox with the placeholder:"Please select
a value".
var comboPSP= {placeholder:"Please select a value"};
//Reading the placeholder of the ComboBox.
alert("ComboBox placeholder is ::"+combo.placeholder);
Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
Windows Phone
J2ME
14.3.6 popupFocusSkin
Specifies the skin that is applied to each item in the native popup (list of options available) that appears when
you select the ComboBox.
Syntax
JavaScript: popupFocusSkin
Lua: popupfocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the popupFocusSkin:"popFSkn".
var comboPSP= {popupFocusSkin:"popFSkn"};
//Reading the popupFocusSkin of the ComboBox
alert("ComboBox popupFocusSkin is ::"+combo.popupFocusSkin);
Accessible from IDE

Yes
This property is available on BlackBerry platform only.
14.3.7 popupSkin
Specifies the skin that is applied to each item in the native popup (list of options available) that appears when
you select the ComboBox.
Syntax
JavaScript: popupSkin
Lua: popupskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the popupSkin:"popSkn".
var comboPSP= {popupSkin:"popSkn"};
//Reading the popupSkin of the ComboBox.
alert("ComboBox popupSkin is ::"+combo.popupSkin);
Accessible from IDE

Yes
This property is available on BlackBerry platform only.
14.3.8 popupTitle
Specifies the title text to be displayed for the ComboBox.
Default: Please Select (This is the default text that will appear as the title of the ComboBox)
Syntax
JavaScript: popupTitle
Lua: popuptitle
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the popupTitle:"ComboPopUp"
var comboPSP= {popupTitle:"ComboPopUp"};
//Reading the popupTitle of the ComboBox
alert("ComboBox popupTitle is ::"+combo.popupTitle);
Accessible from IDE

Yes
l
Symbian
14.3.9 tickedImage
Note: If you specify a tickedImage, ensure that you also specify an unTickedImage. If not specified, the
Syntax
Lua: tickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the tickedImage:"tickedImg.pn
g", Image should be in resources folder.
var comboPSP= {tickedImage:"tickedImg.png"};
Accessible from IDE

Yes
l
iPad
iPhone
14.3.10 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a ComboBox with toolTip:sample text
var comboBasic={id:"combobox1", isVisible:true, skin:"comboSkin", focusSki
n:"comboFSkin", text:"Click Here", toolTip:"sample text"};
var comboLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], h
var comboPSP={};
var combobox1 = new kony.ui.ComboBox(comboBasic, comboLayout, comboPSP);
Accessible from IDE

Yes
Syntax
Lua: untickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for ComboBox with the untickedImage:"UnTickedImg
.png", Image should be in resources folder.
var comboPSP= {unTickedImage:"UnTickedImg.png"};
Accessible from IDE

Yes
l
iPad
iPhone
14.3.12 viewType
Specifies the view mode of the ComboBox.
Default: COMBOBOX_VIEW_TYPE_LISTVIEW
Following are the available options on different platforms:
l
COMBOBOX_VIEW_TYPE_LISTVIEW (applicable on all platforms)
COMBOBOX_VIEW_TYPE_EDITVIEW (applicable on Desktop Web only)
COMBOBOX_VIEW_TYPE_TABLEVIEW (applicable on iPhone and iPad platforms)
COMBOBOX_VIEW_TYPE_TOGGLEVIEW (applicable on iPhone and iPad platforms)
COMBOBOX_VIEW_TYPE_ONSCREENWHEEL (applicable on iPhone and iPad platforms)
Note: In the Desktop Web platform, if the viewType is set as COMBOBOX_VIEW_TYPE_EDITVIEW,

then autoSuggest property is displayed.
Note: For toggleView you can further select the View Style as plain, bordered, or bar.
listView
Note: If you select the listView and do not specify a selection in the masterData, the default behavior of the
platform is to select the first entry on the list.
tableView
toggleView
onscreenwheel
The below image illustrate the nextprevtoolbar set to a Combo Box. The highlighted toolbar is achieved
on setting the Mode as onscreenwheel to the Combo Box and Input Accessory View Type as
nextprevtoolbar to the Form.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the view type as Tableview.
var comboPSP= {viewType:constants.COMBOBOX_VIEW_TYPE_TABLEVIEW};
//Reading the viewType of the ComboBox
alert("ComboBox viewType is ::"+combo.viewType);
Accessible from IDE

Yes
l
iPad
iPhone
Windows Tablet
Desktop Web
14.3.13 viewConfig
Specifies the view configuration for different viewtypes. You can set the configuration for toggle view.
toggleViewConfig: The property to configure the properties of COMBOBOX_VIEW_TYPE_TOGGLEVIEW.
viewStyle: Accepts the view style. This property is not supported in iOS7 and above versions.
l
COMBOBOX_TOGGLE_VIEW_STYLE_PLAIN
COMBOBOX_TOGGLE_VIEW_STYLE_BORDERED
COMBOBOX_TOGGLE_VIEW_STYLE_BAR
equalSegments: Specifies the boolean value which indicates if the segments must be equal.
enableTint: Specifies the boolean value to enable tintColor property. When this property is set
to true, tintColor property is displayed.
tintColor: Specifies the tint color in RGB format. The default color is blue.
Note: Below are the view configuration properties in Desktop Web when the viewType is set as
COMBOBOX_VIEW_TYPE_EDITVIEW.
autoSuggest:Enables the users to quickly find and select from a pre-populated list of values as they type,
leveraging searching and filtering.
Type: Boolean
Default : false
editableAreaSkin: Specifies the skin to be applied to the editor area of the ComboBox.
Type: String
Note: editableAreaSkin is displayed only when the autoSuggest is set to true.
Syntax
Lua: viewconfig
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the view type as Editview.
var comboPSP= {viewType:constants.COMBOBOX_VIEW_TYPE_EDITVIEW, viewConfig:
{autoSuggest: true, editableAreaSkin: "editareaskin"} };
//Reading the viewType of the ComboBox
alert("ComboBox viewType is ::"+combo.viewType);
Accessible from IDE

Yes
l
iPad
iPhone
Desktop Web
Specifies the background color for the wheel that is displayed when you click the ComboBox. This property is
applicable only when you set the viewType as COMBOBOX_VIEW_TYPE_ONSCREENWHEEL.
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for ComboBox with the view type as Editview.
var comboPSP= {viewType:constants.COMBOBOX_VIEW_TYPE_ONSCREENWHEEL, viewCo
nfig: {autoSuggest: true, editableAreaSkin: "editareaskin"} };
form.combo.wheelBackgroundColor = "0000ff00";
Accessible from IDE

No
l
iPad
iPhone
14.4 ComboBox- Events

ComboBox has the following event associated with it:
l
onSelection
preOnclickJS
postOnclickJS
14.4.1 onSelection
This event is triggered when you select or unselect any item in ComboBox.
Signature
Lua: onselection
Read / Write
JavaScript Example
//The below function is onSelection event callback function.
function onSelCallBck(combobox)
{
alert("Inside onSelection event callback");
}
//Defining the properties for ComboBox with the onSelection:onSelCallBck
var comboBasic ={id:"combobox1", isVisible:true, onSelection:onSelCallBck};
var comboPSP= {};
14.4.2 preOnclickJS
ComboBox is invoked. This is applicable only for Mobile Web channel. The function must exist in a javascript
Note: This event should return true, to continue with execution of onSelection and postOnclickJS events.
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is preOnclickJS event callback function.
function preOnclickJSCallBck(combobox)
{
alert("Inside preOnclickJS event callback");
}
//Defining the properties for ComboBox with the preOnclickJS:preOnclickJSC
allBck.
var comboPSP= {preOnclickJS:preOnclickJSCallBck};
//Reading the preOnclickJS of the ComboBox.
alert("ComboBox preOnclickJS is ::"+combo.preOnclickJS);
Accessible from IDE

Yes
ComboBox is invoked. This is applicable only for Mobile Web channel.The function must exist in a javascript
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is postOnclickJS event callback function.
function postOnclickJSCallBck(combobox)
{
alert("Inside postOnclickJS event callback");
}
//Defining the properties for ComboBox with the postOnclickJS:postOnclickJ
SCallBck.
var comboPSP= {postOnclickJS:postOnclickJSCallBck};
//Reading the postOnclickJS of the ComboBox.
alert("ComboBox postOnclickJS is ::"+combo.postOnclickJS);
Accessible from IDE

Yes
14.5 ComboBox - Deprecated Properties

This section contains the following:
l
placeholderi18nKey
Specifies the i18n key for the placeholder text to be used for internationalization.
Type
String
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
J2ME
15. DataGrid
DataGrid widget allows you to present a collection of data in rows and columns (tabular format).
DataGrid also supports common table formatting options, such as alternating the row background color,
customizing the gridline, and ability to hide or show headers.
You can use a DataGrid widget to show a read-only view of a small amount of data in a tabular format.
DataGrid widget provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Property, an Event, and Methods.
Basic Properties
Layout Properties
columnHeadersConfig
data
gridHeight
headerSkin
id
info
isMultiSelect
isVisible
rowAlternateSkin
rowCount
rowFocusSkin
rowNormalSkin
scrollable
selectedIndex
selectedIndices
selectedItem
selectedItems
showColumnHeaders
containerWeight
contentAlignment
margin
padding
widgetAlignment
Event
Methods
onRowSelected
addAll
addDataAt
applyCellSkin
removeAll
removeAt
selectAllRows
setCellDataAt
setData
setDataAt
Platform Specific
Properties
containerHeight
containerHeightInPixel
dockingHeader
enableScrollBar
gridlineColor
hoverSkin
selectedCellItem
selectedCellIndex
toolTip
Creating a DataGrid using a constructor: kony.ui.DataGrid

var dgrid = new kony.ui.DataGrid(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Defining the properties for dataGrid.
var dgridBasic = {id:"dgrid", info:{key:"This is datagrid"}, isVisible:tru
e, headerSkin:"hSkin", rowNormalSkin:"rNSkin", rowFocusSkin:"rFSkin", rowA
lternateSkin:"rASkin", showColumnHeaders:true, columnHeadersConfig:[{colum
nID:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderTe
xt:"Account Type", columnWidthInPercentage:40}, {columnID:"col2", columnTy
pe:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Number",
columnWidthInPercentage:30}, {columnID:"col3", columnType:constants.DATAGR
ID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPercentage:3
0}], isMultiSelect:true, data:[{col1:"Checking", col2:"490",col3:"$400", m
etainfo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Checking",col2:"4
94", col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}]};
var dgridLayout = {widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, conten
tAlignment:constants.CONTENT_ALIGN_CENTER, containerWeight:99, padding:[5,
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {containerHeight:80};
//Creating the dataGrid.
var dgrid = new kony.ui.DataGrid(dgridBasic, dgridLayout, dgridPSP);

The following is the appearance of the DataGrid widget on various platforms with a specified Master Data,
Header skin, and row skin:
Platform
Appearance
Android
Platform
Appearance
BlackBerry
iPhone
Windows Phone
Platform
Appearance
Mobile Web (BJS)
Adding a DataGrid Widget from IDE

The steps involved in adding a DataGrid widget are as follows:
1. From the IDE, drag and drop the DataGrid widget onto a Form (occupies the complete available width).
a. If you want to resize the DataGrid in the horizontal direction, place an HBox on the Form and
drag and drop the DataGrid inside the HBox and resize accordingly.
b. If you want to resize the DataGrid in the vertical direction, place an HBox on the Form and place
a VBox inside the HBox; and drag and drop the DataGrid inside the VBox and resize
accordingly.
2. Specify the data for the DataGrid either by using the data property from the IDE or from code by using
the DataGrid Methods.
3. (Optional) Use the showColumnHeaders property to specify if the headers must be displayed or not
(they are displayed by default).
4. (Optional) Use the isMultiSelect property to specify if the DataGrid must support multiple selection or
not (multiple selection is supported by default).
5. (Optional) Define an onRowSelected event for the DataGrid.
You can customize the appearance of a DataGrid by using the following properties:
l
gridlineColor: Specifies the color of the gridline.
headerSkin: Specifies the skin to be applied to the DataGrid Header.
rowNormalSkin: Specifies the skin to be applied when the row is not in focus.
rowAlternateSkin: Specifies the skin to be applied to every even row when not in focus.
rowFocusSkin: Specifies the skin to be applied when the row is in focus.
The following are the important considerations for the DataGrid widget:
l
To set the data, you must first specify the columns using the data property from the IDE. If you do not
do this, you will not be able to set data for the DataGrid from the code.
If the DataGrid supports the isMultiSelect property, you must ensure that you have specified the
rowFocusSkin property. Else, you will not be able to distinguish multiple selections.
15.1 DataGrid - Basic Configuration Properties

The basic configuration properties for the DataGrid widget are as follows:
l
columnHeadersConfig
data
gridHeight
headerSkin
id
info
isMultiSelect
isVisible
rowAlternateSkin
rowCount
rowFocusSkin
rowNormalSkin
scrollable
selectedIndex
selectedIndices
selectedItem
selectedItems
showColumnHeaders
15.1.1 columnHeadersConfig
It is a property to define the number of columns and the type of each column and their meta properties. The
number of elements in the Array defines the number of columns. The column JSObject must contain the
properties from following column details properties.
l
columnID [Mandatory] - A unique string identifier to represent a column.
columnType[Mandatory] - Specifies the type of the column. Following are the available options:
l
DATAGRID_COLUMN_TYPE_TEXT (default)
DATAGRID_COLUMN_TYPE_IMAGE
DATAGRID_COLUMN_TYPE_TEMPLATE (supported on desktop web only)
columnHeaderText [Mandatory] - The text string that is displayed as header of column.
columnHeaderTemplate [Mandatory] - The template box reference (a composition of widgets in a

HBox or VBox) to be set as header. This property overrides columnHeaderText (supported on desktop
web only.)
columnDataTemplate [Mandatory]- The template box reference to be used to create a row cell for this
column (supported on desktop web only.)
columnWidthInPercentage [Mandatory] - The amount of width in percentage to be occupied from the

widget space. The sum of all the values in each column should be exactly 100% otherwise the
behavior is undefined. This option is not supported in BlackBerry 10 platform.
isColumnSortable [Optional]- A Boolean property to specify whether the column must be sorted. If
set to true, the rows are reordered as per the sorting order. This option is not supported in Windows
Mango and BlackBerry 10 platforms.
columnOnClick [Optional]- The event callback is invoked by the platform when a column is clicked.
columnContentAlignment [Optional]- Specifies the alignment of the text or image within a column.
This option is not supported in BlackBerry 10 platform.
l
CONTENT_ALIGN_TOP_LEFT
CONTENT_ALIGN_TOP_CENTER
CONTENT_ALIGN_TOP_RIGHT
CONTENT_ALIGN_MIDDLE_LEFT
CONTENT_ALIGN_CENTER (default)
CONTENT_ALIGN_MIDDLE_RIGHT
CONTENT_ALIGN_BOTTOM_LEFT
CONTENT_ALIGN_BOTTOM_CENTER
CONTENT_ALIGN_BOTTOM_RIGHT
Syntax
JavaScript: columnHeadersConfig
Lua: columnheadersconfig
Type
JavaScript: Array of Objects
Lua: Table
Read / Write
No
JavaScript Example
//Defining the properties for dataGrid with columnHeadersConfig :[{column
ID:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT,columnHeaderText
:"Account Type", columnWidthInPercentage:40},{columnID:"col2", columnType:
constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Number", co
lumnWidthInPercentage:30}, {columnID:"col3", columnType:constants.DATAGRID_
COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPercentage:30}]
var dgridBasic = {id:"dgrid",info:{key:"This is datagrid"}, isVisible:true,
headerSkin:"hSkin", rowNormalSkin:"rNSkin", rowFocusSkin:"rFSkin", rowAlte
rnateSkin:"rASkin", showColumnHeaders:true, columnHeadersConfig:[{columnID
:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:
"Account Type", columnWidthInPercentage:40},{columnID:"col2", columnType:c
onstants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Number", col
umnWidthInPercentage:30}, {columnID:"col3", columnType:constants.DATAGRID_
COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPercentage:30}],
isMultiSelect:true,data:[{col1:"Checking", col2:"490",col3:"$400", metainf
o:{skin:"rowskin1",col1_skin:"colskin1"}}, {col1:"Checking",col2:"494", co
l3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.1.2 data
Array of JSObjects which represents the actual data to be rendered in each row. Each element in array
represents one row data.
The row data should be represented as a pair of "columnID" defined from columnHeaderConfig and its value
as per the type of the column.
l
If column type is DATAGRID_COLUMN_TYPE_TEXT, the value should be of String datatype.
If column type is DATAGRID_COLUMN_TYPE_IMAGE, the value should be of String datatype

representing the image filename or url.
If column type is DATAGRID_COLUMN_TYPE_TEMPLATE, the value should be a JSObject with

values assigning to each widgetid.
//Example data for three column datagrid with 3 columns as columnid1 (TEXT
type), columnid2(IMAGE type), columnid3(TEXT type):
data = [{columnid1:"mytext", columnid2:"myimage.png", columnid3:"row one"},
{columnid1:"mytext2", columnid2:"myimage2.png", columnid3:"row tw
o"},
{columnid1:"mytext3", columnid2:"myimage.png", columnid3:"row thre
e"}
] //adding 3 rows
//Example for column with type template: columnid1 (TEXT type), columnid2(
IMAGE type), columnid3(TEMPLATE type) Assuming the template has one label
widget with id "labelwidgetid" and one image widget with id "imagewidgeti
d", the data construct should be as follows:
data = [{columnid1:"mytext", columnid2:"myimage.png", columnid3: {labelwi
dgetid: {text:"labeltext", skin:"blueskin"}, imagewidgetid: {src:"image.pn
g"} },
{columnid1:"mytext2", columnid2:"myimage2.png", columnid3: {labe
lwidgetid: {text:"labeltext", skin:"blueskin"}, imagewidgetid: {src:"image
.png"} }}
] //adding 2 rows
Note: DATAGRID_COLUMN_TYPE_TEMPLATE is supported only in desktop web.
To specify the data within the columns and rows,
) button against the Master Data property.The Data Grid Editor window appears.
Note: You cannot specify data in the Rows tab unless you specify the data in the Column tab.
1. In the Column tab you can specify the following for each column:
a. ID: This is the unique identifier of a column.

b. Header Type: Specifies the header type as grid template or text for a column.
c. Header: Specifies the template name for a column
d. Header Data: Specifies the property values for the widgets defined in the template. For
example, if your template has a Label widget and an Image widget, then you can update Text
and Text i18n Key properties for Label widget and Source property for Image Widget.
e. Column Type: Specifies the column to display a template or text.
f. Column: Specifies the template name for a column.
g. Width in percentage: Specifies the width of the column in percentage.
h. Sort: Specifies if sorting is allowed for the column.
i. Column alignment: Specifies the alignment of the content in each column. The content can be
aligned as, top-left, top-center, top-right, middle-left, middle-center, middle-right, bottom-left,
bottom-center, or bottom-right.
j. OnClick event: Specifies the event that takes place when you click on the header of a column.
To specify an Onclick event for a column, click the ellipses button for that subsequent column.
2. In the Rows tab, all the column headers that you specify in the Column tab appear as the headers for
rows. You can enter the required data for each row.
Note: After specifying the columns and rows, you can alternatively choose to specify the data from the code
by using the DataGrid Methods instead of the data property.
Syntax
JavaScript: data
Lua: data
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for dataGrid with data:[{col1:"Checking",col2:"4
90",col3:"$400", metainfo:{skin:"rowskin1",col1_skin:"colskin1"}}, {col1:"
Checking",col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567", col3:"
$4000"}]
lternateSkin:"rASkin", showColumnHeaders:true, columnHeadersConfig:
[{columnID:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnH

eaderText:"Account Type", columnWidthInPercentage:40},{columnID:"col2", co
lumnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Nu
mber", columnWidthInPercentage:30}, {columnID:"col3", columnType:constants
.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPerce
ntage:30}], isMultiSelect:true, data:[{col1:"Checking", col2:"490",col3:"$
400", metainfo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Checking",
col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.1.3 gridHeight
Specifies the height of the DataGrid based in percentage or in pixel. The percentage is calculated based on
the height of the form.
Default: empty
Syntax
JavaScript: gridHeight
Lua: gridheight
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for dataGrid with gridHeight:8
e, gridHeight:8, rowNormalSkin:"rNSkin", rowFocusSkin:"rFSkin", rowAlterna
teSkin:"rASkin", showColumnHeaders:true, columnHeadersConfig:[{columnID:"c
ol1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Ac
count Type", columnWidthInPercentage:40},{columnID:"col2", columnType:cons
tants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Number", column
WidthInPercentage:30}, {columnID:"col3", columnType:constants.DATAGRID_COL
UMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPercentage:30}], i
sMultiSelect:true, data:[{col1:"Checking", col2:"490",col3:"$400", metainf
o:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Checking",col2:"494", c
ol3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
Available on Desktop Web platform only.
15.1.4 headerSkin
This is a skin property. This property specifies the skin that must be applied to the Header row.
Syntax
JavaScript: headerSkin
Lua: headerskin
Type
JavaScript: String
Lua: String
Read / Write
Note: On Windows Phone (Mango) platform, you cannot write data to this property.
JavaScript Example
//Defining the properties for dataGrid with headerSkin :"hSkin"
xt:"Account Type", columnWidthInPercentage:40},{columnID:"col2", columnTyp
e:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Number",
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.1.5 id
id is a unique identifier of a DataGrid consisting of alpha numeric characters. Every DataGrid widget should
have a unique id within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for dataGrid with ID :"dgrid".
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.1.6 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for dataGrid with info property.
var dgridBasic = {id:"dgrid", isVisible:true, headerSkin:"hSkin", rowNorma
lSkin:"rNSkin", rowFocusSkin:"rFSkin", rowAlternateSkin:"rASkin", showColu
mnHeaders:true, columnHeadersConfig:[{columnID:"col1", columnType:constant
s.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Type", columnWidthI
nPercentage:40},{columnID:"col2", columnType:constants.DATAGRID_COLUMN_TYP
E_TEXT, columnHeaderText:"Account Number", columnWidthInPercentage:30}, {c
olumnID:"col3", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHead
erText:"Balance", columnWidthInPercentage:30}], isMultiSelect:true, data:[
{col1:"Checking", col2:"490",col3:"$400", metainfo:{skin:"rowskin1", col1_
skin:"colskin1"}}, {col1:"Checking",col2:"494", col3:"$2000.34"}, {col1:"S
avings",col2:"567",col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
dgrid.info ={key:"This is datagrid"};
Accessible from IDE

No
15.1.7 isMultiSelect
An option to make the datagrid as multi selectable row. The selected rows are indicated by highlighting the
rows by focus skin.
Default: false
Note: Ensure to specify rowFocusSkin, otherwise the user won't be able to visually identify the selected
rows.
if set to true, multiple rows are selected.
if set to false, multiple rows are not selected.
Syntax
JavaScript: isMultiSelect
Lua: ismultiselect
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for dataGrid with isMultiSelect:true.
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.1.8 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for dataGrid with isVisible:true.
var dgridBasic = {id:"dgrid", info:{key:"This is datagrid"},
isVisible:true, headerSkin:"hSkin", rowNormalSkin:"rNSkin", rowFocusSkin:"
rFSkin", rowAlternateSkin:"rASkin", showColumnHeaders:true, columnHeadersC
onfig:[{columnID:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, c
olumnHeaderText:"Account Type", columnWidthInPercentage:40},{columnID:"col
2", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Acco
unt Number", columnWidthInPercentage:30}, {columnID:"col3", columnType:con
stants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthI
nPercentage:30}], isMultiSelect:true, data:[{col1:"Checking", col2:"490",c
ol3:"$400", metainfo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Chec
king",col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$400
0"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.1.9 rowAlternateSkin
The row normal skin which is applied to the alternate rows.
Syntax
JavaScript: rowAlternateSkin
Lua: rowalternateskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for dataGrid with rowAlternateSkin:"rASkin".
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
Available on all platforms except Windows Kiosk and BlackBerry 10
15.1.10 rowCount
Returns the number of rows in the DataGrid.
Syntax
JavaScript: rowCount
Lua: rowcount
Type
JavaScript: Number
Lua: Number
Read / Write
Yes (Read only)
JavaScript Example
$4000"}]
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};

//Reading the rowCount of the dataGrid.
alert("dataGrid rowCount is ::"+dgrid.rowCount);
Accessible from IDE

No
This is a skin property. This property specifies the skin that must be applied when the row is in focus.
Syntax
JavaScript: rowFocusSkin
Lua: rowfocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for dataGrid with rowFocusSkin :"rFSkin".
tAlignment:constants.CONTENT_ALIGN_CENTER, containerWeight:99, padding:
[5,5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
//Reading the rowFocusSkin of the dataGrid.
alert("dataGrid rowFocusSkin is ::"+dgrid.rowFocusSkin);
Accessible from IDE

Yes
15.1.12 rowNormalSkin
This is a skin property. This property specifies the skin that must be applied when the row is not in focus.
Syntax
JavaScript: rowNormalSkin
Lua: rownormalskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for dataGrid with rowNormalSkin:"rNSkin".
ID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance",
columnWidthInPercentage:30}], isMultiSelect:true, data:[{col1:"Checking",

col2:"490",col3:"$400", metainfo:{skin:"rowskin1", col1_skin:"colskin1"}},
{col1:"Checking",col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567",
col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
//Reading the rowNormalSkin of the dataGrid.
alert("dataGrid rowFocusSkin is ::"+dgrid.rowNormalSkin);
Accessible from IDE

Yes
15.1.13 scrollable
Specifies if the DataGrid must have scrollbars.
Default: false
if set to false, the scrollbars are not displayed.
Syntax
JavaScript: scrollable
Lua: scrollable
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for dataGrid with scrollable:true
e, scrollable:true, rowNormalSkin:"rNSkin", rowFocusSkin:"rFSkin", rowAlte
rnateSkin:"rASkin", showColumnHeaders:true, columnHeadersConfig:[{columnID
:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:
"Account Type", columnWidthInPercentage:40},{columnID:"col2", columnType:c
onstants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account Number", col
umnWidthInPercentage:30}, {columnID:"col3", columnType:constants.DATAGRID_
COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPercentage:30}],
isMultiSelect:true, data:[{col1:"Checking", col2:"490",col3:"$400", metain
fo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Checking",col2:"494",
col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
This property returns the user selected row index.
Note: This property is applicable only if the isMultiSelect property is set to false.
Syntax
JavaScript: selectedIndex
Lua: selectedindex
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
$4000"}]
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
//Reading the selectedIndex of the dataGrid.
alert("dataGrid selectedIndex is ::"+dgrid.selectedIndex);
Accessible from IDE

No
This property returns the list of user selected row object indexes. If "isMultiSelect" is set to false, the list will
contain only one entry.
Note: This property is applicable only if the isMultiSelect property is set to true.
Syntax
JavaScript: selectedIndices
Lua: selectedindices
Type
Lua: Table
Read / Write
Yes (Read only)
JavaScript Example
$4000"}]
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
//Reading the selectedIndices of the dataGrid.
kony.print("dataGrid selectedIndices are ::"+dgrid.selectedIndices);
Accessible from IDE

No
Returns the data in the selected rows of the DataGrid.
Note: This property is applicable only if the isMultiSelect property is set to false.
Syntax
JavaScript: selectedItem
Lua: selecteditem
Type
Lua: Table
Read / Write
Yes (Read only)
JavaScript Example
$4000"}]
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
//Reading the selectedItem of the dataGrid.
alert("dataGrid selectedItem is ::"+dgrid.selectedItem);
Accessible from IDE

No
15.1.17 selectedItems
This property returns the list of user selected row objects. If "isMultiSelect" is set to false, the list will contain
only one entry.
Note: This property is applicable only if the isMultiSelect property is set to true.
Syntax
JavaScript: selectedItems
Lua: selecteditems
Type
Lua: Table
Read / Write
Yes (Read only)
JavaScript Example
$4000"}]
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
//Reading the selectedItems of the dataGrid.
kony.print("dataGrid selectedItems are ::"+dgrid.selectedItems);
Accessible from IDE

No
15.1.18 showColumnHeaders
This property controls the visibility of the column headers of the DataGrid.
Default: true
If set to false, the column headers are not displayed.
If set to true, the column headers are displayed.
Syntax
JavaScript: showColumnHeaders
Lua: showcolumnheaders
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for dataGrid with showColumnHeaders :true.
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};

//Reading the showColumnHeaders of the dataGrid.
alert("dataGrid showColumnHeaders is ::"+dgrid.showColumnHeaders);
Accessible from IDE

Yes
15.2 DataGrid - Layout Properties

The layout properties for DataGrid widget are as follows:
l
containerWeight
contentAlignment
margin
padding
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for dataGrid with containerWeight:70.
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

No
Specifies the alignment of the text on the DataGrid with respect to its boundaries. A default value CONTENT_
Default: CONTENT_ALIGN_CENTER
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the widget.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the widget.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the widget.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the widget.
CONTENT_ALIGN_CENTER - Specifies the text should align at center of the widget.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the widget.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the widget.

widget.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the widget.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for dataGrid with contentAlignment:constants.CON
TENT_ALIGN_CENTER.
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.2.3 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for dataGrid with margin:[5,5,5,5].
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
15.2.4 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for dataGrid with padding:[5,5,5,5].
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};
Accessible from IDE

Yes
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for dataGrid with widgetAlignment:constants.WIDG
ET_ALIGN_TOP_LEFT.
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {};

Accessible from IDE

Yes
15.3 DataGrid - Platform Specific Properties

The platform specific properties for DataGrid widget are as follows:
l
containerHeight
containerHeightInPixel
dockingHeader
enableScrollBar
gridlineColor
hoverSkin
selectedCellItem
selectedCellIndex
toolTip
Specifies the container height of the datagrid in percentage (%). Height is calculated with respect to the width
of the datagrid.
Syntax
Type
JavaScript: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for dataGrid with containerHeight:80.
[5,5,5,5], margin:[5,5,5,5]};
var dgridPSP = {containerHeight:80};
Accessible from IDE

Yes
15.3.2 containerHeightInPixel
Specifies the container height of the datagrid in pixels.
Syntax
JavaScript: containerHeightInPixel
Type
JavaScript: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for dataGrid with containerHeightInPixel:80.
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {containerHeightInPixel:80};

Accessible from IDE

Yes
15.3.3 dockingHeader
Specifies if headers are to be docked in the datagrid.
Default:false
If set to true, the headers are docked in the datagrid.
If set to false, the headers are not docked in the datagrid.
Syntax
JavaScript: dockingHeader
Type
JavaScript: Boolean
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for dataGrid with dockingHeader:true.
[5,5,5,5], margin:[5,5,5,5]};
var dgridPSP = {dockingHeader:true;
Accessible from IDE

Yes
15.3.4 enableScrollBar
Specifies if the scrollbars on the datagrid is to be displayed vertically or the default option is to be retained.
Default: DATAGRID_SCROLLBAR_NONE
l
DATAGRID_SCROLLBAR_NONE::Specifies that no scrollbars are to be applied to datagrid.
DATAGRID_SCROLLBAR_VERTICAL :Specifies that the scrollbars are to be displayed vertically.
Syntax
JavaScript: enableScrollBar
Type
JavaScript: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for dataGrid with enableScrollBar:constants.DATA
GRID_SCROLLBAR_VERTICAL.
0}], isMultiSelect:true, data:[{col1:"Checking", col2:"490",col3:"$400",
metainfo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Checking",col2:"

5,5,5], margin:[5,5,5,5]};
var dgridPSP = {enableScrollBar:constants.DATAGRID_SCROLLBAR_VERTICAL};
Accessible from IDE

Yes
15.3.5 gridlineColor
Specifies the color of the grid line of the DataGrid. The color should be specified in the format of "RGBA" in
hex. For example "FF224400".
Syntax
JavaScript: gridlineColor
Lua: gridlinecolor
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Write only)
JavaScript Example
//Defining the properties for dataGrid with gridlineColor:"FF224400".
columnWidthInPercentage:30}, {columnID:"col3",
columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance",
columnWidthInPercentage:30}], isMultiSelect:true, data:[{col1:"Checking",
col2:"490",col3:"$400", metainfo:{skin:"rowskin1", col1_skin:"colskin1"}},
col3:"$4000"}]};
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {gridlineColor:"FF224400"};
The following image illustrates the Gridline color applied to the DataGrid:
Accessible from IDE

Yes
l
BlackBerry
BlackBerry 10
15.3.6 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
JavaScript Example
//Defining the properties for dataGrid with hoverSkin:"hskin".
5,5,5], margin:[5,5,5,5]};
var dgridPSP = {hoverSkin:"hskin"};
Accessible from IDE

Yes
15.3.7 selectedCellItem
Returns the data object associated with the user selected row and columnID combination.
Syntax
JavaScript: selectedCellItem
Type
Read / Write
Yes - (Read only)
JavaScript Example
var dgridBasic = {id:"dgrid", info:{key:"This is datagrid"},
isVisible:true, headerSkin:"hSkin", rowNormalSkin:"rNSkin", rowFocusSkin:"

rFSkin", rowAlternateSkin:"rASkin", showColumnHeaders:true, columnHeadersC
onfig:[{columnID:"col1", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, c
olumnHeaderText:"Account Type", columnWidthInPercentage:40}, {columnID:"co
l2", columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Acc
ount Number", columnWidthInPercentage:30}, {columnID:"col3", columnType:co
nstants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidth
InPercentage:30}], isMultiSelect:true, data:[{col1:"Checking", col2:"490",
col3:"$400", metainfo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Che
cking",col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$400
0"}]};
5,5,5], margin:[5,5,5,5]};
//Reading the selectedCellItem of the dataGrid.
kony.print("dataGrid selectedCellItem is ::"+dgrid.selectedCellItem);
Accessible from IDE

No
l
Desktop Web
BlackBerry 10
15.3.8 selectedCellIndex
Returns the user selected row index and the associated columnid as specified by the developer while defining
the columns. For example, first row with column id of "item1" is provided as [1, "item1"];
Syntax
JavaScript: selectedCellIndex
Type
JavaScript: Array
Read / Write
Yes - (Read only)
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//Reading the selectedCellIndex of the dataGrid.
kony.print("dataGrid selectedCellIndex is ::"+dgrid.selectedCellIndex);
Accessible from IDE

No
l
Desktop Web
BlackBerry 10
15.3.9 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Datagrid with toolTip:sample text
var dgridBasic={id:"datagrid1", isVisible:true, skin:"dgridSkin", focusSki
n:"dgridFSkin", text:"Click Here" };
var dgridLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], h
var dgridPSP={toolTip:"sample text"};
//Creating the Datagrid.
var datagrid1 = new kony.ui.Datagrid(dgridBasic, dgridLayout, dgridPSP);
Accessible from IDE

Yes
15.4 DataGrid - Events

DataGrid has the following event associated with it:
l
onRowSelected
15.4.1 onRowSelected
An event callback that is invoked by the platform when a row is selected.
Syntax
JavaScript: onRowSelected
Lua: onrowselected
Read / Write
Yes - (Write only)
JavaScript Example
//The below function is the callback function for onRowSelected event.
function onRowSelectedCalBck(dGrid)
{
/*write your logic*/
}
94", col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}], onRowSel
ected:onRowSelectedCalBck};
5,5,5], margin:[5,5,5,5]};
Accessible from IDE

Yes
15.5 DataGrid - Methods

DataGrid has the following methods associated with it:
l
addAll
addDataAt
applyCellSkin
removeAll
removeAt
selectAllRows
setCellDataAt
setData
setDataAt
15.5.1 addAll
This method allows you to add new data to the DataGrid. The new data is appended to the existing data. If the
DataGrid has no data, the new data is placed in the DataGrid.
Signature
JavaScript: addAll(data)
Lua:datagrid.addall(datagridid, data)
Input Parameters
data [array of rows] - Mandatory
Specifies the JSObject that represents the row data as key value pairs. The format of the array of
data is as explained in data property of DataGrid basic properties.
datagridid [widgetref] - Mandatory
Return Values
None
JavaScript Example
xt:"Account Type", columnWidthInPercentage:40}, {columnID:"col2",
columnType:constants.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Account
Number", columnWidthInPercentage:30}, {columnID:"col3", columnType:constan
ts.DATAGRID_COLUMN_TYPE_TEXT, columnHeaderText:"Balance", columnWidthInPer
centage:30}], isMultiSelect:true, data:[{col1:"Checking", col2:"490",col3:
"$400", metainfo:{skin:"rowskin1", col1_skin:"colskin1"}}, {col1:"Checking
",col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567",col3:"$4000"}],
onRowSelected:onRowSelectedCalBck};
5,5,5], margin:[5,5,5,5]};
//addAll method call.
dgrid.addAll([{col1:"Savings",col2:"568",col3:"$3000"}]);
Error Codes
None
15.5.2 addDataAt
Allows you to set a row of data at a given index. The new data is placed before the index. The existing data is
pushed to the next row.
Signature
JavaScript: addDataAt(data, rowIndex)
Lua:datagrid.adddataat(datagridid, data, rowindex)
Input Parameters
rowIndex [Number] - Mandatory
The row index.
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//addDataAt method call.
dgrid.addDataAt({col1:"Savings",col2:"569",col3:"$32000"},2);
Error Codes
None
15.5.3 applyCellSkin
Specifies the skin (background color) to be applied to a cell.
Note: The skin set in this property takes precedence over the skin set using rowNormalSkin.
Signature
JavaScript: applyCellSkin(rowindex, columnid, skinid)
Lua:datagrid.applycellskin(datagridid, rowindex, columnid, skinid)
Input Parameters
rowindex [Number] - Mandatory
The row index: 1 <= index <= n; Where n is the number of rows.
columnid [String] - Mandatory
The column identifier.
skinid [Object]
Handle to the skin.
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//applyCellSkin method call.
dgrid.applyCellSkin(3,"col2");
Error Codes
None
15.5.4 removeAll
This method is used to remove all the existing rows in the DataGrid. If you use this method, the data in the
DataGrid will not be visible.
Signature
JavaScript: removeAll()
Lua:datagrid.removeall(datagridid)
Input Parameters
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//removeAll method call.
dgrid.removeAll();
Error Codes
None
15.5.5 removeAt
This method is used to remove all the existing rows in the DataGrid.
Signature
JavaScript: removeAt(rowIndex)
Lua:datagrid.removeat(datagridid, rowIndex)
Input Parameters
The the row index: 1 <= index <= n; Where n is the number of rows.
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};

//removeAt method call.
dgrid.removeAt(2);
Error Codes
None
15.5.6 selectAllRows
Selects or clears the row selection in a multi-selectable DataGrid.
Signature
JavaScript: selectAllRows(select)
Lua:datagrid.selectallrows(datagridid, select)
Input Parameters
select [Boolean] - Mandatory
To select all the rows, set the value to true and to clear all the row selections, set the value to false.
Return Values
None
JavaScript Example
etainfo:{skin:"rowskin1", col1_skin:"colskin1"}},

col3:"$4000"}], onRowSelected:onRowSelectedCalBck};
5,5,5], margin:[5,5,5,5]};
//selectAllRows method call.
dgrid.selectAllRows(true);
Error Codes
None
15.5.7 setCellDataAt
Allows you to set data in a specific row and column. The existing data of the row and column will be replaced
with the new set. In case the index is not valid the operation is ignored.
Signature
JavaScript: setCellDataAt(rowindex, columnID, datavalue)
Lua:datagrid.setcelldataat(datagridid, rowindex, columnID, datavalue)
Input Parameters
columnID [String] - Mandatory
The column identifier.
datavalue [JS Object] - Mandatory
Based on the column type, the value is expected to be either string type or object type for template
column.
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//setCellDataAt method call
dgrid.setCellDataAt(1,"col2","444");
Error Codes
None
15.5.8 setData
This method allows you to set new data to the DataGrid. When you set new data, the existing data will be
replaced with the new data. If the DataGrid has no data, the new data is placed in the DataGrid.
Signature
JavaScript: setData(data)
Lua:datagrid.setdata(datagridid, data)
Input Parameters
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//setData method call.
dgrid.setData([{col1:"Checking", col2:"490", col3:"$400", metainfo:{skin:"
rowskin1",col1_skin:"colskin1"}}, {col1:"Checking",col2:"494", col3:"$2000
.34"}, {col1:"Savings", col2:"567",col3:"$4000"}]);
Error Codes
None
15.5.9 setDataAt
Allows you to set a row of data at a given index. The existing data of the row will be replaced with the new set.
In case the index is not valid the operation is ignored.
Signature
JavaScript: setDataAt(data, rowIndex)
Lua:datagrid.setdataat(datagridid, data, rowindex)
Input Parameters
Return Values
None
JavaScript Example
5,5,5], margin:[5,5,5,5]};
//setDataAt method call.

dgrid.setDataAt({col1:"Savings",col2:"563",col3:"$34000"},2);
Error Codes
None
15.6 DataGrid - Templates

Note: DataGrid templates are supported only on Desktop Web platform.
15.6.1 What is a Template for DataGrids

Grid Template is an HBox in which the developer adds the required widgets and set their alignment. These
templates are used to render columns and rows in the grid when the grid column is set to be of type template.
15.6.2 Where to use a Grid Template

Grid Templates are used to display the data as well as widgets in a DataGrid.
The Grid Templates are used to:
l
support template type to columns.
support template type to headers.
specify the column span while setting the data to the column.
15.6.3 Creating a Template for DataGrid

When you want the same information to be displayed across all the DataGrids in the application, you have a
provision to add a Grid Template using Kony Studio.
To create a grid template at the application-level, follow these steps:
2. Expand the application for which you want to create the Grid Template.
3. Navigate to templates > grids, right-click desktop and select New Grid Template. The Create a New
Grid window appears.
iii. Drag and drop an HBox or a VBox within an HBox.
Note: Only HBox and VBox are supported on the form. You can put other widgets
within these widgets. The widgets that can be dragged into the container are displayed
in the Palette view.
iv. Drag and drop the required widgets onto the HBox/ VBox. Set the properties of these
widgets.
v. A grid template is created.
You can set the created grid template for a row or a column using the Master Data Property of DataGrid.
Previously in the Master Data property for a DataGrid you could only specify text for the column header
template and column template. Using the Grid template, you can set images to be a part of the column header
template or the column template.
You can use the following widgets to define a Grid Template:

l
HBox
VBox
Button
Calendar
CheckBoxGroup
ComboBox
Image
Label
Line
Link
RadioButtonGroup
RichText
TextArea
TextBox
15.6.4 Using Grid Template

You can create separate templates for column Headers and Rows using the above process.
To use Grid Template in an application, follow these steps:
2. Expand the application for which you want to use DataGrid.
window appears.
5. Drag-drop a DataGrid on the form and set data using data property.
16. Image
Image widget is a non-interactive widget that you can use to display a graphic (local or remote) from a PNG
file.
You can use an Image widget in the following scenarios:
l
to display your company's logo.
to display a snapshot.
to provide an illustration.
Image provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
and an Event.
Basic Properties
Layout Properties
base64
id
imageWhenFailed
imageWhileDownloading
info
isVisible
rawBytes
src
containerWeight
imageScaleMode
margin
marginInPixel
padding
paddingInPixel
referenceHeight
referenceWidth
widgetAlignment
Events
Deprecated
onDownloadComplete
hExpand
scaleMode
vExpand
Platform Specific
Properties
glossyEffect
hoverSkin
renderAsAnchor
skin
toolTip
Creating an Image using a constructor: kony.ui.Image2

var myimage = new kony.ui.Image2 (basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Creating the Image with isVisible:true.
var basicConfImage ={id : "imageIdTest", isVisible:true, src:"http://www.f
ordesigner.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png", im
ageWhenFailed:"rn_icon1.png", imageWhileDownloading:"konynew.png"};
var layoutConfImage = {containerWeight:100};
var PSPConfImage = {glossyEffect:constants.MAGE_GLOSSY_EFFECT_RADIAL};

var imageIdTest = new kony.ui.Image2(basicConfImage, layoutConfImage, PSPC
onfImage);
//Reading the visibility of the Image
alert("Image visibility is ::"+imageIdTest.isVisible);
kony.ui.Image.
var Image1 = new kony.ui.Image(basicConf, layoutConf, pspConf)
Adding an Image Widget from IDE
The steps involved in adding an Image widget are as follows:
1. From the IDE, drag and drop the Image widget onto a Form (occupies the complete available width).
a. If you want to resize the Image widget in the horizontal direction, place an HBox on the Form
and drag and drop the Image inside the HBox and resize accordingly.
b. If you want to resize the Image widget in the vertical direction, place an HBox on the Form and
place a VBox inside the HBox; and drag and drop the Image inside the VBox and resize
accordingly.
2. Specify the image (local or remote) that must be displayed using the src property.
Note: To specify a local image, you must add the PNG file (the file name must follow a particular naming
convention) to the resources folder of the Application. For more information on how to add these files, see
the Working with Resources section of the Kony Studio User Guide.
3. (Optional) You can alternatively choose to display an image captured from a camera by using the
rawBytes property. Or, you can convert the raw bytes to base64 encryption format and set the same to
base64 property.
4. (Optional) If you are specifying a remote image, you can use the following properties as per your
requirement:
l
ImageWhenFailed: Specifies the image to indicate that the image (that is being downloaded) is
not available.
ImageWhileDownloading: Specifies the image to indicate that the download is taking place over
a network connection.
Note: These properties are not supported by the Mobile Web platform. A broken image appears in the
browser if a downloadable image is not available.
l
imageScaleMode: Specifies the scale mode of the downloaded image.
You can customize the appearance of the Image widget by using the following properties:
l
Naming Convention
To specify a local image, you must add the PNG 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 Kony
Studio User Guide.
The files that you add must follow a particular naming convention. The following is the naming convention that
you must follow:
l
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

contains uppercase character and an
underscore.
accntsummary.PNG
aCCNT&summary.PNG

contains uppercase characters and
special character
accountdetails.png
Details.PNG

contains uppercase character.
flightstatus123.png
continue.PNG
The file name contains a Java keyword.
Note: Kony Studio does not recognize images that have invalid file names.
16.1 Image - Basic Properties

The basic properties for Image widget are as follows:
l
base64
id
imageWhenFailed
info
isVisible
rawBytes
src
16.1.1 base64
Returns the base64 encoded string of the image raw bytes.
If the image source is a URL, and if the image is not downloaded, or if it encounters an error while
downloading, null is returned.
Note: SPA platform does not support reading base64 from an image src. But it can read base64 from an
image which is displayed through base64.
Syntax
JavaScript: base64
Lua: base64
Type
Lua: UserData
Read / Write
JavaScript Example
//Using base64 property in a form frmBase64.
function readb()
{
var br=frmBase64.image.base64;
frmBase64.labelbase.text="base " + br;
}
function writeb()
{
frmBase64.image.base64="iVBORw0KGgoAAAANSUhEUgAAACMAAAAjCAYAAAAe2bNZAAAAA
XNSR0IArs4c6QAAAARnQU
1BAACxjwv8YQUAAAAJcEhZcwAADsMAAA7DAcdvqGQAAAI3SURBVFhH7Zg9U8JAEIZTKyryGUgG
EEUUEQTHEnsbK34ANjZqjWMpM
5baYy09jRU2VlJLT2dD5x848x5euEBCLpIAhcUxDNnbe+7dvb0N0tflFjn1y6S8svghfd+kyV1
RWR6Y1/OEI5jKaozU1hPkMbBj
Ou430/S5U7WpMu/VpO3EM59CmsFd8ikfkoFSEh7t8D652rD3D3AKg2G1C6jwEsoKL24Fik1gQ9
PUojBIYjMjyN2PFWcGYYDwNU0
lyzC5oYaVSnW/+eYpzMOJalDGSxAGaAYkjdcZGDlJ0L/aImTVNaMIEq8KktXNHLED7URyhohIf
OLOIzzjgHy4dBgcO7udePGcV0
eHQUHzYjERn6z+6DBOK6vIIqI2rPZQGGS16EQv7HDH0esAHyDzYhFRn7i/dBiQiU70wo4lMVXm
H4ZrQ4zKhDKLDZN8MMqZ2oITu
BnODmFYezhQxbs3t5O4Hvo92migQNXRpHJ7ESF/iTKp+OJDZXAN4EtdgxKa7KD/FfHXig5rDIX
hL6p5tg8UVFPlIjTqvyX8yMga
ge25qvOsjPUzgOG7diglIu+sNt1USc8VPUw4Tejw2A8A6ytHngL1UqOk5Zs7Q6fHHuAW9yp/us
lJRXRlrF6qoNBHNO+eQloda6n
5idDYKsMMcP4bWkHqxQszQUGNWsD8XUkYhodqRrLOoJLHpK3kyW0kY/sebxsms/BBqetgmrRiO
fKmFkzHk7xHAVhVdfJPhGkCO3
Hgpu1SwfwALZUki7xaRB8AAAAASUVORK5CYII=";
}
Accessible from IDE

No
Available on all platforms except all Server side Mobile Web platforms
16.1.2 id
id is a unique identifier of Image consisting of alpha numeric characters. Every Image should have a unique id
within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for an Image with the ID :"imageIdTest".
var basicConfImage ={id : "imageIdTest", isVisible:true,
src:"http://www.fordesigner.com/imguploads/Image/cjbc/zcool/png20080525/12
11728825.png"};
//Creating the Image.
var imageIdTest = new kony.ui.Image2(basicConfImage, layoutConfImage, {});
//Reading the id of the Image.
alert("Image id is ::"+imageIdTest.id);
Accessible from IDE

Yes
Specifies the image to be displayed when the remote resource is not available. This image is taken from the
resources folder.
Syntax
JavaScript: imageWhenFailed
Lua: imagewhenfailed
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for an Image with the imageWhenFailed:"rn_icon1.png",
".png" image should be in resources folder.
var basicConfImage ={id : "image1", isVisible:true, src:"http://www.fordes
igner.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png", imageWh
enFailed:"rn_icon1.png"};
var image1= new kony.ui.Image2(basicConfImage, layoutConfImage, {});
Accessible from IDE

Yes
Specifies the image to be displayed when the remote source is still being downloaded. This image is taken
from the resources folder.
Syntax
JavaScript: imageWhileDownloading
Lua: imagewhiledownloading
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for an Image with the imageWhileDownloading:"konynew
.png", ".png" image should be in resources folder.
enFailed:"rn_icon1.png", imageWhileDownloading:"konynew.png"};
var image1 = new kony.ui.Image2(basicConfImage, layoutConfImage, {});
Accessible from IDE

Yes
16.1.5 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for an Image with the info property.
var basicConfImage ={id : "imageIdTest", isVisible:true, src:"http://www.f
ordesigner.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png"};
var imageIdTest = new kony.ui.Image2(basicConfImage, layoutConfImage, {});
imageIdTest.info = {key:"Imagenumber"};
//Reading the info of the Image.
alert("Image info is ::"+imageIdTest.info);
Accessible from IDE

No
16.1.6 isVisible
This property controls the visibility of a widget on the Form.
Default: true
Segment, the visibility of the widget is controlled by the data property of the segment.
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for an Image with isVisible:true
enFailed:"rn_icon1.png",imageWhileDownloading:"konynew.png"};
//Reading the visibilty of the Image
alert("Image visibility is ::"+imageIdTest.isVisible);
Accessible from IDE

Yes
16.1.7 rawBytes
Represents the images raw bytes.
Syntax
Lua: rawbytes
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for an Image with rawBytes:"11111"(This data sho
uld be returned from camera).
var basicConfImage={id:"Image1",isVisible:true, src:"http://www.fordesigne
r.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png", imageWhenFa
iled:"rn_icon1.png", imageWhileDownloading:"konynew.png",
rawBytes:"11111"};
layoutConfImage = {containerWeight:100}, hExpand:true};
var Image1= new kony.ui.Image2(basicConfImage, layoutConfImage, {});
//Reading rawBytes of the Image.
alert("Image rawBytes ::"+Image1.rawBytes);
Accessible from IDE

Yes
16.1.8 src
Specifies the source of the image to be displayed. You can specify an image from the resources folder or
specify a URL of the image.
To specify a URL, enter the address (beginning with http or https) in the default, Mobile Native App, Mobile
Web, or all the three tabs of the Image Location screen.
To select an image from the resources folder, select Browse.
Note: If the given source points to a HTTP URL the images will be a cached based on the Etag (or Entity
tag) which is typically used for cache validation of web resources.
Syntax
JavaScript: src
Lua: src
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for an Image with the src:"http://www.fordesigne
r.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png", we can give
External URL or the image directly from resources folder.
var basicConfImage ={id:"image1", isVisible:true, src:"http://www.fordesig
ner.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png", imageWhen
Failed:"rn_icon1.png", imageWhileDownloading:"konynew.png"};
//Reading the src of the Image.
alert("Image src is ::"+imageIdTest.src);
Accessible from IDE

Yes
16.2 Image - Layout Properties

The layout properties for Image widget are as follows:
l
containerWeight
imageScaleMode
margin
marginInPixel
padding
paddingInPixel
referenceHeight
referenceWidth
widgetAlignment
Specifies percentage of weight to be allocated by its parent widget. The parent widget space is distributed to
its child widgets based on this weight factor. All its child widgets should sum up to 100% of weight except
when placed in kony.ui.ScrollBox.
This property specifies the maximum width of the Image widget and the actual image content fit in this
boundary based on the scale modes.
Note: If you want to restrict the width of the image, then choose the appropriate container weight. It
becomes developer responsibility to serve the right kind of images as per device screen form factors.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for an Image with containerWeight:50
//Reading the containerWeight of the Image
alert("Image containerWeight is ::"+image1.containerWeight);
Accessible from IDE

No
This property specifies how the rendered image's width and height are identified when those of the source
image varies from the Image widget itself. Image Widget represents the underlying native widget which
renders (and applies alignment to) the Source Image.
Default: IMAGE_SCALE_MODE_MAINTAIN_ASPECT_RATIO
Note: When this property is modified programmatically from the code, the scale mode changes will be
reflected when a new source image is rendered.
Aspect Ratio defined:
The image aspect ratio is the width (x) of the image compared to its height (y). A square image has a ratio of
1:1, but a non-square (rectangular) image does not have the same height and width. It is commonly expressed
as two numbers separated by a colon, as in 16:9.
How the size of the image rendered on the screen is identified?
Before rendering the Image first the width and height of the Image widget is calculated. The width and height
are driven by the container weight that has been specified or referenceWidth and referenceHeight whichever
are applicable. Now the Source Image is scaled or cropped as per the ImageScale modes set in the property.
Note: For dynamic images (loaded from a remote server), specifying a referenceWidth / referenceHeight
avoids unnecessary screen re-layouts.
Note: The ImageWidget is aligned as per the widget alignment rules.
IMAGE_SCALE_MODE_MAINTAIN_ASPECT_RATIO: This mode resizes the source image to fit in

the ImageWidget dimensions while it preserves its native aspect ratio. In case,
l
If the source image size is less than the ImageWidget size then source image is rendered as is.
The ImageWidget is aligned as per the widget alignment rules.
If the source image is size is greater than the ImageWidget size then the source image is
resized to the ImageWidget dimensions while maintaining the aspect ratio.
Image Widget size is calculated as follows:

l
Width is based on containerWeight in case of percentage box and in case of non

percentage box , the width is derived from referenceWidth or the original source image
width.
Height is derived from reference height specified, if reference height is specified. If not
the actual Image height is taken.
Note: referenceWidth and referenceHeight are not mandatory for this
scalemode.
IMAGE_SCALE_MODE_CROP: This scale mode preserves the original size of the Source Image. In
case,
l
cropped or clipped to fit the ImageWidget.
Image Widget size is calculated for this mode as follows:
Width is based on containerWeight in case of percentage box and in case of nonpercentage box , the width is derived from referenceWidth.
Height is derived from referenceHeight, if referenceHeight is specified. If not the actual

Image height is taken.
Note: referenceWidth and referenceHeight are not mandatory for this scalemode. This mode is not
supported on Server side Mobile Web, Desktop Web, and SPA platforms. They will render the sourceImage
as its actual size.
IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS: The source image is resized to fill the

ImageWidget dimensions. The aspect ratio is not preserved. In case,
l
If the source image size is less than the ImageWidget size then source image is stretched to
the ImageWidget dimensions (height and width).
squeezed to fill the ImageWidget dimensions (height and width).

l
Width is the minimum of containerWeight and referenceWidth in case of percentage box

and in case of non-percentage box , the width is derived from referenceWidth.
Height is derived from reference height specified.
Note: referenceWidth and referenceHeight are mandatory for this scalemode. Not specifying the
referenceWidth / referenceHeight will lead to undefined behaviour.
Note: If the reference image is bigger than container weight, Mobile Web and SPA platforms may not be
able to adhere to the container weight but will spill over.
Syntax
JavaScript: imageScaleMode
Lua: imagescalemode
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for an Image with imageScaleMode:IMAGE_SCALE_MOD
E_FIT_TO_DIMENSIONS
var basicConfImage = {id : "image1", isVisible:true, src:"http://www.forde
signer.com/imguploads/Image/cjbc/zcool/png20080525/1211728825.png", imageW
henFailed:"rn_icon1.png", imageWhileDownloading:"konynew.png"};
var layoutConfImage = {containerWeight:50, imageScaleMode:constants.IMAGE_
SCALE_MODE_FIT_TO_DIMENSIONS};
//Reading the imageScaleMode of the Image.
alert("Image imageScaleMode is ::"+image1.imageScaleMode);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and SPA. The option IMAGE_SCALE_
MODE_CROP is not supported on Desktop Web.
16.2.3 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for an Image with margin:[10,10,10,10].
var layoutConfImage = {containerWeight:100, margin:[10,10,10,10]};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for an Image with margin in pixels.
var layoutConfImage = {containerWeight:100, margin:[10,10,10,10], marginIn
Pixel:true};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
16.2.5 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for an Image with padding :[10,10,10,10]
var layoutConfImage = {containerWeight:100, padding:[10,10,10,10]};
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for an Image with padding in pixels.
var layoutConfImage = {containerWeight:100, padding:[10,10,10,10], padding
InPixel:true};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
It is the reference image height in pixels. The source image height is resized to fill the widget dimensions. The
image aspect ratio is not preserved. The referenceHeight is respected only when the imageScaleMode
property is set to IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS. The pixels are device independent
pixels specified against 163 dpi.
For example, HzImage widget dimensions are 200 x 100 (height and width respectively ) and your image is
300 x 200 px, then you have to specify referenceHeight as 200 and referenceWidth as 100. The image is
resized to fit in the widget by reducing the height and width.
Syntax
JavaScript: referenceHeight
Lua: referenceheight
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for an Image with referenceHeight:100
var layoutConfImage = {containerWeight:50, referenceHeight:100};
//Reading the referenceHeight of the Image
alert("Image referenceHeight is ::"+image1.referenceHeight);
Accessible from IDE

Yes
It is the reference image width in pixels. The source image width is resized to fill the widget dimensions. The
image aspect ratio is not preserved. The referenceWidth is respected only when the imageScaleMode
Syntax
JavaScript: referenceWidth
Lua: referencewidth
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for an Image with referenceWidth:100
var layoutConfImage = {containerWeight:50, referenceWidth:100};
//Reading the referenceWidth of the Image
alert("Image referenceWidth is ::"+image1.referenceWidth);
Accessible from IDE

Yes
Available on all platform
The widget alignment can be controlled by the below options:
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for an Image with widgetAlignment:WIDGET_ALIGN_MIDDL
E_LEFT
var layoutConfImage = {containerWeight:50,
widgetAlignment:constants.WIDGET_ALIGN_MIDDLE_LEFT};
Accessible from IDE

Yes
16.3 Image - Platform Specific Properties

The platform specific properties for Image widget are as follows:
l
glossyEffect
hoverSkin
renderAsAnchor
skin
toolTip
16.3.1 glossyEffect
Specifies the glossy effect on the image.
Default: IMAGE_GLOSSY_EFFECT_DEFAULT
You can choose one of following glossy effects:
l
IMAGE_GLOSSY_EFFECT_DEFAULT
IMAGE_GLOSSY_EFFECT_LINEAR
IMAGE_GLOSSY_EFFECT_RADIAL
Syntax
JavaScript: glossyEffect
Lua: glossyeffect
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for an Image with glossyEffect:MAGE_GLOSSY_EFFEC
T_RADIAL.
var PSPConfImage = {glossyEffect:constants.IMAGE_GLOSSY_EFFECT_RADIAL};
var image1= new kony.ui.Image2(basicConfImage, layoutConfImage,
PSPConfImage);
Accessible from IDE

Yes
l
iPhone
iPad
16.3.2 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for an Image with hoverSkin:"hskin".
var PSPConfImage = {hoverSkin:"hskin"};
var image1= new kony.ui.Image2(basicConfImage, layoutConfImage, PSPConfIma
ge);
Accessible from IDE

Yes
Most of the Mobile Web browsers do not offer a very good user experience when the entire segment is made
clickable. 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.
This property is typically set to true when the segment onClick is bound to an image.
Note: This property is available only when the Image Widget is placed in a Segment.
Default: false
If set to true, the Image is the first clickable element in the Segment.
If set to false, the Image is not the first clickable element in the Segment.
Syntax
JavaScript: renderAsAnchor
Lua: renderasanchor
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for an Image with renderAsAnchor:true(This property
is available only when the Image Widget is placed in a Segment).
var PSPConfImage = {renderAsAnchor:true};
var image1 = new kony.ui.Image2(basicConfImage, layoutConfImage, PSPConfIm
age);
Accessible from IDE

Yes
l
16.3.4 skin
Specifies the look and feel of the Image.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining properties for an Image with skin:true.
var PSPConfImage = {skin:true};
var image1= new kony.ui.Image2(basicConfImage, layoutConfImage, PSPConfIma
ge);
Accessible from IDE

Yes
l
iPhone
iPad
BlackBerry
Windows Tablet
16.3.5 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for an Image with toolTip:sample text
var basicConfImage={id:"image1", isVisible:true, skin:"confimageSkin", foc
usSkin:"confimageFSkin", text:"Click Here"};
var LayoutConfImage={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,
5], hExpand:true, vExpand:false, displayText:true};
var PSPConfImage={toolTip:"sample text"};
var image1 = new kony.ui.Image(basicConfImage,LayoutConfImage,PSPConfImag
e);
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
16.4 Image - Events

Image has the following events associated with it:
l
onDownloadComplete
16.4.1 onDownloadComplete
This event is triggered when the image download from the URL is complete.
Note: This event is triggered only when the image download from the URL is complete in a Form which is
visible.
This event is not a background job which starts after setting the URL property and is called after the download
is complete.
Signature
JavaScript: onDownloadComplete (widgetref, url, issuccess)
Lua: ondownloadcomplete (widgetref, url, issuccess)
Input Parameters
widgetref [widgetid] - Mandatory
Reference to the image widget that raised the event.
url [String] - Mandatory
Specifies the requested URL.
issuccess [Boolean] - Mandatory
Indicates download completion as successful.
The onDownloadComplete event callback accepts additional parameters when an Image is placed in a
segment row or section template.
Signature
JavaScript: onDownloadComplete (widgetref, url, issuccess, context)
Input Parameters
Index of the row that contains the Image. It is not available if the Image is placed in a section
header.
Index of the section row that contains the Image.

Handle to the parent widget instance(segment) that contains the Image.
Read / Write
JavaScript Example
//The below function is the callback function for onDownloadComplete event
function ondownldComCallBack(this,imagesrc, issuccess)
{
alert("call back event triggered");
}
//Creating the Image with the onDownloadComplete:ondownldComCallBack,onDow
nloadComplete ,this call back event should get triggered.
var basicConfImage = {id : "image", isVisible:true, src:"http://www.fordes
enFailed:"rn_icon1.png",imageWhileDownloading:"konynew.png",onDownloadComp
lete:ondownldComCallBack};
var image = new kony.ui.Image2(basicConfImage, layoutConfImage, {});
16.5 Image - Deprecated Properties

The deprecated properties for Image widget are as follows:
l
hExpand
scaleMode
vExpand
16.5.1 hExpand
Specifies the widget expansion in the horizontal direction.
Note: This is always true in all thin client platforms and this property is never respected.
Note: This property is not supported on Browser, Image, Map, Chart, and PickerView widgets.
Default: False
Type
Boolean
Read / Write
Yes
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Symbian and SPA.
16.5.2 scaleMode
Specifies the scale mode of the downloaded image. You can choose one of the following Scale Modes:
default
Specifies that the downloaded image must occupy the allocated width. This is the default option.
maintainaspectratio
Specifies that the downloaded image must maintain the aspect ratio (the proportional relationship of the
screen's physical width to its height).
retaininitialimagedimensions
Specifies that the downloaded image must retain the initial image dimensions.
Type
Number
Read / Write
No
Accessible from IDE

Yes
SPA, Thin Client
16.5.3 vExpand
Specifies the widget expansion in the vertical direction. The default value is false.
Note: All thin client platforms do not respected property as it is not possible to vertically expand the widgets.
Note: This property is not supported on Browser, Image, Map, Chart, and PickerView widgets.
Default: false (the checkbox is not selected and the widget occupies the preferred height)
If you set the value to true (select the checkbox), the widget occupies the entire available height.
Type
Boolean
Read / Write
Yes
Accessible from IDE

Yes
17. Label
Label widget is used to display non-editable text on the Form and is non-interactive.
When do I use a Label Widget?
You can use a Label widget in the following scenarios:
l
To identify or name a neighboring widget.
To provide instructions to the user on the usage of a feature or a widget. For example, if you want to
inform a user to select one of the options from a CheckBoxGroup, you can place a Label before the
CheckBoxGroup widget with the text "Choose one of the following".
The following are the basic properties, layout properties and platform specific properties.
Basic Properties
Layout Properties
id
info
isVisible
skin
text
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
hoverSkin
pasteboardType
renderAsAnchor
textCopyable
toolTip
wrapping
Creating a Label using a constructor: kony.ui.Label

var lbl1 = new kony.ui.Label(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Defining the properties for a label with id:"label"
var lblBasic = {id:"label", skin:"lblSkn", text:"Hello world", isVisible:t
rue};
var lblLayout ={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5],
hExpand:true, vExpand:false};
var lblLayout ={renderAsAnchor:true, wrapping:constants.WIDGET_TEXT_WORD_W
RAP};
//Creating the label.
var lbl = new kony.ui.Label(lblBasic, lblLayout, lblLayout);
//Reading the id of the label.

alert("Label id::"+lbl.id);

The following is the appearance of a Label widget with the text "This is a Label Widget" on various platforms:
Platform
Appearance
Android
BlackBerry
iPhone
Windows Phone
Adding a Label Widget from IDE

The steps involved in adding a Label widget are as follows:
1. From the IDE, drag and drop the Label widget onto a Form (occupies the complete available width).
2. Use the text property to specify the text for the Label.
You can customize the appearance of the Label widget by using the following properties:
contentAlignment: Specifies the alignment of the content within widget boundaries.
Label has the following considerations:
l
If the text in the Label is occupying more space than the allocated height of the Label widget, the Label
is stretched vertically to accommodate the full text (infinite wrapping) and does not stretch in the
horizontal direction.
If you place a Label in the Form and do not enter a text, when rendered, the height and width occupied
by the Label depends on the following:
l
If the Expand property is false, the Label occupies zero height and width.
If the Expand property is true, the Label occupies the width and height as determined by the
Expand property.
17.1 Label - Basic Properties

The basic properties for Label Widget are as follows:
l
id
info
isVisible
skin
text
toolTip
17.1.1 id
id is the unique identifier of a Label consisting of alpha numeric characters. Every Label should have a unique
id within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a label with id:"label1"
var lblBasic = {id:"label1", skin:"labelSkin", text:"Hello world", isVisib
le:true};
var lblPSP ={};
var label1 = new kony.ui.Label(lblBasic, lblLayout, lblPSP);
//Reading the id of the label
alert("Label id::"+label1.id);
Accessible from IDE

Yes
17.1.2 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a label with info property.
le:true};
var lblPSP ={};
label1.info = {key:"LABEL"};
//Reading the info of the label.
alert("Label info is ::"+label1.info);
Accessible from IDE

No
17.1.3 isVisible
This property controls the visibility of a widget on the Form.
Default: true
If set to false, the label is not displayed on the Form.
If set to true, the label is displayed on the Form.
Segment, the visibility of the widget is controlled by the data property of the segment.
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a label with isVisible:true
le:true};
var lblPSP ={};
var label1= new kony.ui.Label(lblBasic, lblLayout, lblPSP);
//Reading the isVisible of the label
alert("Label isVisible::"+label1.isVisible);
Note: In addition, the visibility of the widget can be controlled by using setVisibility method.
Accessible from IDE

Yes
17.1.4 skin
Specifies the look and feel of the Label widget when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a label with skin:"labelSkin"
le:true};
var lblLayout ={containerWeight:100, padding:[5,5,5,5],margin:[5,5,5,5], h
Expand:true, vExpand:false};
var lblPSP ={};
//Reading the skin of the label
alert("Label skin::"+label1.skin);
Accessible from IDE

Yes
17.1.5 text
Specifies a general or descriptive text for a Label widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a label with text:"Hello world"
le:true};
var lblPSP ={};
//Reading the text of the label.
alert("Label text::"+label1.text);
Accessible from IDE

Yes
17.1.6 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a label with toolTip:sample text
le:true, toolTip:"sample text"};

var lblPSP ={};
Accessible from IDE

Yes
17.2 Label - Layout Properties

The layout properties for Label Widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a label with containerWeight:50.
var lblBasic = {id:"label1", skin:"lblSkn", text:"Hello world", isVisible:
true};
var lblLayout ={containerWeight:50, padding:[5,5,5,5], margin:[5,5,5,5], h
var lblPSP ={};
//Reading the containerWeight of the label
alert("Label containerWeight::"+lbl.containerWeight);
Accessible from IDE

No
Specifies the alignment of the text on the Label with respect to its boundaries. A default value CONTENT_
ALIGN_MIDDLE_LEFT is assigned for all platforms. To choose another alignment, click the drop-down arrow
and select the desired alignment. However, to change the default value on a particular platform, select the
button next to the drop-down and select respective platform and choose the value.
Default: CONTENT_ALIGN_MIDDLE_LEFT
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the label.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the label.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the label.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the label.
CONTENT_ALIGN_CENTER- Specifies the text should be horizontally and vertically centered on the
label.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the label.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the label.
CONTENT_ALIGN_BOTTOM_CENTER- Specifies the text should align at bottom center of the label.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the label.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a label with contentAlignment:constants.CONT
ENT _ALIGN_BOTTOM_LEFT.
true};
var lblLayout ={contentAlignment:constants.CONTENT_ALIGN_BOTTOM_LEFT, cont
ainerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5], hExpand:true, vExpan
d:false};
var lblPSP ={};
Accessible from IDE

Yes
17.2.3 hExpand
Default: true
If set to true, the widget ensures that the entire width available to it is occupied.
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a label with hExpand:true.
true};
var lblPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Desktop Web, and SPA
17.2.4 margin
between the widget and the next widget or the container.
To define the margin values for a platform, click the Ellipsis ( ) button against the property to open the
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a label with margin:[5,5,5,5].
true};
var lblPSP ={};
Accessible from IDE

Yes
Enables you to define the space around a widget in pixels or in percentage. You can use this option to define
the top, left, right, and bottom distance between the widget and the next element.
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a label with margin in pixels.
true};
hExpand:true, vExpand:false, marginInPixel: true};
var lblPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
17.2.6 padding
To define the padding values for a platform, click the Ellipsis ( ) button against the property to open the
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a label with padding:[5,5,5,5].
true};
var lblPSP ={};
Accessible from IDE

Yes
Enables you to define the space between the content of the widget and the widget boundaries in pixels or in
percentage. You can use this option to define the top, left, right, and bottom distance between the widget
content and the widget boundary.
Default: false
Note: For backward compatibility on older projects, this property will be made true for iPhone, iPad, Android
and Windows Phone it will be false.
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a label with padding in pixels.
true};
hExpand:true, vExpand:false, paddingInPixel: true};
var lblPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
17.2.8 vExpand
Default: false
If set to true, the widget ensures that the entire height available to it is occupied.
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a label with vExpand:false.
true};
var lblLayout ={containerWeight:100,padding:[5,5,5,5], margin:[5,5,5,5], h
var lblPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and Desktop Web platforms
The widget alignment can be controlled by the below options.
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a label with widgetAlignment:constants.WIDGET_AL
IGN_TOP_LEFT
true};
var lblLayout ={widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, container
Weight:100, padding:[5,5,5,5], margin:[5,5,5,5], hExpand:true, vExpand:fal
se};
var lblPSP ={};
Accessible from IDE

Yes
17.3 Label - Platform Specific Properties

The platform specific properties for Label Widget are as follows:
l
hoverSkin
pasteboardType
renderAsAnchor
textCopyable
toolTip
wrapping
17.3.1 hoverSKin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a label with hoverSkin:"hskin".
true};
var lblPSP ={hoverSkin:"hskin"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
This property enables an application to share data within the application or with another application using
system-wide or application-specific pasteboards.
Typically, an object in the application writes data to a pasteboard when the user requests a copy or cut
operation on a selection in the user interface. Another object in the same or different application then reads
that data from the pasteboard and presents it to the user at a new location; this usually happens when the user
requests a paste operation.
The different pasteboard types are as follows:
l
constants.PASTE_BOARD_TYPE_DEFAULT: If you select this option, the value selected in the

application properties gets applied.
constants.PASTE_BOARD_TYPE_SYSTEM_LEVEL: This is the default selection and if this option is

unchanged, the text copied from a Label can be pasted across different applications on the device.
Even if you exit the source application, the copied text persists in the memory and can be pasted
across applications or within the same application.
constants.PASTE_BOARD_TYPE_APP_LEVEL_PERSISTENT: If you select this option , the text

copied from a Label can be pasted in TextArea or TextBox (with the pasteboard type set as applevel)
within the same application. Even if you close the application, the copied text persists in the memory
and can be copied to another TextArea whose pasteboard type is applevel, when you restart that
application.
constants.PASTE_BOARD_TYPE_APP_LEVEL_NON_PERSISTENT: If you select this option, the

text copied from a Label can be pasted in TextArea or TextBox within the same application. This text is
not retained in the memory when you close the application.
Syntax
JavaScript: pasteboardType
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining properties for a label with pasteboardType:constants.PASTE_BOAR
D_TYPE_SYSTEM_LEVEL.
true};
var lblPSP ={pasteboardType:constants.PASTE_BOARD_TYPE_SYSTEM_LEVEL};
Accessible from IDE

Yes
l
iPhone
iPad
Most of the Mobile Web browsers do not offer a very good user experience when the entire segment is made
clickable. To offer an acceptable user experience, one of the labels in a segment is made clickable and the
onClick event for the segment is bound to a label.
This property is typically set to true when the segment onClick is bound to a label.
Note: This property is available only when the Label Widget is placed in a Segment.
Default: false
If set to true, the Label is made a clickable element in the Segment.
If set to false, the Label is not a clickable element in the Segment.
Syntax
JavaScript: renderAsAnchor
Lua: renderasanchor
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a label with renderAsAnchor:true.
true};
var lblPSP ={renderAsAnchor:true};
Accessible from IDE

Yes
l
17.3.4 textCopyable
This property enables you to copy a text from a Label widget when the widget is enabled state.
Note: This property is not applicable if the widget is in disabled state.
Note: In iOS platform, partial text cannot be copied.
Default: false
If set to true, the text of Label can be copied to other widgets.
If set to false, the text of the Label cannot be copied to other widgets.
Syntax
JavaScript: textCopyable
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining properties for a label with textCopyable:true.
true};
var lblPSP ={textCopyable:true};
Accessible from IDE

Yes
l
iOS
Android
SPA
17.3.5 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Label with toolTip:sample text
var lblBasic={id:"label1", isVisible:true, skin:"lblSkin", focusSkin:"lblF
Skin", text:"Click Here" };
var lblLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5],

var lblPSP={toolTip:"sample text"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
17.3.6 wrapping
When the content of the label reaches the boundaries, it starts wrapping. While wrapping, two strategies can
be applied:
l
Word Wrapping: Wrap or clip the string only at word boundaries.
Character Wrapping: Wrap or clip the string at the closest character boundary.
Default: WIDGET_TEXT_WORD_WRAP
l
WIDGET_TEXT_WORD_WRAP: Specifies if the complete word must be moved to the next line when
you reach the right margin. This is the default wrapping property.
WIDGET_TEXT_CHAR_WRAP: Specifies if the characters in a word must be moved to the next line
when you reach the right margin.
The following image illustrates the character wrapping property:
Syntax
JavaScript: wrapping
Lua: wrapping
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for a label with wrapping:constants.WIDGET_TEXT_WORD_
WRAP.
true};
var lblPSP ={wrapping:constants.WIDGET_TEXT_WORD_WRAP};
Accessible from IDE

Yes
l
iPhone
iPad
18. Line
The Line widget allows you to draw a horizontal or a vertical line on a Form. It is used as a separator between
widgets for a better visual experience.
Line widget provides you with an option to set Basic Properties and Layout Properties.
Basic Properties
Layout Properties
Platform Specific
Properties
id
margin
toolTip
info
marginInPixel
isVisible
thickness
skin
Creating a Line using a constructor: kony.ui.Line

var myline = new kony.ui.Line(basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//Defining the properties for a Line with id:"line".
var lineBasicConf = {id:"line1",skin:"gradlblskin",isVisible:true};
var lineLayoutConf = {margin:[0,0,0,0],padding:[3,3,3,3],thickness:25};
var linePSPConf = {};
//Creating the Line.
var line1 = new kony.ui.Line(lineBasicConf,lineLayoutConf,linePSPConf);
//Reading the id property of Line widget.
alert("Line id ::"+line1.id);
When do I use a Line Widget?

You can use a Line widget to indicate a separator between two widgets which are placed side-by-side or
placed one below the other.
Behavior of a Line widget
l
Orientation of a line can be horizontal or vertical. The orientation of the line depends on the widget it is
placed in. If a Line widget is placed in an HBox, it becomes a VLine and if it placed in a VBox or a Form,
it becomes an HLine.
Note: Mobile Web platform does not support the VLine.

l
A VLine in an HBox always takes the height of the box.
An HLine in an HBox takes the width as specified in the containerWeight.
An HLine in an VBox takes the width of the VBox.

The following is the appearance of the Line widget on various platforms:
Platform
Appearance
Android
BlackBerry
iPhone
Platform
Appearance
Windows Phone
Adding a Line Widget using IDE

The steps involved in adding a Line widget are as follows:
1. From the IDE, drag and drop the Line widget in between two widgets which are aligned side-by-side in
an HBox or one below the other in a VBox or a Form.
2. Specify the thickness of the line in pixels.
You can customize the appearance of the Line widget by using the following properties:
l
thickness: Defines the thickness of the line in pixels.
18.1 Line - Basic Properties

The basic properties for Line Widget are as follows:
l
id
info
isVisible
skin
18.1.1 id
id is a unique identifier of Line consisting of alpha numeric characters. Every Line should have a unique id
within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Line with id:"line".
var lineBasicConf = {id:"line1", skin:"gradlblskin", isVisible:true};
var lineLayoutConf = {margin:[0,0,0,0], padding:[3,3,3,3], thickness:25};
//Reading the id property of Line widget.
alert("Line id ::"+line1.id);
18.1.2 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a Line with info property.
var lineBasicConf = {id:"line1", skin:"gradlblskin", isVisible:true};
line1.info = {key:"Line"};
//Reading the info property of Line widget.
alert("Line info is ::"+line1.info);
Accessible from IDE

No
18.1.3 isVisible
This property controls the visibility of the line widget on the form.
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Creating the Line with isVisible:true.
var lineBasicConf = {id:"line", skin:"gradlblskin", isVisible:true};
var line = new kony.ui.Line(lineBasicConf,lineLayoutConf,linePSPConf);
//Reading the isVisible property of Line widget.
alert("Line isVisible ::"+line.id);
Accessible from IDE

Yes
18.1.4 skin
Specifies the look and feel of the Line when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Creating the Line with skin:"gradlblskin"

//Reading the skin property of Line widget
alert("Line skin ::"+.line.skin);
Accessible from IDE

Yes
18.2 Line - Layout Properties

The layout properties for Line Widget are as follows:
l
margin
marginInPixel
thickness
18.2.1 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Line with margin:[0,0,0,0].
var lineBasicConf = {id:"line",skin:"gradlblskin",isVisible:true};
var lineLayoutConf = {margin:[0,0,0,0], thickness:25};
//Reading the margin property of Line widget.
alert("Line margin ::"+line.margin);
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Line with margin in pixels.
var lineLayoutConf = {margin:[5,5,5,5], marginInPixel:true, thickness:25};
//Reading the margin property of Line widget.
alert("Line margin ::"+line.margin);
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
18.2.3 thickness
Specifies the thickness of the widget in pixels. The pixel values are scaled to density specific pixels by the
respective platforms.
Syntax
JavaScript: thickness
Lua: thickness
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Creating the Line with thickness:3
var lineBasicConf = {id:"line",skin:"gradlblskin",isVisible:true};
var lineLayoutConf = {margin:[0,0,0,0], thickness:3};
//Reading the thickness property of Line widget.
alert("Line thickness ::"+line.thickness);
Accessible from IDE

Yes
18.3 Line - Platform Specific Properties

The Platform Specific Property of Line Widget is as follows:
l
toolTip
18.3.1 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties of Line with toolTip:sample text
var lineBasicConf={id:"line1", isVisible:true, skin:"lineSkin", focusSkin:
"lineFSkin", text:"Click Here" };
var lineLayoutConf={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5],
var linePSPConf={toolTip:"sample text"};
//Creating a Line.
Accessible from IDE

Yes
18.3.2 Line - Platform Specific Properties

The Platform Specific Property of Line Widget is as follows:
l
toolTip
toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties of Line with toolTip:sample text
var lineBasicConf={id:"line1", isVisible:true, skin:"lineSkin", focusSkin:
"lineFSkin", text:"Click Here" };
var lineLayoutConf={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5],
var linePSPConf={toolTip:"sample text"};
//Creating a Line.
Accessible from IDE

Yes
19. Link
Link widget allows you to define a hyperlink that you can interact with (select and click) and navigate to an
external location or a location within the application.
Link provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties, and
Events.
Basic Properties
Layout Properties
Platform Specific
Properties
focusSkin
id
info
isVisible
skin
text
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
blockedUISkin
contextMenu
externalURL
glowEffect
hoverSkin
submitURL
toolTip
Events
Deprecated
onClick
preOnclickJS
postOnclickJS
focusImage
image
normalImage
You can use a Link widget in the following scenario:

l
To reduce the visual complexity of a design.

The link widget by default does not have any border surrounding it (unless specified in the skin) and
looks like plain text unlike a button widget which has a frame and a border.
The following image illustrates a Label widget with a Link and Button widgets:
In the above image, you can notice that link widget looks like plain text unlike the button widget.
The following images illustrate a Button widget between two TextArea widgets and a Link widget
between two TextArea widgets:
With Button
With Link
Creating a Link using a constructor: kony.ui.Link

var myLink = new kony.ui.Link(basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//Defining properties for a link widget.
var linkBasic ={id:"link1",skin:"linkSkin", focusSkin:"linkFSkin", text:"C
lick here", isVisible:true};
var linkLayout={containerWeight:100, padding[5,5,5,5], margin:[5,5,5,5], p
addingInPixel:true, marginInPixel:true, hExpand:true, vExpand:true};
var linkPSP = {blockedUISkin:"blkSkin"};
//Creating the link.
var link1 = new kony.ui.Link(linkBasic, linkLayout, linkPSP);
//Reading blockedUISkin of Link.
alert("Link blockedUISkin::"+link1.blockedUISkin);

The following is the appearance of a Link widget on various platforms:
Platform
Appearance
Android
Platform
Appearance
BlackBerry
iPhone
Windows Phone
Adding a Link Widget from IDE
The steps involved in adding a Link widget are as follows:
1. From the IDE, drag and drop the Link widget onto a Form (occupies the complete available width). Or,
a. If you want to resize the Link widget in the horizontal direction, place an HBox on the Form and
drag and drop the Link inside the HBox and resize accordingly.
b. If you want to resize the Link widget in the vertical direction, place an HBox on the Form and
place a VBox inside the HBox; and drag and drop the Link inside the VBox and resize
accordingly.
2. Use the text property to specify the text that must be displayed as a link when rendered.
3. Specify the action that must take place when the link is clicked (navigation to another Form or website
etc.) using the onclick event.
You can customize the appearance of the Link widget by using the following properties:
l
Sample use case to navigate to an external URL

Here is a sample use case that explains you to go to a url on click of the link:
1. From the Kony Studio, drag and drop the Link widget onto a Form as frm1.
2. Create another Form as frm2 and drag and drop a Browser widget on it.
3. Double-click the Link widget in the form frm1 and locate onClick property from the properties window.
4. Click the ellipse button to define an event. The Event Editor window appears.
5. Right-click on Action Sequence and select Navigate to Form/Popup. The Form/Popup option
appears.
6. From the left window, select the form frm2 from the dropdown and click OK.
7. Navigate to the Form frm2, double-click browser widget and locate masterData property from the
properties window.
8. Click the ellipse button to define the URL. The Browser Data window appears.
9. Select the option URL and enter the URL as www.google.com.
10. Click OK.
11. Build the application for a rich client to see the results.
Link widget has the following considerations:
l
If you do not specify a skin, the default skin is applied to the link (link appears in blue font and is
underlined).
If you do not specify a focusSkin, the default focus skin is applied to the link (link appears in black font
and is underlined).
If you specify a skin or focusSkin without an underline, when rendered, the link will appear without an
underline on the platform.
For Server side Mobile Web (basic), font styles are not supported.
19.1 Link - Basic Properties

The basic properties for Link Widget are as follows:
l
focusSkin
id
info
isVisible
skin
text
toolTip
19.1.1 focusSkin
Specifies the look and feel of the Link when in focus.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a link widget with focusSkin:"linkFSkin"
var linkLayout={widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, contentAl
ignment:CONTENT_ALIGN_TOP_LEFT, containerWeight:100};
var linkPSP = {};
//Reading focusSkin of Link
alert("Link focusSkin::"+link1.focusSkin);
Accessible from IDE

Yes
19.1.2 id
id is a unique identifier of Link consisting of alpha numeric characters. Every Link should have a unique id
within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a link widget with id:"link1".
var linkPSP = {};
//Reading Id of Link.
alert("Link id::"+link1.id);
Accessible from IDE

Yes
19.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a link widget with info property.
var linkBasic ={id:"link1", skin:"linkSkin", focusSkin:"linkFSkin", text:"
Click here", isVisible:true};
var linkPSP = {};
link1.info = {key:"link text"};
//Reading info of Link.
alert("Link info is ::"+link1.info);
Accessible from IDE

No
19.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining properties for a link widget with isVisible:true.
var linkPSP = {};
//Reading isVisible of Link.
alert("Link id::"+link.isVisible);
Accessible from IDE

Yes
19.1.5 skin
Specifies the look and feel of the Link when not in focus.
Note: On Windows Tablet platform, because of native behavior a skin with font style as underline is not
supported.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a link widget with skin:"linkSkin".
var linkPSP = {};
//Reading skin of Link.
alert("Link skin::"+link1.skin);
Accessible from IDE

Yes
19.1.6 text
Specifies a general or descriptive text for the Link widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a link widget with text:"Click here".
var linkPSP = {};
//Reading text of Link.
alert("Link text::"+link.text);
Accessible from IDE

Yes
19.1.7 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a link widget with toolTip:sample text
lick here", toolTip:"sample text", isVisible:true};
var linkLayout={widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT,
contentAlignment:CONTENT_ALIGN_TOP_LEFT, containerWeight:100};
var linkPSP = {};
Accessible from IDE

Yes
Available on all platforms except BlackBerry
19.2 Link - Layout Properties

The layout properties for Link Widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a link widget with containerWeight:100.
var linkLayout={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5],
paddingInPixel:true, marginInPixel:true, hExpand:true};
var linkPSP = {};
//Creating link widget.
//Reading containerWeight of Link
alert("Link containerWeight::"+link1.containerWeight);
Accessible from IDE

No
Specifies the alignment of the text on the Link with respect to its boundaries. A default value CONTENT_
center of the button)
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the button.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the button.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the button.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the button.
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the button.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the button.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the button.

button.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the button.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a link widget with contentAlignment:CONTENT_ALIG
N_TOP_LEFT
var linkLayout={contentAlignment:constants.CONTENT_ALIGN_TOP_LEFT, contain
erWeight:100, padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:true, ma
rginInPixel:true, hExpand:true};
var linkPSP = {};
Accessible from IDE

Yes
19.2.3 hExpand
Note: Server side Mobile Web platform does not support the Expand property. This is because a widget in a
Server side Mobile Web cannot expand or contract based on the neighboring widget (default behavior of a
widget in a Server side Mobile Web).
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a link widget with hExpand:true.
var linkPSP = {};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Desktop Web, and SPA
19.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a link widget with margin:[5,5,5,5].
var linkPSP = {};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a link widget with marginInPixel:true.
var linkBasic ={id:"link",skin:"linkSkin", focusSkin:"linkFSkin", text:"Cl
ick here", isVisible:true};
var linkPSP = {};
var link = new kony.ui.Link(linkBasic, linkLayout, linkPSP);
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
19.2.6 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a link widget with padding:[5,5,5,5].
var linkBasic ={id:"link", skin:"linkSkin", focusSkin:"linkFSkin", text:"C
var linkPSP = {};
Accessible from IDE

Yes
Available on all platforms except Mobile Web (basic).
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a link widget with paddingInPixel:true.
var linkBasic ={id:"link", skin:"linkSkin", focusSkin:"linkFSkin", text:"C
var linkPSP = {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a link widget with widgetAlignment:constants.WID
GET_ALIGN_TOP_LEFT.
var linkBasic ={id:"link", skin:"linkSkin",focusSkin:"linkFSkin", text:"Cl
ick here",isVisible:true};
ignment:constants.CONTENT_ALIGN_TOP_LEFT, containerWeight:100, padding:[5,
5,5,5], margin:[5,5,5,5], hExpand:true};
var linkPSP = {};
Accessible from IDE

Yes
19.3 Link - Platform Specific Properties

The platform specific properties for Link Widget are as follows:
l
blockedUISkin
contextMenu
externalURL
glowEffect
hoverSKin
submitURL
toolTip
call) is completed.
Default: null (No skin is applied)
Note: For Server side Mobile Web, if you want to use this property, then set it in the IDE against
blockedUISkin property. Only then Server side Mobile Web shows blocked UI when the action is performed.
This is also applicable for Server side Mobile Web iPhone, Android, and Blackberry (Touch) devices.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read and Write except Server side Mobile Web)
JavaScript Example
//Defining properties for a link widget with blockedUISkin:"blkSkin"
var linkBasic ={id:"link1",skin:"linkSkin", focusSkin:"linkFSkin",
text:"Click here", isVisible:true};

var linkPSP = {blockedUISkin:"blkSkin"};
//Reading blockedUISkin of Link.
alert("Link blockedUISkin::"+link1.blockedUISkin);
Accessible from IDE

Yes
l
19.3.2 contextMenu
A context menu is a menu that appears upon clicking a widget. A context menu typically offers a limited set of
choices that are applicable for that widget. Usually these choices are actions, related to the widget.
If you define a context menu for a widget, the steps involved to invoke the context menu on a platform and the
In Desktop Web, on right-click mouse the context specific menu will be displayed with the array of menu
items.
l
BlackBerry 6.x
BlackBerry Touch
Device (<6.x)
BlackBerry Non-Touch Device

(<6.x)

l
Syntax
Lua: contextmenu
Type
JavaScript: Array(kony.ui.MenuItem)
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a link widget with contextMenu:[menu1,menu2], Wh
ere menu1 and menu2 are menu items that are created and made accessible.
var linkPSP = {contextMenu:[menu1,menu2]};
Accessible from IDE

No
l
BlackBerry
19.3.3 externalURL
Specifies that the URL must be opened directly from the web site without having to contact the Kony Server.
For example, in a Banking Application, for Terms and Conditions section, you can provide an external URL
which will open the required section in a new window rather than opening the section in the same window.
Syntax
JavaScript: externalURL
Lua: externalurl
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for a link widget with externalURL:"http://www.googl
e.co.in"
var linkPSP = {externalURL:"http://www.google.co.in"};
Accessible from IDE

Yes
19.3.4 glowEffect
Specifies if there must be glow effect when you touch the link.
Default: false
If set to false, the link will not have glow effect.
If set to true, the link will have glow effect.
Note: The glow appears on the button only for a moment on touch and disappears.
The following image illustrates a link with and without the glow effect:
Syntax
JavaScript: glowEffect
Lua: gloweffect
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a link widget with glowEffect:true
var linkPSP = {glowEffect:true};
Accessible from IDE

Yes
l
iPad
iPhone
19.3.5 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
JavaScript Example
//Defining properties for a link widget with hoverSkin:"hskin"
var linkBasic ={id:"link1",skin:"linkSkin",focusSkin:"linkFSkin",text:"Cli
ck here",isVisible:true};

var linkPSP = {hoverSkin:"hskin"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
Specifies if the progress indicator must be displayed when the link is clicked. This is typically set to true, if it
is known at design time that the link onClick event handling is going to trigger a long running call.
Default: true
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a link widget with showProgressIndicator:true
var linkBasic ={id:"link1",skin:"linkSkin",focusSkin:"linkFSkin",text:"Cli
ck here",isVisible:true};

var linkPSP = {showProgressIndicator:true};
Accessible from IDE

Yes
l
iPad
iPhone
19.3.7 submitURL
Specifies the URL to which the current Form data should be submitted, without contacting Kony Server. This
is typically required when the data collection is done using Kony Studio Form but is actually posted to a thirdparty site.
For example, for an application that requires the user to provide confidential data, you can route the data
directly to the server of the website without contacting the Kony Server using the externalURL property. Doing
so, opens the resultant site in the same window rather than opening it in a new window.
Default: false
If set to false, then the URL is submitted contacting the Kony Server.
If set to true, then the URL is submitted without contacting the Kony Server.
Syntax
JavaScript: submitURL
Lua: submiturl
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a link widget with submitURL:"http://www.google.
co.in"
var linkPSP = {submitURL:"http://www.google.co.in"};
//Creating link widget
Accessible from IDE

Yes
19.3.8 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties of a Linkwidget with toolTip:sample text
var linkBasic={id:"link1", isVisible:true, skin:"linkSkin", focusSkin:"lin
kFSkin", text:"Click Here" };
var linkLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hE
var linkPSP={toolTip:"sample text"};
//Creating the Link.

Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
19.4 Link - Events

Link has the following event associated with it:
l
onClick
preOnclickJS
postOnclickJS
19.4.1 onClick
An event callback that is invoked by the platform when the user performs a click action on the link.
Signature
JavaScript: onClick
Lua: onclick
The onClick event callback accepts additional parameters when a Link widget is placed in a segment row or
section template.
Signature
Input Parameters
Index of the row that contains the Link widget. It is not available if the Link widget is placed in a
section header.
Index of the section row that contains the Link widget.
Handle to the parent widget instance(segment) that contains the Link widget.
Read / Write
JavaScript Example
//The below function is the callback function for onClick event of Link.
function onClickCallBack(link)
{
}
//Defining properties for a link widget with onClick:onClickCallBack.
Click here", isVisible:true, onClick:onClickCallBack};
var linkPSP = {};
19.4.2 preOnclickJS
This event allows the developer to execute custom javascript function before the onClick callback of the Link
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for preOnclickJS event of Li
nk .
function preclickJSCallBack(link)
{
}
//Defining properties for a link widget with preOnclickJS:preclickJSCallBa
ck
var linkBasic ={id:"link1", skin:"linkSkin", focusSkin:"linkFSkin",
text:"Click here", isVisible:true};

var linkPSP = {preOnclickJS:preclickJSCallBack};
//Reading preOnclickJS of Link
alert("Link preOnclickJS::"+link1.preOnclickJS);
Accessible from IDE

Yes
This event allows the developer to execute custom javascript function after the onClick callback of the Link is
invoked. This is applicable only for Mobile Web channel.The function must exist in a javascript file under
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for postOnclickJS event of L
ink .
function postclickJSCallBack(link)
{
}
function postOnclickJS()
{
//Defining properties for a link widget with postOnclickJS:postclickJSCall
Back

var linkPSP = {postOnclickJS:postclickJSCallBack};
//Reading postOnclickJS of Link
alert("Link postOnclickJS::"+link1.postOnclickJS);
Accessible from IDE

Yes
19.5 Link - Deprecated Properties

The deprecated properties for Link widget are as follows:
l
focusImage
image
normalImage
19.5.1 focusImage
Specifies the look and feel of the widget when in focus.
Default: False
Type
Boolean
Read / Write
Yes
Accessible from IDE

Yes
Available on all platforms except Mobile Web, Symbian and SPA.
19.5.2 image
Specifies the scale mode of the downloaded image. You can choose one of the following Scale Modes:
default
Specifies that the downloaded image must occupy the allocated width. This is the default option.
maintainaspectratio
Specifies that the downloaded image must maintain the aspect ratio (the proportional relationship of the
screen's physical width to its height).
retaininitialimagedimensions
Specifies that the downloaded image must retain the initial image dimensions.
Type
Number
Read / Write
No
Accessible from IDE

Yes
Available on Mobile Web and SPA.
19.5.3 normalImage
Type
Boolean
Read / Write
Yes
Accessible from IDE

Yes
20. ListBox
List Box displays a list of items as a drop-down box and allows you to select a one or more items from the list.
The data model for ListBox widget is a key value pair. The key is hidden part of the model while value is
displayed to the user.
Note: ListBox does not support multiple selection from Release 3.0 onwards. However, if you have
upgraded from a version prior to Release 3.0 and used multiple selection, the backward compatibility will be
maintained. If you require multiple selection capability, use either a CheckBox or a Segment with multiple
selection enabled.
ListBox provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
and Events.
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKey
selectedKeys
selectedKeyValue
selectedKeyValues
skin
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Events
Deprecated
onSelection
preOnclickJS
postOnclickJS
multiple
placeholderi18nkey
selectedkeys
selectedkeyvalues
Platform Specific
Properties
applySkinsToPopup
blockedUISkin
dropDownImage
groupCells
hoverSkin
nativeListFieldSkin
nativeListFieldFocusSkin
placeholder
placeholderSkin
popupIcon
popupTitle
tickedImage
toolTip
untickedImage
viewType
viewConfig
Creating a ListBox using a constructor: kony.ui.ListBox

var listbox1 = new kony.ui.ListBox (basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Defining properties for a listbox.
var listBasic ={id:"listbox",isVisible:true, masterData:[["key1", "value
1"],["key2", "value2"],["key3", "value3"]], skin:"listSkin", focusSkin:"li
stFSkin"};
var listLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, padding:[
0,0,0,0], margin:[0,0,0,0], containerWeight:100, hExpand:false};
var listPSP = {applySkinsToPopup: true, nativeListFieldSkin:"nativeListSki
n", viewType: constants.LISTBOX_VIEW_TYPE_SPINNER};
//Creating the ListBox.
var listbx = new kony.ui.ListBox(listBasic, listLayout, listPSP);
//Reading the containerWeight of the listbox
alert("listbox containerWeight ::"+listbx.containerWeight);
The appearance of the widget with the default properties (with and without skin) on various platforms is as
follows:
Platform
Without Skin
With Skin
Android
BlackBerry
iPhone
Mobile Web (BJS)
l
Shows dynamic set of data in a fixed space.
The master data of choices should be limited and fetched in a separate service call.
20.1 ListBox - Basic Properties

The basic properties for ListBox Widget are as follows:
l
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKey
selectedKeys
selectedKeyValue
selectedKeyValues
skin
20.1.1 focusSkin
Specifies the look and feel of the ListBox when in focus.
1. On J2ME, if you do not specify the Focus skin, it will not possible to identify the traversal.
2. Mobile Web does not support this property. For Advanced Mobile Web platforms, a platform specific
progress indicator is displayed. For other Mobile Web platforms (Basic and BJS), the screen is refreshed.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the focusSkin:"listFSkin",Skin
with the same name should be created through IDE or handcode
var listBasic ={id:"listbx",isVisible:true, masterData:[["key1", "value1"],
["key2", "value2"],["key3", "value3"]],skin:"listSkin", focusSkin:"listFSk
in"};
var listPSP = {};
//Creating the Listbox.

//Reading the focusSkin of the listbox
alert("listbox focusSkin ::"+listbx.focusSkin)
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and BlackBerry 10 platforms
20.1.2 id
id is a unique identifier of ListBox consisting of alpha numeric characters. Every ListBox should have a unique
id within a Form.
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Listbox with the id:"listbx"
in"};
var listPSP = {};
//Creating the Listbox
//Reading the id of the listbox
alert("listbox Id ::"+listbx.id);
Accessible from IDE

Yes
20.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Listbox with the info property.
in"};
var listPSP = {};

listbx.info = {key:"listboxitems"};
//Reading the info of the listbox.
alert("listbox info ::"+listbx.info);
Accessible from IDE

No
20.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Listbox with the isVisible:true
in"};
var listPSP = {};
//Reading the isVisible of the listbox
alert("listbox isVisible ::"+listbx.isVisible)
Accessible from IDE

Yes
20.1.5 masterData
ListBox window.
In the Master Data window, you can specify the Key, Display Value, i18N Key, and the Accessibility Config.
The following image illustrates the MasterData for ListBox window:
Data when you Quick Preview. (For more information on Quick Preview, see the Kony Studio User Guide.
Note: If the key or the display value is null/nil, the value will not be listed as one of the available choices.
[
]
Syntax
Lua: masterdata
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Listbox with the masterData:[["key1", "value
1"],["key2", "value2"],["key3", "value3"]]
var listBasic ={id:"listbx",isVisible:true, masterData:[["key1", "value1",
accessibilityConfigObject],["key2", "value2", accessibilityConfigObject],[
"key3", "value3", accessibilityConfigObject]],skin:"listSkin", focusSkin:"
listFSkin"};
var listPSP = {};
//Reading the masterData of the listbox
alert("listbox masterData ::"+listbx.masterData)
Accessible from IDE

Yes
Specifies the set of values from which you can make selections.You must specify a key and a value in a
master data map.
Note: This property is applicable only if the masterData is not set. You must use either the masterData or
the masterDataMap to set data for the CheckBox.
[
[
{"mykey":"item2","myvalue":"Item
Two","accessibilityConfig":acObject},...,
],
"mykey",
"myvalue"
]
Syntax
Lua: masterdatamap
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Listbox with the masterDataMap:[[{"mykey":"k
ey1","myvalue":"value1"}, {"mykey":"key2","myvalue":"value2"}, {"mykey":"k
ey3","myvalue":"value3"}], "mykey","myvalue"]
var listBasic ={id:"listbx", isVisible:true, skin:"listSkin", focusSkin:"l
istFSkin"};
var listPSP = {};
listbx.masterDataMap = [[{"mykey":"key1","myvalue":"value1","accessibility
Config":acObject}, {"mykey":"key2","myvalue":"value2", "accessibilityConfi
g":acObject}, {"mykey":"key3","myvalue":"value3", "accessibilityConfig":ac
Object}], "mykey","myvalue"];
//Reading the masterDataMap of the listbox
alert("listbox masterDataMap ::"+listbx.masterDataMap)
Accessible from IDE

No
20.1.7 selectedKey
Represents the key that is shown as selected.
Syntax
Lua: selectedkey
Type
JavaScript: String
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Listbox with the selectedKey:"key1"
["key2", "value2"],["key3", "value3"]], skin:"listSkin", focusSkin:"listFS
kin", selectedKey:"key1"};
var listPSP = {};
//Reading the selectedKey of the listbox
alert("listbox selectedKey ::"+listbx.selectedKey)
Accessible from IDE

No
20.1.8 selectedKeys
Returns the keys from the data representing the selected keys.
If you set the selectedkeys to null/nil, the selection is cleared.
Syntax
Type
JavaScript: Array
Read / Write
JavaScript Example
//Defining the properties for Listbox with the selectedKeys: "key1", "key2"
["key2", "value2"],["key3", "value3"]], skin:"listSkin", focusSkin:"listFS
kin", selectedKeys:["key1","key2"]};
var listPSP = {};
//Reading the selectedKeys of the listbox
alert("listbox selectedKeys ::"+listbx.selectedKeys)
Accessible from IDE

No
Syntax
Type
JavaScript: Array
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Listbox with the selectedKey:"key1"
var listBasic ={id:"listbx", isVisible:true, masterData:[["key1", "value
1"], ["key2", "value2"], ["key3", "value3"]], skin:"listSkin", focusSkin:"
listFSkin", selectedKey:"key1"};
var listPSP = {};
//Reading the selectedKeyValue(ReadOnly) of the listbox
alert("listbox selectedKeyValue ::"+listbx.selectedKeyValue)
Accessible from IDE

No
Returns the array of selected key-value pair from the data representing the selected key and value.
Syntax
Type
JavaScript: Array
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for ListBox with selectedKeyValues:[["key1","va
lue1"],["key2","value2"]]
listFSkin", selectedKey:"key1"};
var listPSP = {};
var listbx = new kony.ui.ListBox(chkBasic,chkLayout,{});
//Reading the selectedKeyValues of ListBox.
alert("listBox selectedKeyValues are ::"+listbx.selectedKeyValues);
Accessible from IDE

No
20.1.11 skin
Specifies a background skin for ListBox widget.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the skin:"listSkin", Skin with
the same name should be created through IDE or handcode
listFSkin"};
var listPSP = {};
//Reading the skin of the listbox
alert("listbox skin ::"+listbx.skin)
Accessible from IDE

Yes
20.2 ListBox - Layout Properties

The layout properties for ListBox Widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Listbox with the containerWeight:100
stFSkin"};
var listPSP = {};
//Reading the containerWeight of the listbox.
alert("listbox containerWeight ::"+listbx.containerWeight);
Accessible from IDE

No
Specifies the alignment of the text for a ListBox with respect to its boundaries.
Default:CONTENT_ALIGN_CENTER
Note: This property is applicable only when the view is set as wheel type.
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the ListBox.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the ListBox.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the ListBox.
CONTENT_ALIGN_MIDDLE_LEFT - Specifies the text should align at meddle left of the ListBox.
(Android platform supports this option only).
CONTENT_ALIGN_CENTER - Specifies the text should align at center of the ListBox. (Android
platform supports this option only).
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the ListBox.
(Android platform supports this option only).
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the ListBox.

ListBox.
CONTENT_ALIGN_BOTTOM_RIGHT- Specifies the text should align at bottom right of the ListBox.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Listbox with the contentAlignment:constants.
CONTENT_ALIGN_TOP_LEFT
var listBasic ={id:"listbox", isVisible:true, masterData:[["key1", "value
stFSkin"};
0,0,0,0], margin:[10,10,0,10], containerWeight:40, contentAlignment:consta
nts.CONTENT_ALIGN_TOP_LEFT, hExpand:true};
var listPSP = {};
Accessible from IDE

Yes
20.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with the hExpand:true
stFSkin"};
0,0,0,0], margin:[10,10,0,10], containerWeight:40, hExpand:true};
var listPSP = {};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, and SPA
20.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Listbox with the margin:[10,10,0,10].
stFSkin"};
var listPSP = {};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Listbox with margin in pixels.
stFSkin"};
var listLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, marginInP
ixel:true, margin:[10,10,0,10], containerWeight:40, hExpand:false};
var listPSP = {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
20.2.6 padding
Note: Due to Browser restrictions, you cannot apply Padding for a ListBox and Form widgets on Mobile
Web platform. Padding is not supported by Windows Mobile browser for Box and Image Gallery.
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Listbox with the padding:[10,10,10,0]
stFSkin"};
var listPSP = {};
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Listbox with padding in pixels.
stFSkin"};
10,10,10,0], paddingInPixel:true, containerWeight:40, hExpand:false};
var listPSP = {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
20.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Listbox with the vExpand:true
stFSkin"};
0,0,0,0], margin:[10,10,0,10], containerWeight:40, hExpand:true, vExpand:t
rue};
var listPSP = {};
Accessible from IDE

Yes
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
/Defining properties for a Listbox with the widget alignment as center.
1"],["key2", "value2"],["key3", "value3"]], skin:"listSkin",
focusSkin:"listFSkin"};
var listPSP = {};
Accessible from IDE

Yes
20.3 ListBox - Platform Specific Properties

The platform specific properties for ListBox Widget are as follows:
l
applySkinsToPopup
blockedUISkin
dropDownImage
groupCells
hoverSkin
multiSelect
multiSelectRows
nativeListFieldSkin
placeholder
placeholderSkin
popupIcon
popupTitle
tickedImage
toolTip
untickedImage
viewType
viewConfig
20.3.1 applySkinsToPopup
Specifies if the skin and focusSkin properties specified for the ListBox must be applied to the popup that
appears when you click on the ListBox.
Default: false
If set to true, the skin is applied to the popup.
If set to false, the skin is not applied to the popup.
Apply Popup Skin-true
Apply Popup Skin-false
Syntax
JavaScript: applySkinsToPopup
Lua: applyskinstopopup
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with the applySkinsToPopup: true
stFSkin"};
var listPSP = {applySkinsToPopup: true};
Accessible from IDE

Yes
Available on Android/Android Tablet platform only.
call) is completed.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the blockedUISkin:"blckUISkin"
stFSkin"};
var listPSP = {blockedUISkin:"blckUISkin"};
//Reading the blockedUISkin of the listbox
alert("listbox blockedUISkin ::"+listbx.blockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
Note: For Windows Phone platform, you can specify the image from the ListBox skin.
The following figure illustrates the default drop-down box indicator:
Syntax
Lua: dropdownimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with the dropDownImage: "downarrow.p
ng"
stFSkin"};
var listPSP = {dropDownImage: "downarrow.png"};

Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
20.3.4 groupCells
Specifies if all the rows in the ListBox should be grouped using a rounded corner background and border.
Default: false
If set to true, the cells will have a rounded border.
If set to false, the cells will not have rounded border.
Note: For iOS platform, this property is applicable only when viewType is set as LISTBOX_VIEW_TYPE_
TABLEVIEW.
Syntax
Lua: groupcells
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with groupCells:true
var listBasic ={id:"listbox",isVisible:true, masterData:[["key1",
"value1"],["key2", "value2"],["key3", "value3"]], skin:"listSkin", focusSk

in:"listFSkin"};
var listLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, container
Weight:80, hExpand:false};
var listPSP = {groupCells:true, viewType:constants.LISTBOX_VIEW_TYPE_TABLE
VIEW};
Accessible from IDE

Yes
l
iPad
iPhone
20.3.5 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the hoverSkin:"hskin"
stFSkin"};
var listPSP = {hoverSkin:"hskin"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
20.3.6 multiSelect
Specifies if the widget allows multiple values to be selected from the drop down list.
Default: false
If set to true, an additional property multiSelectRows is displayed.
Syntax
JavaScript: multiSelect
Type
JavaScript: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with the multiSelect:false
stFSkin"};
var listPSP = {multiSelect:false};
Accessible from IDE

Yes
20.3.7 multiSelectRows
Specifies the number of visible rows in the ListBox. A ListBox in Desktop Web can grow to any length. This
property is used to restrict the number of rows visible in a ListBox.
Note: This property is displayed only when the multiSelect is set to true.
Default: none
Syntax
JavaScript: multiSelectRows
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Listbox with the multiSelectRows:5
stFSkin"};
var listPSP = {multiSelect:true, multiSelectRows:5};
Accessible from IDE

Yes
Specifies the skin that is applied to each item in the native popup that appears when you click on the ListBox.
Syntax
JavaScript: nativeListFieldSkin
Lua: nativelistfieldskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the nativeListFieldSkin:"native
ListSkin"
stFSkin"};
var listPSP = {nativeListFieldSkin:"nativeListSkin"};
//Reading the nativeListFieldSkin of the listbox
alert("listbox nativeListFieldSkin ::"+listbx.nativeListFieldSkin);
Accessible from IDE

Yes
l
BlackBerry
Specifies the skin that is applied to a focused item in the native popup that appears when you click on the
ListBox.
Syntax
JavaScript: nativeListFieldFocusSkin
Lua: nativelistfieldfocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the nativeListFieldFocusSkin:"n
ativeListFSkin"
stFSkin"};
var listPSP = {nativeListFieldFocusSkin:"nativeListFSkin"};
//Reading the nativeListFieldFocusSkin of the listbox.
alert("listbox nativeListFieldFocusSkin ::"+listbx.nativeListFieldFocusSki
n)
Accessible from IDE

Yes
l
BlackBerry
20.3.10 placeholder
ListBox until the actual selection is made. If you do not specify the placeholder text, the first option in the list
is shown as the selected value.
If placeholder is set then by default (without user selecting any option) selectedKey and selectedKeyValue
properties will return null/nil.
If placeholder is not set then by default the first entry should be shown as selected and selectedKey and
selectedKeyValue properties will return the first options key-value pair.
Syntax
Lua: placeholder
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the placeholder:"Please select a
value"
stFSkin"};
var listPSP = {placeholder:"Please select a value"};
//Reading the placeholder of the listbox.
alert("listbox placeholder ::"+listbx.placeholder);
Accessible from IDE

Yes
l
iPad
iPhone
BlackBerry
Windows Phone
Windows Kiosk
This property reads the font color set in the skin and ignores the other attributes.Android does not support
setting a background color for a placeholder.
Syntax
JavaScript: placeholderSkin
Lua: placeholderskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Listbox with the placeholderSkin:"plcHolderS
kn"
stFSkin"};
var listPSP = {placeholderSkin:"plcHolderSkn"};
//Reading the placeholderSkin of the listbox
alert("listbox placeholderSkin ::"+listbx.placeholderSkin);
Accessible from IDE

Yes
This property is available on Android/Android Tablet platform only.
20.3.12 popupIcon
Specifies the icon that appears in the title area of the popup (on the top left side of the popup). For the popup to
appear, you have to expand or click the Listbox.
Default: empty
The figure below depicts how a Popup Icon in a List Box looks:
Syntax
JavaScript: popupIcon
Lua: popupicon
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with popupIcon:"icon.png"
stFSkin"};
var listPSP = {popupIcon:"icon.png"};
Accessible from IDE

Yes
This property is available on Android/Android Tablet platform only.
20.3.13 popupTitle
Specifies the Title text to be displayed for the Listbox.
Default: Please Select (This is the default text that will appear as the title of the Listbox)
Syntax
JavaScript: popupTitle
Lua: popuptitle
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with popupTitle:"List of items"
stFSkin"};
var listPSP = {popupTitle:"List of items"};
Accessible from IDE

Yes
l
Symbian
20.3.14 tickedImage
Note: If you specify a ticked Image, ensure that you also specify an unTickedimage. If not specified, the
Syntax
Lua: tickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with tickedImage:"tickImg.png"
stFSkin"};
var listPSP = {tickedImage:"tickImg.png"};
Accessible from IDE

Yes
l
iPad
iPhone
20.3.15 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a ListBox with toolTip:sample text
var listBasic={id:"listbox1", isVisible:true, skin:"listSkin", focusSkin:"
listFSkin", text:"Click Here", toolTip:"sample text"};
var listLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hE
var listPSP={};
var listbox1 = new kony.ui.ListBox(listBasic, listLayout, listPSP);
Accessible from IDE

Yes
Syntax
Lua: untickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Listbox with untickedImage:"untickImg.png"
stFSkin"};
var listPSP = {untickedImage:"untickImg.png"};
Accessible from IDE

Yes
l
iPad
iPhone
20.3.17 viewType
Specifies the view type of the ListBox.
Default: LISTBOX_VIEW_TYPE_LISTVIEW
Following are the available options on various platforms:
l
LISTBOX_VIEW_TYPE_LISTVIEW (applicable on all platforms)
LISTBOX_VIEW_TYPE_TABLEVIEW (applicable on iPhone and iPad platforms)
LISTBOX_VIEW_TYPE_TOGGLEVIEW (applicable on iPhone and iPad platforms)
LISTBOX_VIEW_TYPE_ONSCREENWHEEL (applicable on iPhone and iPad platforms)
LISTBOX_VIEW_TYPE_SPINNER (applicable on Android/Android Tablet only)
Note: For toggleView you can further select the View Style as plain, bordered, or bar.

listView
tableView
toggleView
onscreenwheel
spinner
The below image illustrate the nextprevtoolbar set to a listbox. The highlighted toolbar is achieved on
setting the Mode as onscreenwheel to the List Box and Input Accessory View Type as nextprevtoolbar to
the Form.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Listbox with the viewType: constants.LISTBOX_
VIEW_TYPE_SPINNER.
stFSkin"};
var listPSP = {viewType: constants.LISTBOX_VIEW_TYPE_SPINNER};
//Reading the viewType of the listbox.
alert("listbox viewType ::"+listbx.viewType);
Accessible from IDE

Yes
l
iPad
iPhone
Android/Android Tablet (only Spinner view is available for the platform)
20.3.18 viewConfig
toggleViewConfig: The property to configure the properties of LISTBOX_VIEW_TYPE_TOGGLEVIEW.
l
LISTBOX_TOGGLE_VIEW_STYLE_PLAIN
LISTBOX_TOGGLE_VIEW_STYLE_BORDERED
LISTBOX_TOGGLE_VIEW_STYLE_BAR
Syntax
Lua: viewconfig
Type
Lua: Table
Read / Write
Accessible from IDE

Yes
l
iPad
iPhone
Specifies the background color for the wheel that is displayed when you click the ListBox. This property is
applicable only when you set the viewType as LISTBOX_VIEW_TYPE_ONSCREENWHEEL.
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for Listbox
stFSkin"};
var listPSP = {viewType: constants.LISTBOX_VIEW_TYPE_ONSCREENWHEEL};
form.listbx.wheelBackgroundColor = "0000ff00";
Accessible from IDE

No
l
iPad
iPhone
20.4 ListBox - Events

ListBox has the following event associated with it:
l
onSelection
preOnclickJS
postOnclickJS
20.4.1 onSelection
Note: This callback is not invoked if the selectedKey and selectedKeyValue are changed programmatically.
Note: In BlackBerry 10 platform, invoking this event dynamically is not supported.
Signature
Lua: onselection
Read / Write
JavaScript Example
//The below function is the call back function for onSelection event.
function onSelectionCallBck(list)
{
}
{
//Defining the properties for Listbox with onSelection:onSelectionCallBck.
1"],["key2", "value2"],["key3", "value3"]],
onSelection:onSelectionCallBck};

var listPSP = {};
Available on all platforms except Server side Mobile Web (Basic). This event is not supported because
Java script is not supported on browsers of basic devices. To achieve a functionality similar to this on
Server side Mobile Web (Basic), you must create an additional button for the Basic version of the Server
side Mobile Web with an onclick event and attach an ondone closure.
20.4.2 preOnclickJS
This event allows the developer to execute custom javascript function before the onClick callback of the
ListBox is invoked. This is applicable only for Mobile Web channel. The function must exist in a javascript file
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the call back function for preOnclickJS event.
function preOnclickJSCallBck(list)
{
}
//Defining the properties for Listbox with preOnclickJS:preOnclickJSCallBc
1"],["key2", "value2"],["key3", "value3"]]};
var listPSP = {preOnclickJS:preOnclickJSCallBck};
Accessible from IDE

Yes
This event allows the developer to execute custom javascript function after the onClick callback of the
ListBox is invoked. This is applicable only for Mobile Web channel.The function must exist in a javascript file
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the call back function for postOnclickJS event.
function postOnclickJSCallBck(list)
{
}
//Defining the properties for Listbox with postOnclickJS:postOnclickJSCall
Bck
1"],["key2", "value2"],["key3", "value3"]]};
var listPSP = {postOnclickJS:postOnclickJSCallBck};
Accessible from IDE

Yes
20.5 ListBox - Deprecated Properties

This section contains the following:
l
listStyle
multiple
placeholderi18nKey
selectedkeys
selectedkeyvalues
20.5.1 listStyle
Specifies the appearance of the List Box. You can set the style to one of the following:
l
Default (this is the default selected option)
Spinner Style
If the List Style is default, the appearance of the List Box is as follows:
If you change the List Style to Spinner Style, the appearance of the ListBox is as follows:
Type
Number
Read / Write
No
Accessible from IDE

Yes
20.5.2 multiple
Specifies if the widget allows multiple values to be selected from the drop down list.
Default: false
If set to true, multiple selection is allowed.
If set to false, multiple selection is not allowed.
Note: List Box does not support multiple selection from Release 3.0 onwards. However, if you have
upgraded from a version prior to Release 3.0 and used multiple selection, to maintain backward
compatibility, this property is enabled. If you then change the value to false, you cannot change the value
back to true.
Note: If you require multiple selection capability, use either a CheckBox widget or a Segment with multiple
selection enabled.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
Specifies the i18n key for the placeholder text to be used for internationalization.
Type
String
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
J2ME
20.5.4 selectedKey
Specifies the value to be shown as selected.
If you do not select a value, the return value is nil.
Type
String
Read / Write
Yes (Write)
If a Form frm1 has a ListBox lstbx1, and the master data is as follows:
frm1.lstbx1.masterdata = {{"A","Asia"},{"E","Europe"},{"NA","North
America"} }
If you want Asia to be shown as selected, enter the following:
frm1.lstbx1.selectedkey = "A"
Accessible from IDE

No
If you do not select a value, the return value is nil.
Type
Object
Read / Write
Yes (Read)
If a Form frm1 has a ListBox lstbx1, and the master data is as follows:
frm1.lstbx1.masterdata = {{"A","Asia"},{"E","Europe"},{"NA","North
America"} }
When the user makes a selection, you can know the user selection by entering the following:
local var = frm1.lstbx1.selectedkeyvalue
For example, if the user selected Asia, the value returned is {"A","Asia"}
Accessible from IDE

No
21. MenuContainer
A MenuContainer is a horizontal strip that can contain any number of Menus and MenuItems. The Menus
provide the access to functions such as navigate to a specified form, access to an external link, or a specific
user action.
A Menu Template currently allows you to drag and drop the following widgets:
l
HBox
VBox
Image
Label
Link
Note: MenuContainer is supported in Desktop Web platform only.

When do I use a MenuContainer?
You can use a MenuContainer in the following scenario:
l
to navigate to other forms in the application.
to perform an action on an onClick event of a menu.
to provide customized options in the Menu for a Form.

For example, in a Retail Application, you can have menus showing various segments of products. You
can add number of menu items on a MenuContainer.
MenuContainer provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Property, Events, and Methods.
Basic Properties
Layout Properties
activeSkin
collapsedImage
containerWeight
margin
data
marginInPixel
expandedImage
padding
hoverSkin
paddingInPixel
id
widgetAlignment
Platform Specific
Properties
contextMenu
collapsedImage
expandedImage
viewType
info
isVisible
menuItemTemplate
orientation
selectedMenuIndex
selectedMenuItem
skin
widgetDataMap
Event
Methods
onClick
onRightClick
addAll
addDataAt
removeAll
removeAt
setData
setDataAt
Creating a MenuContainer using a constructor: kony.ui.MenuContainer

var menuContainer = new kony.ui.MenuContainer(basicConf, layoutConf, pspCo
nf)
l
they are ignored.
JavaScript Example
//Defining the properties for a MenuContainer.
var mnuBasic = {id:"menu1", hoverSkin:"mnuhovSkin", activeSkin: "mnuactSki
n",
data:[{template: hbox2,
label2: {text: "News", isVisble: false},
image2: "btn.png",
children: []
},
{template: hbox2,
label2: {text: "Science"},
image2: "btn.png",
children: []
},
{template: hbox2,
label2: {text: "Sports"},
image2: "btn.png",
children: [
{template: hbox2,
label2: {text: "Football"},
image2: "btn.png"
},
{template: hbox2,
label2: {text: "Cricket"},
image2: "btn.png",
children: [
{template: hbox2,
label2: {text: "India"},
image2: "btn.png",
children: [
{template: hbox2,
label2: {text: "Test Match"},
image2: "btn.png"
},
{template: hbox2,
label2: {text: "One Day Match"},
image2: "btn.png"
}
]
},
{template: hbox2,
label2: {text: "England"},
image2: "btn.png"
},
{template: hbox2,
label2: {text: "Australia"},
image2: "btn.png"
}
]
}
}
], isVisible:true, menuItemTemplate: hbox2, skin:"mnuSkin", isVisible: tr
ue, widgetDataMap:{label2: "label2", image2: "image2"} };
var mnuLayout = {padding:[5,5,5,5], margin:[5,5,5,5], containerWeight:100,
paddingInPixel:true, marginInPixel:true, widgetAlignment:constants.WIDGET_
ALIGN_TOP_LEFT};
var mnuPSP ={viewType: constants.MENU_CONTAINER_VIEW_DROPDOWNVIEW};
//Creating the MenuContainer.
var menu1 = new kony.ui.MenuContainer(mnuBasic, mnuLayout, mnuPSP);
menu1.addAll ([{template: hbox2,
label2:{text: "Politics"},
image2: "btn.png",
children: []
}]);
Adding a MenuContainer from IDE

The steps involved in adding a MenuContainer widget are as follows:
2. Expand the application for which you want to use Menus.
window appears.
4. Enter a name for the form and click Finish. A new form is created.
5. Drag and drop a MenuContainer on the form.

Note: The MenuContainer should not be placed at the bottom of the form because the menu always
expands downwards. If still want to place the menu at the bottom of the form, ensure that you have
enough space to view the items when the menu is expanded.
6. To add menu, define a menu template as explained in templates section. You can define different
templates for menus and sub menus.
7. To assign the template to menu container, follow the below steps:
a. Select the MenuContainer and from the Widget Properties window and locate the
property menuItemTemplate. Set the template from the drop down menu.
b. Locate the property data and assign data to it. The following image illustrates the Master
Data for MenuBar window:
c. Right-click on the row MenuBar Data and select Add MenuItem. A row gets added.
Select Template ID, click Template Data to update the values for the properties
displayed.
d. To add sub menu items, set the subMenucolumn false/true to the respective menu
item. If the menu item is set to true you can add sub menu items.
e. To create a submenu item for a menu item, right-click on submenu item and select Add
MenuItem. A row gets added.
f. Select Template ID, click Template Data to update the values for the properties
displayed.
g. Once you are done, click OK. Following is the snapshot of a typical menu with sub menu
items.
21.1 MenuContainer - Basic Properties

The basic properties for MenuContainer widget are as follows:
l
activeSkin
data
hoverSkin
id
info
isVisible
menuItemTemplate
orientation
selectedMenuIndex
selectedMenuItem
skin
widgetDataMap
21.1.1 activeSkin
Specifies the skin for a menu item that is currently selected.
Syntax
JavaScript: skin
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with activeSkin: "mnuactSki
n", Skin with the same name should be created through IDE or handcode.
n",
label2: {text: "One", isVisble: false},
image2: "btn.png",
children: []
},
{template: hbox2,
label2: {text: "Two"},
image2: "btn.png",
children: []
},
{template: hbox2,
label2: {text: "Three"},
image2: "btn.png",
},
{template: hbox2,
label2:{text: "Four"},
image2: "btn.png",
children: []
}
], isVisible:true, menuItemTemplate: hbox2, skin:"mnuSkin", viewType: con
stants.MENU_CONTAINER_VIEW_DROPDOWNVIEW, widgetDataMap:{label2: "label2",
image2: "image2"} };
ALIGN_TOP_LEFT};
var mnuPSP ={};
//Reading the activeSkin of the MenuContainer.
alert("MenuContainer activeSkin ::"+menu1.activeSkin);
Accessible from IDE

Yes
21.1.2 data
Specifies the menu items that must be displayed in the Menu. You can set the data in the below format.
//Data format
{metaInfo : {"skin" : "skinname"} //skin is applied to the box.
template:boxRef2,
label1:{"skin":"someskin", "text":"foo", "isVisible":false}//JSObject w
ith write properties of the widget as keys with corresponding values.
image2:"icon.png"//JSObject with write properties of the widget as keys
with corresponding values.
children: [{Array of Child menu items}]
}
Note:
Template is the standard key which can be used optionally to override the common menuItemTemplate
provided with a specific template for the row. For template, always the value has to be valid box reference, if
not it falls back to common menuItemTemplate.
metaInfo is another standard key which can be used to specify some meta information about the row. For
example clickable and skin.
All write properties of the widget are allowed to be set as a part of the widget data while programming for the
menu items.
To add menu and sub menu items to the menu container, follow these steps:
Before proceeding, ensure that you have already created menu templates to be used in the data property.
1. To specify the values, click the Ellipsis button against the property to open the screen Master data for
MenuBar.
2. Right-click on MenuBar Data and select Add MenuItem. A Menu item is added.
3. Assign the Template Id and click Template Data to update the values for the properties displayed.
4. To add sub menu items, set the subMenucolumn false/true to the respective menu item. If the menu
item is set to true you can add sub menu items. Right-click on the menu item and select Add
MenuItem and update the data accordingly.
5. Once you are done, click OK.
Note: When you change a submenu to menu or viceversa, the data that is set will be lost and templateID
gets reset to default template.
Syntax
JavaScript: data
Type
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with data.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
label2: {text: "Three One"},
image2: "btn.png"
},
{template: hbox2,
label2: {text: "Three Two"},
image2: "btn.png",
children: [
{template: hbox2,
label2: {text: "Three Two One"},
image2: "btn.png",
children: [
{template: hbox2,
label2: {text: "Three Two One One"},
image2: "btn.png",
},
{template: hbox2,
label2: {text: "Three Two One Two"},
image2: "btn.png",
}
]
},
{template: hbox2,
label2:{text: "Three Two Two"},
image2: "btn.png"
},
{template: hbox2,
label2: {text: "Three Two Three"},
image2: "btn.png"
}
}
]
},
{template: hbox2,
image2: "btn.png",
children: []
}
], isVisible:true, menuItemTemplate: hbox2, skin:"mnuSkin", widgetDataMap
:{label2: "label2", image2: "image2"} };
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
21.1.3 hoverSkin
Syntax
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with hoverSkin:"mnuhovSkin",
Skin with the same name should be created through IDE or handcode.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
//Reading the hoverSkin of the MenuContainer.
alert("MenuContainer hoverSkin ::"+menu1.hoverSkin);
Accessible from IDE

Yes
21.1.4 id
id is a unique identifier of MenuContainer consisting of alpha numeric characters. Every MenuContainer
should have a unique id within a Form.
Syntax
JavaScript: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a MenuContainer with id: "menu1".
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
21.1.5 info
Syntax
JavaScript: info
Type
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with info: "MenuContainer In
fo".
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
menu1.info = {key:"MenuContainer info"};
Accessible from IDE

No
21.1.6 isVisible
Default: true
Syntax
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with isVisible: true.
n",

image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
//Reading the isVisible of the MenuContainer.
alert("MenuContainer isVisible ::"+menu1.isVisible);
Accessible from IDE

Yes
21.1.7 menuItemTemplate
Indicates a common template to be used for each menuItem while creating the menu items and filling the data.
Syntax
JavaScript: menuItemTemplate
Type
JavaScript: kony.ui.Box - [Mandatory]
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with menuItemTemplate: hbox2.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ue, widgetDataMap:{label2: "label2", image2: "image2"}};
ALIGN_TOP_LEFT};
//Reading the menuItemTemplate of the MenuContainer.
alert("MenuContainer menuItemTemplate ::"+menu1.menuItemTemplate);
Accessible from IDE

No
21.1.8 orientation
Specifies how you can stack the widgets within the MenuContainer. You can set the orientation of the
MenuContainer as horizontal or vertical.
Note: This property is disabled if the viewType is set as MENU_CONTAINER_VIEW_TYPE_TREEVIEW.
Default: MENUCONTAINER_POSITION_AS_HORIZONTAL
l
MENUCONTAINER_POSITION_AS_HORIZONTAL: Enables you to stack the content within the

menucontainer horizontally.
MENUCONTAINER_POSITION_AS_VERTICAL: Enables you to stack the content within the

menucontainer vertically.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with orientation :constants.
MENUCONTAINER_POSITION_AS_HORIZONTAL.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
:{label2: "label2", image2: "image2"},orientation:constants.MENUCONTAINE
R_POSITION_AS_HORIZONTAL};
ALIGN_TOP_LEFT};
var mnuPSP ={viewType: constants.MENU_CONTAINER_VIEW_DROPDOWNVIEW, };
//Reading the orientation of the MenuContainer.
alert("MenuContainer orientation ::"+menu1.orientation );
Accessible from IDE

Yes
21.1.9 selectedMenuIndex
Indicates the selected Menu Item. The index starts from 0.
For example, if the selectedMenuItem is:
l
[0 ] indicates the first menu item in the menu container.
[0, 2 ] indicates 2nd menu item which is under the first menu item in the menu container.
[0, 2, 4] indicates 4th menu item, which is the child of 2nd menu item of the 0th menu item in the menu
container.
Syntax
JavaScript: selectedMenuIndex
Type
JavaScript: Array
Read / Write
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
//Reading the selectedMenuIndex of the MenuContainer.
alert("MenuContainer selectedMenuIndex::"+menu1.selectedMenuIndex);
Accessible from IDE

No
21.1.10 selectedMenuItem
Returns the selected menu item present at the selectedMenuIndex.
Syntax
JavaScript: selectedMenuItem
Type
JavaScript: Array
Read / Write
Yes - (Read only)
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
}
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
//Reading the selectedMenuItem of the MenuContainer.
alert("MenuContainer selectedMenuItem::"+menu1.selectedMenuItem);
Accessible from IDE

No
21.1.11 skin
Specifies the skin for a MenuContainer.
Syntax
JavaScript: skin
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with skin: "mnuskin", Skin w
ith the same name should be created through IDE or handcode.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
//Reading the skin of the MenuContainer.
alert("MenuContainer skin ::"+menu1.skin );
Accessible from IDE

Yes
Note: It is developer responsibility to ensure that widget data map to accommodate all the widget ids
{
widgetID1:
widgetId2:
widgetId3:
widgetId4:
widgetId5:
"dataId1",
"dataId2",
"dtaId3",
"secDataId1"
"secDataId2"
Syntax
JavaScript: widgetDataMap
Type
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with widgetDataMap:{label2:
"label2", image2: "image2"}.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
//Reading the widgetDataMap of the MenuContainer.
alert("MenuContainer widgetDataMap::"+menu1.widgetDataMap);
Accessible from IDE

No
21.2 MenuContainer - Layout Properties

The layout properties for MenuContainer widget are as follows:
l
containerWeight
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with containerWeight:100.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
:{label2: "label2", image2: "image2"}};
ALIGN_TOP_LEFT};
//Reading the containerWeight of the MenuContainer.
alert("MenuContainer containerWeight::"+menu1.containerWeight);
Accessible from IDE

No
21.2.2 margin
Syntax
JavaScript: margin
Type
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with margin:[5,5,5,5].
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
Default: false
Syntax
Type
JavaScript: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a MenuContainer with marginInPixel:true.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
21.2.4 padding
Note: Due to Browser restrictions, you cannot apply Padding for a ComboBox and Form widgets on Mobile
Web platform. Padding is not supported by Windows Mobile browser for Box and Image Gallery.
Syntax
JavaScript: padding
Type
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with padding:[5,5,5,5].
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
Default: false
Syntax
Type
JavaScript: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a MenuContainer with paddingInPixel:true.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
l
WIDGET_ALIGN_TOP_LEFT
WIDGET_ALIGN_CENTER
WIDGET_ALIGN_BOTTOM_RIGHT
Syntax
Type
JavaScript: Number
Read / Write
No
JavaScript Example
//Defining the properties for a MenuContainer with widgetAlignment as top
left.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
Accessible from IDE

Yes
21.3 MenuContainer - Platform Specific Properties

The Platform Specific properties for MenuContainer widget are as follows:
contextMenu
collapsedImage
expandedImage
viewType
21.3.1 contextMenu
Default: None
A series of steps to be followed to use contextMenu:
2. Define a contextmenu template under project > templates >menus.
d. Enter a Name for the template and click Finish. A new form is created
e. Drag-drop a menucontainer.
Syntax
Type
Read / Write
JavaScript Example
function initializeaddtoabc()
{
"data": [{template: hbox12068, "label12068": {"text": "India"},
children: [{template: hbox12068, "label12068": {"text": "Mumbai"},
"image212068": {}, children: [] }]
},
{template: hbox120685810729885, "label12068": {"text": "Srilanka" },
"image212068": {} }
],
212068"},
"menuItemTemplate": hbox12068},
{"widgetAlignment": constants.WIDGET_ALIGN_CENTER, "containerWeight": "5
0",
"margin": [0, 0, 0, 0], "padding": [0, 0, 0, 0], "marginInPixel": false,
},
{"viewType": constants.MENU_CONTAINER_VIEW_TYPE_CONTEXTVIEW });
};
//Defining the box with contextMenu:menucontainer12068.
//Creating the box.
nfBox );
Accessible from IDE

Yes
21.3.2 collapsedImage
Note: This property is displayed only when the viewType is selected as MENU_CONTAINER_VIEW_
TYPE_TREEVIEW.
Specifies the image to collapse an extended menu.
Syntax
JavaScript: skin
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with collapsedImage.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
:{label2: "label2", image2: "image2"}, orientation:constants.MENUCONTAINE
ALIGN_TOP_LEFT};
var mnuPSP ={collapsedImage: "collapseimage",expandedImage: "expandimage",
viewType: constants.MENU_CONTAINER_VIEW_TREEVIEW};
//Reading the collapsedImage of the MenuContainer.
alert("MenuContainer collapsedImage::" + menu1.collapsedImage);
Accessible from IDE

Yes
21.3.3 expandedImage
Note: This property is displayed only when the viewType is selected as MENU_CONTAINER_VIEW_
TYPE_TREEVIEW.
Specifies the image to expand a collapsed menu.
Syntax
JavaScript: skin
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with expandedImage.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
:{label2: "label2", image2: "image2"}, orientation:constants.MENUCONTAINE
ALIGN_TOP_LEFT};
var mnuPSP ={collapsedImage: "collapseimage", expandedImage: "expandimage",
viewType: constants.MENU_CONTAINER_VIEW_TREEVIEW};
//Reading the expandedImage of the MenuContainer.
alert("MenuContainer expandedImage::" + menu1.expandedImage);
Accessible from IDE

Yes
21.3.4 viewType
Specifies the view of the MenuContainer when expanded.
Default: MENU_CONTAINER_VIEW_TYPE_DROPDOWNVIEW
l
MENU_CONTAINER_VIEW_TYPE_CONTEXTVIEW: This view is applicable only when defining

contextmenu. The items are aligned as defined in a menutemplate. When you right-click (appropriate to
the widget in focus) the context specific menu will be displayed with the array of menu items.
MENU_CONTAINER_VIEW_TYPE_DROPDOWNVIEW: This is the default view. The MenuItems of

the MenuContainer are dropped downwards vertically. The items are aligned one below the other. The
Menu gets expanded when the cursor hovers over the MenuContainer.
MENU_CONTAINER_VIEW_TYPE_DROPLINEVIEW: The MenuItems of the MenuContainer are

dropped downwards horizontally. The items are aligned next to each other. The Menu gets expanded
when the cursor hovers over the MenuContainer. This view is not supported in Internet Explorer 8 and
Internet Explorer 9 versions.
MENU_CONTAINER_VIEW_TYPE_TREEVIEW: The MenuItems of the MenuContainer are

displayed in a hierarchical structure vertically. You can expand and collapse the MenuItems. When this
option is selected two additional properties expandedImage and collapsedImage are displayed to
specify the images to expand and collapse a menu.
Note: MenuContainer first level is always horizontal when the view is set as DROPDOWNVIEW and
DROPLINEVIEW.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a MenuContainer with viewType: constants.MEN
U_CONTAINER_VIEW_DROPDOWNVIEW.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
children: []
}
], isVisible:true, menuItemTemplate: hbox2, skin:"mnuSkin", , isVisible:
true, widgetDataMap:{label2: "label2", image2: "image2"},orientation:con
stants.MENUCONTAINER_POSITION_AS_HORIZONTAL};
ALIGN_TOP_LEFT};
//Reading the viewType of the MenuContainer.
alert("MenuContainer viewType::"+menu1.viewType);
Accessible from IDE

Yes
21.4 MenuContainer - Event

MenuContainer widget has the following events associated with it:
l
onClick
onRightClick
21.4.1 onClick
An event callback is invoked by the platform when the user performs a click action on the MenuContainer.
Signature
JavaScript: onClick(menuContainer, selectedMenuIndex, selectedMenuItem)
Input Parameters
menuContainer [widgetref]- Mandatory
Reference to the menuContainer widget that raised the event.
selectedMenuIndex [Number]- Mandatory
Specifies the index of the selected menu.
selectedMenuItem [Number]- Mandatory

Specifies the item of the selected menu.
Read / Write
JavaScript Example
//The below function is the callback function for onClick event.
function onClickCalBck(widgetModel, itemIndex, itemData)
{
//itemIndex is an array
//itemData is an object
//Assuming the template has a label widget with an id "label2".
if(itemData.label2 == "One") {
frmOne.show();
} else if(itemData.label2 == "Two") {
frmTwo.show();
}
}
//Defining the properties for a MenuContainer with onClick:onClickCallBck.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
}
},
{template: hbox2,
image2: "btn.png",
children: []
}
image2: "image2"},onClick:onClickCalBck };
ALIGN_TOP_LEFT};
var mnuPSP ={};
Accessible from IDE

Yes
21.4.2 onRightClick
An event callback is invoked by the platform when the user performs a right-click action on the
MenuContainer.
Signature
JavaScript: onRightClick(menuContainer, selectedMenuIndex, selectedMenuItem)
Input Parameters
menuContainer [widgetref]- Mandatory
Reference to the menuContainer widget that raised the event.
selectedMenuIndex [Number]- Mandatory
Specifies the index of the selected menu.
selectedMenuItem [Number]- Mandatory
Specifies the item of the selected menu.
Read / Write
JavaScript Example
//The below function is the callback function for onRightClick event.
function onRightClickCalBck(widgetModel, itemIndex, itemData)
{
//itemIndex is an array
//itemData is an object
//Assuming the template has a label widget with an id "label2".
if(itemData.label2 == "One") {
frmOne.show();
} else if(itemData.label2 == "Two") {
frmTwo.show();
}
}
//Defining the properties for a MenuContainer with onRightClick:onRightCli
ckCallBck.
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,

image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
},
{template: hbox2,
image2: "btn.png",
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
}
]
},
{template: hbox2,
image2: "btn.png",
children: []
}
image2: "image2"},onRightClick:onRightClickCalBck };
ALIGN_TOP_LEFT};
var mnuPSP ={};
Accessible from IDE

Yes
21.5 MenuContainer - Methods

The MenuContainer widget has the following methods associated with it:
l
addAll
addDataAt
removeAll
removeAt
setData
setDataAt
21.5.1 addAll
This method allows you to add new data to the menu container widget. The new data is appended to the
existing data.
Signature
Input Parameters
data [Array] - Mandatory
Specifies an array to represent data as key value pairs. The format of the array of data is as
explained in data property of menuContainer basic properties. The top most menu items are directly
added to the menuContainer.
Return Values
None
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
}
]
}
stants.MENU_CONTAINER_VIEW_DROPDOWNVIEW, isVisible: true, widgetDataMap:{
label2: "label2", image2: "image2"} };
ALIGN_TOP_LEFT};
var mnuPSP ={};

menu1.addAll ([{template: hbox2,
label2:{text: "Politics"},
image2: "btn.png",
children: []
}]);
Error Codes
None
21.5.2 addDataAt
Allows you to add an array of menu items at a given index. The new data is placed before the index. The
existing menu items are pushed to the next row.
Signature
JavaScript: addDataAt(data, Index)
Input Parameters
data [JSObject ] - Mandatory
Specifies the JSObject to represent data as key value pairs. The format of the array of data is as
explained in data property of MenuContainer basic properties.
Index [Array] - Mandatory
Specifies an array representing the index at which the menu item data needs to be added. The
format of the array is as explained in selectedMenuIndex property of MenuContainer basic
properties. For example, [0, 1, 2] - Add data at 2nd position of 1st menu item under 0th menu item in
the menu container.
if at any level of the hierarchy if a provided position is not found, it is simply added to the last
available menu item.
For example, addDataAt(data, [1, 2, 3]) if the 3rd row is not found, then menu items defined will be
added under the last available menu item which in this case will be the 2nd position. Which means
the data is actually added to the position [1, 2, 2].
Return Values
None
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
}
]
}

ALIGN_TOP_LEFT};
var mnuPSP ={};
menu1.addDataAt ({template: hbox2,
label2: {text:"Politics"},
image2: "btn.png",
children: []
}, 3);
Error Codes
None
21.5.3 removeAll
This method is used to remove all the menu items and sub menus from the menu container.
Signature
Input Parameters
None
Return Values
None
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
}
ALIGN_TOP_LEFT};
var mnuPSP ={};
menu1.removeAll ();
Error Codes
None
21.5.4 removeAt
This method is used to remove the menu item from hierarchy based on the index provided.
Signature
JavaScript: removeAt(Index)
Input Parameters
Specifies an array representing the Index at which the menu item data needs to be removed. The
properties.
Return Values
None
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
}
]
ALIGN_TOP_LEFT};
var mnuPSP ={};
//removeAt method call.
menu1.removeAt ([0,1]);
Error Codes
None
21.5.5 setData
This method allows you to set new data to the menuContainer widget. When you set new data, the existing
data will be replaced with the new data.
Signature
JavaScript: setData()
Input Parameters
menubarRef [Array] - Mandatory
Specifies an array of menu items.
Return Values
None
JavaScript Example
n",
label2: {text:"Weather"},
image2: "btn.png",
children: []
}
ALIGN_TOP_LEFT};
var mnuPSP ={};
menu1.setData [
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
}
];
Error Codes
None
21.5.6 setDataAt
This method allows you to set/modify the menu item at a particular index in the hierarchy with in the
menuContainer.
Signature
JavaScript: setDataAt(data, index)
Input Parameters
explained in data property of MenuContainer basic properties.
Index [Array] - Mandatory
Specifies an array representing the index at which the menu item data needs to be added. The
properties. For example, [0, 1, 2] - Add data at 2nd position of 1st menu item under 0th menu item in
the menu container.
if at any level of the hierarchy if a provided position is not found, it is simply added to the last
available menu item.
For example, addDataAt(data, [1, 2, 3]) if the 3rd row is not found, then menu items defined will be
added under the last available menu item which in this case will be the 2nd position. Which means
the data is actually added to the position [1, 2, 2].
Return Values
None
JavaScript Example
n",
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: []
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png",
children: [
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
},
{template: hbox2,
image2: "btn.png"
},
{template: hbox2,
image2: "btn.png"
}
]
}
}
ALIGN_TOP_LEFT};
var mnuPSP ={};
menu1.setDataAt ({template: hbox2,
label2: {text:"Politics"},
image2: "btn.png" ,
children: []
}, [0,3);
Error Codes
None
21.6 Menu - Templates

Note: Menu templates are supported only on Desktop Web platform.
21.6.1 What is a Template for Menu

In Kony platform, a menu template is a container which can hold widgets in it. You can customize the behavior
and look and feel of the menu template. The customized behavior is applied across the forms where the Menu
Templates are used.
To define a menu, the following widgets are used:
l
MenuContainer
Menu Template
MenuContainer: It is a parent container which acts as a menu when a Menu Template is mapped to it.
MenuTemplate: It is a container which holds widgets in it. You can define multiple templates to be used for
menus and sub menus.
A Menu Template currently allows you to drag and drop the following widgets:
l
HBox
VBox
Image
Label
Link
21.6.2 Where to use a Menu Template

Menus are typically used to navigate to a particular form or perform an action.
The Menu templates are used to:
l
have uniform look and feel of the Menus.
have uniform look and feel when an item is focused in a MenuContainer.
perform an action on the event of an onclick of an item in the MenuContainer.
define uniform margins and padding's for the MenuItems.
21.6.3 Creating a Template for Menu

You can create a multiple templates that can be used for menus and sub menus.
To create a template at the application-level, follow these steps:
2. Expand the application for which you want to create a menu template.
3. Navigate to templates > menus, right-click desktop and select New Menu Template. The Create a
New Menu window appears.
iii. Drag and drop an HBox and then a VBox within an HBox.
Note: Only HBox and VBox are supported on the form. You can put other widgets
within these widgets.
iv. Drag and drop the required widgets onto the HBox/VBox. Set the properties of these
widgets.
v. A menu template is created.
21.6.4 Using Menu Templates

Always create multiple templates for menus, sub menus for better user experience.
To use Menus Template in an application, follow these steps:
2. Expand the application for which you want to use Menus.
window appears.
4. Enter a name for the form and click Finish. A new form is created.
5. Drag-drop a MenuContainer on the form.
Note: The MenuContainer should not be placed at the bottom of the Form because the menu always
expands downwards. If still want to place the menu at the bottom of the form, ensure that you have
enough space to view the items when the menu is expanded.
6. From the Widget Properties window, select menuItemTemplate and select the template what you
have created. You can define different templates for menus and sub menus.
7. To assign the template to menu container, follow the below steps:
a. Select the MenuContainer and from the Widget Properties window and locate the
property menuItemTemplate. Set the template from the drop down menu.
b. Locate the property data and assign data to it. The following image illustrates the Master
Data for MenuBar window:
c. Right-click on the row MenuBar Data and select Add MenuItem. A row gets added.
Select Template ID, click Template Data to update the values for the properties
displayed.
d. To add sub menu items, set the subMenu column false/true to the respective menu
item. If the menu item is set to true you can add sub menu items.
e. To create a submenu item for a menu item, right-click on submenu item and select Add
MenuItem. A row gets added.
f. Select Template ID, click Template Data to update the values for the properties
displayed.
g. Once you are done, click OK. Following is the snapshot of a typical menu with sub menu
items.
22. MenuItem
MenuItem is a choice on the Menu. It is typically a command or function such as Application Logout, Form
Exit, Sending SMS, or other options that you can select inside a Menu.
You can add MenuItems for a specific Form. These MenuItems appear when you navigate to the Form (that
contains the MenuItems) and select the Menu button on the device. The added MenuItems appear along with
the regular device MenuItems for that Form.
Note: Menuitem is supported only on Android/Android tablet, BlackBerry, BlackBerry 10, and J2ME.
When do I use a MenuItem?
You can use a MenuItem in the following scenario:
l
To provide customized options in the Menu for a Form.

For example, in an Airlines Booking Application, in the confirmation page, you can add additional
MenuItems like, "Modify Travel Dates", "Modify Passenger Details" etc.
Menuitem provides you with an option to set Basic Properties and an Event.
Basic Properties
Event
focusImage
id
info
image
title
type
onClick
Adding a MenuItem from IDE

The steps involved in adding a MenuItem widget are as follows:
1. From the IDE, open the Form for which you want to add MenuItems.
2. Click Menu which is present on the right-hand bottom corner of the Form.
A Box appears on top of the Menu into which you can drag and drop the MenuItem from the Palette.
The following image illustrates the box into which you can drag the MenuItems in the IDE:
3. Drag and Drop the MenuItem from the palette.

Note: You can drag and drop any number of MenuItems into the box as per your requirement.
The following image illustrates a Menu with a MenuItem in the IDE:
4. Specify a name for the MenuItem using the title property.

5. (Optional) Specify an image and a focusImage for the MenuItem.
6. (Optional) For J2ME platform, specify the MenuItem type as ok, back, or exit.
7. Specify an onClick event for the MenuItem.
l
You cannot specify a skin for a MenuItem.
BlackBerry 10 platform does not support onClick event as writable property.
22.1 MenuItem - Basic Properties

The basic properties for MenuItem widget are as follows:
l
focusImage
id
info
image
title
type
22.1.1 focusImage
Specifies the image to be displayed when the focus is on the MenuItem.
Syntax
JavaScript: focusImage
Lua: focusimage
Type
JavaScript: String
Lua: String
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry
BlackBerry 10
J2ME
22.1.2 id
id is a unique identifier of Menuitem consisting of alpha numeric characters. Every Menuitem should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
Accessible from IDE

Yes
l
Android/Android tablet
BlackBerry
BlackBerry 10
J2ME
22.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
Accessible from IDE

No
l
BlackBerry
BlackBerry 10
J2ME
22.1.4 image
Specifies the image to be displayed for the MenuItem.
Syntax
JavaScript: image
Lua: image
Type
JavaScript: String
Lua: String
Read / Write
Accessible from IDE

Yes
l
BlackBerry
BlackBerry 10
J2ME
22.1.5 title
Specifies the title of the menuitem.
Syntax
JavaScript: title
Lua: title
Type
JavaScript: String
Lua: String
Read / Write
Accessible from IDE

Yes
l
BlackBerry
BlackBerry 10
J2ME
22.1.6 type
Specifies the type of the MenuItem as ok, back, or exit.
The execution engine will try to map the MenuItem to one of the available standard buttons on the platforms. If
no such capability is available on the platform, the execution engine adds the MenuItem as a custom item
(appends the item to the left key menu).
Syntax
JavaScript: type
Lua: type
Type
JavaScript: Number
Lua: Number
Read / Write
No
Accessible from IDE

Yes
l
BlackBerry 10
J2ME
22.2 Menuitem - Event

Menuitem widget has the following event associated with it:
l
onClick
22.2.1 onClick
An event callback is invoked by the platform when the user performs a click action on the Menuitem.
Signature
JavaScript: onClick
Lua: onclick
Read / Write
Accessible from IDE

Yes
l
BlackBerry
BlackBerry 10
J2ME
23. RadioButtonGroup
RadioButtonGroup is a widget that allows you to define a set of radio buttons and the user can choose one of it
as an option.
A radio button usually contains a small circle with text next to it. When you make a selection, a dot appears in
the circle to indicate your selection.
If you select one button in the set, the previously selected button is deselected. Hence only one of the options
is selected at a time.
You can use a RadioButtonGroup widget to choose one option from a set of mutually exclusive choices.
The data model for RadioButtonGroup widget is a key value pair. The key is hidden part of the model while
value is displayed to the user.
Note: To provide a multiple selection option, use the CheckBoxGroup Widget.
RadioButtonGroup provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKey
selectedKeyValue
skin
containerWeight
hExpand
itemOrientation
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Platform Specific
Properties
dropdownImage
focusTickedImage
focusUnTickedImage
groupCells
hoverSkin
placeholder
tickedImage
toolTip
untickedmage
viewType
viewConfig
Events
onSelection
preOnclickJS
postOnclickJS
Creating a RadioButtonGroup using a constructor: kony.ui.RadioButtonGroup

Creating RadioButtonGroup object instance:
var radiobutton1 = new kony.ui.RadioButtonGroup (basicConf, layoutConf, ps
pConf)
they are ignored.
JavaScript Example
//Defining properties for RadioButtonGroup
var radioBasic ={id:"RadioButton", isVisible:true, masterData:[["key1","va
lue1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin",focusSkin:"r
adFSkin"};
var radioLayout = {widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, paddin
g:[0,0,0,0], margin:[0,0,0,0], containerWeight:40, hExpand:false};
var radioPSP= {tickedImage:"tickdImg.png", untickedImage:"unTickdImg.png",
focusTickedImage:"tickdFImg.png", viewType:constants.RADIOGROUP_VIEW_TYPE_
TABLEVIEW};
//Creating the RadioButtonGroup
radioBtn = new kony.ui.RadioButtonGroup(radioBasic, radioLayout, radioPSP);
//Reading the id of the RadioButtonGroup
alert("RadioButtonGroup Id ::"+radioBtn.id);

The appearance of the RadioButtonGroup widget on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
Platform
Appearance
iPhone
Windows Phone
Adding a RadioButtonGroup Widget from IDE

The steps involved in adding a RadioButtonGroup widget are as follows:
1. From the IDE, drag and drop the RadioButtonGroup widget onto a form (occupies the complete
available width). Or, based on your requirements, you can choose to perform any of the following
options:
a. If you want to resize a RadioButtonGroup widget in the horizontal direction, place an
HBox on the form and drag and drop the RadioButtonGroup widget inside the HBox and
resize accordingly.
b. If you want to resize a RadioButtonGroup widget in the vertical direction, place an HBox
on the form and place a VBox inside the HBox; and drag and drop the RadioButtonGroup
widget inside the VBox and resize accordingly.
2. Specify the values to be displayed in the RadioButtonGroup widget from the IDE by using the
masterData property or from code by using the masterDataMap property.
3. (Optional) If you set the values from the code, you can use the selectedKey property to specify the
value to be displayed as selected.
4. (Optional) For programming purposes, if you want to find the value selected by a user, use the
selectedKeyValue property.
5. (Optional) The radio buttons in the RadioButtonGroup widget are aligned vertically by default. You can
choose to align them horizontally (not applicable on iPhone and iPad) by using the itemOrientation
property.
You can customize the appearance of the RadioButtonGroup widget by using the following properties:
l
The following are the important considerations for the RadioButtonGroup widget.
All Platforms
l
RadioButtonGroup widget is always a group widget.
Limit the number of choices in the widget. If you need to display several choices,
consider using a ComboBox widget.
Android
l
If you set the itemOrientation to horizontal, we suggest that you do not place more than
two items in the group, as there is a platform limitation.
If you place more than two items and the associated text with the items is large, there is
a possibility that the additional items will not fit in the screen width and will not be visible
on the screen.
BlackBerry and J2ME

l
For non-touch devices, you can specify focus images for ticked and unTicked states.
Windows all channels

l
The focusSkin property, background color is not be applied to the selected item, only font
color is be applied. For example, if you define a skin for focusSkin property as
background as red and font color as yellow, then only the font color is applied ignoring the
background color.
Mobile Web
l
Focus skin is not supported.
The onSelection event is not supported on the Basic version of Mobile Web as the Java
script is not supported on browsers of basic devices.
To achieve a functionality similar to an onSelection event, you must create an additional
button for the Basic version of the Mobile Web with an onclick event and attach an
onselection closure.
23.1 RadioButtonGroup - Basic Properties

The basic properties for RadioButtonGroup Widget are as follows:
l
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKey
selectedKeyValue
skin
23.1.1 focusSkin
Specifies the look and feel of the RadioButton when in focus.

2. Server side Mobile Web does not support this property, instead browser specific focus will be applied.
3. On SPA platform, focusSkin is applied in the vertical direction of the radio button.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with the focusSkin:"radFSki
n"
adFSkin"};
var radioPSP= {};
//Creating the RadiobuttonGroup.
//Reading the focusSkin of the RadioButtonGroup
alert("RadioButtonGroup focusSkin ::"+radioBtn.focusSkin);
Accessible from IDE

Yes
23.1.2 id
id is a unique identifier of RadioButton consisting of alpha numeric characters. Every RadioButton should
have a unique id within a Form.
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for RadioButtonGroup with the id:"RadioButton"
adFSkin"};
var radioPSP= {};
//Reading the id of the RadioButtonGroup
alert("RadioButtonGroup Id ::"+radioBtn.id);
Accessible from IDE

Yes
23.1.3 info

Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with the info property.
adFSkin"};
var radioPSP= {};
radioBtn.info = {key:"RADIO"};
//Reading the info of the RadioButtonGroup
alert("RadioButtonGroup info is ::"+radioBtn.info);
Accessible from IDE

No
23.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with isVisible:true
lue1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin", focusSkin:"
radFSkin"};
var radioPSP= {};
//Reading isVisible property of the RadioButtonGroup
alert("RadioButtonGroup isVisible ::"+radioBtn.isVisible);
Accessible from IDE

Yes
23.1.5 masterData
RadioButtonGroup window.
The following image illustrates the MasterData for RadioButtonGroup window:
Data when you Quick Preview. (For more information on Quick Preview, see the Kony Studio User Guide.
[
]
Syntax
Lua: masterdata
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with masterData:[["key1","v
alue1"],["key2","value2"],["key3","value3"]]
lue1", accessibilityConfigObject], ["key2","value2", accessibilityConfigOb
ject], ["key3","value3", accessibilityConfigObject]], skin:"radSkin", focu
sSkin:"radFSkin"};
var radioPSP= {};
//Reading the masterData of the RadioButtonGroup
alert("RadioButtonGroup masterData ::"+radioBtn.masterData);
Accessible from IDE

Yes
Specifies the set of values from which you can make a selection.You must specify a key and a value in a
master data map.
masterDataMap property to set data for the radio button.
[
[
{"mykey":"item2","myvalue":"Item Two","accessibilityConfig":acObjec
t},...,
],
"mykey",
"myvalue"
]
Syntax
Lua: masterdatamap
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with masterDataMap:[[{"myke
y":"key1","myvalue":"value1"},{"mykey":"key2","myvalue":"value2"}, {"mykey
":"key3", "myvalue":"value3"}],"mykey","myvalue"]
var radioBasic ={id:"RadioButton", isVisible:true, masterDataMap:[[{"mykey
":"key1","myvalue":"value1", "accessibilityConfig":acObject}, {"mykey":"ke
y2", "myvalue":"value2", "accessibilityConfig":acObject}, {"mykey":"key3",
"myvalue":"value3", "accessibilityConfig":acObject}],"mykey","myvalue"],
skin:"radSkin", focusSkin:"radFSkin"};
var radioPSP= {};
//Reading the masterDataMap of the RadioButtonGroup
alert("RadioButtonGroup masterDataMap ::"+radioBtn.masterDataMap);
Accessible from IDE

No
23.1.7 selectedKey
Represents the key that is shown as selected.
If you create a radio button with multiple values, you can choose to show a specific value as selected when
the radio button is rendered.
Syntax
Lua: selectedkey
Type
JavaScript: String
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with selectedKey:"key1"
radFSkin", selectedKey:"key1"};

var radioPSP= {};
Accessible from IDE

No
Syntax
Type
JavaScript: Array
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for RadioButtonGroup with selectedKey:"key1"
radFSkin", selectedKey:"key1"};
var radioPSP= {};
Accessible from IDE

No
23.1.9 skin
Specifies a background skin for RadioButton widget.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with the skin:"radSkin"
radFSkin"};
var radioPSP= {};
//Reading the skin of the RadioButtonGroup
alert("RadioButtonGroup skin::"+radioBtn.skin);
Accessible from IDE

Yes
23.2 RadioButtonGroup - Layout Properties

The layout properties for RadioButtonGroup Widget are as follows:
l
containerWeight
hExpand
itemOrientation
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with the containerWeight:40
lue1"], ["key2","value2"],["key3","value3"]], skin:"radSkin", focusSkin:"r
adFSkin"};
var radioPSP= {};
//Creating the RadioButtonGroup.
//Reading the containerWeight of the RadioButtonGroup

alert("RadioButtonGroup containerWeight ::"+radioBtn.containerWeight);
Accessible from IDE

No
23.2.2 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with hExpand:true
lue1"],["key2","value2"],["key3","value3"]], skin:"radSkin", focusSkin:"ra
dFSkin"};
g:[0,0,0,0], margin:[0,0,0,0], containerWeight:40, hExpand:true};
var radioPSP= {};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Desktop Web, and SPA.
Specifies the alignment of the widget as horizontal or vertical.
Default: RADIOGROUP_ITEM_ORIENTATION_VERTICAL
l
RADIOGROUP_ITEM_ORIENTATION_VERTICAL: The radio buttons are aligned in the vertical

direction.
RADIOGROUP_ITEM_ORIENTATION_HORIZONTAL: The radio buttons are aligned in the

horizontal direction.
The following image illustrates the vertical orientation:
The following image illustrates the horizontal orientation:
Note: On Android platform, if you set the itemOrientation to horizontal, due to platform limitations, we
suggest that you do not place more than two items in the group. If you place more than two items and the
associated text with the items is large, there is a possibility that the additional items will not fit in the screen
width and will not be visible on the screen.
Syntax
JavaScript: itemOrientation
Lua: itemorientation
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with itemOrientation:consta
nts.RADIOGROUP_ITEM_ORIENTATION_HORIZONTAL
radFSkin"};
g:[0,0,0,0], margin:[0,0,0,0], containerWeight:40, hExpand:false,itemOrien
tation:constants.RADIOGROUP_ITEM_ORIENTATION_HORIZONTAL};
var radioPSP= {};
Accessible from IDE

Yes
Available on all platforms except iPhone, iPad, and BlackBerry 10 platforms
23.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a RadioButtonGroup with the margin:[0,10,0,10]
var radioBasic ={id:"radioBtn", isVisible:true, masterData:[["key1","value
1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin", focusSkin:"rad
FSkin"};
var radioPSP= {};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RadioButtonGroup with margin in pixels.
FSkin"};
var radioLayout = {widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, margin
InPixel:true, margin:[0,10,0,10], containerWeight:40, hExpand:false};
var radioPSP= {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone Mango
Windows Kiosk
23.2.6 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a RadioButtonGroup with the padding:[10,0,10,0]
var radioBasic ={id:"RadioButton",isVisible:true, masterData:[["key1","val
ue1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin", focusSkin:"r
adFSkin"};
var radioPSP= {};
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RadioButtonGroup with padding in pixels.
FSkin"};
gInPixel:true, padding:[0,10,0,10], containerWeight:40, hExpand:false};
var radioPSP= {};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone Mango
Windows Kiosk
23.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RadioButtonGroup with vExpand:false.
radFSkin"};
g:[0,0,0,0], margin:[0,0,0,0], containerWeight:40, vExpand:false};
var radioPSP= {};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web platforms.
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a RadioButtonGroup with widget Alignment as TOP_
LEFT.
var radioBasic ={id:"RadioButton", isVisible:true, masterData:
[["key1","value1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin",

focusSkin:"radFSkin"};
var radioPSP= {};
Accessible from IDE

Yes
23.3 RadioButtonGroup - Platform Specific Properties

The platform specific properties for RadioButtonGroup Widget are as follows:
l
dropDownImage
focusTickedImage
focusUnTickedImage
groupCells
hoverSkin
placeholder
tickedImage
toolTip
unTickedImage
viewType
viewConfig
Note: For Windows Phone platform, you can specify the image from the RadioButton skin.
The following figure illustrates the default drop-down box indicator:
Syntax
Lua: dropdownimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup dropDownImage:"downarr.png"
radFSkin"};
var radioPSP= {dropDownImage:"downarr.png"};
Accessible from IDE

Yes
l
iPad
iPhone
Specifies the image to be displayed when you make a selection on non-touch devices.
Syntax
JavaScript: focusTickedImage
Lua: focustickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with focusTickedImage:"tick
dFImg.png"
var radioBasic ={id:"RadioButton",isVisible:true, masterData:[["key1","val

ue1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin", focusSkin:"r
adFSkin"};
focusTickedImage:"tickdFImg.png"};
Accessible from IDE

Yes
l
BlackBerry
J2ME
Specifies the image to be displayed when you clear a selection on non-touch devices.
Syntax
JavaScript: focusUnTickedImage
Lua: focusuntickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with focusUnTickedImage:"un
TickdFImg.png"
lue1"],["key2","value2"], ["key3","value3"]], skin:"radSkin", focusSkin:"r
adFSkin"};

focusTickedImage:"tickdFImg.png", focusUnTickedImage:"unTickdFImg.png"};
Accessible from IDE

Yes
l
BlackBerry
J2ME
23.3.4 groupCells
Specifies if all the rows in the RadioButton widget should be grouped using a rounded corner background and
border.
Default: false
Note: This property is applicable only when viewType is set as RADIOGROUP_VIEW_TYPE_
TABLEVIEW.
Syntax
Lua: groupcells
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with groupCells:true
var radioBasic ={id:"RadioButton",isVisible:true, masterData:
[["key1","value1"], ["key2","value2"], ["key3","value3"]], skin:"radSkin",

focusSkin:"radFSkin"};
g:[0,0,0,0], containerWeight:40, hExpand:false};
var radioPSP= {groupCells:true};
Accessible from IDE

Yes
l
iPad
iPhone
23.3.5 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
23.3.6 placeholder
RadioButton until the actual selection is made. If you do not specify the Placeholder text, the first option in the
list is shown as the selected value.
If placeholder is set then by default (without user selecting any option) selectedKey and selectedKeyValue
properties will return null/nil.
If placeholder is not set then by default the first entry should be shown as selected and selectedKey and
selectedKeyValue properties will return the first options key-value pair.
Note: This property is applicable only if the viewType is selected as RADIOGROUP_VIEW_TYPE_
LISTVIEW.
Syntax
Lua: placeholder
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup with placeholder:"Please se
lect the option"
adFSkin"};
var radioPSP= {placeholder:"Please select the option"};
//Reading the placeholder of the RadioButtonGroup

alert("RadioButtonGroup placeholder ::"+radioBtn.placeholder);
Accessible from IDE

Yes
l
iPad
iPhone
23.3.7 tickedImage
Note: If you specify a tickedImage, ensure that you also specify an unTickedImage. If not specified, the
Syntax
Lua: tickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with tickedImage:"tickdImg.
png"
adFSkin"};
var radioPSP= {tickedImage:"tickdImg.png"};
Accessible from IDE

Yes
l
iPad - applicable only when the viewType is selected as tableView.
iPhone - applicable only when the viewType is selected as tableView.
BlackBerry
Windows Tablet
Windows Kiosk
23.3.8 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a RadioButoonGroup with toolTip:sample text
var radioBasic={id:"radiobuttongroup1", isVisible:true, skin:"radioSkin",
focusSkin:"radioFSkin", text:"Click Here", toolTip:"sample text"};
var radioLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], h
var radioPSP={};
//Creating the RadioButoonGroup.
var radiobuttongroup1 = new kony.ui.RadioButoonGroup(radioBasic, radioLayo
ut, radioPSP);
Accessible from IDE

Yes
Syntax
Lua: untickedimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for RadioButtonGroup with untickedImage:"unTickd
Img.png"
radFSkin"};
var radioPSP= {unTickedImage:"unTickdImg.png"};
Accessible from IDE

Yes
l
iPad - applicable only when the viewType is selected as tableView.
iPhone - applicable only when the viewType is selected as tableView.
BlackBerry
Windows Tablet
Windows Kiosk
23.3.10 viewType
Specifies the view type of the RadioButtonGroup widget.
Default: RADIOGROUP_VIEW_TYPE_LISTVIEW
Following are the available options on various platforms:
l
RADIOGROUP_VIEW_TYPE_LISTVIEW
RADIOGROUP_VIEW_TYPE_TABLEVIEW
RADIOGROUP_VIEW_TYPE_TOGGLEVIEW
RADIOGROUP_VIEW_TYPE_ONSCREENWHEEL
Note: On iPhone platform, skin is not supported when the view type is set as RADIOGROUP_VIEW_
TYPE_TOGGLEVIEW and RADIOGROUP_VIEW_TYPE_ONSCREENWHEEL.
The following images illustrate the Views:
listView
tableView
toggleView
Plain
Bordered
Bar
onscreenwheel
The below image illustrates the nextprevtoolbar set to a RadioButtonGroup. The highlighted toolbar is
achieved by setting the Mode as onscreenwheel to the RadioButtonGroup and Input Accessory View
Type as nextprevtoolbar to the Form.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup viewType:constants.RADIOGRO
UP_VIEW_TYPE_TABLEVIEW
radFSkin"};
var radioPSP= {viewType:constants.RADIOGROUP_VIEW_TYPE_TABLEVIEW};
//Reading the viewType of the RadioButtonGroup

alert("RadioButtonGroup viewType ::"+radioBtn.viewType);
Accessible from IDE

Yes
l
iPad
iPhone
23.3.11 viewConfig
toggleViewConfig: The property to configure the properties of RADIOGROUP_VIEW_TYPE_
TOGGLEVIEW.
l
RADIOGROUP_TOGGLE_VIEW_STYLE_PLAIN
RADIOGROUP_TOGGLE_VIEW_STYLE_BORDERED
RADIOGROUP_TOGGLE_VIEW_STYLE_BAR
Syntax
Lua: viewconfig
Type
Lua: UserData
Read / Write
Accessible from IDE

No
l
iPad
iPhone
Specifies the background color for the wheel that is displayed when you click the RadioButton group. This
property is applicable only when you set the viewType as RADIOGROUP_VIEW_TYPE_
ONSCREENWHEEL.
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for RadioButtonGroup
radFSkin"};
var radioPSP= {viewType:constants.RADIOGROUP_VIEW_TYPE_ONSCREENWHEEL};

form.radioBtn.wheelBackgroundColor = "0000ff00";
Accessible from IDE

No
l
iPad
iPhone
23.4 RadioButtonGroup - Events

RadioButtonGroup has the following events associated with it:
l
onSelection
preOnclickJS
postOnclickJS
23.4.1 onSelection
Signature
Lua: onselection
Read / Write
JavaScript Example
//The below function is the call back function for onSelection event
function onSelectionCallBck(radio)
{
}
//Defining the properties for RadioButtonGroup onSelection:onSelectionCall
Bck
lue1"], ["key2","value2"], ["key3","value3"]], onSelection:onSelectionCall
Bck};
var radioPSP= {};
23.4.2 preOnclickJS
RadioButton is invoked. This is applicable only for Mobile Web channel. The function must exist in a
javascript file under project>module>js folder.
Note: This event should return true, to continue with execution of onSelection and postOnclickJS events.
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the call back function for preOnclickJS event
function preOnclickJSCallBck(radio)
{
}
//Defining the properties for RadioButtonGroup preOnclickJS:preOnclickJSCa

llBck
var radioBasic ={id:"RadioButton", isVisible:true,masterData:[["key1","val
ue1"], ["key2","value2"], ["key3","value3"]]};
var radioPSP= {preOnclickJS:preOnclickJSCallBck};
Accessible from IDE

Yes
RadioButton is invoked. This is applicable only for Mobile Web channel.The function must exist in a javascript
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the call back function for postOnclickJS event
function postOnclickJSCallBck(radio)
{
}
//Defining the properties for RadioButtonGroup postOnclickJS:postOnclickJS
CallBck
lue1"], ["key2","value2"], ["key3","value3"]]};
var radioPSP= {postOnclickJS:postOnclickJSCallBck};

Accessible from IDE

Yes
24. RichText
RichText widget is used to display non-editable and well formatted text on the Form. HTML formatting tags
are used in RichText widget to display text with styles (bold, underlined etc.), links, and images.
You can use a RichText widget to show a read-only view of a well formatted text and to display text with
different formatting styles.
For example, you can use the RichText widget in the "Contact Us" Form of an Application. You can use the
widget's text styles (bold, italics etc.) to display the contact information, URL's telephone numbers instead of
using multiple widgets like Label, Phone, and Link widgets on the Form.
RichText provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
and an Event.
Basic Properties
Layout Properties
id
info
isVisible
linkSkin
skin
text
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Platform Specific
Properties
hoverSkin
linkFocusSkin
superScriptSkin
telephoneLinkSkin
toolTip
wrapping
Event
onClick
preOnclickJS
postOnclickJS
Creating a RichText using a constructor: kony.ui.RichText

var RichText1 = new kony.ui.RichText(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//The below function is the callback function for onClick event of RichText
widget.
function onClickCalBck(richText)
{

}
//Defining properties for a RichText with onClick:onClickCalBck
var rTextBasic={id:"rText", skin:"rTextSkin", linkSkin:"lnkSkin", text:"Sa
mple text", isVisible:true, onClick:onClickCalBck};
var rTextLayout={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5],
paddingInPixel:true, marginInPixel:true, hExpand:true, vExpand:false};
var rTextPSP={};
//Creating the RichText.
var rText = new kony.ui.RichText(rTextBasic, rTextLayout, rTextPSP);

The appearance of the RichText widget on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
iPhone
Windows Phone
Adding a RichText Widget from IDE

The steps involved in adding a RichText widget are as follows:
1. From the IDE, drag and drop the RichText widget onto a Form (occupies the complete available width).
Or, based on your requirement, you can choose to perform any of the following options:
a. If you want to resize the RichText widget in the horizontal direction, place an HBox on the Form
and drag and drop the RichText widget inside the HBox and resize accordingly.
b. If you want to resize the RichText widget in the vertical direction, place an HBox on the Form
and place a VBox inside the HBox; and drag and drop the RichText widget inside the VBox and
resize accordingly.
2. Enter the text using HTML formatting tags for the RichText widget using the text property.
3. (Optional) Define an onClick event.
Supported HTML formatting tags
The intended use of Rich Text is to display well formatted text using the following HTML formatting tags:
Tags
Description
<b>Text </b>
Displays Text in Bold.
<i> Text </i>
Displays Text in italics.

Displays Text underlined.
<u> Text </u>
<a href=""> </a>
Note: On BlackBerry and J2ME platforms, if the text

contains multiple words, the individual words are
underlined and not the whole text.
This tag is used to display a link. It supports
optional href attribute.
This tag is used to display an image and supports src
attribute. The path for the image can be local or url based.
<img src="" > </img>

Note: Specify the absolute path of an image for
MobileWeb platforms.
<sub>Subscript</sub>
Displays text as
<sup>Superscript</sup>
Displays text as Superscript.
Subscript
Displays the text in the color specified. To display a red

colored text, enter the following:
<label style="color:#rgbhexformat">
</label>
<label style="color:#FF0000">This is
a red colored text</label>
<br/>
Inserts a line break.
<tel number=""></tel>
Displays a telephone number on Native

Applications.
Tags
<a href="tel:"></a>
Description
Displays a telephone number on Mobile Web
platforms.
Note: If you need to apply multiple formats on the same text, these tags can be nested. For example:
<b><i><u>BoldItalicAndUnderlined</u></i></b>.
You can customize the appearance of the RichText widget by using the following properties:
l
RichText widget has the following considerations:
l
All Platforms: If you specify a skin for the RichText widget, all the font level settings (color style, or
size etc.) is applied to the complete content in RichText widget. You can use the label style HTML
formatting tag to override the text color specified at the skin level.
In onClick event, the attribute does not respect anchor tags in rich client. It is respected only on
browser based platforms (Mobile Web, SPA etc).
For example, in the below code when we click on "Click here" link, javascript confirm function is not
invoked. Only in Mobile Web and SPA it is invoked.
<a href="#" onclick=confirm("Do you want to proceed")>Click here </a>
iPhone: <img> HTML formatting tag is not supported. While integrating custom fonts, the name of the
font file should match its PostScript name. You have to determine the PostScript name using some
tool (in Mac you can install the font to find the PostScript name) and make sure that you name the font
file as the <postscriptname>.ttf. For example, if the PostScript font file name is "DBOzoneXBoldItalic", then the font name during integration should be "DBOzoneX-BoldItalic.ttf".
BlackBerry and J2ME: If you use the <u> HTML formatting tag, and the text contains multiple words,
the individual words are underlined and not the whole text (spaces between the words are not
underlined).
24.1 RichText - Basic Properties

The basic properties for RichText Widget are as follows:
l
id
info
isVisible
linkSkin
skin
text
24.1.1 id
id is a unique identifier of RichText consisting of alpha numeric characters. Every RichText should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
//Defining properties for a RichText with id:"rText"
mple text", isVisible:true};
var rTextPSP={};
//Reading the id of RichText.
alert("RichText id::"+rText.id);
Accessible from IDE

Yes
24.1.2 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a RichText with info property.
var rTextPSP={};
rText.info = {key:"text of richtext"};
//Reading the info of RichText.
alert("RichText info is ::"+rText.info);
Accessible from IDE

No
24.1.3 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
//Defining properties for a RichText with isVisible:true.
var rTextBasic={id:"rText",skin:"rTextSkin",linkSkin:"lnkSkin",text:"Sample
text", isVisible:true};
var rTextPSP={};
//Reading the isVisible of RichText
alert("RichText isVisible::"+rText.isVisible);
Accessible from IDE

Yes
24.1.4 linkSkin
Specifies the skin that must be applied to the link in the RichText widget.
Default: Skin Defaults (link appears in blue font and is underlined)
Syntax
JavaScript: linkSkin
Lua: linkskin
Type
JavaScript: String
Lua: String
Read / Write
//Defining properties for a RichText with linkSkin:"lnkSkin".
var rTextPSP={};
//Reading the linkSkin of RichText.
alert("RichText linkSkin::"+rText.linkSkin);
Accessible from IDE

Yes
24.1.5 skin
Specifies the look and feel of the RichText when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
//Defining properties for a RichText with skin:"rTextSkin".
var rTextPSP={};
//Reading the skin of RichText
alert("RichText skin::"+rText.skin);
Accessible from IDE

Yes
24.1.6 text
Specifies a general or descriptive text for the RichText widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
//Defining properties for a RichText with text:"Sample text"

var rTextPSP={};
//Reading the text of RichText
alert("RichText text::"+rText.text);
Accessible from IDE

Yes
24.2 RichText - Layout Properties

The layout properties for RichText Widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Specifies the percentage of width that should allocated by its parent widget. The parent widget space is
weight except when placed in kony.ui.ScrollBox.
Syntax
Type
JavaScript: Number (less than 100)
Lua: Number (less than 100)
Read / Write
JavaScript Example
//Defining properties for a RichText with containerWeight:100
var rTextBasic={id:"rText",skin:"rTextSkin", linkSkin:"lnkSkin", text:"Sam
ple text", isVisible:true};
var rTextPSP={};
//Reading the containerWeight of RichText
alert("RichText containerWeight::"+rText.containerWeight);
Accessible from IDE

No
Specifies the alignment of the text on the RichText with respect to its boundaries. A default value
CONTENT_ALIGN_MIDDLE_LEFT is assigned for all platforms. To choose another alignment, click the
drop-down arrow and select the desired alignment. However, to change the default value on a particular
platform, select the button next to the drop-down and select respective platform and choose the value.
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the RichText.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the RichText.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the RichText.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the RichText.
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the RichText.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the RichText.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the RichText.

RichText.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the

RichText.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a RichText with contentAlignment:constants.CONTE
NT_ALIGN_CENTER
contentAlignment:constants.CONTENT_ALIGN_CENTER, hExpand:true, vExpand:fal
se};
var rTextPSP={};
Accessible from IDE

Yes
24.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RichText with hExpand:true
var rTextPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, Windows Kiosk, Desktop Web, and SPA.
24.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a RichText with margin:[5,5,5,5]
var rTextPSP={};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RichText with marginInPixel:true
var rTextPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
BlackBerry 10
24.2.6 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a RichText with padding:[5,5,5,5]
var rTextPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic), BlackBerry 10, and Widows 7 Kiosk
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RichText with paddingInPixel:true.
var rTextPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
24.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a RichText with vExpand:false
var rTextPSP={};
Accessible from IDE

Yes
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a RichText with widgetAlignment:constants.WIDGET_
ALIGN_TOP_LEFT.
widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, hExpand:true, vExpand:fal
se};
var rTextPSP={};
Accessible from IDE

Yes
24.3 RichText - Platform Specific Properties

The basic properties for RichText Widget are as follows:
l
hoverSkin
linkFocusSkin
superScriptSkin
telephoneLinkSkin
toolTip
wrapping
24.3.1 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
JavaScript Example
//Defining properties for a RichText with hoverSkin:"hskin"
var rTextLayout={containerWeight:100,padding:[5,5,5,5], margin:[5,5,5,5],
var rTextPSP={linkFocusSkin:"linkFocSkin", hoverSkin:"hskin"};
Accessible from IDE

Yes
Available on Windows Tablet platform
24.3.2 linkFocusSkin
Specifies the skin that must be applied to the link when focused.
Syntax
JavaScript: linkFocusSkin
Lua: linkfocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a RichText with linkFocusSkin:"linkFocSkin"
var rTextLayout={containerWeight:100,padding:[5,5,5,5], margin:[5,5,5,5],

var rTextPSP={linkFocusSkin:"linkFocSkin"};
Accessible from IDE

Yes
l
BlackBerry
J2ME
24.3.3 superScriptSkin
Specifies the skin to be applied to superscripts in the RichText widget.
Syntax
JavaScript: superScriptSkin
Lua: superscriptskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a RichText with superScriptSkin:"supSkin".
var rTextPSP={superScriptSkin:"supSkin"};
Accessible from IDE

Yes
l
BlackBerry
Windows Tablet
Windows Kiosk
24.3.4 telephoneLinkSkin
Specifies the skin to be applied to the telephone links in the RichText widget.
Syntax
JavaScript: telephoneLinkSkin
Lua: telephonelinkskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a RichText with telephoneLinkSkin:"telSkin".
var rTextPSP={telephoneLinkSkin:"telSkin"};
Accessible from IDE

Yes
Available on Windows Phone (Mango) and Windows Tablet platform.
24.3.5 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a RichTextwith toolTip:sample text
var rTextBasic={id:"richtext1", isVisible:true, skin:"rtextSkin", focusSki
n:"rtextFSkin", text:"Click Here", toolTip:"sample text"};
var rTextLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], h
var rTextPSP={};
var richtext1 = new kony.ui.RichText(rTextBasic, rTextLayout, rTextPSP);
Accessible from IDE

Yes
24.3.6 wrapping
When the content of the RichText reaches the boundaries, it starts wrapping. While wrapping two strategies
can be applied:
l
Word Wrapping: Wrap or clip the string only at word boundaries.
Character Wrapping: Wrap or clip the string at the closest character boundary.
Default: WIDGET_TEXT_WORD_WRAP
WIDGET_TEXT_WORD_WRAP: Specifies if the complete word must be moved to the next line when
you reach the right margin. This is the default wrapping property.
WIDGET_TEXT_CHAR_WRAP: Specifies if the characters in a word must be moved to the next line
when you reach the right margin.
The following image illustrates the character wrapping property:
Syntax
JavaScript: wrapping
Lua: wrapping
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining properties for a RichText with wrapping:constants.WIDGET_TEXT_W
ORD_WRAP
var rTextPSP={wrapping:constants.WIDGET_TEXT_WORD_WRAP};
Accessible from IDE

Yes
l
iPad
iPhone
24.4 RichText - Events

RichText widget has the following event associated with it:
l
onClick
preOnclickJS
postOnclickJS
24.4.1 onClick
An event callback is invoked by the platform when the user performs a click action on the portion of the text
only where a link is defined. If the link is not defined, then onClick event is not invoked.
Note: When the anchor tag is available and onClick event is not defined, the widget opens all anchor tags in
a device browser.
Signature
JavaScript: onClick(richtextid, linktext, attributes)
Lua: onclick(richtextid, linktext, attributes)
Input Parameters
self [widgetref] - Mandatory
Reference to the RichText widget that raised the event.
linktext [String] - Mandatory
Specifies the text of the link which you have touched or clicked.
attributes [JSObject] - Mandatory
Specifies the JSObject containing the attributes of the link. For example, the attribute can contain
href as a key and the url as the value.
Note: In onClick event , the attribute does not respect anchor tags in rich client. It is
respected only on browser based platforms (Mobile Web, SPA etc).
For example, in the below code when we click on "Click here" link, javascript confirm function
is not invoked. Only in Mobile Web and SPA it is invoked.
<a href="#" onclick=confirm("Do you want to proceed")>Click here </a>
Read / Write
JavaScript Example
//The below function is the callback function for onClick event of RichText
widget.
function onClickCalBck(rText, linktext, attributes)
{
}
//Defining properties for a RichText with onClick:onClickCalBck
var rTextPSP={};
Accessible from IDE

Yes
24.4.2 preOnclickJS
widget is invoked. This is applicable only for Mobile Web channel. The function must exist in a javascript file
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
function preOnclickJSCalBck(rText)
{
}
//Defining properties for a RichText with preOnclickJS:preOnclickJSCalBck.
var rTextPSP={preOnclickJS:preOnclickJSCalBck};
Accessible from IDE

Yes
is invoked. This is applicable only for Mobile Web channel.The function must exist in a javascript file under
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
function postOnclickJSCalBck(rText)
{
}
//Defining properties for a RichText with postOnclickJS:postOnclickJSCalBc
k.
var rTextPSP={postOnclickJS:postOnclickJSCalBck};
Accessible from IDE

Yes
25. Slider
Slider widget allows you to select a value from a defined range of values by moving the thumb (an indicator) in
a horizontal direction. The Slider widget consists of a seekbar (or track) and a thumb (a control that you can
slide). You can optionally choose to display a minimum value and a maximum value. When you drag the
thumb along the slider, the value or process is updated continuously and is displayed on the track (you must
define an event to achieve this behavior).
Note: The Slider widget is not supported on all Server side Mobile Web platforms.
The Slider widget provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Basic Properties
Layout Properties
focusThumbImage
id
info
isVisible
leftSkin
max
min
rightSkin
selectedValue
step
thumbImage
containerWeight
margin
marginInPixel
widgetAlignment
Platform Specific Properties Events

enableThumbTintColor
onSelection
maxLabel
maxLabelSkin
maxValueImage
minLabel
minLabelSkin
minValueImage
orientation
thickness
thumbTintColor
viewType
onSlide
Creating a Slider using a constructor: kony.ui.Slider

var slider = new kony.ui.Slider(basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//The following function is the callback function for onSelectCallback eve
nt
function onSelectCallBck(slider)
{
/*Write your logic here */
}
//Defining the properties for Slider with "onSelectCallback" event
var sliderBasic = {id:"slider", info:{key:"SLIDER"}, min:0, max:100, step:
1, isVisible:true, leftSkin:"lKin", rightSkin:"rSkin", thumbImage:"thumb.p
ng", focusThumbImage:"fThumb.png", selectedValue:50, onSelection:onSelectC
allBck}
var sliderLayout ={margin:[5,5,5,5], marginInPixel:true, widgetAlignment:c
onstants.WIDGET_ALIGN_CENTER, containerWeight:99};
var sliderPSP ={};
//Creating the Slider.
var slider = new kony.ui.Slider(sliderBasic, sliderLayout, sliderPSP);
//Reading onSelectCallback event of the Slider.
alert("Slider onSelectCallback is ::"+slider.onSelectCallback);

The appearance of the widget with the default properties inside an HBox is as follows:
Platform
Default Appearance
Android
BlackBerry
iPhone
Windows Phone
Adding a Slider Widget from IDE
The steps involved in adding a Slider widget are as follows:
1. From the IDE, drag and drop the Slider widget onto a form (occupies the complete available width).
You can also choose to place the Slider in an HBox and use the widgetAlignment property to specify
the slider alignment as top, center, or bottom.
2. (Optional) Specify the maximum and the minimum values that the Slider can select.
3. (Optional) Specify a thumbImage and a focusThumbImage.
4. (Optional) Specify a default selectedValue.

5. (Optional) Specify a step increment value.
6. (Optional) Specify the text or number to be displayed for the maximum and minimum values.
Note: The maximum and minimum values are not displayed on the slider by default. You must
specify the maxLabel and minLabel to display the same (not supported on iPhone).
7. (Optional) Specify the onSelection and onSlide events.
You can customize the appearance of the Slider widget by using the following platform specific properties:
l
leftSkin: Specifies the skin to be applied to the background of the slider on left side of the thumb image
of the seekbar.
rightSkin: Specifies the skin to be applied to the background of the slider on right side of the thumb
image of the seekbar.
minLabel: Specifies the text or number to be displayed for the minimum value of the slider.
maxLabel: Specifies the text or number to be displayed for the maximum value of the slider.
thickness: Specifies the thickness of the seekbar.
minLabelSkin: Specifies the skin for the minLabel property of the slider.
maxLabelSkin: Specifies the skin for the maxLabel property of the slider.
l
All platforms (except iPhone): The slider widget does not display the minimum and maximum values
unless the minLabel and maxLabel are specified.
iPhone: You cannot display the minimum and maximum values. You can use the minValueImage and
the maxValueImage to indicate the values.
25.1 Slider - Basic Configuration Properties

The basic properties for Slider widget are as follows:
l
focusThumbImage
id
info
isVisible
leftSkin
max
min
rightSkin
selectedValue
step
thumbImage
25.1.1 focusThumbImage
Specifies the image to indicate that there is focus on the thumb. You can select the image from the resources
folder.
Note: If you specify a focus thumb image, you must also ensure that you have specified an image for the
thumb image property.
Syntax
JavaScript: focusThumbImage
Lua: focusthumbimage
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Slider with the focusThumbImage:"fThumb.png".
var sliderBasic = {id:"slider", info:{key:"SLIDER"},min:0, max:100,step:1,
isVisible:true, leftSkin:"lKin", rightSkin:"rSkin", thumbImage:"thumb.png",
focusThumbImage:"fThumb.png", selectedValue:50};
var sliderPSP ={};
//Reading focusThumbImage of the Slider.
alert("Slider focusThumbImage is ::"+slider.focusThumbImage);
Accessible from IDE

Yes
25.1.2 id
A unique identifier of Slider consisting of alpha numeric characters. Every Slider should have a unique id
within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Slider with the id:"slider".
ng", focusThumbImage:"fThumb.png", selectedValue:50};
var sliderPSP ={};
//Reading id of the Slider.
alert("Slider id is ::"+slider.id);
Accessible from IDE

Yes
25.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Slider with the info property.
var sliderBasic = {id:"slider", min:0,max:100, step:1, isVisible:true, lef
tSkin:"lKin", rightSkin:"rSkin", thumbImage:"thumb.png", focusThumbImage:"
fThumb.png", selectedValue:50};
var sliderPSP ={};
slider.info = {key:"SLIDER"};
//Reading info of the Slider.
alert("Slider info is ::"+slider.info);
Accessible from IDE

No
25.1.4 isVisible
Default:true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Slider with isVisible:true.
var sliderBasic = {id:"slider",info:{key:"SLIDER"}, min:0,max:100, step:1,
var sliderPSP ={};
//Reading info of the Slider.
alert("Slider info is ::"+slider.info);
Accessible from IDE

Yes
25.1.5 leftSkin
Skin to be applied to the background of the slider on left side of the thumb image. Specifies the skin to be
applied to the selected part of the seekbar (skin is applied to the left side of the thumb icon).
If you want to apply a skin, select the desired skin from the available skins.
- On Android platform, if you specify only a Left Skin, you must ensure that you specify a skin with a
rounded corner. If you do not specify a skin with a rounded corner, the appearance of the selected and
progress part of the seekbar is not identical.
- On iPhone platform, only a skin with the Background Style as Image is allowed.
The following image illustrates a Slider with the skins applied:
Syntax
JavaScript: leftSkin
Lua: leftskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Slider with the leftSkin:"lKin".
var sliderBasic = {id:"slider",info:{key:"SLIDER"},min:0,max:100,step:1,is
Visible:true, leftSkin:"lKin", rightSkin:"rSkin",thumbImage:"thumb.png",fo
cusThumbImage:"fThumb.png", selectedValue:50};
var sliderPSP ={};

//Reading leftSkin of the Slider.
alert("Slider leftSkin is ::"+slider.leftSkin);
Accessible from IDE

Yes
25.1.6 max
Specifies the maximum value on the slider that you can select. It accepts a non-decimal value.
Note: The maximum value is not displayed on the Slider. To display the maximum value, you must specify
the maxLabel (not supported on iPhone).
Default: 100 (The default maximum value on the slider that you can select is hundred)
If you want to set a different maximum value, you can set any Number (the Number can be upto 4 bytes
(positive or negative)) as the maximum value.
Note: The maximum value must be greater than the minimum value.
Syntax
JavaScript: max
Lua: max
Type
JavaScript: Number (non-decimal value)
Lua: Number (non-decimal value)
Read / Write
JavaScript Example
//Defining the properties for Slider with max:100.
var sliderBasic = {id:"slider", info:{key:"SLIDER"},min:0, max:100, step:1
,isVisible:true, leftSkin:"lKin", rightSkin:"rSkin",
thumbImage:"thumb.png", focusThumbImage:"fThumb.png", selectedValue:50};

var sliderLayout ={margin:[5,5,5,5],marginInPixel:true,widgetAlignment:con
stants.WIDGET_ALIGN_CENTER,containerWeight:99};
var sliderPSP ={};
Accessible from IDE

Yes
25.1.7 min
Specifies the minimum value on the slider that you can select. It accepts a non-decimal value.
Note: The minimum value is not displayed on the Slider. To display the minimum value, you must specify
the minLabel (not supported on iPhone).
Default: 0 (The default minimum value on the slider that you can select is zero)
If you want to set a different minimum value, you can set any Number (the Number can be upto 4 bytes
(positive or negative)) as the minimum value.
Note: The minimum value must be less than the maximum value.
Syntax
JavaScript: min
Lua: min
Type
Lua: Number (non-decimal value)
Read / Write
JavaScript Example
//Defining the properties for Slider with min:0.
var sliderBasic = {id:"slider", info:{key:"SLIDER"},min:0, max:100, step:1,

var sliderPSP ={};
Accessible from IDE

Yes
25.1.8 rightSkin
Skin to be applied to the background of the slider on right side of the thumb image. Specifies the skin to be
applied to the progress part of the seekbar (skin is applied to the right side of the thumb icon).
If you want to apply a skin, select the desired skin from the available skins.
- On Android platform, if you specify only a Right Skin, you must ensure that you specify a skin with a
rounded corner. If you do not specify a skin with a rounded corner, the appearance of the selected and
progress part of the seekbar is not identical.
- On iPhone platform, only a skin with the Background Style as Image is allowed.
The following image illustrates a Slider with the skins applied:
Syntax
JavaScript: rightSkin
Lua: rightskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Slider with the rightSkin:"rSkin".
var sliderBasic = {id:"slider",info:{key:"SLIDER"},min:0, max:100,step:1,
var sliderPSP ={};
//Reading rightSkin of the Slider.
alert("Slider rightSkin is ::"+slider.rightSkin);
Accessible from IDE

Yes
25.1.9 selectedValue
Specifies the value that must be displayed as selected when rendered. If you specify the default selected
value, the thumb shows the specified value as the selected value when rendered.
You must be aware of the following scenarios for the slider:
Scenario1: Below is the calculation, if default value is not specified:
Default value = minimum value + (maximum value - minimum value)/2
The default value is the minimum value plus half the difference between the minimum and the
maximum value.
For example, if the minimum value is 0 and the maximum value is 100, the default value is 50.
Scenario2: Below is the calculation, if default value is specified:
If you specify a default value which is lesser than the minimum value, the minimum value is
taken as the default value.
If you specify a default value which is greater than the maximum value, the maximum value is
taken as the default value.
Syntax
JavaScript: selectedValue
Lua: selectedvalue
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read and Write )
JavaScript Example
//Defining the properties for Slider with the selectedValue:50.
var sliderBasic = {id:"slider", info:{key:"SLIDER"}, min:0,max:100, step:1,
isVisible:true, leftSkin:"lKin", rightSkin:"rSkin",thumbImage:"thumb.png",
var sliderPSP ={};
//Reading selectedValue of the Slider.
alert("Slider selectedValue is ::"+slider.selectedValue);
Accessible from IDE

Yes
25.1.10 step
Specifies the value by which the slider is increased or decreased between the allowed slider values. It
accepts a non-decimal value.
Default: 1 (the default step increment value of the slider is one)
If you want a different Step value, you can specify a value which is in between the difference of the maximum
and minimum values of the slider.
For example, if you set the minimum value to 40 and the maximum value to 45, the step value can be a
number between 1 and 5.
Note: If you specify a value which is not in between the difference of the maximum and minimum values of
the slider, the step increment value is reset to 1.
Syntax
JavaScript: step
Lua: step
Type
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Slider with step:1.
var sliderBasic = {id:"slider", info:{key:"SLIDER"},min:0, max:100, step:1,
var sliderPSP ={};
Accessible from IDE

Yes
25.1.11 thumbImage
Specifies the image to indicate the thumb. You can select the image from the resources folder.
The following image illustrates a Slider with a thumb image:
Syntax
JavaScript: thumbImage
Lua: thumbimage
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Slider with the thumbImage:"thumb.png"
var sliderBasic = {id:"slider",info:{key:"SLIDER"}, min:0, max:100, step:1,
var sliderPSP ={};
//Reading thumbImage of the Slider.
alert("Slider thumbImage is ::"+slider.thumbImage);
Accessible from IDE

Yes
25.2 Slider - Layout Properties

The layout properties for Slider widget are as follows:
containerWeight
margin
marginInPixel
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Slider with the containerWeight:70
var sliderBasic = {id:"slider",info:{key:"SLIDER"}, min:0, max:100, step:1,
var sliderPSP ={};
//Reading containerWeight of the Slider
alert("Slider containerWeight is ::"+slider.containerWeight);
Accessible from IDE

No
25.2.2 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Slider with the margin:[5,5,5,5]
var sliderBasic = {id:"slider", info:{key:"SLIDER"}, min:0, max:100,step:1,
var sliderPSP ={};
//Reading margin of the Slider
alert("Slider margin is ::"+slider.margin);
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Slider with the marginInPixel:true
var sliderPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Slider with the widgetAlignment:constants.WI
DGET_ALIGN_CENTER.
var sliderPSP ={};
Accessible from IDE

Yes
25.3 Slider - Platform Specific Properties

The platform specific properties for Slider widget are as follows:
l
enableThumbTintColor
maxLabel
maxLabelSkin
maxValueImage
minLabel
minLabelSkin
minValueImage
orientation
thickness
thumbTintColor
viewType
25.3.1 enableThumbTintColor
This property enables you to configure thumbTintColor property.
Syntax
JavaScript: thumbTintColor
Type
JavaScript: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Slider with thumbTintColor.
var sliderPSP ={thumbTintColor:RGB 255,0,0};
Accessible from IDE

Yes
l
iPhone
iPad
25.3.2 maxLabel
Specifies the text or number to be displayed for the maximum value of the slider. This text is displayed just
below the slider on the right.
Default: null/nil (No label is displayed)
The following image illustrates a Slider with the text "Maximum Value" in the maxLabel property:
Syntax
JavaScript: maxLabel
Lua: maxlabel
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Slider with maxLabel:"100".
var sliderPSP ={maxLabel:"100"};
Accessible from IDE

Yes
l
Windows Phone(Mango)
Windows Kiosk
SPA (iPhone/Android/BlackBerryWindows NTH)
25.3.3 maxLabelSkin
Specifies the skin (font color or style) for the maxLabel property of the slider.
Default: null/nil (No skin is applied to the maxLabel)
Note: For the Max Label Skin, only the changes made under the Font tab of the skin property is applied.
Rest of the changes are ignored. For example, if you specify a skin for the Slider widget and define a
background image and font color, only the font color will be applied and not the background image.
The following image illustrates the Max Label with a defined skin:
Syntax
JavaScript: maxLabelSkin
Lua: maxlabelskin
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Slider with maxLabelSkin:{color:"FF224400"}.
var sliderPSP ={maxLabelSkin:{color:"FF224400"}};
Accessible from IDE

Yes
l
Windows Kiosk
25.3.4 maxValueImage
Specifies the image for the maximum value of the slider. You can select the image from the resources folder.
Syntax
JavaScript: maxValueImage
Lua: maxvalueimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Slider with maxValueImage:"maxImg.png".
1, isVisible:true, leftSkin:"lKin", rightSkin:"rSkin",
thumbImage:"thumb.png", focusThumbImage:"fThumb.png", selectedValue:50};

var sliderPSP ={maxValueImage:"maxImg.png"};
Accessible from IDE

Yes
l
iPhone
iPad
25.3.5 minLabel
Specifies the text or number to be displayed for the minimum value of the slider. This text is displayed just
below the slider on the left.
Default: null/nil (No label is displayed)
The following image illustrates a Slider with the text "Minimum Value" in the minLabel property:
Syntax
JavaScript: minLabel
Lua: minlabel
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Slider with minLabel:"0"
var sliderPSP ={minLabel:"0"};
Accessible from IDE

Yes
l
Windows Kiosk
25.3.6 minLabelSkin
Specifies the skin for the minLabel property of the slider.
Default: null/nil (No skin is applied to the minLabel)
Note: For the Min Label Skin, only the changes made under the Font tab of the skin property is applied. Rest
of the changes are ignored. For example, if you specify a skin for the Slider widget and define a background
image and font color, only the font color will be applied and not the background image.
The following image illustrates the minLabel with a defined skin:
Syntax
JavaScript: minLabelSkin
Lua: minlabelskin
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Slider with minLabelSkin:{color:"FF224400"}.
var sliderPSP ={minLabelSkin:{color:"FF224400"}};
Accessible from IDE

Yes
l
Windows Tablet
Windows Kiosk
25.3.7 minValueImage
Specifies the image for the minimum value of the slider. You can select the image from the resources folder.
Syntax
JavaScript: minValueImage
Lua: minvalueimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Slider with minValueImage:"mImg.png".
var sliderPSP ={minValueImage:"mImg.png"};
Accessible from IDE

Yes
l
iPhone
iPad
25.3.8 orientation
Specifies the orientation of the slider widget. You can select the orientation as horizontal or vertical.
Default: SLIDER_HORIZONTAL_ORIENTATION
l
SLIDER_HORIZONTAL_ORIENTATION: Specifies the orientation of the slider widget in horizontal

direction.
SLIDER_VERTICAL_ORIENTATION: Specifies the orientation of the slider widget in vertical

direction.
Syntax
Type
JavaScript: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Slider with orientation:constants.SLIDER_HOR
IZONTAL_ORIENTATION.
var sliderPSP ={orientation:constants.SLIDER_HORIZONTAL_ORIENTATION};
Accessible from IDE

Yes
25.3.9 thickness
Specifies the thickness of the seekbar. You can specify a thickness between 1 and 25.
If you do not specify the thickness (the thickness field is blank), the device specific thickness is assigned.
Note: On Android platform, the thickness property is applicable only if a leftSkin or rightSkin is applied. If
you do not specify a left or a right skin, Android specific seekbar thickness is assigned.
Syntax
JavaScript: thickness
Lua: thickness
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Slider with thickness:3.
var sliderPSP ={thickness:3};
Accessible from IDE

Yes
l
BlackBerry
Windows Kiosk
Windows Phone
Windows Tablet
25.3.10 thumbOffset
If the thumb image is a valid drawable (not null), by default half its width is used as the new thumb offset. If the
thumb image drawable is symmetric, thumb offset is set such that the thumb image hangs halfway off either
edge of the slider widget. To avoid half hanging of the thumb image, set the thumbOffset value to zero.
Syntax
JavaScript: thumbOffset
Lua: thumboffset
Type
JavaScript: Number
Lua: Number
Read / Write
Write only
JavaScript Example
//Defining the properties for Slider with thumbOffset:0.
var sliderPSP ={thickness:3};
//Defining the properties for Slider with thumbOffset:0.
FormID.slider.thumbOffset = 0;
Accessible from IDE

No
Available on Android/Android Tablet platforms only
25.3.11 thumbTintColor
Specifies the color for thumb tint.
Note: When both the thumbImage and thumbTintColor are configured, the property thumbTintColor takes
precedence over thumbImage.
Syntax
JavaScript: thumbTintColor
Type
JavaScript: String
Read / Write
JavaScript Example
//Defining the properties for Slider with thumbTintColor.
var sliderPSP ={thumbTintColor:RGB 255,0,0};
Accessible from IDE

Yes
l
iPhone
iPad
25.3.12 viewType
Specifies the view type of the Slider widget.
Default: SLIDER_VIEW_TYPE_DEFAULT
Following are the available options platforms:
l
SLIDER_VIEW_TYPE_DEFAULT: Specifies the default slider view. An indicator is displayed on the

slider widget.
SLIDER_VIEW_TYPE_PROGRESS : Specifies the progress view of the slider. The indicator is not
displayed. It represents the progress of an activity that is being completed in percentage. For Desktop
Web platform, the property selectedValue is not available to set through IDE, but it can be set through
code.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for Slider with viewType:constants.SLIDER_VIEW_T
YPE_DEFAULT.
var sliderPSP ={viewType:constants.SLIDER_VIEW_TYPE_DEFAULT};
Accessible from IDE

Yes
25.4 Slider - Events

The Slider widget has the following event associated with it:
l
onSelection
onSlide
25.4.1 onSelection
An event callback that is invoked by the platform when the user makes a selection.
For touch based devices, this event is triggered when you stop sliding the thumb icon.
For non touch based devices, this event is triggered when the left or right key is released.
Syntax
Lua: onselection
Read / Write
JavaScript Example
//The following function is the callback function for onSelectCallback eve
nt
function onSelectCallBck(slider)
{
}
//Defining the properties for Slider with "onSelectCallback" event
ng", focusThumbImage:"fThumb.png", selectedValue:50, onSelection:onSelectC
allBck}
var sliderPSP ={};
//Reading onSelectCallback event of the Slider.
alert("Slider onSelectCallback is ::"+slider.onSelectCallback);
Accessible from IDE

Yes
25.4.2 onSlide
An event callback that is invoked by the platform when there is a change in the default selected value.
For touch based devices, this event is triggered when you stop sliding the thumb icon.
For non touch based devices, this event is triggered when the left or right key is released.
Syntax
JavaScript: onSlide
Lua: onslide
Read / Write
JavaScript Example
//The following function is the callback function for onSliderCallback eve
nt
function onSliderCallBck(slider)
{
}
//Defining the properties for Slider with onSliderCallback event
ng", focusThumbImage:"fThumb.png", selectedValue:50, onSlide:onSliderCallB
ck};
var sliderPSP ={};
//Reading onSliderCallback event of the Slider.
alert("Slider onSliderCallback is ::"+slider.onSliderCallback);
Accessible from IDE

Yes
26. TextArea
TextArea is used to provide an editable field for the user to enter text which spans over multiple lines .
You can use the TextArea widget to provide a field where a user can enter multiple lines of text.
For example, in the "Feedback" section of an Application, you can place a TextArea widget and instruct the
users to enter their comments.
Note: The TextArea widget inherits all the properties of the TextBox widget.
TextArea provides you with an option to set Basic Properties, Layout Properties, and Platform Specific
Properties.
Basic Properties
Layout Properties
autoCapitalize
focusSkin
id
info
isVisible
keyBoardStyle
maxTextLength
numberOfVisibleLines
placeholder
secureTextEntry
skin
text
textInputmode
contentAlignment
containerWeight
hExpand
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Events
Deprecated
onDone
onBeginEditing
onEndEditing
onTextChange
editable
No of Rows
Platform Specific
Properties
autoCorrect
blockedUISkin
closeButtonText
keyboardActionLabel
pasteboardType
placeholderSkin
showCloseButton
toolTip
Creating a TextArea using a constructor: kony.ui.TextArea2

var setTextArea1 = new kony.ui.TextArea2 (basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//Defining properties for TextArea.

var tAreaBasic = {id:"txtArea", skin:"txtSkin", focusSkin:"txtFSkin", text
:"Text", maxTextLength:20, isVisible:true, secureTextEntry:true, placehold
er:"enter text"};
var tAreaLayout = {padding:[5,5,5,5], margin:[5,5,5,5], containerWeight:10
0, hExpand:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var tAreaPSP ={keyboardActionLabel:constants.TEXTAREA_KEYBOARD_LABEL_SEND,
pasteboardType:constants.TEXTAREA_PASTE_BOARD_TYPE_SYSTEM_LEVEL, showProgr
essIndicator:true};
//Creating the TextArea.
var txtArea = new kony.ui.TextArea2(tAreaBasic, tAreaLayout, tAreaPSP);
//Reading the widgetAlignment of the TextArea.
alert("TextArea widgetAlignment ::"+txtArea.widgetAlignment);

The appearance of the TextArea widget with a specified text on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
iPhone
Platform
Appearance
Windows Phone
Adding a TextArea Widget from IDE

The steps involved in adding a TextArea widget are as follows:
1. From the IDE, drag and drop the TextArea widget onto a Form (occupies the complete available width).
a. If you want to resize the TextArea widget in the horizontal direction, place an HBox on the Form
and drag and drop the TextArea widget inside the HBox and resize accordingly.
b. If you want to resize the TextArea widget in the vertical direction, place an HBox on the Form
and place a VBox inside the HBox; and drag and drop the TextArea widget inside the VBox and
resize accordingly.
2. Enter text for the TextArea widget using the text property.
Note: When the widget is rendered, the text is editable by the user.
3. (Optional) Specify the maximum number of characters that a user can enter into the TextArea widget
using the maxTextLength property.
4. (Optional) For Windows and Symbian platforms, specify an onDone event.
You can customize the appearance of the TextArea widget by using the following properties:
l
The following are the important considerations for the TextArea widget:
Editing on devices with small form factor takes place in a new screen.
Editing on devices with medium or large form factor takes place in the same screen.
In Mobile web, some browsers by default enable a scroll bar (vertical/horizontal) for the text area, even
if the number of lines is less than numberOfVisibleLines. The Mobile Web platform has no control if the
scroll bar should appear or not.
For Desktop Web platform, transparency (border/font) is not support in Internet Explorer 7 and Internet
Explorer 8.
For Desktop Web platform, rounded corner skins do not support in Internet Explorer 7 and Internet
Explorer 8.
26.1 TextArea - Basic Properties

The basic properties for TextArea Widget are as follows:
l
autoCapitalize
focusSkin
id
info
isVisible
keyBoardStyle
maxTextLength
placeholder
secureTextEntry
skin
text
textInputmode
Specifies the character capitalization behavior.
Default: TEXTAREA_AUTO_CAPITALIZE_NONE
Note: For Desktop Web platform, autoCapitalize property is not supported, use the events onBeginEditing,
onEndEditing, onKeyUp, and onKeyDown, and onDone as necessary.
l
TEXTAREA_AUTO_CAPITALIZE_NONE: If you leave this option unchanged, no action takes place

on the input string.
Example : This is sample text.
TEXTAREA_AUTO_CAPITALIZE_WORDS: This option changes the first character of all the words
to uppercase. (Not supported on Server side Mobile Web and BlackBerry platforms)
Example : This Is Sample Text.
TEXTAREA_AUTO_CAPITALIZE_SENTENCES: This option changes the first character of all the

sentences to uppercase. (Not supported on BlackBerry platform)
TEXTAREA_AUTO_CAPITALIZE_ALL: This option changes all the characters to uppercase. (Not

supported on Mobile Web)
Example : THIS IS SAMPLE TEXT.
Syntax
JavaScript: autoCapitalize
Lua: autocapitalize
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a TextArea with the autoCapitalize:constants.TEX
TAREA_AUTO_CAPITALIZE_ALL
var tAreaBasic = {id:"txtArea", text:"Text", isVisible:true, secureTextEnt
ry:true, autoCapitalize:constants.TEXTAREA_AUTO_CAPITALIZE_ALL};
var tAreaPSP ={};
var txtArea = new kony.ui.TextArea2 (tAreaBasic, tAreaLayout, tAreaPSP);
//Reading the autoCapitalize of the TextArea
alert("TextArea autoCapitalize ::"+txtArea.autoCapitalize);
Accessible from IDE

Yes
Available on all platforms except SPA, Desktop Web, and on all Server side Mobile Web platforms
26.1.2 focusSkin

Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a TextArea with the focusSkin:"txtFSkin".
:"Text", maxTextLength:20,isVisible:true, secureTextEntry:true};
var tAreaPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, BlackBerry 10, and SPA (Android) platforms
26.1.3 id
A unique identifier of TextArea consisting of alpha numeric characters. Every TextArea should have a unique
id within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining properties for a TextArea with the id:"txtArea"
:"Text", maxTextLength:20, isVisible:true, secureTextEntry:true};
var tAreaPSP ={};
//Reading the id of the TextArea
alert("TextArea Id ::"+txtArea.id);
Accessible from IDE

Yes
26.1.4 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining properties for a TextArea with the info property.
var tAreaPSP ={};
txtArea.info = {key:"text of textarea"};
//Reading the info of the TextArea
alert("TextArea info is ::"+txtArea.info);
Accessible from IDE

No
26.1.5 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining properties for a TextArea with the isVisible:true.
var tAreaBasic = {id:"txtArea", skin:"txtSkin", focusSkin:"txtFSkin",text:
"Text", maxTextLength:20, isVisible:true, secureTextEntry:true};
var tAreaPSP ={};
//Reading the isVisible of the TextArea
alert("TextArea isVisible ::"+txtArea.isVisible);
Accessible from IDE

Yes
When you interact with a TextBox widget, a keyboard is displayed. You can use this property to select the
type of keyboard that you want to display.
Note: Keys on the keyboard style may vary from platform to platform.
Note: On Desktop Web platform, KeyBoardStyle property is not supported, use the events onBeginEditing,
Note: The option TEXTAREA_KEY_BOARD_STYLE_DECIMAL is not supported in iPad device natively.

Note: On BlackBerry 10 platform, only the option TEXTAREA_INPUT_MODE_ANY is supported. Click
here for BlackBerry 10 supported keyboard styles.
The following are the available keyboard types when you select textInputMode as TEXTAREA_INPUT_
MODE_ANY.
l
TEXTAREA_KEY_BOARD_STYLE_DEFAULT: Specifies the default keyboard in respective

platforms. Supported in BlackBerry 10 platform.
TEXTAREA_KEY_BOARD_STYLE_EMAIL: Specifies the keyboard to enter email address.

Supported in BlackBerry 10 platform.
TEXTAREA_KEY_BOARD_STYLE_URL: Specifies the keyboard to enter URL address.
TEXTAREA_KEY_BOARD_STYLE_CHAT: Specifies the keyboard type which is helpful for chatting.

The following are the available keyboard types when you select textInputMode as TEXTAREA_INPUT_
MODE_NUMERIC.
TEXTAREA_KEY_BOARD_STYLE_DEFAULT: Specifies the default numeric keyboard.
TEXTAREA_KEY_BOARD_STYLE_DECIMAL: Specifies the keyboard to enter decimals.
TEXTAREA_KEY_BOARD_STYLE_NUMBER_PAD: Specifies the keyboard to enter numbers. (Not

supported in Windows Phone platform)
TEXTAREA_KEY_BOARD_STYLE_PHONE_PAD: Specifies the keyboard to enter phone numbers.

(Not supported in Windows platform)
TEXTAREA_KEY_BOARD_STYLE_SIGNED_NUMBER: Specifies the keyboard to enter negative

numbers(for example -345). This option is applicable to Android platform only.
TEXTAREA_KEY_BOARD_STYLE_SIGNED_DECIMAL_NUMBER: Specifies the keyboard to

enter negative decimal numbers (for example -345.87). This option is applicable to Android platform
only.
Syntax
JavaScript: keyBoardStyle
Lua: keyboardstyle
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a TextArea with the keyBoardStyle to accept URL
address.
var tAreaBasic = {id:"txtArea", text:"Text", maxTextLength:20, isVisible:t
rue, secureTextEntry:true, keyBoardStyle:constants.TEXTAREA_KEY_BOARD_STYL
E_URL};
var tAreaPSP ={};
//Reading the keyBoardStyle of the TextArea
alert("TextArea keyBoardStyle ::"+txtArea.keyBoardStyle);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, SPA, Windows Kiosk, and Desktop Web
platforms
Specifies the maximum number of characters that the text field can accept.
Default: empty
If you specify a number for this property, the number of input characters cannot exceed the specified number.
Syntax
JavaScript: maxTextLength
Lua: maxTextLength
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a TextArea with the maxTextLength:20.
var tAreaBasic = {id:"txtArea",skin:"txtSkin", focusSkin:"txtFSkin", text:
"Text", maxTextLength:20, isVisible:true, secureTextEntry:true};
var tAreaPSP ={};
//Reading the maxTextLength of the TextArea
alert("TextArea maxTextLength ::"+txtArea.maxTextLength);
Accessible from IDE

Yes
26.1.8 numberOfVisibleLines
Number of lines to be displayed at a given time in the view port of the TextArea. This essentially decides the
height of the text area.
Syntax
JavaScript: numberOfVisibleLines
Lua: numberofvisiblelines
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a TextArea with numberOfVisibleLines:5
var tAreaBasic = {id:"txtArea", text:"Text", maxTextLength:20,isVisible:tr
ue, secureTextEntry:true, numberOfVisibleLines:5};
var tAreaPSP ={};
//Reading the numberOfVisibleLines of the TextArea
alert("TextArea numberOfVisibleLines ::"+txtArea.numberOfVisibleLines);
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic) and Windows Phone (Mango) platforms.
26.1.9 placeholder
The placeholder attribute specifies a short hint that describes the expected value of an input field (example, a
sample value or a short description of the expected format). The hint is displayed in the input field when it is
empty, and disappears when the field gets focus.
For example, for the Username field, you can enter the placeholder text as Enter User ID or Email Address.
The user then clicks on the TextArea widget and enters the Username.
- If you specify text both in the text property and the placeholder property, the text entered in the text
property is displayed when rendered. If the user deletes the text, the placeholder text is displayed.
- If you programmatically set an empty string for the text property, the placeholder text is displayed.
Syntax
Lua: placeholder
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a TextArea with placeholder:"Enter text".
er:"Enter text"};
var tAreaLayout = {padding:[5,5,5,5], margin:[5,5,5,5],containerWeight:100,
hExpand:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var tAreaPSP ={};
//Reading the placeholder of the TextArea
alert("TextArea placeholder ::"+txtArea.placeholder);
Note: You can set the placeholder text from the code only on iPhone, Android, BlackBerry, Windows
Phone, J2ME, Symbian and Mobile Web Advanced platforms.
Accessible from IDE

Yes
Available on all platforms except on Server side Mobile Web (Basic and BJS)
Specifies whether the text entered by the user will be secured using a mask character, such as asterisk or
dot. This is typically set to true for a password field.
Default: false
If set to true, the text in the TextArea will be masked.
If set to false, the text in the TextArea will be displayed as clear text.
Syntax
JavaScript: secureTextEntry
Lua: securetextentry
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a TextArea with the secureTextEntry:true.
var tAreaLayout = {padding:[5,5,5,5],margin:[5,5,5,5], containerWeight:100,
var tAreaPSP ={};
Accessible from IDE

Yes
Available on all platforms except BlackBerry 10, Desktop Web, and on all Server side Mobile Web
platforms
26.1.11 skin
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a TextArea with the skin:"txtSkin"
:"Text", maxTextLength:20, isVisible:true,secureTextEntry:true};
var tAreaPSP ={};
//Reading the skin of the TextArea
alert("TextArea skin ::"+txtArea.skin);
Accessible from IDE

Yes
26.1.12 text
Specifies a general or descriptive text for the TextArea widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining properties for a TextArea with the text:"Text"
var tAreaPSP ={};

//Reading the text of the TextArea
alert("TextArea text ::"+txtArea.text);
Accessible from IDE

Yes
Specifies the type of input characters that a user can enter into the TextArea widget. You can use this
property to restrict the input characters to only numbers or a combination of alphabets, numbers, and special
characters.
Default: TEXTAREA_INPUT_MODE_ANY
l
TEXTAREA_INPUT_MODE_ANY: Specifies that the input characters can be letters, numbers,

special characters, or a combination of all three of them. Only this option is supported in BlackBerry 10
platform.
TEXTAREA_INPUT_MODE_NUMERIC: Specifies that the input characters must be numbers only.

This option is not supported on Server side Mobile Web and Desktop Web platforms.
Note: The values of keyBoardStyle property are dependent on these modes.

Note: In Android platform, multiple lines for a textbox is displayed only when textInputMode property is set
to TEXTAREA_INPUT_MODE_ANY. When the option is set to TEXTAREA_INPUT_MODE_NUMERIC
the text is shown as single line.
Syntax
JavaScript: textInputMode
Lua: textinputmode
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a TextArea with the textInputMode:constants.TEXT
AREA_INPUT_MODE_NUMERIC
var tAreaBasic = {id:"txtArea", text:"Text", maxTextLength:20, isVisible:t
rue, secureTextEntry:true, textInputMode:constants.TEXTAREA_INPUT_MODE_NUM
ERIC};
var tAreaPSP ={};
//Reading the textInputMode of the TextArea
alert("TextArea textInputMode ::"+txtArea.textInputMode);
Accessible from IDE

Yes
Available on all platforms except SPA, BlackBerry, and on all Server side Mobile Web platforms
26.2 TextArea - Layout Properties

The layout properties for TextArea Widget are as follows:
l
contentAlignment
containerWeight
hExpand
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Specifies the alignment of the text and place holder text for a TextArea with respect to its boundaries. The
default value is CONTENT_ALIGN_MIDDLE_LEFT for all platforms. To choose another alignment, click the
drop-down arrow adjacent to the property from the properties window and select the alignment option.
Default: constants.CONTENT_ALIGN_MIDDLE_LEFT
l
constants.CONTENT_ALIGN_TOP_LEFT: Specifies the text should align at top left corner of the
TextArea.
constants.CONTENT_ALIGN_TOP_RIGHT: Specifies the text should align at top right of the

TextArea.
constants.CONTENT_ALIGN_TOP_CENTER: Specifies the text should align at top center of the

TextArea.
constants.CONTENT_ALIGN_MIDDLE_LEFT: Specifies the text should align from left of the

TextArea.
constants.CONTENT_ALIGN_CENTER: Specifies the test should align at the center of the TextArea.
constants.CONTENT_ALIGN_MIDDLE_RIGHT: Specifies the text should align from right of the

TextArea.
constants.CONTENT_ALIGN_BOTTOM_LEFT: Specifies the text should align at bottom left of the

TextArea.
constants.CONTENT_ALIGN_BOTTOM_CENTER: Specifies the text should align at bottom center

of the TextArea.
constants.CONTENT_ALIGN_BOTTOM_RIGHT: Specifies the text should align at bottom right of the

TextArea.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a TextArea with contentAlignment:constants.C
ONTENT_ALIGN_MIDDLE_LEFT.
er:"enter text"};
0, contentAlignment:constants.CONTENT_ALIGN_MIDDLE_LEFT, widgetAlignment:c
onstants.WIDGET_ALIGN_TOP_LEFT};
var tAreaPSP ={};
Accessible from IDE

No
Available on all platforms except on all Server side Mobile Web
Specifies percentage of width that should be allocated by its parent widget. The parent widget space is
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a TextArea with the containerWeight:100.
er:"enter text"};
var tAreaLayout = {padding:[5,5,5,5], margin:[5,5,5,5],
containerWeight:100, hExpand:true, widgetAlignment:constants.WIDGET_ALIGN_
TOP_LEFT};
var tAreaPSP ={};
Accessible from IDE

No
26.2.3 hExpand
Default: true
contents width, padding, and margin.
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a TextArea with the hExpand:true.
er:"enter text"};
var tAreaPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and SPA
26.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a TextArea with the margin:[5,5,5,5]
er:"enter text"};
var tAreaPSP ={};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a TextArea with margin in pixels.
er:"enter text"};
0, marginInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var tAreaPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
26.2.6 padding
Note: In DesktopWeb platform, Firefox browser does not support percentage (%) based padding, while
other browsers does support.
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a TextArea with the padding:[5,5,5,5].
er:"enter text"};
var tAreaPSP ={};
Accessible from IDE

Yes
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a TextArea with the padding in pixels.
er:"enter text"};
paddingInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var tAreaPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
l
Note: The alignment property is applicable only if the widget size is lesser than the allocated size.
On Windows Platform TextArea does not support horizontal alignment attributes. By default, the TextArea is
aligned to the center of the horizontal space.
The following image illustrates the widget alignment property:
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining properties for a TextArea with the widget Alignment as TOP_LEFT.
er:"enter text"};
var tAreaPSP ={};
Accessible from IDE

Yes
26.3 TextArea - Platform Specific Properties

The platform specific properties for TextArea Widget are as follows:
l
autoCorrect
blockedUISkin
closeButtonText
hoverSkin
keyboardActionLabel
pasteboardType
placeholderSkin
showCloseButton
toolTip
26.3.1 autoCorrect
This property determines whether auto-correction is enabled or disabled during typing. With auto-correction
enabled, the text object tracks unknown words and suggests a more suitable replacement candidate to the
user, replacing the typed text automatically unless the user explicitly overrides the action.
Default: false
If set to true, the auto correction option is enabled.
If set to false, the auto correction option is not enabled.
Syntax
JavaScript: autoCorrect
Lua: autocorrect
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a TextArea with autoCorrect:true.
var tAreaBasic = {id:"txtArea", skin:"txtSkin", focusSkin:"txtFSkin",
text:"Text", maxTextLength:20, isVisible:true};

var tAreaPSP ={autoCorrect:true};
Accessible from IDE

Yes
l
iPhone
SPA (iPhone/Android/BlackBerry)
Desktop Web
call) is completed.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a TextArea with blockedUISkin:"blockedUISki
n".
:"Text", maxTextLength:20, isVisible:true};
var tAreaPSP ={blockedUISkin:"blockedUISkin"};
//Reading the blockedUISkin of the TextArea.
alert("TextArea blockedUISkin ::"+txtArea.blockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
Server side Mobile Web (Advanced)
Specifies the text to replace the "Done" button that appears in the Keypad (opens when you select a textbox).
Default: Done (The text on the close button is Done)
If you want to change the text for the close button, enter the text of your choice. For example, if you want to
change the text from Done to Go, enter Go in the property field. The following image illustrates the Keypad
when the text in the property is changed to Go:
Syntax
JavaScript: closeButtonText
Lua: closebuttontext
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for a TextArea with closeButtonText:"done"
var tAreaPSP ={closeButtonText:"Done"};
Accessible from IDE

Yes
Available on iPhone only
26.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
JavaScript Example
//Defining the properties for a TextArea with hoverSkin:"hskin"
var tAreaPSP ={hoverSkin:"hskin"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
Specifies if the text to be displayed in action key of the keyboard.
Default: TEXTBOX_KEYBOARD_LABEL_DONE
l
TEXTBOX_KEYBOARD_LABEL_DONE
TEXTBOX_KEYBOARD_LABEL_GO
TEXTBOX_KEYBOARD_LABEL_SEARCH
TEXTBOX_KEYBOARD_LABEL_NEXT
TEXTBOX_KEYBOARD_LABEL_SEND
TEXTBOX_KEYBOARD_LABEL_GOOGLE
TEXTBOX_KEYBOARD_LABEL_JOIN
TEXTBOX_KEYBOARD_LABEL_ROUTE
TEXTBOX_KEYBOARD_LABEL_YAHOO
TEXTBOX_KEYBOARD_LABEL_CALLs
The following images illustrate the Keyboard label as Done and Search respectively:
Label - Done
Label - Search
Syntax
JavaScript: keyboardActionLabel
Lua: keyboardactionlabel
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a TextArea with keyboardActionLabel:constant
s.TEXTAREA_KEYBOARD_LABEL_SEND.
var tAreaPSP ={keyboardActionLabel:constants.TEXTAREA_KEYBOARD_LABEL_SEND};
//Reading the keyboardActionLabel of the TextArea.
alert("TextArea keyboardActionLabel ::"+txtArea.keyboardActionLabel);
Accessible from IDE

Yes
l
iPhone
iPad
Note: You can only paste the text to a textbox with the same pasteboard type as that of the source textbox.
For example, if you set the pasteboardType as TEXTAREA_PASTE_BOARD_TYPE_APP_LEVEL_
PERSISTENT, you can paste the text only to another textbox whose pasteboard type is set to
applevelpersistent.
The different pasteboard types are as follows:
l
TEXTAREA_PASTE_BOARD_TYPE_DEFAULT: If you select this option, the value selected in the

TEXTAREA_PASTE_BOARD_TYPE_SYSTEM_LEVEL: This is the default selection and if this

option is unchanged, the text copied from a TextArea can be pasted in TextArea (with the pasteboard
type set as systemlevel) across different applications on the device. Even if you exit the source
application, the copied text persists in the memory and can be pasted across applications or within the
same application.
l
TEXTAREA_PASTE_BOARD_TYPE_APP_LEVEL_PERSISTENT: If you select this option , the

text copied from a TextArea can be pasted in TextArea (with the pasteboard type set as applevel)
within the same application. Even if you close the application, the copied text persists in the memory
and can be copied to another TextArea whose pasteboard type is applevel, when you restart that
application.
TEXTAREA_PASTE_BOARD_TYPE_APP_LEVEL_NON_PERSISTENT: If you select this option ,

the text copied from a TextArea can be pasted in TextArea (with the pasteboard type set as
applevelnonpersistent) within the same application. This text is not retained in the memory when you
close the application.
TEXTAREA_PASTE_BOARD_TYPE_NO_PASTE_BOARD: Select this option, if you want to

disable the content to be copied from a TextArea.
Syntax
Lua: pasteboardtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a TextArea with pasteboardType:constants.TEX
TAREA_PASTE_BOARD_TYPE_SYSTEM_LEVEL
var tAreaPSP ={pasteboardType:constants.TEXTAREA_PASTE_BOARD_TYPE_SYSTEM_L
EVEL};
//Reading the pasteboardType of the TextArea.
alert("TextArea pasteboardType ::"+txtArea.pasteboardType);
Accessible from IDE

Yes
l
iPhone
iPad
Specifies the skin to be applied to the placeholder text in the TextArea widget. Only the font color skin
attribute is applicable.
The following image illustrates the placeholder text with a placeholder color applied:
Syntax
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for a TextArea with placeholderSkin:"placeholder
Skin"
:"Text", maxTextLength:20, isVisible:true, placeholder:"Enter text"};
var tAreaPSP ={placeholderSkin:"placeholderSkin"};
Note: You cannot specify an image as a skin for a placeholder as of now. You can only specify a single
color as a skin for a textbox for BlackBerry.
Note: Android and Windows support change in font color only.
Accessible from IDE

Yes
l
Android
BlackBerry
Windows Phone
Specifies if the "Done" button that appears in the keypad (opens when you select text box) must be visible or
not.
Default: true
If set to false, the "Done" button is not visible on the textbox.
If set to true, the "Done" button is visible on the textbox.
Note: You can customize the "Done" button using keyboardActionLabel
The following image illustrates the Keypad when the property is set to true:
The following image illustrates the Keypad when the property is set to false:
Syntax
JavaScript: showCloseButton
Lua: showclosebutton
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a TextArea with showCloseButton:true.
var tAreaPSP ={showCloseButton:true};
Accessible from IDE

Yes
Specifies if there must be an indication to the user that the widget content is being loaded.
Default: true
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a TextArea with showProgressIndicator:true.
var tAreaPSP ={showProgressIndicator:true};
Accessible from IDE

Yes
l
iPhone
iPad
26.3.10 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a TextArea with toolTip:sample text
var tAreaBasic={id:"textarea1", isVisible:true, skin:"txtSkin", focusSkin:
"txtFSkin", text:"Click Here"};
var tAreaLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], h
var tAreaPSP={toolTip:"sample text"};
var textarea1 = new kony.ui.TextArea(tAreaBasic, tAreaLayout, tAreaPSP);
Accessible from IDE

Yes
26.4 TextArea - Events

TextArea widget has the following events associated with it:
l
onDone
onBeginEditing
onEndEditing
onKeyUp
onKeyDown
onTextChange
26.4.1 onDone
This event is triggered when user is done with entering text in textarea and click or touch the Go or Enter
option.
Note: In Desktop Web platform, this event is fired when the enter key is pressed when the textarea has
focus.
Signature
JavaScript: onDone
Lua: ondone
Read / Write
JavaScript Example
//The below is the callback function for onDone event.
function onDoneCalBck(txtArea)
{
alert("onDone event triggered ");
//Write further logic here
}
//Defining the properties for a TextArea with the margin:[5,5,5,5].
var tAreaBasic = {id:"txtArea", maxTextLength:20, isVisible:true, placehol
der:"enter text", onDone:onDoneCalBck};
var tAreaPSP ={};
Accessible from IDE

Yes
Available on all platforms except SPA and on all Server side Mobile Web platforms
This is an event callback that is invoked by the platform when the user clicks within the TextArea and is about
to start editing.
Signature
JavaScript: onBeginEditing
Lua: onbeginediting
Read / Write
JavaScript Example
//The below is the callback function for onBeginEditing event.
function onBegEditCalBck(txtArea)
{
alert("onBeginEditing event triggered ");
}
//Defining the properties for a TextArea with the margin:[5,5,5,5]
der:"enter text"};
var tAreaPSP ={onBeginEditing:onBegEditCalBck};
Accessible from IDE

Yes
l
iPhone
iPad
Desktop Web
BlackBerry 10
26.4.3 onEndEditing
This is an event callback that is invoked by the platform when the user performs one of the below actions:
l
Click on any other focusable widget (for example, another TextBox)
Click on the Done button on the Next Previous bar.
Click on the Done button on the keypad.
When you click on the Done button of the keypad the following events take place in a sequence:
l
onendediting
ondone
Signature
JavaScript: onEndEditing
Lua: onendediting
Read / Write
JavaScript Example
//The below is the callback function for onEndEditing event.
function onEndEditCalBck(txtArea)
{
alert("onEndEditing event triggered ");
}
der:"enter text"};
var tAreaPSP ={onEndEditing:onEndEditCalBck};
Accessible from IDE

Yes
l
iPhone
iPad
Desktop Web
BlackBerry 10
26.4.4 onKeyUp
This is an event callback that is invoked by the platform when the user releases a key (on the keyboard).
Signature
JavaScript: onKeyUp
Read / Write
JavaScript Example
//The below is the callback function for onKeyUp event.
function onKeyUpeventCalBck(txtArea)
{
alert("onKeyUp event triggered ");
}
//Defining the properties for a TextArea
der:"enter text"};
var tAreaPSP ={onKeyUp:onKeyUpeventCalBck};
Accessible from IDE

Yes
Available only on Desktop Web
26.4.5 onKeyDown
This is an event callback that is invoked by the platform when the user presses a key (on the keyboard).
Signature
JavaScript: onKeyDown
Read / Write
JavaScript Example
//The below is the callback function for onKeyDown event.
function onKeyDowneventCalBck(txtArea)
{
alert("onKeyDown event triggered ");
}
//Defining the properties for a TextArea
der:"enter text"};
var tAreaPSP ={onKeyDown:onKeyDowneventCalBck};
Accessible from IDE

Yes
26.4.6 onTextChange
This is an event callback triggered when text in the TextArea changes. This event is not fired when the text is
changed programmatically.
Note: In Desktop Web platform, this event is fired when the focus is out after changing the text in the
textarea.
Signature
JavaScript: onTextChange
Lua: ontextchange
Read / Write
JavaScript Example
//The below is the callback function for onTextChange event.
function onTextChangeCallBack(txtArea)
{
alert("onTextChange event triggered");
//Write further logic here.
}
var tAreaBasic = {id:"txtArea", maxTextLength:20, isVisible:true, onTextCh
ange:onTextChangeCallBack, placeholder:"enter text"};
var tAreaPSP ={};
Accessible from IDE

Yes
26.5 TextArea - Deprecated Properties

The deprecated properties for TextArea widget are as follows:
l
editable
No of Rows
editable
No. of Rows
setEnabled API
26.5.1 editable
Specifies if the TextArea widget is enabled for editing when rendered.
Default: true (the checkbox is selected and the TextArea widget can be edited)
If you do not want the TextArea widget to be editable, set the value to false (clear the checkbox).
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
iPhone
iPad
26.5.2 No of Rows
The TextArea widget, by default displays three rows of text (irrespective of the text size). You can use this
property to customize the number of rows that the TextArea widget must display.
Default: 3 (three rows of text is displayed)
If you want the TextArea widget to display more number of rows, enter the desired number (between 3 and 10)
in this field.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
27. TextBox
TextBox widget is an editable text component that can be placed on a Form and is used to obtain an input from
a user.
You can use the TextBox widget to provide a field where a user can enter input text.
For example, in the "Login" page of an Application, you can place two TextBox widgets for Login and
Password fields and instruct the users to enter their login credentials in those fields.
TextBox provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
and Events.
Basic Properties
Layout Properties
autoCapitalize
focusSkin
id
info
isVisible
keyBoardStyle
maxTextLength
placeholder
secureTextEntry
skin
text
textInputMode
containerHeight
containerHeightMode
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Events
Deprecated
onCancel
onDone
onBeginEditing
onEndEditing
onKeyUp
onKeyDown
onTextChange
preOnclickJS
postOnclickJS
inputMode
inputStyle
keyBoardType
type
Platform Specific
Properties
autoComplete
autoCorrect
autoFilter
blockedUISkin
closeButtonText
filterlist
hoverSkin
keyboardActionLabel
leftViewImage
nativeListFieldSkin
pasteboardType
placeholderSkin
showClearButton
showCloseButton
toolTip
viewType
Creating an TextBox using a constructor: kony.ui.TextBox2

var mytextbox = new kony.ui.TextBox2 (basicConf, layoutConf, pspConf)
they are ignored.
JavaScript Example
//Defining the properties for a Textbox with isVisible: true.
var txtBasic = {id:"textBox1",placeholder:"enter text", maxTextLength:20,
isVisible:true, autoCapitalize:constants.TEXTBOX_AUTO_CAPITALIZE_SENTENCE
S};
var txtLayout = {padding:[5,5,5,5], margin:[5,5,5,5], containerWeight:100,
var txtPSP ={pasteboardType:constants.TEXTBOX_PASTE_BOARD_TYPE_SYSTEM_LEVE
L, keyboardActionLabel:constants.TEXTBOX_KEYBOARD_LABEL_GOOGLE};
//Creating the Textbox.
var textBox1 = new kony.ui.TextBox2(txtBasic, txtLayout, txtPSP);
//Reading the autoCapitalize of the Textbox.
alert("Textbox autoCapitalize ::"+textBox1.autoCapitalize);
kony.ui.TextBox.
var myTextBox = new kony.ui.TextBox(basicConf, layoutConf, pspConf)
The appearance of the TextBox widget with the Text "Editable text component" on various platforms is as
follows:
Platform
Appearance
Android
BlackBerry
Platform
Appearance
iPhone
Windows Phone
Adding a TextBox Widget using IDE

The steps involved in adding a TextBox widget are as follows:
1. From the IDE, drag and drop the TextBox widget onto a Form (occupies the complete available width).
a. If you want to resize the TextBox widget in the horizontal direction, place an HBox on the Form
and drag and drop the TextBox widget inside the HBox and resize accordingly.
b. If you want to resize the TextBox widget in the vertical direction, place an HBox on the Form
and place a VBox inside the HBox; and drag and drop the TextBox widget inside the VBox and
resize accordingly.
2. Enter text for the TextBox widget using the text property.
Note: When the widget is rendered, the text is editable by the user.
3. (Optional) Specify the maximum number of characters that a user can enter into the TextBox widget
using the maxTextLength property.
4. (Optional) Specify the restriction on the input characters that a user can enter (for example you can
restrict the entry to numbers) using the textInputMode property.
5. Specify an onDone event.
You can customize the appearance of the TextBox widget by using the following properties:
l
27.1 TextBox - Basic Properties

The basic properties for TextBox Widget are as follows:
l
autoCapitalize
focusSkin
id
info
isVisible
keyBoardStyle
maxTextLength
placeholder
secureTextEntry
skin
text
textInputMode
toolTip
Specifies the character capitalization behavior.
Default: TEXTBOX_AUTO_CAPITALIZE_NONE
Note: For Desktop Web platform, autoCapitalize property is not supported, use the events onBeginEditing,
l
TEXTBOX_AUTO_CAPITALIZE_NONE: If you leave this option unchanged, no action takes place on

the input string.
TEXTBOX_AUTO_CAPITALIZE_WORDS: This option changes the first character of all the words to
uppercase. (Not supported on Server side Mobile Web and BlackBerry platforms)
Example : This Is Sample Text.
TEXTBOX_AUTO_CAPITALIZE_SENTENCES: This option changes the first character of all the

sentences to uppercase. (Not supported on BlackBerry platform)
TEXTBOX_AUTO_CAPITALIZE_ALL: This option changes all the characters to uppercase. (Not

supported on Server side Mobile Web)
Example : THIS IS SAMPLE TEXT.
Syntax
JavaScript: autoCapitalize
Lua: autocapitalize
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with autoCapitalize:constants.TEXT
BOX_AUTO_CAPITALIZE_SENTENCES.
var txtBasic = {id:"textBox1", placeholder:"enter text", maxTextLength:20,
isVisible:true, autoCapitalize:constants.TEXTBOX_AUTO_CAPITALIZE_
SENTENCES};
var txtPSP ={};
//Creating a Textbox.
//Reading the autoCapitalize of the Textbox.
alert("Textbox autoCapitalize ::"+textBox1.autoCapitalize);
Accessible from IDE

Yes
Available on all platforms except Desktop Web and on Server side Mobile Web (basic and BJS). It is
browser specific on Server side Mobile Web (Advanced) platform.
Below is the browser specific limitations on SPA platform for the available options:
Browsers/Devices
NONE
WORDS
IE8
Supported Not supported
IE9
IE10
Chrome 29.0
Firefox 23.0.0
SENTENC
ES
Not
supported
Not
supported
Not
supported
Not
supported
Not
supported
All
Not
supported
Not
supported
Not
supported
Not
supported
Not
supported
Safari 5
iPhone5 OS 6.1.3
Not
Not supported
supported
Supported
Supported
Android 2.3.3
Android 4.2
BlackBerry
Windows
iPhone4 OS 4.2
Not
supported
Supported
Supported
Not
supported
Not
supported
Not
supported
Not
supported
Not
supported
Not
supported
Supported
Not
supported
Not
supported
Not
supported
Not
supported
27.1.2 focusSkin
2. Server side Mobile Web platform does not support this property, instead browser specific focus will be
applied.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with focusSkin:"txtFSkin".
var txtBasic = {id:"textBox1", skin:"txtSkin", focusSkin:"txtFSkin", text:
"Text", maxTextLength:20, isVisible:true, secureTextEntry:true, placeholde
r:"enter text"};
var txtPSP ={};

//Reading the focusSkin of the Textbox
alert("Textbox focusSkin ::"+textBox1.focusSkin);
Accessible from IDE

Yes
27.1.3 id
id is a unique identifier of TextBox consisting of alpha numeric characters. Every TextBox should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Textbox with id:"textBox1".
r:"enter text"};
var txtPSP ={};
//Reading the id of the Textbox.
alert("Textbox Id ::"+textBox1.id);
Accessible from IDE

Yes
27.1.4 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a Textbox with info property.
r:"enter text"};
var txtPSP ={};
textBox1.info = {key:"Textboxinfo"};
//Reading the info of the Textbox.
alert("Textbox Info is ::"+textBox1.info);
Accessible from IDE

No
27.1.5 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Textbox with isVisible:true.
r:"enter text"};
var txtPSP ={};
//Reading the isVisible of the Textbox
alert("Textbox isVisible ::"+textBox1.isVisible);
Accessible from IDE

Yes
When you interact with a TextBox widget, a keyboard is displayed. You can use this property to select the
type of keyboard that you want to display.
Note: Keys on the keyboard style may vary from platform to platform.
Note: On Desktop Web platform, KeyBoardStyle property is not supported, use the events onBeginEditing,
Note: The option TEXTBOX_KEY_BOARD_STYLE_DECIMAL is not supported in iPad device natively.
Note: On BlackBerry 10 platform, only the option TEXTBOX_INPUT_MODE_ANY is supported. Click here
for BlackBerry 10 supported keyboard styles. The key ".com" is shown as "/" on the device when you set
keyboard style as TEXTBOX_KEY_BOARD_STYLE_URL, instead of ".com" as mentioned in the
BlackBerry documentation site.
The following are the available keyboard types when you select textInputMode as TEXTBOX_INPUT_
MODE_ANY.
l
TEXTBOX_KEY_BOARD_STYLE_DEFAULT: Specifies the default keyboard in respective

platforms. Supported in BlackBerry 10 platform.
TEXTBOX_KEY_BOARD_STYLE_EMAIL: Specifies the keyboard to enter email address. Supported

in BlackBerry 10 platform.
TEXTBOX_KEY_BOARD_STYLE_URL: Specifies the keyboard to enter URL address. Supported in

BlackBerry 10 platform.
TEXTBOX_KEY_BOARD_STYLE_CHAT: Specifies the keyboard type which is helpful for chatting.

The following are the available keyboard types when you select textInputMode as TEXTBOX_INPUT_
MODE_NUMERIC.
l
TEXTBOX_KEY_BOARD_STYLE_DEFAULT: Specifies the default numeric keyboard.
TEXTBOX_KEY_BOARD_STYLE_DECIMAL: Specifies the keyboard to enter decimals.
TEXTBOX_KEY_BOARD_STYLE_NUMBER_PAD: Specifies the keyboard to enter numbers. (Not

supported in Windows platform)
TEXTBOX_KEY_BOARD_STYLE_PHONE_PAD: Specifies the keyboard to enter phone numbers.

(Not supported in Windows platform)
TEXTBOX_KEY_BOARD_STYLE_SIGNED_NUMBER: Specifies the keyboard to enter negative

numbers(for example -345). This option is applicable to Android platform only.
TEXTBOX_KEY_BOARD_STYLE_SIGNED_DECIMAL_NUMBER: Specifies the keyboard to enter

negative decimal numbers (for example -345.87). This option is applicable to Android platform only.
Syntax
JavaScript: keyBoardStyle
Lua: keyboardstyle
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with keyBoardStyle:constants.TEXTB
OX_KEY_BOARD_STYLE_URL.
isVisible:true, keyBoardStyle:constants.TEXTBOX_KEY_BOARD_STYLE_URL};
var txtPSP ={};
//Reading the keyBoardStyle of the Textbox.
alert("Textbox keyBoardStyle ::"+textBox1.keyBoardStyle);
Accessible from IDE

Yes
Available on all platforms except on Server side Mobile Web (basic, BJS), Windows Kiosk, SPA, and it is
device specific on Server side Mobile Web (Advanced) platform.
Specifies the maximum number of characters that the text field can accept.
Default: empty
If you specify a number for this property, the number of input characters cannot exceed the specified number.
Note: On Server side Mobile Web, support for this property depends on the device that support maxlength
attribute for TextBox (HTML input tag), else this property is ignored.
Syntax
JavaScript: maxTextLength
Lua: maxtextlength
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with maxTextLength:20.
r:"enter text"};
var txtPSP ={};
//Reading the maxTextLength of the Textbox
alert("Textbox maxTextLength ::"+textBox1.maxTextLength);
Accessible from IDE

Yes
Available on all platform except Server side Mobile Web(basic) and BlackBerry 10 platform
27.1.8 placeholder
The placeholder attribute specifies a short hint that describes the expected value of an input field (example, a
sample value or a short description of the expected format). The hint is displayed in the input field when it is
empty, and disappears when the field gets focus.
For example, for the Username field, you can enter the placeholder text as Enter User ID or Email Address.
The user then clicks on the TextBox widget and enters the Username.
- If you specify text both in the text property and the Placeholder property, the text entered in the text
property is displayed when rendered. If the user deletes the text, the placeholder text is displayed.
- If you programmatically set an empty string for the text property, the placeholder text is displayed.
The following image illustrates the placeholder text in a TextBox widget:
Syntax
Lua: placeholder
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with placeholder:"enter text".
r:"enter text"};
var txtPSP ={};
//Reading the placeholder of the Textbox.
alert("Textbox placeholder ::"+textBox1.placeholder);
Note: You can set the placeholder text from the code only on iPhone, Android, BlackBerry, Windows,
J2ME, and Server side Mobile Web Advanced platforms.
Accessible from IDE

Yes
Available on all platforms except SPA Windows 7.5 devices and Server side Mobile Web (Basic, BJS,
and Windows NTH devices)
Specifies whether the text entered by the user will be secured using a mask character, such as asterisk or
dot. This is typically set to true for a password field.
Default: false
If set to true, the text in the TextBox will be masked.
If set to false, the text in the TextBox will be displayed as clear text.
Syntax
JavaScript: secureTextEntry
Lua: securetextentry
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with secureTextEntry:true.
r:"enter text"};
var txtPSP ={};
Accessible from IDE

Yes
27.1.10 skin
Note: On BlackBerry 10 platform, skin font style with underline is not supported.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with skin:"txtSkin".
r:"enter text"};
var txtPSP ={};
//Reading the skin of the Textbox
alert("Textbox skin ::"+textBox1.skin);
Accessible from IDE

Yes
27.1.11 text
Specifies a general or descriptive text for the TextBox widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with text:"Sample Text".
var txtBasic = {id:"txtBox",skin:"txtSkin", focusSkin:"txtFSkin", text:"Sa
mple Text", maxTextLength:20,isVisible:true, secureTextEntry:true, placeho
lder:"PH"};
var txtPSP ={};
//Reading the text of the Textbox
alert("Textbox text ::"+textBox1.text);
Accessible from IDE

Yes
Specifies the type of input characters that a user can enter into the TextBox widget. You can use this property
to restrict the input characters to only numbers or a combination of alphabets, numbers, and special
characters.
Default: TEXTBOX_INPUT_MODE_ANY
l
TEXTBOX_INPUT_MODE_ANY: Specifies that the input characters can be letters, numbers, special
characters, or a combination of all the three. Only this option is supported in BlackBerry 10 platform.
TEXTBOX_INPUT_MODE_NUMERIC: Specifies that the input characters must be numbers only.

This option is not supported on Mobile Web platforms.
Note: The values of keyBoardStyle property are dependent on these modes.
Syntax
JavaScript: textInputMode
Lua: textinputmode
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with textInputMode:constants.TEXTB
OX_INPUT_MODE_NUMERIC.
isVisible:true, textInputMode: constants.TEXTBOX_INPUT_MODE_NUMERIC};
var txtLayout = {padding:[5,5,5,5],margin:[5,5,5,5], containerWeight:100,
var txtPSP ={};
Accessible from IDE

Yes
Available on all platforms expect SPA and on all Server side Mobile Web (Basic, BJS and Advanced),
and Desktop Web platforms
27.1.13 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with toolTip:sample text
isVisible:true, textInputMode: constants.TEXTBOX_INPUT_MODE_NUMERIC, toolT
ip:"sample text"};
var txtPSP ={};
Accessible from IDE

Yes
Available on all platforms except Windows Kiosk and BlackBerry 10
27.2 TextBox - Layout Properties

The layout properties for TextBox Widget are as follows:
l
containerHeight
containerHeightMode
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
widgetAlignment
Specifies the height of the textbox in terms of percentage. The percentage is with reference to the value of
containerHeightReference property.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with containerHeight:40
r:"enter text"};
var txtLayout = {padding:[5,5,5,5], margin:[5,5,5,5],
containerWeight:100,containerHeight: 40, containerHeightReference:constant
s.TEXTBOX_HEIGHT_BY_FORM_REFERENCE, widgetAlignment:constants.WIDGET_ALIGN_
TOP_LEFT};
var txtPSP ={};
Accessible form IDE

Yes
This property is enabled when you set the containerHeight. The textbox height percentage is calculated based
on the option selected.
Default: TEXTBOX_HEIGHT_BY_FORM_REFERENCE
l
TEXTBOX_HEIGHT_BY_FORM_REFERENCE: The textbox height is calculated based on the height

of the Form excluding headers and footers. This option is not respected if textbox is placed inside a
popup or in templates and fallback to containerHeightMode option TEXTBOX_FONTS_METRICS_
DRIVEN_HEIGHT.
TEXTBOX_HEIGHT_BY_PARENT_WIDTH: This option is used if the textbox is placed inside a

popup or in templates. The width is calculated based on the width of the parent container.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with containerHeightReference:cons
tants.CONTAINER_HEIGHT_BY_FORM_REFERENCE
r:"enter text"};
containerHeight: 40, containerHeightReference:constants.TEXTBOX_HEIGHT_BY_
FORM_REFERENCE, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var txtPSP ={};
Accessible from IDE

Yes
27.2.3 containerHeightMode
Specifies the textbox height based on the selected option.
Default: TEXTBOX_CUSTOM_HEIGHT
l
TEXTBOX_DEFAULT_PLATFORM_HEIGHT: This is default option for iPhone and SPA platform and
is available on those platforms only.
TEXTBOX_FONT_METRICS_DRIVEN_HEIGHT:This the default option on Android, Blackberry, and

Windows Phone platforms. It is supported on all platforms.
TEXTBOX_CUSTOM_HEIGHT: This option is supported by all platforms and accepts height in

percentage (%). The percentage is evaluated using the containerHeightReference.
Syntax
JavaScript: containerHeightMode
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with containerHeightMode:constants
.TEXTBOX_CUSTOM_HEIGHT
r:"enter text"};

containerHeight: 40, containerHeightReference:constants.TEXTBOX_HEIGHT_BY_
FORM_REFERENCE,containerHeightMode:constants.TEXTBOX_CUSTOM_HEIGHT ,widget
Alignment:constants.WIDGET_ALIGN_TOP_LEFT};
var txtPSP ={};
Accessible from IDE

Yes
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a Textbox with the containerWeight:100
r:"enter text"};
var txtPSP ={};

//Reading the containerWeight of the Textbox
alert("Textbox containerWeight ::"+textBox1.containerWeight);
Accessible from IDE

No
Specifies the alignment of the text for a TextBox with respect to its boundaries. The default value is
CONTENT_ALIGN_TOP_LEFT for all platforms. To choose another alignment, click the drop-down arrow
adjacent to the property from the properties window and select the alignment option.
Default: constants.CONTENT_ALIGN_TOP_LEFT
l
constants.CONTENT_ALIGN_TOP_LEFT: Specifies the text should align at top left corner of the
TextBox.
constants.CONTENT_ALIGN_TOP_RIGHT: Specifies the text should align at top right of the

TextBox.
constants.CONTENT_ALIGN_TOP_CENTER: Specifies the text should align at top center of the

TextBox.
constants.CONTENT_ALIGN_MIDDLE_LEFT: Specifies the text should align from left of the

TextBox.
constants.CONTENT_ALIGN_CENTER: Specifies the test should align at the center of the TextBox.
constants.CONTENT_ALIGN_MIDDLE_RIGHT: Specifies the text should align from right of the

TextBox.
constants.CONTENT_ALIGN_BOTTOM_LEFT: Specifies the text should align at bottom left of the

TextBox.
constants.CONTENT_ALIGN_BOTTOM_CENTER: Specifies the text should align at bottom center

of the TextBox.
constants.CONTENT_ALIGN_BOTTOM_RIGHT: Specifies the text should align at bottom right of the

TextBox.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with contentAlignment:constants.CO
NTENT_ALIGN_TOP_LEFT
r:"enter text"};
contentAlignment:constants.CONTENT_ALIGN_TOP_LEFT, widgetAlignment:constan
ts.WIDGET_ALIGN_TOP_LEFT};
var txtPSP ={};
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and Windows Kiosk platforms
27.2.6 hExpand
Default: true
contents width, padding, and margin.
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with the hExpand:true
r:"enter text"};
var txtPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and SPA
27.2.7 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Textbox with the margin:[5,5,5,5]
r:"enter text"};
var txtPSP ={};
var textBox1= new kony.ui.TextBox2(txtBasic, txtLayout, txtPSP);
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Textbox with margin in pixels.
"Text",maxTextLength:20, isVisible:true, secureTextEntry:true, placeholder
:"enter text"};
marginInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var txtPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
27.2.9 padding
To define the padding values for a platform, click the Ellipsis ( ) button against the property to open the
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Textbox with the padding:[5,5,5,5].
r:"enter text"};
var txtPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web(basic) and BlackBerry 10
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Textbox with padding in pixels.
r:"enter text"};
paddingInPixel:true, widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT};
var txtPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
l
Note: The alignment property is applicable only if the widget size is lesser than the allocated size.
On Windows Platform TextBox does not support horizontal alignment attributes. By default, the TextBox is
aligned to the center of the horizontal space.
Refer the following table for alignment properties in Windows Phone.
Alignment set in the IDE

top-left, top-right, top-center
Alignment on the device

Top
middle-left, middle-right, middle-center Middle

bottom-left, bottom-right, bottomcenter
Bottom
The following image illustrates the widget alignment property:
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with the widgetAlignment:constants
.WIDGET_ALIGN_TOP_LEFT
"Text",maxTextLength:20, isVisible:true, secureTextEntry:true, placeholder
:"enter text"};
var txtPSP ={};
//Reading the widgetAlignment of the Textbox
alert("Textbox widgetAlignment ::"+textBox1.widgetAlignment);
Accessible from IDE

Yes
27.3 TextBox - Platform Specific Properties

The platform specific properties for TextBox Widget are as follows:
l
autoComplete
autoCorrect
autoFilter
blockedUISkin
closeButtonText
filterList
hoverSkin
keyboardActionLabel
leftViewImage
nativeListFieldSkin
pasteboardType
placeholderSkin
showClearButton
showCloseButton
toolTip
viewType
27.3.1 autoComplete
Autocomplete, enables users to quickly find and select from a prepopulated list of values as they type,
leveraging searching and filtering.
Default: false
If set to true, the word suggestion is enabled.
If set to false, the word suggestion is not enabled.
Syntax
JavaScript: autoComplete
Lua: autocomplete
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with autoComplete:true
var txtBasic = {id:"textBox1", isVisible:true, placeholder:"enter text"};
var txtPSP ={autoComplete:true};
Accessible from IDE

Yes
l
Below is the browser specific limitations on SPA platform when autoComplete property is set to true/false.
Browsers/Devices
IE8
IE9
IE10
Chrome 29.0
Firefox 23.0.0
Safari 5
iPhone4 OS 4.2
iPhone5 OS 6.1.3
Android 2.3.3
Android 4.2
BlackBerry
Windows
True
Not supported
Not supported
Not supported
Supported if form is
submitted to an external url
Supported if form is
submitted to an external url
Not supported
Not supported
Not supported
Not supported
Not supported
Not supported
Not supported
False
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
27.3.2 autoCorrect
This property determines whether auto-correction is enabled or disabled during typing. With auto-correction
enabled, the text object tracks unknown words and suggests a more suitable replacement candidate to the
user, replacing the typed text automatically unless the user explicitly overrides the action.
Default: false
If set to true, the auto correction option is enabled.
If set to false, the auto correction option is not enabled.
Syntax
JavaScript: autoCorrect
Lua: autocorrect
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Textbox with autoCorrect:true
var txtBasic = {id:"txtBox", isVisible:true, placeholder:"enter text"};
var txtPSP ={autoCorrect:true};
var txtBox = new kony.ui.TextBox2(txtBasic, txtLayout, txtPSP);
Accessible from IDE

Yes
l
iOS
Server side MobileWeb (Advanced)
Below is the browser specific limitations on SPA platform when autoCorrect property is set to true/false.
Browsers/Devices
IE8
IE9
IE10
Chrome 29.0
Firefox 23.0.0
Safari 5
iPhone4 OS 4.2
iPhone5 OS 6.1.3
Android 2.3.3
Android 4.2
BlackBerry
Windows
True
Not supported
Not supported
Not supported
Not supported
Not supported
Not supported
Supported
Supported
Not supported
Not supported
Not supported
Not supported
False
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
Supported
27.3.3 autoFilter
Specifies if the input characters you enter in the TextBox widget must be matched against the filterList and
possible matches be displayed.
Note: This property is applicable only if you set a filterList.
Default: false (the checkbox is not selected and the input characters are not matched against the filterlist)
If you want the input characters to be matched against the filterlist and possible matches to be displayed, set
the value to true (select the checkbox).
The following image illustrates the Auto Filter property:
On Windows platform, if you set the autoFilter property to true, the following additional properties are made
available :
filterCriteria
Specifies the criteria with which the items attached to the filterlist are compared. You can select one of
the following criteria:
None - No criteria is specified. If you leave the selection unchanged, the event
associated with ontextchange is triggered.
StartsWith: Filters and displays all the values that start with the value defined in this
mode.
StartsWithCaseSensitive: Filters and displays all the values that start with the value
defined in this mode with case sensitivity.
StartsWithOrdinal: Filters and displays all the values that start with the sequence of
values defined in this mode.
StartsWithOrdinalCaseSensitive: Filters and displays all the values that start with the
sequence of values defined in this mode with case sensitivity.
Contains: Filters and displays all the values that contain the value defined in this mode.
ContainsCaseSensitive: Filters and displays all the values that contain the value defined
in this mode with case sensitivity.
ContainsOrdinal: Filters and displays all the values that contain the sequence of values
defined in this mode.
ContainsOrdinalCaseSensitive: Filters and displays all the values that contain the
Equals: Filters and displays all the values that are equal to the value defined in this
mode.
EqualsCaseSensitive: Filters and displays all the values that are equal to the value
defined in this mode with case sensitivity.
EqualsOrdinal: Filters and displays all the values that are equal to the sequence of
values defined in this mode.
EqualsOrdinalCaseSensitive: Filters and displays all the values that are equal to the
filterBoxSkin
Specifies the skin that must be applied to the box in which the filtered values are displayed.
Syntax
JavaScript: autoFilter
Lua: autofilter
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with autoFilter:true
var txtLayout = {padding:[5,5,5,5], margin:[5,5,5,5],containerWeight:100,
var txtPSP ={autoFilter:true};
Accessible from IDE

Yes
l
BlackBerry
Windows Mobile
Android
Windows Kiosk
call) is completed.
Default: null (No skin is applied)
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with blockedUISkin:"blockUISkin"
var txtPSP ={blockedUISkin:"blockUISkin"};
//Reading the blockedUISkin of the Textbox
alert("Textbox blockedUISkin ::"+textBox1.blockedUISkin);
Accessible from IDE

Yes
l
Specifies the text to replace the "Done" button that appears in the Keypad (opens when you select a textbox).
Default: Done (The text on the close button is Done)
If you want to change the text for the close button, enter the text of your choice. For example, if you want to
change the text from Done to Go, enter Go in the property field. The following image illustrates the Keypad
when the text in the property is changed to Go:
Syntax
JavaScript: closeButtonText
Lua: closebuttontext
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with closeButtonText:"done"
var txtPSP ={closeButtonText:"Done"};
Accessible from IDE

Yes
27.3.6 filterList
The values you enter in the TextBox are matched against this list and possible matches are displayed.
Note: For BlackBerry, Android, and Windows platforms, this property is applicable only if the autoFilter
property is set to true.
Syntax
JavaScript: filterList
Lua: filterlist
Type
JavaScript: Array
Lua: Table
Read / Write
Yes - (Write only)
JavaScript Example
//Defining the properties for a Textbox with filterlist:["Aaaa","Bbbb","Cc
cc","Dddd"]
var txtPSP ={filterlist:["Aaaa","Bbbb","Cccc","Dddd"]};
Accessible from IDE

No
l
BlackBerry
Windows Mobile
Android
Windows Kiosk
27.3.7 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
JavaScript Example
//Defining the properties for a Textbox with hoverSkin:"hskin"
var txtPSP ={hoverSkin:"hskin"};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
Specifies the text to be displayed in action key of the keyboard.
Default: TEXTBOX_KEYBOARD_LABEL_DONE
The following are the available options on iOS platform:
l
TEXTBOX_KEYBOARD_LABEL_GOOGLE
TEXTBOX_KEYBOARD_LABEL_JOIN
TEXTBOX_KEYBOARD_LABEL_ROUTE
TEXTBOX_KEYBOARD_LABEL_YAHOO
TEXTBOX_KEYBOARD_LABEL_CALL
The following are the available options on Android platform:

l
TEXTBOX_KEYBOARD_LABEL_PREVIOUS
The following images illustrate the Keyboard label as Done and Search respectively:
Label - Done
Label - Search
Syntax
JavaScript: keyboardActionLabel
Lua: keyboardactionlabel
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with the keyboardActionLabel:const
ants.TEXTBOX_KEYBOARD_LABEL_SEARCH.
var txtPSP ={keyboardActionLabel:constants.TEXTBOX_KEYBOARD_LABEL_SEARCH;
//Creating the TextBox.
//Reading the keyboardActionLabel of the Textbox
alert("Textbox keyboardActionLabel ::"+textBox1.keyboardActionLabel);
Accessible from IDE

Yes
l
iPad
iPhone
27.3.9 leftViewImage
Specifies the image that must be displayed on the left-hand side within a TextBox widget. For example, if you
want a magnifying glass image to be displayed to indicate "Search" option, you can use this property to
display the image.
The following image illustrates a TextBox widget with a Left View image:
Syntax
JavaScript: leftViewImage
Lua: leftviewimage
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with the leftViewImage:"magnify.pn
g"
var txtBasic = {id:"textBox1",isVisible:true,placeholder:"enter text"};
var txtPSP ={leftViewImage:"magnify.png"};
Accessible from IDE

Yes
l
iPhone
iPad
Specifies the skin that is applied to a focused item in the native popup (the list of items are displayed and a
pop up appears just below the textfield) that appears when you enter a value in the TextBox.
Syntax
JavaScript: nativeListFieldFocusSkin
Lua: nativelistfieldfocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with nativeListFieldFocusSkin:true
var txtPSP ={nativeListFieldFocusSkin:true};
//Reading the nativeListFieldFocusSkin of the Textbox
alert("Textbox nativeListFieldFocusSkin ::"+textBox1.nativeListFieldFocusS
kin);
Accessible from IDE

Yes
Available on BlackBerry only
Specifies the skin that is applied to each item in the native popup (the list of items are displayed and a pop up
appears just below the text field) that appears when you enter a value in the TextBox.
Syntax
JavaScript: nativeListFieldSkin
Lua: nativelistfieldskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Textbox with nativeListFieldSkin:true.
var txtPSP ={nativeListFieldSkin:true};

//Reading the nativeListFieldSkin of the Textbox.
alert("Textbox nativeListFieldSkin ::"+textBox1.nativeListFieldSkin);
Accessible from IDE

Yes
Available on BlackBerry only
Note: You can only paste the text to a textbox with the same pasteboard type as that of the source textbox.
For example, if you set the Pasteboard type as applevelpersistent, you can paste the text only to another
textbox whose pasteboard type is set to applevelpersistent.
The different Pasteboard types are as follows:
l
TEXTBOX_PASTE_BOARD_TYPE_DEFAULT : If you select this option, the value selected in the

TEXTBOX_PASTE_BOARD_TYPE_SYSTEM_LEVEL : This is the default selection and if this option

is unchanged, the text copied from a Textbox can be pasted in Textboxes (with the pasteboard type set
as systemlevel) across different applications on the device. Even if you exit the source application, the
copied text persists in the memory and can be pasted across applications or within the same
application.
TEXTBOX_PASTE_BOARD_TYPE_APP_LEVEL_PERSISTENT : If you select this option , the text

copied from a Textbox can be pasted in Textboxes (with the pasteboard type set as applevel) within
the same application. Even if you close the application, the copied text persists in the memory and can
be copied to another textbox whose pasteboard type is applevel. For Example, when you restart that
application.
TEXTBOX_PASTE_BOARD_TYPE_APP_LEVEL_NON_PERSISTENT : If you select this option ,

the text copied from a Textbox can be pasted in Textboxes (with the pasteboard type set as
(nonpersistent) within the same instance of the application. This text is not retained in the memory
when you close the application.
TEXTBOX_PASTE_BOARD_TYPE_NO_PASTE_BOARD : Select this option if you want to disable

copying the content from a TextBox.
Syntax
Lua: pasteboardtype
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Textbox with the pasteboardType:constants.
TEXTBOX_PASTE_BOARD_TYPE_SYSTEM_LEVEL
var txtPSP ={pasteboardType:constants.TEXTBOX_PASTE_BOARD_TYPE_SYSTEM_
LEVEL};
//Reading the pasteboardType of the Textbox
alert("Textbox pasteboardType ::"+textBox1.pasteboardType);
Accessible from IDE

Yes
l
iPhone
iPad
Specifies the skin to be applied to the placeholder text in the TextBox widget. Only the font color skin attribute
is applicable.
The following image illustrates the placeholder text with a placeholder color applied:
Syntax
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with placeholderSkin:"placeholderS
kn"
var txtPSP ={placeholderSkin:"placeholderSkn"};
Note: You cannot specify an image as a skin for a placeholder as of now. You can only specify a single
color as skin background for a textbox for BlackBerry.
Note: Android and Windows support change in font color only.
Accessible from IDE

Yes
l
iPhone
iPad
Android
BlackBerry
27.3.14 showClearButton
Specifies if a "Clear" button must be provided. You can use the "Clear" button to erase the text in the TextBox
widget.
Default: true
If set to false, the clear button is not provided to the textbox.
If set to true, the clear button is provided to the textbox.
The following images illustrate a TextBox widget with and without a Clear Button:
With Clear Button
Without Clear Button
Syntax
JavaScript: showClearButton
Lua: showclearbutton
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with the showClearButton:false.
var txtPSP ={showClearButton:false};
Accessible from IDE

Yes
l
iPhone
iPad
Specifies if the "Done" button that appears in the keypad (opens when you select text box) must be visible or
not.
Default: true
If set to false, the "Done" button is not visible on the textbox.
If set to true, the "Done" button is visible on the textbox.
Note: You can customize the "Done" button using keyboardActionLabel.
The following image illustrates the Keypad when the property is set to true:
The following image illustrates the Keypad when the property is set to false:
Syntax
JavaScript: showCloseButton
Lua: showclosebutton
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with showCloseButton:true.
var txtPSP ={showCloseButton:true};
Accessible from IDE

Yes
Specifies if there must be an indication to the user that the widget content is being loaded.
Default: true
The following image illustrates the loading indicator:
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Textbox with the showProgressIndicator:tru
e.
var txtPSP ={showProgressIndicator:true};
Accessible from IDE

Yes
l
iPhone
iPad
27.3.17 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a TextBox with toolTip:sample text
var txtBasic={id:"textbox1", isVisible:true, skin:"txtSkin", focusSkin:"tx
tFSkin", text:"Click Here", toolTip:"sample text"};
var txtLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hEx
var txtPSP={};
//Creating the TextBox.
var textbox1 = new kony.ui.TextBox(txtBasic, txtLayout, txtPSP);
Accessible from IDE

Yes
This property is available on Windows 8
27.3.18 viewType
Specifies the appearance of the Textbox as Search view or a textbox to accept text input. You can select one
of the following available views:
TEXTBOX_VIEW_TYPE_DEFAULT - This is the default selection and if this option is unchanged, the
appearance of the Textbox remains unchanged.
TEXTBOX_VIEW_TYPE_SEARCH_VIEW - The Textbox appears as a Search view.
The following image illustrates the both the view types:
View - Textbox
View - Search view
On Android platform, when you select the viewType as Search view, and click anywhere within the search
box, a cancel button appears along with a keypad. On clicking Cancel, the keypad goes out of view.
The following image illustrates the "Cancel" button for a search box on android platform:
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read and Write) (on Android Platform, this property is not writable)
JavaScript Example
//Defining the properties for a Textbox with viewType:TEXTBOX_VIEW_TYPE_SE
ARCH_VIEW.
var txtPSP ={viewType:TEXTBOX_VIEW_TYPE_SEARCH_VIEW};
//Reading the viewType of the Textbox.
alert("Textbox viewType ::"+textBox1.viewType);
Accessible from IDE

Yes
l
iPhone
iPad
Android
27.4 TextBox - Events

TextBox has the following events associated with it:
l
onCancel
onDone
onBeginEditing
onEndEditing
onKeyUp
onKeyDown
onTextChange
preOnclickJS
postOnclickJS
27.4.1 onCancel
This event is a callback that is invoked by the platform then the user performs a click action on the Cancel
button.
Note: This event is triggered only when the viewType is set as TEXTBOX_VIEW_TYPE_SEARCH_VIEW.
Signature
JavaScript: onCancel
Read / Write
JavaScript Example
//The below function is the callback function for onCancel event.
function onCancelCallBack(eventobject)
{
alert("onCancel event triggered");
}
//Defining the properties for a Textbox with the id:"txtBox"
var txtBasic = {id:"txtBox", isVisible:true, onDone:onDoneCallBack, onCanc
el:onCancelCallBack};
var txtPSP ={viewType:constants.TEXTBOX_VIEW_TYPE_SEARCH_VIEW};
Accessible from IDE

No
Available on iOS platform only
27.4.2 onDone
This event is a callback that is invoked by the platform then the user performs a click action on the Go or Enter
button.
Note: In Desktop Web platform, this event is fired when the enter key is pressed when the textbox has
focus.
Signature
JavaScript: onDone
Lua: ondone
Read / Write
JavaScript Example
//The below function is the callback function for onDone event.
function onDoneCallBack(txtBox)
{
alert("onDone event triggered");
}
var txtBasic = {id:"txtBox", isVisible:true, onDone:onDoneCallBack};
var txtPSP ={};
Accessible from IDE

Yes
This is an event callback that is invoked by the platform when the user clicks within the TextBox and is about
to start editing.
Signature
JavaScript: onBeginEditing
Lua: onbeginediting
Read / Write
JavaScript Example
//The below function is the callback function for onBeginEditing event
function onBeginEditCallBack(txtBox)
{
alert("onBeginEditing event triggered");
}
var txtBasic = {id:"txtBox",isVisible:true};
var txtPSP ={onBeginEditing:onBeginEditCallBack};
Accessible from IDE

Yes
l
iPhone
iPad
Desktop Web
27.4.4 onEndEditing
This is an event callback that is invoked by the platform when the user performs one of the below actions:
Click on any other focusable widget(for example, another TextBox)
Click on the Done button on the Next Previous bar.
Click on the Done button on the keypad.
When you click on the Done button of the keypad the following events take place in a sequence:
l
onendediting
ondone
Signature
JavaScript: onEndEditing
Lua: onendediting
Read / Write
JavaScript Example
//The below function is the callback function for onEndEditing event.
function onEndEditCallBack(txtBox)
{
alert("onEndEditing event triggered");
}
var txtBasic = {id:"txtBox", isVisible:true};

var txtPSP ={onEndEditing:onEndEditCallBack};
l
iPhone
iPad
Desktop Web
27.4.5 onKeyUp
This is an event callback that is invoked by the platform when the user releases a key (on the keyboard).
Signature
JavaScript: onKeyUp
Read / Write
JavaScript Example
//The below function is the callback function for onKeyUp event.
function onKeyUpeventCalBck(txtBox)
{
alert("onKeyUp event triggered");
}
var txtPSP ={onKeyUp:onKeyUpeventCalBck};
Accessible from IDE

Yes
27.4.6 onKeyDown
This is an event callback that is invoked by the platform when the user presses a key (on the keyboard).
Signature
JavaScript: onKeyDown
Read / Write
JavaScript Example
//The below function is the callback function for onKeyDown event.
function onKeyDowneventCalBck(txtBox)
{
alert("onKeyDown event triggered");
}
var txtPSP ={onKeyDown:onKeyDowneventCalBck};
Accessible from IDE

Yes
27.4.7 onTextChange
This is an event callback triggered when text in the text box changes. This event is not fired when the text is
changed programmatically.
Note: In Server side MobileWeb platform, this event is triggered only when the user enters minimum three
characters. This event cannot be used to display a form or a popup or an alert. It is used to update filterList
property.
Note: In Desktop Web platform, this event is fired when the focus is out after changing the text in the
textbox.
Signature
JavaScript: onTextChange
Lua: ontextchange
Read / Write
JavaScript Example
//The below function is the callback function for onTextChange event
function onTextChangeCallBack(txtBox)
{
alert("onTextChange event triggered");
}
var txtBasic = {id:"txtBox", isVisible:true, onTextChange:onTextChangeCall
Back};
var txtPSP ={};
Available on all platforms except Server side Mobile Web(basic/BJS)
27.4.8 preOnclickJS
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
function preOnclickJSCalBck(txtBox)
{
}
Back};
var txtPSP ={preOnclickJS:preOnclickJSCalBck};
Accessible from IDE

Yes
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
function postOnclickJSCalBck(txtBox)
{
}
Back};
var txtPSP ={postOnclickJS:postOnclickJSCalBck};
Accessible from IDE

Yes
27.5 TextBox - Deprecated Properties

The deprecated properties for TextBox widget are as follows:
l
inputStyle
keyBoardType
type
27.5.1 inputStyle
Specifies the input style in the TextBox widget.
If Any is selected in the Mode property, then the following options are made available:
l
default: This is the default selection. If you leave this option unchanged, no action takes place on the
input string.
Capitalize Words: This option changes the first character of all the words to uppercase.
Capitalize sentence: This option changes the first character of all the sentences in a string to
uppercase.
ALL CAPS: This option changes all the characters to uppercase.
Email: This option opens a keyboard to enter an email address.
If Numeric is selected in the Mode property, then the following options are made
available:
l
default: This is the default selection. If you leave this option unchanged, you can enter only Real
positive values (0-9).
Signed Number: This option allows you to enter a positive or negative sign at the beginning of the
number.
Decimal Number: This option allows you to enter a decimal point to enter fractional values.
Signed Decimal Number: This option allows you to enter fractional values and negative numbers.
If Password is selected in the Mode property, then the following options are made
available:
l
default: This is the default selection. If you leave this option unchanged, the characters you enter are
masked.
Visible Password: The password characters you enter are visible to you and not masked.
Type
Number
Read / Write
No
Accessible from IDE

Yes
Available only on Android/Android Tablet
27.5.2 keyBoardType
When you interact with a TextBox widget, a keyboard is displayed.
You can use this property to select the type of keyboard that you want to display. The following are the
available keyboard types that you can select and their appearances on iPhone native client:
l
default (set as default)
NumbersAndPunctuation
URL
DigitPad
PhonePad
NamePhonePad
EmailAddress
On Mobile Web and SPA platform, the available keyboard types are as follows:
l
default (set as default)
digitpad
emailpad
urlpad
telpad
search
On Mobile Web and SPA platform, the available keyboard types are as follows:
l
Default - Specifies the default keyboard type.
Chat - Specifies the keyboard which is helpful for chatting.
Url - Specifies the keyboard which is helpful for entering URL address.
Email Name or Address - Specifies the keyboard which is helpful for entering email or address.
Name or Phone Number - Specifies the keyboard which is helpful for entering names and numbers.
Postal Address - Specifies the keyboard which is helpful for entering postal address.
Telephone Number - Specifies the telephone number keyboard.
Digits - Specifies the keyboard which is helpful for entering numbers.
Search - Specifies the keyboard which is helpful for searching.
Formula - Specifies the keyboard which is helpful for entering text and formula.
Type
String
Read / Write
No
Accessible from IDE

Yes
l
iPhone
iPad
windows phone/windows kiosk
SPA(iPhone/Android/BlackBerry/Windows NTH)/Playbook
27.5.3 Type
Specifies the TextBox type as none or search.
Default: none (The TextBox behaves as an editable text component)
You can choose to change the TextBox to a search box by selecting search.
If you select search, the following additional property is displayed:
Auto Save
Specifies if the text that is entered in the search box must be saved automatically.
Default: false (the checkbox is not selected and the entered text is not saved automatically)
To save the text automatically, set the value to true (select the checkbox).
Type
String
Read / Write
No
Accessible from IDE

Yes
Available only on iPhone Mobile Web
28. Advanced Widgets

This section describes the following Advanced Component widgets:
l
Browser
Camera
Hz Image Strip
ImageGallery
Map
ObjectSelector3D
Phone
PickerView
SegmentedUI
Switch
SignatureCapture
Video
Charts2D3D
App Menu
29. Browser
You can use a Browser widget to display HTML content in the context of your application without navigating
away from the application or opening the native browser from your application.The HTML content can be
either static or obtained from a URL.
Browser widget provides you with an option to set Basic Properties, Layout Properties, Events, and Methods.
Basic Properties
Layout Properties
detectTelNumber
enableZoom
htmlString
id
info
isVisible
requestURLConfig
screenLevelWidget
containerHeight
containerWeight
margin
marginInPixel
Events
Methods
handleRequest
onFailure
onSuccess
scrollingEvents
canGoBack
canGoForward
clearHistory
goBack
goForward
reload
Creating a Browser using a constructor: kony.ui.Browser

Var webtemp = new kony.ui.Browser(basicConf, layoutConf, pspConf)
l
they are ignored
The following is the appearance of the Browser widget on various platforms with an external URL:
Platform
Appearance
Android
BlackBerry
Platform
Appearance
iPhone
Adding a Browser Widget from IDE

The steps involved in adding a Browser widget are as follows:
1. From the IDE, drag and drop the Browser widget onto a form (occupies the complete available width).
a. If you want to resize the Browser widget in the horizontal direction, place an HBox on the
form and drag and drop the Browser widget inside the HBox and resize accordingly.
b. If you want to resize the Browser widget in the vertical direction, place an HBox on the
form and place a VBox inside the HBox; and drag and drop the Browser widget inside the
VBox and resize accordingly.
2. Use the requestURLConfig property to specify the HTML content (static HTML content or a URL).
3. (Optional) If you choose to display HTML content from a URL, specify onfailure and onsuccess
Events.
4. (Optional) You can choose to display a loading screen while the content is being loaded from a URL.
For more information about the loading screen, see the Windows Library section of the Kony API
Reference Guide.
5. (Optional) On iPhone platform, you can move back and forward through the web page history by using
the Browser Methods.
The Browser widget has the following important considerations:
l
On iOS and Android platforms, when the Browser widget is set as non-screen level widget and you
keep some widgets before browser and after browser then double scrolling issue will be seen which is
native iOS issue. We recommend you to use browser widget as screen level widget and move other
widgets to header or footer of the form.
The Browser widget, unlike other widgets, is considered to be "heavy" widget as far as memory and
performance is considered.
The Browser widget uses a lot of initial RAM. The RAM usage grows in proportion to the number of
images and static text rendered.
If there are multiple instances of the Browser widget in the same application, there may be issues
related to sharing of information. For example, cookies etc.
You must not place multiple Browser widgets in a screen. As a guideline, you must not have more than
two Browser widgets in an application.
You must not use the Browser widget as a RichText widget. It should only be used to display large
HTML content.
You must avoid using the Browser widget to create an application which looks and behaves like a mini
web browser. Users normally expect to use the native browser to browse web content. Hence,
replicating this functionality within your application is not recommended.
On BlackBerry device placing widgets below the browser widget can lead to focus issues especially
when using the trackpad or the trackball.
On BlackBerry platform, when a popup screen is displayed over the browser widget, then the browser
widget does not appear until the popup is closed.
Server side Mobile Web platform does not support Browser widget in startup form.
On SPA platform, <script> tag is not supported.
On SPA platform, to get a formatted bullet list in the browser, add the below css before the browser
content.
<style>#[formname]_[browserwidgetid]> ul, li{list-style-type: initial;

list-style-position: inside; list-style-image: initial;}</style>
//For example
<style>#frmMain_browserMain> ul, li{list-style-type: initial; list-st
yle-position: inside; list-style-image: initial;}</style>
29.1 Browser - Basic Properties

The basic properties for Browser Widget are as follows:
l
detectTelNumber
enableZoom
htmlString
id
info
isVisible
requestURLConfig
screenLevelWidget
29.1.1 detectTelNumber
Specifies if the Browser widget must support the detection of phone numbers in the web page and display the
phone numbers as clickable Phone links. If you click the Phone link, the Phone application launches and dials
the number.
Default: true
If set to false, the Browser does not detect the Phone numbers.
If set to true, the Browser detects the phone numbers and displays them as links on the Phone.
Syntax
JavaScript: detectTelNumber
Lua: detecttelnumber
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Browser widget with detectTelNumber:true
var webBasic = {id : "browserID", isVisible:true, screenLevelWidget: false,
detectTelNumber:true};
var webLayout = {containerWeight:100};
//Creating the Browser.
var browser = new kony.ui.Browser(webBasic, webLayout, {});
//Reading the detectTelNumber of the Browser
alert("Browser detectTelNumber ::"+browser.detectTelNumber);
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango), BlackBerry, and BlackBerry 10 platform.
Note: On BlackBerry platform (7 and below), the default value is set based on the device constraints.
29.1.2 enableZoom
Specifies if Zoom (ability to change the scale of the view area) must be enabled.
Default: false
If set to true, the Zoom feature is enabled.
If set to false, the Zoom feature is disabled.
Default: false (the checkbox is not selected and Zoom is not enabled)
Syntax
JavaScript: enableZoom
Lua: enablezoom
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Browser widget with enableZoom:true
var webBasic = {id: "browserID", isVisible:true, screenLevelWidget: false,
enableZoom:true};
//Reading the enableZoom of the Browser
alert("Browser enableZoom ::"+browser.enableZoom);
Accessible from IDE

Yes
Available on all platforms except BlackBerry and all Windows platforms.
29.1.3 htmlString
Specifies the HTML content for the Browser widget.
Syntax
JavaScript: htmlString
Lua: htmlstring
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Browser widget with htmlString:"<html>Welc
ome</html>"
htmlString:"<html>Welcome</html>"};
//Reading the htmlString of the Browser

alert("Browser htmlString ::"+browser.htmlString);
Accessible from IDE

Yes
29.1.4 id
id is a unique identifier of Browser widget consisting of alpha numeric characters. Every Browser should have
a unique id within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Browser widget with id :"browserID"
var webBasic = {id :"browserID",isVisible:true, screenLevelWidget:false};
var browser = new kony.ui.Browser(webBasic,webLayout,{});
//Reading the id of the Browser
alert("Browser id ::"+browser.id);
Accessible from IDE

Yes
29.1.5 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a Browser widget with info property.
var webBasic = {id :"browserID", isVisible:true, screenLevelWidget:false};
browser.info = {key:"zoom of browser"};
//Reading the info of the Browser
alert("Browser info is ::"+browser.info);
Accessible from IDE

No
29.1.6 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Browser widget with isVisible:true
var webBasic = {id : "browserID", isVisible:true, screenLevelWidget: fals
e};
Accessible from IDE

Yes
29.1.7 requestURLConfig
Specifies the configurations for the requested URL in key-value pairs as a JavaScript object or Lua table.
The following are the keys that are accepted in this object.
l
URL - Mandatory
Specifies the initial URL that must be requested from the server. The URL must begin with http:// .
l
requestMethod - Optional
Specifies the HTTP method to use for requesting the initial URL. You can choose either:
l
BROWSER_REQUEST_METHOD_GET (Default)
Note: SPA and Desktop Web platforms supports BROWSER_REQUEST_
METHOD_GET option only.
BROWSER_REQUEST_METHOD_POST
requestData - Optional
Specifies the key-value pairs that must be sent to the initial URL. It accepts an array of array. For
example,
[["key1","value1"],["key2","value2"],.....,["keyn", "valuen"]]
Syntax
JavaScript: requestURLConfig
Lua: requesturlconfig
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Browser widget with requestURLConfig:urlCo
nf.
var urlConf = {URL: "https://www.google.co.in/", requestMethod:constants.B
ROWSER_REQUEST_METHOD_GET};
requestURLConfig:UrlConf};
//Reading the requestURLConfig of the Browser.
alert("Browser requestURLConfig ::"+browser.requestURLConfig);
Accessible from IDE

Yes
Specifies whether the widget should occupy the whole container or not when your Browser widget has a large
HTML content to display. You must set the value to true for your Browser widget occupy the complete Form
and results in a good user experience.
If set to false, a scroll bar appears on the Browser widget and the Form resulting in a bad user experience
while scrolling.
Note: You must not place more than one Browser widget as a screen level widget inside a Form. Also, if you
choose to make a Browser widget a Screen Level Widget, you must place only the Browser widget in the
Form and must not place any other widgets in the Form.
Default: false
If set to true, the widget occupies the whole container.
If set to false, the widget does not occupy the whole container.
Few guidelines for using screenLevelWidget property for Browser widget.
l
Placing any widgets below the Browser widget on a form is not advised as this leads to double scrolling
issues. Use Browser widget as screen level widget and place the rest of the widgets as part of headers
and footers.
l
In order to control the height of the Browser widget, place browser widget as screen level widget inside
the ScrollBox and control the height of the ScrollBox.
On iPhone, Android, and Windows platforms, if this property is set to true, the following are applicable:
iPhone
When a browser widget is used on the form, make sure that all other widgets are part of header
or footer of the form.
Android
Only the widgets placed above the Browser widget (which is a screen level widget) are visible. The
widgets placed below the Browser widget are not visible when rendered.
Windows
The widgets placed above and below the Browser widget (which is a screen level widget) are
not visible when rendered.
Note: If you configure Application level Header and Footer, they will be visible even if the browser is
a screen level widget.
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Browser widget with screenLevelWidget:false
var webBasic = {id : "browserID", isVisible:true, screenLevelWidget:false};
//Reading the screenLevelWidget of the Browser
alert("Browser screenLevelWidget ::"+browser.screenLevelWidget);
Accessible from IDE

Yes
Available on all platforms except BlackBerry, BlackBerry 10, Desktop Web, and SPA
29.2 Browser - Layout Properties

The layout properties for Browser Widget are as follows:
l
containerHeight
containerWeight
margin
marginInPixel
Note: In Windows Phone platform, when screenLevelWidget property is set to false, the Browser widget
occupies 500 px. When screenLevelWidget property is set to true it occupies form height. There is no
change in Windows Tablet and Windows Kiosk platforms.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining properties for a Browser widget with containerHeight:100.
var webLayout = {containerHeight:100, margin:[10,10,10,10]};
//Reading the containerHeight of the Browser.

alert("Browser containerHeight ::"+browser.containerHeight);
Accessible form IDE

No
l
CONTAINER_HEIGHT_BY_FORM_REFERENCE: The Browser height is calculated based on the

height of the Form excluding headers and footers. This property doesn't have any effect if the Browser
widget is placed inside a popup or headers/footers.
CONTAINER_HEIGHT_BY_PARENT_WIDTH: Use this option if the Browser is placed inside a Box.

Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining properties for a Browser widget with containerHeightReference:c
onstants.CONTAINER_HEIGHT_BY_PARENT_WIDTH.
var webLayout = {containerHeight:100, margin:[10,10,10,10], containerHeigh
tReference:constants.CONTAINER_HEIGHT_BY_PARENT_WIDTH};
Accessible from IDE

Yes
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining properties for a Browser widget with containerWeight:100.
var webLayout = {containerWeight:100, margin:[10,10,10,10]};
//Reading the containerWeight of the Browser.
alert("Browser containerWeight ::"+browser.containerWeight);
Accessible from IDE

No
29.2.4 margin
Note: In BlackBerry platform, right side margin is not supported.
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Browser widget with margin:[10,10,10,10]
var webLayout = {containerWeight:100, margin:[10,10,10,10]};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Browser widget with marginInPixel:true.
var webLayout = {containerWeight:100, margin:[10,10,10,10], marginInPixel:
true};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
29.3 Browser - Events

Browser Widget has the following events associated:
l
handleRequest
onFailure
onSuccess
scrollingEvents
29.3.1 handleRequest
An event callback which gets invoked by the platform before browser widget navigates to a new URL. This is
useful in scenarios where the developer wants to keep track of the URLs that the browser field navigates to.
For example, in a payment flow (that is, being executed inside a browser widget) on successful redirection to
a payment confirmation page the developer would like to take the user to a new native form.
Note: On iOS platform, whenever handleRequest is set to browser and request comes to browser widget to
load the url or html, then before loading the content, handle request is called. Also, whenever a user selects
any hyperlink then also handleRequest is called.
The return value from this function determines how the browser widget handles the original request. If a false
value is returned, then the browser widget continues navigation to the original URL and if the true value is
returned then the developer has to handle the request.
Syntax
JavaScript: handleRequest (eventobject, params)
Input Parameters
eventobject[widgetid] - Optional
A unique Id that identifies the browser widget.
params[Object] - Optional
An object that identifies the url parameters as key-values pair.
Following are the parameters of the object.
originalURL [String] - Optional
Specifies the original url.
queryParams[Object] - Optional
Specifies the dictionary containing the query parameters passed to the URL as key,
values in the dictionary.
requestMethod[String] - Optional - Supported only on iOS
Specifies the request method type. Following are the available options:
Constants.BROWSER_REQUEST_METHOD_GET
Constants.BROWSER_REQUEST_METHOD_POST
header[JSObject] - Optional - Supported only on iOS

Specifies a dictionary containing all the HTTP header fields.
Read / Write
Yes - (Write)
JavaScript Example
//The below function is the call back for handleRequest event
function handleRequestCallback(browserWidget,params)
{
kony.print("handleRequest event triggered");
kony.print("Original URL" + params ["originalURL"]);
kony.print("Request Method" + params ["requestMethod"]);
kony.print("Header" + JSON.stringify(params["header"]));
//Ignore this request and continue loading other URLs.
return false; //If false is returned, platform will load the originalu
rl in the browser widget.
}
frmobj.brw1.handleRequest = handleRequestCallback
l
iPhone
iPad
29.3.2 onFailure
An event callback which gets invoked by the platform when the given request URL is failed to load the data.
This event is called only for the given request URL, but not for the subsequent web navigation request
failures.
This event is also not called when htmlString is set to the web widget.
Syntax
JavaScript: onFailure
Lua: onfailure
Read / Write
JavaScript Example
//The below function is the call back for onFailure event
function onFailureCallBck(browser)
{
alert("onFailure event triggered");
}
//Defining the properties for a Browser widget with requestURLConfig:reque
stUrlConf which is JS object defined below.
var requestUrlConf = {URL: "https://www.google.co.in/", requestMethod:cons
tants.BROWSER_REQUEST_METHOD_GET};
requestURLConfig:requestUrlConf, onFailure:onFailureCallBck};
//Reading the onFailure of the Browser
alert("Browser onFailure ::"+browser.onFailure);
User Guide.
Available on all platforms except Windows Kiosk, Desktop Web, on all Server side Mobile Web, and
SPA.
29.3.3 onSuccess
An event callback which gets invoked by thee platform when the given request URL is successful in loading
the data. This event is called only for the given request URL, but not for the subsequent web navigation
requests.
This event is also not called when htmlString is set to the web widget.
Syntax
JavaScript: onSuccess
Lua: onsuccessilure
Read / Write
JavaScript Example
//The below function is the call back for onSuccess event
function onSuccessCallBck(browser)
{
alert("onSuccess event triggered");
}
requestURLConfig:requestUrlConf, onSuccess:onSuccessCallBck};
//Reading the onSuccess of the Browser.
alert("Browser onSuccess ::"+browser.onSuccess);
User Guide.
Available on all platforms except Desktop Web, on all Server side Mobile Web, and SPA.
Specifies the scrolling events which gets called when scrolling reaches beginning of the widget or end of the
widget.
onReachingBegining: Gets called when scrolling reaches the beginning of the Browse
widget.
Signature
JavaScript: onReachingBegining(browser, scrollDirection)
onReachingEnd: Gets called when scrolling reaches the end of the Browse widget.
Signature
JavaScript: onReachingEnd(browser, scrollDirection)
Input Parameters
browser [widgetref] - Mandatory
scrollDirection - Mandatory
Specifies the direction in which the scroll box must scroll. Following are the available options:
l
SCROLL_VERTICAL: Specifies the browser must scroll vertical direction.
SCROLL_BOTH: Specifies the browser must scroll in both horizontal and vertical
direction.
Type
Read / Write
JavaScript Example
//The below is the callback function for onReachingBegining event which co
mes under scrollingEvents.
function onReachingBeginingCallBack(webwidget, scrollDirection)
{
alert("onReachingBegining event triggered");
}
//The below is the callback function for onReachingEnd event which comes u
nder scrollingEvents.
function onReachingEndCallBack(webwidget, scrollDirection)
{
alert("onReachingEnd event triggered");
}
//Defining the properties for a Browser widget with scrollingevents.

requestURLConfig:requestUrlConf, scrollingEvents:{onReachingBegining:onRea
chingBeginingCallBCk, onReachingEnd: onReachingEndCallBck}};
Accessible from IDE

No
Available on iPad platform.
29.4 Browser - Methods

Browser Widget has the following methods associated with it:
l
canGoBack
canGoForward
clearHistory
goBack
goForward
reload
29.4.1 canGoBack
This method specifies whether the browser can navigate back into history. If the browser cache is empty then
this method returns false and the goBack method has no effect.
Signature
JavaScript: <widgetid>.canGoBack()
Lua: webwidget.cangoback(widgetref)
Input Parameters
Return Values
This method has the following return values.
status [Boolean]
true - if the browser cache is not empty.
false - if the browser cache is empty.
JavaScript Example
stUrlConf.
requestURLConfig:requestUrlConf};
//calling canGoBack method
var canGoBck = browser.canGoBack();
alert("canGoBack?::"+canGoBck);
Available on all platforms except SPA, Desktop Web, and on all Server side Mobile Web
29.4.2 canGoForward
This method specifies whether the browser can navigate forward into history. If the browser cache is empty
then this method returns false and goForward method has no effect.
Signature
JavaScript: <widgetid>.canGoForward()
Lua: webwidget.cangoforward(widgetref)
Input Parameters
Return Values
This method has the following return values.
status [Boolean]
true - if the browser cache is not empty.
false - if the browser cache is empty.
JavaScript Example
stUrlConf.
//calling canGoForward method
var canGoForwrd = browser.canGoForward();
alert("canGoBack?::"+canGoForwrd);
29.4.3 clearHistory
This method clears the page history of the specified Browser.
Signature
JavaScript: <widgetid>.clearHistory()
Lua: webwidget.clearhistory(widgetref)
Input Parameters
Return Values
None
JavaScript Example
stUrlConf.
//Calling clearHistory method to clear the browser history of a browser br
ws1 which is in Form frm1.
browser.clearHistory(frm1.brws1)
Available on all platforms except on all Server side Mobile Web, SPA, Desktop Web, BlackBerry 10, and
iPhone
29.4.4 goBack
This method provides you with the ability to navigate one step back in the browser history. If the history stack
is empty then this method has no effect.
Note: This method can be used only when canGoBack returns true.
Signature
JavaScript: <widgetid>.goBack()
Lua: webwidget.goback(widgetref)
Input Parameters
Return Values
None
JavaScript Example
//calling goBack method.
browser.goBack()
29.4.5 goForward
This method provides you with the ability to navigate one step forward in the browser history. If there are no
visited links in the history stack, then this method has no effect.
Note: This method can be used only when canGoForward returns true.
Signature
JavaScript: <widgetid>.goForward()
Lua: webwidget.goforward(widgetref)
Input Parameters
Return Values
None
JavaScript Example
//calling goForward method.
browser.goForward()
Available on all platforms except SPA, Desktop Web, and Server side Mobile Web
29.4.6 reload
This method provides you with the ability to reload the current web page.
Signature
JavaScript: <widgetid>.reload()
Lua: webwidget.reload(widgetref)
Input Parameters
Return Values
None
JavaScript Example

//calling reload method
browser.reload();
Available on all platforms except on all Server side Mobile Web, SPA, and Desktop Web
29.5 Browser - Deprecated Properties

The deprecated properties for Browser widget are as follows:
l
masterData
29.5.1 masterData
Specifies the content of the browser. The content can be static HTML or a URL.
Depending upon your requirement, you can either choose to enter the HTML content in the Content field or
select the URL option to specify an initial URL.
If you select the URL option, the following properties are made available:
URL
Specifies the initial URL that must be requested from the server. The URL must begin with http:// .
Method
Specifies the HTTP method to use for requesting the initial URL. You can choose either the get or post
methods.
Default: get
Query Data
Specifies the key-value pairs that must be sent to the initial URL.
Type
String
Read / Write
Yes - (Write Only)
//To specify a URL for a browser widget with ID brws1 and in Form with ID
frm1, enter the following:
frm1.brws1.url="http://www.kony.com"
//To specify static HTML content for a browser widget with ID brws1 and in
Form with ID frm1, enter the following:
frm1.brws1.htmlstring="<html><body> Text with HTML tags </body></html>
Accessible from IDE

Yes
Available on all platforms except Mobile Web(basic) and Win Mobile6x.
30. Camera
A Camera widget appears as a button in a form. If you select the Camera widget, the phone camera is invoked
to capture an image (which you can choose to accept or discard) and is stored as a PNG (Portable Network
Graphics) image by default (JPEG in BlackBerry platform) with the original size.
Note: The Camera widget is not supported on all Server side Mobile Web, SPA, and Desktop Web
platforms.
The following are few examples where you can use a Camera widget:
l
Automobile Insurance - To capture the scene of an accident for claims
To capture VIN (Vehicle Identification Number)
Camera provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
an Event, and Methods.
Platform Specific
Properties
Basic Properties
Layout Properties
base64
compressionLevel
focusSkin
id
info
isVisible
maxSideOfTheImage
rawBytes
scaleFactor
skin
text
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Event
Methods
Deprecated
onCapture
closeCamera
releaseRawBytes
takePicture
Auto Store to disk
accessMode
cameraOptions
captureOrientation
enableOverlay
enablePhotoCropFeature
hoverSkin
imageFormat
nativeUserInterface
overlayConfig
toolTip
mode
Creating a Camera using a constructor: kony.ui.Camera

var mycamera = new kony.ui.Camera(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Defining the properties for a Camera.

var camBasic={id:"camera1", skin:"camSkin", focusSkin:"camFSkin", text:"Ca
mera", isVisible:true};
var camLayout={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5], p
var camPSP={enableOverlay:true};
//Creating the Camera.
var camera1 = new kony.ui.Camera(camBasic, camLayout, camPSP);
//Reading enableOverlay of Camera.
alert("Camera enableOverlay::"+camera1.enableOverlay);
Widget Appearance on Platforms:

The appearance of the camera widget with a text "Camera view" on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
iPhone
Platform
Appearance
Windows
Adding a Camera Widget from IDE

The steps involved in adding a camera widget are as follows:
1. From the IDE, drag and drop the camera widget onto a form (occupies the complete available width).
a. If you want to resize a camera widget in the horizontal direction, place an HBox on the
form and drag and drop the camera inside the HBox and resize accordingly.
b. If you want to resize a camera widget in the vertical direction, place an HBox on the form
and place a VBox inside the HBox; and drag and drop the camera widget inside the VBox
and resize accordingly.
2. Add text in the text property (for example, Take a Snap) for the camera widget.
Note: If you do not add the text in the text property, the camera widget will not be visible when
rendered.
3. (Optional) On iPhone and Android platforms, you can choose to save the captured image in JPEG
(Joint Photographic Experts Group) format by using the imageFormat property.
Note: If you choose the imageFormat as JPEG.
4. (Optional) On iPhone and Android platforms, you can customize the native camera view (by overlaying
forms on the native camera) by using the overlayConfig property.
5. (Optional) On iPhone, use the nativeUserInterface property to specify a customized interface.
6. After the camera is launched and an image is captured, the captured image is in the form of rawbytes.
The rawbytes of the captured image are available to an application until the application closes or until
the rawbytes are manually deleted.
(Optional) On iPhone platform, you can choose the accessMode property to specify if the rawbytes of
the captured image must be stored on the disk or in-memory.
If you want to store the rawbytes of the captured image on the device permanently, use the ds.save
API. To retrieve the rawbytes, use the ds.read API. For more information on ds.save and ds.read APIs,
see the Kony API Reference Guide.
Note: For optimization, the raw bytes property can be read only once. Once it is read, the platform releases
the handle.
The camera image handle is provided to the action handler and if the action handler does not store the image
handle, the image cannot be retrieved from the widget (the camera widget does not have the
getImageHandle method).
7. To delete the rawbytes, use the releaseRawBytes method.
Pitfalls
The following are the pitfalls to avoid for a camera:
l
If you delete the rawbytes using the releaseRawBytes method, you will not be able to access the
captured image.
On iPhone, the size of the captured image varies from device to device and is not the same. You must
take this factor into consideration when you are working with the image.
To have a consistent size of the captured image across all iPhone devices, you can use the
maxSideOfTheImage property to specify width and height of the captured image.
The following are the important considerations of the camera widget across all platforms and individual
platforms:
l
iPhone: The following are the important considerations:

l
You can down scale a captured image (using maxSideOfTheImage and the scaleFactor
properties) but cannot up scale a captured image.
The click events on camera Overlay form works only if hideControlBar property is set to true.
On iOS devices, due to technical limitation, avoid overlayForm option when nativeUserInterface
is set to true.
Using custom controls (like Tap anywhere) is not allowed with hideControlBar property is set to
true.
For overlay forms that require orientation works only if hideControlBar property is set to true.
Kony popup added to any of the overlay form widget must be anchored.
cameraOptions should not be modified in camera preview mode.
Only pre-show and post show events of the overlay form are respected.
Flash mode always on (constants.FLASH_MODE_ALWAYS_ON) is not supported. If set, it

will change to Flash mode as on (constants.FLASH_MODE_ON).
BlackBerry: The following are the important considerations:

l
Does not support the overlay form.
Will always create a file on the local file system.
The image format is always JPEG.
To avoid out of Memory errors, you must inform the users to set the ImageSize to small and
Quality to Low. These can be set using (Camera -> Options) on a blackberry device.
Android: The following are the important considerations:

l
Camera OverlayForm , displayOrientation is not respected in devices with OS versions < 3.0 ,
by default OverayForm is shown in Portrait mode.
The picture captured orientation is not respected in OS versions < 3.0, by default the picture is
captured in Landscape mode.
30.1 Camera - Basic Properties

The basic properties for Camera Widget are as follows:
l
base64
compressionLevel
focusSkin
id
info
isVisible
maxSideOfTheImage
rawBytes
scaleFactor
skin
text
30.1.1 base64
downloading, null/nil is returned.
Syntax
JavaScript: base64
Lua: base64
Type
Lua: UserData
Read / Write
JavaScript Example
//Using base64 property in a form frmOnclick.
function customhandlerbase64(camerawidget)
{
frmOnclick2.img1.base64 = camerawidget.base64;
frmOnclick2.show();
}
Accessible from IDE

No
30.1.2 compressionLevel
Specifies the compression level or picture quality with which the captured image must be stored. You can
specify the compression level value between 0 (best picture quality) and 100 (low picture quality).
Default: 0 (The image is stored with the best picture quality)
Note: Applicable only when the imageFormat is jpeg.
Note: On Android platform, compressionLevel property is applicable only when you set enableOverlay as
true.
Syntax
JavaScript: compressionLevel
Lua: compressionlevel
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with compressionLevel: 25.
mera", isVisible:true, compressionLevel: 25};
var camLayout={containerWeight:100, padding:[5,5,5,5], margin:[5,5,5,5],
paddingInPixel:true, marginInPixel:true, hExpand:true, vExpand:true};

var camPSP={};
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango), Windows Kiosk, and on all Server side
Mobile Web, SPA, and Desktop Web platforms
30.1.3 focusSkin
2. Mobile Web does not support this property, instead browser specific focus is applied.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Camera with focusSkin:"camFSkin".
var camPSP={};

//Reading focusSkin of Camera.
alert("Camera focusSkin::"+camera1.focusSkin);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, SPA, BlackBerry 10, and Desktop Web
platforms
30.1.4 id
id is a unique identifier of Camera consisting of alpha numeric characters. Every Camera should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Camera with id:"camera1".
var camPSP={};
//Reading id of Camera.
alert("Camera id::"+camera1.id);
Accessible from IDE

Yes
30.1.5 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a Camera with info property.
var camPSP={};

camera1.info = {key:"camera images"};
//Reading info of Camera.
alert("Camera info is ::"+camera1.info);
Accessible from IDE

No
30.1.6 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Camera with isVisible:true
var camPSP={};

//Reading isVisible of Camera
alert("Camera isVisible::"+camera1.isVisible);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, SPA, and Desktop Web platforms.
30.1.7 maxSideOfTheImage
Specifies the width of the camera picture/image. It is used to set the resolution (width * height) of the camera
picture. On Android platform, this property is applicable only when "enableOverlay" property is set to true. For
example, if maxSideOfTheImage = 1600, if the device has exact matching resolution (in width ie. 1600*1200),
then 1600 * 1200 resolution is used to set the camera picture size.
Syntax
JavaScript: maxSideOfTheImage
Lua: maxsideoftheimage
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with maxSideOfTheImage: 20.
mera", isVisible:true, maxSideOfTheImage: 20};
var camPSP={};
Accessible from IDE

No
Available on all platforms except Windows Phone (Mango), Windows Kiosk, Server side Mobile Web,
SPA, and Desktop Web platforms
30.1.8 rawBytes
Specifies the rawbytes representing an Image (usually the image captured from the camera) that can be used
as a background for the Camera. You cannot assign rawBytes directly to a button widget. The rawBytes has
to be assigned to an Image widget or Button widget that has image skin.
Syntax
Lua: rawbytes
Type
Lua: UserData
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Camera.
var camBasic={id:"camera1",skin:"camSkin", focusSkin:"camFSkin", text:"Cam
era", isVisible:true};
addingInPixel:true, marginInPixel:true, hExpand:true,vExpand:true};
var camPSP={};
//Reading rawBytes of Camera.

alert("Camera rawBytes::"+camera1.rawBytes);
Accessible from IDE

No
30.1.9 scaleFactor
Specifies the ratio by which the captured image is reduced. You can set the scale factor between 10 and 100.
If you set the scale factor as 100, no reduction takes place and the actual image is returned. If you set the
value as 10, an image which is reduced to 10% of the actual captured image is returned.
Note: On Android platform, scaleFactor property is applicable only when you set enableOverlay as true.
Syntax
JavaScript: scaleFactor
Lua: scalefactor
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with scaleFactor: 25.
mera", isVisible:true, scaleFactor: 25};
var camPSP={};

Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango), Windows Kiosk, Server side Mobile Web,
SPA, and Desktop Web platforms
30.1.10 skin
Specifies the look and feel of the Camera when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Camera with skin:"camSkin"
var camPSP={};
//Reading skin of Camera.
alert("Camera skin::"+camera1.skin);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, SPA, BlackBerry 10, and Desktop Web
platforms.
30.1.11 text
Specifies a general or descriptive text for the Camera widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Camera with text:"Camera"
mera",isVisible:true};
var camPSP={};
//Reading text of Camera
alert("Camera text::"+camera1.text);
Accessible from IDE

Yes
30.2 Camera - Layout Properties

The layout properties for Camera Widget are as follows:
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a Camera with containerWeight:100.
var camBasic={id:"camera1",skin:"camSkin", focusSkin:"camFSkin", text:"Cam
var camPSP={};
//Reading containerWeight of Camera.
alert("Camera containerWeight::"+camera1.containerWeight);
Accessible from IDE

No
Specifies the alignment of the text on the Camera with respect to its boundaries. A default value CONTENT_
center of the RichText )
l
CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the Camera.
CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the Camera.
CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the Camera.
CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the Camera.
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the Camera.
CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the Camera.
CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the Camera.

Camera.
CONTENT_ALIGN_BOTTOM_RIGHT - Specifies the text should align at bottom right of the Camera.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with contentAlignment:constants.CON
TENT_ALIGN_TOP_LEFT.
var camBasic={id:"Camera1",skin:"camSkin", focusSkin:"camFSkin", text:"Cam
addingInPixel:true, marginInPixel:true, contentAlignment:constants.CONTENT_
ALIGN_TOP_LEFT};
var camPSP={};
Accessible from IDE

Yes
30.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Camera with hExpand:true
var camBasic={id:"Camera1", skin:"camSkin", focusSkin:"camFSkin", text:"Ca
var camPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, SPA, and Desktop Web platforms
30.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Camera with margin:[5,5,5,5]
var camPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, SPA, and Desktop Web platforms
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Camera with marginInPixel:true
var camPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
30.2.6 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Camera with padding:[5,5,5,5].
var camPSP={};
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, BlackBerry 10, SPA, and Desktop Web
platforms
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Camera with paddingInPixel:true
var camPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
30.2.8 vExpand
Note: Server side Mobile Web does not support the Expand property. This is because a widget in a Mobile
Web cannot expand or contract based on the neighboring widget (default behavior of a widget in a Mobile
Web).
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Camera with vExpand:true
var camPSP={};
Accessible from IDE

Yes
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a Camera with widgetAlignment:constants.WIDG
ET_ALIGN_TOP_LEFT
addingInPixel:true, marginInPixel:true, widgetAlignment:constants.WIDGET_A
LIGN_TOP_LEFT};
var camPSP={};
Accessible from IDE

Yes
30.3 Camera - Platform Specific Properties

The platform specific properties for Camera Widget are as follows:
l
accessMode
cameraOptions
captureOrientation
enableOverlay
enablePhotoCropFeature
hoverSkin
imageFormat
nativeUserInterface
overlayConfig
toolTip
30.3.1 accessMode
Specifies how the captured image must be stored. This property is enabled when the launchMode is
overlayform for Android and Windows Phone.
Note: On Android Platform, this property is respected only if the enableOverlay is set to true and in
overlayConfig > Android> overlayForm is set to a form name.
Default:CAMERA_IMAGE_ACCESS_MODE_PUBLIC (except on Windows )
l
CAMERA_IMAGE_ACCESS_MODE_PUBLIC: The captured image is stored on the device as a

Image and is accessible to all the applications on the device. For example, the captured images are
accessible in ImageGallery.
CAMERA_IMAGE_ACCESS_MODE_PRIVATE: This is the default option for Windows. The

captured image is stored as an Image on the device and will not be accessible to any other application
on the device and remain private to the application.
CAMERA_IMAGE_ACCESS_MODE_INMEMORY: The captured camera image is stored in memory

and is never written to the disk.
Syntax
JavaScript: accessMode
Lua: accessmode
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with accessMode:constants.CAMERA_IM
AGE_ACCESS_MODE_PRIVATE

var camPSP={accessMode:constants.CAMERA_IMAGE_ACCESS_MODE_PRIVATE};
//Reading accessMode of Camera
alert("Camera accessMode::"+camera1.accessMode);
Accessible from IDE

Yes
l
iPhone
iPad
Windows Phone
Windows Kiosk
Windows Tablet
30.3.2 cameraOptions
Specifies the camera options that can be used on a form.
The following are the configurable properties:
l
flashMode : Enables you to control the flash on the device when the camera is turned on.
Note: Devices may have different flash capabilities that are dependent on the camera driver.
Default : constants.FLASH_MODE_AUTO
l
constants.FLASH_MODE_AUTO: Specifies the flash must be turned on when required.
constants.FLASH_MODE_ON: Specifies the flash must be turned on when you take a picture.
constants.FLASH_MODE_OFF: Specifies the flash must not be turned on even when you take
a picture.
constants.FLASH_MODE_ALWAYS_ON: Specifies the flash must not be turned on constantly

when the camera is open. On Android platform, this option is respected only when overlay form
is enabled.
hideControlBar : Enables you to show or hide the default control bar (capture and cancel buttons) of
the respective platforms. This feature is not supported in iPad.
Default : false
Note: For iOS < 7.0, when hideControlBar is set to true, there will be a blank space (black or white
color) in place of camera control bar in iPhone device. The space of the control bar depends on the
device model (iPhone 5 device has 96px and iPhone 4 has 54 px). It is recommended to note this
point while designing the overlay form for the camera.
captureButtonSkin : Specifies the skin for a captured button. This option is applicable on Android
platform only and is respected only when hideControlBar is set to true.
captureButtonText : Specifies the text for a captured button. This option is applicable on Android
platform only and is respected only when hideControlBar is set to true.
Syntax
JavaScript: cameraOptions
Type
Read / Write
JavaScript Example
//Defining the properties for a Camera with overlayConfig:{overlayForm:"fr
mSample", referenceImageToCrop:"refImg.png", tapAnywhere:false, imageSizeT
humbnail:false}.
var camPSP={cameraOptions:{flashMode:"constants.FLASH_MODE_ON", hideContro
lBar:true, captureButtonSkin:snap.png, captureButtonText:OK}};
//Reading overlayConfig of Camera.
alert("Camera overlayConfig::"+camera1.overlayConfig);
Accessible from IDE

No
l
iPhone
iPad
Windows Tablet
30.3.3 captureOrientation
Specifies the orientation of the captured image.
Note: This property works for complete image and not for cropped image. Thus it is considered only when
referenceImageToCrop is not provided. In cases, where referenceImageToCrop is provided, this property is
ignored.
Default: CAMERA_CAPTURE_ORIENTATION_DEFAULT
l
CAMERA_CAPTURE_ORIENTATION_LANDSCAPE: On the device the camera is always turned

sideways so that the height of the screen becomes width.
CAMERA_CAPTURE_ORIENTATION_PORTRAIT: On the device the camera is always displayed

such that the horizontal sides are shorter than vertical sides.
Syntax
Lua: accessmode
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with LANDSCAPE.
var camPSP={captureOrientation:constants.CAMERA_CAPTURE_ORIENTATION_LANDSC
APE};
//Reading captureOrientation of Camera.
alert("Camera captureOrientation::"+camera1.captureOrientation);
Accessible from IDE

Yes
l
iPhone
iPad
30.3.4 enableOverlay
The camera is launched with capability of over-lay a Form UI over the camera view.
Default : false
If set to true, the Camera preview is overlaid on the form.
If set to false, the Camera preview is not overlaid on the form.
Syntax
JavaScript: enableOverlay
Lua: enableoverlay
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Camera with enableOverlay:true
var camPSP={enableOverlay:true};
//Reading enableOverlay of Camera
alert("Camera enableOverlay::"+camera1.enableOverlay);
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
30.3.5 enablePhotoCropFeature
Enables you to crop the captured image manually.
Default: false
Note: In Windows Tablet platform, the default value is true.
If set to true, the photo crop feature is enabled.
If set to false, the photo crop feature is not enabled.
Note: This property is ignored when you set enableOverlay as true.
Syntax
JavaScript: enablePhotoCropFeature
Lua: enablephotocropfeature
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Camera with enablePhotoCropFeature:true
var camPSP={enablePhotoCropFeature:true};
//Reading enablePhotoCropFeature of Camera.
alert("Camera enablePhotoCropFeature::"+camera1.enablePhotoCropFeature);
Accessible from IDE

Yes
Available on Windows Phone (Mango) and Windows Kiosk platforms.
30.3.6 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE

Yes
This property is available on Windows Tablet platform
30.3.7 imageFormat
Specifies if the image must be stored as a PNG (Portable Network Graphics) or a JPEG (Joint Photographic
Experts Group) image.
Default: CAMERA_IMAGE_FORMAT_PNG
l
CAMERA_IMAGE_FORMAT_PNG : When you select this option the image is always stored as PNG
format.
CAMERA_IMAGE_FORMAT_JPEG : When you select this option the image is always stored as
JPEG format.
Syntax
JavaScript: imageFormat
Lua: imageformat
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Camera with imageFormat:constants.CAMERA_I
MAGE_FORMAT_PNG.
var camPSP={imageFormat:constants.CAMERA_IMAGE_FORMAT_PNG };

//Reading imageFormat of Camera.
alert("Camera imageFormat::"+camera1.imageFormat);
Accessible from IDE

Yes
l
iPhone
iPad
30.3.8 nativeUserInterface
Specifies if the camera must have the native interface on camera view (an interface with the default platform
controls for camera) or the user interface with custom options.
Default: true
if set to false, the user interface with custom options is displayed.
if set to true, the native interface of camera in respective platforms is displayed.
Note: On iOS devices, due to technical limitation, avoid overlayForm option when nativeUserInterface is
set to true.
Syntax
JavaScript: nativeUserInterface
Lua: nativeuserinterface
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Camera with nativeUserInterface:true.
var camBasic={id:"camera1", skin:"camSkin", focusSkin:"camFSkin",
text:"Camera", isVisible:true};
var camPSP={nativeUserInterface:true};
//Reading nativeUserInterface of Camera.
alert("Camera nativeUserInterface::"+camera1.nativeUserInterface);
Accessible from IDE

Yes
l
iPhone
iPad
30.3.9 overlayConfig
Specifies the overlay configuration parameters for overlaying a form.
The following are the configurable properties applicable to iOS, Windows Phone, and Android platforms:
l
overlayForm : Specifies the reference of the form to be rendered over the camera view. When this
option is set, the captureOrientation property is not respected.
Note: On iOS devices, due to technical limitation, avoid overlayForm option when nativeUserInterface is
set to true.
Default : None
referenceImageToCrop : Specifies the reference of the Image widget in the overlayForm which
guides the camera to crop the captured image to the referenceImage dimensions.
Default : None
tapAnywhere : Specifies to capture an image with a tap on the camera overlay view. This option is
applicable to Windows Phone and Android platforms only.
Default : false
captureButtonSkin : Specifies the skin for a captured button. This option is applicable to Android
platform only.
captureButtonText : Specifies the text for a captured button. This option is applicable to Android
platform only.
Note: For Windows Tablet platform, the call back event is executed only when you come back to the calling
form by selecting the Back button in app menu in Form overlay view.
Syntax
JavaScript: overlayConfig
Lua: overlayconfig
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a Camera with overlayConfig:{overlayForm:"fr
mSample", referenceImageToCrop:"refImg.png", tapAnywhere:false, imageSizeT
humbnail:false}.
var camPSP={overlayConfig:{overlayForm:"frmSample", referenceImageToCrop:"
refImg.png", tapAnywhere:false, captureButtonSkin:"snap.png", captureButto
nText:"Back"}};
//Reading overlayConfig of Camera.
alert("Camera overlayConfig::"+camera1.overlayConfig);
Accessible from IDE

Yes
l
iPhone
iPad
Windows Tablet
30.3.10 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Camera with toolTip:sample text
var camBasic={id:"camera1", isVisible:true, skin:"camskin", focusSkin:"cam
FSkin", text:"Click Here", toolTip:"sample text"};
var camLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hEx
var camPSP={};
Accessible from IDE

Yes
30.4 Camera - Event

The Camera Widget has the following event associated with it:
l
onCapture
30.4.1 onCapture
An event callback is invoked when the user captures a picture.
Signature
JavaScript: onCapture
Lua: oncapture
Read / Write
JavaScript Example
//The below function is the callback for onCapture event of the Camera wid
get.
function onCapturCalBck(camera)
{
//Write logic here
}
//Defining the properties for a Camera with id:"camera1"
var camBasic={id:"camera1", skin:"camSkin", focusSkin:"camFSkin",text:"Cam
era", isVisible:true, onCapture:onCapturCalBck};
var camPSP={};
Accessible from IDE

Yes
30.5 Camera - Methods

Camera has the following methods associated with it:
closeCamera
releaseRawBytes
takePicture
30.5.1 closeCamera
This method allows you to close the camera. But on Andoid platform, this method is applicable only when an
overlay form is enabled and is ignored when overlayForm is disabled.
Signature
JavaScript: closeCamera
Input Parameters
None
Return Values
None
Error Codes
No error codes
JavaScript Example
var camPSP={};
//Close camera method call.
camera1.closeCamera(); //It is suggested to use the closeCamera method, wh
en the camera is being dismissed after invoking the takePicture method.
l
iPad
iPhone
30.5.2 releaseRawBytes
This method allows you to delete the rawbytes for the image captured from the camera.
- Rawbytes once released cannot be used or released again.
- If multiple handles (variables pointing) to the same rawbytes exist, and if you release the rawbytes using
any one of those handles, the other handles become obsolete.
If you use this method, the captured image is deleted from the device irrespective of it being on the disk or inmemory.
Note: If you store the rawbytes of the captured image in some location on the device by using the ds.save
API; and you call this method, the rawbytes are deleted from the disk or in-memory, but the image stored in
the specific location remains intact (you must delete the stored image manually).
Signature
JavaScript: releaseRawBytes(rawbytes)
Lua: releaserawbytes(rawbytes)
Input Parameters
rawbytes [Number]- Mandatory
The rawbytes for the image captured from the camera.
Return Values
None
Error Codes
No error codes
JavaScript Example
var camPSP={};
//Release raw bytes method call.
camera1.releaseRawBytes(rawBytes);
l
iPad
iPhone
30.5.3 takePicture
This method allows you to capture the picture when the camera is in preview mode. But in Android platform,
this method is applicable only when an overlay form is enabled and is ignored when overlayForm is disabled.
Signature
JavaScript: takePicture
Input Parameters
None
Return Values
None
Error Codes
No error codes
JavaScript Example
var camPSP={};
//Take picture method call.
camera1.takePicture();
l
iPad
iPhone
30.6 Camera - Deprecated Properties

The deprecated properties for Camera widget are as follows:
l
Auto store to disk
mode
30.6.1 Auto store to disk

Specifies if the rawbytes of the captured image must be stored on the disk or in-memory.
Default: true (the checkbox is selected and the rawbytes of the captured image is stored on the disk)
If you leave the default option (true) unchanged, the rawbytes is the handle to the image stored on the disk.
If you do not want the captured image to be stored on the disk and want to store the rawbytes in in-memory
(For example, for a Financial Application you might not prefer to store the rawbytes on the disk), change the
value to false (clear the checkbox).
Note: If your application uses the rawbytes for a very short time, we recommend that you set the value to
false and delete the rawbytes after its purpose is served by using the releaserawbytes method.
If you set the value to false, the rawbytes is the handle to the actual image data.
Note: The rawbytes of the captured image are available to an application until the application closes or until
the rawbytes are manually deleted. For a good user experience, we recommend that you delete the
rawbytes of the captured image after its purpose is served.
To delete the rawbytes of the captured image from the disk or in-memory use the releaserawbytes method.
If you want to store the rawbytes of the captured image on the device permanently, use the ds.save API. To
retrieve the rawbytes, use the ds.read API. For more information on ds.save and ds.read APIs, see the
Kony API Reference Guide.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
l
iPad
iPhone
Windows Phone/Windows Kiosk - This property is not supported on Kiosk .
30.6.2 mode
Specifies the viewing mode of the camera as native or overlay.
If you select the Mode as native, the native camera application is launched for image capture.
If you select the Mode as overlay, a form is overlaid over the camera preview.
Note: You can use the overlay form when you are developing a Remote Deposit Capture application (a
banking application using which you can deposit a bank check remotely without going to a bank).
If you select the Mode as overlay, the following properties are enabled:
Overlay Form (Applicable on iPhone, iPad, Android, and Windows Phone(mango))

Specifies the form that must be overlaid on the camera preview. All the forms that are available are listed
in the drop-down. You can select the desired form from the list.
Note: If you select the Mode as overlay and do not specify an overlay form, the camera widget does
not appear when rendered.
If you select an overlay form, the following property is made available:
Image Widget
Specifies the image widget (which is already available in the overlay form) that must be used as
the overlay on the camera. Based on the image widget, the captured image is cropped (only the
portion of the captured image which is within the image widget is saved).
Default: None (the captured image is not cropped)
If you want to crop the captured image, select the widget ID that you want to use as a reference
for cropping the image from the drop-down list.
Capture Button Text (Applicable only on Android)

Specifies the text for the capture button.
Capture Button Skin (Applicable only on Android)

Specifies the skin for the capture button.
Tap Anywhere (Applicable on Android and Windows Phone(mango))

Specifies if the image must be captured when there is a tap on the camera preview screen.
Default: false (the image is not captured if there is a tap on the camera preview screen. The image is
captured with the Capture Button)
If you want to be able to capture an image by tapping the camera preview screen, select true.
Note: On iPhone platform, to enable the Tap Anywhere feature, go to Project Properties > Native
App> iPhone/iPad and set the camera Settings to true.
Image Type
Specifies if the image must be stored as a PNG (Portable Network Graphics) or JPEG (Joint
Photographic Experts Group) image. Click here for more information about this property.
Access Mode (Applicable on Android and Windows Phone(mango))

Specifies how the captured image must be stored. You can select one of the following options:
Public
This is the default selection value. If you leave the selection unchanged, the captured image is
stored on the device and is visible to all the applications on the device (For example, Phone
Image Gallery).
Private
If you select this option, the captured image will not be visible to any other application on the
device. The captured image will remain private to the application (any application that is using
the camera widget).
In Memory
If you select this option, the captured camera image is stored in-memory and not written to the
disk. The in-memory image can be accessed through the rawbytes property or the base64
property. When you access this image for the first time using either of these properties, the
reference to in-memory bytes is removed from the camera widget.
Note: When you set the Access Mode as In Memory, ensure to call releaserawbytes method to
free the memory of the rawbytes.
Image Size (Applicable only Windows Phone)

Specifies the size of the image to be captured. You can select one of the following options:
thumbnail
This is the default value. The resolution of the image is low and occupies less memory.
cameradefault
Specifies the resolution of the image as set in the device.
The following images illustrate the view mode of a camera on an Android device with and without a
customized overlay form:
Without Overlay
With Overlay
Type
String
Read / Write
No
Accessible from IDE

Yes
l
iPad
iPhone
Windows Phone/Windows Kiosk - Overlay property is supported only on mango.
31. HorizontalImageStrip
HorizontalImageStrip also called as Hz Image Strip displays a list of images which are aligned side-by-side in
the horizontal direction. You can scroll through the Hz Image Strip to view the next or previous set of images.
You can use an Hz Image Strip to display a set of images to give an idea to the user about the available
products or a location (for example, in a Travel Application, you can add images of popular tourist destinations
or add images of the different suites available in a hotel).
Hz Image Strip widget provides you with an option to set Basic Properties, Layout Properties, Platform
Specific Properties, Events, and Methods.
Platform Specific
Properties
Basic Properties
Layout Properties
arrowConfig
data
focusSkin
id
imageWhenFailed
imagewhileDownloading
info
isVisible
selectedIndex
selectedItem
showArrows
showScrollbars
skin
spaceBetweenImages
viewConfig
viewType
containerWeight
imageScaleMode
margin
marginInPixel
padding
paddingInPixel
referenceHeight
referenceWidth
widgetAlignment
hoverSkin
toolTip
Events
Methods
Deprecated
onSelection
preOnclickJS
postOnclickJS
addAll
frameHeight
addDataAt
height
removeAll
width
removeAt
setData
setDataAt
Creating an HorzontalImgStrip using a constructor: kony.ui.HorzontalImageStrip2

var HorizontalImgStrip = new kony.ui.HorizontalImageStrip2 (basicConf, lay
outConf, pspConf)
l
they are ignored.
JavaScript Example
function onSelectionCallBack(hIS)
{
}
//Defining the properties for Image strip with onSelection:onSelectionCalB
ck
var hISBasic={id:"hIS",skin:"hISkn", focusSkin:"hISknFocus", isVisible:tru
e,selectedIndex:1, imageWhileDownloading:"img.png",imageWhenFailed:"img3.p
ng", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"},{"imagekey":"
image2.png"}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIEW_
TYPE_COVERFLOW, showArrows:true, showScrollbars:true, onSelection:onSelect
ionCallBack};
var hISLayout={padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:true, m
arginInPixel:true, referenceWidth:100, referenceHeight:100, imageScaleMode
:constants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS, containerWeight:100};
var hISPSP={};
//Creating the Horizontal Image strip.
var hIS=new kony.ui.HorizontalImageStrip2(hISBasic, hISLayout, hISPSP);
//Reading onSelection of Horizontal Image strip.
alert("Horizontal Image strip onSelection::"+hIS.onSelection);
kony.ui.HorzontalImageStrip .
var HorizontalImg1 = new kony.ui.HorizontalImageStrip (basicConf, layoutCo
nf, pspConf)
Adding an Hz Image Strip from IDE
The steps involved in adding an Hz Image Strip are as follows:
1. From the IDE, drag and drop the Hz Image Strip onto a Form (occupies the complete available width).
a. If you want to resize the Hz Image Strip in the horizontal direction, place an HBox on the Form
and drag and drop the Hz Image Strip inside the HBox and resize accordingly.
b. If you want to resize the Hz Image Strip in the vertical direction, place an HBox on the Form and
place a VBox inside the HBox; and drag and drop the Hz Image Strip inside the VBox and resize
accordingly.
2. Specify the images (local or remote) that must be displayed using the data property.
Note: For a good user experience, you must add images of the same width and height.
Note: To specify local images, you must add the PNG or JPEG files (the file names must follow a particular
naming convention) to the resources folder of the Application. For more information on how to add these
files, see the Working with Resources section of the Kony Studio User Guide.
3. (Optional) If you are specifying remote images, you can use the following properties as per your
requirement:
l
imageWhenFailed: Specifies the image to indicate that the image (that is being downloaded) is
not available.
imageWhileDownloading: Specifies the image to indicate that the download is taking place over
4. Specify the desired spaceBetweenImagespace.

5. Specify the onSelection event.
You can customize the appearance of the Hz Image Strip by using the following properties:
l
skin: Specify the skin to be applied to the images in the Hz Image Strip.
focusSkin: Specify the skin to be applied to the individual image in the Hz Image Strip when in focus.
The following are the important considerations of an Hz Image Strip:
l
For a good user experience, you must add images of the same width and height.
You can scroll through one or more images at a time (platform dependent).
If you reach the end of an image strip and if there are additional images, a network call is placed to get
the additional images.
In Android platform, images are displayed from the middle of the widget.
For Symbian, HzImageStrip always uses an image size of 64x64 pixels.
31.1 HorizontalImageStrip - Basic Properties

The basic properties for HorizontalImageStrip Widget are as follows:
l
arrowConfig
data
focusSkin
id
imageWhenFailed
info
isVisible
selectedIndex
selectedItem
showArrows
showScrollbars
skin
spaceBetweenImages
viewConfig
viewType
31.1.1 arrowConfig
Specifies the configurable arrow properties of the HorizontalImageStrip. This property is available only when
showArrows is set to true.
l
leftArrowImage : Accepts the image to be set as left arrow.
leftArrowFocusImage : Accepts the image to be set as left arrow when in focus.
rightArrowImage : Accepts the image to be set as right arrow.
rightArrowFocusImage : Accepts the image to be set as right arrow when in focus.
Note: The options leftArrowFocusImage and rightArrowFocusImage are not supported in BlackBerry,
Mobile Web, and SPA platforms.
Syntax
JavaScript: arrowConfig
Lua: arrowconfig
Type
Lua: UserData
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with arrowConfig.
var hISBasic={id:"hIS", skin:"hISkn", focusSkin:"hISknFocus", isVisible:tr
ue,selectedIndex:1, imageWhileDownloading:"img.png",
imageWhenFailed:"img3.png", spaceBetweenImages:20, data:[[{"imagekey":"ima

ge1.png"}, {"imagekey":"image2.png"},"imagekey"]], viewType:constants.HORI
ZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW, showArrows:true, showScrollbars:tru
e, arrowConfig:{"leftArrowImage":"lArrow.png", "leftArrowFocusImage" :"lAr
rowFoc.png", "rightArrowImage":"rArrow.png", "rightArrowFocusImage":"rArro
wFoc.png"}};
var hISLayout={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel:true, ma
rginInPixel:true, referenceWidth:100, referenceHeight:100, imageScaleMode:
constants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS, containerWeight:100};
var hISPSP={};
//Reading arrowConfig of Horizontal Image strip
alert("Horizontal Image strip arrowConfig::"+hIS.arrowConfig);
Accessible from IDE

Yes
31.1.2 data
Specifies the JSObject which represents the images to be rendered in horizontal image strip.
Data format : An array with two elements.
l
[0] is the array of objects with hashes.
[1] is the image key's key in the data hash of [0].
Example
//Data format of JavaScript object
[
[
{"imagekey":"image1.png", accessibilityConfig:acObject},
{"imagekey": "image2.png", accessibilityConfig:acObject}, .....,
{"imagekey": "imagen.png", accessibilityConfig:acObject}
],
"imagekey"
]
Syntax
JavaScript: data
Lua: data
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with data:[[{"imageke
y":"image1.png"}, {"imagekey":"image2.png"}, "imagekey"]]
var hISBasic={id:"hIS", skin:"hISkn",focusSkin:"hISknFocus", isVisible:tru
e, selectedIndex:1, imageWhileDownloading:"img.png", imageWhenFailed:"img3
.png", spaceBetweenImages:20, data:[[{"imagekey":"image1.png", accessibili
tyConfig:acObject}, {"imagekey":"image2.png", accessibilityConfig:acObjec
t}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVER
FLOW, showArrows:true, showScrollbars:true};
var hISPSP={};
//Reading data of Horizontal Image strip
alert("Horizontal Image strip data::"+hIS.data);
Accessible from IDE

Yes
31.1.3 focusSkin
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with focusSkin:"hISkn
Focus"
var hISBasic={id:"hIS",skin:"hISkn",focusSkin:"hISknFocus", isVisible:true
,selectedIndex:1, imageWhileDownloading:"img.png", imageWhenFailed:"img3.p
ng", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"}, {"imagekey":
"image2.png"}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIEW_
TYPE_COVERFLOW, showArrows:true, showScrollbars:true};
var hISPSP={};
//Reading focusSkin of Horizontal Image strip.
alert("Horizontal Image strip focusSkin::"+hIS.focusSkin);
Accessible from IDE

Yes
31.1.4 id
id is a unique identifier of HorizontalImageStrip consisting of alpha numeric characters. Every
HorizontalImageStrip should have a unique id within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Horizontal Image strip with id:"hIS"
ue, selectedIndex:1, imageWhileDownloading:"img.png", imageWhenFailed:"img
3.png", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"}, {"imageke
y":"image2.png"}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_V
IEW_TYPE_COVERFLOW, showArrows:true, showScrollbars:true};
var hISPSP={};
//Reading id of Horizontal Image strip
alert("Horizontal Image strip id::"+hIS.id);
Accessible from IDE

Yes
resources folder.
Syntax
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with imageWhenFailed:
"img3.png"
.png", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"}, {"imagekey
":"image2.png"}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VI
EW_TYPE_COVERFLOW, showArrows:true, showScrollbars:true};
var hISPSP={};
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web and Windows Kiosk platforms
Syntax
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with imageWhileDownlo
ading:"img.png"
.png", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"},{"imagekey"
:"image2.png"}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIE
W_TYPE_COVERFLOW, showArrows:true, showScrollbars:true};
var hISPSP={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web and Windows Kiosk platforms
31.1.7 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with info property.
var hISLayout={padding:[5,5,5,5], paddingInPixel:true, referenceWidth:100,
referenceHeight:100, imageScaleMode:constants.IMAGE_SCALE_MODE_FIT_TO_DIME
NSIONS, containerWeight:100};
var hISPSP={};
hIS.info = {key:"horizontal images"};
//Reading info of Horizontal Image strip
alert("Horizontal Image strip info is ::"+hIS.info);
Accessible from IDE

No
31.1.8 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with isVisible:true
var hISBasic={id:"hIS",skin:"hISkn",focusSkin:"hISknFocus", isVisible:true,
selectedIndex:1, imageWhileDownloading:"img.png", imageWhenFailed:"img3.pn
g", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"}, {"imagekey":"
var hISPSP={};
//Reading isVisible of Horizontal Image strip
alert("Horizontal Image strip isVisible::"+hIS.isVisible);
Accessible from IDE

Yes
Indicates the currently selected row in the HorizontalImageStrip. The index is with respect to the order in
which data is set with data property. Programmatically setting the selected Index will not make any visible
differences in the row, however it will bring the row at the index into the view able area on the screen. Setting it
to null/nil clears the selection state.In JavaScript the Index is '0' based and in Lua it is '1' based.
Note: If data contains the sections then the selectedIndex indicates the selected row index within the
section.
Syntax
Lua: selectedindex
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with selectedIndex:1
var hISBasic={id:"hIS",skin:"hISkn",
focusSkin:"hISknFocus",isVisible:true,selectedIndex:1, imageWhileDownloadi
ng:"img.png", imageWhenFailed:"img3.png",spaceBetweenImages:20, data:[[{"i
magekey":"image1.png"}, {"imagekey":"image2.png"},"imagekey"]], viewType:c
onstants.HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW,showArrows:true, showSc
rollbars:true};
var hISLayout={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel:true, ma
rginInPixel:true, referenceWidth:100, referenceHeight:100, imageScaleMode:
constants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS, containerWeight:100};
var hISPSP={};
//Reading selectedIndex of Horizontal Image strip
alert("Horizontal Image strip selectedIndex::"+hIS.selectedIndex);
Accessible from IDE

No
Returns the selected data object (input array) corresponding to the selected image of the
HorizontalImageStrip. If no image is selected, null/nil is returned.
Syntax
Lua: selecteditem
Type
Lua: UserData
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Horizontal Image strip with selectedIndex:1
":"image2.png"},"imagekey"]],viewType:constants.HORIZONTAL_IMAGESTRIP_VIEW_
TYPE_COVERFLOW,showArrows:true,showScrollbars:true};
var hISPSP={};
//Reading selectedItem of Horizontal Image strip
alert("Horizontal Image strip selectedItem::"+hIS.selectedItem);
Accessible from IDE

No
31.1.11 showArrows
Specifies the arrow images must be displayed on the left and right edges of the HorizontalImageStrip.
Default: false
If set to true, the arrows are displayed.
If set to false, the arrows are not displayed.
Syntax
JavaScript: showArrows
Lua: showarrows
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with showArrows:true
EW_TYPE_COVERFLOW,showArrows:true, showScrollbars:true};
:constants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS,containerWeight:100};
var hISPSP={};
//Reading showArrows of Horizontal Image strip
alert("Horizontal Image strip showArrows::"+hIS.showArrows);
Accessible from IDE

Yes
Specifies if the scrollbars must be visible all the time.
Default: As per native platform behavior.

Syntax
Lua: showscrollbars
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with showScrollbars:t
rue
EW_TYPE_COVERFLOW,showArrows:true, showScrollbars:true};
var hISPSP={};
//Reading showScrollbars of Horizontal Image strip
alert("Horizontal Image strip showScrollbars::"+hIS.showScrollbars);
Accessible from IDE

Yes
31.1.13 skin
Specifies the look and feel of the HorizontalImageStrip when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with skin:"hISkn"
var hISBasic={id:"hIS", skin:"hISkn", focusSkin:"hISknFocus",isVisible:tru
:"image2.png"}, "imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIE
var hISPSP={};
//Reading skin of Horizontal Image strip
alert("Horizontal Image strip Skin::"+hIS.skin);
Accessible from IDE

Yes
Specifies the space between the images in the horizontal image strip.
Syntax
JavaScript: spaceBetweenImages
Lua: spacebetweenimages
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with spaceBetweenImag
es:20
var hISPSP={};
Accessible from IDE

Yes
31.1.15 viewConfig
Specifies the view configuration properties for various view types in the horizontal image strip. Following are
the available view types:
l
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW : The cover flow view enables you to

flip through the images placed in a horizontal Image strip and bring the associated images into view.
This property accepts a JSObject with the below key-value pairs:
l
projectionAngle [Number]:Specifies the angle in degrees between a row except at center and at
z-axis. When the projection angle is 0, all the rows are aligned along z-axis one behind the other.
When previewed, it only shows one row at center. When projection angle is 90, all the rows are
aligned along x-axis side by side. If the value entered is negative then the resultant angle is 90 +
entered value. For example, if projection angle is -30 then resultant projection angle is 90 - 30 =
60 degrees. It accepts a range between -90 and +90 only. (Available on Android only)
imageItemRotationAngle [Number]: Specifies the angle in degrees of rotation of each row along
its own y-axis. It accepts a range between 0 and 360. (Available only on android)
isCircular [Boolean]: When set to true, it specifies the widget to scroll endlessly (repeating the
first row after you reach the last row) and when set to false, it stops scrolling after you reach the
last row. (Available only on android)
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_ SLOTVIEW : This property accepts a JSObject with

the below key-value pairs:
l
flingVelocity: Accepts a number (in density independent pixels) representing the velocity at
which user flings the imagestrip in order to activate auto-flipping the images. Not mandatory
(Available only on android)
flipInterval: Accepts a number in milliseconds representing the time interval to wait before
flipping to the next image. This is applicable when auto-flipping is activated when user flings.
scrollDistance: Accepts a number (in density independent pixel) representing the touch scroll
distance to travel to consider for navigation between images. Not mandatory (Available only on
android)
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_STRIPVIEW : This property accepts a JSObject with

l
enableScrollBounce : A boolean to enable/disable the bouncing effect when the stripview

reaches the end of the scroll. Default value is true. (Available only on SPA).
Syntax
Lua: viewconfig
Type
Lua: Table
Read / Write
Accessible from IDE

Yes
31.1.16 viewType
Specifies the view type of Horizontal Image Strip.
Default: HORIZONTAL_IMAGESTRIP_VIEW_TYPE_STRIPVIEW
The below table shows the list of view types and their availability in different platforms:
viewType
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_
STRIPVIEW
SLOTVIEW
LINEAR
ROTARY
INVERTED_ROTARY
CYLINDRICAL
INVERTED_CYLINDRICAL
COVERFLOW
COVERFLOW2
STACK
PAGEVIEW
iPhone Android
BlackBerry /J2ME/
Windows
Phone/SPA
Windows BlackBerry
Kiosk
10
Yes
Yes
Yes
Yes
Yes
Yes
Yes
Yes
No
Yes
Yes
No
No
No
No
Yes
No
No
No
No
Yes
No
No
No
No
Yes
No
No
No
No
Yes
No
No
No
No
Yes
Yes
No
No
No
Yes
No
No
No
No
Yes
No
No
No
No
No
No
Yes
Yes
No
Following are the available view types:

l
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_STRIPVIEW: In this view the images are placed side

by side and looks as if the images are placed in a strip. You can scroll through the images and view the
desired image.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_ SLOTVIEW : In this view the images are displayed

one at a time. The images change with the left or right gesture. This view is useful when you want to
present a 360 degree view of an object.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_ LINEAR : Displays images in a linear view; which is

very similar to the existing views, where you can scroll the images horizontally. You can scroll across
the imagestrip by moving them forward or backward as shown in the figure.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_ROTARY : Displays an imagestrip that rotates around

the axis of reference, where the current image is projected inwards and the other images appear closer
to the user than the current image. There won't be any image skewing or tilting like in the cover flow
view.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_INVERTED_ROTARY : Displays an imagestrip that

rotates around the axis of reference, where the current image is projected inwards and the other images
appear closer to the user than the current image. There won't be any image skewing or tilting like in the
cover flow view.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_CYLINDRICAL : Displays an imagestrip as a cylinder.

All the images of the imagestrip form a horizontal cylinder (polygon) and the cylinder rotates based on
the user's gesture. In the Cylinder view, the image strip appear as if the user is viewing at the cylinder
from outside. Images get skewed as you move along the axis of reference of the cylinder. You can
rotate the image strip around the axis of reference as shown in the figure.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_INVERTED_CYLINDRICAL : Displays an imagestrip

as a cylinder. All the images of the imagestrip form a horizontal cylinder (polygon) and the cylinder
rotates based on user's gesture. In the Inverted Cylinder view, the image strip appear as if the user is
viewing the cylinder from inside. Images get skewed as you move the imagestrip along the axis of
reference. You can rotate the image strip around the axis of reference as shown in the figure.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW : Regular cover flow view. The cover

flow view enables you to flip through the images and bring the associated image into view. You can flip
through the images as shown in the figure.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW2 : Similar to the Cover flow view with

more skewing or tilting.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_STACK : Custom stack view where the image strip

appear as a stack. Images can be moved inside and outside the stack based on the user's gesture as
shown in the figure below.
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_PAGEVIEW : In this view the images are displayed

pagewise. You can scroll through the images and view the desired image. If you do not specify the
width of an image, by default only 3 images appear in a page. If you specify the width of the image,
images are displayed as per the screen width. You can view the page you are on or view the images
exist by viewing the page indicator below.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with viewType as COVE
RFLOW.
var hISLayout={padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:true,
marginInPixel:true, referenceWidth:100, referenceHeight:100, imageScaleMod

e:constants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS, containerWeight:100};
var hISPSP={};
//Reading viewType of Horizontal Image strip.
alert("Horizontal Image strip viewType::"+hIS.viewType);
Accessible from IDE

Yes
31.2 HorizontalImageStrip - Layout Properties

The layout properties for HorizontalImageStrip Widget are as follows:
l
containerWeight
imageScaleMode
margin
marginInPixel
padding
paddingInPixel
referenceHeight
referenceWidth
widgetAlignment
Note: If you want to restrict the width of the image, then choose the appropriate container weight. It
becomes developer responsibility to serve the right kind of images as per device screen form factors.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with containerWeight:
100
var hISBasic={id:"hIS", skin:"hISkn",focusSkin:"hISknFocus", isVisible:tru
:"image2.png"},"imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIEW_
var hISPSP={};
//Reading containerWeight of Horizontal Image strip.
alert("Horizontal Image strip containerWeight::"+hIS.containerWeight);
Accessible from IDE

No
A value of the this property specifies how the rendered image's width and height are identified if those of the
source image varies from the Image widget itself. Image Widget represents the underlying native widget
which renders (and applies alignment to) the Source Image.

l

l

l

width.
scalemode.
case,
l

supported on Mobile Web and SPA. they will render the sourceImage as its actual size.

l

l

Syntax
Lua: imagescalemode
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with imageScaleMode:c
onstants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS.
var hISPSP={};

//Reading imageScaleMode of Horizontal Image strip
alert("Horizontal Image strip imageScaleMode::"+hIS.imageScaleMode);
Accessible from IDE

Yes
Available on all platforms, but the option IMAGE_SCALE_MODE_CROP is not supported on Desktop
Web.
31.2.3 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with margin:[5,5,5,5]
3.png", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"},{"imagekey
var hISLayout={padding:[5,5,5,5], margin:[5,5,5,5], referenceWidth:100, re
ferenceHeight:100, imageScaleMode:constants.IMAGE_SCALE_MODE_FIT_TO_DIMENS
IONS, containerWeight:100};
var hISPSP={};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with marginInPixel:tr
ue
var hISPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
31.2.5 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with padding:[5,5,5,
5].
var hISLayout={padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:true, r
eferenceWidth:100, referenceHeight:100, imageScaleMode:constants.IMAGE_SCA
LE_MODE_FIT_TO_DIMENSIONS, containerWeight:100};
var hISPSP={};
Accessible from IDE

Yes
Default: false
Android and Windows and for other platforms it will be false.
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with paddingInPixel:t
rue
var hISLayout={padding:[5,5,5,5], margin:[5,5,5,5], paddingInPixel:true, r
eferenceWidth:100, referenceHeight:100, imageScaleMode:constants.IMAGE_SCA
LE_MODE_FIT_TO_DIMENSIONS, containerWeight:100};
var hISPSP={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with referenceHeight:
100
var hISBasic={id:"hIS",skin:"hISkn",focusSkin:"hISknFocus",isVisible:true,
var hISPSP={};
Accessible from IDE

Yes
It is the reference image width in pixels.The source image width is resized to fill the widget dimensions. The
Syntax
Lua: referencewidth
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Horizontal Image strip with referenceWidth:1
00
var hISPSP={};
Accessible from IDE

Yes
Available on all platform
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Horizontal Image strip with widgetAlignment:
constants.WIDGET_ALIGN_TOP_RIGHT
IONS, containerWeight:100}, widgetAlignment:constants.WIDGET_ALIGN_TOP_RIG
HT};
var hISPSP={};
Accessible from IDE

Yes
31.3 HorizontalImageStrip - Platform Specific Properties

The platform specific properties for HorizontalImageStrip Widget are as follows:
l
hoverSkin
toolTip
31.3.1 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
JavaScript Example
//Defining the properties for a HzImageStrip with hoverSkin:"hskin"
var hISBasic={id:"his1", isVisible:true, skin:"hISkin", focusSkin:"hISFSki
n", text:"Click Here" };
var hIS={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hExpand:t
rue, vExpand:false, displayText:true};
var hISPSP={hoverSkin:"hskin"};
//Creating the HzImageStrip.
var his1 = new kony.ui.HorizontalImageStrip2(hISBasic, hISLayout, hISPSP);
Accessible from IDE

Yes
31.3.2 toolTip
Syntax
JavaScript: toolTip
Lua: tooltip
Type
JavaScript: String
Lua: String
Read / Write
//Defining the properties for a HzImageStrip with toolTip:sample text
var hISBasic={id:"his1", isVisible:true, skin:"hISkin", focusSkin:"hISFSki
n", text:"Click Here" };
var hIS={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5], hExpand:t
rue, vExpand:false, displayText:true};
var hISPSP={toolTip:"sample text"};
//Creating the HzImageStrip.
var his1 = new kony.ui.HorizontalImageStrip2(hISBasic, hISLayout, hISPSP);
Accessible from IDE

Yes
31.4 HorizontalImageStrip - Events

HorizontalImageStrip Widget has the following event associated with it:
l
onSelection
preOnclickJS
postOnclickJS
31.4.1 onSelection
An event callback that is invoked by the platform when an Image is selected in HorizontalImageStrip.
Signature
Lua: onselection
Read / Write
JavaScript Example
function onSelectionCallBack(hIS)
{
}
//Creating Horizontal Image strip with onSelection:onSelectionCalBck
e,selectedIndex:1, imageWhileDownloading:"img.png",imageWhenFailed:"img3.p
ng", spaceBetweenImages:20, data:[[{"imagekey":"image1.png"},{"imagekey":"
TYPE_COVERFLOW, showArrows:true, showScrollbars:true, onSelection:onSelect
ionCallBack};
var hISPSP={};
//Reading onSelection of Horizontal Image strip.
alert("Horizontal Image strip onSelection::"+hIS.onSelection);
Accessible from IDE

Yes
31.4.2 preOnclickJS
This event allows the developer to execute custom javascript function when the HorizontalImageStrip is
invoked. This is applicable only for Mobile Web channel. The function must exist in a javascript file under
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for preOnclickJS event of Ho
rizontal Image strip.
function preOnclickJSCalBck(hIS)
{
}
//Creating Horizontal Image strip with preOnclickJS:preOnclickJSCalBck
ue,selectedIndex:1, imageWhileDownloading:"img.png", imageWhenFailed:"img3
:constants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS,containerWeight:100};
var hISPSP={preOnclickJS:preOnclickJSCalBck};
//Reading preOnclickJS of Horizontal Image strip.
alert("Horizontal Image strip preOnclickJS::"+hIS.preOnclickJS);
Accessible from IDE

Yes
HorizontalImageStrip is invoked. This is applicable only for Mobile Web channel.The function must exist in a
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the callback function for postOnclickJS event of H
orizontal Image strip.
function postOnclickJSCalBck(hIS)
{
}
//Creating Horizontal Image strip with postOnclickJS:postOnclickJSCalBck
ue, selectedIndex:1,imageWhileDownloading:"img.png", imageWhenFailed:"img3
":"image2.png"},"imagekey"]], viewType:constants.HORIZONTAL_IMAGESTRIP_VIE
arginInPixel:true, referenceWidth:100,referenceHeight:100,imageScaleMode:c
onstants.IMAGE_SCALE_MODE_FIT_TO_DIMENSIONS,containerWeight:100};
var hISPSP={postOnclickJS:postOnclickJSCalBck};
//Reading postOnclickJS of Horizontal Image strip
alert("Horizontal Image strip postOnclickJS::"+hIS.postOnclickJS);
Accessible from IDE

Yes
31.5 HorizontalImageStrip - Methods

HorizontalImageStrip Widget has the following methods associated with it:
l
addAll
addDataAt
removeAll
removeAt
setData
setDataAt
31.5.1 addAll
This method allows you to add new images to the HorizontalImageStrip. The new images are appended to the
existing images. If the Hz Image Strip has no images, the new images are placed in the HorizontalImageStrip.
Signature
JavaScript: addAll(array_of_data,image_url_property)
Lua: imagestrip.addall(widgetid, array_of_data,image_url_property)
Input Parameters
array_of_data [Array] - Mandatory
Array of objects having image property. The image property name must be the one passed as
second argument.
image_url_property [String] - Mandatory
Specifies the url in the JSObject passed in the first argument whose value must be considered for
the image.
widgetid [widgetref] - Mandatory
Return Values
None
JavaScript Example
//Defining the properties for Horizontal Image strip.
.png", spaceBetweenImages:20,data:[[{"imagekey":"image1.png"}, {"imagekey"
:"image2.png"}, "imagekey"]],viewType:constants.HORIZONTAL_IMAGESTRIP_VIEW_
TYPE_COVERFLOW};

arginInPixel:true, referenceWidth:100, referenceHeight:100, containerWeigh
t:100};
var hISPSP={};
//Adding new new images to the Horizontal Image strip by addAll method, We
can use external URL images or the images inside resources folder.
hIS.addAll([{imageurl: "http://chromeactions.com/i/3d-like-box.png" },
{imageurl: "http://www.unlockiphoneinstantly.com/wp-content/themes
/unlockiphone/images/check-box.jpg" }],"imageurl"
);
Error Codes
No error codes
31.5.2 addDataAt
Allows you to add/insert a new image at a given index. In case the index is not valid and not falling in range 0
<= index <= N, where N is the total number of records image is added at the end of the horizontal Image strip.
Signature
JavaScript: addDataAt(imagedata, index)
Lua: imagestrip.addDataAt(widgetid, imagedata, index)
Input Parameters
imagedata [JSObject]- Mandatory
Specifies the JSObject having image property. The image property name must be the one set in
setData and addAll methods.
Return Values
None
JavaScript Example
TYPE_COVERFLOW};
t:100};
var hISPSP={};
//Adding new new image at a 1st index by addDataAt method.
hIS.addDataAt({imageurl: "http://chromeactions.com/i/3d-like-box.png" },
1);
Error Codes
No error codes
31.5.3 removeAll
This method is used to remove all the images in the HorizontalImageStrip.
Signature
Lua: imagestrip.removeAll(widgetid)
Input Parameters
Return Values
None
JavaScript Example
TYPE_COVERFLOW};
t:100};
var hISPSP={};
//Removing all the images inside the Horizontal Image strip using removeAll
method.
hIS.removeAll();
Error Codes
No error codes
31.5.4 removeAt
Removes the image at the given index in the HorizontalImageStrip. In JavaScript the Index is '0' based and in
Lua it is '1' based.
Signature
Lua: imagestrip.removeAt(widgetid, index)
Input Parameters
Return Values
None
JavaScript Example
TYPE_COVERFLOW};
t:100};
var hISPSP={};
//Removing the image
hIS.removeAt(1);
at index 1 using removeAt method.
Error Codes
No error codes
31.5.5 setData
Allows you to set new images to the Hz Image Strip. The existing images will be replaced with the new
images.
Signature
JavaScript: setData(array_of_data,image_url_property)
Lua: imagestrip.setData(widgetid, array_of_data,image_url_property)
Input Parameters
array_of_data [Array]- Mandatory
second argument

Specifies the url as an the array passed in the first argument whose value must be considered for
the image.
Return Values
None
JavaScript Example
var hISBasic={id:"hIS",skin:"hISkn",focusSkin:"hISknFocus", isVisible:true,
TYPE_COVERFLOW};
t:100};
var hISPSP={};
//Replacing existing images with the new images using setData method,We can
use external URL images or the images inside resources folder.
hIS.setData([{imageurl: "http://chromeactions.com/i/3d-like-box.png" },
{imageurl: "http://chromeactions.com/i/3d-like-box.png1" },
{imageurl: "http://www.unlockiphoneinstantly.com/wp-content/themes
/unlockiphone/images/check-box.jpg" },
{imageurl: "http://chromeactions.com/i/3d-like-box.png1" },
{imageurl: "image2.png"}],"imageurl"
);
Error Codes
No error codes
31.5.6 setDataAt
Allows you to set a new image at a given index. The existing image at that index will be replaced with the new
image. In case the index is not valid and not falling in range 0 <= index <= N, where N is the total number of
records then the operation is ignored.
Signature
JavaScript: setDataAt(imagedata, index)
Lua: imagestrip.setDataAt(widgetid, imagedata, index)
Input Parameters
Return Values
None
JavaScript Example
IEW_TYPE_COVERFLOW};
t:100};
var hISPSP={};
//set a new image at a 1st index by setDataAt method
hIS.setDataAt({imageurl: "http://chromeactions.com/i/3d-like-box.png" },
1);
Error Codes
No error codes
31.6 HorizontalImageStrip - Deprecated

The deprecated properties for HorizontalImageStrip widget are as follows:
l
frameHeight
height
viewConfig
width
31.6.1 frameHeight
Specifies the height of the Hz Image Strip in pixels. The height of the images in the Hz Image Strip will not
exceed the height specified in this property.
Default: 100 (the height of the Hz Image Strip is set to 100 pixels)
To change the default height, enter the desired height in this property.
Type
Number
Read / Write
No
Accessible from IDE

Yes
31.6.2 height
Specifies the height of the image in the Hz Image Strip in pixels.
Note: If the height of the image exceeds the height of the Hz Image Strip, the image size is scaled to fit the
HzImagestrip.
Type
Number
Accessible from code

No
Accessible from IDE

Yes
Available on SPA platform only
31.6.3 viewConfig
Note: The two options coverflowAngle and coverflowDepth are deprecated. The option coverflowAngle is
mapped to imageItemRotationAngle.
Specifies the view configuration properties for various view types in the horizontal image strip. Following are
the available view types:
l
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW : The cover flow view enables you to

flip through the images placed in a horizontal Image strip and bring the associated images into view.
This property accepts a JSObject with the below key-value pairs:
l
coverflowAngle: Accepts a number representing the angle at which the non-focused images are
rendered. (Available only on android)
coverflowDepth: Accepts a number (in density independent pixel) representing the depth at
which the non-focused images should be rendered. (Available only on android)
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_ SLOTVIEW : This property accepts a JSObject with

l
flingVelocity: Accepts a number (in density independent pixels) representing the velocity at
which user flings the imagestrip in order to activate auto-flipping the images. Not mandatory
flipInterval: Accepts a number in milliseconds representing the time interval to wait before
flipping to the next image. This is applicable when auto-flipping is activated when user flings.
scrollDistance: Accepts a number (in density independent pixel) representing the touch scroll
distance to travel to consider for navigation between images. Not mandatory (Available only on
android)
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_STRIPVIEW : This property accepts a JSObject with

l
enableScrollBounce : A boolean to enable/disable the bouncing effect when the stripview

reaches the end of the scroll. Default value is true. (Available only on SPA).
Syntax
Lua: viewconfig
Type
Lua: Table
Read / Write
Accessible from IDE

Yes
31.6.4 width
Specifies the width of the image in the Hz Image Strip in pixels.
Type
Number

No
Accessible from IDE

Yes
Available on SPA platform only.
32. ImageGallery
ImageGallery represents a set of images adjacent to each other. If the images exceed the row size, they are
pushed to the next line.
Note: ImageGallery widget is not supported in BlackBerry 10 platform.
ImageGallery provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Properties, Events, and Methods.
Basic Properties
Layout Properties
focusSkin
Id
imageWhenFailed
info
isVisible
selectedIndex
selectedItem
skin
spaceBetweenImages
containerWeight
imageScaleMode
margin
marginInPixel
referenceHeight
referenceWidth
hoverSkin
itemsPerRow
navigationBarPosition
noofRowsPerPage
viewType
viewConfig
Events
Methods
Deprecated
onSelection
preOnclickJS
postOnclickJS
addAll
addDataAt
removeAll
removeAt
setData
setDataAt
frameHeight
height
width
showItemCount
Creating an Image Gallery using a constructor: kony.ui.ImageGallery

var imagegallery1 = new kony.ui.ImageGallery2 (basicConf, layoutConf, pspC
onf)
l
they are ignored
JavaScript Example
//Defining properties for ImageGallery.
var imgGalBasic = {id: "imgGallery", isVisible: true,skin: "gradroundfocu
sbtn", focusSkin: "gradroundfocusbtn", selectedIndex:3, spaceBetweenImages:
50}
var imgGalLayout = {containerWeight:50}
var imgGalPSP = {itemsPerRow:3, navigationBarPosition:"Bottom"}

//Creating the ImageGallery.
var imgGallery = new kony.ui.ImageGallery(imgGalBasic,imgGalLayout,imgGalP
SP );
//Reading the containerWeight of ImageGallery.
alert("ImageGallery containerWeight is ::"+imgGallery.containerWeight);
kony.ui.ImageGallery.
var imageGal1= new kony.ui.ImageGallery (basicConf, layoutConf, pspConf)
Adding an Image Gallery from IDE
The steps involved in adding an ImageGallery are as follows:
1. From the IDE, drag and drop the ImageGallery onto a Form (occupies the complete available width).
2. Specify the images (local or remote) that must be displayed using the data property.
Note: To specify local images, you must add the PNG or JPEG files (the file names must follow a particular
naming convention) to the resources folder of the Application. For more information on how to add these
files, see the Working with Resources section of the Kony Studio User Guide.
3. (Optional) If you are specifying remote images, you can use the following properties as per your
requirement:
l
imageWhenFailed: Specifies the image to indicate that the image (that is being downloaded) is
not available.
imageWhileDownloading: Specifies the image to indicate that the download is taking place over
4. Specify the desired spaceBetweenImages.

5. Specify the onSelection event.
You can customize the appearance of the Image Gallery by using the following properties:
l
imageScaleMode: Specifies the scale mode for all the images in the ImageGallery.
referenceHeight: Specifies the reference height of the ImageGallery in pixels.
referenceWidth: Specifies the reference width of the ImageGallery in pixels.
skin: Specify the skin to be applied to the images in the Image Gallery.
focusSkin: Specify the skin to be applied to the individual image in the ImageGallery when in focus.
l
The Image Gallery occupies 100% of the screen width.
On devices which have a navigation key, you can use the up or down keys to navigate through the
images.
Form cycling is supported (i.e, if you reach the end of the gallery and if it is the last widget, you are
taken to the first control of the form).
For Symbian, Image gallery always uses an image size of 64x64 pixels.
For Windows Kiosk, Image Gallery widget behaves like a screen-level widget,hence
HorizontalImageStrip is preferred while using images.
32.1 ImageGallery - Basic Properties

The basic properties for ImageGallery Widget are as follows:
l
data
focusSkin
id
imageWhenFailed
info
isVisible
selectedIndex
selectedItem
skin
spaceBetweenImages
32.1.1 data
Represents the JSObject to represent the images to be rendered in ImageGallery. The format of the JSObject
consists of an array of two elements:
l
[0] is the array of objects with hashes
[1] is the key's key in the data hash of [0]
Example
//set the images in ImageGallery.
[
{"imagekey":"image1.png"},
{"imagekey":"image2.png"},....
{"imagekey":"imagen.png"}],"imagekey"
]
Syntax
JavaScript: data
Lua: data
Type
JavaScript: Array
Lua: Table
Read / Write
Accessible from IDE

Yes
32.1.2 focusSkin
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with focusSkin: "gradroundfocus
btn"
sbtn", focusSkin: "gradroundfocusbtn"};
var imgGalLayout = {containerWeight:100};
var imgGallery = new kony.ui.ImageGallery2(imgGalBasic,imgGalLayout,{});
//Reading the focusSkin of ImageGallery
alert("ImageGallery focusSkin is ::"+imgGallery.focusSkin);
Accessible from IDE

Yes
32.1.3 id
id is a unique identifier of ImageGallery consisting of alpha numeric characters. Every ImageGallery should
have a unique id within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for ImageGallery with ID:"imgGallery"
var imgGalBasic = {id: "imgGallery", isVisible: true};
//Reading the ID of ImageGallery

alert("ImageGallery id is ::"+imgGallery.id);
Accessible from IDE

Yes
resources folder.
Syntax
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for ImageGallery with imageWhenFailed: "AppIcon.
png" ,Image with the same name should be in resources folder.
var imgGalBasic = {id: "imgGallery", isVisible: true, skin: "gradroundfoc
usbtn", focusSkin: "gradroundfocusbtn", imageWhileDownloading: "Applicatio
nIcon.png", imageWhenFailed: "AppIcon.png"};
Accessible from IDE

No
platforms
Syntax
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for ImageGallery with imageWhileDownloading: "Ap
plicationIcon.png" ,Image with the same name should be in resources folder.
nIcon.png"};
Accessible from IDE

Yes
platforms
32.1.6 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with info property.
imgGallery.info = {key:"ImageGal"};
//Reading the info of ImageGallery
alert("ImageGallery info is ::"+imgGallery.info);
Accessible from IDE

No
32.1.7 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with isVisible: true
//Reading the Visibility of ImageGallery
alert("ImageGallery Visibility is ::"+imgGallery.isVisible);
Accessible from IDE

Yes
Indicates the currently selected image in the ImageGallery. The index is with respect to the order in which
data is set with data property. Programmatically setting the selectedIndex will not make any visible
differences in the row, however it will bring the row at the index into the view able area on the screen. Setting it
to null/nil clears the selection state.
section.
Syntax
Lua: selectedindex
Type
JavaScript: Number
Lua: Number
Read / Write
Note: On Windows Phone (Mango) platform, you cannot write data to this property.
JavaScript Example
//Defining the properties for ImageGallery with selectedIndex:3 (setSelect
edIndex)
nIcon.png", imageWhenFailed: "AppIcon.png", selectedIndex:3};
//getSelectedIndex
alert("Selected Index : "+imgGallery.selectedIndex);
Accessible from IDE

No
32.1.9 selectedItem
Returns the selected data object (input array) corresponding to the selected image of the ImageGallery. If no
image is selected, null/nil is returned.
Syntax
Lua: selecteditem
Type
Lua: UserData
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for ImageGallery with selectedIndex:3 (setSelect
edIndex)
nIcon.png", imageWhenFailed: "AppIcon.png", selectedIndex:3};
//getSelectedItem
alert("selected Item : "+imgGallery.selectedItem);
Accessible from IDE

No
32.1.10 skin
Specifies the look and feel of the ImageGallery when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with skin: "gradroundfocusbtn"
usbtn"};
//Reading the skin of ImageGallery
alert("ImageGallery skin is ::"+imgGallery.skin);
Accessible from IDE

Yes
Specifies the space between the images in the ImageGallery.
Syntax
JavaScript: spaceBetweenImages
Lua: spacebetweenimages
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for ImageGallery with spaceBetweenImages: 50
nIcon.png", imageWhenFailed: "AppIcon.png", selectedIndex:3, spaceBetweenI
mages: 50};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic), BlackBerry 10, and Windows Mango
platforms.
32.2 ImageGallery - Layout Properties

The layout properties for ImageGallery Widget are as follows:
l
containerWeight
imageScaleMode
margin
marginInPixel
referenceHeight
referenceWidth
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with containerWeight:50
50};
//Reading the containerWeight of ImageGallery.
alert("ImageGallery containerWeight is ::"+imgGallery.containerWeight);
Accessible from IDE

No
A value of the this property specifies how the rendered image's width and height are identified if those of the
source image varies from the Image widget itself. Image Widget represents the underlying native widget
which renders (and applies alignment to) the Source Image.

l

l

width.
scalemode.
case,
l

supported on Mobile Web and SPA. they will render the sourceImage as its actual size.

l

l

Syntax
Lua: imagescalemode
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for ImageGallery with imageScaleMode:IMAGE_SCALE_
MODE_FIT_TO_DIMENSIONS
var imgGalBasic = {id: "imgGallery", isVisible: true, skin: "gradroundfocu
50};
var imgGalLayout = {containerWeight:100, imageScaleMode:constants.IMAGE_SC
ALE_MODE_FIT_TO_DIMENSIONS};
//Reading the imageScaleMode of ImageGallery.
alert("ImageGallery imageScaleMode is ::"+imgGallery.imageScaleMode);
Accessible from IDE

Yes
32.2.3 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a ImageGallery with margin:[10,10,10,10] (left,
top, right, bottom).
mages: 50};
var imgGalLayout = {containerWeight:100, margin:[10,10,10,10]};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a ImageGallery with margin in pixels.
mages: 50};
var imgGalLayout = {containerWeight:100, margin:[10,10,10,10], marginInPix
el: true};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with referenceHeight:100
mages: 50};
var imgGalLayout = {containerWeight:100, referenceWidth:100, referenceHeig
ht:100};
//Reading the referenceHeight of ImageGallery
alert("ImageGallery referenceHeight is ::"+imgGallery.referenceHeight);
Accessible from IDE

Yes
It is the reference image width in pixels. The source image width is resized to fill the widget dimensions. The
Syntax
Lua: referencewidth
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with referenceWidth:100
mages: 50};
var imgGalLayout = {containerWeight:100, referenceWidth:100};
//Reading the referenceWidth of ImageGallery
alert("ImageGallery referenceWidth is ::"+imgGallery.referenceWidth);
Accessible from IDE

Yes
32.3 ImageGallery - Platform Specific Properties

The platform specific properties for ImageGallery Widget are as follows:
l
hoverSkin
itemsPerRow
navigationBarPosition
noofRowsPerPage
viewType
viewConfig
32.3.1 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with hoverSkin:"hskin"
usbtn", focusSkin: "gradroundfocusbtn", selectedIndex:3, spaceBetweenImage
s: 50};
var imgGalPSP = {hoverSkin:"hskin"};
var imgGallery = new kony.ui.ImageGallery2(imgGalBasic,imgGalLayout,imgGal
PSP);
Accessible from IDE

Yes
32.3.2 itemsPerRow
Specifies the number of images to be displayed per row in an ImageGallery at a time.
Syntax
JavaScript: itemsPerRow
Lua: itemsperrow
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for ImageGallery with sitemsPerRow:3
s: 50};
var imgGalPSP = {itemsPerRow:3};
PSP);
Accessible from IDE

Yes
This property is available only on Server side Mobile Web (advanced) platform.
32.3.3 navigationBarPosition
Specifies the position of the navigation bar for the ImageGallery. The pageview indicator either appears on the
top or bottom of the ImageGallery.
Syntax
JavaScript: navigationBarPosition
Lua: navigationbarposition
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for ImageGallery with navigationBarPosition:"Bot
tom"
s: 50};
var imgGalPSP = {itemsPerRow:3, navigationBarPosition:"Bottom"};
PSP);
Accessible from IDE

Yes
This property is available only on Server side Mobile Web (advanced) platform.
32.3.4 noofRowsPerPage
Specifies the number of rows to be displayed in each page.
Note: This property is displayed only when viewType is set to IMAGE_GALLERY_VIEW_TYPE_
PAGEVIEW.
Syntax
JavaScript: noofRowsPerPage
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with noofRowsPerPage:4.
var imgGalBasic={id:"imagegallery1", isVisible:true, skin:"imgGalskin", fo
cusSkin:"imgGalFSkin", text:"Click Here", toolTip:"sample text"};
var imgGalLayout={containerWeight:100,padding:[5,5,5,5],margin:[5,5,5,5],
var imgGalPSP={viewType: constants.IMAGE_GALLERY_VIEW_TYPE_PAGEVIEW, viewC
onfig: {noofRowsPerPage:4}};
var imagegallery1 = new kony.ui.ImageGallery(imgGalBasic,imgGalLayout,imgG
alPSP);
Accessible from IDE

Yes
32.3.5 viewType
Specifies the appearance of the Image Gallery as Default view or Page view.
Default: IMAGE_GALLERY_VIEW_TYPE_DEFAULT
You can select one of the following available views:
l
IMAGE_GALLERY_VIEW_TYPE_DEFAULT - This is the default selection and if this option is

unchanged, the appearance of the image gallery remains unchanged.
IMAGE_GALLERY_VIEW_TYPE_PAGEVIEW - The images appears as a pageview. When this

option is selected, the noofRowsPerPage is displayed.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with viewType:IMAGE_GALLERY_VIE
W_TYPE_DEFAULT.
var imgGalPSP={viewType: constants.IMAGE_GALLERY_VIEW_TYPE_DEFAULT };
alPSP);
Accessible from IDE

Yes
32.3.6 viewConfig
Specifies the view configuration parameters when the viewType is set as IMAGE_GALLERY_VIEW_TYPE_
PAGEVIEW for Desktop Web platform.
Type
Read / Write
JavaScript Example
//Defining the properties for ImageGallery with viewConfig:noofRowsPerPage.
var imgGalPSP={viewType: constants.IMAGE_GALLERY_VIEW_TYPE_PAGEVIEW, viewC
onfig: {noofRowsPerPage: 5} };
alPSP);
Accessible from IDE

Yes
32.4 ImageGallery - Events

ImageGallery has the following event associated with it:
l
onSelection
preOnclickJS
postOnclickJS
32.4.1 onSelection
An event callback that is invoked by the platform when an Image is selected in ImageGallery.
Signature
Lua: onselection
Read / Write
JavaScript Example
//The below function is the callback for onSelection event
function onSelCallBck(imgGal)
{
alert("onSelection call back triggered");
}
//Defining the properties for ImageGallery with onSelection:onSelCallBck
usbtn",focusSkin: "gradroundfocusbtn", imageWhileDownloading: "Application
Icon.png", imageWhenFailed: "AppIcon.png", selectedIndex:3, spaceBetweenIm
ages: 50,onSelection:onSelCallBck}
var imgGalPSP = {itemsPerRow:3};
PSP);
Accessible from IDE

Yes
32.4.2 preOnclickJS
This event allows the developer to execute custom javascript function when the ImageGallery is invoked.
This is applicable only for Mobile Web channel. The function must exist in a javascript file under
Syntax
Lua: preonclickjs
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//The below function is the callback for preOnclickJS event
function preOnclickCallBck(imgGal)
{
alert("PreOnclick call back triggered");
}
//Defining the properties for ImageGallery with preOnclickJS:preOnclickCal
lBck
mages: 50}
var imgGalPSP = {itemsPerRow:3, preOnclickJS:preOnclickCallBck};
PSP);
Accessible from IDE

Yes
ImageGallery is invoked. This is applicable only for Mobile Web channel.The function must exist in a
Type
String
Read / Write
JavaScript Example
//The below function is the callback for postOnclickJS event.
function postOnclickCallBck(imgGal)
{
alert("PostOnclick call back triggered");
}
//Defining the properties for ImageGallery with postOnclickJS:postOnclickC
allBck
sbtn", focusSkin: "gradroundfocusbtn", imageWhileDownloading: "Application
ages: 50}
var imgGalPSP = {itemsPerRow:3, postOnclickJS:postOnclickCallBck};
PSP);
Accessible from IDE

Yes
32.5 ImageGallery - Methods

ImageGallery has the following methods associated with it:
l
addAll
addDataAt
removeAll
removeAt
setData
setDataAt
32.5.1 addAll
This method allows you to add new images to the ImageGallery. The new images are appended to the existing
images. If the ImageGallery has no images, the new images are placed in the ImageGallery.
Signature
JavaScript: addAll(array_of_data)
Note: There is no need for the second parameter (image_url_property) as this API assumes
the same image_url_property i.e set while setting the data using the setData. setData is a
must to be called before calling any of the add, addAt Apis.
Lua: gallery.addall(widgetid, array_of_data,image_url_property)
For Backward compatiability use the below signature:
JavaScript: addAll(array_of_data,image_url_property)
Input Parameters
second argument.
Specifies the url in the JSObject passed in the first argument whose value must be considered for
the image.
Return Values
None
JavaScript Example
//Defining the properties for ImageGallery.
mages: 50}
PSP);
//Adding new new images to the Image Gallery by addAll method,We can use e
xternal URL images or the images inside resources folder
imgGallery.addAll(
[{imageurl: "http://chromeactions.com/i/3d-like-box.png"
},
{imageurl: "http://www.unlockiphoneinstantly.com/wp-con
tent/themes/unlockiphone/images/check-box.jpg" }],
"imageurl"
);
Exceptions
WidgetError
32.5.2 addDataAt
Allows you to add/insert a new image at a given index. In case the index is not valid and not falling in range 0
<= index <= N, where N is the total number of records image is added at the end of the ImageGallery.
Signature
JavaScript: addDataAt(imagedata, index)
Lua: gallery.addDataAt(widgetid, imagedata, index)
Input Parameters

Return Values
None
32.5.3 removeAll
This method is used to remove all the images in the HorizontalImageStrip.
Signature
Lua: gallery.removeAll(widgetid)
Input Parameters
Return Values
None
JavaScript Example
mages: 50}
PSP);
//Removing all the images inside the imageGallery by
imgGallery.removeAll();
removeAll method.
32.5.4 removeAt
Removes the image at the given index in the ImageGallery. In JavaScript, the Index is '0' based and in Lua, it
is '1' based.
Signature
Lua: gallery.removeAt(widgetid, index)
Input Parameters
Return Values
None
JavaScript Example
sbtn", focusSkin: "gradroundfocusbtn", imageWhileDownloading: "Application
ages: 50}
PSP);
//Removing the image at index 1 by removeAt method
imgGallery.removeAt(1);
32.5.5 setData
Allows you to set new images to the ImageGallery. The existing images will be replaced with the new images.
Signature
JavaScript: setData(array_of_data)
Note: There is no need for the second parameter (image_url_property) as this API assumes
the same image_url_property i.e set while setting the data using the setData. setData is a
must to be called before calling any of the add, addAt Apis.
Lua: gallery.setData(widgetid, array_of_data, image_url_property)
For Backward compatiability use the below signature:
JavaScript: setData(array_of_data, image_url_property)
Input Parameters
second argument
Specifies the url as an the array passed in the first argument whose value must be considered for
the image.
Return Values
None
JavaScript Example
mages: 50}
PSP);
//Replacing existing images with the new images by setData method,We can u
se external URL images or the images inside resources folder
imgGallery.setData([{imageurl: "http://chromeactions.com/i/3d-like-box.pn
g" },
{imageurl: "http://chromeactions.com/i/3d-like-
box.png1" },
{imageurl: "http://www.unlockiphoneinstantly.com/wp-c
ontent/themes/unlockiphone/images/check-box.jpg" },
{imageurl: "http://chromeactions.com/i/3d-like-box.pn
g1" },
{imageurl: "image2.png"}],
"imageurl"
);
32.5.6 setDataAt
Allows you to set a new image at a given index. The existing image at that index will be replaced with the new
image. In case the index is not valid and not falling in range 0 <= index <= N, where N is the total number of
records then the operation is ignored.
Signature
JavaScript: setDataAt(imagedata, index)
Lua: gallery.setDataAt(widgetid, imagedata, index)
Input Parameters
Return Values
None
JavaScript Example
mages: 50}
PSP);
//Set a new image at a 1st index by setDataAt method
imgGallery.setDataAt({imageurl: "http://chromeactions.com/i/3d-like-box.p
ng" }, 1);
32.6 ImageGallery - Deprecated Properties

The deprecated properties for ImageGallery widget are as follows:
l
frameHeight
height
width
showItemCount
frameHeight
height
width
showItemCount
referenceHeight
referenceWidth
referenceHeight
NA
32.6.1 frameHeight
Specifies the height of the ImageGallery in pixels. The height of the images in the ImageGallery will not
exceed the height specified in this property.
Default: 100 (the height of the ImageGallery is set to 100 pixels)
To change the default height, enter the desired height in this property.
Type
Number
Read / Write
No
Accessible from IDE

Yes
32.6.2 height
Specifies the height of the image in the ImageGallery in pixels.
Note: If the height of the image exceeds the height of the ImageGallery, the image size is scaled to fit the
ImageGallery .
Type
Number

No
Accessible from IDE

Yes
Available on SPA platform only
32.6.3 width
Specifies the width of the image in the ImageGallery in pixels.
Type
Number

No
Accessible from IDE

Yes
Available on SPA platform only.
Specifies if the meta structure must be displayed.
The meta structure has the following format:
start_rec_num, end_rec_num, total_recs
For example, {1,10,100} indicates that the current record start is 1, the set ends at 10, and that there are 100
records.
Default: true
If set to false, the meta structure is not displayed.
If set to true, the meta structure is displayed.
Type
Boolean
Read / Write
Yes
Accessible from IDE

Yes
Available on all platforms except Symbian.
33. Map
A Map widget provides you the capability to display pre-defined locations (latitude and longitude) on an
onscreen map. Platforms like BlackBerry (above JDE 4.5), iPhone (above 3.0), and Android provide a native
map widget that can be displayed as part of the application.
On platforms where a native map widget is not available, the Kony Map widget integrates with Google Maps
and displays the static image with zoom and pan controls. You can customize the map view if you do not want
to use the default view.
Note: The platforms Mobile Web (basic), Mobile Web (BJS) and Non-Touch HTML devices supports only
static maps.
Note: On Android platform, Map widget does not work in Popup.
The Map widget renders a map using the mapping service provided by the platform. The following table shows
the list of platforms and the available mapping services:
Platform
Mapping Service
iPhone/iPad
iOS Native Framework Map
Android
Google Maps
BlackBerry (Version 4.5 and

above)
BlackBerry Maps
BlackBerry (Version below 4.5)
Google Static Maps
Windows
Bing Maps
Google Static Maps, Native maps of the device, and interactive maps
(Java script)
To generate and configure Android Google Map APIs click here.

The Map widget provides you with an option to set Basic Properties, Layout Properties, Platform Specific
Properties, Events, and Methods.
Platform Specific
Properties
Basic Properties
Layout Properties
calloutTemplate
calloutWidth
defaultPinImage
id
info
isVisible
locationData
mapKey
provider
screenLevelWidget
widgetDataMapForCallout
containerHeight
containerWeight
margin
marginInPixel
address
mapHeight
mapSource
mapWidth
mode
navControlsImageConfig
showCurrentLocation
showZoomControl
zoomlevel
Events
Methods
Deprecated
onClick
onPinClick
addPolyline
clear
Events
Methods
onSelection
dismissCallout
getBounds
navigateTo
navigateToLocation
removePolyline
Deprecated
Creating a Map using a constructor: kony.ui.Map

var mymap = new kony.ui.Map(basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//The below function is the callback function for onPinClick event.
function onPinClickCallBck(map)
{
alert("onPinClick event triggered");
}
//Defining the map properties
var mapBasicConf = {id: "map1", provider:constants.MAP_PROVIDER_GOOGLE, ma
pKey:"0z5UtaSPUYj42f5qX0VAwmDGLX39Qxgbtcra0TA", defaultPinImage: "kmpin.pn
g", isVisible:true, onPinClick:onPinClickCallBck};
var mapLayoutConf={margin:[20,40,50,20], containerWeight:100, widgetAlignm
ent:constants.WIDGET_ALIGN_BOTTOM_LEFT,padding:[10,10,10,10], hExpand:fals
e, vExpand:false};
var mapPSPConf={mode: constants.MAP_VIEW_MODE_HYBRID, showCurrentLocation:
constants.MAP_VIEW_SHOW_CURRENT_LOCATION_AS_PIN};
//Creating the map with the properties defined above.
var map = new kony.ui.Map(mapBasicConf,mapLayoutConf,mapPSPConf);
The appearance of the Map widget with a defined locationData on various platforms is as follows:
Platform
Appearance
Android
BlackBerry
Platform
Appearance
iPhone
Platform
Appearance
Mobile Web (BJS)
Adding a Map Widget from IDE

The steps involved in adding a map widget are as follows:
1. Drag and drop the map widget onto a form (occupies the complete available width). Or, based on your
requirements, you can choose to resize a map widget in the horizontal direction by placing a Box on the
form and by dragging and dropping the map widget inside the Box and resizing accordingly.
2. On Android, BlackBerry, configure the mapKey for your application:
Note: You do not have to configure map keys for Windows and Mobile Web platforms.
3. Specify the locationData from the code.
Note: On Android and Mobile Web platforms you can choose to specify the address property instead
of the locationData property.
4. (Optional) Specify a defaultPinImage to indicate a location for all platforms or for specific platforms.
5. (Optional) Specify a zoomlevel (applicable on iPhone, Android, and BlackBerry).
6. (Optional) On Android and Mobile Web platforms, change the viewing mode as per your requirements.
7. (Optional) On Mobile Web platforms, change the mapSource , mapHeight and mapWidth.
Interactions with a Map Widget
There are three ways to interact with a Map widget. They are as follows:
l
Pan
Zoom
Location selection
Pan
It is the ability to move (left, right, up, or down) around a region on the map.
On iPhone, Android, and Windows platforms, you can swipe (left, right, up, or down) to move around a region
on the map.
On BlackBerry Touch and Non-touch devices, you can swipe (left, right, up, or down) and use the trackball (or
trackpad) respectively to move around a region on the map.
Zoom
It is the ability to magnify a region on the map to show additional details of that region. If you zoom-in, the
region is magnified and additional details are displayed. If you zoom out, the field of vision of the map is
increased.
On iPhone, Android, and Windows platforms, you can poke to zoom-in and pinch to zoom out.
On BlackBerry Touch and Non-touch devices, you can use the "+" and "-" search glass icons and "i" and "o"
keys respectively to zoom-in and zoom out of a region on the map.
The following image illustrates the BlackBerry "+" and "-" search glass icons:
Location Selection
You can get additional details of a location by clicking a plotted point on the map. If you click a plotted point, a
popup containing the name and description of the plotted point is displayed.
Note: You can specify the coordinates that must be plotted on the Map using the locationData property.
If you want additional information related to that location (for example, directions to that location), you can
click the popup and trigger an onSelection event.
Note: The onSelection event is triggered only if you click the location popup.
Note: Preview of map widget is not supported on SPA and DesktopWeb platforms.
On BlackBerry platform (Version 4.1 and above), you must ensure the following:
There is no focusable widget above the Map widget. This is because, on non-touch devices, when the
map widget is in focus, you will not be able to move the focus away from the map (this is done to
ensure that the trackball movements will result in panning of the map).
The Map widget should be the last widget on the form. You must ensure this for a good user
experience.
To test the Map widget on any Blackberry emulator execute the following steps:
Note: : You require administrator rights to perform the following operations.

Setup the MDS:
Note: : Make sure the BlackBerry simulator is not running before starting the MDS. Ignore Step 3 - if
you are not using proxy.
1. Go to MDS location, for example C:\Program Files\Research In Motion\BlackBerry JDE
X.Y.Z\MDS and find for the file rimpublic.property.
2. Open rimpublic.property file in a text editor.
3. If you are using a proxy - add the following lines under [HTTP HANDLER] section:
application.handler.http.proxyEnabled=true
application.handler.http.proxyHost=proxy.server.com
application.handler.http.proxyPort=80
4. Find and replace the string localhost in the same file rimpublic.property with your system ipaddress [use ipconfig in your command prompt to find your system ip-address].
5. Save the file.
6. Start MDS.
Before launching the simulator:
1. Go to the simulator location, for example C:\Program Files\Research In Motion\BlackBerry JDE
X.Y.Z\simulator.
2. Delete all the '.dmp' files (example: 9800-XXX.dmp) or run clean.bat.
3. In the simulator ensure that the "Network Mode" in "Mobile Network" settings is set to 2G or 3G
& 2G
4. Go to Mange Connections.
5. Uncheck Wi-Fi and switch it On back.
6. Start the simulator.

Android Limitations
In Android Platform, if Map widget V1 is not dragged into any of the forms built through IDE but only created
dynamically through hand code, you can follow any of the procedures mentioned below:
Procedure1:
1. From the Applications View, right-click on the project and select Properties.
2. Select Native App tab and select Android.
3. Under Manifest Properties, select Tags tab.
4. Add the below line of code in Child tag entries under <application> tag:.
<uses-library android:name="com.google.android.maps"></uses-library>
Procedure2: (works only with Kony Studio IDE plugin version IDE GA-V5.0.10 )
2. Under Application tab, add map key in Android map widget key textbox.
In Android Platform, if the developer wants to use Map widget V2, follow the below steps:
2. Select Native App tab and select Android.
3. Under Manifest Properties, select Tags tab.
4. Add the below line of code in Child tag entries under <application> tag:. If the developer provides
Google Map V2 key then Platform by default loads Google Map V2.
<meta-data android:name="com.google.android.maps.v2.API_KEY" android:value

="MapV2-Key"/>
5. Replace MapV2-Key string with the generated Map V2 Key.

Click here to read more about Generating and Configuring Map API Keys.
Note: Google Map V2 does not work on emulator. On Android devices it works only with Android Version 2.2
and above. It requires OpenGL ES version 2 to load.
Note: On Android platform, Multiple Map Widgets in a single form is not supported for Google Map V1. It is
supported for Google Map V2.
Note: In Kony Studio, Preview feature launches Google Map V1 only.
Note: Clickable/Interactive widgets inside a Map callout template will become non-clickable when android
Map V2 version is used. This the limitation of native Android Map V2 callout. As callouts are displayed as
static image snapshot of callout template and only the entire callout is clickable. Map onSelection callback
is invoked when a callout is clicked.
BlackBerry 10 Limitations
Following are the limitations of BlackBerry 10 platform:
1. From Kony Studio, you have to set the permission for access_location_service as true. To set
access_location_service, navigate to Application Properties >Native >BlackBerry10, select access_
location_services and click Add >.
2. Your device location service setting must be on. To set device location service in your device, navigate
to Device Settings >Location Services > turn on the location services.
3. Map is available for USA and Canada regions only. It will not work for Asia Pacific region.
4. Map works in BlackBerry 10 OS version 10.0.9.2709 and above.
5. If the network is slow then rendering of the map is not smooth. You may observe different fonts and
ODD UI.
6. For devices less than 10.1, developer specified or custom pin image is not displayed. Only BlackBerry
10 provided images can be displayed.
7. Rendering of Map may takes 2 to 3 minutes depending on your network. Sometimes it may take more
than 5 minutes also.
8. When a Map is loading we cannot display an alert messages.
9. Your application may crash when you perform any action while loading the Map.
10. Zoom level is decided by altitude. Hence user has to provide zoom level in terms of 1000. The default
zoomlevel is 10000.
11. Events associated with Map widget are not writable.
33.1 Map - Basic Properties

The basic properties of Map Widget are as follows:
l
calloutTemplate
calloutWidth
defaultPinImage
id
info
isVisible
locationData
mapKey
provider
screenlevelwidget
widgetDataMapForCallout
33.1.1 calloutTemplate
Accepts reference to a box widget which represents a UI template for a custom callout. The box template is
allowed to have only Label, Link, Richtext, Button and Image widgets.
Note: If template is not provided, it will fallback to the platform specific default callout for backward
compatibility. On iOS platform, onSelection event will not get fired for custom callout.
Syntax
JavaScript: calloutTemplate
Type
Lua: UserData
Read / Write
Accessible from IDE

Yes
33.1.2 calloutWidth
Specifies the width of the callout on the map. It accepts a number between 1 to 100 in percentage relative to
the map widget width. For example, 100% value means, callout width should fill its map widget width. If the
value specified is less than 1 or more than 100, it should fallback to 80%.
Default: 80%
Syntax
JavaScript: calloutWidth
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Map with calloutWidth: 80
g", isVisible:true, screenLevelWidget:false, calloutWidth: 80};
var mapLayoutConf={margin:[20,40,50,20], containerWeight:100};
var mapPSPConf={};
//Creating the Map.
//Reading calloutWidth of the Map.
alert("Map calloutWidth is ::"+map.calloutWidth);
Accessible from IDE

Yes
33.1.3 defaultPinImage
The default map pin image to be used to indicate a location on map.
Note: For Static maps, the defaultPinImage is not supported in Server side Mobile Web platforms.
Note: On BlackBerry 10 platform, for better user experience the image must of the size 60x60 px.
Syntax
JavaScript: defaultPinImage
Lua: defaultpinimage
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Map with defaultPinImage: "kmpin.png".
g", isVisible:true, screenLevelWidget:false};
var mapPSPConf={};
//Creating the Map.
//Reading thedefaultPinImage of the Map.
alert("Map defaultPinImage is ::"+map.defaultPinImage);
Accessible from IDE

Yes
33.1.4 id
id is a unique identifier of Map consisting of alpha numeric characters. Every Map should have a unique id
within an Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Map with the id: "map1"
var mapPSPConf={};
//Creating the Map.
//Reading the id of the Map.
alert("Map ID is ::"+map.id);
Accessible from IDE

Yes
33.1.5 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Map with the info property.
g", isVisible:true, screenLevelWidget:false };
var mapPSPConf={};
//Creating the Map.
map.info = {key:" my location"};
//Reading the info of the Map.
alert("Map info is ::"+map.info);
Accessible from IDE

No
33.1.6 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Map with isVisible:true.
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
33.1.7 locationData
The location data to be highlighted on the map widget.
The following are the keys required in the location JSobject:
l
latitude [Number] [Mandatory] : Specifies the latitude of the location.
longitude [Number] [Mandatory] : Specifies the longitude of the location.
name [String] [Mandatory] : Specifies a short description for the location.
desc [String] [Mandatory]: Specifies a long description for the location.
image [String] [Mandatory]: Specifies the map pin image that overrides the defaultPinImage.
showcallout [Boolean] [Optional]: Shows the callout popup. Default value is true.
calloutData [JSObject] [Optional]: Specifies the widget data for a given template for a particular
location. The value should be a map of key-value pairs. The data can have one of the standard key
called "template" that accepts a box reference, in order to provide location specific template, which
overrides the widget level "calloutTemplate".
Note: The widget-data map for a template must be provided in the "widgetDataMapForCallout"
property. The sample format of the data is as follows: {dataId1:"", dataId2:"" dataId3:"",
template:boxRef2}
meta [JSObject] [Optional]: Specifies the platform specific meta information.

l
color[String] [Optional]:Specifies the color for the popup. (Supported on Mobile Web and SPA)
label [String] [Optional] : Specifies the text for the popup. (Supported on Mobile Web and SPA)
Syntax
JavaScript: locationData
Lua: locationdata
Type
JavaScript: Array. But on BlackBerry 10 platform, it is JSObject. The developer has to use jsonstringify
to access the value.
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Map with locationData:[{lat :"17.445775",lon
:"78.3731", name: "Campus 1", desc: "My Office Campus"}]
g", isVisible:true, screenLevelWidget:false, locationData:[{lat :"17.44577
5", lon :"78.3731",name: "Campus 1", desc: "My Office Campus"}]};
var mapPSPConf={};
//Creating the Map.
//platform specific meta information needed for location data.
//meta:{color:"green",label:"C"} //color and label meta are supported only
by Mobile Web and SPA platforms.
Accessible from IDE

Yes
33.1.8 mapKey
The map key required to connect to the map provider service. Since we currently support only Google maps,
this property accepts google map key.
Note: There should be a separate map key needed for the android platform as per the android SDK map key
requirements, which is different from the map key requirements for static/dynamic JavaScript based google
map key.
Syntax
JavaScript: mapKey
Lua: mapkey
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Map with mapKey:"0z5UtaSPUYj42f5qX0VAwmDGLX3
9Qxgbtcra0TA"
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
33.1.9 provider
Specifies the map data provider. For example, you can set the map provider as Google or Bing based on your
location and requirement.
Default: MAP_PROVIDER_GOOGLE
Syntax
JavaScript: provider
Lua: provider
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Map with provider:constants.MAP_PROVIDER_GOO
GLE
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango) and BlackBerry 10 platforms
Specifies whether the widget should occupy the whole container excluding space for headers and footers, if
any.
Note: On BlackBerry 10 platform, by default it takes display height.
Default: true
If set to false, the map occupies the space as set in the IDE or layout properties.
If set to true, the map occupies the whole space on the container.
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Map with screenLevelWidget:false.
g", isVisible:true, screenLevelWidget:false,locationData:[{lat :"17.44577
5", lon :"78.3731", name: "Campus 1", desc: "My Office Campus"}]};
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
Available on all platforms except SPA and BlackBerry 10 platforms
33.1.11 widgetDataMapForCallout
Specifies the mapping between the widget identifiers and data identifiers. The map must contain all widget
data map referred across multiple templates, including the dynamic templates for each map location, if any. It
accepts the data as key-value pairs, where key is the widget identifier and value is the data identifier.
Note: On iOS platform, onSelection event will not get fired for custom callout.
Syntax
JavaScript: widgetDataMapForCallout
Lua: widgetdatamapforcallout
Type
Lua: Table
Read / Write
Accessible from IDE

Yes
Available on all platforms except on Windows Tablet, BlackBerry 10, and Windows Kiosk platforms
33.2 Map - Layout Properties

The Layout properties for Map Widget are as follows:
l
containerHeight
containerWeight
margin
marginInPixel
Note: In Windows Phone platform, when screenLevelWidget property is set to false or true, the Map widget
occupies 500 px. But on Windows Tablet and Windows Kiosk platforms, when the value changed from
positive to negative value, there is no change and when changed from 0 to negative value, it takes default
height (500 px).
When changed from 0 to negative value default height
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining properties for a map with the containerHeight:80
g", isVisible:true};
var mapLayoutConf={margin:[20,40,50,20], containerHeight:80};
var mapPSPConf={};
//Creating the map.
Accessible form IDE

Yes
l
CONTAINER_HEIGHT_BY_FORM_REFERENCE: The Map height is calculated based on the height

of the Form excluding headers and footers. This property doesn't have any effect if the Map widget is
placed inside a popup or headers/footers.
CONTAINER_HEIGHT_BY_PARENT_WIDTH: Use this option if the Map is placed inside a Box.

Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining properties for a map with the containerHeightReference:constant
s.CONTAINER_HEIGHT_BY_PARENT_WIDTH
var mapLayoutConf={margin:[20,40,50,20], containerHeight:80, containerHeig
htReference:constants.CONTAINER_HEIGHT_BY_PARENT_WIDTH};
var mapPSPConf={};
//Creating the map.
Accessible from IDE

Yes
Syntax
Type
Read / Write
JavaScript Example
//Defining properties for a map with the containerWeight:80

var mapPSPConf={};
//Creating the map.
Accessible from IDE

No
33.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a map with the margin:[20,40,50,20]
var mapPSPConf={};
//Creating the map.
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a map with margin in pixels.
var mapLayoutConf={margin:[20,40,50,20], containerWeight:100, marginInPixe
l:true};
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
33.3 Map - Platform Specific Properties

The platform specific properties for Map Widget are as follows:
l
address
mapHeight
mapSource
mapWidth
mode
navControlsImageConfig
showCurrentLocation
showZoomControl
zoomLevel
33.3.1 address
Enables you to navigate to the specified address.
Syntax
JavaScript: address
Lua: address
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Map with address:Kony Solutions, Inc., Tower
Lane, Foster City, CA, United States
var mapPSPConf={mapHeight:100};
//Creating the Map.

//Defining the address location.
formid.map1.address={"location" : "Kony Solutions, Inc., Tower Lane, Foster
City, CA, United States"}
Accessible from IDE

No
l
Server side Mobile Web (basic) - Location Pin marker is not supported.
Server side Mobile Web (BJS) - Location Pin marker is not supported.
Server side Mobile Web (advanced) - Address popup will not be displayed.
SPA(iPhone/Android/BlackBerry/Windows NTH)
33.3.2 mapHeight
Specifies the Width of the map. Accepts the values based on 320 screen height.
Default: (No skin is applied)
Note: For the skin to be available in the list, you must add a skin for BlockedUI under Widget Skins.
Syntax
JavaScript: mapHeight
Lua: mapheight
Type
Lua: UserData
Read / Write
No
JavaScript Example
//Defining the properties for Map with mapHeight:100
pKey:"0z5UtaSPUYj42f5qX0VAwmDGLX39Qxgbtcra0TA", defaultPinImage:
"kmpin.png", isVisible:true};
var mapPSPConf={mapHeight:100};
//Creating the Map.
Accessible from IDE

Yes
l
33.3.3 mapSource
Specifies the source of the maps.
You can choose one of the following available sources:
Default: (No skin is applied)
l
MAP_SOURCE_NATIVE : If you select this option, the application uses the mapKey and provider
details to fetch the map.
The fetched map is interactive with an ability to zoom and pan.
Note: Polygon view on advanced Mobile Web platform is available only when the source is set to
non-native.
MAP_SOURCE_NON_NATIVE : If you select this option, the application uses the map that is on the
device.
MAP_SOURCE_STATIC : If you select this option, the application uses the mapKey and provider
properties to fetch the maps.
The fetched map is non-interactive. However, you can zoom and pan across the map.
Note: MAP_SOURCE_STATIC is only applicable to HTML5 mobile web platform.
Note: Mobile Web (basic), and Mobile Web (BJS) support only Google Static Maps as a source. Static
maps are directly requested from Google for a given latitude and longitude. Kony does not support any other
option because the size of the get request URL can be bigger than 256 characters leading to the request not
being served.
Syntax
JavaScript: mapSource
Lua: mapsource
Type
JavaScript: Number
Lua: Number
Read / Write
No
Accessible from IDE

Yes
l
Server side Mobile web (Advanced)
SPA(iPhone/BlackBerry/Android/WindowsNTH)
33.3.4 mapWidth
Specifies the Width of the map. Accepts the values based on 320 screen width.
Syntax
JavaScript: mapWidth
Lua: mapwidth
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Map with mapWidth:100
var mapPSPConf={mapWidth:100};
//Creating the Map.
Accessible from IDE

Yes
l
33.3.5 mode
Specifies the map viewing mode.
Default: MAP_VIEW_MODE_NORMAL

MAP_VIEW_MODE_NORMAL : Traditional depiction of roads, parks, borders etc.
MAP_VIEW_MODE_SATELLITE: Map showing aerial imagery.
MAP_VIEW_MODE_STREET: Navigate within street-level imagery.
MAP_VIEW_MODE_HYBRID: Street map superimposed on Satellite map.
MAP_VIEW_MODE_POLYGON: Map showing the polygonal area as specified in locationdata property.
MAP_VIEW_MODE_TRAFFIC: Specifies the streets with different colors to indicate traffic information
on the map. The color green indicates low traffic, orange indicates medium traffic and red indicates heavy
traffic.
MAP_VIEW_MODE_TERRAIN: Map showing the surface of the land in 3D view.
Note: Traffic mode works only in North America and Europe.
The following images illustrate the Normal Mode, Satellite Mode, and Street Mode.
Normal Mode
Satellite Mode
Street Mode
The following images illustrate the Polygon Mode, Hybrid Modeand Traffic Mode.
Polygon Mode
Hybrid Mode
Traffic Mode
The following image illustrates the Terrain Mode
Terrain Mode
The below table shows the list of map modes and their availability in respective platforms:
Modes
Normal
IOS
Yes
Windows
Yes
Phone/Kiosk
Android
Yes
SPA
Yes
Mobile Web
Yes
(basic)
Mobile Web (BJS)
Yes
Mobile Web
Yes
(Advanced)
DesktopWeb
Yes
Satellite
Yes
Hybrid
Yes
Street
No
Polygon
No
Traffic
No
Terrain
No
Yes
Yes
No
No
No
No
Yes
Yes
No
Yes
No
No
No
Yes
Yes
No
No
Yes
Yes
Yes
No
No
No
Yes
Yes
Yes
No
No
No
Yes
Yes
Yes
No
Yes
No
Yes
Yes
Yes
No
Yes
No
Yes
If you select the mode as polygon for Mobile Web, the location coordinates specified in the locationData
property are plotted as the vertices of a polygon and the area is shaded.
Note: The polygon mode is applicable only if the mapSource is MAP_SOURCE_NON_NATIVE.
Syntax
JavaScript: mode
Lua: mode
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read and Write) (on Blackberry it is not accessible from code)
JavaScript Example
//Defining the properties for Map with the mode: constants.MAP_VIEW_MODE_H
YBRID
var mapPSPConf={mode: constants.MAP_VIEW_MODE_HYBRID};
//Creating the Map.
Accessible from IDE

Yes
l
iPhone
iPad
Android
Server side MobileWeb (basic,BJS,Advanced)
Windows Kiosk
33.3.6 navControlsImageConfig
The images required to configure the zoom (in and out) and navigation (left, right, top, and bottom) controls on
static map view.
It accepts key values for image names for the following.
l
zoomIn
zoomOut
navLeft
navRight
navTop
navBottom
Syntax
JavaScript: navControlsImageConfig
Lua: navcontrolsimageconfig
Type
Lua: Table
Read / Write
No
JavaScript Example
//Defining the properties for Map with zoom and navigation control images.
The images should be in resources folder.
var mapPSPConf={navControlsImageConfig:{zoomIn:"a.png", zoomOut:"b.png", n
avLeft:"c.png", navRight:"d.png", navTop:"e.png", navBottom:"f.png" }};
//Creating the Map.
Accessible from IDE

Yes
l
33.3.7 showCurrentLocation
Indicates the current location on map as a pin, circle or none.
Default: MAP_VIEW_SHOW_CURRENT_LOCATION_NONE
l
MAP_VIEW_SHOW_CURRENT_LOCATION_NONE
MAP_VIEW_SHOW_CURRENT_LOCATION_AS_PIN
MAP_VIEW_SHOW_CURRENT_LOCATION_AS_CIRCLE
Syntax
JavaScript: showCurrentLocation
Lua: showcurrentlocation
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Map to show the Current Location as pin.
var mapPSPConf={showCurrentLocation:constants.MAP_VIEW_SHOW_CURRENT_LOCATI
ON_AS_PIN};
//Creating the Map.
Accessible from IDE

Yes
l
iPhone
iPad
33.3.8 showZoomControl
Indicates if the zoom control to be displayed on the map.
Default: true
If set to false, the zoom control is displayed.
If set to true, the zoom control is not displayed.
Syntax
JavaScript: showZoomControl
Lua: showzoomcontrol
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Map with showZoomControl:true
var mapPSPConf={showZoomControl:true};
//Creating the Map.
Accessible from IDE

Yes
Available on Android/Android Tablet only
33.3.9 zoomLevel
Sets the zoom level for the current map view. The range varies from platform to platform.
Following are the range and default values on different platforms:
l
iPhone range: [0-28], default 14.
Android range: [1-21], default 15.
BlackBerry 10 :[1000-50,000], default is 10,000.
Note: On BlackBerry 10 platform, zoomlevel is decided by altitude. Hence you have to provide zoom level in
terms of 1000.
Syntax
JavaScript: zoomLevel
Lua: zoomlevel
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Map with the zoomLevel:15
var mapPSPConf={zoomLevel:15};
//Creating the Map.
Accessible from IDE

Yes
l
Android
iPhone/iPad
Windows Tablet
Windows Kiosk
BlackBerry 10
33.4 Map - Events

Map has the following events associated with it:
l
onClick
onPinClick
onSelection
33.4.1 onClick
An event callback is invoked by the platform when the user performs a click action on the map and location
data with "latitude" and "longitude" are passed to the callback. This event is not raised if the user clicks on
map pin and callout.
Signature
JavaScript: onClick(mapwidgetid, locationdata)
Input Parameters
mapwidgetid [widgetref] - Mandatory
locationData [JSObject] - Mandatory
Specifies the location data of a single location following the data format of the "locationData"
property on the map widget. It should support both hash and array format.
Read / Write
JavaScript Example
//The below function is the callback function for onClick event.
function onClickCallBck(map)
{
alert("onClick event triggered");
}
//Defining the properties for Map with onClick:onClickCallBck
g", isVisible:true, locationData:[{lat :"17.445775",lon :"78.3731",name: "
Campus 1",desc: "My Office Campus"}], onClick:onClickCallBck};
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web (basic), BlackBerry, BlackBerry 10, and on all
Windows platforms
33.4.2 onPinClick
An event callback that is invoked by the platform when a map pin is clicked, passing the selected locationdata
to the callback.
Note: On SPA (Windows Phone) platform, a pop-over already appears when you click the pin. Hence alerts
should not be used for onPinClick event.
Signature
JavaScript: onPinClick(mapwidget, locationdata)
Lua: onpinclick(mapwidgetid, locationdata)
Input Parameters
mapwidgetid [widgetref] - Mandatory
Read / Write
Yes - (Read and Write) - On BlackBerry 10 platform, it is not writable.
JavaScript Example
//The below function is the callback function for onPinClick event.
function onPinClickCallBck(mapid, locationdata)
{
alert("onPinClick event triggered");
}
//Defining the properties for Map with onPinClick:onPinClickCallBck
g", isVisible:true, locationData:[{lat :"17.445775",lon :"78.3731",name: "
Campus 1",desc: "My Office Campus"}], onPinClick:onPinClickCallBck};
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
33.4.3 onSelection
An event callback that is invoked by the platform when the user clicks on a callout of the Map.
Signature
JavaScript: onSelection(mapwidget, locationdata)
Lua: onselection(mapwidgetid, locationdata)
Input Parameters
mapwidgetid[widgetref] - Mandatory
Read / Write
Yes - (Read and Write) - On BlackBerry 10 platform, it is not writable.
JavaScript Example
function onSelectionCallBck(mapid,locationdata)
{
}
//Defining the properties for Map with onSelection:onSelectionCallBck
g", isVisible:true, locationData:[{lat :"17.445775", lon :"78.3731", name:
"Campus 1", desc: "My Office Campus"}], onSelection:onSelectionCallBck};
var mapPSPConf={};
//Creating the Map.
Accessible from IDE

Yes
33.5 Map - Methods

The Map widget has the following methods associated with it:
l
addPolyline
clear
dismissCallout
getBounds
navigateTo
navigateToLocation
removePolyline
33.5.1 addPolyline
This method is used to add a polyline to the map widget with the given location data. You can add multiple
polylines to the map widget using this method.
Signature
JavaScript: addPolyline(locationData)
Input Parameters
Specifies the location data for which the polyline is drawn on the map. Parameters of the
locationdata are as follows:
l
id [String] [Mandatory] : Specifies the unique identifier to represent the polyline. If a

polyline already exists with the same identifier, then it gets replacesd by the new id.
startLocation [String] [Optional] : Specifies the location data for the start point of the
polyline. The values should be provided as specified in locationData property. The start
point of the polyline is represented with a map pin.
endLocation [String] [Optional] : Specifies the location data for the end point of the
polyline. The values should be provided as specified in locationData property. The start
point of the polyline is represented with a map pin.
locations [JSObject] [Optional] : Specifies the list of all the locations as an array
including start and end points. Each location object accepts "lat" and "lon" keys and
other keys are ignored.
polylineConfig [JSObject] [Optional] : Specifies an object with predefined configuration

keys. These configuration keys can hold platform specific keys as well. The following is
the list configuration keys:
o
lineColor [String] : Specifies the color of the polyline in #RBGA hex format.
lineWidth [Number]:Specifies the width of the polyline in screen independent

pixels.
Return Values
None
Exceptions
WidgetError, Error
JavaScript Examples
//addPolyline method call
mapref.addPolyline (
{
id: "polyid1",
startLocation:{lat:"43.47591",lon:"80.53964",name:"Campus
1",desc:"My College Campus",image:"marker.png",meta:{color:"green",label:"

C"}
},
endLocation:{lat:"43.47621", lon:"-80.54034", name:"Campus 2", des
c: "My School Campus",image:"ymarker.png",meta:{color:"red",label:"A"}
},
locations:[
{lat:"43.47591",lon:"-80.53964"},{lat:"44.47593",lon:"-8
1.53964"},{lat:"43.47621",lon:"-80.54034"}
]
polylineConfig:{lineColor:"0xffffff", lineWidth:"2"}
}
)
l
iPhone
iPad
33.5.2 clear
This method is used to clear all the data associated with map widget which including locationData and
polylines.
Signature
JavaScript: clear()
Input Parameters
None
Return Values
None
Exceptions
None
JavaScript Examples
//clear method call
mapref.clear()
l
iPhone
iPad
33.5.3 dismissCallout
This method is used to dismiss the custom callout for a given location. This method is ignored if the callout is
already is in dismissed state, or location argument is invalid or non-existing.
Signature
JavaScript: dismissCallout(location)
Lua: map.dismisscallout(mapid, location)
Input Parameters
mapid [widgetref] - Mandatory
Return Values
None
Exceptions
WidgetError
33.5.4 getBounds
This method returns the currently visible map boundaries as an object. The predefined keys for the object are
as follows:
l
center[JSObject] : Specifies the latitude and longitude keys and associated values.
northeast [JSObject] : Specifies the latitude and longitude keys and associated values.
southwest [JSObject] : Specifies the latitude and longitude keys and associated values.
latspan [number] : Specifies the spanning latitudes in degrees.
lonspan [number] : Specifies the spanning longitude in degrees.
Note: This method returns nil if the map is not initialized.
Signature
JavaScript: getBounds()
Input Parameters
None
Return Values
None
Exceptions
WidgetError, Error
JavaScript Examples
//getBounds method call
var bounds = mapref.getBounds();
kony.print(bounds.center);
l
iPhone
iPad
33.5.5 navigateTo
This helps to navigate programmatically from one index to other index in the given list of locations shown on
the map view.
Signature
JavaScript: navigateTo(index, showcallout)
Lua: map.navigateto(mapid, index, showcallout)
Input Parameters
Index [Number] - Mandatory
Specifies the index of the pin to which the map should navigate to. Index is calculated based on the
order of the locations that are passed to the map widget initially. Index is one based in Lua.
showCallout [Boolean] - Optional
Indicates whether to show the call out on the pin after navigating to the pin at the given index.

Return Values
None
Exceptions
WidgetError
JavaScript Examples
//Defining the properties for Map
g", isVisible:true, locationData:[{lat :"17.445775", lon :"78.3731", name:
"Campus 1", desc: "My Office Campus"}]};
var mapPSPConf={};
//Creating the Map.
//navigateTo method call
map.navigateTo(2,true);
33.5.6 navigateToLocation
This method allows you to navigate programmatically to the specified location. Based on the parameters
passed it also displays the dropPin and callout.
Note: All the values specified in this method invocation are respected only for the invocation and does not
change the original state of the map, I.e locationData that is set at the map widget level.When this method is
called in sequence, the map is navigated to the latest location and there wont be trace of the old locations
which were navigated earlier through this method on the map..
Signature
JavaScript: navigateToLocation(locationData, showcallout, dropPin)
Lua: map.navigatetolocation(mapid, locationData, showcallout, dropPin)
Input Parameters
Specifies the location data of a single location following the data format of the "locationdata"
property on the map widget. It support both hash and array formats.
showcallout [Boolean] - Optional
Indicates whether to show the callout on the pin after navigating to the pin at the given index. The
showcallout set in this API takes priority over the following:
1. showcallout defined as a part of locationdata sent to this method.
2. showcallout defined as a part of the locationData that is set at the map widget level
for a matching location.
dropPin [Boolean] - Optional
Indicates whether to drop the pin at the given location or not. If true, a pin is displayed at the given
location. Drop Pin is effective only when you navigate to a location which doesn't exist as a part of
the locationData set at the map widget level.
Note: If navigated to same location again and again by toggling dropPin property, pin is
toggled.
Return Values
None
Exceptions
WidgetError
JavaScript Examples
//Defining the properties for Map.
var mapPSPConf={};
//Creating the Map.
var locationData = {lat :"17.433451",lon :"78.432061",name: "Kids Park",de
sc: "Kids Park Near My Home"};
//navigateToLocation method call
map.navigateToLocation(locationData,true,true);
33.5.7 removePolyline
This method is used to remove a polyline from the map.
Signature
JavaScript: removePolyline(polylineID)
Input Parameters
polylineID[String] - Mandatory
Specifies the id of the polyline what is used while adding a polyline. This method is ignored if the
given id is incorrect or not found.
Return Values
None
Exceptions
WidgetError, Error
JavaScript Examples
//removePolyline method call
mapref.removePolyline("polyid1")
l
iPhone
iPad
33.6 Map - Templates

33.6.1 What is a Template for Map callout
Map template enables you to define a template for callout with specified widgets. You can use the template on
multiple maps and in multiple forms. This is primarily useful for developers to achieve common look and feel of
the callout in the map widget and the changes made to template reflect across the maps.
33.6.2 Where to use a Map callout Template

Map templates are used in the following cases:
l
To have uniform look and feel of the callout with the specified widgets.
To display different callouts for different maps.
To perform an action on a callout.
33.6.3 Creating a Template for Map callout

When you want information to be displayed across all the Maps in the application, you have a provision to add
a Map Template using Kony Studio. For more information about Map Templates refer Kony Studio User
Guide.
To create a Map Template at the application-level, follow these steps:
2. Expand the application for which you want to create the MapTemplate.
3. Navigate to templates > maps, right-click mobile/desktop/tablet and select New Map Template.
The Create a New Template window appears.
iii. Drag and drop an HBox and a VBox onto the form.
Note: Only HBox and VBox are supported on the form. You can put other
i. Drag and drop the required widgets onto the HBox/VBox. Set the properties of these
widgets. For more information, see Kony Widget User Guide.
ii. A map template is created.
33.6.4 Using Map callout Template

You can define only one template for each map using the above process.
To use map template in an application, follow these steps:
3. Navigate to forms > mobile/tablet/desktop , right-click and select New Form. The Create a New
Form window appears.
5. If you are building for desktop, select the Form in desktop and right-click on the Form. Select Fork. The
Platform Selection window appears.
6. Select Desktop_web and click OK. The form is now forked for Desktop_web and new window
appears as web_<formname>.
Note: The development activities for desktop web should happen in web_<formname> only. Although the
newly created form, remains accessible in the desktop forms.
7. Drag-drop a Map on the Form and other widgets as required. Click Save.
8. To set the template to a map, select the map and go to Properties window.
9. Select calloutTemplate and Select/Search map Template window opens. Select the template,
which you want to set to the segment.
10. Click OK.
33.7 Appendix: Generating and Configuring Map API Keys

You will need Maps API Key for Maps to work in the applications you develop. You need to generate the Maps
API key and specify it in the properties of the Map widget.
You need to configure the following map keys for your application:
l
Application Level Map widget key (generic key at application level for J2ME, MobileWeb, Blackberry
devices which do not support BlackBerry Maps)
Google Map key for Android (exclusive key for Android platform).
Bing Map key for Windows
33.7.1 Application Level Map Widget Key

The map widget key needs to be generated based on a domain name. The key generated for a single domain
can be used for all sub-domains, URLs on hosts in those domains, and all ports on those hosts. For more
information about the domain to be used for generating a map APIs key, see
http://code.google.com/apis/maps/faq.html#keysystem.
The generated map key is configured at an application level. This map key is used by all the Map widgets
within an application. This map key enables the application to display Google Maps through the Map widgets
within the application.
To configure map widget key, follow these steps:
1. Go to https://code.google.com/apis/console and log in with your Google Account.

i. Click the Services link from the left-hand menu.
ii. Activate the Google Maps API v3 service.
iii. Note the API Key that you generate.
iv. Click the API Access link from the left-hand menu. Your API key is available on the API Access
page, in the Simple API Access section. Maps API applications use the Key for browser apps.
By default, a key can be used on any site. We strongly recommend that you restrict the use of
your key to domains that you administer, to prevent use on unauthorized sites. You can specify
which domains are allowed to use your API key by clicking the Edit allowed referrers... link for
your key.
3. Right-click the required application and select Properties.
4. Enter the API Key you have generated in the Static map widget key field under Map widget.
5. Click Finish. A Clean and Rebuild window appears as shown below:
6. Click OK. The application gets built on the platforms that were selected earlier in the Build Generation
window.
Note: When you add a Map widget to a form, the map widget key you have entered in step 4
automatically appears against Google Map Key property of the Map widget. The key generated once
is applicable to all the Map widgets within an application.
This configured map widget key is applicable for all platforms except for Android. For Android you need to
generate a specific map APIs key and use it in the properties. For more information, see Google Map Key for
Android.
33.7.2 Google Map Key for Android

You need the Google Maps API key for Android in order to enable Maps in the applications you develop for
Android platform. Maps API keys are linked to specific certificate/package pairs, rather than to users or
applications.You only need one key for each certificate, no matter how many users you have for an
application. Applications that use the same certificate can use the same API key. For generating maps API
key for Android, you need to provide the fingerprint of the signed certificate. For more information about
signing Android applications, see http://developer.android.com/guide/developing/eclipse-adt.html and
https://developers.google.com/maps/documentation/android/start?hl=en
Important! Version 1 of the Google Maps Android API as been officially deprecated as of December 3rd,
2012. This means that from March 3rd, 2013 you will no longer be able to request an API key for this version.
No new features will be added to Google Maps Android API v1. However, apps using v1 will continue to
work on devices. Existing and new developers are encouraged to use Google Maps Android API v2.
To configure Google Maps API Key v2 for Android, follow these steps:
1. Please follow steps for "Displaying certificate information" and "Creating an API Project" under link
Getting the Google Maps Android API v2
2. Once you are done with "Creating API Project", make sure you turn on "Google Maps Android API v2"
service under Services section in Google API console.
3. To get the key, navigate to the Google API console:
In the left navigation bar, click API Access.
In the resulting page, click Create New Android Key....
In the resulting dialog, enter the SHA-1 fingerprint, then a semicolon, then your application's
package name. For
example:BB:0D:AC:74:D3:21:E1:43:67:71:9B:62:91:AF:A1:66:6E:44:5D:75;com.example.an
droid.mapexample
4. The Google APIs Console responds by displaying Key for Android apps (with certificates) followed by
a forty-character API key, for example: AIzaSyBdVl-cTICSwYKrZ95SuvNw7dbMuDt1KG0
5. Navigate to Properties > NativeApp > Android > Tags > Child tag entries under <application> tag. Add
the following tag <meta-data android:name="com.google.android.maps.v2.API_KEY"
android:value="Map V2 key"/>. Replace the value of the Map V2 key with the generated Map v2
key.
l
Google Maps V2 does not work on an emulator.
Multiple Map widgets per Form is not supported Map V1 (supported for MAP V2).
If MapV2 key is provided in IDE and if the application is installed on a device with Android Verison 2.2
and above (i.e kony.os.deviceInfo().APILevel >= 8 ) Google Maps Version 2 would be loaded by
default. In rest all cases Google Maps Version 1 would be loaded.
If the developer uses Google Maps V2, the developer must meet the Google Play attribution
requirements as specified at
https://developers.google.com/maps/documentation/android/intro#attribution_requirements . The
attribution text is available by using kony.os.deviceInfo().googleplayservicesoftwarelicence in Lua and
kony.os.deviceInfo().googleplayServiceSoftwareLicence in JavaScript projects respectively . This
property returns the open source software license information for the Google Play services application,
or null when either Google Play services is not available on this device or MapV2 Key is not added in
application properties.
Map does not work on a popup.
Map preview launches only version 1 map
Map V2 works for Android 2.2 and above.
Clickable/Interactive widgets inside a Map callout template will become non-clickable when Android
Map V2 version is used. This is the limitation of native Android Map V2 callout. As callouts are
displayed as static image snapshot of callout template and only the entire callout is clickable.
onSelection event callback is invoked when a callout is clicked.
You need to update the "Android SDK Tools"," Android SDK Platform-tools" to the latest revision using
under SDK Manager (Min revision of Android SDK Tools required is >=15 for Android Google MapV2).
Android Google MapsV2 requires OpenGL ES version 2 to load.
You need to download the latest Google Play Services sdk using the SDK Manager. To do so, navigate
to Extras > Google Play Services. Please refer to the links below for additional information on how
Android Google Play and Google MapsV2 work
o
http://developer.android.com/google/play-services/index.html
http://developer.android.com/google/play-services/setup.html
http://developer.android.com/google/play-services/maps.html
33.7.3 Bing Map Key for Windows

To generate a Bing Map Key for Windows platforms, refer http://msdn.microsoft.com/enus/library/ff428642.aspx.
Navigate to Application>Properties and enter the obtained key in the Bing map widget key field.

l
Application Level Map Widget Key


your key.
window.
Android.
Google Map Key for Android
package name. For
droid.mapexample
key.
l
o
Bing Map Key for Windows


l


your key.
window.
Android.
package name. For
droid.mapexample
key.
l
o


l


your key.
window.
Android.
package name. For
droid.mapexample
key.
l
o

34. ObjectSelector3D
The ObjectSelector3D widget can be used for allowing the user to select homogeneous objects arranged on a
two-dimensional grid. It provides the user with a three-dimensional graphical view of the objects which makes
it more attractive than regular two-dimensional images. It has two modes, a selection mode and a walkthrough mode.
The selection mode provides you with a top view of the grid of 3D objects and allows the user to tap on objects
to select/unselect them. At any time, the user can hold down on a selected object and the widget will go into
walk-through mode.
In walk-through mode, the user is shown a simulation of how it would appear if the user were to start from a
starting point and walk (on foot) up to the selected object.
Note: To use the ObjectSelector3D widget, you must load the 3D models. For more information about
loading the models, see Kony Studio User Guide.
The ObjectSelector3D widget provides you with an option to set Basic Properties, Layout Properties, an
Event, and Methods.
This widget is supported only on Windows Phone 7 (Mango) platform.
Basic Properties
Layout Properties
Methods
focusSkin
id
info
isVisible
skin
text
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
addModel
clearAllData
defineSpecialModels
getSelectedCells
setCameraProperties
setMapData
setRequiredSelectionsCount
setSelectedCells
Event
onSelectionDone
Creating a ObjectSelector3D using a constructor: kony.ui.ObjectSelector3D

var myOS3D = new kony.ui.ObjectSelector3D (basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//The below function is the callback function for onSelectionDoneCalBck ev

ent
function onSelectionDoneCalBck(objThreeD)
{
}
//Defining the properties for ObjectSelector3D with onSelectionDone:onSele
ctionDoneCalBck
var objBasic = {id:"objThreeD", skin:"ObjSkin", focusSkin:"ObjFSkin", text
:"Seat reservation", isVisible:true, onSelectionDone:onSelectionDoneCalBc
k};
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, padding:[5
,5,5,5], margin:[5,5,5,5], contentAlignment:constants.CONTENT_ALIGN_CENTER,
containerWeight:99, paddingInPixel:true, marginInPixel:true, hExpand:false,
vExpand:false};
//Creating the ObjectSelector3D.
var objThreeD =new kony.ui.ObjectSelector3D(objBasic, objLayout, {}) ;
When do I use an ObjectSelector3D widget?

You can use an ObjectSelector3D in the following scenarios:
l
To display identical elements where the user wants to make the selection of his choice (for example, in
a Travel Application, you can provide all the seats indicating reserved and unreserved tickets of a
flight, train or bus. While booking the seats, let the user select his preference.
You can also use this widget in applications to book a seat in a stadium or a cinema hall leaving the
selection of seats to the customer.
Selection modes in different modes:

The appearance of the widget using a cube model on Windows Phone (Mango) platform is as follows:
Selection Mode
Walk-through Mode
Adding a ObjectSelector3D Widget from IDE

The steps involved in adding a ObjectSelector3D widget are as follows:
1. Drag and drop the ObjectSelector3D widget onto a form (occupies the complete available width). Or,
based on your requirements, you can choose to resize a ObjectSelector3D widget in the horizontal
direction by placing an HBox on the form and by dragging and dropping the ObjectSelector3D widget
inside the HBox and resizing accordingly.
2. It is applicable only on Windows Phone (Mango) platform.
3. It uses the models added in the IDE through the project properties. If the models are not loaded you
won't be able to use this widget.
4. Use the text property and specify the text to be displayed on the ObjectSelector3D.
5. Define an onSelectionDone event.
You can customize the appearance of the ObjectSelector3D by using the following properties:
l
skin: Specify the skin to be applied to the ObjectSelector3D widget.
focusSkin: Specify the skin to be applied to the ObjectSelector3D when in focus.
On Windows Phone (Mango) platform, you must ensure the following:
l
This widget cannot be used without the models being loaded in the project.
For performance reasons, the models being used must be specifically designed for real-time rendering.
This widget is only useful where objects must be selected out of a homogeneous set (i.e., all the
objects must be the same kind. For example, seats in a bus.)
34.1 ObjectSelector3D - Basic Properties

The basic properties for ObjectSelector3D Widget are as follows:
l
focusSkin
id
info
isVisible
skin
text
34.1.1 focusSkin
Specifies the look and feel of the ObjectSelector3D when in focus.
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with focusSkin:"ObjFSkin"
:"Seat reservation", isVisible:true};

,5,5,5], contentAlignment:constants.CONTENT_ALIGN_CENTER, containerWeight:
99, margin:[5,5,5,5], paddingInPixel:true, marginInPixel:true, hExpand:fal
se, vExpand:false};
//Reading focusSkin of the ObjectSelector3D
alert("ObjectSelector3D focusSkin is ::"+objThreeD.focusSkin);
Accessible from IDE

Yes
Available on Windows Phone (Mango) platform only.
34.1.2 id
id is a unique identifier of ObjectSelector3D consisting of alpha numeric characters. Every ObjectSelector3D
should have a unique id within a Form.
Syntax
JavaScript: id
Lua: id
Type
JavaScript: String
Lua: String
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for ObjectSelector3D with id:"objThreeD"
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, contentAli
gnment:constants.CONTENT_ALIGN_CENTER, containerWeight:99, padding:[5,5,5,
5], margin:[5,5,5,5], paddingInPixel:true, marginInPixel:true, hExpand:fal
se, vExpand:false};

//Reading id of the ObjectSelector3D.
alert("ObjectSelector3D id is ::"+objThreeD.id);
Accessible from IDE

Yes
34.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with info property.
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, contentAli
gnment:constants.CONTENT_ALIGN_CENTER, containerWeight:99, padding:[5,5,5,
5], margin:[5,5,5,5], paddingInPixel:true, marginInPixel:true, hExpand:fal
se, vExpand:false};
objThreeD.info = {key:"OS3D images"};
//Reading info of the ObjectSelector3D.
alert("ObjectSelector3D info is ::"+objThreeD.info);
Accessible from IDE

No
34.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with isVisible:true
99, margin:[5,5,5,5], paddingInPixel:true, marginInPixel:true, hExpand:fa
lse, vExpand:false};
//Reading visibility of the ObjectSelector3D.
alert("ObjectSelector3D visibility is ::"+objThreeD.isVisible);
Accessible from IDE

Yes
34.1.5 skin
Specifies a background skin for ObjectSelector3D widget.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with skin:"ObjSkin"
var objBasic = {id:"objThreeD", skin:"ObjSkin", focusSkin:"ObjFSkin",
text:"Seat reservation", isVisible:true};

,5,5,5], contentAlignment:constants.CONTENT_ALIGN_CENTER,containerWeight:9
se, vExpand:false};
//Reading skin of the ObjectSelector3D
alert("ObjectSelector3D skin is ::"+objThreeD.skin);
Accessible from IDE

Yes
34.1.6 text
Specifies a general or descriptive text for the ObjectSelector3D widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
//Defining the properties for ObjectSelector3D with text:"Seat reservation"
se, vExpand:false};

//Reading text of the ObjectSelector3D.
alert("ObjectSelector3D text is ::"+objThreeD.text);
Accessible from IDE

Yes
34.2 ObjectSelector3D - Layout Properties

The layout properties for ObjectSelector3D Widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with containerWeight:70
se, vExpand:false};
Accessible from IDE

Yes
Specifies the alignment of the text on the ObjectSelector3D with respect to its boundaries. A default value
CONTENT_ALIGN_MIDDLE_LEFT is assigned for all platforms. To choose another alignment, click the
drop-down arrow and select the desired alignment. However, to change the default value on a particular
platform, select the button next to the drop-down and select respective platform and choose the value.
l
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the widget.

widget.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for ObjectSelector3D with contentAlignment:const
ants.CONTENT_ALIGN_CENTER
var objBasic = {id:"objThreeD", skin:"ObjSkin",focusSkin:"ObjFSkin", text:
"Seat reservation", isVisible:true};
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, paddingInP
ixel:true, marginInPixel:true, contentAlignment:constants.CONTENT_ALIGN_CE
NTER, containerWeight:99, padding:[5,5,5,5], margin:[5,5,5,5], hExpand:fal
se, vExpand:false};
Accessible from IDE

Yes
34.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ObjectSelector3D with hExpand:false
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, margin:[5,
5,5,5], paddingInPixel:true, contentAlignment:constants.CONTENT_ALIGN_CENT
ER, containerWeight:99, padding:[5,5,5,5], marginInPixel:true, hExpand:fal
se, vExpand:false};
Accessible from IDE

Yes
34.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with margin:[5,5,5,5]
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, margin:[5,
5,5,5], paddingInPixel:true, contentAlignment:constants.CONTENT_ALIGN_CENT
ER, containerWeight:99, padding:[5,5,5,5], marginInPixel:true, hExpand:fal
se, vExpand:false};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ObjectSelector3D with marginInPixel:true
vExpand:false};
Accessible from IDE

Yes
34.2.6 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for ObjectSelector3D with padding:[5,5,5,5]
vExpand:false};
Accessible from IDE

Yes
Default: false
Note: This property can be set to true or false only for iPhone, iPad, Android and Windows Mobile 7. On
other platforms this property does not give any results even when set to true.
Android and Windows Mobile 7 and for other platforms it will be false.
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ObjectSelector3D with paddingInPixel:true
vExpand:false};
Accessible from IDE

Yes
34.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for ObjectSelector3D with vExpand:false
vExpand:false};
Accessible from IDE

Yes
l
WIDGET_ALIGN_CENTER
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for ObjectSelector3D with widgetAlignment:consta
nts.WIDGET_ALIGN_CENTER
se, vExpand:false};
Accessible from IDE

Yes
34.3 ObjectSelector3D - Event

ObjectSelector3D has the following event associated with it:
l
onSelectionDone
34.3.1 onSelectionDone
An event callback that is invoked by the platform when an Image is selected in ObjectSelector3D .
Signature
JavaScript: onSelectionDone
Lua: onselectiondone
Read / Write
JavaScript Example
//The below function is the callback function for onSelectionDoneCalBck ev
ent
function onSelectionDoneCalBck(objThreeD)
{
}
//Defining the properties for ObjectSelector3D with onSelectionDone:onSele
ctionDoneCalBck
:"Seat reservation", isVisible:true,
onSelectionDone:onSelectionDoneCalBck};
vExpand:false};
Accessible from IDE

Yes
34.4 ObjectSelector3D - Methods

The ObjectSelector3D widget has the following methods associated with it:
l
addModel
clearAllData
defineSpecialModels
getSelectedCells
setCameraProperties
setMapData
setRequiredSelectionsCount
setSelectedCells
34.4.1 addModel
This method allows you to add a new model to the widget's working set of models.
Signature
JavaScript: addModel(modelId, resourceName, scale)
Lua: OS3D.addmodel(os3did, modelId, resourceName, scale)
Input Parameters
modelId [Number] - Mandatory
User defined identifier which can be used to refer to this model.
resourceName [String] - Mandatory
Specifies the name of the resource to load model data.
Note: The resourceName is the original file name of the model without any file extension to it.
For example, if the original model file name is Box_Normal.fbx, the corresponding
resourceName would be Box_Normal. For more information on how to add models to the
application, refer to the section Adding Models to the Application from IDE in Kony Studio
User Guide.
scale [Number] - Mandatory
Specifies the scale factor to reduce/increase the size of the loaded model. It can be any valid
number.
For example, a scale of 1.0 will not cause any change to the model's size. A scale of 0.5 will cause
the model to be scaled to half of its original size and a scale of 2.0 will cause the model to be scaled
to double its original size.
os3did [widgetref ] - Mandatory
Return Values
None
Exceptions
None
JavaScript Examples
//Defining the properties for ObjectSelector3D
var objBasic = {id:"objThreeD",skin:"ObjSkin",focusSkin:"ObjFSkin",text:"S
eat reservation",isVisible:true};
vExpand:false};
//addModel method call.
objThreeD.addModel(1, "Flight_Down_Up_01", 0.371);
34.4.2 clearAllData
This method allows you to clear all the data set on the widget.
Signature
JavaScript: clearAllData()
Lua: OS3D.clearalldata(os3did)
Input Parameters
Return Values
None
Exceptions
None
JavaScript Examples
vExpand:false};
//clearAllData method call.
objThreeD.clearAllData();
34.4.3 defineSpecialModels
This method allows you to define the models to the widget. The widget needs to know the models that
represent selected/unselected items.
Signature
JavaScript: defineSpecialModels(unselectedModelId, selectedModelId)
Lua: OS3D.definespecialmodels(os3did, unselectedModelId, selectedModelId)
Input Parameters
unselectedModelId [Number] - Mandatory
Specifies the model which represents unselected items.
selectedModelId [Number] - Mandatory
Specifies the model which represents selected items.
Return Values
None
Exceptions
None
JavaScript Examples
vExpand:false};
//defineSpecialModels method call
objThreeD.defineSpecialModels(3, 4);
34.4.4 getSelectedCells
This method allows you to retrieve the cells that are currently selected in the widget.
Signature
JavaScript: getSelectedCells()
Lua: OS3D.getselectedcells(os3did)
Input Parameters
Return Values
An array of cell locations in the format {row,column}.
Exceptions
None
JavaScript Examples
var objLayout = {widgetAlignment:constants.WIDGET_ALIGN_CENTER, padding:
[5,5,5,5], margin:[5,5,5,5], contentAlignment:constants.CONTENT_ALIGN_CENT

ER, containerWeight:99, paddingInPixel:true, marginInPixel:true, hExpand:f
alse, vExpand:false};
//getSelectedCells method call
var result=objThreeD.getSelectedCells();
34.4.5 setCameraProperties
This method allows you to set the properties of the camera while in walk-through mode.
Signature
JavaScript: setCameraProperties(movementSpeed, height, entryLocations)
Lua: OS3D.setcameraproperties(os3did, movementSpeed, height, entryLocations)
Input Parameters
movementSpeed [Number] - Mandatory
Specifies the speed at which the camera should move(in seconds).
height [Number] - Mandatory
Specifies the height at which the camera will be placed above the XZ plane.
entryLocations [JSObject] - Mandatory
Specifies the list of cell locations in the format {row, column}. In Walk-through mode, the closest
entry point to the selected seat is automatically chosen.
Return Values
An array of cell locations in the format {row,column}.
Exceptions
None
JavaScript Examples
vExpand:false};
//setCameraProperties method call
objThreeD.setCameraProperties(1.5, 2.5, [[1,4] ]);
34.4.6 setMapData
This method allows you to define the map of objects which will be presented to the user for selecting the
items.
Signature
JavaScript: setMapData(rows, columns, cellWidth, cellDepth, data)
Lua: OS3D.setmapdata(os3did, rows, columns, cellWidth, cellDepth, data)
Input Parameters
rows [Number] - Mandatory
Specifies the number of rows of the map.
columns [Number] - Mandatory
Specifies the number of columns of the map.
cellWidth [Number] - Mandatory
Specifies the width (in world units) for each object.
cellDepth [Number] - Mandatory
Specifies the depth (in world units) for each object.
Specifies a two-dimensional array which specifies which model is present in each cell of the map.

Return Values
None
Exceptions
None
JavaScript Examples
//Defining the properties for ObjectSelector3D.
vExpand:false};
//setMapData method call
objThreeD.setMapData(12, 7, 1, 1.774,[
0, 6, 6, 7, 6, 6, 0,
5, 3, 2, 1, 2, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 3, 3, 1, 3, 3, 5,
5, 2, 2, 1, 2, 2, 5,
]);
Note: Selected models cannot be specified in the data, use the setselectedcells method to specify the data.
34.4.7 setRequiredSelectionsCount
This method allows you to define the number of objects the user must select for the selection process to be
considered complete.
Signature
JavaScript: setRequiredSelectionsCount(count)
Lua: OS3D.setrequiredselectionscount(os3did, count)
Input Parameters
count [Number] - Mandatory
Specifies the number of objects the user must select.
Return Values
None
Exceptions
None
JavaScript Examples
//Defining the properties for ObjectSelector3D.
vExpand:false};
//setRequiredSelectionsCount method call.
objThreeD.setRequiredSelectionsCount(3);
34.4.8 setSelectedCells
This method allows you to identify the cells that are initially selected in the map.
Signature
JavaScript: setSelectedCells(array)
Lua: OS3D.setselectedcells(os3did, array)
Input Parameters
array [JSObject] - Mandatory
Contains a list of cell locations with the format{row, column}.
Return Values
None
Exceptions
None
JavaScript Examples
vExpand:false};
//setSelectedCells method call
objThreeD.setSelectedCells([[4, 3], [5, 5] ] );
35. Phone
A Phone widget, when placed in an application, allows you to launch the native phone dialer and initiate a
phone call to the number that is displayed on it. It appears as a button on the Form and the phone number is
displayed on it either in the number format or the phone spell text. When the user selects the phone widget,
the native dialer is launched to make a phone call.
Note: Phone widget is not applicable for Server side Mobile Web, Desktop Web, Windows 8 Tablet, and
Windows 7 Kiosk platforms.
You can use a Phone widget in the following scenarios:
l
To build applications for both Native and Mobile Web.

You can use phone.dial API in your application to initiate a call. But, the Mobile Web platforms do not
support this API. To overcome this you must use the Phone widget to be able to initiate a call from both
Native and Mobile Web platforms.
The convenience of providing a call initiation feature. Which otherwise, for the call initiation feature you
must use a button and define an onclick event or use a RichText widget.
Phone widget provides you with an option to set Basic Properties and Layout Properties.
Basic Properties
Layout Properties
focusSkin
id
isVisible
skin
text
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Widget Appearance on Platforms:

The appearance of the Phone widget with a phone number on various platforms is as follows:
Platform
Appearance
Android
Platform
Appearance
BlackBerry
iPhone
Windows
Adding a Phone Widget from IDE

The steps involved in adding a Phone widget are as follows:
1. From the IDE, drag and drop the Phone widget onto a form (occupies the complete available width). Or,
a. If you want to resize a Phone widget in the horizontal direction, place an HBox on the form and
drag and drop the Phone widget inside the HBox and resize accordingly.
b. If you want to resize a Phone widget in the vertical direction, place an HBox on the form and
place a VBox inside the HBox; and drag and drop the Phone widget inside the VBox and resize
accordingly.
2. Use the text property to enter the phone number or phone spell text to which the call must be initiated.
You can customize the appearance of the Phone by using the following properties:
l
hExpand: Expand the widget horizontally.
vExpand: Expand the widget vertically.
The following is the important consideration for a Phone widget:
J2ME: Unlike other platforms (for example Android, BlackBerry etc.) you will not be able to simulate a Phone
widget behavior on an emulator.
35.1 Phone - Basic Properties

The basic properties for Phone widget are as follows:
l
focusSkin
id
isVisible
skin
text
35.1.1 focusSkin
Specifies the look and feel of the Phone when in focus.
Type
String
Read / Write
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, Desktop Web, BlackBerry 10, Windows
Tablet, and Windows Kiosk platforms.
35.1.2 id
id is a unique identifier of Phone consisting of alpha numeric characters. Every Phone should have a unique id
within an Form.
Type
String - [Mandatory]
Read / Write
Yes - (Read only)
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, Desktop Web, Windows Tablet, and
Windows Kiosk platforms.
35.1.3 isVisible
Default: true
Type
Boolean
Read / Write
Accessible from IDE

Yes
35.1.4 skin
Specifies the look and feel of the Phone when not in focus.
Type
String
Read / Write
Accessible from IDE

Yes
35.1.5 text
Specifies a general or descriptive text for the Phone widget.
Type
String
Read / Write
Accessible from IDE

Yes
35.2 Phone - Layout Properties

The layout properties for Phone widget are as follows:
l
containerWeight
contentAlignment
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
Read / Write
Accessible from IDE

No
Specifies the alignment of the text on the Phone with respect to its boundaries. A default value CONTENT_
center of the widget)
l
CONTENT_ALIGN_CENTER- Specifies the text should align at center of the widget.

widget.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
Accessible from IDE

Yes
35.2.3 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, Desktop Web, SPA, Windows Tablet,
and Windows Kiosk platforms.
35.2.4 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web (basic), Desktop Web, Windows Tablet,
and Windows Kiosk platforms.
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
Accessible from IDE

Yes
Available on all platforms except Windows Tablet
35.2.6 padding
Note: If no skin is applied to a Call, then Padding is not supported on iPhone. This is due to iOS Safari
browser limitation. If you want the padding to be applied, apply a skin to the widget and then apply padding.
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web(basic), Desktop Web, Windows Tablet,
BlackBerry 10, and Windows Kiosk platforms.
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
Accessible from IDE

Yes
35.2.8 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
Accessible from IDE

Yes
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
Accessible from IDE

Yes
36. PickerView
A PickerView widget uses a spinning wheel metaphor to display multiple sets of values and allows you to
select a single combination of values. You can select a single combination of values by rotating the wheels
and aligning the desired row of values with the selection indicator.
PickerView can have multiple components and each component comprises of keys. Users can choose the
keys from different components and make the choices .. useful in grouping the multiple choices that user can
make in different categories related to concept. For example: color, model, year of manufacturing all these
three can be modeled as components with different possible values so that user can make his choice using
this single widget.
Note: PickerView widget is not supported in Windows 7 Kiosk, Desktop Web, SPA, BlackBerry 10, and on
all Server side Mobile Web platforms. To implement PickerView in Desktop Web platform, the developer is
expected to make use of multiple list boxes to achieve similar functionality.
Basic Properties
Layout Properties
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKeys
selectedKeyValues
skin
containerWeight
hExpand
margin
marginInPixel
widgetAlignment
Events
Methods
onSelection
setComponentData
setSelectedKeyInComponent
Creating a PickerView using a constructor: kony.ui.PickerView

var picker = new kony.ui.PickerView(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//The below function is the callback function for onSelect event.
function onSelectCalBck(picker)
{
/*write your logic here*/
}
//Defining the properties for PickerView with onSelect:onSelectCalBck.
var pickerBasic = {id:"picker", info:{key:"PickerView"}, skin:"pickerSkin",
focusSkin:"pickerFSkin", masterData:[[["y1","2009"],["y2","2010"],["y3","2
011"], 40],[["m1","Jan"], ["m2", "Feb"], ["m3","Mar"], ["m4","Apr"],["m5",
"May"], ["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y
2","m1"] , onSelect:onSelectCalBck};
var pickerLayout = {margin:[5,5,5,5], marginInPixel:true, widgetAlignment:
constants.WIDGET_ALIGN_CENTER, hExpand:true, containerWeight:99};
//Creating the PickerView.
var picker = new kony.ui.PickerView(pickerBasic, pickerLayout, {});
//Reading onSelect of the pickerView.
kony.print("pickerView onSelect event::"+picker.onSelect);

The appearance of the PickerView widget on various platforms is as follows:
Platform
Appearance
Android
Platform
Appearance
iPhone
Appearance on Windows Phone

On Windows Phone, the PickerView widget appears as a button and displays the selected combination of
values. If you touch the button, the PickerView window opens and you can select the desired values.
The following image illustrates the appearance of the widget when rendered:
When do I use a PickerView Widget?

You can use a PickerView widget in the following scenario:
l
When you want a user to make multiple selections and arrive at a combination of the selected values.
For example, for Flight Bookings, if you want the user to select one of the available dates, time, and
flight number; you can create lists for date, time, and flight numbers and display them in a PickerView
widget.
Adding a PickerView Widget from IDE

The steps involved in adding a PickerView widget are as follows:
1. From the IDE, drag and drop the PickerView onto a form (occupies the complete available width). Or, based
on your requirements, you can choose to perform any of the following options:
a. If you want to resize the PickerView widget in the horizontal direction, place an HBox on the
form and drag and drop the PickerView widget inside the HBox and resize accordingly.
b. If you want to align multiple PickerView widgets in the horizontal direction, place an HBox on
the form and drag and drop the PickerView widgets inside the HBox.
c. If you want to align multiple PickerView widgets in the vertical direction, place an HBox on
the form and place a VBox inside the HBox; and drag and drop the PickerView widgets inside
the VBox.
2. Define the Master Data from the IDE (masterData) or through code (masterDataMap) for the PickerView
widget.
3. For programming purposes, if you want to set some values as pre-selected values or find the values
selected by the user, use the selectedKeys and the selectedKeyValues respectively.
5. (Optional) If you want to change the data in one of the components of the PickerView widget from the code
after you have set the masterData, you can use the setComponentData method.
6. (Optional) If you want to set a value as the selected value in one of the components of the PickerView
widget, you can use the setSelectedKeyInComponent method.
Pitfalls
The following are the pitfalls to avoid for a PickerView widget:
l
You must avoid resizing a PickerView widget or placing multiple PickerView widgets side- by- side in
the horizontal direction.
You must avoid doing so because, by resizing or placing multiple PickerView widgets side- by- side in
the horizontal direction, when the PickerView widget is rendered, the PickerView widget alignment
might not be confined to the screen width and results in a bad user experience.
Limitations
PickerView widget is not supported in Windows Phone, Windows 7 Kiosk, Desktop Web, SPA, and on all
Server side Mobile Web platforms
36.1 PickerView - Basic Properties

The basic properties of PickerView Widget are as follows:
l
focusSkin
id
info
isVisible
masterData
masterDataMap
selectedKeys
selectedKeyValues
skin
36.1.1 focusSkin
Specifies the look and feel of the PickerView widget when it is in focus.
Note: Not applicable for iPhone / iPad currently. Even if configured will be ignored in case of iPhone and
iPad.
1. On J2ME non-touch devices, if you do not specify the focus skin, it is not possible to identify the focus
Syntax
Lua: focusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for PickerView with focusSkin:"pickerFSkin"
focusSkin:"pickerFSkin", masterData:[[["y1","2009"],["y2","2010"], ["y3","
2011"], 40], [["m1","Jan"],["m2", "Feb"], ["m3","Mar"], ["m4","Apr"],["m5"
,"May"], ["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["
y2","m1"] };
//Reading focusSkin of the pickerView
alert("pickerView focusSkin is ::"+picker.focusSkin);
Accessible from IDE

Yes
Available on all platforms except iOS, Desktop Web, Windows Kiosk, SPA, BlackBerry 10, and on all
Server side Mobile Web platforms.
36.1.2 id
id is a unique identifier of PickerView consisting of alpha numeric characters. Every PickerView should have a
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for PickerView with id:"picker"
var pickerBasic = {id:"picker",info:{key:"PickerView"}, skin:"pickerSkin",
focusSkin:"pickerFSkin", masterData:[[["y1","2009"], ["y2","2010"], ["y3",
"2011"], 40], [["m1","Jan"],["m2", "Feb"],["m3","Mar"], ["m4","Apr"],["m5"
,"May"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y
2","m1"] };
//Reading id of the pickerView
alert("pickerView id is ::"+picker.id);
Accessible from IDE

Yes
Available on all platforms except on all Server side Mobile Web, Windows Kiosk, SPA, BlackBerry 10,
36.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for PickerView with info property.
var pickerBasic = {id:"picker", skin:"pickerSkin", focusSkin:"pickerFSkin",
masterData:[[["y1","2009"],["y2","2010"],["y3","2011"], 40],[["m1","Jan"],
["m2", "Feb"],["m3","Mar"], ["m4","Apr"],["m5","May"],["m6","Jun"], ["m7",
"Jul"], 60]],isVisible:true, selectedKeys:["y2","m1"] };
picker.info = {key:"PickerView"};
//Reading info of the pickerView
alert("pickerView info is ::"+picker.info);
Accessible from IDE

No
36.1.4 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for PickerView with isVisible:true
focusSkin:"pickerFSkin", masterData:[[["y1","2009"], ["y2","2010"], ["y3",
"2011"], 40], [["m1","Jan"], ["m2", "Feb"],["m3","Mar"], ["m4","Apr"], ["m
5","May"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:[
"y2","m1"] };
//Reading isVisible of the pickerView
kony.print("pickerView isVisible is ::"+picker.isVisible);
Accessible from IDE

Yes
36.1.5 masterData
PickerView window.
You can add the components by clicking the "+" button.
The following screen shot illustrates the MasterData for pickerview window:
The key and value should be of string data type
[
//0th component
[
["key1","value1", accessibilityConfigObject],
["key2","value2", accessibilityConfigObject],....,
["keyn", "valuen", accessibilityConfigObject], componentWidth
],
//1st component
[
["key1","value1", accessibilityConfigObject],
["key2","value2", accessibilityConfigObject],....,
["keyn", "valuen", accessibilityConfigObject], componentWidth
],
]
Syntax
Lua: masterdata
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for PickerView with masterData:[[["y1","2009"],
["y2","2010"],["y3","2011"], 40], [["m1","Jan"], ["m2", "Feb"], ["m3","Ma
r"], ["m4","Apr"], ["m5","May"], ["m6","Jun"], ["m7","Jul"], 60]]
focusSkin:"pickerFSkin", masterData:[[["y1","2009", accessibilityConfigObj
ect],["y2","2010", accessibilityConfigObject], ["y3","2011",
accessibilityConfigObject], 40],[["m1","Jan", accessibilityConfigObject],

["m2", "Feb", accessibilityConfigObject],["m3","Mar", accessibilityConfigO
bject], ["m4","Apr", accessibilityConfigObject], ["m5","May", accessibilit
yConfigObject], ["m6","Jun", accessibilityConfigObject], ["m7","Jul", acce
ssibilityConfigObject], 60]], isVisible:true, selectedKeys:["y2","m1"] };
var pickerLayout = {margin:[5,5,5,5],marginInPixel:true,widgetAlignment:co
nstants.WIDGET_ALIGN_CENTER,hExpand:true,containerWeight:99};
//Reading masterData of the pickerView
alert("pickerView masterData is ::"+picker.masterData);
Accessible from IDE

Yes
Specifies the set of values from which you can make one or more selections. You must set the values from
the code.
It is array of arrays. masterdatamap format: leaf level with four elements represents the component data,
[0] is the array of JS objects with hashes. Component with the keys and values
[1] is the item key's key in the data hash of [0]
[2] is the item value's key in the data hash of [0]
[3] is the components width.
For example: data for PickerView with 2 components with width set as 30 and 70.
[
//0th component
[
[
{key1="datakey1", value1="dataValue1", "accessibilityconfig":acObje
ct},
{key1="datakey2", value1="dataValue2",
"accessibilityconfig":acObject},
ct},
key1,value1,30
]
]
//1st component
[
[
ct},
ct},
ct},
key1,value1,30
]
]
]
masterDataMap to set data for the PickerView.
Syntax
Lua: masterdatamap
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for PickerView with masterDataMap:[[[{key1:"y1
",value1:"2001"}, {key1:"y2",value1:"2002"}, {key1:"y3",value1:"2003"} ],
yearid,yearvalue,60 ],[[
{key2:"m1",value2:"jan"}, {key2:"
m2",value2:"feb"}, {key2:" m3",value2:"mar"} ], monid, monvalue, 40]]

focusSkin:"pickerFSkin", masterDataMap:[[[{key1:"y1",value1:"2001", "acc
essibilityconfig":acObject}, {key1:"y2", value1:"2002", "accessibilitycon
fig":acObject},{key1:"y3",value1:"2003", "accessibilityconfig":acObject} ]
,yearid,yearvalue,60 ],[[
{key2:"m1", value2:"jan", "accessibilityco
nfig":acObject}, {key2:" m2",value2:"feb", "accessibilityconfig":acObject},
{key2:" m3",value2:"mar", "accessibilityconfig":acObject} ], monid,monvalu
e, 40]], isVisible:true, selectedKeys:["y2","m1"] };
//Reading masterDataMap of the pickerView
alert("pickerView masterDataMap is ::"+picker.masterDataMap);
Accessible from IDE

No
36.1.7 selectedKeys
If you create a PickerView with multiple values, you can choose to show specific values as selected when the
PickerView is rendered. Returns the array of selected keys from the masterdata representing the selected
key. If you set the selectedkeys to null/nil, the selection is cleared.
Syntax
Lua: selectedkeys
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for PickerView with selectedKeys:["y2","m1"]
focusSkin:"pickerFSkin", masterData:[[["y1","2009"],["y2", "2010"],["y3","
2011"], 40],[["m1","Jan"],["m2", "Feb"],["m3","Mar"], ["m4","Apr"], ["m5",
"May"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y2
","m1"] };
//Reading selectedKeys of the pickerView
alert("pickerView selectedKeys is ::"+picker.selectedKeys);
Accessible from IDE

No
Returns the array of selected key-value pairs selected from the masterdata representing the selected key
value.
If you do not select a value, the return value is null/nil is returned.
Syntax
Lua: selectedkeyvalues
Type
JavaScript: Array
Lua: Table
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for PickerView with id:"picker"
focusSkin:"pickerFSkin",masterData:[[["y1","2009"],["y2","2010"],["y3","20
11"], 40],[["m1","Jan"],["m2", "Feb"],["m3","Mar"], ["m4","Apr"],["m5","Ma
y"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y2","
m1"] };
//Reading selectedKeyValues of the pickerView
.kony.print("pickerView selectedKeyValues is ::"+picker.selectedKeyValues);
Accessible from IDE

No
36.1.9 skin
Specifies the look and feel of the button when not in focus. It is the skin which is applied at the widget level.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for PickerView with skin:"pickerSkin"
011"], 40],[["m1","Jan"],["m2", "Feb"],["m3","Mar"], ["m4","Apr"],["m5","M
ay"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y2",
"m1"] };
//Reading skin of the pickerView
alert("pickerView skin is ::"+picker.skin);
Accessible from IDE

Yes
Available on all platforms except iOS, on all Server side Mobile Web, Windows Kiosk, SPA, BlackBerry
10, and Desktop Web platforms
Note: On iOS platform, even if the skin is configured, is ignored.
36.2 PickerView - Layout Properties

The Layout properties for PickerView Widget are as follows:
l
containerWeight
hExpand
margin
marginInPixel
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for PickerView with containerWeight:70.
var pickerBasic = {id:"picker", info:{key:"PickerView"},skin:"pickerSkin",
focusSkin:"pickerFSkin", masterData:[[["y1","2009"], ["y2","2010"],["y3","
2011"], 40],[["m1","Jan"],["m2", "Feb"],["m3","Mar"], ["m4","Apr"],["m5","
May"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y2"
,"m1"] };
//Reading containerWeight of the pickerView
alert("pickerView containerWeight is ::"+picker.containerWeight);
Accessible from IDE

No
36.2.2 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for PickerView with hExpand:true
ay"],["m6","Jun"], ["m7","Jul"], 60]],isVisible:true,selectedKeys:["y2","m
1"] };
Accessible from IDE

Yes
36.2.3 margin
Margin screen. Select the PickerView against the platform for which you want to define the margins and enter
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for PickerView with margin:[5,5,5,5]
var pickerBasic = {id:"picker",info:{key:"PickerView"},skin:"pickerSkin",
ay"],["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y2",
"m1"] };
//Reading margin of the pickerView.
alert("pickerView margin is ::"+picker.margin);
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for PickerView with marginInPixel:true.
ay"],["m6","Jun"], ["m7","Jul"], 60]],isVisible:true,selectedKeys:["y2","m
1"] };
Accessible from IDE

Yes
l
iPhone
iPad
l
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for PickerView with widgetAlignment:constants.WI
DGET_ALIGN_CENTER
011"], 40],[["m1","Jan"],["m2", "Feb"],["m3","Mar"], ["m4","Apr"],
["m5","May"],["m6","Jun"], ["m7","Jul"], 60]],isVisible:true,selectedKeys:

["y2","m1"] };
Accessible from IDE

Yes
36.3 PickerView - Event

The PickerView widget has the following event associated with it:
l
onSelection
36.3.1 onSelection
An event callback that is invoked by the platform when the component selection changes.
Signature
JavaScript: onSelection(pickerViewRef, component, keySelected)
Lua: onselection(pickerViewRef, component, keySelected)
Input Parameters
pickerViewRef [widgetref] - Mandatory
component [Number] - Mandatory
Specifies the component of the pickerview.
keySelected [String ] - Mandatory
Specifies the selected key of the component.
Return Values
None
Syntax
JavaScript: onSelect
Lua: onselect
Read / Write
JavaScript Example
//The below function is the callback function for onSelection event.
function onSelectCalBck(picker)
{
}
//Defining the properties for PickerView with onSelection:onSelectCalBck.
011"], 40],[["m1","Jan"], ["m2", "Feb"], ["m3","Mar"], ["m4","Apr"],["m5",
"May"], ["m6","Jun"], ["m7","Jul"], 60]], isVisible:true, selectedKeys:["y
2","m1"] , onSelection:onSelectCalBck};
//Reading onSelect of the pickerView.
kony.print("pickerView onSelect event::"+picker.onSelect);
Accessible from IDE

Yes
Available on all platforms except BlackBerry, Desktop Web, Windows Kiosk, SPA, BlackBerry 10, and
on all Server side Mobile Web platforms.
36.4 PickerView - Methods

The PickerView widget has the following methods associated with it:
l
setComponentData
setSelectedKeyInComponent
36.4.1 setComponentData
Provides the ability to set the data for a given component with in the pickerview. To use this method, you must
first have set data using the masterData property. This method allows you to set component data to the
PickerView widget. The data you specify in this method overrides the existing data.
Note: The width is considered to be the same as the width which was originally specified in the masterData.
To change the width, you must use the masterData.
Signature
JavaScript: setComponentData(componentIndex, Array)
Lua:pickerview.setcomponentdata(pickerViewRef, componentIndex, Array)
Input Parameters
componentIndex [Number] - Mandatory
Specifies the component data to be set to the pickerview.
Array [Array of rows] - Mandatory
Specifies the data in array format.
Return Values
None
JavaScript Example
//Defining the properties for a PickerView with id:"picker"
focusSkin:"pickerFSkin", masterData:[[["y1","2009"], ["y2","2010"],["y3","
2011"], 40],[["m1","Jan"], ["m2", "Feb"],["m3","Mar"], ["m4","Apr"], ["m5"
2","m1"] };
//setComponentData method call
picker.setComponentData(2,[["1","2008"] , ["2","2009"] , ["3","2010"], ["4
", "2011"],["5", "2012"]]);
Error Codes
None
36.4.2 setSelectedKeyInComponent
This method allows you to set a particular value in the component data of a PickerView widget as selected.
Signature
JavaScript: setSelectedKeyInComponent(key, componentIndex)
Lua:pickerview.setselectedkeyincomponent(pickerViewRef, key, componentIndex)
Input Parameters
key [String] - Mandatory
Specifies the key of the component.
componentIndex [Number] - Mandatory
Specifies the component data to be set to the pickerview.
Note: The component index starts from 0 to n (n is the number of defined components).
Return Values
None
JavaScript Example
//Defining the properties for a PickerView with id:"picker".
focusSkin:"pickerFSkin", masterData:[[["y1","2009"],["y2","2010"], ["y3","
2011"], 40],[["m1","Jan"], ["m2", "Feb"],["m3","Mar"], ["m4","Apr"], ["m5"
2","m1"] };
//setSelectedKeyInComponent method call

picker.setSelectedKeyInComponent ("m2", 2);
Error Codes
None
37. SegmentedUI
A SegmentedUI consists of multiple segments (rows or records) and each segment (row or record) can have
multiple child widgets.
A SegmentedUI can consist of any of the following widgets:
l
Box
Button
Image
Label
Line
Link
RichText
Phone
Switch
SegmentedUI features specific to Desktop Web Platform

Apart from the above mentioned widgets, Desktop Web platform allows you to add some more widgets. The
below table shows the additional widgets and the properties accessible from code applicable to Desktop Web
platform:
Widget Name
Properties accessible from code
Calendar
dataComponents, dateFormat, skin and visible
TextBox
text, placeholder, i18nKey, skin, and visible
TextArea
text, i18nKey, skin, and visible
CheckBoxGroup
masterData, selectedKeys, skin, and visible
RadioButtonGroup masterData, selectedKeys, skin, and visible

ComboBox
masterData, selectedKeys, skin, and visible
Note: For ComboBox, RadioButton,and CheckBox widgets masterData should be provided only if the
masterDataMap set to the widget initially is different for a particular row.
The data returned when selectedItem is called on the SegmentedUI widget when the row has the following
widgets:
Widget Name
CheckBoxGroup
Properties
selectedKeys, selectedKeyValues
Description
An array of key value pairs with
the keys as mentioned.
RadioButtonGroup selectedKey, selectedKeyValue

ComboBox
selectedKey, selectedKeyValue
TextBox
text
TextArea
text
Calendar
dataComponents
An array of the date

components
Each of the above widgets is allowed to have its own skin and control. This gives the flexibility to design a
segment with separate interconnected widgets and expose their properties for mapping.
When a SegmentedUI template is created based on the input data, the segment is repeated in the Segmented
UI.
The SegmentedUI widget provides you with an option to set Basic Properties, Layout Properties, Platform
Specific Properties, Events, and Methods.
Basic Properties
Layout Properties
alternateRowSkin
data
groupCells
id
info
isVisible
needPageIndicator
orientation
pageOnDotImage
pageOffDotImage
pullToRefreshSkin
pushToRefreshSkin
retainSelection
rowSkin
rowFocusSkin
rowTemplate
screenLevelWidget
sectionHeaderSkin
sectionHeaderTemplate
selectedRowIndex
selectedRowIndices
selectedRowItems
selectionBehavior
selectionBehaviorConfig
separatorColor
separatorRequired
separatorThickness
showScrollbars
viewType
viewConfig
widgetDataMap
widgetSkin
containerHeight
containerWeight
gridCell
layoutMeta
layoutType
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
blockedUISkin
border
bounces
defaultSelection
editStyle
enableDictionary
indicator
pressedSkin
searchBy
searchCriteria
viewConfig
Events
Methods
Deprecated
onDidFinishDataLoading
onEditing
onRowClick
addAll
addDataAt
addSectionsAt
addAt
editable
focusIndex
Events
Methods
Deprecated
onSwipe
scrollingEvents
preOnclickJS
postOnclickJS
removeAll
removeAt
removeSectionsAt
setData
setDataAt
setSectionAt
focusItem
navigationSkin
needSectionHeader
selectedIndex
selectedIndices
ondeleteclick
oninsertclick
onselect
retainHeaderFooter
showItemCount
spaceBetweenSections
viewConfig
Creating a SegmentedUI using a constructor: kony.ui.SegmentedUI2

var seg = new kony.ui.SegmentedUI2 (basicConf, layoutConf, pspConf)
l
they are ignored
JavaScript Example
//Defining properties for a Segment.
var basicConf ={id:"segId", isVisible:true, widgetSkin:"widSkin", rowSkin:
"rowSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin", sectionHeade
rSkin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2",
widgetId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" }, row
Template:box1};
var layoutConf ={padding:[5,5,5,5], margin:[5,5,5,5], containerWeight:100};
var pspConf ={border:constants.SEGUI_BORDER_TOP_ONLY, defaultSelection:tru
e};
//Creating the Segment
var segment = new kony.ui.SegmentedUI2(basicConf, layoutConf, pspConf);
//Reading the alternateRowSkin of the SegmentedUI
alert("SegmentedUI alternateRowSkin ::"+segment.alternateRowSkin);
kony.ui.SegmentedUI.
var seg1= new kony.ui.SegmentedUI (basicConf, layoutConf, pspConf)
When do I use a SegmentedUI Widget?

You can use a segment widget in the following scenarios:
l
To display similar data in the Segmented UI.

For example, if you want to display the Bank Account Number, Account Type, and Balance for a
number of customers, you can use the segment widget to create a template that reflects the required
parameters. Based on the number of records in the input data, the segment (row or record) is populated
and repeated.
The following image illustrates the above example:
To provide a list of records or rows from which a user can make a single or multiple selections.
To display a hierarchy of information. Each row item can lead to different subset of information
displayed in a new list.
To display conceptually grouped information.

The following is the appearance of the Segment on various platforms with a specified Master Data:
Platform
Appearance
Android
Platform
Appearance
BlackBerry
iPhone
Windows Phone
Platform
Appearance
Adding a SegmentedUI Widget from IDE

The steps involved in adding a segment widget are as follows:
1. From the IDE, drag and drop the segment widget onto a form (occupies the complete available width).
2. Use the Orientation property to specify if the widget orientation in the segment must be vertical or
horizontal and drag-and-drop the supported widgets into the segment.
Note: You can use the HBox and VBox to align the widgets in the horizontal and vertical directions
without using the Orientation property.
3. Drag and-drop the supported widgets into the segment and set the data for the segment from the IDE
by using the data property or programmatically by specifying the widgetDataMap property and then set
data using the setData method.
4. Specify the rows of the segment must appear in a table or in pages by using the viewType property.
5. Use the selectionBehavior property to specify if the segment must support single selection or multiple
selection, or none. Based on your selection, define an onRowClick or a scrolling event.
6. Customize the segment appearance by specifying the rowSkin, rowFocusSkin, alternateRowSkin,
and sectionHeaderSkin. You can also specify the separator separatorColor, separatorThickness, and
viewType of the segment.
The following are the important considerations for the segment widget:
Segment occupies memory from two perspectives:

l
Amount of data required from number of rows. For example, if you set data for 100 rows,
memory for all the 100 records will be in memory.
View hierarchy (Box and other supported widgets) in each segment row. If the View hierarchy is
complex, the memory usage is high.
Note: On iPhone, Android, and Windows platforms, if your segment has large data sets (more
than 20 records with each record having more than 15 widgets), set the segment as a Screen
Level Widget.
Note: In KonyOne Studio 4.1 and below, if you add widgets (button, image, label, line, link, or
Rich Text) to the segment from the IDE, the value set for the isVisible property in the IDE for
these widgets is not considered. The default isVisible property value is set to true. If you want
to change the value to false, you can do so by using the segment methods.
Images in segment are not scaled and are rendered with autosize property set to false. If the image
requires lesser space than the allocated space, the image is center aligned.
You cannot add any elements to the widgets dynamically. However, if you want to hide any elements,
do not provide any data for that element.
You can dynamically change the skin of the widgets in the segment by using the Segment Alternate
Methods.
A SegmentedUI cannot be placed directly in a ScrollBox.It can be placed in a ScrollBox with

orientation as Vertical and only then you can place a SegmentedUI on a ScrollBox.
The height of the segmentedUI is determined by the content of the widget. If you set the
screenLevelWidget as true, then the height of the segmentedUI widget is the form height excluding
headers and footers.
Whenever a segmentedUI is set as screenLevelWidget there is a reduction in load time of the

segmentedUI but scrolling speed reduces. This is because the SegmentedUI loads few rows at the
load time and the rest of the rows are loaded as user scrolls through the widget. This is recommended
option when you have huge number of records.
When a segmentedUI is not set as screenLevelWidget, load time of segmentedUI increases because
all the rows are loaded at the beginning, but scrolling speed improves.
Note: Mobile Web also supports dynamic skinning using the Segment Alternate Methods. However, for the
basic version of Mobile Web, if a background image is applied to the widget in the Segment through skin, the
dynamic skinning is not supported.
Note: In general Android SDK does not support the bounce-back feature (rubber band effect). But there are
some OEM's which extended the android SDK to support bounce-back like samsung devices. So to
summarize this is a device specific feature rather than an Android SDK feature.
37.1 SegmentedUI - Basic Properties

The basic properties for Segment Widget are as follows:
l
alternateRowSkin
data
groupCells
id
info
isVisible
needPageIndicator
orientation
pageOnDotImage
pageOffDotImage
pullToRefreshSkin
pushToRefreshSkin
retainSelection
rowSkin
rowFocusSkin
rowTemplate
screenLevelWidget
sectionHeaderSkin
sectionHeaderTemplate
selectedRowIndex
selectedRowIndices
selectedRowItems
selectionBehavior
selectionBehaviorConfig
separatorColor
separatorRequired
separatorThickness
showScrollbars
viewType
viewConfig
widgetDataMap
widgetSkin
37.1.1 alternateRowSkin
Specifies the skin that is applied to every alternate even numbered row in the segment.
For example, if you have 5 segments, the alternate row skin is applied to segments 2 and 4.
Note: If you delete any even segment using the method removeAt, the odd indexes will reset and become
even. The Alternate skin is applied to these new even indexes.
For example, if you have 5 segments and you delete segment 2, the odd indexes reset and segment 3
becomes segment 2 and the alternate skin is applied to it.
Syntax
JavaScript: alternateRowSkin
Lua: alternaterowskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with alternateRowSkin:"altSkin"
var segBasic ={id:"segId",isVisible:true, widgetSkin:"widSkin", rowSkin:"r
owSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin", sectionHeaderS
kin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", w
idgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, rowT
emplate:box1};
var segLayout ={padding:[5,5,5,5], margin:[5,5,5,5], containerWeight:100};
var segPSP ={};
//Creating the Segment.
var segment = new kony.ui.SegmentedUI2(segBasic, segLayout, segPSP);
//Reading the alternateRowSkin of the SegmentedUI.
alert("SegmentedUI alternateRowSkin ::"+segment.alternateRowSkin);
Accessible from IDE

Yes
Available on all platforms except Windows Phone.
37.1.2 data
Specifies the set of values that must be displayed on each row of the segment. The data is categorized into
Sections and Rows.The Sections information is optional. You can set the data in three different formats.
l
Format1: Set the data without any sections.
Format 2: Set the data with sections where section header is a name.
Format 3: Set the data with sections where header is driven by template.
Example of Format 1
//set the data without any sections
[
{dataId1:"foo", dataId2:"foo", dataId3:"foo", accessibilityConfig:acObjec
t},
{dataId1:"bar", dataId2:"bar", dataId3:"bar",template:boxRef2, accessibil
ityConfig:acObject},
{dataId1:"bar", dataId2:"bar", dataId3:{isVisible=true, skin='nskin', foc
usSkin="fskin", text="Foo"} "", accessibilityConfig:acObject}
]
Note: In the above example, template is the standard key which can be optionally to override the common
rowTemplate provided with a specific template for the row. For template always the value has to be valid
box reference, if not it falls back to the common rowTemplate. mentainfo is another standard key which can
be used to specify meta information about the row. iOS specific standard parameters that metainfo can
support are clickable, skin and editmode.
Note: In the above examples, the values of dataId1, dataId2 are shown as string, but dataId3 is key value
pair. The key value pair format allows you to set the properties specific to the widget. In the above example,
we are setting the isVisible property to ture and text property to "Foo", skin property with ID nskin and
focusSkin to a skin with ID fskin. If a string is provided, typically is mapped to the text property for button
and labels and the src property for the image.
Example of Format 2
//set the data with sections where section header is a name. This example
has two sections and each section with two rows.
[
[
"section1",[
{dataId1:"foo", dataId2:"foo", dataId3:"foo", accessibilityCo
nfig:acObject},
{dataId1:"bar", dataId2:"bar", dataId3:"bar", accessibilityCo
nfig:acObject}
], accessibilityConfig:acObject
]
,
[
"section2",[
nfig:acObject},
nfig:acObject}
], accessibilityConfig:acObject
]
]
Example of Format 3
//set the data with sections where section header driven by template. This
example has two sections and each section with two rows.
[
[
{secDataId1:"", secDataId2:"", template=secHeaderBoxRef2, accessibility
Config:acObject},
[
nfig:acObject},
nfig:acObject}
]
]
,
[
{secDataId2:"", secDataId2:"", template=secHeaderBoxRef2, accessibility
Config:acObject},
[
nfig:acObject},
nfig:acObject}
]
]
]
The below table explains the type and description of template and metaInfo keys as well as keys inside the
metaInfo key:
Key
template
Key
Not Applicable
Type
JavaScript:
Object
Comments
Indicates the template to be used for the specific

row
Lua: UserData
JavaScript:
Object
metaInfo (in JS)

metainfo (in Lua)
Allows to capture row level attributes
Lua: Table
clickable
JavaScript:
Boolean
Specifies if the row is clickable and supported by

all platforms.
Lua: Boolean
JavaScript:
Number
Lua: Number
Possible values
constants.SEG
UI_EDIT_
MODE_
INSERT (
editMode (in JS) displays a "+"
icon on the left
editmode (in Lua)
handside of the
row)
constants.SEG
UI_EDIT_
MODE_
DELETE (
displays a "-"
icon on the left
handside of the
row)
skin
JavaScript:
Object
eidtMode is only applicable if the editStyle has

been set to either constants.SEGUI_EDITING_
STYLE_ICON or constants.SEGUI_EDITING_
STYLE_SWIPE
If the editMode property is not specified for a row
then it is not enabled for editing (even though an
editStyle has been set).
constants.SEGUI_EDIT_MODE_INSERT is not
applicable for constants.SEGUI_EDITING_
STYLE_SWIPE
ID of the skin that needs to be applied to the

entire row.
Lua: UserData
Syntax
JavaScript: data
Lua: data
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with data:[{dataId1:"data1", data
Id2:"data2", dataId3:"data3"}, {dataId1:"datax", dataId2:"datay" dataId3:"
dataz", template:box1}]
var segBasic ={id:"segId",isVisible:true,widgetSkin:"widSkin",rowSkin:"row
Skn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin", sectionHeaderSki
n:"secHSkin", data:[{dataId1:"data1", dataId2:"data2", dataId3:"data3", a
ccessibilityConfig:acObject}, {dataId1:"datax", dataId2:"datay" dataId3:"d
ataz", template:box1, accessibilityConfig:acObject}], rowTemplate:box1, se
ctionHeaderTemplate:box2, separatorRequired:true, separatorThickness:20, v
iewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW , screenLevelWidget:false, grou
pCells:true, retainSelection:true, needPageIndicator:true, pageOnDotImage:
"dot.png", pageOffDotImage:"off.png", selectionBehavior:constants.SEGUI_MU
LTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageIndetifier:img, selecte
dStateImage:"sel.png", unselectedStateImage:"unSel.png"}, selectedRowIndex
:4, selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the data of the SegmentedUI.
alert("SegmentedUI data ::"+segment.data);
Accessible from IDE

Yes
37.1.3 groupCells
Specifies if all the rows in the segment should grouped using a rounded corner background and border.
Default: true
Syntax
Lua: groupcells
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with groupCells:true.
var segBasic ={id:"segment",isVisible:true, widgetSkin:"widSkin", rowSkin:
widgetId3:"dataId3" ,widgetId4:"secDataId1", widgetId5:"secDataId2" },rowT
emplate:box1, sectionHeaderTemplate:box2, separatorRequired:true, separato
rThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWid
get:false, groupCells:true, retainSelection:true, needPageIndicator:true,
pageOnDotImage:"dot.png", pageOffDotImage:"off.png", selectionBehavior:con
stants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageIndetifi
er:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel.png"},
selectedRowIndex:4,selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the groupCells of the SegmentedUI.
alert("SegmentedUI groupCells ::"+segment.groupCells);
Accessible from IDE

Yes
Available on all platforms except Windows Phone (Mango), Desktop Web, and Server side Mobile Web
platforms
37.1.4 id
A unique identifier of Segment consisting of alpha numeric characters. Every Segment should have a unique
id within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Segment with id:"segId".
widgetId3:"dataId3", widgetId4:"secDataId1" ,widgetId5:"secDataId2" }, row
Template:box1};
var segPSP ={};

//Reading the id of the SegmentedUI.
alert("SegmentedUI Id ::"+segment.id);
Accessible from IDE

Yes
37.1.5 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for a Segment with info property.
widgetId3:"dataId3", widgetId4:"secDataId1" ,widgetId5:"secDataId2" }, row
Template:box1 };
var segPSP ={};
segment.info = {key:"segmentobjects"};
//Reading the info of the SegmentedUI.
alert("SegmentedUI info ::"+segment.info);
Accessible from IDE

No
37.1.6 isVisible
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Segment with isVisible:true
widgetId3:"dataId3", widgetId4:"secDataId1" ,widgetId5:"secDataId2" },rowT
er:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel.png"}, s
electedRowIndex:4, selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the id of the SegmentedUI.
alert("SegmentedUI Id ::"+segment.id);
Accessible from IDE

37.1.7 needPageIndicator
A Page Indicator is a succession of docs centered below the SegmentedUI widget. Each dot corresponds to a
row segment with the white dot indicating the currently viewed page.
Specifies if the page indicator must be displayed when a segment is dispalayed using pageView. This
property is available only when the viewType is selected as pageView.
Default:true
If set to false, the page indicator is not displayed.
If set to true, the page indicator is displayed.
Syntax
JavaScript: needPageIndicator
Lua: needpageindicator
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Segment with needPageIndicator:true
var segBasic ={id:"segId",isVisible:true,widgetSkin:"widSkin", rowSkin:"ro
wSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin", sectionHeaderSk
in:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", wi
dgetId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" },rowTem
plate:box1, sectionHeaderTemplate:box2, separatorRequired:true, separatorT
hickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWidge
t:false, groupCells:true, retainSelection:true, needPageIndicator:true, pa
geOnDotImage:"dot.png", pageOffDotImage:"off.png", selectionBehavior:const
ants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageIndetifier
:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel.png"}, sel
ectedRowIndex:4,selectedRowIndices:[4,5]};
var segLayout ={padding:[5,5,5,5],margin:[5,5,5,5],containerWeight:100};
var segPSP ={};
//Reading the needPageIndicator of the SegmentedUI.
alert("SegmentedUI needPageIndicator ::"+segment.needPageIndicator);
Accessible from IDE

Yes
37.1.8 orientation
Specifies how you can stack the widgets within the SegmentedUI. You can set the orientation of the
SegmentedUI as horizontal or vertical.
BOX_LAYOUT_HORIZONTAL: Enables you to stack the content within the SegmentedUI

horizontally.
BOX_LAYOUT_VERTICAL: Enables you to stack the content within the SegmentedUI vertically.
Syntax
Lua: orientation
Type
JavaScript: Number
Lua: Number
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Segment with orientation:BOX_LAYOUT_HORIZO
NTAL.
dgetId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" },rowTem
plate:box1, sectionHeaderTemplate:box2, separatorRequired:true, separatorT
hickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWidge
t:false, groupCells:true, retainSelection:true, orientation:constants.BOX_
LAYOUT_HORIZONTAL, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", se
lectionBehavior:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorCo
nfig:{imageIndetifier:img, selectedStateImage:"sel.png", unselectedStateIm
age:"unSel.png"}, selectedRowIndex:4,selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the orientation of the SegmentedUI.
alert("SegmentedUI orientation ::"+segment.orientation);
Accessible from IDE

Yes
37.1.9 pageOnDotImage
Specifies the image to indicate that the page is currently being viewed. This property is available only when
the viewType is selected as pageview. By default a white dot indicates the currently viewed page.
Note: The image size should be of size 7x7 px and 14x14 px for non-retina and retina devices respectively.
Type
Syntax
JavaScript: pageOnDotImage
Lua: pageondotimage
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with pageOnDotImage:"dot.png"
idgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" },rowTe
mplate:box1, sectionHeaderTemplate:box2, separatorRequired:true, separator
Thickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW, screenLevelWidg
et:false, groupCells:true, retainSelection:true, needPageIndicator:true, p
ageOnDotImage:"dot.png", pageOffDotImage:"off.png", selectionBehavior:cons
tants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageIndetifie
r:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel.png"}, se
lectedRowIndex:4,selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the pageOnDotImage of the SegmentedUI.
alert("SegmentedUI pageOnDotImage ::"+segment.pageOnDotImage);
Accessible from IDE

Yes
37.1.10 pageOffDotImage
Specifies the image to indicate that the pages that are not been currently viewed. This property is available
only when the viewType is selected as pageview. By default a black/grey dot indicates the currently viewed
page.
Note: The image size should be of size 7x7 px and 14x14 px for non-retina and retina devices respectively.
Syntax
JavaScript: pageOffDotImage
Lua: pageoffdotimage
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with pageOffDotImage:"off.png"
idgetId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" }, rowT
rThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW, screenLevelWid
var segPSP ={};
//Reading the pageOffDotImage of the SegmentedUI.

alert("SegmentedUI pageOffDotImage ::"+segment.pageOffDotImage);
Accessible from IDE

Yes
Specifies the i18N key for "pull to refresh" title. The platforms get the value from the existing application locale
specific i18N resource bundle. If the key is not found in the resource bundle, then platforms use the default
(english locale) title text.
Note: This property is supported when the viewType is set as SEGUI_VIEW_TYPE_TABLEVIEW and the
property screenLevelWidget is set to true.
Syntax
JavaScript: pullToRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the skin to be applied to the pull to refresh title. This property does not support image as
background.
font_weight
font_style
font_size
font_color
font_name
background_color
bg_type
background_style
Syntax
JavaScript: pullToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the i18N key for "push to refresh" title. The platforms get the value from the existing application
locale specific i18N resource bundle. If the key is not found in the resource bundle, then platforms use the
default (english locale) title text.
Syntax
JavaScript: pushToRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the skin to be applied to the push to refresh title. This property does not support image as
background.
l
font_weight
font_style
font_size
font_color
font_name
background_color
bg_type
background_style
Syntax
JavaScript: pushToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the i18N key for "release to refresh" title that appears for pull to refresh. The platforms get the value
from the existing application locale specific i18N resource bundle. If the key is not found in the resource
Syntax
JavaScript: releaseToPullRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
Specifies the i18N key for "release to refresh" title that appears for push for refresh. The platforms get the
value from the existing application locale specific i18N resource bundle. If the key is not found in the resource
Note: This property is supported when the viewType is set as SEGUI_VIEW_TYPE_TABLEVIEW and
screenLevelWidget is set to true.
Syntax
JavaScript: releaseToPushRefreshI18NKey
Type
JavaScript: String
Read / Write
Accessible from IDE

Yes
37.1.17 retainSelection
Specifies if the segment should retain the selection made even when the user navigates out of the form and
revisits the form.
Note: By default retainSelection is true in Server sideMobile Web, hence this property is not supported.
Default: false
If set to true, the selection is retained when the user navigates to different form.
If set to false, the selection is not retailed.
Type
Syntax
JavaScript: retainSelection
Lua: retainselection
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Segment with retainSelection:true.
var segBasic ={id:"segId", isVisible:true, widgetSkin:"widSkin", rowSkin:"
rowSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin", sectionHeader
Skin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2",
widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, row
Template:box1, sectionHeaderTemplate:box2, separatorRequired:true,
separatorThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screen

LevelWidget:false, groupCells:true, retainSelection:true, needPageIndicato
r:true, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", selectionBeha
vior:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{image
Indetifier:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel.
png"}, selectedRowIndex:4, selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the retainSelection of the SegmentedUI.
alert("SegmentedUI retainSelection ::"+segment.retainSelection);
Accessible from IDE

Yes
l
iPad
iPhone
Windows Phone
Windows Kiosk
37.1.18 rowSkin
Specifies the skin that must be applied for each row.
Syntax
JavaScript: rowSkin
Lua: rowskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with rowSkin:"rowSkn"
Template:box1};
var segPSP ={};
//Reading the rowSkin of the SegmentedUI.
alert("SegmentedUI rowSkin ::"+segment.rowSkin);
Accessible from IDE

Yes
Specifies the skin that must be applied when user selects the row.
Syntax
JavaScript: rowFocusSkin
Lua: rowfocusskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with rowFocusSkin:"rowFSkn".
var segBasic ={id:"segId", isVisible:true, widgetSkin:"widSkin",
rowSkin:"rowSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin", sect

ionHeaderSkin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"d
ataId2", widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId
2" }, rowTemplate:box1};
var segPSP ={};
//Reading the rowFocusSkin of the SegmentedUI.
alert("SegmentedUI rowFocusSkin ::"+segment.rowFocusSkin);
Accessible from IDE

Yes
37.1.20 rowTemplate
Indicates the common template to be used for each row while creating the row and filling the data. This can be
overridden at the row level when setting the data using the template key.
Syntax
JavaScript: rowTemplate
Lua: rowtemplate
Type
JavaScript: kony.ui.Box- [Mandatory]
Lua: UserData- [Mandatory]
Read / Write
Note: On BlackBerry 10 platform, you cannot change rowTemplate dynamically. For example, the below
code does not work.
frm1.segment1.rowTemplate = template1
JavaScript Example
//Defining the properties for a Segment with rowTemplate:box1, where box1
is a box that should be created and made accessible.
Thickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWidg
var segPSP ={};
//Reading the rowTemplate of the SegmentedUI.
alert("SegmentedUI rowTemplate ::"+segment.rowTemplate);
Accessible from IDE

Yes
Specifies weather the widget should occupy the whole container or not. You must set the value to true if your
segment has large data sets (more than 20 records with each record having more than 15 widgets) to facilitate
a better reuse of the widgets and a different scrolling behavior.
Note: You cannot place more than one segment as a screen level widget inside a form. Also, if you choose
to make a segment a screen level widget, we recommend that you place only one segment in the form and
do not place any other widgets in the form.
Note: In iOS platform, screenLevelWidget property can be set to true when SegmentedUI is placed in
ScrollBox and Popup.
Default: false
If set to true, the widget occupies the whole container and there is a reduction in load time of the SegmentedUI
as only few rows are loaded at the load time. The rest of the rows are loaded as the user scrolls through the
widget. But the scrolling speed reduces.
If set to false, the widget does not occupy the whole container and load time of SegmentedUI increases
because all the rows are loaded at the beginning. But the scrolling speed improves.
On iPhone, Android, and Windows platforms, if this property is set to true, the following are applicable:
iPad and iPhone

l
The widgets placed above and below the segment (which is a screen level widget) are
You can use the retainHeaderFooter property to specify if the header and footer scroll
with the form or scroll with the segment.
Android
l
Only the widgets placed above the segment (which is a screen level widget) are visible. The
widgets placed below the segment are not visible when rendered.
You can use the Position property (segheader and segfooter) of the Box to specify if the header
and footer scroll with the form or scroll with the segment.
Note: If you leave the Position property options unchanged as normal; when rendered, only
the Boxes placed above the segment are visible. The Boxes placed below the segment are
not visible.
If you change the Position property to header or footer, the Boxes are added as form header or
footer and are "fixed" and do not scroll along with the segment.
Windows
l
The widgets placed above and below the segment (which is a screen level widget) are
Note: If you configure Application level Header and Footer, they will be visible even if the browser
is a screen level widget.
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with screenLevelWidget:false.
widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" },rowT
electedRowIndex:4,selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the screenLevelWidget of the SegmentedUI
alert("SegmentedUI screenLevelWidget ::"+segment.screenLevelWidget);
Accessible from IDE

Yes
l
iPad
iPhone
Windows Phone
Windows Kiosk
37.1.22 sectionHeaderSkin
Specifies the skin to be applied to the Section Header.
Syntax
JavaScript: sectionHeaderSkin
Lua: sectionheaderskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with sectionHeaderSkin:"secHSkin".
rThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW, screenLevelWid
var segPSP ={};
//Reading the sectionHeaderSkin of the SegmentedUI.
alert("SegmentedUI sectionHeaderSkin ::"+segment.sectionHeaderSkin);
Accessible from IDE

Yes
37.1.23 sectionHeaderTemplate
Specifies the common template to be used for each section while creating the section header and filling the
data. This is optional parameter and if not provided the default template provided by each platform will be
used. It can also be provided at each section level when setting the data. Please refer data property for
examples.
Note: When a Section Header is provided along with the rows/items, the Section Header is "clamped" to the
top of the scrollable area (on the Form) as one scrolls through a long list of items (for example, if you have a
long list of contacts that all begin with the letter "A", the "A" header will be fixed at the top until you scroll
down past the last "A" item). This behavior can be clearly seen iPhone's Contacts application.
This behavior of Section Headers is available on iOS and Android platform and is enabled when the
screenLevelWidget has been set to true.
Syntax
JavaScript: sectionHeaderTemplate
Lua: sectionheadertemplate
Type
Lua: UserData
Read / Write
Note: On BlackBerry 10 platform, you cannot change sectionHeaderTemplate dynamically. For example,
the below code does not work.
frm1.segment1.sectionHeaderTemplate = template1
JavaScript Example
//Defining the properties for a Segment with sectionHeaderTemplate:box2, w
here box1 is a box that should be created and made accessible.
Template:box1, sectionHeaderTemplate:box2, separatorRequired:true, separat
orThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWi
dget:false, groupCells:true, retainSelection:true, needPageIndicator:true,
var segPSP ={};
//Reading the sectionHeaderTemplate of the SegmentedUI
alert("SegmentedUI sectionHeaderTemplate ::"+segment.sectionHeaderTemplat
e);
Accessible from IDE

Yes
37.1.24 selectedRowIndex
Indicates the currently selected row in single select or multi select modes in the SegmentedUI. The index is
with respect to the order in which data is set with data property. Programmatically setting the selectedRow
Index will not make any visible differences in the row, however it will bring the row at the index into the view
able area on the screen. Setting it to null/nil clears the selection state and also sets the selectedRowIndices
to null in case segui selection behavior is SEGUI_SINGLE_SELECT or SEGUI_DEFAULT_BEHAVIOR or
SEGUI_MULTI_SELECT_BEHAVIOR. The selectedRowIndex is not updated when clicked on any child
widget of a Row. For example, a Button or an HBox.
selectedRowIndex Array format:
[sectionIndex1, [rowIndex1],
For example,
[1,3] indicates 4th row in 2nd section.
Note: selectedRowIndex is not updated when a row is swiped in PAGE_VIEW or COVERFLOW_VIEW. It

is updated only when clicked on a row.
Syntax
JavaScript: selectedRowIndex
Lua: selectedrowindex
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with selectedRowIndex:4.
rThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW
,screenLevelWidget:false, groupCells:true, retainSelection:true, needPageI

ndicator:true, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", select
ionBehavior:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:
{imageIndetifier:img, selectedStateImage:"sel.png", unselectedStateImage:"
unSel.png"}, selectedRowIndex:4, selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the selectedRowIndex of the SegmentedUI.
alert("SegmentedUI selectedRowIndex ::"+segment.selectedRowIndex);
Accessible from IDE

No
37.1.25 selectedRowIndices
Specifies an array of indexes which indicates the selected rows. In case of MULTI_SELECT there can be
more than one selected index and the array represents the same. In case of SINGLE_SELECT and
DEFAULT_BEHAVIOR the array contains only one element indicating the selectedIndex. Setting it to null/nil
clears the selection state and also sets the selectedIndices to null/nil. The selectedRowIndices is not updated
when clicked on any child widget of a Row. For example, a Button or an HBox.
When this property is read from the SegmentedUI the list structure depends on the usage of sections.
selectedRowIndices Array format:
[
[sectionIndex1, [rowIndex1, rowIndex2, ...],
.....
]
For example:
l
[[0, [2] ] ] indicates 3rd row is selected in the first selection.
[[0, [1, 4] ] ] indicates 2nd and 5th rows are selected in the first section.
[[0, [0, 3] ], [2, [1, 3, 4] ] ] indicates the 1st, 4th rows, of 1st section and also 2nd , 4th and 5th rows in
3rd section.
Note: selectedRowIndices is not updated when a row is swiped in PAGE_VIEW or COVERFLOW_VIEW.

It is updated only when clicked on a row.
Syntax
JavaScript: selectedRowIndices
Lua: selectedrowindices
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with selectedIndicies:[4,5].
emplate:box1, sectionHeaderTemplate:box2, separatorRequired:true,separator
var segPSP ={};
//Reading the selectedIndicies of the SegmentedUI.
alert("SegmentedUI selectedIndicies ::"+segment.selectedIndicies);
Behavior when data is modified in the segment

l
If you set new data in the segment using the setData method, the earlier selected indices
are cleared.
If you add additional data to the segment using the addAll method, the earlier selected
indices are retained.
Accessible from IDE

No
37.1.26 selectedRowItems
Returns the data in the selected row of the segmentedUI.
Note: Use the property name as selectedItem for backward compatibility.
Syntax
JavaScript: selectedRowItems
Lua: selectedrowitems
Type
JavaScript: Array of objects
Lua: Table
Read / Write
Yes - (Read only)
Accessible from IDE

No
37.1.27 selectionBehavior
Specifies if the segment can support single or multiple selection.
Default: SEGUI_DEFAULT_BEHAVIOR
l
SEGUI_DEFAULT_BEHAVIOR: Indicates that the segment does not support either single or multiple
selection. This option allows you to define an onRowClick event for the segment.
SEGUI_SINGLE_SELECT_BEHAVIOR: Indicates that you can make one selection when you have
many choices in the segment (the behavior is similar to a RadioButtonGroup).
SEGUI_MULTI_SELECT_BEHAVIOR: Indicates that you can make more than one selection when
you have many choices in the segment (the behavior is similar to a CheckBoxGroup).
Syntax
JavaScript: selectionBehavior
Lua: selectionbehavior
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with selectionBehavior:constants.S
EGUI_MULTI_SELECT_BEHAVIOR.
var segPSP ={};
//Reading the selectionBehavior of the SegmentedUI.
alert("SegmentedUI selectionBehavior ::"+segment.selectionBehavior);
Accessible from IDE

Yes
37.1.28 selectionBehaviorConfig
This property is enabled if you select either singleselect or multiselect. It specifies the Image widget ID which
is used to indicate to the user that the row is selected or deselected. Following are the key value
configurations:
imageIdentifier - Identifier of the Image widget that is placed in template box and this will be used to indicate
the selection state by toggling selectedStateImage and unselectedStateImage.
Note: Only after you specify the imageIdentifier, the selectStateImage and unselectedStateImage
properties will be available.
selectedStateImage
Specifies the image to be displayed when the user selects the row.
unselectedStateImage
Specifies the image to be displayed when the user deselects the row.
Note: The image size should be equal for both selectedStateImage and unselectedStateImage otherwise
the UI gets distorted.
Syntax
JavaScript: selectionBehaviorConfig
Lua: selectionbehaviorconfig
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with selectionBehaviorConfig:{imag
eIndetifier:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel
.png"}.
idgetId3:"dataId3", widgetId4:"secDataId1" ,widgetId5:"secDataId2" },rowTe
et:false, groupCells:true, retainSelection:true, needPageIndicator:true,

stants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageIdentifi
var segPSP ={};
//Reading the selectionBehaviorConfig of the SegmentedUI.
alert("SegmentedUI selectionBehaviorConfig ::"+segment.selectionBehaviorCo
nfig);
Accessible from IDE

No
37.1.29 separatorColor
Specifies the color of the separator between row of segmentedUI. The color property follows hex format
(#RRGGBBAA) which includes even transparency portion. For example, if the seperator color is green and
transparency is 50% then value is 00ff0032. Similarly if the transparency is 100% then the value is 00ff0064.
Syntax
JavaScript: separatorColor
Lua: separatorcolor
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with separatorColor:"#FF0000".
rowSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",
sectionHeaderSkin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId

2:"dataId2", widgetId3:"dataId3", widgetId4:"secDataId1" ,widgetId5:"secDa
taId2" }, rowTemplate:box1, sectionHeaderTemplate:box2, separatorRequired:
true,separatorThickness:20, separatorColor:"#FF0000", viewType:constants.S
EGUI_VIEW_TYPE_PAGEVIEW , screenLevelWidget:false, groupCells:true,retainS
election:true, needPageIndicator:true,pageOnDotImage:"dot.png", pageOffDot
Image:"off.png", selectionBehavior:constants.SEGUI_MULTI_SELECT_BEHAVIOR,
selectionBehaviorConfig:{imageIndetifier:img, selectedStateImage:"sel.png",
unselectedStateImage:"unSel.png"}, selectedRowIndex:4,selectedRowIndices:[
4,5]};
var segPSP ={};
//Reading the seperatorColor of the SegmentedUI.
alert("SegmentedUI seperatorColor ::"+segment.seperatorColor);
Accessible from IDE

Yes
37.1.30 separatorRequired
Specifies if the segment should display the separator between the rows of the SegmentedUI.
Default: false
If set to true, the separator is displayed.
If set to false, the separator is not displayed.
Syntax
JavaScript: separatorRequired
Lua: separatorrequired
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with separatorRequired:true
Template:box1, sectionHeaderTemplate:box2, separatorRequired:true, separat
orThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWi
var segPSP ={};
Accessible from IDE

Yes
37.1.31 separatorThickness
Specifies the thickness of the separator in pixels.
Note: For iOS platform, this property is applicable only when you set the groupCells property as true.
Note: From iOS7 onwards this property is not applicable even when you set the groupCells property as true.
Default: 1px
Syntax
JavaScript: separatorThickness
Lua: separatorthickness
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with separatorThickness:3.
rThickness:3, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWidg
var segPSP ={};
//Reading the separatorThickness of the SegmentedUI.
alert("SegmentedUI separatorThickness ::"+segment.separatorThickness);
Accessible from IDE

Yes
Available on all platforms except iPhone and iPad.
Specifies if the scrollbars must be visible all the time.
Default: As per native platform behavior.
Syntax
Lua: showscrollbars
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with showScrollbars:true.
emplate:box1, sectionHeaderTemplate:box2, separatorRequired:true, showScro
llbars:true, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWidge
t:false, groupCells:true, retainSelection:true, needPageIndicator:true, pa
geOnDotImage:"dot.png", pageOffDotImage:"off.png", selectionBehavior:const
ectedRowIndex:4,selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the showScrollbars of the SegmentedUI.
alert("SegmentedUI showScrollbars ::"+segment.showScrollbars);
Accessible from IDE

Yes
Available on all platforms except Desktop Web and Server side Mobile Web platforms
37.1.33 viewType
You can use this property to select the view type of a segment. The following are the available view types that
you can select and their appearances on iPhone native client:
Default: SEGUI_VIEW_TYPE_TABLEVIEW
Note: Only the view type SEGUI_VIEW_TYPE_TABLEVIEW supports sections. All other views do not
support sections but display rows of all sections continuously one below the other without any indication of
sections.However, all section related APIs, sectionIndex, rowIndex work with all views of the segui without
any code level changes when switching from one view to the other view.
Note: On Windows Phone, setting the pageview dynamically is not supported.
l
SEGUI_VIEW_TYPE_TABLEVIEW: The rows of the segment appear in a table as a

list.
SEGUI_VIEW_TYPE_PAGEVIEW: The rows of the segment appear in pages and you

need to scroll through the pages to view the rows.
Note: To avoid UI issues with segment, ensure that each page of segment with pageview has
equal size and also the height of segment should fit into the screen viewport area.
The below option applicable to iPhone, iPad and Android/Android Tablet platforms.
l
SEGUI_VIEW_TYPE_COVERFLOW: Regular cover flow view. The cover flow view

enables you to flip through the widgets placed in a segment and bring the associated
widget into view. You can flip through the widgets placed in a segment as shown in the
figure.
Following are the options applicable to iPhone and iPad only.

l
SEGUI_VIEW_TYPE_CYLINDER: Displays the widgets placed in a segment as a

cylinder. All the widgets placed in a segment form a horizontal cylinder (polygon) and the
cylinder rotates based on the user's gesture. In the Cylinder view, the widgets appear as
if the user is viewing at the cylinder from outside. The widgets gets skewed as you move
along the axis of reference of the cylinder. You can rotate the widgets placed in a
segment around the axis of reference as shown in the figure.
SEGUI_VIEW_TYPE_INVERTED_CYLINDER: Displays the widgets placed in a

segment as a cylinder. All the widgets of the segment form a horizontal cylinder
(polygon) and the cylinder rotates based on user's gesture. In the Inverted Cylinder view,
the widgets placed in a segment appear as if the user is viewing the cylinder from inside.
The widgets in a segment gets skewed as you move the segment along the axis of
reference. You can rotate the widgets placed in a segment around the axis of reference
as shown in the figure.
SEGUI_VIEW_TYPE_INVERTED_ROTARY: Displays the widgets placed in a

segment that rotates around the axis of reference, where the current objects are
projected inwards and the other widget appear closer to the user than the current widget.
There won't be any widgets skewing or tilting like in the cover flow view.
SEGUI_VIEW_TYPE_LINEAR: Displays the widgets placed in a segment in a linear

view; which is very similar to the existing views, where you can scroll the widgets
horizontally. You can scroll across the widgets by moving them forward or backward as
shown in the figure.
SEGUI_VIEW_TYPE_ROTARY: Displays the widgets placed in a segment that rotates

around the axis of reference, where the current widget protrudes outwards and other
widget appear slightly behind the current widget. There won't be any widget skewing or
tilting like in the cover flow view.
SEGUI_VIEW_TYPE_STACK: Custom stack view where the widgets placed in a

segment appear as a stack. The widgets can be moved inside and outside the stack
based on the user's gesture as shown in the figure below.
Syntax
Lua: viewtype
Type
JavaScript: Number
Lua: Number
Read / Write
Note: On Android platform, this property cannot be changed dynamically.
JavaScript Example
//Defining the properties for a Segment with viewType:constants.SEGUI_VIEW
_TYPE_PAGEVIEW.
lectedRowIndex:4, selectedRowIndices:[4,5]};
var segPSP ={};

//Reading the viewType of the SegmentedUI.
alert("SegmentedUI viewType ::"+segment.viewType);
Accessible from IDE

Yes
37.1.34 viewConfig
This property is applicable only when viewType is set as SEGUI_VIEW_TYPE_COVERFLOW. The cover
flow view enables you to flip through the widgets placed in a segment and bring the associated widget into
view. You can flip through the widgets placed in a segment as shown in the figure.
To configure coverflow view for andoird platform, follow these steps:

1. Drag-drop a segment on to the form, from the widget properties window navigate to viewType.
2. Click the Ellipsis ( ) button against the property, select Android and then select SEGUI_VIEW_
TYPE_COVERFLOW from the drop down box. Click OK.
) button against the viewConfig property. The viewConfig window appears.
4. Enter projectionAngle, rowItemRotationAngle, spaceBetweenRowItems, rowItemWidth, and

isCircular as required. Click OK.
l
projectionAngle [Number]:Specifies the angle in degrees between a row except at

center and at z-axis. When the projection angle is 0, all the rows are aligned along z-axis
one behind the other. When previewed, it only shows one row at center. When projection
angle is 90, all the rows are aligned along x-axis side by side. If the value entered is
negative then the resultant angle is 90 + entered value. For example, if projection angle is
-30 then resultant projection angle is 90 - 30 = 60 degrees. It accepts a range between 90 and +90 only.
l
rowItemRotationAngle[Number]: Specifies the angle in degrees of rotation of each row

along its own y-axis. It accepts a range between 0 and 360.
spaceBetweenRowItems [Number]: Specifies the space between each row. It accepts

the value in pixels.
rowItemWidth[Number]: Specifies the width in percentage relative to its parent width. It

accepts a range between 1 and 100.
isCircular[Boolean]: When set to true, it specifies the widget to scroll endlessly

(repeating the first row after you reach the last row) and when set to false, it stops
scrolling after you reach the last row.
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a Segment with viewConfig.
kin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2: "dataId2",
Template:box1, viewConfig:{coverflowConfig:{projectionAngle:60, rowItemRot
ationAngle: 45, spaceBetweenRowItems: 25, rowItemWidth:50, isCurcular:tru
e}}};
var segPSP ={};
Accessible from IDE

Yes
Available on Android/Android Tablet platform only
Note: It is developer responsibility to ensure that Widget datamap to accommodate all the widget ids
{
widgetID1:
widgetId2:
widgetId3:
widgetId4:
widgetId5:
"dataId1",
"dataId2",
"dtaId3",
"secDataId1"
"secDataId2"
}
Note: Only after you specify the mapping information, you can use the Methods applicable for a segment.
Syntax
JavaScript: widgetDataMap
Lua: widgetdatamap
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with widgetDataMap:{widgetId1:"dat
aid1", widgetId2:"dataId2", widgetId3:"dataId3", widgetId4:"secDataId1", w
idgetId5:"secDataId2" }.
widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2}, rowTe
tants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:

unSel.png"}, selectedRowIndex:4, selectedRowIndices:[4,5]};
var segPSP ={};
//Reading the widgetDataMap of the SegmentedUI.
alert("SegmentedUI widgetDataMap ::"+segment.widgetDataMap);
Below is an example showing a segment and assigning properties for widgets placed on it.
//Defining properties for a Segment with write properties of the widgets p
laced on it.
var segBasic ={id:"segment1", isVisible:true, widgetSkin:"widSkin",
widgetDataMap: {
"label1": "label1",
"image1": "image1",
"button1": "button1"
},
data: [{
"label1": "Label1",
"image1": "img14.png",
"button1": "button1"
}]
};
var segPSP ={};
//On an onClick event of a button, the properties for label1, image1 and
button1 are set.
function form1_button_onClick_(eventobject) {
form1.segment1.data = [{
"button1": {
"text": "CButton1",
"containerWeight": 50
},
"label1": {
"text": "CButton2",
"containerWeight": 30,
"isVisible":false
},
"image1": {
"src": "img4.png",
"isVisible": true,
"containerWeight":50
}
}]
};
Accessible from IDE

No
37.1.36 widgetSkin
Specifies the skin to be applied to the entire SegmentedUI.
Note: In Server side Mobile Web, widgetSkin property with Border style as rounded corner is supported only
when you set the border property as SEGUI_BORDER_NONE.
Syntax
JavaScript: widgetSkin
Lua: widgetskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with widgetSkin:"widSkin".
Template:box1};
var segPSP ={};
//Reading the widgetSkin of the SegmentedUI.

alert("SegmentedUI widgetSkin ::"+segment.widgetSkin);
Accessible from IDE

Yes
37.2 SegmentedUI - Layout Properties

The layout properties for Segment Widget are as follows:
l
containerHeight
containerWeight
gridCell
layoutMeta
layouType
layoutAlignment
margin
marginInPixel
padding
paddingInPixel
Specifies the height of the SegmentedUI in terms of percentage. The percentage is with reference to the value
of containerHeightReference property. This property is enabled when the viewType is set as SEGUI_VIEW_
TYPE_TABLEVIEW or SEGUI_VIEW_TYPE_PAGEVIEW.
Note: In Windows platforms, when screenLevelWidget property is set to false, the SegmentedUI widget
occupies the form screen height. When screenLevelWidget property is set to true and viewType property is
set to TABLEVIEW, the SegmentedUI widget occupies the form height.
Note: When screenLevelWidget property is set to true and viewType property is set to PAGEVIEW, the
SegmentedUI widget occupies the content height.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with containerHeight:40.
Template:box1};
var segLayout ={padding:[5,5,5,5], margin:[5,5,5,5], containerWeight:100,
containerHeight: 40, containerHeightReference:constants.CONTAINER_HEIGHT_B
Y_FORM_REFERENCE};
var segPSP ={};
Accessible form IDE

Yes
Available on all platforms except Server side Mobile Web platform
This property is enabled when the viewType is set as SEGUI_VIEW_TYPE_TABLEVIEW or SEGUI_VIEW_
TYPE_PAGEVIEW and the containerHeight is set. The segmentedUI height percentage is calculated based
on the option selected.
l
CONTAINER_HEIGHT_BY_FORM_REFERENCE: The SegmentedUI height is calculated based on

the height of the form excluding headers and footers. This option is not respected if SegmentedUI is
placed inside a popup or in templates.
CONTAINER_HEIGHT_BY_PARENT_WIDTH: This option is used if the SegmentedUI is placed

inside a popup or in templates. The width is calculated based on the width of the parent container.
Syntax
Type
JavaScript: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with containerHeightReference:SEGU
I_HEIGHT_BY_FORM_REFERENCE.
Template:box1};
containerHeight: 40, containerHeightReference:constants.CONTAINER_HEIGHT_B
Y_FORM_REFERENCE};
var segPSP ={};
Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web platform
child widgets based on this weight factor. All its child widgets should sum up to 100% of weight.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with containerWeight:100.
Template:box1};
var segPSP ={};
//Reading the containerWeight of the SegmentedUI.
alert("SegmentedUI containerWeight ::"+segment.containerWeight);
Accessible from IDE

No
37.2.4 gridCell
applied.
are as follows:
l
GridLayout.
Syntax
Lua: gridCell
Type
Lua:table
Read / Write
JavaScript Example
//Defining the properties for a Segment with layoutType:CONTAINER_LAYOUT_G
RID.
Template:box1};
layoutType: constants.CONTAINER_LAYOUT_GRID,
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}, gridcell:{"colSpan":1, "rowSpan":1, "rowNo":1, "colNo":1}};
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
37.2.5 layoutMeta

Syntax
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with layoutMeta.
Template:box1};
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
37.2.6 layoutType
Defines the type of the layout of widget. Following are the available options:
l
platforms.
Apply GridLayout.
Syntax
Lua: layouttype
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for a Segment with layoutType:CONTAINER_LAYOUT_G
RID.
Template:box1};
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Desktop Web
Specifies the direction in which the widgets are laid out.
l
BOX_LAYOUT_ALIGN_FROM_LEFT: The widgets placed inside a SegmentedUI are aligned left.
BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets placed inside a SegmentedUI are aligned

center.
BOX_LAYOUT_ALIGN_FROM_RIGHT: The widgets placed inside a SegmentedUI are aligned right.
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with layoutAlignment:BOX_LAYOUT_AL
IGN_FROM_LEFT.
Template:box1};
var segLayout ={padding:[5,5,5,5], margin:[5,5,5,5], layoutAlignment:const
ants.BOX_LAYOUT_ALIGN_FROM_LEFT, containerWeight:100};
var segPSP ={};

Accessible from IDE

Yes
Available on all platforms except Server side Mobile Web, BlackBerry 10, and Windows Kiosk platforms.
37.2.8 margin
Syntax
Lua: widgetskin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Segment with margin:[5,5,5,5].
widgetId3:"dataId3", widgetId4:"secDataId1" , widgetId5:"secDataId2" },row
Template:box1},selectedIndex:4, selectedIndicies:[4,5]};
var segPSP ={};
Accessible from IDE

Yes
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
var segLayout ={padding:[5,5,5,5], margin:[5,5,5,5], marginInPixel:true, c
var segPSP ={};
Accessible from IDE

Yes
l
iPhone
iPad
Windows Kiosk
37.2.10 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Segment with padding:[5,5,5,5].
rowSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",sectionHeaderS
mplate:box1}, selectedIndex:4, selectedIndicies:[4,5]};
var segPSP ={};
Accessible from IDE

Yes
Available on all platforms except iOS, Server side Mobile Web (basic), and BlackBerry 10 platforms
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Segment with padding in pixels.
var segLayout ={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel: true,
var segPSP ={};
Accessible from IDE

Yes
l
Windows Kiosk
37.3 SegmentedUI - Platform Specific Properties

The platform specific properties for Segment Widget are as follows:
l
blockedUISkin
border
bounces
contextMenu
defaultSelection
dockSectionHeaders
editStyle
enableDictionary
indicator
pressedSkin
searchBy
searchCriteria
viewConfig
call) is completed.
Note: For the skin to be available in the list, you must add a skin for blockedUISkin under Widget Skins.
Syntax
Lua: blockeduiskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with blockedUISkin:"blockUiSkn".
emplate:box1, sectionHeaderTemplate:box2, seperatorRequired:true, separato
rThickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLevelWi
electedIndex:4, selectedIndices:[4,5]};
var segPSP ={blockedUISkin:"blockUiSkn"};
//Reading the blockedUISkin of the SegmentedUI
alert("SegmentedUI blockedUISkin ::"+segment.blockedUISkin);
Accessible from IDE

Yes
l
Desktop Web
37.3.2 border
Specifies the border to the SegmentedUI.
Default: SEGUI_BORDER_BOTH_BOTTOM_TOP
l
SEGUI_BORDER_NONE: The border is not displayed on the segment.
SEGUI_BORDER_TOP_ONLY: The border is displayed on top of the segment.
SEGUI_BORDER_BOTTOM_ONLY: The border is displayed at the bottom of the segment.
SEGUI_BORDER_BOTH_BOTTOM_TOP: The border is displayed on top and bottom of the segment.
Syntax
JavaScript: border
Lua: border
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with border:constants.SEGUI_BORDER_
TOP_ONLY.
n:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", wid
getId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, rowTem
plate:box1, sectionHeaderTemplate:box2, seperatorRequired:true, separatorT
hickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLevelWidg
ageOnDotImage:"dot.png",pageOffDotImage:"off.png", selectionBehavior:const
ectedIndex:4, selectedIndices:[4,5]};
var segPSP ={border:constants.SEGUI_BORDER_TOP_ONLY};
//Reading the border of the SegmentedUI
alert("SegmentedUI border ::"+segment.border);
Accessible from IDE

Yes
l
SPA
37.3.3 bounces
Default:true
Syntax
JavaScript: bounces
Lua: bounces
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with bounces:true.
var segBasic ={id:"segId", isVisible:true, widgetSkin:"widSkin",rowSkin:"r
mplate:box1,sectionHeaderTemplate:box2, seperatorRequired:true, separatorT
hickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW, screenLevelWidg
tants.SEGUI_MULTI_SELECT_BEHAVIOUR, selectionBehaviorConfig:{imageIndetifi
var segPSP ={bounces:true};
Accessible from IDE

Yes
l
iPhone
iPad
37.3.4 contextMenu
A context menu is a menu that appears upon clicking a widget. A context menu typically offers a limited set of
choices that are applicable for that widget. Usually these choices are actions, related to the widget.
If you define a context menu for a widget, the steps involved to invoke the context menu on a platform and the
l
BlackBerry 6.x
BlackBerry Touch
Device (<6.x)
Device (<6.x)

l
Type
Array(kony.ui.MenuItem)
Syntax
Lua: contextmenu
Type
JavaScript: Array (kony.ui.MenuItem)
Lua: Table
Read / Write
JavaScript Example
//Defining contextMenu for Windows8 platform.
allbackMenuItem1 };
callbackMenuItem3};
callbackMenuItem4};
{
}
{
}
{
}
{
}
//Defining the properties for a Segment with contextMenu

dgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, rowTe
mplate:box1, sectionHeaderTemplate:box2, seperatorRequired:true, separator
Thickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLevelWid
var segPSP = {contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]};
Accessible from IDE

No
l
BlackBerry
Windows Phone
Windows Tablet
37.3.5 defaultSelection
Specifies if the first clickable element (Image or Label) of the segment is selected by default.
Default:true
If set to false, the default selection is not applied.
If set to true, the default selection is applied.
Syntax
JavaScript: defaultSelection
Lua: defaultselection
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Segment with defaultSelection:true.
var segPSP ={defaultSelection:true};
//Reading the defaultSelection of the SegmentedUI.
alert("SegmentedUI defaultSelection ::"+segment.defaultSelection);
Accessible from IDE

Yes
l
37.3.6 dockSectionHeaders
The docking header property enables you to dock or place the section header at the top of the segment while
scrolling the section content. If you are scrolling the segment data, the next section header will be docked on
top of the segment.
Note: This property is applicable only when the segment is a screenLevelWidget and viewType is SEGUI_
VIEW_TYPE_TABLE_VIEW and has sections data.
For example, If you scroll the segment data shown in the figure below, as the segment data scrolls up, the
Samsung Phones docked header moves out of view and is replaced with the HTC Phones section header
which is now docked.
Default:false
If set to false, the section header is not docked.
If set to true, the section header is docked.
Syntax
JavaScript: dockSectionHeaders
Lua: docksectionheaders
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Segment with dockSectionHeaders:true.
var segPSP ={dockSectionHeaders:true};
//Reading the defaultSelection of the SegmentedUI.
alert("SegmentedUI dockSectionHeaders::"+segment.dockSectionHeaders);
Accessible from IDE

Yes
Available on Android/Android Tablet platforms only.
37.3.7 editStyle
Specifies the editing style to be applied to the rows in the SegmentedUI.
Default: SEGUI_EDITING_STYLE_NONE
SEGUI_EDITING_STYLE_ICON: An icon will be displayed on the left hand side of each row.
SEGUI_EDITING_STYLE_SWIPE: A delete or insert button will be shown on the right hand side of
each row when the user performs a SWIPE gesture on the row. Whether an insert button or delete
button is to be shown is controlled by the editmode property that is set using the data property of the
SegmentedUI.
SEGUI_EDITING_STYLE_NONE: No special edit styles are applied.
For information regarding the Meta Info that can be set for the rows, see Methods associated with the
segment.
If you want to enable Swipe to delete feature for a row in the SegmentedUI then set the editing style to
constants.SEGUI.EDITING_STYLE_SWIPE (a delete confirmation appears when you swipe a row).
Syntax
JavaScript: editStyle
Lua: editstyle
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with editStyle:constants.SEGUI_EDI
TING_STYLE_SWIPE.
idgetId3:"dataId3" ,widgetId4:"secDataId1" , widgetId5:"secDataId2" },rowT
emplate:box1,sectionHeaderTemplate:box2, seperatorRequired:true, separator
var segPSP ={editStyle:constants.SEGUI_EDITING_STYLE_SWIPE};
//Reading the editStyle of the SegmentedUI

alert("SegmentedUI editStyle ::"+segment.editStyle);
The following image illustrates the Icon edit style:
Accessible from IDE

No
l
iPhone
iPad
37.3.8 enableDictionary
Specifies if dictionary must be enabled for easy navigation.
If the dictionary property is enabled, alphabets from A to Z appear on the screen and when you select any
alphabet, all the corresponding results that start with the selected alphabet are displayed.
Note: This property is applicable if screenLevelWidget property is set to true and the section headers have
been set.
Default: false
If set to true, the dictionary is available.
If set to false, the dictionary is not available.
The following image illustrates the behavior of the Enable Dictionary property when set to true:
Syntax
JavaScript: enableDictionary
Lua: enabledictionary
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with enableDictionary:true.
idgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" },
rowTemplate:box1, sectionHeaderTemplate:box2, seperatorRequired:true, sepa

ratorThickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLev
elWidget:false, groupCells:true, retainSelection:true, needPageIndicator:t
rue, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", selectionBehavio
r:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageInd
etifier:img, selectedStateImage:"sel.png", unselectedStateImage:"unSel.pn
g"}, selectedIndex:4, selectedIndices:[4,5]};
var segPSP ={enableDictionary:true};
Accessible from IDE

Yes
l
iPhone
iPad
37.3.9 indicator
Specifies the indicator type as rowSelect, rowClick, or none. Based on your selection, the behavior is
exhibited:
Default: SEGUI_ROW_SELECT
l
SEGUI_ROW_SELECT: Specifies the disclosure indicator. The indicator appears as follows:
If the user selects the indicator, the related content appears in the next screen .
l
SEGUI_ROW_CLICK: Specifies the disclosure button. The button appears as follows:
If the user selects the disclosure button, the detailed content appears.
l
SEGUI_NONE: No indicator or button is displayed.
Syntax
JavaScript: indicator
Lua: indicator
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with indicator:constants.SEGUI_ROW_
CLICK.
Skn",rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",sectionHeaderSkin:
"secHSkin",widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", widget
Id3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" },rowTemplat
e:box1, sectionHeaderTemplate:box2, seperatorRequired:true, separatorThick
ness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLevelWidget:f
alse, groupCells:true, retainSelection:true, needPageIndicator:true, pageO
nDotImage:"dot.png", pageOffDotImage:"off.png", selectionBehavior:constant
s.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{imageIndetifier:im
g, selectedStateImage:"sel.png", unselectedStateImage:"unSel.png"}, select
edIndex:4, selectedIndices:[4,5]};
var segPSP ={indicator:constants.SEGUI_ROW_CLICK};
Accessible from IDE

Yes
l
iPhone
iPad
37.3.10 pressedSkin
Specifies the skin to indicate that the row of the segment is pressed or clicked.
Note: If you do not specify the pressedSkin, the rowFocusSkin is applied.
Syntax
JavaScript: pressedSkin
Lua: pressedskin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with pressedSkin:"pressedSkn".
var segPSP ={pressedSkin:"pressedSkn"};
Accessible from IDE

Yes
This property is available on Android/Android Tablet only.
Specifies the color of the progress indicator as white or grey.
Default: PROGRESS_INDICATOR_COLOR_WHITE
PROGRESS_INDICATOR_COLOR_WHITE: The progress indicator is white in color
PROGRESS_INDICATOR_COLOR_GREY: The progress indicator is grey in color
Syntax
JavaScript: progressIndicatorColor
Lua: progressindicatorcolor
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with progressIndicatorColor:consta
nts.PROGRESS_INDICATOR_COLOR_GREY.
mplate:box1, sectionHeaderTemplate:box2, seperatorRequired:true,separatorT
hickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLevelWidg
lectedIndex:4, selectedIndices:[4,5]};
var segPSP ={progressIndicatorColor:constants.PROGRESS_INDICATOR_COLOR_
GREY};
var segId = new kony.ui.SegmentedUI2(segBasic, segLayout, segPSP);
Accessible from IDE

Yes
l
iPhone
iPad
37.3.12 searchBy
Indicates the identifier of the widget placed inside the row of the SegmentedUI. Search will be performed
against the content present inside the widget.
Note: This property is applicable only when screenLevelWidget of SegmentedUI is set to true.
Syntax
JavaScript: searchBy
Lua: searchby
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for a Segment with searchBy:"widgetId1", where "
widgetId1" is a reference of a label.
get:true, groupCells:true, retainSelection:true, needPageIndicator:true, p
lectedIndex:4, selectedIndices:[4,5]};
var segPSP ={searchBy:"widgetId1"};
var segID= new kony.ui.SegmentedUI2(segBasic, segLayout, segPSP);
Accessible from IDE

Yes
l
iPhone
iPad
37.3.13 searchCriteria
Specifies the search criteria to be applied when searching has been enabled on the SegmentedUI.
Note: This property is applicable only when screenLevelWidget of SegmentedUI is set to true and searchBy
property has been set.
Default: SEGUI_SEARCH_CRITERIA_STARTSWITH
l
SEGUI_SEARCH_CRITERIA_STARTSWITH: The search is performed on the strings that start with

the input string.
SEGUI_SEARCH_CRITERIA_ENDSWITH: The search is performed on the strings that end with the
input string.
SEGUI_SEARCH_CRITERIA_CONTAINS: The search is performed on the strings that contain the

input string.
The following image illustrates the search with startsWith criteria:
Syntax
JavaScript: searchCriteria
Lua: searchcriteria
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a Segment with searchCriteria:constants.SEGU
I_SEARCH_CRITERIA_ENDSWITH
owSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",
sectionHeaderSkin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId

2:"dataId2", widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDa
taId2" },rowTemplate:box1, sectionHeaderTemplate:box2, seperatorRequired:t
rue, separatorThickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW,
screenLevelWidget:false, groupCells:true, retainSelection:true, needPageIn
dicator:true, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", selecti
onBehavior:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:
unSel.png"}, selectedIndex:4, selectedIndices:[4,5]};
var segPSP ={searchCriteria:constants.SEGUI_SEARCH_CRITERIA_ENDSWITH};
//Reading the searchCriteria of the SegmentedUI
alert("SegmentedUI searchCriteria ::"+segment.searchCriteria);
Accessible from IDE

Yes
l
iPhone
iPad
Specifies if the progress indicator must be displayed.
Default: true (the progress indicator is displayed on the widget)
If you do not want the progress indicator to be displayed, set the value to none.
Syntax
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a Segment with showProgressIndicator:true.
Skin:"secHSkin",widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", w
emplate:box1, sectionHeaderTemplate:box2, seperatorRequired:true, separato
rThickness:20, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW ,screenLevelWi
electedIndex:4,selectedIndices:[4,5]};
var segPSP ={showProgressIndicator:true};
Accessible from IDE

Yes
l
iPhone
iPad
37.3.15 viewConfig
Configurable properties of viewConfig property are Reference Width and Reference Height. If reference height
and width are greater than 0, then view set is grid view.
Default application displays 0, you can give any number greater than 0 to get grid view type of a widget.
If you set righttap event using setGestureRecognizer to a box then you can see right click behavior on each
cell of grid view.
Syntax
Lua: viewconfig
Type
JavaScript:Object
Lua: table
Read / Write
No
Accessible from IDE

Yes
37.4 SegmentedUI - Events

Segment has the following events associated with it:
l
onDidFinishDataLoading
onEditing
onRowClick
onSwipe
scrollingEvents
preOnclickJS
postOnclickJS
37.4.1 onDidFinishDataLoading
This event is triggered when you load data in the segmentedUI using the setData method. This event is
supported only when you set the segment view type as table view.
Signature
JavaScript: onDidFinishDataLoading
Read / Write
JavaScript Example
//The below function is the call back function for onEditing event
function onDidFinishDataLoadingCallBck(seguiWidget)
{
}
//Defining the properties for a Segment.
emplate:box1}, selectedIndex:4, selectedIndicies:[4,5],
viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};

var segPSP ={onDidFinishDataLoadingCallBck:onDidFinishDataLoadingCallBckCa
llBck};
//Reading the onDidFinishDataLoadingCallBck of the SegmentedUI
alert("SegmentedUI onDidFinishDataLoading::"+segment.onDidFinishDataLoadin
gCallBck);
This event is available on iPhone and iPad only.
37.4.2 onEditing
This event is triggered when a user indicates his desire to edit the row (delete or insert). This event is only
triggered if the eidtStyle is set to SEGUI_EDITING_STYLE_ICON or SEGUI_EDITING_STYLE_SWIPE.
Signature
JavaScript: onEditing (seguiWidget, editmode, sectionIndex, rowIndex)
Lua: onediting (seguiWidget, editmode, sectionIndex, rowIndex)
Input Parameters
seguiWidget [String]- Mandatory
Reference to the SegmentedUI widget that raised the event.
editmode - Mandatory
Specifies the editing mode either insert or delete. Following are the available options:
l
SEGUI_EDIT_MODE_INSERT
SEGUI_EDIT_MODE_DELETE
sectionIndex [Number]- Mandatory
Specifies the index of the section to which the row belongs to.
rowIndex [Number]- Mandatory
Specifies the index of the row that has been clicked.
JavaScript Example
//The below function is the call back function for onEditing event
function onEditingCallBck(seguiWidget, editmode, sectionIndex, rowIndex)
{
}
emplate:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constants
.SEGUI_VIEW _TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
var segPSP ={onEditing:onEditingCallBck};
//Reading the onEditing of the SegmentedUI
alert("SegmentedUI onEditing ::"+segment.onEditing);
This event is available on iPhone and iPad only.
37.4.3 onRowClick
This event is triggered when the user click any row of the SegmentedUI. This event is not raised if the
clickable property in the metainfo is set to false.
Signature
JavaScript: onRowClick (seguiWidget, sectionIndex, rowIndex, isSelected)
Lua: onrowclick (seguiWidget, sectionIndex, rowIndex, isSelected)
Input Parameters
Specifies the index of the section to which the row belongs to.
Specifies the index of row that has been clicked.
isSelected [Boolean]- Mandatory

Specifies the selected state.
Read / Write
Note: selectedState is applicable only when the selectionBehavior is set to SEGUI_SINGLE_SELECT_
BEHAVIOR or SEGUI_MULTI_SELECT_BEHAVIOR.
JavaScript Example
/The below function is the callback function for onRowClick event.
function onRowClickCallBck(seguiWidget, sectionNumber, rowNumber, selected
State)
{
}
//Defining the properties for a Segment with onRowClick:onRowClickCallBck
emplate:box1}, selectedIndex:4, selectedIndicies:[4,5], onRowClick:onRowCl
ickCallBck, viewType:constants.SEGUI_VIEW _TYPE_PAGEVIEW};
var segPSP ={};
//Reading the onRowClick event of the SegmentedUI
alert("SegmentedUI onRowClick event ::"+segment.onRowClick event);
37.4.4 onSwipe
This event is triggered when you swipe a row in a segment. This event is available only when the viewType is
set to page view.
Signature
JavaScript: onSwipe (seguiWidget, sectionIndex, rowIndex, selectionState)
Lua: onswipe (seguiWidget, sectionIndex, rowIndex, selectionstate)
Input Parameters
Specifies the index of the section where the current focused row belongs to. -1 in case if there are
no sections.
Specifies the index of the current focused row of the section.
selectionstate [Boolean]- Optional
Specifies the selected state of the current focused rows checked or unchecked. It is available
when selectionBehavior is set as SEGUI_SINGLE_SELECT_BEHAVIOR or SEGUI_MULTI_
SELECT_BEHAVIOR mode. It is applicable to the following viewTypes:
l
SEGUI_VIEW_TYPE_PAGEVIEW
SEGUI_VIEW_TYPE_COVERFLOW (iOS and Android)
SEGUI_VIEW_TYPE_STACK (iOS)
SEGUI_VIEW_TYPE_LINEAR (iOS)
SEGUI_VIEW_TYPE_ROTATORY (iOS)
SEGUI_VIEW_TYPE_INVERTED_ROTARY (iOS)
SEGUI_VIEW_TYPE_CYLINDER (iOS)
SEGUI_VIEW_TYPE_INVERTED_CYLINDER (iOS)
Read / Write
JavaScript Example
//The below function is the callback function for onSwipe event.
function onSwipeCallBck(segUI)
{
}
//Defining the properties for a Segment with onSwipe:onSwipeCallBck
emplate:box1}, selectedIndex:4,selectedIndicies:[4,5], viewType:constants.
SEGUI_VIEW_TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};

var segPSP ={};
//Reading the onSwipe of the SegmentedUI
alert("SegmentedUI onSwipe ::"+segment.onSwipe);
Available on all platforms except BlackBerry, BlackBerry 10, and Server side Mobile Web (Basic, BJS,
and Advanced) platforms.
An event callback that is invoked by the platform when scrolling the SegmentedUI widget.
Following are the requirements and limitations to use this event on iOS and Android/Android Tablet platforms:
l
This event is invoked only when it is placed directly inside a ScrollBox or in a Form
Segment viewType must be set as SEGUI_VIEW_TYPE_TABLEVIE
The property screenLevelWidget must be set to true.
Note: If segment is inside any other container widget like HBox/VBox then onPull, onPush,
onReachingBegining and onReachingEnd events, cross platform behavior is undefined and these events
might not be called.
Note: On Android platform, if the rows height/number of rows is less than the screen display height, then
onReaching and onPush event callbacks won't get invoked.
onReachingBegining : Gets called when scrolling reaches the beginning of the

SegmentedUI widget.
Signature
JavaScript: onReachingBegining(seguiWidget)
Lua: onreachingbegining(seguiWidget)
onReachingEnd: Gets called when scrolling reaches the end of the SegmentedUI widget.
Signature
JavaScript: onReachingEnd(seguiWidget)
Lua: onreachingend(seguiWidget)
onPull: Gets called when SegmentedUI is pulled from top.

Signature
JavaScript: onPull(seguiWidget)
Lua: onpull(seguiWidget)
onPush: Gets called when SegmentedUI is pushed from bottom.

Signature
JavaScript: onPush(seguiWidget)
Lua: onpush(seguiWidget)
Input Parameters
seguiWidget [widgetref]- Mandatory
Type
Lua: Table
Read / Write
JavaScript Example
//The below function is the call back function for onReachingBegining(scro
llingEvents) event.
function onReachingBeginingCallBCk(seguiWidget)
{
}
//Defining the properties for a Segment
mplate:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constants.
SEGUI_VIEW_TYPE_PAGEVIEW, scrollingEvents:{onReachingBegining:onReachingBe
giningCallBCk}};
var segPSP ={};

//Reading the scrollingEvents of the SegmentedUI.
alert("SegmentedUI scrollingEvents ::"+segment.scrollingEvents);
Accessible from IDE

Yes
37.4.6 preOnclickJS
Syntax
Lua: preonclickjs
Read / Write
JavaScript Example
//The below function is the call back function for preOnclickJS event call.
function preOnclickJSCalBck(seguiWidget)
{
}
//Defining the properties for a Segment with preOnclickJS:preOnclickJSCalB
ck.
SEGUI_VIEW_TYPE_PAGEVIEW};
var segPSP ={preOnclickJS:preOnclickJSCalBck};

//Reading the preOnclickJS of the SegmentedUI.
alert("SegmentedUI preOnclickJS ::"+segment.preOnclickJS);
Accessible from IDE

Yes
Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
//The below function is the call back function for postOnclickJS event cal
l.
function postOnclickJSCalBck(seguiWidget)
{
}
//Defining the properties for a Segment with postOnclickJS:postOnclickJSCa
lBck.
SEGUI_VIEW_TYPE_PAGEVIEW};
var segPSP ={postOnclickJS:postOnclickJSCalBck};

//Reading the postOnclickJS of the SegmentedUI.
alert("SegmentedUI postOnclickJS ::"+segment.postOnclickJS);
Accessible from IDE

Yes
37.5 SegmentedUI - Methods

This section describes the methods associated with the Segment widget. You can use these methods across
all platforms.
Note: The methods described in this section can be used only after you specify the mapping information
between the widget IDs and the keys in the data using the widgetDataMap property.
The methods that you can use on all platforms are as follows:
l
addAll
addDataAt
addSectionAt
removeAll
removeAt
removeSectionAt
setData
setDataAt
setSectionAt
37.5.1 addAll
This method allows you to add new data to the segment. The new data is appended to the existing data. If the
segment has no data, the new data is placed in the segment.
Note: Using this method, you can not add the rows to the existing sections.
Signature
Lua:segui.addall(seguiid, data)
Input Parameters
explained in data property of segment basic properties.
seguiid [widgetref] - Mandatory
Return Values
None
JavaScript Example
Skn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",sectionHeaderSkin
:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId2:"dataId2", widg
etId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, rowTemp
late:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constants.SE
GUI_VIEW_TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
segment.addAll([{dataId1:"data1", dataId2:"data2", dataId3:"data3"}, {dat
aId1:"datax", dataId2:"datay" dataId3:"dataz", template:box1}]);
Error Codes
None
37.5.2 addDataAt
Allows you to add one row of data at a given index or with in a section. The new data is placed before the
index. The existing data is pushed to the next row.
Signature
JavaScript: addDataAt(data, rowIndex, sectionIndex)
Lua: segui.adddataat(seguiid, data, rowIndex, sectionIndex)
Input Parameters
Row data can also have the standard template key to indicate a new template for this added row.
However it is developer responsibility to ensure widgetdatamap covers the widgets present in the
new template.

Specifies the Index of the row within the section if the sectionIndex is mentioned. If the
sectionIndex is not mentioned, the rowIndex is treated in absolute terms independent of sections.
Note: Sections should not be counted as rows when calculating the rowIndex.
Index is '0' based in JavaScript and should be less than "n", where "n" is the number of existing
rows within the section if sectionIndex is mentioned. If the sectionIndex is not mentioned "n" is the
total number of rows in a segment.
Index is '1' based in Lua and should be less than "n", where "n" is the number of existing rows
within the section if sectionIndex is mentioned. If the sectionIndex is not mentioned "n" is the total
number of rows in a segment.
If the rowIndex mentioned is greater than "n", then row is added at the end of the segment or at the
end of the section depending on the sectionIndex.
Specifies the Index of the section. If the index is not mentioned, the rowIndex will be treated in
absolute terms.
Return Values
None
JavaScript Example
etId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" },rowTempl
ate:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constants.SEG
UI_VIEW_TYPE_PAGEVIEW,onSwipe:onSwipeCallBck};
//Defining a row.
dataObj1 = {globaDdataId1:"label1", globaDataId2:"label2", globalDataId3:"
label3"};
//addAt method call ,adding the above row at 15th index position.
segment.addDataAt(dataObj1,15);
Error Codes
None
37.5.3 addSectionAt
This method allows you to add one or more sections with rows to the segment.
Signature
JavaScript: addSectionAt(data, sectionIndex)
Lua: segui.addsectionat(seguiid, data, sectionindex)
Input Parameters
Note: Sections and its rows can have the standard template key to indicate a new template
for this added row. However it is developer responsibility to ensure widgetdatamap covers the
widgets present in the new template.
Specifies the Index of the section.
sections within the segment. If the index is greater than or equal to "n", then section is added at the
end of the segment.
Index is '1' based in Lua and should be less than "n", where "n" is the number of existing sections
within the segment. If the index is greater than or equal to "n", then section is added at the end of
the segment.
Return Values
None
JavaScript Example
getId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" },rowTemp
GUI_VIEW_TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
//Defining section data.
data =[["section1", [{dataId1:"aaa"},{dataId1:"bbb"} ]],["section2", [
{dataId1:"ccc"}, {dataId1:"ddd"} ] ]];
//addSectionAt method call.
segment.addSectionAt(data,2);
Error Codes
None
37.5.4 removeAll
This method is used to remove all the existing rows and sections in a segment.
Signature
Lua: segui.removeall(seguiid)
Input Parameters
Return Values
None
JavaScript Example
etId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" },rowTempl
ate:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constants.SEG
UI_VIEW_TYPE_PAGEVIEW,onSwipe:onSwipeCallBck};
segment.removeAll();
Error Codes
None
37.5.5 removeAt
This method is used to remove the row at the given index or a row with in a section.
Signature
JavaScript: removeAt(rowIndex, sectionIndex)
Lua: segui.removeat(seguiid, rowIndex, sectionIndex)
Input Parameters
Specifies the Index of the row within the section if the sectionIndex is mentioned. It the
sectionIndex is not mentioed, the rowIndex is treated in absolute terms independent of sections.
If the rowIndex mentioned is not within the limits then no action takes place.
absolute terms.
Return Values
None
JavaScript Example
etId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" }, rowTemp
GUI_VIEW_TYPE_PAGEVIEW,onSwipe:onSwipeCallBck};
//removeAt method call,removing the row at 15th index position.
segment.removeAt(15);
Error Codes
None
37.5.6 removeSectionAt
This method allows you to remove a section at the given index within a segment.
Signature
JavaScript: removeSectionAt(sectionIndex)
Lua: segui.removesectionat(seguiid, sectionIndex)
Input Parameters
sections within the segment. The operation is ignored if the sectionIndex is not mentioned.
Index is '1' based in Lua and should be less than "n", where "n" is the number of existing sections
within the segment. The operation is ignored if the sectionIndex is not mentioned.
Return Values
None
JavaScript Example
getId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, rowTem
plate:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constants.S
EGUI_VIEW _TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
//removeSectionAt method call.
segment.removeSectionAt(2);
Error Codes
None
37.5.7 setData
This method allows you to set new data to the segment. When you set new data, the existing data will be
replaced with the new data. If the segment has no data, the new data is placed in the segment.
Signature
JavaScript: setData(data)
Lua: segui.setdata(seguiid, data)
Input Parameters
seguiid [widgetref]- Mandatory
Return Values
None
JavaScript Example
widgetId3:"dataId3" ,widgetId4:"secDataId1" ,widgetId5:"secDataId2" }, row
Template:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constant
s.SEGUI_VIEW_TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
segment.setData([{dataId1:"data1", dataId2:"data2", dataId3:"data3"}, {da
taId1:"datax", dataId2:"datay" dataId3:"dataz", template:box1}]);
Error Codes
None
37.5.8 setDataAt
Allows you to set data or modify an existing data of a row or within a section. The existing data of the row will
be replaced with the new set. In case the index is not valid and not falling in range 0 <= index <= N, where N is
the total number of records then the operation is ignored.
Signature
JavaScript: setDataAt(data, rowIndex, sectionIndex)
Lua: segui.setdataat(seguiid, data, rowIndex, sectionIndex)
Input Parameters
explained in data property of segment basic properties. Rowdata can have the standard template
key to indicate a new template for this row. However it is developer responsibility to ensure
widgetDataMap covers the widgets present in the new template.
Specifies the Index of the row within the section if the sectionIndex is mentioned. If the
sectionIndex is not mentioed, the rowIndex is treated in absolute terms independent of sections.
If the rowIndex mentioned is not within the limits then no action takes place.
sectionIndex []Number] - Optional
absolute terms.
Return Values
None
JavaScript Example
etId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" }, rowTemp
late:box1},selectedIndex:4, selectedIndicies:[4,5], viewType:constants.SEG
UI_VIEW_TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
//Defining a row.
dataObj1 = {globaDdataId1:"label3", globaDataId2:"label4", globalDataId3:"
label5"};
//setDataAt method call,modifying the data at 15th index position with the
above row.
segment.setDataAt(dataObj1,15);
Error Codes
None
37.5.9 setSectionAt
This method allows you to set or modify a section with rows to the segment. When you set new data, the
existing data will be replaced with the new data. If the segment has no data, the new data is placed in the
segment.
Signature
JavaScript: setSectionAt(data, sectionIndex)
Lua:segui.setsectionat(seguiid, data, sectionIndex)
Input Parameters
Specifies an array that represents the section data as key value pairs. The format of the array of
data is as explained in data property of segment basic properties. Sections and its rows can have
standard template key to indicate a new template for this added row. However it is developer
responsibility to ensure widgetdatamap covers the widgets represent in the new template.
Index is '0' based in JavaScript and should be less than "N", where "N" is the number of existing
sections within the segmentedUI widget. If not. setSectionAt will be silent and does not yield any
results.
Return Values
None
JavaScript Example
idgetId3:"dataId3", widgetId4:"secDataId1" , widgetId5:"secDataId2" }, row
Template:box1}, selectedIndex:4, selectedIndicies:[4,5], viewType:constant
s.SEGUI_VIEW_TYPE_PAGEVIEW, onSwipe:onSwipeCallBck};
//Defining section data.
data =[["section1", [{dataId1:"aaa"},{dataId1:"bbb"} ] ], ["section2",
[{dataId1:"ccc"}, {dataId1:"ddd"} ] ]];
//setSectionAt method call,modifying the data at 2nd sectionIndex position.
segment.setSectionAt(data,2);
Error Codes
None
37.6 Segment - Deprecated Properties

The deprecated properties for segment widget are as follows:
l
addAt
editable
focusedIndex
focusedItem
navigationSkin
needSectionHeader
selectedIndex
selectedIndices
ondeleteclick
oninsertclick
onselect
retainHeaderFooter
showItemCount
spaceBetweenSections
viewConfig
37.6.1 addAt
Allows you to add a row of data at a given index. The new data is placed before the index. The existing data is
pushed to the next row.
Signature
segui.addat(seguiid, data map, index)
Input Parameters
seguiid - Mandatory
Handle to the widget instance
data map - Mandatory
Lua Table
index - Mandatory
Number
Possible values: 1 <= index <= n; Where n is the number of rows. Note: Index does not include the
Section Headers.
Return Values
Example
To add a new Checking Account 594 with a balance of $200.34 in row 3, enter the following:
segui.addat(frmAccnOvw.segBankAccounts,{BAccName = "Checking 594", BAccBal
ance = "$200.34", AccOvwBAarrow = "arrow.png"}, 3)
Alternate Method
segui.setdataat(frmAccnOvw.segBankAccounts,
{{BAccName={text="Checking 594",skin=sk1},BAccBalance={text="$200.34",skin
=sk1}, url={text="http://imagelocation.com",skin=sk1},metainfo={clickable=
true, skin=newskin},3
})
Error Codes
No error codes
37.6.2 editable
Specifies if the segment is editable (rows can be added or deleted).
Default: false (the checkbox is not selected and you cannot add or delete the rows in the segment)
If you want to be able to add or delete rows in the segment, set the value to true (select the checkbox).
Note: This property is applicable only on iPhone platform and can be set only from the code.
Type
Boolean
Read / Write
Yes (Write only)
Example: If you want to set a segment seg1 which is in Form frm1 as editable, enter the following:
frm1.seg1.editable = "true"
Accessible from IDE

No
Available on iPhone platform only.
37.6.3 focusedIndex
Returns the selected row index of the selected segment in the Segmented UI.
Type
Number
Read / Write
Accessible from IDE

Yes
37.6.4 focusedItem
Returns the data object of the corresponding segment (row or record) in the Segmented UI.
Type
Number
Read / Write
Accessible from IDE

Yes
37.6.5 navigationSkin
Specifies the skin for the navigation bar.
Type
Object
Read / Write
No
Accessible from IDE

Yes
37.6.6 needSectionHeader
Specifies if the column headers must be displayed.
Default: false (the checkbox is not selected and the column headers are not displayed)
To display the column headers, set the value to true (select the checkbox) and configure the Section Headers
(i.e add the section header names) from the Master Data property.
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
Indicates the currently selected row in the SegmentedUI. The index is with respect to the order in which data
is set with data property. Programmatically setting the selected Index will not make any visible differences in
the row, however it will bring the row at the index into the view able area on the screen. Setting it to null/nil
clears the selection state and also sets the selectedIndices to null in case segui selection behavior is
SINGLE_SELECT or DEFAULT_BEHAVIOR.
selectedIndex Array format:
[sectionIndex1, [rowIndex1],
For example,
section.
Syntax
Lua: selectedindex
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with selectedIndex:4.
var segPSP ={};
//Reading the selectedIndex of the SegmentedUI.
alert("SegmentedUI selectedIndex ::"+segment.selectedIndex);
Accessible from IDE

No
Specifies an array of indexes which indicates the selected rows. In case of MULTI_SELECT there can be
more than one selected index and the array represents the same. In case of SINGLE_SELECT and
DEFAULT_BEHAVIOR the array contains only one element indicating the selectedIndex. Setting it to null/nil
clears the selection state and also sets the selectedIndices to null/nil.
When this property is read from the SegmentedUI the list structure will depend upon the usage of sections.
selectedIndices Array format:
[
.....
]
For example:
l
[[0, [2] ] ] indicates 3rd row is selected in the first selection.
[[0, [1, 4] ] ] indicates 2nd and 5th rows are selected in the first section.
[[0, [0, 3] ], [2, [1, 3, 4] ] ] indicates the 1st, 4th rows, of 1st section and also 2nd , 4th and 5th rows in
3rd section.
Syntax
JavaScript: selectedIndices
Lua: selectedindices
Type
JavaScript: Array
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with selectedIndicies:[4,5].
emplate:box1, sectionHeaderTemplate:box2, separatorRequired:true,separator
Thickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW
,screenLevelWidget:false, groupCells:true, retainSelection:true, needPageI

ndicator:true, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", select
ionBehavior:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:
unSel.png"}, selectedIndex:4,selectedIndices:[4,5]};
var segPSP ={};
//Reading the selectedIndicies of the SegmentedUI.
alert("SegmentedUI selectedIndicies ::"+segment.selectedIndicies);
Behavior when data is modified in the segment

If you set new data in the segment using the setData method, the earlier selected indices are
cleared.
If you add additional data to the segment using the addAll method, the earlier selected indices
are retained.
Accessible from IDE

No
37.6.9 ondeleteclick
This event is applicable only when the edit style property of the Segment is set to icon.
You must use this property to specify the event to be executed when the add accessory button on the
Segment is clicked.
Signature
ondeleteclick()
37.6.10 oninsertclick
This event is applicable only when the edit style property of the Segment is set to icon.
You must use this property to specify the event to be executed when the remove accessory button on the
Segment is clicked.
Signature
oninsertclick()
37.6.11 onselect
This event is available only when the Behavior property is set to either singleselect or multiselect and is
triggered when a row in a Segment is selected.
Signature
onselect(seguiid, rowindex, rowstate)
Input Parameters
seguiid - Mandatory
Reference of the Segment whose row is selected
rowindex [Number]- Mandatory
Row index of the Segment that is clicked
rowstate [Boolean]- Mandatory
Specifies if the row is selected (true) or unselected (false)
This event uses the above input parameters and allows you to identify the segment, row that is clicked, and
the row state (selected or unselected).
37.6.12 retainHeaderFooter
Specifies if the Header and Footer (defined in the HBox Position property) must be attached to the segment
or to the Form.
Note: This property is applicable only if the Screen Level Widget property of the segment is set to true.
If the Screen Level Widget property for the segment is set to true and if the Header and Footer is defined, the
default behavior of the segment is to occupy a major portion of the screen; and the Header and Footer to scroll
along with the contents of the segment.
If RetainHeaderFooter property is set to false, the Header and Footer do not scroll along with the contents of
the segment and are fixed to the form.
Default: true (the checkbox is selected and the Header and Footer scroll along with the contents of the
segment )
If you do not want the Header and Footer to scroll along with the contents of the segment, set the value to
false (clear the checkbox).
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
Available on iPhone/iPad platform.
Specifies if the meta structure must be displayed.
The meta structure has the following format:
start_rec_num, end_rec_num, total_recs
For example, {1,10,100} indicates that the current record start is 1, the set ends at 10, and that there are 100
records.
Default: true (the checkbox is selected and the meta structure is displayed)
If you do not want to display the meta structure, set the value to false (clear the checkbox).
Type
Boolean
Read / Write
No
Accessible from IDE

Yes
Available on all platforms except Palm and Symbian platforms.
37.6.14 spaceBetweenSections
Specifies the space between the sections in pixels.
Default: 0 (There is no space in between the sections)
To define the space between the sections, enter a number.
Note: On Mobile Web platform, this property is available only when the Need Section Headers property is
set to true.
Type
Number
Read / Write
No
Accessible from IDE

Yes
Available on Windows Phone and on all Mobile Web platforms.
37.6.15 viewConfig
Note: The two options coverflowAngle and coverflowDepth are deprecated. The option coverflowAngle is
mapped to rowItemRotationAngle.
This property is applicable only when viewType is set as SEGUI_VIEW_TYPE_COVERFLOW. The cover
flow view enables you to flip through the widgets placed in a segment and bring the associated widget into
view.
To configure coverflow view for andoird platform, follow these steps:
1. Drag-drop a segment on to the form, from the widget properties window navigate to viewType.
2. Click the Ellipsis ( ) button against the property, select Android and then select SEGUI_VIEW_
TYPE_COVERFLOW from the drop down box. Click OK.
) button against the viewConfig property. The viewConfig window appears.
4. Enter coverflowAngle, coverflowDepth and rowItemWidth as required. Click OK.

l
coverflowAngle: Specifies the angle at which the non focused images as rendered. It
accepts the angle in number.
coverflowDepth: Specifies the depth at which the non focused images as rendered. It
accepts the pixel value in number.
rowItemWidth: Specifies the width relative to its parent width. It accepts the value in
number
Syntax
Type
Read / Write
JavaScript Example
//Defining the properties for a Segment with viewConfig.
Template:box1, viewConfig:{coverflowConfig:{coverflowAngle:30, rowItemWidt
h: 20, coverflowDepth: 50}}};
var segPSP ={};
Accessible from IDE

Yes
Available on Android/Android Tablet platform only
37.7 SegmentedUI - Templates

37.7.1 What is a Template for SegmentedUI
SegmentedUI template enables you to define a template for section headers. Only one template can be used
for each segment. This is primarily useful for developers to achieve common look and feel of section headers
along with few widgets added as part of section header of a segment.
37.7.2 Where to use a SegmentedUI (section) Template

SegmentedUI sections are used to differentiate or group a set of rows.
The section templates are used:
l
to have uniform look and feel of the section headers.
to achieve the behavior of having widgets such as an Image and a label for all the section headers of
the segment.
to perform an action on the event of an onclick of an item or a widget in the section header.
37.7.3 Creating a Template for SegmentedUI

When you want the same information to be displayed across all the Section Headers of a Segment in the
application, you have a provision to add a Segment Template using Kony Studio. For more information about
section headers refer Kony Studio User Guide.
To create a segment template at the application-level, follow these steps:
2. Expand the application for which you want to create the SegmentTemplate.
3. Navigate to templates > segments, right-click mobile/desktop/tablet and select New Segment
Template. The Create a New Segment window appears.
iii. Drag and drop an HBox or a Scrollable Box onto the form.
Note: Only HBox and Scrollable box are supported on the form. You can put
other widgets within these widgets.
i. Drag and drop the required widgets onto the HBox/Scrollable Box. Set the properties of
these widgets. For more information, see Kony Widget User Guide.
ii. A segment template is created.
For more information on setting a Section Header template for a segment, click here.
37.7.4 Using SegmentedUI Section Template

You can define only one template for each segment using the above process.
To use section template in an application, follow these steps:
3. Navigate to forms > mobile/tablet/desktop , right-click and select New Form. The Create a New
Form window appears.
5. If you are building for desktop, select the Form in desktop and right-click on the Form. Select Fork. The
Platform Selection window appears.
6. Select Desktop_web and click OK. The form is now forked for Desktop_web and new window
appears as web_<formname>.
Note: The development activities for desktop web should happen in web_<formname> only. Although the
newly created form, remains accessible in the desktop forms.
7. Drag-drop a SegmentedUI on the Form and add widgets to the segment as required. Click Save.
8. To set the template to a segment, select the segment and go to Properties window.
9. Select sectionHeaderTemplate and Select/Search Segment Template window appears. Select the
template, which you want to set to the segment.
10. Click OK.
Note: Setting data using data property will be made available in future releases.
38. Switch
The Switch widget is identical to the Switch Control (on-off switch which is non customizable) in iPhone and
presents two mutually exclusive choices or states.
The Switch widget displays the value that is currently in effect. You must slide the control to select (or reveal)
the other value.
Note: The Switch widget is supported on iOS, SPA, Desktop Web, Windows Phone (7.5 and 8), and
Windows 8 Tablets.
You can use a Switch widget to present the user two simple, diametrically opposed choices that determine
the state or choice of something.
For example, in an Airline application booking screen, you can use the Switch widget to display "One Way "
and "Round Trip". The user can choose to slide and select the required value before proceeding with the
booking.
The Switch widget provides you with an option to set Basic Properties, Layout Properties, and Events.
Basic Properties
Layout Properties
Events
id
info
isVisible
leftSideText
Left Text i18n Key
rightSideText
Right Text i18n Key
selectedIndex
skin
containerWeight
margin
marginInPixel
widgetAlignment
onSlide
Creating a Switch using a constructor: kony.ui.Switch

var myswitch = new kony.ui.Switch(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//The below function is the callback function for onSliderCallback event.
function onSliderCallbck(swtch)
{
}
//Defining the properties for Switch.

var swtchBasic = {id:"swtch", info:{key:"switch"}, leftSideText:"on", righ
tSideText:"off", skin:"swchSkin", selectedIndex:0, isVisible:true, onSlide
:onSliderCallbck};
var swtchLayout = {margin:[5,5,5,5], marginInPixel:false, widgetAlignment:
constants.WIDGET_ALIGN_TOP_LEFT, containerWeight:99};
//Creating the Switch.
var swtch = new kony.ui.Switch(swtchBasic, swtchLayout, {})
//Reading the id of the Switch
alert("Switch id is ::"+swtch.id);
Adding a Switch Widget
The steps involved in adding a Switch widget are as follows:
1. From the IDE, drag and drop the Switch widget onto a form (occupies the complete available width).
Or, based on your requirements, you can choose to perform the following :
a. If you want to resize a Switch widget in the horizontal direction, place an HBox on the form and
drag and drop the Switch inside the HBox and resize accordingly.
Note: You cannot resize a Switch widget in the vertical direction.

2. Specify the text to be displayed in the left and right portions of the Switch widget by using the
leftSideText and rightSideText properties respectively.
3. (Optional) Use the selectedIndex property to specify the option of the Switch that must be shown as
selected when rendered.
4. (Optional) Use the skin property to specify an image for the left and right portions of the Switch widget.
For example, you can use a bright image for the selected side and a dull image for the unselected side.
Note: You must first add a skin for the Switch widget and specify the Left Image and the Right
Image. For more information about adding skins in the IDE, see the Working with Applications
section of the Kony Studio User Guide.
5. (Optional) Specify an onSlide event.
The following are the important considerations for this widget:
l
For a good user experience, use a predictable pair of values so that the users do not have to slide the
Switch to know the other value.
You can also consider using the Switch widget to change the state of other UI elements in the view.
Depending upon the choice that the user makes, changes in the UI must take place.
For example, in an Airline application booking screen, based on the Switch widget selection as "One
Way" or "Round Trip", the required UI elements must change.
One color or Two colors in iPhone specific forked skin are supported only on iOS 5.0 and above. These
properties are not respected in versions older than iOS 5.0.
Following are the changes and behavior of Switch widget in iOS7 and above:
l
Right background color has no effect.
Size of the switch is fixed as 51 x 31 px. Hence the hExpand property has no effect.
Left side text and right side text has no effect.
If the skin is not applied, we will get the look and feel of native switch. If the skin is applied we
will not get the native look.
38.1 Switch - Basic Properties

The basic properties for Switch Widget are as follows:
l
id
info
isVisible
leftSideText
Left Text i18n Key
rightSideText
Right Text i18n Key
selectedIndex
skin
38.1.1 id
A unique identifier of Switch consisting of alpha numeric characters. Every Switch should have a unique id
within a Form.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Switch with the ID :"swtch"
tSideText:"off", skin:"swchSkin", selectedIndex:0, isVisible:true};
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.2 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Switch with the info property.
var swtchBasic = {id:"swtch", leftSideText:"on", rightSideText:"off", skin
:"swchSkin", selectedIndex:0, isVisible:true};
swtch.info = {key:"switch"};
//Reading the info of the Switch
alert("Switch info is ::"+swtch.info);
Accessible from IDE

No
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.3 isVisible
Default:true
Note: This property is not applicable if the widget is placed in a SegmentedUI. When the widget is placed in
a Segment, the default Visibility is set to true. If you want to change the value to false, you can do so by
using the SegmentedUI methods.
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Switch with the isVisible:true
var swtchBasic = {id:"swtch",info:{key:"switch"}, leftSideText:"on", right
SideText:"off", skin:"swchSkin", selectedIndex:0, isVisible:true};
//Reading the visibility of the Switch
alert("Switch visibility is ::"+swtch.isVisible);
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.4 leftSideText
Specifies the text to be displayed on the left portion of the Switch.
Syntax
JavaScript: leftSideText
Lua: leftsidetext
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Switch with the leftSideText :"on".
//Reading the id of the Switch.
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.5 Left Text i18n Key

Specifies the key to be used for internationalization of the string specified in the leftSideText property.
Syntax
JavaScript: leftSideText
Type
JavaScript: kony.i18n.getLocalizedString
Read / Write
No
JavaScript Example
//Defining the properties for Switch with the leftSideText: kony.i18n.getL
ocalizedString("select").
var swtchBasic = {id:"swtch", info:{key:"switch"}, leftSideText: kony.i18n
.getLocalizedString("select"), rightSideText:"off", skin:"swchSkin", selec
tedIndex:0, isVisible:true};
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.6 rightSideText
Specifies the text to be displayed on the right portion of the Switch.
Syntax
JavaScript: rightSideText
Lua: rightsidetext
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Switch with the rightSideText:"off"
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.7 Right Text i18n Key

Specifies the key to be used for internationalization of the string specified in the rightSideText property.
Syntax
JavaScript: rightSideText
Type
JavaScript: kony.i18n.getLocalizedString
Read / Write
No
JavaScript Example
//Defining the properties for Switch with the rightSideText: kony.i18n.get
LocalizedString("select").
var swtchBasic = {id:"swtch", info:{key:"switch"}, rightSideText: kony.i18
n.getLocalizedString("unselect"), leftSideText:"off", skin:"swchSkin",
selectedIndex:0, isVisible:true};
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
This property is accessible only from code and it specifies the option of the Switch that must be shown as
selected when rendered.
In JavaScript, the possible values for this property are 0 and 1. By default, the selected Index is set to 1, and
the option in the right portion of the Switch is selected. If you change the selected index to 0, the option in the
left portion of the Switch is selected.
In Lua, the possible values for this property are 1 and 2. By default, the selected Index is set to 2, and the
option in the right portion of the Switch is selected. If you change the selected index to 1, the option in the left
portion of the Switch is selected.
section.
Syntax
Lua: selectedindex
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Switch with the selectedIndex:0.
//Reading the selectedIndex of the Switch
alert("Switch selectedIndex is ::"+swtch.selectedIndex);
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.1.9 skin
Specifies a background skin for Switch widget.
Note: In iOS 7 platform, if the skin is not applied, we will get the look and feel of native switch. If the skin is
applied we will not get the native look.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
//Defining the properties for Switch with the skin:"swchSkin".
//Reading the skin of the Switch
alert("Switch skin is ::"+swtch.skin);
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.2 Switch - Layout Properties

The layout properties for Switch Widget are as follows:
l
containerWeight
margin
marginInPixel
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Switch with the containerWeight:70
//Reading the containerWeight of the Switch.
alert("Switch containerWeight is ::"+swtch.containerWeight);
Accessible from IDE

No
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.2.2 margin
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Switch with the margin:[5,5,5,5].
//Reading the margin of the Switch.
alert("Switch margin is ::"+swtch.margin);
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Switch with marginInPixel:false.
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
l
WIDGET_ALIGN_CENTER
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for Switch with widgetAlignment:constants.WIDGET_
ALIGN_TOP_LEFT.
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
38.3 Switch - Events

Switch has the following event associated with it:
38.3.1 onSlide
An event callback that is invoked by the platform when there is a change in the default selected value.
Syntax
JavaScript: onSlide
Lua: onslide
The onSlide event callback accepts additional parameters when a Switch widget is placed in a segment row
or section template.
Signature
JavaScript: onSlide (context)
Input Parameters
Index of the row that contains the Switch widget. It is not available if the Switch widget is placed in
a section header.
Index of the section row that contains the Switch widget.
Handle to the parent widget instance(segment) that contains the Switch widget.
Read / Write
JavaScript Example
//The below function is the callback function for onSliderCallback event.
function onSliderCallbck(swtch)
{
}
//Defining the properties for Switch.
var swtchBasic = {id:"swtch", info:{key:"switch"}, leftSideText:"on",
rightSideText:"off", skin:"swchSkin", selectedIndex:0, isVisible:true, onS

lide:onSliderCallbck};
Accessible from IDE

Yes
l
iOS
Windows Phone
Windows Tablet
SPA
Desktop Web
39. SignatureCapture
A SignatureCapture widget enables you to capture a signature on a form and save it as an image for easy
uploading.
Note: This widget is only supported on Windows Phone 8 and Windows 8 Tablet platforms.
The SignatureCapture widget provides you with an option to set Basic Properties, Layout Properties Platform
Specific Property, Event, and Methods.
Basic Properties
Layout Properties
base64
id
info
isVisible
penWidth
rawBytes
skin
containerWeight
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Event
Methods
onCapture
clear
getAsRawBytes
save
Platform Specific
Properties
accessMode
Creating a Signature using a constructor: kony.ui.SignatureCapture

var mysignature = new kony.ui.SignatureCapture(basicConf, layoutConf, pspC
onf)
l
they are ignored.
JavaScript Example
//Defining the properties for a SignatureCapture.
var signatureBasic = {id:"signature", info:{key:"signature"}, skin:"signat
ureSkin", isVisible:true, penWidth: 3};
var signatureLayout = {hExpand:false, vExpand:true, widgetAlignment:consta
nts.WIDGET_ALIGN_TOP_LEFT, containerWeight:100};
//Creating the SignatureCapture.
var signature = new kony.ui.SignatureCapture (signatureBasic,
signatureLayout, {})
//signature clear method call.
signature.clear();
Adding a SignatureCapture Widget
The steps involved in adding a SignatureCapture widget are as follows:
1. From the IDE, drag and drop the Signature widget onto a form or any other container widget.
2. Set the value of pen width to a value between 1 and 10 inclusive.
You can customize the appearance of the SignatureCapture widget by using the following properties:
l
skin: Specify the skin to be applied to the Signature widget.
The following are the important considerations for signature:
l
The padding and margin properties are not applicable for this widget.
This widget is supported only in Windows Phone 8 and Windows 8 tablet platforms.
39.1 SignatureCapture - Basic Properties

The basic properties for SignatureCapture Widget are as follows:
l
base64
id
info
isVisible
penWidth
rawBytes
skin
39.1.1 base64
downloading, null/nil is returned.
Note: This is a non-Constructor property. You cannot set this property through widget constructor.
Syntax
JavaScript: base64
Lua: base64
Type
Lua: UserData
Read / Write
Yes - (Read only)
Accessible from IDE

No
l
Windows Tablet
Windows Phone
39.1.2 id
A unique identifier of SignatureCapture consisting of alpha numeric characters.
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for SignatureCapture with the ID :"signature"

var signature = new kony.ui.SignatureCapture (signatureBasic, signatureLay
out, {})
//Reading the id of the SignatureCapture.
alert("SignatureCapture id is ::"+signature.id);
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.1.3 info
Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for SignatureCapture.
out, {})
//Reading the info of the SignatureCapture.
alert("SignatureCapture info is ::"+signature.info);
Accessible from IDE

No
l
Windows Tablet
Windows Phone
39.1.4 isVisible
Default:true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for SignatureCapture with the isVisible:true
out, {})
//Reading the visibility of the SignatureCapture.
alert("SignatureCapture visibility is ::"+signature.isVisible);
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.1.5 penWidth
Specifies the width of the stroke lines of a signature. You can enter a value between 1-10 inclusive.
Syntax
JavaScript: penWidth
Lua: penwidth
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for SignatureCapture with the penWidth:3
var signatureBasic = {id:"signature", info:{key:"signature"},
skin:"signatureSkin", isVisible:true, penWidth: 3};

out, {})
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.1.6 rawBytes
Specifies the rawbytes representing an Image that is returned from SignatureCapture.
Syntax
Lua: rawbytes
Type
Lua: UserData
Read / Write
Accessible from IDE

No
l
Windows Tablet
Windows Phone
39.1.7 skin
Specifies a background and pen color skin for SignatureCapture widget.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for SignatureCapture with the skin:"signatureSki
n".
out, {})
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.2 SignatureCapture - Layout Properties

The layout properties for SignatureCapture Widget are as follows:
l
containerWeight
hExpand
margin
marginInPixel
padding
paddingInPixel
vExpand
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for a SignatureCapture with containerWeight:100
out, {})
Accessible from IDE

No
l
Windows Tablet
Windows Phone
39.2.2 hExpand
Default: true
Syntax
JavaScript: hExpand
Lua: hexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a SignatureCapture with hExpand:true.
var signatureLayout = {hExpand:true, vExpand:true,
widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, containerWeight:100};
out, {})
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.2.3 margin
Syntax
Lua: widgetskin
Type
Lua: Table
Read / Write
JavaScript Example
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
Default: false
Syntax
Lua: margininpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
var segLayout ={padding:[5,5,5,5], margin:[5,5,5,5], marginInPixel:true, c
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.2.5 padding
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining properties for a Segment with padding:[5,5,5,5].
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
Default: false
Syntax
Lua: paddinginpixel
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining properties for a Segment with padding in pixels.
var segLayout ={padding:[5,5,5,5],margin:[5,5,5,5], paddingInPixel: true,
var segPSP ={};
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.2.7 vExpand
Default: false
Syntax
JavaScript: vExpand
Lua: vexpand
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for a SignatureCapture with vExpand:true.
var signatureLayout = {hExpand:true, vExpand:true, widgetAlignment:constan
ts.WIDGET_ALIGN_TOP_LEFT, containerWeight:100};

out, {})
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
l
WIDGET_ALIGN_CENTER
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a SignatureCapture with widgetAlignment.
var signatureLayout = {hExpand:true, vExpand:true, widgetAlignment:constan
ts.WIDGET_ALIGN_TOP_LEFT, containerWeight:100};
out, {})
Accessible from IDE

Yes
l
WindowsTablet
Windows Phone
39.3 SignatureCapture - Platform Specific Properties

The platform specific properties for this SignatureCapture Widget are as follows:
39.3.1 accessMode
Specifies how the captured image must be stored.
Default:CAMERA_IMAGE_ACCESS_MODE_PRIVATE
l
CAMERA_IMAGE_ACCESS_MODE_PRIVATE: The captured image is stored as an Image on the

device and will not be accessible to any other application on the device and remain private to the
application.
CAMERA_IMAGE_ACCESS_MODE_PUBLIC: The captured image is stored on the device as a

Image and is accessible to all the applications on the device. For example, the captured images are
accessible in ImageGallery.
CAMERA_IMAGE_ACCESS_MODE_INMEMORY: The captured camera image is stored in memory

and is never written to the disk.
Syntax
Lua: accessmode
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
var signaturePSP = {accessMode:constants.CAMERA_IMAGE_ACCESS_MODE_
INMEMORY};
out, signaturePSP)
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone
39.4 SignatureCapture - Event

The SignatureCapture Widget has the following event associated with it:
39.4.1 onCapture
An event callback is invoked when the user captures a picture.
Signature
JavaScript: onCapture
Lua: oncapture
Read / Write
JavaScript Example
//The below function is the callback for onCapture event of the SignatureC
apture widget.
function onCapturCalBck(SignatureCapture)
{
//Write logic here
}
//Defining the properties for a SignatureCapture
ureSkin", isVisible:true, penWidth: 3, rawBytes:"11111", onCapture:onCaptu
rCalBck};
var signaturePSP = {accessMode:constants.CAMERA_IMAGE_ACCESS_MODE_
INMEMORY};
out, signaturePSP )
Accessible from IDE

Yes
l
Windows Tablet
Windows Phone 8
39.5 SignatureCapture - Methods

SignatureCapture widget has the following methods associated with it:
l
clear
getAsRawBytes
save
39.5.1 clear
This method enables you to clear the area where a signature is captured. If signature is already set to widget,
canvas will show that signature. If an image is not loaded, the area where the signature widget is placed is
cleared.
Signature
JavaScript: clear()
Lua:signaturecapture.clear(signaturecatureId)
Input Parameters
signaturecatureId[widgetref] - Mandatory
Return Values
None
JavaScript Example
out, {})
//signature clear method call.
signature.clear();
Error Codes
None
l
Windows Tablet
Windows Phone
39.5.2 getAsRawBytes
This method enables you to return the signature that is saved as an image as rawbytes. These rawbytes can
be used to assign the signature image to another widget. getasrawbytes() returns rawbytes which can be
assigned to a variable and later can be assigned only to an image.
Signature
JavaScript: getAsRawBytes(imageformat)
Lua:signaturecapture.getasrawbytes(signaturecatureId, imageformat)
Input Parameters
imageformat[String] - Mandatory
Specifies the image format. The supported file formats are png or jpg.
Return Values
None
Error Codes
None
l
Windows Tablet
Windows Phone
39.5.3 save
Saves the signature as an image to the location where images are stored. The signature can be stored as png
or jpg formats.
Signature
JavaScript: save (filename, imageformat)
Lua:signaturecapture.save(signaturecatureId, filename, imageformat)
Input Parameters
filename[String] - Mandatory
Specifies the name of the file.
imageformat[String] - Mandatory
Specifies the image format. The supported file formats are png or jpg.
Return Values
None
JavaScript Example
out, {})
//signature save method call.
signature.save("mysignature", "png");
Error Codes
None
l
Windows Tablet
Windows Phone
40. Video
Video widget enables you to play a video (by streaming data from a server) within a form. You can add a video
widget only within a container widget.
Note: This widget is currently supported only on SPA and Desktop Web platforms.
When do I use a Video Widget?
You can use a video widget in the following scenario:
l
To play a video which may provide an explanation about the contents of the form.
To play an advertisement within the form.
To play a video which provides product features.
Basic Properties
Layout Properties
id
isVisible
skin
source
text
containerWeight
margin
padding
widgetAlignment
controls
poster
Creating a Video using a constructor: kony.ui.Video

var video = new kony.ui.Video(basicConf, layoutConf, pspConf)
l
they are ignored.
JavaScript Example
//Defining the properties for Video with Id:"video"
var videoBasic ={id:"video", skin:"vSkin", source:{mp4 : "mp4 URL", web :
"webm URL", ogv : "ogv URL" }, isVisible:true};
var videoLayout = {widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT, contai
nerWeight:99, padding:[5,5,5,5], margin:[5,5,5,5]};
var videoPSP = {controls:true};
//Creating the Video.
var video = new kony.ui.Video(videoBasic, videoLayout, videoPSP);
//Reading id of the Video
alert("Video id is ::"+video.id);

The appearance of the Video widget across platforms is depicted below:
Platform
Appearance
Android (SPA/Mobile Web

Advanced)
BlackBerry (SPA/Mobile
Web Advanced)
iPhone (SPA/Mobile Web

Advanced)
Adding a Video Widget from IDE

The steps involved in adding a Video widget are as follows:
1. From the IDE, drag and drop the Video widget onto a Container widget.
2. Double-click Video widget and locate source property from the Edit Properties window.
3. Specify the source URL from which the video will be streamed.
4. (Optional) You can specify a poster which is to be displayed within the video widget area before a video
starts playing.
You can customize the appearance of a Video by using the following properties:
The following are the important considerations for a Video widget:
l
When the form contains dockable components such as headers, footers, or an Appmenu, scrolling the
video widget on iPhone or iPad does not scroll the form. This is due to a limitation that iPhone video
controls do not respond to (custom) touch events when media controls are present.To avoid this, apply
left or right margins to the either side of the video widget to enable scrolling of the form as well.
If you have two videos in a form, you can only play one at a time.
Supported devices and video formats for SPA platform.
Category and
Device
OS
Browser
OGG, MP4,
OGV)
XHTML
Mandatory
Attributes Comments
Height/Wi
dth
Video
Format
(WebM,
BB Non Touch BB 6
BlackBerry 9780 bold
Native BB
Browser
MP4
Supported
BB 7.0 (touch) BlackBerry 9900 Bold BB 7

and BlackBerry 9860
BB 6.0 (touch) BlackBerry 9800
BB 6
Torch
Windows Phone
Mango - Dell Venue Win 7.5
Pro
Native BB
Browser
MP4
na
Native BB
Browser
not
supported
na
IE9
not
supported
na
MP4
na
MP4
na
MP4
na
MP4
MP4
na
na
MP4
na
iPhone - iPhone
iOS 4.2.1
iPhone - iPhone
Windows Phone 8 Windows Phone 8
(Nokia)
iOS 6.1.3
Native
Android
Webkit
Native
Android
Webkit
Native
Android
Webkit
Safari
Safari
OS8
IE10
Samsung Galaxy S2 - Android

amsung I9100
2.3.3
amsung I9100
4.0.4
amsung I9100
4.0.4
Video tag doesn't render without

XHTML attributes
Supported video formats on different browsers for Desktop Web platform.

Video widget in print API is not supported in Firefox browser.
Refer to the below links for supported video formats on Desktop Web platform:
http://caniuse.com/#search=video
http://www.w3schools.com/tags/att_video_poster.asp
40.1 Video - Basic Properties

The basic properties of Video Widget are as follows:
l
id
isVisible
skin
source
text
40.1.1 id
id is a unique identifier of Video consisting of alpha numeric characters. Every Video should have a unique id
within an Form.
Note: This is a Construct-only property. You cannot set this property through a widget constructor. But
Syntax
JavaScript: id
Lua: id
Type
Read / Write
Yes - (Read only)
JavaScript Example
//Defining the properties for Video with Id:"video"
var videoBasic ={id:"video", skin:"vSkin", source:{mp4 : "mp4 URL", web :
var videoLayout = {widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT,
containerWeight:99, padding:[5,5,5,5], margin:[5,5,5,5]};

var video = new kony.ui.Video(videoBasic, videoLayout, {});
//Reading id of the Video
alert("Video id is ::"+video.id);
Accessible from IDE

Yes
l
Desktop Web
40.1.2 isVisible
This property controls the visibility of the Video widget on the form.
Default: true
Syntax
Lua: isvisible
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
JavaScript Example
//Defining the properties for Video with isVisible:true
var videoBasic ={Id:"video", skin:"vSkin", source:{mp4 : "mp4 URL", web :
var videoLayout = {widgetAlignment:constants.WIDGET_ALIGN_TOP_LEFT,
containerWeight:99, padding:[5,5,5,5], margin:[5,5,5,5]};

//Reading isVisible of the Video
alert("Video isVisible is ::"+video.isVisible);
Accessible from IDE

Yes
l
Desktop Web
40.1.3 skin
Specifies the look and feel of the video when not in focus.
Syntax
JavaScript: skin
Lua: skin
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Video with skin:"video"
//Reading skin of the Video

alert("Video skin is ::"+video.skin);
Accessible from IDE

Yes
l
Desktop Web
40.1.4 source
Specifies the URLs of the video which are to be streamed. When you click the
button next to the source
property, the Video widget source URLs dialog appears. Specify the URL of a video which is saved in three
different formats. The three formats are mp4, webm, ogv. {mp4 : "mp4 URL", web : "webm URL", ogv : "ogv
URL"}.
For example, if you stream a video from a server , the video must be available in all the three formats. You
then specify the URL of these videos in the Video widget source URLs dialog.
Note: It is mandatory to specify the URL for all the three different formats. The device browser plays a
format which is compatible with the underlying Native SDK.
Syntax
JavaScript: source
Lua: source
Type
Lua: UserData
Read / Write
JavaScript Example
//Defining the properties for Video with source:{mp4 : "mp4 URL", web : "w
ebm URL", ogv : "ogv URL"}, Here mp4 URL means the URL which will open mp4
video, Similarly webm URL and ogv URL.

//Reading source of the Video
alert("Video source is ::"+video.source);
Accessible from IDE

Yes
l
Desktop Web
40.1.5 text
Specifies a general or descriptive text for the Video widget.
Syntax
JavaScript: text
Lua: text
Type
JavaScript: String
Lua: String
Read / Write
JavaScript Example
//Defining the properties for Video with text: "samplevideo".
"webm URL", ogv : "ogv URL" }, isVisible:true, text: "samplevideo"};
var video =
new kony.ui.Video(videoBasic, videoLayout, {});
//Reading source of the Video

alert("Video source is ::"+video.source);
Accessible from IDE

Yes
l
Desktop Web
40.2 Video - Layout Properties

The Layout properties for Video Widget are as follows:
l
containerWeight
margin
padding
widgetAlignment
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for Video with containerWeight:70
//Reading containerWeight of the Video
alert("Video containerWeight is ::"+video.containerWeight);
Accessible from IDE

Yes
l
Desktop Web
40.2.2 margin
between the widget and the next element. The Array format is [left, top, right, bottom]. For example:
[10,10,10,10].
Syntax
JavaScript: margin
Lua: margin
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Video with margin:[5,5,5,5].
//Reading margin of the Video
alert("Video margin is ::"+video.margin);
Accessible from IDE

Yes
l
Desktop Web
40.2.3 padding
define the top, left, right, and bottom distance between the widget content and the widget boundary. The Array
format is [left, top, right, bottom]. For example: [10,10,10,10].
Syntax
JavaScript: padding
Lua: padding
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for Video with padding:[5,5,5,5]
//Reading padding of the Video
alert("Video padding is ::"+video.padding);
Accessible from IDE

Yes
l
Desktop Web
l
WIDGET_ALIGN_CENTER
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No
JavaScript Example
//Defining the properties for a Video with widgetAlignment as LEFT.
var chkLayout = {containerWeight:80, percent:false, widgetAlignment:consta
nts.WIDGET_ALIGN_MIDDLE_LEFT};
Accessible from IDE

Yes
l
Desktop Web
40.3 Video - Platform Specific Properties

The platform specific properties for Video Widget are as follows:
l
controls
poster
40.3.1 controls
Specifies if the default video controls need to be displayed. When this property is set to false, video is
playable by clicking anywhere on the Poster.
Default: True
If set to false, the video controls are not displayed.
If set to true, the video controls are displayed.
Syntax
JavaScript: controls
Lua: controls
Type
JavaScript: Boolean
Lua: Boolean
Read / Write
No
JavaScript Example
//Defining the properties for Video with controls:true.
var video = new kony.ui.Video(videoBasic, videoLayout, {controls:true});
Accessible from IDE

Yes
l
SPA(Android)
Desktop Web
40.3.2 poster
You can specify an image which is to be displayed as a poster or as a starting image for the video. The image
location must point to an external URL. For example,
www.kony.com/sites/all/themes/kony/logo.png
Syntax
JavaScript: poster
Lua: poster
Type
JavaScript: String
Lua: String
Read / Write
No
JavaScript Example
//Defining the properties for Video with poster:"Sample URL"
var video = new kony.ui.Video(videoBasic, videoLayout, {poster:"Sample UR
L"});//Sample URL means URL of the poster which will be displayed when the
video is not playing.
Accessible from IDE

Yes
l
Desktop Web
41. App Menu

The Application Menu (App Menu) contains features that apply to the application as a whole, rather than to a
specific application screen or window.
Every application has features for the users, you can choose to make these features available on every
screen or specific screens of the application (by using the needAppMenu in a form) for easy navigation to
these features.
For example, for a banking mobile application, the application features can include Accounts, Payments,
Transfers, ATM Locations, and Services.
These features can be placed as App Menu as illustrated in the figure below:
Note: On BlackBerry and J2ME platforms, App Menu is also supported on a Popup.
Appmenu provides you with an option to set Common Properties, Platform Specific Properties, and Methods.
Common Properties
Skin
Focus Skin
ID
Platform Specific
Properties
Needs Separator
Appbar Button Style
Position
Methods
createAppMenu
setCurrentAppMenu
getCurrentAppMenu
Title
setAppMenuFocusByID
Icon
addAppMenuItemAt
Render
removeAppMenuItemAt
i18n Key
setAppMenuBadgeValue
Event
getAppMenuBadgeValue
Android Specific Behavior

l
If you add more than six App Menu items, the menu items beyond the fifth App Menu item are grouped
under the Menu item More (added automatically by the Android platform) and if you select More, the
rest of the Menu items are displayed in a list without any icons (even if the icons are set through code).
This is an Android platform limitation.
You cannot specify a skin for the App Menu.
BlackBerry Specific Behavior

l
Image for a App Menu item will not be displayed.
If an event is not defined, the App Menu item behaves as Close command.
BlackBerry 10 Specific Behavior

l
A maximum of five App Menu items can displayed on the screen. Even if you provide more than 5
items, it will display 5 items and ignore the rest.
iOS Specific Behavior

l
In iOS 7 and iOS 7.1, AppMenu supports only single color. If the color is not specified, then by default
native color (transparent) is applied to iOS 7 and cyan color is applied to iOS7.1.
A maximum of five App Menu items can displayed on the screen. If you want to display more than 5
items, follow any of the below steps:
o
Create a customizable more controller using KonyForm, which would give you the
appmenu look & feel and navigation perspective.
Use show/hide app menu items as required.
You should always show a form in closure execution of app menu item.
Windows 7 Specific Behavior

l
A maximum of four App Menu icons can displayed on the screen followed by an ellipsis. If you click the
ellipsis, the description of the App Menu icons is displayed.
If there are more than four App Menu items, when you click the ellipsis, the text describing the four App
Menu is displayed along with the rest of the App Menu items in a list without icons.
The text describing the app menu icons are always in a lowercase.
Only One Color Background style is supported for the App Menu.
The font color is applied to the App Menu item text and the circle around the App Menu item icon.
Mobile Web Specific Behavior:

l
On Mobile Web platforms, if you add more than four App Menu items, the menu items beyond the
fourth App Menu item are grouped under the Menu item More (added automatically by the Mobile Web
platform) and if you select More, all the App Menu items are displayed in a list with the associated
icons.
Note: Only the icons in the list are clickable and not the text.
For dynamic App Menu (addmenuitem and removemenuitem) to work on Mobile Web, you must have
atleast one App Menu item at the application level from the IDE; otherwise the dynamic App Menu will
not work.
l
The behavior of the App Menu in Mobile Web Advanced, Basic, and BJS is not the same. The behavior
of the App Menu for Mobile Web (Advanced, Basic, and BJS) is as follows:
Note: In Mobile Web (Advanced) versions, the App Menu is displayed at the bottom of the screen and is
visible even when you scroll the form.
Note: In Mobile Web (Basic and BJS) platforms, the App Menu is available at the bottom of the form and
you must scroll to the bottom of the form to see the App Menu.
41.1 Common Properties

The properties for the App Menu are as follows:
l
Skin
Focus Skin
ID
Title
Icon
Render
i18n Key
Event
41.1.1 Skin
Specifies the look and feel of the App Menu.
Note: For iPhone and Android, you cannot set a skin for the default App Menu items.
Note: In iOS 7 and iOS 7.1, AppMenu supports only single color. If the color is not specified, then by default
native color (transparent) is applied to iOS 7 and cyan color is applied to iOS7.1.
Type
String
Read / Write
No
Accessible from IDE

Yes
Note: When you apply a skin for an App Menu item for Kiosk, the menu items overflow outside the emulator
width. The items shown outside the appmenu bar are called the overflow items. When the appmenu
contains more items than can fit into its area, it enables the overflow button. To see the overflow items, the
user can click the overflow button and the items are shown in a pop-up window below the appmenu.
41.1.2 Focus Skin

Specifies the look and feel when there is focus on the App Menu.
Note: For iPhone and Android, you cannot set a focus skin for the default App Menu items.
Type
String
Read / Write
No
Accessible from IDE

Yes
41.1.3 ID
A unique identifier of App Menu consisting of alpha numeric characters.
Accessible from IDE

Yes
41.1.4 Title
Specifies a general or descriptive text for App Menu.
Type
String
Read / Write
No
Accessible from IDE

Yes
41.1.5 Icon
Specifies the image to be displayed for the App Menu item.
Type
String
Read / Write
No
Accessible from IDE

Yes
41.1.6 Render
Specifies if the widget code must be included in the platform when the code is generated.
You can use the Render property to specify the platforms on which the widget will not be available.
By default, the Render property includes all the platforms. You must explicitly clear the check box against the
platforms that you want to exclude.
The following illustration shows the render option:
Unlike the Visible property, the Render property does not include the widget in the code generated for the
excluded platforms and hence the generated code results in an optimized application for the excluded
platforms.
Note: When two widgets are placed side by side in an HBox, and you exclude one widget from code
generation, the widget which is rendered respects its container weight and does not expand.
However, on Mobile Web advanced platform, due to the browser behavior, the widget which is rendered
does not respect the container weight and expands to occupy the available width.
Type
String
Read / Write
No
Accessible from IDE

Yes
41.1.7 i18n Key

Specifies the i18n Key to be used for internationalization.
Type
String
Read / Write
No
Accessible from IDE

Yes
41.1.8 Event
Specifies the event for the App Menu item. For more information, see Kony Studio User Guide.
Note: In BlackBerry platform, if an event is not defined, the App Menu item behaves as Close command.
Accessible from IDE

Yes
41.2 App Menu - Platform Specific Properties

The platform specific properties for App Menu are as follows:
l
Needs Separator
Appbar Button Style
Position
41.2.1 Needs Separator

Specifies if the App Menu must have a separator between the App Menu items. By default, this property is
selected and a separator appears between the App Menu items.
If you do not want the separator for an App Menu item, open the Edit Platform Specific Properties screen and
clear the Needs Separator check box.
Note: This property is applicable only on BlackBerry platform from version 6.0 and above.
The following image illustrates the Edit Platform Specific Properties screen:
The following image illustrates an App Menu with a separator between the App Menu items:
Available on BlackBerry platform only
41.2.2 Appbar Button Style

Specifies the button style for application bar. For example, you can apply a the button style with play button
style or pause button style etc.
Accessible from IDE

Yes
Available on Windows Tablet platform only
41.2.3 Position
Specifies the position of the button for application bar.
l
BOTTOM_LEFT
BOTTOM_RIGHT
TOP_LEFT
TOP_RIGHT
Accessible from IDE

Yes
Available on Windows Tablet platform only
41.3 Methods
The namespace for App Menu is kony.application. It has the following methods associated with it:
l
createAppMenu
setCurrentAppMenu
getCurrentAppMenu
setAppMenuFocusByID
addAppMenuItemAt
removeAppMenuItemAt
setAppMenuBadgeValue
getAppMenuBadgeValue
41.3.1 createAppMenu
This method allows you to create App Menu dynamically through code.
Note: You must set this method in pre-appinit property. You can set this method only once. For more
information about the pre-appint property, see Configuring Project Properties, Application Properties in the
Note: On Android platform, if you add more than six App Menu items, the menu items beyond the fifth App
Menu item are grouped under the Menu item More (added automatically by the Android platform) and if you
select More, the rest of the Menu items are displayed in a list without any icons (even if the icons are set
through code). This is an Android platform limitation.
Note: On Windows Phone, a maximum of four App Menu icons can be displayed on the screen followed by
an ellipsis. If you click the ellipsis, the description of the App Menu icons is displayed.
Signature
JavaScript: kony.application.createAppMenu (appMenuId, appMenu, skinID, onFocusSkinID)
Lua: createappmenu (appMenuId, appMenu, skinID, onFocusSkinID)
Input Parameters
appMenuId [String] - Mandatory
Id of the menu item.
appMenu [Array of arrays] - Mandatory
l
menuitemId: ID of the menu item.
menuitemName: Name of the menu item.
menuitemImage: The image to be used for the menu item (image will not be displayed on
Blackberry platform).
menuitemClosure: onclick event to be executed for the menu item.
menuitemSeparator: (Applicable on Blackberry only) A boolean value to hide/show the

separator below the menu item.Default: true (the separator is shown)
Note: On iOS platform, menuitemId and menuItemClosure are mandatory parameters and the
menuItemClosure should end with form.show() call.
skinID [String] - Optional
The normal skin to be set for the menu.
onFocusSkinID [String] - Optional
The focus skin to be set for the menu.
Return Values
None
Exceptions
SkinError - If the skin is not defined with the specified skin identifier.
Error - If the input is invalid type or doesn't follow the structure as expected.
Special Considerations
If the app menu is already created with the identifier passed, a new app menu will be created and the old
app menu will be replaced with the new one.
At least one app menu item is must in the app menu created. App menu with zero number of app menu
items is invalid.
Example
To create an App Menu for a banking application with Accounts and Payments enter the following:
//The below two functions are callback functions for onClickClosure events
for menu items.
function onClickClosure1()
{
//proceed with the logic
}
{
}
//Defining appmenu items (Atleast one item should be defined).
var appMenuItem1 = ["appmenuitemid1","Accounts", "icon1.png",
onClickClosure1, {startupForm: "someform", selectedImage: "someimage"}];

var appMenuItem2 = ["appmenuitemid2", "Payments", "icon2.png", onClickClos
ure2];
//defining appMenu parameter with the above menu items.
var appMenu = [appMenuItem1, appMenuItem2];
//Creating App menu.
kony.application.createAppMenu("myappmenu", appMenu, "skn1", "fcskn1");
Error Codes
None
41.3.2 setCurrentAppMenu
This method uses the unique identifier which represents the App Menu and sets it as current app menu. There
can be only one current app menu that can be set any time. If you call this method multiple times, will replace
the current app menu.
Note: For iPhone, this method is one way of showing the form as well as focusing on a specific menu item.
Note: When an appmenu is set as current app menu item, by default the first app menu item of the app
menu is selected and the function associated with the first app menu item gets executed.
Signature
JavaScript: kony.application.setCurrentAppMenu(appMenuId)
Lua: setcurrentappmenu(appMenuId)
Input Parameters
ID of the menu item.
Return Values
None
Exceptions
Example
//After creating appMenu with the unique identifier "myappmenu", set it as
current app menu.
kony.application.setCurrentAppMenu("myappmenu");
Error Codes
None
41.3.3 getCurrentAppMenu
This method returns the unique identifier of the current app menu that is set through setCurrentAppMenu.
Signature
JavaScript: kony.application.getCurrentAppMenu ()
Lua: getcurrentappmenu ()
Input Parameters
None
Return Values
This method returns appMenuId as string. Incase of app menu is not set, null is returned.
Exceptions
None
Example
//Get the Current app menu
var currAppMenuId = kony.application.getCurrentAppMenu();
//Alert the Current app menu
alert("Current app menu id is:: "+currAppMenuId);
Error Codes
None
41.3.4 setAppMenuFocusByID
This method takes id (which is set using createAppMenu) instead of index and sets the focus on the menu
item of the current app menu.
Note: While using this method, ensure that the current menu item is in focus before showing the form.
Note: For iOS platform, closure associated with the focus id will get executed along with setting the focus to
the given id.
Signature
JavaScript: kony.application.setAppMenuFocusByID(appMenuitemId)
Lua: setappmenufocusbyid(appMenuitemId)
Input Parameters
appMenuItemId [String] - Mandatory
ID of the app menu item.
Return Values
None
Exceptions
At any given point of time, one of the app menu items in the current app menu is mandatory to be focused
app menu item.
Example
To set focus on the App Menu items 2, enter the following:
//Set the menu item with the identifier "appmenuitemid2" as the focused me
nu item.
kony.application.setAppMenuFocusByID("appmenuitemid2");
Error Codes
No error codes
Available on all platforms except on BlackBerry, BlackBerry 10, and on all Windows channels
41.3.5 addAppMenuItemAt
This method adds an App Menu item at the given index.
Signature
JavaScript: kony.application.addAppMenuItemAt(appMenuId, index, appMenuItem)
Lua: addappmenuitemat(appMenuId, index, appMenuItem)
Input Parameters
This method has the following parameters:
Id of the appmenu to which the menu item is to be added. This is the ID used while creating the app
menu.
The index at which the menu item must be added. The index value lies between 0 and n-1. If the
index is beyond the current length of the app menu items then item is added to the end.
appmenuItem [array of arrays] - Mandatory
l
menuitemId: ID of the menu item.
menuitemImage: The image to be used for the menu item (image will not be displayed
on BlackBerry platform).
menuitemSeparator: (Applicable on BlackBerry only) A boolean value to hide/show the

separator below the menu item. Default: true (the separator is shown).
menuitemVisibility: (Applicable on BlackBerry only) A boolean value to hide/show the

menu item. Default: true (the menu item is displayed).
Note: On iOS platform, menuitemId and menuItemClosure are mandatory parameters and the
menuItemClosure should end with form.show() call.
Return Values
None
Exceptions
The index value starts from 0. For example, to insert a menu item at the 4th position specify the index
value as 3.
Example
//The below function is the callback function for onClickClosure event of
app menu item with id "appmenuitemid3".
{
}
//Defining app menu item.
var appMenuItem3 = ["appmenuitemid3","Rewards","reward.png",onClickClosure
3, {startupForm: "someform", selectedImage: "someimage"}];
//Adding the above app menu item at the index 4.
kony.application.addAppMenuItemAt("accountMenu", 3,
appMenuItem3);
Error Codes
No error codes
41.3.6 removeAppMenuItemAt
This method removes the specified App Menu item.
Signature
JavaScript: kony.application.removeAppMenuItemAt(appMenuId, index)
Lua: removeappmenuitemat(appMenuId, index)
Input Parameters
This method has the following parameters:
Id of the appmenu to which the menu item is to be removed. This is the ID used while creating the
app menu.
The index at which the menu item must be removed.
Return Values
None
Exceptions
If current focus menu item is removed then the first menu item of the app menu will be focused by default
as its associated function will be selected.
At least one app menu item must be present in the app menu. App menu with zero number of app menu
items is invalid state of the app menu.
Example
var appMenuId = "accountMenu";
//Removing the app menu item at index 2.
kony.application.removeAppMenuItemAt(appMenuId,2);
Error Codes
No error codes
41.3.7 setAppMenuBadgeValue
This method allows you to set a badge value to the given app menu item at the upper, right corner of the menu
item. Passing an empty string "" as a parameter, removes the badge off the appmenu item. This method is
applicable only for iPhone. The figure below depicts a badge applied on an appmenu item.
Signature
JavaScript: kony.application.setAppMenuBadgeValue(appMenuId, menuItemId, badgeValue)
Lua: setappmenubadgevalue(appMenuId, menuItemId, badgeValue)
Input Parameters
If you are setting the badge for an app menu item that was created dynamically, use the same ID
that was used to create the app menu item.If you are setting the badge for an app menu item that
was created from the IDE, use the ID available in the generated script file.
menuItemId [String] - Mandatory
Id of the app menu item to which the badge value is to be set.
badgeValue [String] - Mandatory
Value of the badge. The value you specify in the badge value appears within the badge. If the length
of the badge value is greater than 1 the badge is a rounded rectangle. For example, if you specify
the value of the badge as 88, the number appears in a rounded rectangular badge. If the length of
the badge value is 1, the badge is always a circle. The maximum number of characters that can be
specified in a badge value is 9. If the badge value id beyond 9 only the first 9 characters are
displayed.
Return Values
None
Exceptions
None
Example
//Set the AppMenuBadgeValue for the menu item with id ::"appmenuitemid3" ,
here the badge value is "3".
kony.application.setAppMenuBadgeValue("accountMenu","appmenuitemid3","3");
Error Codes
No error codes
For more information about the Badge APIs refer the Kony API Reference Document.
This method is available on iPhone/iPad
41.3.8 getAppMenuBadgeValue
This method enables you to read the badge value (if any) attached to the given Appmenu item.
Signature
JavaScript: kony.application.getAppMenuBadgeValue(appMenuId, menuItemId)
Lua: getappmenubadgevalue(appMenuId, menuItemId)
Input Parameters
If you are setting the badge for an app menu item that was created dynamically, use the same ID
that was used to create the app menu item.If you are setting the badge for an app menu item that
was created from the IDE, use the ID available in the generated script file.
menuItemId [String] - Mandatory
Id of the app menu item from which the badge value is to be read.
Return Values
String - returns the badge value.
Exceptions
None
Example
//Get the AppMenuBadgeValue for the menu item with id ::"appmenuitemid3".
kony.application.getAppMenuBadgeValue("accountMenu","appmenuitemid3");
For more information about the Badge APIs refer the Kony API Reference Document.
41.4 Methods
The namespace for App Menu is kony.application. It has the following methods associated with it:
l
setAppMenu
setAppMenuFocusIndex
showAppMenuItems
hideAppMenuItems
41.4.1 setAppMenu
This method allows you to create App Menu dynamically through code.
Note: You must set this method in pre-appinit property. You can set this method only once. For more
information about the pre-appint property, see Configuring Project Properties, Application Properties in the
Note: On Android platform, if you add more than six App Menu items, the menu items beyond the fifth App
Menu item are grouped under the Menu item More (added automatically by the Android platform) and if you
select More, the rest of the Menu items are displayed in a list without any icons (even if the icons are set
through code). This is an Android platform limitation.
Note: On Windows Phone, a maximum of four App Menu icons can be displayed on the screen followed by
an ellipsis. If you click the ellipsis, the description of the App Menu icons is displayed.
Input Parameters
appMenu [Object] - Mandatory
l
menuitemID: ID of the menu item.
menuitemImage: The image to be used for the menu item (image will not be displayed on
Blackberry platform).
menuitemSeparator: (Applicable on Blackberry only) A boolean value to hide/show the

separator below the menu item.Default: true (the separator is shown)
skin [Object] - Optional

The normal skin to be set for the menu.
onFocusSkin [Object] - Optional
The focus skin to be set for the menu.
Return Values
None
Example
To create an App Menu for a banking application with Accounts and Payments enter the following:
//The below two functions are callback functions for onClickClosure events
for menu items.
{
}
{
}
//Defining appmenu items (Atleast one item should be defined)

var appMenuItem1 = ["appmenuitemid1","Accounts", "icon1.png", onClickClosu
re1];
var appMenuItem2 = ["appmenuitemid2", "Payments", "icon2.png", onClickClos
ure2];
//defining appMenu parameter with the above menu items
var appMenu = [appMenuItem1, appMenuItem2];
//Creating App menu
kony.application.setAppMenu(appMenu, "skn1", "fcskn1");
Error Codes
No error codes
41.4.2 setAppMenuFocusIndex
Specifies the App Menu item on which the focus must be set.
Note: For iPhone, this method is one way of showing the form as well as focusing on a specific menu item.
This method should not be called from any lifecycle event of the form.
Input Parameters
Specifies the index number 0<= index <=n-1; where n is the number of App Menu items.
Return Values
None
Example
//To set focus on App Menu item 2, enter the following:
setappmenufocusindex(1)
//The index should be n-1//
Error Codes
None
Available on all platforms except Android, BlackBerry, Symbian, and J2ME.
41.4.3 showAppMenuItems
This method shows only the App Menu items that you specify and hides the rest.
Input Parameters
listofmenuids [Object] - Mandatory
Specifies the index number 0<= index <=n-1; where n is the number of App Menu items.
Return Values
None
Example
//To show only the App Menu items 1 and 2 and hide the others, enter the f
ollowing:
showappmenuitems({"appmenuid1","appmenuid2"})
Error Codes
None
41.4.4 hideAppMenuItems
This method hides the App Menu items that you specify and shows the rest.
Note: For iPhone, this method should not be called from any lifecycle event of the form.
Input Parameters
listofmenuIds [Object] - Mandatory
Specifies the list of App Menu items.
Return Values
None
Example
//To hide App Menu items 1 and 2, enter the following:
hideappmenuitems({"appmenuid1","appmenuid2"})
Error Codes
None
42. Accessibility (508 Compliance)

Accessibility on the Web refers to the best practice of providing equal access and equal opportunity to people
with diverse disabilities. This chapter provides the concepts of accessibility and implementation it through
Kony Studio. This chapter explains the following topics:
l
What is 508 Compliance?
Navigation Keys
Achieving 508 Compliance Using Kony Studio
Widget Navigation Model and Tab/Focus Order
What is 508 Compliance?

In software application development, 508 Compliance is also referred to as accessibility. For example, people
with impaired vision must be able to use software with the help of touch gestures, that is designed to run on a
system that has a keyboard. The result of performing a function is read out using the screen reading
technology.
The assistive technology (AT) for iPhone and Android platforms has built-in programs that support
accessibility when enabled on devices. Browser-based platforms use the Web Accessibility Initiative Accessible Rich Internet Applications (WAI-ARIA) framework. The WAI-ARIA framework enables you to add
attributes to identify features for user interaction, map controls, events, and APIs used in a rich Internet
application.
The tablebelow shows different platforms and their assistive technology:
Platform
Assistive Technology
iOS
Android
SPA
VoiceOver
TalkBack
WAI-ARIA
Note: The screen-reading capabilities of the different assistive technologies may vary and may not produce
the same results.
Navigation Keys
When a device enables assistive technology, visually impaired users typically navigate through the UI
controls such as tab/enter/arrow keys/page up/down keys. On various touch-only devices, a few of these key
actions are mapped to touchscreen finger gestures.
The chart below shows how keyboard-based navigation keys are mapped to gestures on mobile platforms:
Note: A gesture may function differently in different assistive technologies. Refer to the respective
assistive technology documentation for more information on gestures.
Keyboard
based devices
(desktop)
Tab
Shift+Tab
Enter /Space
Right Arrow/Up
Arrow
Left Arrow/Up
Arrow
Page Up
Page Down
Purpose
To move focus in
forward direction
To move focus in
reverse direction
To take action on the
focused widget
To increase the value
selection on specific
widgets like
slider/picker
To decrease the value
selection on specific
widgets like
slider/picker
To scroll up/left of the
content in a scroll
container.
To scroll down/right the
content in a scroll
container
Starts reading from the
beginning of the page
Starts reading from the
current focused item
Android touch
(Android 4.1 and
higher) (talkback)
One finger right/down
flick gesture
One finger left/up flick
gesture
One finger double tap
iOS touch
One finger right flick gesture
One finger left flick gesture
One finger double tap
One finger up flick gesture
One finger up flick gesture
Two/three finger up/left

flick gesture
Three fingers up/right flick gesture
Two/three finger
down/right flick gesture
Three fingers down/right flick gesture

Two fingers up flick gesture
Two fingers down flick gesture
iOS Gestures
Below are some of the gestures explained in the above table:
For more information on accessibility gestures, refer to:

l
Android: https://support.google.com/nexus/answer/2926960?hl=en
iOS: https://www.apple.com/in/accessibility/osx/voiceover/
SPA and Desktop Web: http://www.w3.org/WAI/mobile/
Achieving 508 Compliance Using Kony Studio

The built-in assistive technology in the iOS and Android platforms reads some basic widgets of Kony Studio,
such as Button, Label, and TextBox. The assistive technology in iOS and Android platforms read the
information differently on other widgets.
Every application that is created using Kony Studio is accessible to iOS and Android platforms built-in
assistive technology. The way the assistive technology interprets the widget information is left to its individual
capability. Developers can enhance the behavior of assistive technology with the configuration property
(explained in the next page) available for each accessibility supported widget.
Widget Navigation Model and Tab/Focus Order
The general navigation model is for a user to tab/swipe to reach a widget, interact with the control in that
widget, and then tab/swipe to move focus to the next widget in the tab order. When a container widget
contains a widget, the tab/swipe gesture brings the focus to the container widget because it is the next item in
the tab order. This continues down the layers of widgets until the last widget is reached. For example, we
have two widgets ' HBox ' and ' Button ' on a page. The widget ' HBox ' contains a ' VBox ' widget. Within the '
VBox ' widget there is a ' Label ' widget.
While tabbing, the focus lands on HBox, then another tab will move the focus to VBox, and then another tab
will move the focus to Label. This is because Label is the last widget in VBox focus will not come directly to
the Label. One more tab will move the focus to Button. The order in which the focus is passed from one widget
to another widget is based on the nearest neighboring widget in a given direction.
Note: Some operating systems allow you to change the systems and enlarge all text displayed on the
screen.
42.1 Defining accessibilityConfig for a Widget in Kony Studio

To define accessibilityConfig on a widget from Kony Studio, follow the below steps:
1. From Kony Studio, drag a widget where you want it. For example, a Button widget.
2. Select the Button widget and locate the accessibilityConfig property from the Properties Window.
) button against the property. The Accessibility Config window appears.
4. Enter the following values in the respective fields:

l
a11yLabel:Specifies an alternate text to identify the widget. Generally the label should be the
text that is displayed on the screen.
a11yValue: Specifies the current state/value associated with the widget so that the user can
perform an action. For example, a checkbox is in selected state or unselected state.
a11yHint: Specifies the descriptive text that explains the action about the widget.
a11yHidden: Specifies if the widget must be ignored by assistive technology.
Define accessibilityConfig for a Widget Dynamically

The property accessibilityConfig enables you to specify the accessibility configuration property for a widget.
Following are the predefined keys:
a11yLabel [String] - Optional
Specifies an alternate text to identify the widget. Generally the label should be the text that is
displayed on the screen.
a11yValue [String] - Optional
Specifies the current state/value associated with the widget so that the user can perform an action.
For example, a checkbox is in selected state or unselected state.
Note: On the Android platform, the text specified for a11yLabel is prefixed to the
a11yValue.
a11yHint [String] - Optional

Specifies the descriptive text that explains the action about the widget.
Note: On the Android platform, the text specified for a11yValue is prefixed to
the a11yHint.
a11yHidden [Boolean] - Optional
Specifies if the widget must be ignored by assistive technology. The default option is set to false.
Note: This option is supported on iOS 5.0 and above, Android 4.1 and above,
and SPA.
Limitations
Android:
l
If the results of the concatenation of a11y fields result in an empty string, then the accessibilityConfig
is ignored and the text that is on widget is read out.
The soft keypad does not gain accessibility focus with right/left swipe gesture when the keypad
appears.
SPA: The a11y fields are mapped to the ARIA tags. The results may vary among browsers because not
all browsers recognize all the ARIA tags.
Read / Write
JavaScript Example
//Defining the properties for a button.

FSkin", text:"Click Here", "accessibilityConfig":
{
"a11yHidden": true,
"a11yValue": "Your text goes here",
"a11yLabel": "Your text goes here",
"a11yHint": "Your text goes here"
}};
var btnPSP={};
l
iOS
Android
SPA (iPhone and Android)
42.2 Widget Behavior When Accessibility is Enabled

Here is a sample representation of accessibility on iPhone and Android devices. For example, you have a
Confirm button on form frm1, and the accessibilityConfig is defined as below:
then the assistive technology in the respective platforms will read as follows:
Note: In the above snapshot the highlighted text is role, generated by native platforms. The iPhone
appended the text button to the value, and Android appended the text button to the hint automatically. Kony
Studio has no control on this behavior. Developers should test the text that is provided for
accessibilityConfig.
42.3 Container Widgets

Below are the platforms behaviors for the container widgets when the accessibility feature is enabled.
l
Form
HBox
VBox
ScrollBox
Popup
42.3.1 Form
Keyboard/Gesture-based
Interactions
Tab key or equivalent touch gesture moves the focus to the first
focusable child widget of the form.
Multiple tabs move the focus to the interactive child widgets of the
form.
The title of the form is accessible in the platforms that support native
form widget titleBar property using the tab key or equivalent touch
gesture along tab order.
The a11yLabel overrides the text of the title property.
The a11yValue, a11yHint, and a11yHidden fields are not applicable to

form and are ignored.
accessibilityConfig property is supported in iPhone, Android, and SPAiPhone platforms.
Default Behavior
iOS:
l
When the VoiceOver focus reaches the bottom of the form, it does not
cycle to the top of the form again, with a right swipe gesture. Similarly,
with a left swipe gesture, the focus does not cycle to the bottom of the
form when you have reached the top of the form.
The iOS VoiceOver, focus the first accessible widget available on the
form.
Android:
l
onTap gesture on a form, when there are no focusable widgets, the

assistive technology reads all non-focusable widgets text available in
the form.
In Android OS versions less than 4.2, form does not scroll, although it
has content to scroll. You have to enable an option in Android OS
versions 4.2 and above in system accessibility settings to auto scroll
the content on swipe gesture.
Accessibility capability of the ActionBar is left to the device default

behavior.
Limitations
SPA:
l
SPA-iPhone: When the VoiceOver focus reaches the bottom of the

form, it does not cycle to the top of the form again, with a right swipe
gesture. Similarly, with a left swipe gesture, the focus does not cycle
to the bottom of the form when you have reached the top of the form.
SPA-Android: accessibilityconfig is not supported
Tab key or equivalent touch gesture moves the focus along the tab
order when:
42.3.2 HBox
a. Box is clickable
b. accessibilityConfig is defined.
Keyboard/Gesture based
Interactions
Default Behavior
With a focus on the HBox, press Spacebar or Enter or equivalent

gesture action to select the HBox when it is clickable.
Multiple tabs or navigation keys help in navigating focus to the child

widgets that are actionable.
accessibilityConfig property is supported in iPhone, Android, and SPA

platforms.
iOS:
l
If the accessibilityConfig is set for an HBox, then the focus never goes
to its child widgets and other widgets within the HBox are not
accessible to the user.
Android: None
SPA:
Limitations
l
SPA-iPhone: If the accessibilityConfig is set for an HBox, then the

focus never goes to its child widgets, and other widgets within the
HBox are not accessible to the user.
SPA-Android: If the accessibilityConfig is set for an HBox, then

widgets within the HBox are not accessible to the user with a swipe
gesture. But when touched explicitly the widgets gain focus. The
option a11yHint is not supported.
order when:
42.3.3 VBox
a. Box is clickable.
b. accessibilityConfig is defined.
Interactions
Default Behavior
With a focus on the VBox, press Space or Enter or equivalent gesture

action to select the VBox when it is clickable.


platforms.
iOS:
l
If the accessibilityConfig is set for a VBox, then the focus never goes
to its child widgets and other widgets within the VBox.
Android: None
SPA:
Limitations
SPA-iPhone: If the accessibilityConfig is set for a VBox, then the

focus will never go to its child widgets, and other widgets within the
VBox are not accessible to the user.
SPA-Android: If the accessibilityConfig is set for a VBox, then widgets

within the VBox are not accessible to the user with a swipe gesture.
But when touched explicitly the widgets gain focus. The option
a11yHint is not supported.
order when accessibilityConfig is defined.

Page Up / Page Down or equivalent key/gesture allows you to scroll

the content of the ScrollBox.
42.3.4 ScrollBox
Interactions
Default Behavior

platforms.
iOS:
l
If the accessibilityConfig is set for a ScrollBox, then the focus never

goes to its child widgets, and other widgets within the ScrollBox are
not accessible to the user.
Android: In Android OS versions less than 4.2, the form does not scroll
although it has content to scroll. It depends on the capability of the built-in
Accessibility service. You have to enable an option in Android OS versions
4.2 and above in the system accessibility settings to auto-scroll the content
on swipe gesture. Similar behavior is observed with native applications as
well.
When the scrollDirection property is set to SCROLLBOX_SCROLL_BOTH,
the behavior is undefined.
Limitations
SPA: When a user scrolls through the Scrollbox, it does not scroll and the
widgets are not displayed in the view port, even if you set accessibility. This
is due to the inability of the browsers to detect the touch gestures. But the
widgets within Scrollbox are navigated and accessibility of the widget is read
out.
l
SPA-iPhone: If the accessibilityConfig is set for a ScrollBox, then

widgets within the ScrollBox are not accessible to the user.
SPA-Android: If the accessibilityConfig is set for a ScrollBox, then

widgets within the ScrollBox are not accessible to the user with a
swipe gesture. But when touched explicitly the widgets gain focus.
The option a11yHint is not supported.
Tab key or equivalent touch gesture moves the focus to the first
focusable child widget of the Popup.
Multiple tabs move the focus to the interactive child widgets of the
Popup.
The a11yLabel overrides the text of the title property.
42.3.5 Popup
Interactions
l
l
The a11yValue, a11yHint, and a11yHidden fields are not applicable to

Popup and are ignored.
accessibilityConfig property is supported in iPhone, Android, and SPAiPhone platforms.
Default Behavior
iOS:
l
When the VoiceOver focus reaches the bottom of the Popup, it does
not cycle to the top of the Popup again, with a right swipe gesture.
Similarly with a left swipe gesture, the focus does not cycle to the
bottom of the Popup when you have reached the top of the Popup.
Android:
l
When there are no focusable widgets in a Popup, the assistive

technology reads all non-focusable widgets text available in the Popup.
In Android OS versions less than 4.3, the Popup does not scroll
although it has more content to scroll. It is the capability of the built-in
Accessibility service (TalkBack) that is lacking in versions less than
4.3 OS versions. You have to enable an option in Accessibility settings
in 4.3 and 4.4 Android OS versions to auto-scroll the content on a
swipe gesture.
Limitations
SPA:
l
SPA-iPhone: When the VoiceOver focus reaches the bottom of the

Popup, it does not cycle to the top of the Popup again, with a right
swipe gesture. Similarly, with a left swipe gesture, the focus does not
cycle to the bottom of the Popup when you have reached the top of the
Popup.
SPA-Android: accessibilityConfig is not supported.
42.4 Basic Widgets

Below are the platforms behaviors of the basic widgets when accessibility feature is enabled.
l
Button
Calendar
CheckBox
ComboBox
Image
Label
Line
Link
ListBox
RadioButton
RichText
Slider
TextArea
TextBox
42.4.1 Button
Interactions
Default Behavior
With a focus on the Button, press the Spacebar or Enter key or

equivalent gesture action to select the Button.
Single finger double tap to execute the action.
Accessible by the tab key or equivalent touch gesture along tab order.

platforms.
iOS: None
Android: None
Limitations
SPA:
l
SPA-iPhone: None
SPA-Android: The option a11yHint is not supported.
42.4.2 Calendar
A Calendar widget accepts dates from the user. Following are the view types
that support accessibility in respective platforms:
Description
CALENDAR_VIEW_TYPE_DEFAULT (Android)
CALENDAR_VIEW_TYPE_WHEEL_POPUP (iPhone)
CALENDAR_VIEW_TYPE_ GRID_POPUP (iPhone and SPA)

Interactions
Default Behavior
With a focus on the Calendar, press the Spacebar or Enter key or

equivalent gesture action to launch the date selector.
You can reach to each available day, month, and year in a calendar
through one/some of the keys or touch gestures.

platforms.
a11yValue is not applicable.
It is recommended to provide accessibility text to the assistive

technology to read the date when the tab focus/gesture makes a
selection.
accessibilityConfig is not supported for the viewTypes that are not

focused as a whole.
Multiple tabs or navigation keys help in navigating the focus to each

check button in the group.
With a focus on the CheckBox, press the Spacebar or Enter key or

equivalent gesture to change the selection state of the focused check
button.

platforms.
Limitations
42.4.3 CheckBox
Interactions
Default Behavior
iOS: Following are the limitations of iOS platform based on the selected
viewType:
viewType
accessibilityConfig
Widget Level
CHECKBOX_VIEW_TYPE_LISTVIEW
CHECKBOX_VIEW_TYPE_TOGGLEVIEW
CHECKBOX_VIEW_TYPE_
ONSCREENWHEEL
CHECKBOX_VIEW_TYPE_TABLEVIEW
Respected
Items within
widget
Ignored
Ignored
Respected
Ignored
Ignored
Ignored
Respected
* accessibilityConfig is ignored when set through masterData or

Limitations
masterDataMap to the items within the widget that pops up as pickerview

from the bottom.
Android: None
SPA:
Example code
SPA-iPhone: accessibilityConfig for CheckBox as a whole is not

respected, but the items within the widget are respected. The
CheckBox state and the item text gets the focus separately.
SPA-Android: accessibilityConfig for CheckBox as a whole is not

respected, but the items within the widget are respected. The
CheckBox state and the item text get the focus separately. The option
Click here to view the sample code
42.4.4 ComboBox
Interactions
Default Behavior
Tab key or equivalent touch gesture along tab order.
With a focus on the ComboBox, press the Spacebar or Enter key or

equivalent gesture action to open the drop-down list.
With drop-down list in an expanded state, press the Spacebar or Enter

key or equivalent gesture to select the focused item.

item in the ComboBox.

platforms.
viewType:
viewType
accessibilityConfig
Widget Level
COMBOBOX_VIEW_TYPE_LISTVIEW
COMBOBOX_VIEW_TYPE_TABLEVIEW
COMBOBOX_VIEW_TYPE_TOGGLEVIEW
COMBOBOX_VIEW_TYPE_
ONSCREENWHEEL
Respected
Items Within
Widget
Ignored
Ignored
Ignored
Respected
Respected
Ignored
Ignored

masterDataMap to the items within the widget that pops up as pickerview from
the bottom.
Limitations
Android: If the accessibilityConfig is set, it will override the selected item.
SPA:
Example code
SPA-iPhone: The ComboBox widget is mapped to the HTML

ComboBox, and browsers launch the list items as native popup.
Accessibility configuration working for the list items cannot be
controlled by Kony Platform. Accessibility is not supported for the items
of the ComboBox widget.
SPA-Android:The ComboBox widget is mapped to the HTML

ComboBox, and browsers launch the list items as native popup.
Accessibility configuration working for the list items cannot be
controlled by Kony Platform. Accessibility is not supported for the items
of the ComboBox widget.
42.4.5 Image
Interactions
Default Behavior

platforms.
On all platforms, except SPA, if the accessibility is not configured, the image
widget is not accessible to the user.
Limitations
42.4.6 Label
Description
Interactions
Default Behavior
A Label widget is used to display non-editable text to the user.
accessibilityConfig property is supported in iPhone, Android, and SPAAndroid platforms.
iOS: None
Android: None
Limitations
SPA:
l
SPA-iPhone: accessibilityConfig property is not supported.
SPA-Android:The option a11yHint is not supported
42.4.7 Line
Interactions
Not accessible by the tab key or equivalent touch gesture.
Default Behavior
accessibilityConfig property is not supported.
Limitations
None
42.4.8 Link
Interactions
Default Behavior
With a focus on the link, press the Spacebar or Enter key or equivalent
gesture action to select the link.

platforms.
iOS: None
Android: None
Limitations
SPA:
l
SPA-iPhone: None
With a focus on the ListBox, press the Spacebar or Enter key or

equivalent gesture to open the drop-down list.
With drop-down list in an expanded state, press the Spacebar or Enter

key or equivalent gesture to select the focused item.

item in the ListBox.

platforms.
42.4.9 ListBox
Interactions
Default Behavior
viewType:
viewType
accessibilityConfig
Widget Level
LISTBOX_VIEW_TYPE_LISTVIEW
LISTBOX_VIEW_TYPE_TABLEVIEW
LISTBOX_VIEW_TYPE_TOGGLEVIEW
LISTBOX_VIEW_TYPE_
ONSCREENWHEEL
Supported
Items Within
Widget
Ignored
Ignored
Ignored
Supported
Supported
Ignored
Ignored

from the bottom.
Limitations
Android: If the accessibilityConfig is set, it will override the selected item.
SPA:
Example code
SPA-iPhone: The ListBox widget is mapped to the HTML ListBox, and

browsers launch the list items as native popup. Accessibility
configuration working for the list items cannot be controlled by Kony
Platform. Accessibility is not supported for the items of the ListBox
widget.
SPA-Android:The ListBox widget is mapped to the HTML ListBox and

browsers launch the list items as native popup. Accessibility
configuration working for the list items cannot be controlled by Kony
Platform. Accessibility is not supported for the items of the ListBox
widget. The option a11yHint is not supported.
42.4.10 RadioButton
Interactions
Default Behavior
With a focus on the RadioButton, press the Spacebar or Enter key or

equivalent gesture to change the selection state of the focused item.

item in the RadioButton.

platforms.
iOS: Following are the limitations of the iOS platform based on the selected
viewType:
viewType
accessibilityConfig
Widget Level
RADIOGROUP_VIEW_TYPE_LISTVIEW
RADIOGROUP_VIEW_TYPE_
TABLEVIEW
TOGGLEVIEW
ONSCREENWHEEL
Limitations
Supported
Items Within
Widget
Ignored
Ignored
Supported
Ignored
Supported
Ignored
Ignored
accessibilityConfig is ignored when set through masterData or

from the bottom is ignored.
Android: None
SPA:
Example code
SPA-iPhone: accessibilityConfig for RadioButton as a whole is not

supported, but the items within the widget are supported.
SPA-Android: accessibilityConfig for RadioButton as a whole is not

supported, but the items within the widget are supported. The option
42.4.11 RichText
Interactions
Default Behavior

platforms.
On all platforms, links inside a RichText widget are not accessible.

Limitations
42.4.12 Slider
l
Interactions
With a focus on the Slider, press the Right / Up key or equivalent

gesture to increase the value of the slider. Press the Left / Down key or
equivalent gesture to decrease the value of the slider.
Default Behavior

platforms.
Android: Android OS cannot change the slider value when accessibility is set.
SPA:
Limitations
SPA-iPhone: Browsers cannot change the slider value when

accessibility is set.
SPA-Android: Browsers cannot change the slider value when

accessibility is set.
With a focus on the TextArea, press the Spacebar or equivalent

gesture to open the soft keypad for touch devices.
Soft keypad gains focus on explicit touch on the soft keypad.
42.4.13 TextArea
Interactions
Default Behavior

platforms.
iOS: None
Android: When the accessibilityConfig is defined for placeholder or entered
text, then behavior is left to the device.
Limitations
SPA:
l
SPA-iPhone: None
42.4.14 TextBox
Interactions
With a focus on the TextBox, press the Spacebar or equivalent gesture

to open the soft keypad for touch devices.
Soft keypad gains focus on explicit touch on the soft keypad.

platforms.
Default Behavior
Note: To configure the clear text button, use the property

accessibilityConfigForClearButton and the keys are same as that of
accessibilityConfig. This is applicable to iOS platform only
iOS: None
Android: When the accessibilityConfig is defined for placeholder or entered
text, then behavior is left to the device.
Limitations
SPA:
l
SPA-iPhone: None
42.5 Advanced Widgets

Below are the behaviors of the advanced widgets when the accessibility feature is enabled.
l
Alert
Camera
Hz Image Strip
PickerView
SegmentedUI
Switch
42.5.1 Alert
Description
An Alert is a dialog displayed to show an alert message.
Interactions
Touch gesture: Single finger double tap.
Accessible by the tab key or equivalent touch gesture to navigate and

focus on the buttons and messages of the Alert dialog box.
With a focus on the Alert button, press the Enter or Spacebar or

equivalent gesture to select the button.
By default, Alerts should gain focus as Alert displays.
Default Behavior
accessibilityConfig is not supported.
Limitations
On all platforms, the buttons within the Alert dialog are not configurable.
42.5.2 Camera
l
Interactions
With a focus on the camera, press the Enter or Spacebar or equivalent

gesture to launch the camera.
Default Behavior
accessibilityConfig property is supported in iPhone and Android

platforms.
Limitations
accessibilityConfig property is not supported in SPA platform
42.5.3 Hz Image Strip
Interactions
Default Behavior
On multiple tabs or equivalent touch gesture, move the focus to the

images where accessibility is configured and visible on the screen.
Images that are not visible are scrolled automatically to a visible region
on a tab or equivalent gesture.

platforms.
If the entire image strip widget is not focused as a whole, then the
accessibilityConfig is not respected in any of the platform. The
accessibilityConfig is supported only when the viewType is set to
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_STRIPVIEW.
iOS:For the viewType when set to HORIZONTAL_IMAGESTRIP_VIEW_
TYPE_STRIPVIEW, accessibility is ignored. But the accessibility configured
for each image is supported. Accessibility is not available for all other
viewtypes.
Limitations
Android: In Android OS versions less than 4.2, Horizontal Image Strip does
not scroll though it has content to scroll. It depends on the capability of the
built-in accessibility service. You must enable an option in Android OS
versions greater than equal to 4.2 in system accessibility settings to auto
scroll the content on swipe gesture. You will observe similar behavior with
native applications as well.
SPA:
Example code
SPA-iPhone: If the accessibilityConfig is set for a Horizontal Image

Strip, then widgets within the Horizontal Image Strip are not accessible
to the user.
SPA-Android: If the accessibilityConfig is set for a Horizontal Image

Strip, then widgets within the Horizontal Image Strip are not accessible
to the user with a swipe gesture. But when touched explicitly the
widgets gain focus. The option a11yHint is not supported.
sample code
42.5.4 PickerView
Interactions
Every column in the PickerView is reachable by the tab key or

equivalent touch gesture.
With a focus on the PickerView, press the Right / Up key or Left /

Down key or equivalent gesture to allow navigation between items in
the focused column.
With a focus on the PickerView, press the Enter or Spacebar or

equivalent gesture to select the focused item in the PickerView.
accessibilityConfig property is supported in Android platforms.
Default Behavior
iOS: accessibilityConfig is not supported
Limitations
Example code
Android: In Android OS versions less than 4.2, SegmentedUI does not scroll
though it has content to scroll. It depends on the capability of the built-in
accessibility service. You must enable an option in Android OS versions
greater than equal to 4.2 in system accessibility settings to auto-scroll the
content on a swipe gesture. You will observe similar behavior with native
applications as well.
sample code
42.5.5 SegmentedUI - TABLEVIEW

Description
A SegmentedUI is a container widget to display multiple rows of information in

vertical order.
l
Accessible by the tab key or equivalent touch gesture along the tab
order moves the focus to the first row.
If the first row is a section header, then the subsequent tabs move the
focus to the interactive child widgets. If there are no child widgets or
interactive widgets, or all child widgets are reached, the tab moves the
focus to the next row until it reaches the last visible row.
In SINGLE_SELECT_MODE or MULTI_SELECT_MODE, as the row

gets the focus through the tab, underlying accessibility technology
conveys the user as either selected/unselected.
At widget level, accessibilityConfig property is not supported in
iPhone, Android, and SPA platforms because it is not focusable
completely. Accessibility is supported only for the individual rows
because they are focused completely.
Interactions
accessibilityConfig is applied to the row template, and then

accessibility is applied to each row, unless overridden by the row data.
Row template's accessibility configurations can be modified before

setting the row data to the SegmentedUI and should not be modified
after data are set.
Default Behavior
iOS: If the accessibilityConfig is set to a row of a SegmentedUI, then

actionable child widgets of the row become inaccessible.
though it has content to scroll. You must enable an option in Android OS
versions 4.2 and above system accessibility settings to auto-scroll the
content on a swipe gesture. You will observe similar behavior with native
applications.
Limitations
Example code
SPA:
l
SPA-iPhone: If the accessibilityConfig is set to a row of a

SegmentedUI, then actionable child widgets of the row become
inaccessible.
SPA-Android: If the accessibilityConfig is set to a row of a

inaccessible. But when touched explicitly the widgets gain focus with
a swipe gesture. The option a11yHint is not supported.
sample code
42.5.6 SegmentedUI - PAGEVIEW

Description
Interactions
A SegmentedUI is a container widget to display multiple rows of information in

horizontal layout with a single row appearing on the widget.
l
If the first row is a section header, then the subsequent tabs move the
focus to the interactive child widgets. If there are no child widgets or
interactive widgets, or all child widgets are reached, the tab moves the
focus out of the widget.
If there are page indicators at the bottom of the PAGEVIEW and the
page indicators are interactive, the tab focus each page and pass the
index of the total page information to the assistive technology.
In SINGLE_SELECT_MODE or MULTI_SELECT_MODE, as the row

gets the focus through the tab, underlying assistive technology
conveys the user as either selected/unselected.
At widget level accessibilityConfig property is not respected. It is
respected only for the page level in iPhone, Android, and SPA
platforms.
accessibilityConfig applied to the row template and its internal widgets

are applied to each row, unless overridden by the row data.
Row template's accessibility configurations can be modified before

setting the row data to the SegmentedUI and should not be modified
after data are set.
Default Behavior
On all platforms, accessibilityConfig is not supported for page indicators.

iOS: If the accessibilityConfig is set to a row of a SegmentedUI, then
actionable child widgets of the row become inaccessible.
Limitations
though it has content to scroll. It depends on the capability of the built-in
accessibility service. You must enable an option in Android OS versions 4.2
and above, in system accessibility settings to auto-scroll the content on a
swipe gesture. You will observe similar behavior with native applications as
well.
SPA: The event onRowClick is fired when any child widget is explicitly
selected or clicked.
l
SPA-iPhone: If the accessibilityConfig is set to a row of a

inaccessible.
SPA-Android: If the accessibilityConfig is set to a row of a

inaccessible. But when touched explicitly the widget's gain focus. The
option a11yHint is not supported.
With a focus on the Switch, press the Enter key or Spacebar or

equivalent gesture to toggle the state and initiate the action.
accessibilityConfig property is supported in iPhone and SPA

platforms.
42.5.7 Switch
Interactions
Default Behavior
iOS: None
SPA:
Limitations
l
SPA-iPhone: None
42.6 Accessibility Best Practices

To read the best practices of accessibility, refer to WebAccessibility.
42.7 Accessibility:Platform Specific Limitations

This section lists the accessibility limitations of SPA platforms.
42.7.1 SPA
This section lists the accessibility limitations of SPA platforms.
1. Scrolling a form and SegmentedUI through a swipe with three fingers and tab gestures (custom scroll)
is not supported in SPA platform.
2. When a Popup is loaded, the default focus goes to the form on which the Popup is loaded, and then it
comes to Popup.
3. A Label widget without any text is not focusable with tab gestures.
4. When a form is loaded, the default focus can be any where in the form.
5. For the widgets such as ScrollBox, Horizontal Image Strip, Slider, and Segment (PAGEVIEW), a
swipe or tab gesture will not bring the focused item into a view area.
6. On the SPA Android platform, accessibiltiyConfig for form and Popup is not supported.
7. On the SPA Android platform, before loading a form, some random text is read by assistive technology.
The random text is read from the script tag that may be present in JavaScript.
8. For container widgets, if only a11yHint is configured, then accessibility first reads the text of the child
widgets and then a11yHint text that is configured for a container widget.
43. Widget Level Animation

Note: Widget level animation is supported only in iOS (version 5.0 and above) and Android (version 3.0 and
above) platforms only.
Animation feature allows you to animate widgets on a Form, HBox, VBox to add a widget, remove a widget,
replace a widget with other widget, and set the visibility of a widget with animation. Following are the widgets
in which the animations are supported using the respective methods:
setVisibility
addAt
removeAt
replaceAt
layoutAnimConfig
Form
HBox
VBox
Button
Label
Image
Calendar
SegmentedUI
addAt: This method is used to add widgets to the container at the specified index.
removeAt:This method removes a widget at the given index from the container.
replaceAt:This method replaces a widget with another widget in the container.
setVisibility: This method is used to set the visibility of the widget.
layoutAnimConfig: This property is used to configure the layout changes that occur due to the
animations applied/removed on other widgets.
The above methods except layoutAnimConfig property are documented in methods sections of the respective
widgets.
Where and How to Use Animations
The animations are used to:
l
Add or remove a widget during an action in an application.
Replace a widget with another widget.
Set the visibility based on need of the application design.
The animations are handled through animation configuration object. It is an optional parameter for the methods
mentioned in the above table. The methods mentioned in the above table accept animationConfig as optional
parameter in iOS and Android platforms. All other platforms do not support this parameter.
The animation configuration object contain the below parameters:
l
animEffect
animDuration
animDelay
animCurve
animCallBacks
43.1 Layout Animation

Layout Animation property is used to configure the layout changes that occur due to the animations
applied/removed on other widgets. For example, on a Form when the visibility of the Button widget is set to
false, all the widgets placed below the Button widget should move up with an animation.The
layoutAnimConfig is the property that helps you to animate the layout changes.
The layoutAnimconfig property is supported on the following widgets:
Note: This property is respected by iOS platform only.
l
Form
HBox
VBox
Button
Label
Image
Calendar
SegmentedUI
The signature and properties of the layoutAnimConfig property are as follows:
Signature
layoutAnimConfig (JSObject)
l
constants.ANIMATION_PLATFORM_DEFAULT: Specifies the widget

must use the platforms default animation for all the layout changes that
occur on a widget. This constant can only be used while specifying layout
animation configuration.

Note: Using any constants other than the ones explained above may
lead to undefined behavior.
l
constants.ANIMATION_CURVE_EASEIN:This option specifies the

animation effect to start slow in the beginning.
constants.ANIMATION_CURVE_EASEOUT: This option specifies the

animation effect to slowdown towards the end.
constants.ANIMATION_CURVE_EASEINOUT:This option specifies the

animation effect to start slow and slowdown towards the end.
constants.ANIMATION_CURVE_LINEAR:This is the default value. It

specifies the animation effect to continue with the same speed from start
to end.
l


JavaScript Example
{
"animEffect":constants.ANIMATION_PLATFORM_DEFAULT,
"animDuration":2,
"animDelay":3,
}
formObj.layoutAnimConfig = withAnimConfig3;
//To remove animation you can set as below
box.Obj.layoutAnimConfig = {
"animEffect"=constants.ANIMATION_EFFECT_NONE
};
Inheritance of layout animations

If the layoutAnimConfig is not configured for the above widgets, will get inherited from the parent widget. If the
parent widget also not configured then the search continues through parent hierarchy until layoutAnimConfig
is found that can be used or Form widget is reached in the heirarchy.
If the layoutAnimConfig is not configured at the widget or cannot be inherited from the parent hierarchy then
layout changes will be animated with the below defaults:
l
animEffect: The default option is set to constants.ANIMATION_EFFECT_NONE

Note: You can configure layout animation effect as either constants.ANIMATION_PLATFORM_
DEFAULT or constants.ANIMATION_EFFECT_NONE, other animation effects will lead to
undefined behavior.
animDuration: The default option is set to 1 second.
animDelay: The default option is set to 0 seconds.
animCurve:The default option is set to constants.ANIMATION_CURVE_LINEAR
43.2 Animation Limitations

This section provides the knows limitations of animations:
Animation callbacks are expected to be light weight and avoid calling heavy end operations such as
network calls, SQL Lite, etc.
Animations are played only on the form to which the widget belongs are rendered and currently
displayed on the form. Invoking animations on a widget whose form is not yet shown/rendered doesn't
reflect the animations.
Touching a widget, when an animation is in progress may lead to undefined behavior.
The animation effect constants.ANIMATION_PLATFORM_DEFAULT is not respected when used in

animation configuration while invoking an operation.
Layout animation configuration specified is not respected by Android. By default Android always plays
the default animations native to android for all other widgets, which go through animation due to an
operation on a widget.
Animations that child widgets go through (due to layout animation configuration) are undefined when an
operation such as addAt, removeAt, and replaceAt are invoked with an animation configuration on a
parent widget. For proper animations:
You must add parent widget and then child widget with animation.
If you remove some widgets, then remove the child widgets first with animation and then the
parent widget.
If you replace a widget using replaceAt method, do not make layoutAnimConfig applicable for
the new widget to avoid unwanted animations.
Animation behavior when the properties of widgets in the same closure where an operation on a widget
is invoked with an animation:
l
If properties of the same widget (on which operation is invoked) are modified even these
property changes also go through animation configuration specified while invoking the
operation. It is one animation where the operation will be animated along with the property
changes.
If properties of different widgets (widgets other than the one on which operation is invoked) are
modified then these property changes go through animation configuration specified in layout
animation configuration.
When there is no change in the state of the widget or parent widget after cumulative set of operations in
the closure, then the animations are not played including callbacks. For example, when a widget is
removed and added in the same closure with animation at the same location in the widget hierarchy,
then there is no change in the widgets, hence the widget will not go through any animation.
Note: In Android platform, you may observe intermittent animations for a fraction of second including
the callbacks for each of the operations invoked with animation in the closure.
44. Appendix A: Layout

A layout defines the position of content presented within an application screen. A layout can include one or
more container widgets, which in turn hold component widgets.
This chapter describes the behavior of container and component widgets when different properties of the
widget are enabled or disabled.
44.1 HBox Behavior

The behavior of a Box is governed by the property containerWeight and you must be aware of the
following characteristics:
l
An HBox can be placed within a Form, Vbox, Tabpane, a Segment or a ScrollBox

(only if the orientation is vertical).
An HBox supports three levels of nesting.
If percent is true, the HBox exhibits the following width characteristics:

l
The width allocated to the child widget is dependent on the percentage allocated size
(container weight) of the widget.
The actual width occupied by the widget is determined by the content of the widget
and the Expand horizontal property.
If percent property is false, the HBox exhibits the following width characteristics:
l
The width of the widget is determined by its preferred width.
The widget lay out direction set for a box does not work for Windows Mobile Web.
The HBox exhibits the following height characteristics (the containerWeight property does not matter):
l
If an HBox contains multiple child widgets with varying heights, the height of the
child widget with the maximum height is set as the height of the HBox.
If a background image is specified (as part of the normal skin) for the HBox, and if
the height of the child widgets is lesser than the height of the background image, the
height of the HBox will be the height of the image.
44.1.1 Scenario 1 (General Layout)

Create an HBox with a width of 200 px and add five buttons (Button1, Button2, Button3, Button4, and
Button5) with container weights of 20 each. Depending upon the properties set for the HBox
(containerWeight) and for the individual buttons (Expand horizontal and vertical), the layout varies.
Properties
Set the following property values for the HBox, Button1, Button2, Button3, Button4, and Button5:
HBox:
HBox width: 200 px
Use Widget Size %: true
Button1:
hExpand: false
vExpand: false
Allocated width: 40 px (20% of 200)
Text to be displayed: Kony

Width required to display the text 'Kony' (preferred width): 20 px
Height required to display the text 'Kony' (preferred height): 40 px
Button2:
hExpand: true
vExpand: false
Button3:
hExpand: false
vExpand: true
Button4:
Expand horizontal: true
Expand vertical: true
Button5:
hExpand: false
vExpand: true
Text to be displayed: Kony Solutions

Width required to display the text 'Kony Solutions' (preferred width): 60 px
Height required to display the text 'Kony Solutions' (preferred height): 80 px
Layout
The layout with the above properties appears as follows:
Explanation:
Button1
Width: The width occupied is 20 px (preferred width) and not 40 px (allocated width) as the
hExpand property is set to false and horizontal expansion is not allowed.
Height: The height occupied is 40 px (preferred height) and not 80 px (height of the HBox) as the
vExpand property is set to false and vertical expansion is not possible.
Button2
Width: The width occupied is 40 px (allocated width) and not 20 px (preferred width) as the
hExpand property is set to true and horizontal expansion is allowed.
Height: The height occupied is 40 px (preferred height) and not that of the HBox (80 px) as the
vExpand property is set to false and vertical expansion is not possible.
Note: Button2 does not begin immediately after Button1. This is because the Use Widget Size %
property of the HBox is set to true.
Button3
Width: The width occupied is 20 px (preferred width) and not 40 px (allocated width) as the
hExpand property is set to false and horizontal expansion is not allowed.
Height: The height occupied is 80 px (HBox height) and not 40 px (preferred height) as the
vExpand property is set to true and vertical expansion is possible.
Button4
Width: The width occupied is 40 px (allocated width) and not 20 px (preferred width) as hExpand
property is set to true and horizontal expansion is allowed.
Height: The height occupied is 80 px (HBox height) and not 40 px (preferred height) as vExpand
property is set to true and vertical expansion is possible.
Button5
Width: The width occupied is 40 px (allocated width) and not 60 px (preferred width) even
though the hExpand property is set to false.
This is because when the required width is more than the allocated width, the widget always
occupies the complete allocated width irrespective of the Expand property setting and wraps the
text to the next line.
Height: The height occupied is 80 px (preferred height).
HBox
Width: The width occupied is 200 px (container weight)
Height: The height occupied is 80 px.
If there are multiple child widgets with varying heights, the height of the child widget with the
maximum height is set as the height for the HBox.
Here, Button5 has the maximum height. So, the height of Button5 is set as the height of the
HBox.
44.1.2 Scenario 2 (Alignment)

Create an HBox with a width 100 px and add two widgets (Label1and Button1) with container weights of
50 and 50 respectively, the following use cases are applicable:
Use Case 1
Set the following property values for the HBox, Label1, and Button1:
HBox:
HBox width: 100 px
Label1
hExpand: true
vExpand: true
Text to be displayed: Large text (enter any text which wraps to four lines)
Height required to display the text (preferred height): 80 px
Button1:
hExpand: false
vExpand: false
Text to be displayed: Hi
Width required to display the text 'Hi' (preferred width): 20 px
Height required to display the text 'Hi' (preferred height): 30 px
Layout
Explanation
The height of the HBox is the height of the child widget with the maximum height. Here Label1 has the
maximum height, and so, the height of Label1 is set as the height of the HBox.
This means that the width and height available to Button1 are 50 px and 80 px respectively.
However, as the Expand horizontal and vertical properties for Button1 are false, Button1 occupies a
width of 20 px (preferred width) and a height of 30 px (preferred height) respectively. This gives an
opportunity for Button1 to be aligned in the directions specified by the layoutAlignment property.
Use Case 2
HBox:
HBox width: 100 px
Label1
hExpand: true
vExpand: true

Button1:
hExpand: true
vExpand: false
Layout
Explanation
The height of the HBox is the height of the child widget with the maximum height. Here, Label1 has the
This means that the width and height available for Button1 are 50 px and 80 px respectively.
For Button1, as the Expand horizontal property is set to true, it occupies a width of 50 px (allocated
width).
As the Expand vertical property is set to false, Button1 occupies a height of 30 px (preferred height).
Hence alignment is possible only in the vertical direction.
Use Case 3
Set the following property values for HBox, Label1, and Button1:
HBox:
HBox width: 100 px
Label1
hExpand: true
vExpand: true
Button1:
hExpand: false
vExpand: true
Layout
Explanation
The height of the HBox is the height of the child widget with the maximum height. Here, Label1 has the
For Button1, as the Expand vertical property is set to true, it occupies the entire available height of 80 px
and not 30 px (preferred height). Hence the alignment is possible only in the horizontal direction.
Use Case 4
HBox:
HBox width: 100 px
Label1
hExpand: true
vExpand: true
Button1:
hExpand: true
vExpand: true
Layout
Explanation
The height of the HBox is the height of the child widget with the maximum height. Here Label1 has the
However, as the Expand horizontal and vertical properties for Button1 are true, Button1 occupies the
complete available width and height and cannot be aligned in any direction.
44.2 VBox Behavior

A VBox has the following characteristics:
l
A VBox cannot be placed directly onto a form.
A VBox cannot be placed within another VBox.
The width of a widget in a VBox is the width of the VBox.
The height of a VBox is the cumulative height of the child widgets.
The Expand vertical property is not applicable for widgets inside a VBox.
Based on the above characteristics of a VBox, the following section lists a possible Scenario and Use Cases
for a VBox:
44.2.1 Scenario 1
Create a VBox of width 100 px and add two buttons (Button1 and Button2) with container weights of 50 and
50 respectively, consider the following cases:
Use Case 1
Set the following property values for the VBox and Button1:
VBox:
VBox width: 100 px
Button1:
Expand horizontal: false
Allocated width: 100 px
Text to be displayed: Hello
Width required to display the text 'Hello' (preferred width): 40 px
Height required to display the text 'Hello' (preferred height): 30 px
Layout
Explanation:
For Button1, as the Expand horizontal property is set to false, it occupies a width of 40 px (preferred
width) and not 100 px (allocated width), and occupies a height of 30 px (preferred height). However,
Button1 can be aligned in the left, center, and right direction of the allocated space.
Use Case 2
VBox:
VBox width: 100 px
Button1:
Expand horizontal: true
Text to be displayed: Hello
Width required to display the text 'Hello' (preferred width): 40 px
Height required to display the text 'Hello' (preferred height): 30 px
Layout
Behavior:
Button1 occupies the allocated width (100 px) and the height is the preferred height (30 px).
Explanation:
As the Expand horizontal property is set to true, the widget occupies a width of 100 px (allocated width)
and not 40 px (preferred width) because the horizontal expansion is allowed.
The height occupied is 30 px (preferred height).
Use Case 3
VBox:
VBox width: 100 px
Button1:
Expand horizontal: false
Text to be displayed: Good Morning World
Width required to display the text 'Good Morning World' (preferred width): 120 px
Height required to display the text 'Good Morning World' (preferred height): 40 px
Layout
Behavior:
Button2 occupies the allocated width (100 px) and wraps the text to the next line and has an height of 80
px.
Reason
When the required width is more than the allocated width, the widget always occupies the complete
allocated width irrespective of the Expand property setting and wraps the text to the next line.
Here, Button1 occupies a width of 100 px (allocated width). and wraps the text to the next line, and has
an height of 80 px.
As the height of the VBox is dependent on the content, and in this use case, the text is wrapped to the
next line, this results in a corresponding increase in height.
Here Button1 occupies a height of 80 px.
45. Appendix B: Platform Specific Limitations

This section lists the limitations, properties or the widgets not supported by platforms.
45.1 DesktopWeb Limitations

This section lists the properties that are not supported by the Desktop Web platform.
1. ComboBox and ListBox, skin styles "Transparent" and "One Color" are supported in background color
tab.
2. ComboBox and ListBox, browser does not support if the properties defined in font tab and border are
3. On Firefox browser, TextBox and TextArea widgets does not support percentage (%) based padding,
while other browsers does support.
4. For all widgets in Internet Explorer 7 and 8, transparency (border/font) is not supported for skin.
5. On safari browser, ListBox and ComboBox widgets does not support padding.
6. Rounded Corners will not work for all widgets in Internet Explorer 8 because of border-radius property
is not supported in Internet Explorer 8 and its lower versions.
7. Vertical split and Horizontal split will not work for all widgets in Internet Explorer 9 and its lower
versions.
8. For non-modal popups (isModal = false), popup transparency (transparencyBehindThePopup) property
is not applied as the background widgets are accessible to the user.
9. A valid calendar year selection range is from 1900 to 2099. If you select an year beyond the range
shows an alert message (you can customize this error message).
10. In Internet Explorer 8 and below browsers do not support all geolocation APIs.
11. focusSkin applied to the container widgets (like HBox, VBox, Segment ) is not inherited by the inner
widgets in IE browsers (IE8, IE9, IE10). To overcome this apply focusSkin at every widget inside the
container widget.
12. For ScrollBox and TabPane widgets, angle background Multi Step Gradient is not supported.
13. Desktop Web platform does not support browser (Internet Explorer 8 ) running in compatibility mode.
14. Vertical gradient and Horizontal gradient are supported for all widgets in Internet Explorer 8 and above
versions.
15. Preview of map widget is not supported.
16. On Internet Explorer browsers, focusSkin applied to the widgets CheckBox and RadioButton will work
on click of text, but not on icon.
17. For Browser widget, Desktop Web platform supports BROWSER_REQUEST_METHOD_GET option
only.
18. Video widget in print API is not supported in Firefox browser.
19. To apply focusSkin for dynamically created widgets, assign focsuSkin dynamically after creating the
widget.
formid.widgetid.focusSkin = "skinname";
20. To apply hoverSkin for dynamically created widgets, assign hoverSkin dynamically after creating the
widget.
formid.widgetid.hoverSkin = "skinname";
45.2 SPA Limitations

This section lists the properties that are not supported by the SPA platform.
1. focusSkin is not supported in Windows NTH and Android devices.
2. For Horizontal Image strip, the stripview and slot view are not supported. If the images are of different
size, It is mandatory to mention the width and height property. Else, the alignment of the images may
get disturbed on the screen.
3. Only static maps are supported on Windows Phone 7.5 and BlackBerry NTH.
4. The widgets Slider, Chart2D3D, and PickerView widgets are not supported by both the Windows and
BlackBerry NTH devices.
5. Opacity should not be applied to form background for Windows Phone 7.5 and may lead to erroneous
results.
6. The property secureTextEntry for textarea is not supported in IE (desktop and mobile).
7. HBox position attribute is not supported in SPA (mobile and desktop). Instead use for header / footer to
dock elements.
8. showLoadingScreen() should be preferred over blockedUI, as blockedUI cannot cater to multiple
service calls which may be either chained or nested depending upon the application logic.
9. setContext for popup, dockable header / footer /appmenu is not supported on Windows Phone 7.5
since it doesn't support absolute positioned elements.
10. A valid calendar year selection range is from 1900 to 2099. If you select an year beyond the range
shows an alert message (you can customize this error message).
11. On SPA (Windows 8 and Windows Tablet devices) platform, focusSkin applied to the widgets HBox,
VBox, Calendar, ComboBox, ListBox, and SegmentedUI is not inherited by the inner widgets in IE
browsers (IE8, IE9, IE10). To overcome this apply focusSkin at every widget inside the container
widget.
12. Multi Step Gradient is not supported for all widgets on Windows Mango (IE9) devices.
13. ScrollBox does not support Blur radius option for skins on BB and BB NTH devices.
14. Preview of map widget is not supported.
15. On Windows device browsers, focusSkin applied to the widgets CheckBox and RadioButton will work
on click of text, but not on icon.
16. For Browser widget, SPA platform supports BROWSER_REQUEST_METHOD_GET option only.
17. For Calender widget, font color for input cannot be changed for Windows Phone 7.5 (Mango) platform.
18. On SPA platform, <script> tag is not supported.
19. To apply focusSkin for dynamically created widgets, assign focsuSkin dynamically after creating the
widget.
formid.widgetid.focusSkin = "skinname";
45.3 Windows 7/8/8.1 Kiosk

This section lists the properties that are not supported by Windows 7 Kiosk platform.
1. The widgets ObjectSelector3D, Phone, PickerView, Switch, MenuItem and Video are not supported.
2. As of today (10th, July 2013) Windows 7 Kiosk applications run only on Windows 8 PRO and not on
Windows 8 RT.
3. The application icon that is set from Application Properties > Common > Desktop icon size should be
multiple of 8 pixel and less than 256 pixel. For example, the icon image should be of size 8x8 or 16x16
px, it should be not 16x17 px.
45.4 BlackBerry 10
This section lists the limitations and properties that are not supported by BlackBerry 10 platform.
1. BlackBerry platform does not support the following widgets:
l
PickerView
TabPane
2. Gradient skins are not supported on any widgets.

3. The BlackBerry 10 supports application version only if the format is specified as x.x.x (For example,
2.3.6). The Build generation fails if you specify any other version format.
4. Only three options (WIDGET_ALIGN_TOP_LEFT, WIDGET_ALIGN_CENTER, and WIDGET_
ALIGN_BOTTOM_RIGHT) of the widgetAlignment is supported by respective widgets.
5. The layout property hExpand is always true for respective widgets and there is no effect when you set
as false.
6. You application crashes- when an event is invoked dynamically by assigning a JSObject. For example,
the below code will not work.
form.button.onClick = callback method()
//The callback method is a JSObject
7. In segmentedUI, you cannot change sectionHeaderTemplate and rowTemplate dynamically. For
example, the below code will not work.
form1.segment1.rowTemplate = template1
8. In calendar widget, if you use the method setenabled, the date gets cleared and validStartDate is
displayed. If validStartDate is not set then current date is displayed.
9. The property focusSkin is not supported for TextBox widget.
10. The font style with underline is not supported for TextBox widget.
11. Skin font style with underline is supported only for widgets RichText and Link.
12. All BlackBerry 10 supported widget events are not writable.
13. Following are the Map widget limitations:
a. From Kony Studio, you must set the permission for access_location_service as true. To set
access_location_service, navigate to Application Properties >Native >BlackBerry10, select
access_location_services and click Add > and then click Finish.
b. Your device location service setting must be on. To set device location service in your device,
navigate to Device Settings >Location Services > turn on the location services.
c. BlackBerry Native maps are supported, but map key and provider not applicable.
d. The Map widget is available in the United States and Canada regions. It will not work in Asia
Pacific region.
e. The Map widget works with BlackBerry 10 OS version 10.0.9.2709 and above.
f. If the network is slow, then rendering of the map is not smooth. The fonts and the user interface
(UI) may be affected.
g. For devices earlier than 10.1, a developer- specified or custom pin image is not displayed. Only
BlackBerry 10 provided images can be displayed.
h. Rendering of Map may takes 2 to 3 minutes or sometimes more than 5 minutes depending on
your network.
i. Templates for Map widget are not supported.
j. The default pin is always shown by the BlackBerry 10 device.
k. When a Map is loading you cannot display any alert messages as "Map is loading".
l. Your application may crash when you perform any action while loading a map.
m. Zoom level is decided by altitude. Hence user has to provide zoom level in terms of 1000. The
default zoomlevel is 10000.
n. Events associated with respective widgets are not writable.
14. Following are the CheckBox widget limitations:

a. By default the itemOrientation of a CheckBox widget is set to vertical. Unlike other platforms,
the BlackBerry 10 platform does not support the horizontal orientation.
b. When you define a skin for normal skin or focus skin, the options font style, font size, font color
are applied to the text of the CheckBox. They are not applicable to CheckBox image.
15. Following are the Button widget limitations:

a. Word Wrapping and Padding properties are not supported for Native button. Image button
supports Word Wrapping.
b. Rounded corner for borders and background is not supported. You can achieve this behavior
using Image button.
c. When you define a skin for normal skin or focus skin, the options font style, font size, font color
are applied to the text of the button in Image Button. They are not applicable to Native Button
widget.
16. Following are the ComboBox widget limitations:

a. Word Wrapping and Padding properties are not supported.
b. Rounded corner for borders and background is not supported.
c. Overriding the down arrow is not supported.
17. Following are the RadioButton widget limitations:

c. Overriding the default ticked and unTicked images is not supported.
18. Following are the Calendar widget limitations:

c. Grid calendar view is not supported.
d. Skin is not supported for Calender widget.
46. Glossary
B
base64
Returns the base64 encoded string of the image raw bytes. It is applicable for few widgets such as Image, Camera, and SignatureCapture widgets.
Basic Properties
Widgets properties are classified into three groups. Basic properties, Layout Properties and Platform Specific Properties. Most of the Basic Properties are applicable for all platforms.When you hand code the
properties should be put in basic bucket. Some of the Basic Properties
are ID, skin, focusSkin and so on.
blockedUISkin
Specifies the skin that must be used to block the interface until the action
in progress (for example, a service call) is completed.
C
CheckBoxGroup
The CheckBoxGroup widget allows you to make one or more selections
from a group of check boxes. If you select a check box, a check mark
appears inside the check box to indicate the selection.
ComboBoxGroup
The ComboBox is a widget that allows you to select a single item from a
drop-down list. When you select an item from the drop-down list, the
selected item is displayed on the ComboBox.
containerWeight
Specifies percentage of width to be allocated by its parent widget. The
parent widget space is distributed to its child widgets based on this
weight factor. All its child widgets should sum up to 100% of weight
except when placed in kony.ui.ScrollBox.
DataGrid
The DataGrid widget allows you to present a collection of data in rows
and columns (tabular format). You can use this widget to show a readonly view of a small amount of data in a tabular format.
E
Event
Events are functions that are associated with respective widgets are
executed to perform a sequence of actions, when the condition is satisfied.
F
focusSkin
This is a skin property and it determines the look and feel when there is
focus on a widget.
footers
A footer is a section of the form that is docked at the bottom of the form
(does not scroll along with the content of the form). These footers can
be reused across forms.
Form
A Form is a visual area (basic application screen) that holds other widgets. You can use a form to set a title and scroll content (similar to a web
browser). The entire contents of the form except the headers and footers scroll together. A form is also the top most container widget. A form
can contain any number of widgets but cannot contain another form.
H
HBox
An (HBox) is used to layout widgets in a single horizontal orientation. It
can contain any number of widgets. However, due to form size limitations, it is advisable not to place many widgets in a HBox.
headers
A header is a section of the form that is docked at the top of the form
(does not scroll along with the content of the form). These headers can
be reused across forms.
hExpand
HorizontalImageStrip
HorizontalImageStrip also called as Hz Image Strip displays a list of
images which are aligned side-by-side in the horizontal direction. You
can scroll through the Hz Image Strip to view the next or previous set of
images.
hoverSkin
I
id
id is a unique identifier of widget consisting of alpha numeric characters.
Every widget should have a unique id within a form.
Image
Image widget is a non-interactive widget that you can use to display a
graphic (local or remote) from a PNG file.
ImageGallery
ImageGallery represents a set of images adjacent to each other. If the
images exceed the row size, they are pushed to the next line.
info
A custom JSObject with the key value pairs that a developer can use to
store the context with the widget. This will help in avoiding the globals to
most part of the programming.
isVisible
L
Label
Label widget is used to display non-editable text on the form and is noninteractive.
Layout Properties
Widgets properties are classified into three groups. Basic properties, Layout Properties and Platform Specific Properties. Most of the Layout Properties are applicable for all platforms.When you hand code the
properties should be put in layout bucket. Some of the properties that
fall under layout bucket are margin, padding, containerWeight, widgetAlignment and so on.
Line
The Line widget allows you to draw a horizontal or a vertical line on a
form. It is used as a separator between widgets for a better visual experience.
Link
Link widget allows you to define a hyperlink that you can interact with
(select and click) and navigate to an external location or a location within
the application.
ListBox
List Box displays a list of items as a drop-down box and allows you to
select a single item at a time.
M
Map
A Map widget provides you the capability to display pre-defined locations
(latitude and longitude) on an onscreen map. Platforms like BlackBerry
(above JDE 4.5), iPhone (above 3.0), and Android provide a native map
widget that can be displayed as part of the application.
margin
Defines the space around a widget. You can use this option to define the
left, top, right, and bottom distance between the widget and the next element.
MenuItem
MenuItem is a choice on the Menu. It is typically a command or function
such as Application Logout, Form Exit, Sending SMS, or other options
that you can select inside a Menu.
Method
Methods are procedures that are associated with respective widgets to
access the data stored in an instance of the class to control the state of
the instance.
O
ObjectSelector3D
The ObjectSelector3D widget can be used for allowing the user to select
homogeneous objects arranged on a two-dimensional grid. It provides
the user with a three-dimensional graphical view of the objects which
makes it more attractive than regular two-dimensional images. It has
two modes, a selection mode and a walk-through mode.
P
padding
Defines the space between the content of the widget and the widget
boundaries. You can use this option to define the top, left, right, and bottom distance between the widget content and the widget boundary.
Phone
A Phone widget, when placed in an application, allows you to launch the
native phone dialer and initiate a phone call to the number that is displayed on it. It appears as a button on the Form and the phone number
is displayed on it either in the number format or the phone spell text.
When the user selects the phone widget, the native dialer is launched to
make a phone call.
PickerView
A PickerView widget uses a spinning wheel metaphor to display multiple
sets of values and allows you to select a single combination of values.
You can select a single combination of values by rotating the wheels and
aligning the desired row of values with the selection indicator.

The platform specific properties allow you to have a native look and feel
on the respective platforms.
Popup
Popup is a visual component that displays content on top of existing content, within the bounds of the application window. Generally a popup is
displayed in the center of the screen on top of the Form from which you
have invoked the popup. It does not span the entire screen
width.Popups allow you to partition UI design into smaller parts.
R
RadioButtonGroup
RadioButtonGroup is a widget that allows you to define a set of radio buttons and the user can choose one of it as an option. A radio button usually contains a small circle with text next to it. When you make a
selection, a dot appears in the circle to indicate your selection.
RichText
RichText widget is used to display non-editable and well formatted text
on the Form. HTML formatting tags are used in RichText widget to display text with styles (bold, underlined etc.), links, and images. You can
use a RichText widget to show a read-only text.
S
ScrollBox
A ScrollBox is a scrollable container which allows you to scroll the content
within horizontally and vertically. A ScrollBox can contain any widget
except a Tab pane.
SegmentedUI
A SegmentedUI consists of multiple segments (rows or records) and
each segment (row or record) can have multiple child widgets.
SignatureCapture
A SignatureCapture widget enables you to capture a signature on a form
and save it as an image for easy uploading.
skin
Slider
Slider widget allows you to select a value from a defined range of values
by moving the thumb (an indicator) in a horizontal direction. The Slider
widget consists of a seekbar (or track) and a thumb (a control that you
can slide). You can optionally choose to display a minimum value and a
maximum value.
Switch
The Switch widget is identical to the Switch Control (on-off switch which
is non customizable) in iPhone and presents two mutually exclusive
choices or states.
T
TabPane
TabPane widget is a container widget that allows you to organize multiple tabs within it. Each Tab will in turn hold a collection of widgets within
the same area of the Form. You can only view one Tab a time.
TextArea
TextArea is used to provide an editable field for the user to enter text
which spans over multiple lines. You can use the TextArea widget to
provide a field where a user can enter multiple lines of text.
TextBox
TextBox widget is an editable text component that can be placed on a
form and is used to obtain an input from a user. You can use the TextBox
widget to provide a field where a user can enter input text.
toolTip
Specifies the hint text when the cursor hovers over a widget, without
clicking it. The text entered in the tooltip appears as a small box when
the cursor hovers over a widget.
V
vBox
A VBox is used to layout widgets in a single vertical orientation. It can
contain any number of widgets. However, due to form size limitations, it
is advisable not to place many widgets in a VBox.
vExpand
Video
Video widget enables you to play a video (by streaming data from a
server) within a form. You can add a video widget only within a container
widget.
widgetAlignment
Indicates how a widget is to be anchored with respect to its parent. Each
of the options have a horizontal alignment attribute and a vertical alignment attribute. For example, WIDGET_ALIGN_TOP_LEFT specifies the
vertical alignment as TOP and horizontal alignment as LEFT.

Kony Widget User Guide

Hochgeladen von

Dokumentinformationen

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Kony Widget User Guide

Hochgeladen von

Copyright:

Verfügbare Formate

Kony Studio

Cloud and On-Premises Widget

Kony Widget User Guide - Ver 17.0

Copyright 2012 Kony, Inc.

Copyright 2012 Kony, Inc. All Rights Reserved.Page 2 of 1824

Kony Widget User Guide - Ver 17.0

Document Version Description of Modifications/Release

Document Release. 2D/3DChart wizard is dropped in 5.0 and

Updated Windows 8 and Desktop Web platform.

Updated MenuContainer and enhancements of SegmentedUI

New Properties and Methods added for Camera Widget.

Added Windows 7 Kiosk platform

New event added for Browser widget and minor enhancements

Document Release for 5.5

Document Release for 5.5.2. Charts widget updated

Added onCancel event for TextBox

Added Accessibility properties for applicable widgets

Widget Level Animation

Minor enhancements for SegmentedUI and ScrollBox

iOS7 support for Form, Popup, Slider,RadioButton,

Copyright 2012 Kony, Inc. All Rights Reserved.Page 3 of 1824

Kony Widget User Guide - Ver 17.0

Document Version Description of Modifications/Release

Copyright 2012 Kony, Inc. All Rights Reserved.Page 4 of 1824

Kony Widget User Guide - Ver 17.0

1.2 Intended Audience

1.3 Typographical Conventions

1.4 Reference Documents

2. Working with Widgets

2.1 Widget Classification

2.1.1 Container Widgets

2.1.2 Basic Widgets

2.1.3 Advanced Component Widgets

2.2 Widget Methods

2.3 Widget Skins

2.3.1 Dynamic Skinning

2.3.2 Platform Specific Skin Limitations

4.1 Form - Basic Properties

Copyright 2012 Kony, Inc. All Rights Reserved.Page 5 of 1824

Kony Widget User Guide - Ver 17.0

4.2 Form - Layout Properties

4.3 Form - Platform Specific Properties

Copyright 2012 Kony, Inc. All Rights Reserved.Page 6 of 1824

Kony Widget User Guide - Ver 17.0

4.4 Form - Events

Copyright 2012 Kony, Inc. All Rights Reserved.Page 7 of 1824

Kony Widget User Guide - Ver 17.0

4.5 Form - Methods

Copyright 2012 Kony, Inc. All Rights Reserved.Page 8 of 1824

Kony Widget User Guide - Ver 17.0

4.6.1 Dockable Appmenu

4.6.2 Dockable Header

4.6.3 Dockable Footer

4.6.4 Enable Back

4.6.5 Ignore Escape

4.6.7 menu Renderer

5.2 HBox - Layout Properties

Copyright 2012 Kony, Inc. All Rights Reserved.Page 9 of 1824

Kony Widget User Guide - Ver 17.0

5.3 HBox - Platform Specific Properties

5.4 HBox - Events

5.5 HBox - Methods

5.6 Context Menu- Templates

5.6.1 What is a Template for a Context Menu