Examen Itil v3 Preguntas y Respuestas

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.
October, 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 1833

Revision History
Date Document Version Description of Modifications/Release

Document Release. 2D/3DChart wizard is dropped in 5.0 and
08/31/2012 1.0 future versions will have support for revamped and
sophisticated charts.
09/20/2012 2.0 Updated onDestroy event for Form and Popup.
11/09/2012 3.0 Updated Windows 8 and Desktop Web platform.
Updated MenuContainer and enhancements of SegmentedUI
12/14/2012 4.0
and TabPane.
01/11/2013 5.0 Updated Windows Phone and minor changes.
New methods added for ScrollBox widget, and info added for
03/05/2013 6.0
Map V2 for Map Widget. Added SignatureCapture Widget.
05/31/2013 7.0 Updated Windows support for Switch widget.
06/20/2013 8.0 New Properties and Methods added for Camera Widget.
7/10/2013 9.0 Added Windows 7 Kiosk platform.
New event added for Browser widget and minor
8/30/2013 10.0
enhancements.
Updated 5.5 features. New features added for Calendar,
9/24/2013 11.0 Slider, SegmentedUi, Map, TextBox, Popup, ScrollBox,
SignatureCapture and Tabpane widgets.
10/25/2013 12.0 Added BlackBerry 10 platform
12/3/2013 13.0 Document Release for 5.5
2/21/2014 14.0 Document Release for 5.5.2. Charts widget updated
3/28/2014 15.0 Added onCancel event for TextBox
l Added Accessibility properties for applicable widgets
l Widget Level Animation
5/13/2014 16.0 l Minor enhancements for SegmentedUI and ScrollBox

widgets.
l 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:
l ScrollBox
l TabPane
l Popup
l Calendar
l CheckBox
8/1/2014 17.0 l ComboBox
l DataGrid
l ListBox
l RadioButton
l TextArea
l TextBox
l Browser
l SegmentedUI
12/24/2014 18.0 Document Release for 5.6.4

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 156
4.4 Form - Events 159

4.4.1 addWidgets 159
4.4.2 init 160
4.4.3 onActionBarBack 161
4.4.4 onHide 162
4.4.5 onOrientationChange 163
4.4.6 onDeviceBack 163
4.4.7 onDeviceMenu 164
4.4.8 onDestroy 165
4.4.9 preShow 166
4.4.10 postShow 167
4.4.11 onLoadJS 168
4.4.12 unLoadJS 169
4.5 Form - Methods 171
4.5.1 add 171
4.5.2 addAt 172
4.5.3 show 175
4.5.4 destroy 176
4.5.5 remove 177
4.5.6 removeAt 178
4.5.7 replaceAt 181
4.5.8 widgets 184
4.5.9 setTitleBarLeftSideButtonSkin 185
4.5.10 setTitleBarRightSideButtonSkin 185
4.5.11 setTitleBarSkin 186
4.5.12 showTitleBar 187
4.5.13 hideTitleBar 187
4.5.14 scrollToWidget 188
4.5.15 scrollToBeginning 189

4.5.16 scrollToEnd 189
4.6 Form - Deprecated Properties and Events 190
4.6.1 Dockable Appmenu 191
4.6.2 Dockable Header 191
4.6.3 Dockable Footer 192
4.6.4 Enable Back 192
4.6.5 Ignore Escape 193
4.6.6 masterdataload 193
4.6.7 menu Renderer 193
4.6.8 transactionaldataload() 194
4.6.9 undockappheader 194
4.6.10 undockappfooter 195
5. HBox 196
5.1 HBox - Basic Properties 197
5.1.1 focusSkin 197
5.1.2 id 198
5.1.3 info 199
5.1.4 isVisible 200
5.1.5 orientation 201
5.1.6 position 202
5.1.7 skin 204
5.2 HBox - Layout Properties 205
5.2.1 containerWeight 205
5.2.2 gridCell 206
5.2.5 layoutAlignment 209
5.2.6 margin 210

5.2.7 marginInPixel 212
5.2.8 padding 213
5.2.10 percent 216
5.2.11 vExpand 218
5.2.12 widgetAlignment 219
5.3 HBox - Platform Specific Properties 221
5.3.1 blockedUISkin 221
5.3.2 borderCollapse 222
5.3.3 contextMenu 223
5.3.4 hoverSkin 227
5.4 HBox - Events 232
5.4.1 onClick 232
5.4.2 onHover 233
5.4.3 onRightClick 236
5.4.4 preOnclickJS 237
5.4.5 postOnclickJS 238
5.5 HBox - Methods 239
5.5.1 add 239
5.5.2 addAt 240
5.5.3 remove 243
5.5.4 removeAt 244
5.5.5 replaceAt 247
5.5.6 widgets 250
5.6 Context Menu- Templates 251
5.6.1 What is a Template for a Context Menu 251
5.6.2 Where to use a Context MenuTemplate 251

5.6.3 Creating a Template for Context Menu 251
5.6.4 Using Context Menu Template 251
6. VBox 253
6.1 VBox - Basic Properties 254
6.1.1 focusSkin 254
6.1.2 id 255
6.1.3 info 256
6.1.4 isVisible 257
6.1.6 skin 259
6.2 VBox - Layout Properties 260
6.2.2 gridCell 261
6.2.6 margin 266
6.2.8 padding 269
6.3 VBox - Platform Specific Properties 274
6.3.2 borderCollapse 275
6.3.4 hoverSkin 280
6.4 VBox - Events 284

6.4.1 onClick 284
6.4.2 onHover 285
6.5 VBox - Methods 291
6.5.1 add 291
6.5.2 addAt 292
6.5.3 remove 295
6.5.4 removeAt 296
6.5.5 replaceAt 299
6.5.6 widgets 302
6.6 Context Menu- Templates 304
6.6.1 What is a Template for a Context Menu 304
6.6.2 Where to use a Context MenuTemplate 304
6.6.3 Creating a Template for Context Menu 304
6.6.4 Using Context Menu Template 304
7. ScrollBox 306
7.1 ScrollBox - Basic Properties 308
7.1.1 enableScrollByPage 308
7.1.2 id 309
7.1.3 info 310
7.1.4 isVisible 311
7.1.6 position 313
7.1.7 pullToRefreshI18NKey 314
7.1.8 pullToRefreshSkin 315
7.1.9 pushToRefreshI18NKey 316

7.1.10 pushToRefreshSkin 316
7.1.11 releaseToPullRefreshI18NKey 317
7.1.12 releaseToPushRefreshI18NKey 318
7.1.13 scrollDirection 318
7.1.14 showScrollbars 319
7.1.15 skin 320
7.2 ScrollBox - Layout Properties 321
7.2.1 containerHeight 322
7.2.2 containerHeightReference 323
7.2.5 margin 326
7.2.7 padding 329
7.2.9 percent 332
7.3 ScrollBox - Platform Specific Properties 333
7.3.1 bounces 333
7.3.3 scrollArrowConfig 337
7.3.4 showFadingEdges 338
7.4 ScrollBox - Events 341
7.4.1 scrollingEvents 341
7.5 ScrollBox - Methods 344
7.5.1 add 344
7.5.2 addAt 345
7.5.3 remove 346

7.5.4 removeAt 347
7.5.8 widgets 351
8. TabPane 353
8.1 TabPane - Basic Properties 356
8.1.1 activeFocusSkin 356
8.1.2 activeSkin 357
8.1.3 activeTabs 358
8.1.4 id 359
8.1.5 inactiveSkin 360
8.1.6 info 361
8.1.7 isVisible 362
8.1.8 retainPositionInTab 363
8.1.9 screenLevelWidget 364
8.1.11 viewType 367
8.2 TabPane - Layout Properties 368
8.2.4 gridCell 372
8.2.7 margin 376
8.2.9 padding 379

8.3 TabPane - Platform Specific Properties 382
8.3.1 pageSkin 382
8.3.2 progressIndicatorColor 384
8.3.3 showProgressIndicator 385
8.3.4 tabHeaderTemplate 386
8.3.5 tabHeaderHeight 386
8.4 TabPane - Events 388
8.4.1 onTabClick 388
8.5 TabPane - Methods 392
8.5.1 addTab 392
8.5.2 addTab 393
8.5.3 addTabAt 394
8.5.4 removeTabAt 395
8.5.5 removeTabByld 396
8.6 Tab header - Templates 398
8.6.1 What is a Template for tabHeader and where to use it 398
8.6.2 Creating a Template for tabHeader 398
8.6.3 Using tabHeader Template 398
9. Popup 400
9.1 Popup - Basic Properties 402
9.1.1 footers 403
9.1.2 headers 404
9.1.3 id 404
9.1.4 info 405
9.1.5 isModal 406

9.1.6 skin 407
9.1.7 title 408
9.1.8 transparencyBehindThePopup 409
9.2 Popup - Layout Properties 411
9.2.4 gridCell 414
9.2.7 padding 417
9.3 Popup - Platform Specific Properties 421
9.3.1 bounces 421
9.3.2 captureGPS 422
9.3.3 contextPath 424
9.3.4 configureExtendTop 424
9.3.5 draggable 425
9.3.6 extendTop 426
9.3.7 footerOverlap 427
9.3.8 headerOverlap 428
9.3.9 inputAccessoryViewType 428
9.3.10 inTransitionConfig 431
9.3.11 layout 434
9.3.12 minimizeOnLostFocus 435
9.3.13 noCache 436
9.3.14 outTransitionConfig 437
9.3.15 popupStyle 439

9.3.16 resizable 440
9.3.17 secureData 441
9.3.18 showMiniAppMenu 442
9.3.19 submitSecure 443
9.3.20 titleBarConfig 444
9.3.22 windowSoftInputMode 447
9.4 Popup - Events 449
9.4.1 addWidgets 449
9.4.2 init 449
9.4.3 onHide 450
9.4.4 onDeviceBack 451
9.4.5 onLoadJS 452
9.4.6 unLoadJS 453
9.5 Popup - Methods 455
9.5.1 add 455
9.5.2 addAt 456
9.5.3 destroy 457
9.5.4 dismiss 458
9.5.5 navigateTo 459
9.5.6 remove 460
9.5.7 removeAt 461
9.5.11 setContext 464
9.5.12 setTitleBarLeftSideButtonSkin 466
9.5.13 setTitleBarRightSideButtonSkin 467

9.5.14 setTitleBarSkin 468
9.5.15 showTitleBar 469
9.5.16 hideTitleBar 470
9.5.17 show 470
9.5.18 widgets 471
9.6 Popup - Deprecated Properties 472
9.6.1 closureLeftSideView 473
9.6.2 closureRightSideView 474
9.6.3 dockableAppMenu 474
9.6.4 imageLeftSideView 474
9.6.5 imageRightSideView 475
9.6.6 nift 475
9.6.7 onOrientationChange 475
9.6.8 orientationmode 476
9.6.9 renderTitleText 476
9.6.10 reset Focus to top of the Form 476
9.6.11 skin Around Popup 477
9.6.12 titleBar 477
9.6.13 titleBarLeftSideView 478
9.6.14 titleBarRightSideView 478
10. Basic Widgets 479
11. Button 480
11.1 Button - Basic Properties 483
11.1.1 focusSkin 483
11.1.2 id 484
11.1.3 info 485
11.1.4 isVisible 486
11.1.5 rawBytes 487

11.1.6 skin 488
11.1.7 text 489
11.2 Button - Layout Properties 490
11.2.2 contentAlignment 491
11.2.3 displayText 493
11.2.4 hExpand 494
11.2.5 margin 496
11.2.7 padding 499
11.2.9 vExpand 502
11.3 Button - Platform Specific Properties 505
11.3.3 externalURL 508
11.3.4 glowEffect 509
11.3.5 hoverSkin 510
11.3.6 pressedSkin 511
11.3.8 submitURL 513
11.3.9 toolTip 514
11.4 Button - Events 515
11.4.1 onClick 515
11.5 Button - Deprecated Properties 518

11.5.1 focusimage 518
11.5.2 image 519
11.5.3 normalimage 519
12. Calendar 520
12.1 Calendar - Basic Properties 527
12.1.1 calendarIcon 527
12.1.2 dateComponents 528
12.1.3 dateFormat 530
12.1.4 day 531
12.1.6 formattedDate 533
12.1.7 hour 534
12.1.8 id 535
12.1.9 info 536
12.1.11 minutes 538
12.1.12 month 539
12.1.13 placeholder 540
12.1.14 seconds 541
12.1.15 skin 542
12.1.16 validStartDate 543
12.1.17 validEndDate 544
12.1.19 viewType 547
12.1.20 year 549
12.2 Calendar - Layout Properties 549

12.2.3 hExpand 552
12.2.4 margin 554
12.2.6 padding 557
12.2.8 vExpand 560
12.3 Calendar-Platform Specific Properties 563
12.3.1 cellTemplate 564
12.3.4 dateEditable 567
12.3.5 data 568
12.3.6 dayTextAlignmentInCell 570
12.3.7 displayedMonth 571
12.3.8 hideDaysHeader 572
12.3.9 hideMonthsHeader 573
12.3.11 mode 575
12.3.12 noOfMonths 576
12.3.13 titleOnPopup 577
12.3.14 toolTip 578
12.3.15 widgetDataMapForCell 579
12.3.16 wheelBackgroundColor 580
12.4 Calendar - Event 582
12.4.1 onSelection 582
12.5 Calendar - Methods 583
12.5.1 clear 583

12.5.2 clearData 584
12.5.3 enableRangeOfDates 585
12.5.4 navigateToPreviousMonth 586
12.5.5 navigateToNextMonth 587
12.5.6 removeDataAt 588
12.5.7 setData 589
12.5.8 setDataAt 590
12.5.9 setEnabled 591
12.5.10 setEnableAll 593
12.5.11 setDatesSkin 594
12.5.12 setContext 595
12.5.13 addAppointments 596
12.5.14 deleteAppointments 598
12.5.15 modifyAppointments 599
12.5.16 getAppointments 600
12.5.17 clearAppointments 602
12.5.18 switchToDate 603
12.6 Calendar - Deprecated Properties 605
12.6.1 date 605
12.6.2 format 607
12.6.3 monthI18Nkey 607
12.6.4 weekdayI18Nkey 608
12.7 gridcalender - Templates 608
12.7.1 What is a Template for gridcalendar 608
12.7.2 Where to use a gridcalendar Template 609
12.7.3 Creating a Template for gridcalendar 609
12.7.4 Using gridcalendar Template 609
13. CheckBoxGroup 611

13.1 CheckBox - Basic Properties 615
13.1.2 id 616
13.1.3 info 617
13.1.5 masterData 619
13.1.6 masterDataMap 621
13.1.7 selectedKeys 623
13.1.8 selectedKeyValues 624
13.1.9 skin 624
13.2 CheckBox - Layout Properties 625
13.2.2 itemOrientation 626
13.2.3 margin 627
13.2.5 padding 630
13.3 CheckBox - Platform Specific Properties 635
13.3.1 focusTickedImage 635
13.3.2 focusUnTickedImage 636
13.3.3 groupCells 636
13.3.5 tickedImage 638
13.3.6 toolTip 639
13.3.7 unTickedImage 640
13.3.8 viewType 641

13.4 CheckBox - Events 646
14. ComboBox 650
14.1 ComboBox - Basic Properties 655
14.1.2 id 656
14.1.3 info 657
14.1.7 selectedKey 663
14.1.8 selectedKeyValue 664
14.1.9 skin 664
14.2 ComboBox - Layout Properties 665
14.2.3 hExpand 668
14.2.4 margin 669
14.2.6 padding 672
14.2.8 vExpand 675
14.3 ComboBox - Platform Specific Properties 679
14.3.2 dropDownImage 680

14.3.6 popupFocusSkin 684
14.3.7 popupSkin 685
14.3.8 popupTitle 685
14.3.9 singleLineText 686
14.3.10 singleLineTextInPopup 687
14.3.11 textTruncatePosition 688
14.3.12 textTruncatePositionInPopup 689
14.3.14 toolTip 691
14.4 ComboBox- Events 699
14.5 ComboBox - Deprecated Properties 701
14.5.1 placeholderi18nKey 702
15. DataGrid 703
15.1 DataGrid - Basic Configuration Properties 707
15.1.1 columnHeadersConfig 707
15.1.2 data 709
15.1.3 gridHeight 712
15.1.4 headerSkin 713

15.1.5 id 714
15.1.6 info 715
15.1.7 isMultiSelect 716
15.1.9 rowAlternateSkin 719
15.1.10 rowCount 720
15.1.11 rowFocusSkin 721
15.1.12 rowNormalSkin 722
15.1.13 scrollable 723
15.1.14 selectedIndex 724
15.1.15 selectedIndices 725
15.1.16 selectedItem 726
15.1.17 selectedItems 728
15.1.18 showColumnHeaders 729
15.2 DataGrid - Layout Properties 730
15.2.3 margin 733
15.2.4 padding 735
15.3 DataGrid - Platform Specific Properties 740
15.3.2 containerHeightInPixel 741
15.3.3 dockingHeader 742
15.3.4 enableScrollBar 743
15.3.5 gridlineColor 744
15.3.7 selectedCellItem 746

15.3.8 selectedCellIndex 747
15.3.9 toolTip 748
15.4 DataGrid - Events 750
15.4.1 onRowSelected 750
15.5 DataGrid - Methods 752
15.5.1 addAll 752
15.5.2 addDataAt 753
15.5.3 applyCellSkin 754
15.5.4 removeAll 756
15.5.5 removeAt 757
15.5.6 selectAllRows 758
15.5.7 setCellDataAt 759
15.5.8 setData 760
15.6 DataGrid - Templates 764
15.6.1 What is a Template for DataGrids 764
15.6.2 Where to use a Grid Template 764
15.6.3 Creating a Template for DataGrid 764
15.6.4 Using Grid Template 765
16. Image 766
16.1 Image - Basic Properties 768
16.1.1 base64 769
16.1.2 id 770
16.1.3 imageWhenFailed 771
16.1.4 imageWhileDownloading 772
16.1.5 info 773
16.1.7 rawBytes 775

16.1.8 src 776
16.2 Image - Layout Properties 777
16.2.2 imageScaleMode 778
16.2.3 margin 783
16.2.5 padding 786
16.2.7 referenceHeight 789
16.2.8 referenceWidth 790
16.3 Image - Platform Specific Properties 793
16.3.1 glossyEffect 793
16.3.3 renderAsAnchor 795
16.3.4 skin 796
16.3.5 toolTip 797
16.4 Image - Events 798
16.4.1 onDownloadComplete 798
16.5 Image - Deprecated Properties 799
16.5.1 hExpand 799
16.5.2 scaleMode 800
16.5.3 vExpand 801
17. Label 803
17.1 Label - Basic Properties 805
17.1.1 id 805
17.1.2 info 806

17.1.4 skin 808
17.1.5 text 809
17.1.6 toolTip 810
17.2 Label - Layout Properties 811
17.2.3 hExpand 814
17.2.4 margin 816
17.2.6 padding 819
17.2.8 vExpand 822
17.3 Label - Platform Specific Properties 825
17.3.1 hoverSKin 825
17.3.2 pasteboardType 826
17.3.3 renderAsAnchor 827
17.3.4 textCopyable 828
17.3.5 toolTip 829
17.3.6 wrapping 830
18. Line 832
18.1 Line - Basic Properties 834
18.1.1 id 834
18.1.2 info 835
18.1.4 skin 837
18.2 Line - Layout Properties 838
18.2.1 margin 838

18.2.3 thickness 841
18.3 Line - Platform Specific Properties 842
18.3.1 toolTip 842
18.3.2 Line - Platform Specific Properties 844
19. Link 845
19.1 Link - Basic Properties 848
19.1.2 id 849
19.1.3 info 850
19.1.5 skin 852
19.1.6 text 853
19.1.7 toolTip 854
19.2 Link - Layout Properties 855
19.2.3 hExpand 858
19.2.4 margin 859
19.2.6 padding 862
19.3 Link - Platform Specific Properties 867
19.3.3 externalURL 870
19.3.4 glowEffect 871

19.3.7 submitURL 874
19.3.8 toolTip 875
19.4 Link - Events 877
19.4.1 onClick 877
19.5 Link - Deprecated Properties 880
19.5.1 focusImage 880
19.5.2 image 881
19.5.3 normalImage 881
20. ListBox 882
20.1 ListBox - Basic Properties 883
20.1.2 id 885
20.1.3 info 886
20.1.11 skin 895
20.2 ListBox - Layout Properties 896

20.2.3 hExpand 899
20.2.4 margin 900
20.2.6 padding 903
20.2.8 vExpand 906
20.3 ListBox - Platform Specific Properties 910
20.3.1 applySkinsToPopup 910
20.3.6 multiSelect 916
20.3.7 multiSelectRows 917
20.3.8 nativeListFieldSkin 917
20.3.9 nativeListFieldFocusSkin 918
20.3.11 placeholderSkin 921
20.3.12 popupIcon 921
20.3.13 popupTitle 923
20.3.14 singleLineText 924
20.3.15 singleLineTextInPopup 924
20.3.16 textTruncatePosition 925
20.3.17 textTruncatePositionInPopup 926
20.3.19 toolTip 928

20.4 ListBox - Events 937
20.5 ListBox - Deprecated Properties 940
20.5.1 listStyle 940
20.5.2 multiple 941
20.5.3 placeholderi18nKey 942
21. MenuContainer 944
21.1 MenuContainer - Basic Properties 948
21.1.1 activeSkin 948
21.1.2 data 950
21.1.4 id 953
21.1.5 info 955
21.1.7 menuItemTemplate 957
21.1.9 selectedMenuIndex 960
21.1.10 selectedMenuItem 961
21.1.11 skin 963
21.1.12 widgetDataMap 965
21.2 MenuContainer - Layout Properties 966

21.2.2 margin 968
21.2.4 padding 971
21.3 MenuContainer - Platform Specific Properties 976
21.3.2 collapsedImage 979
21.3.3 expandedImage 981
21.3.4 viewType 982
21.4 MenuContainer - Event 985
21.4.1 onClick 985
21.5 MenuContainer - Methods 990
21.5.1 addAll 990
21.5.4 removeAt 995
21.5.5 setData 997
21.6 Menu - Templates 1002
21.6.1 What is a Template for Menu 1002
21.6.2 Where to use a Menu Template 1002
21.6.3 Creating a Template for Menu 1002
21.6.4 Using Menu Templates 1003
22. MenuItem 1005
22.1 MenuItem - Basic Properties 1007

22.1.1 focusImage 1007
22.1.2 id 1008
22.1.3 info 1008
22.1.4 image 1009
22.1.5 title 1010
22.1.6 type 1010
22.2 Menuitem - Event 1012
22.2.1 onClick 1012
23. RadioButtonGroup 1013
23.1 RadioButtonGroup - Basic Properties 1017
23.1.2 id 1018
23.1.3 info 1019
23.1.9 skin 1027
23.2 RadioButtonGroup - Layout Properties 1028
23.2.2 hExpand 1029
23.2.3 itemOrientation 1030
23.2.4 margin 1032
23.2.6 padding 1035
23.2.8 vExpand 1038

23.3 RadioButtonGroup - Platform Specific Properties 1042
23.3.2 focusTickedImage 1043
23.3.3 focusUnTickedImage 1044
23.3.8 toolTip 1049
23.3.10 viewType 1051
23.4 RadioButtonGroup - Events 1058
24. RichText 1062
24.1 RichText - Basic Properties 1065
24.1.1 id 1066
24.1.2 info 1066
24.1.4 linkSkin 1068
24.1.5 skin 1069
24.1.6 text 1070
24.2 RichText - Layout Properties 1071

24.2.3 hExpand 1074
24.2.4 margin 1075
24.2.6 padding 1078
24.2.8 vExpand 1081
24.3 RichText - Platform Specific Properties 1084
24.3.2 linkFocusSkin 1085
24.3.3 superScriptSkin 1086
24.3.4 telephoneLinkSkin 1087
24.3.5 toolTip 1088
24.3.6 wrapping 1088
24.4 RichText - Events 1091
24.4.1 onClick 1091
25. Slider 1095
25.1 Slider - Basic Configuration Properties 1097
25.1.1 focusThumbImage 1098
25.1.2 id 1099
25.1.3 info 1099
25.1.5 leftSkin 1102
25.1.6 max 1103
25.1.7 min 1104

25.1.8 rightSkin 1105
25.1.9 selectedValue 1106
25.1.10 step 1107
25.1.11 thumbImage 1108
25.2 Slider - Layout Properties 1109
25.2.2 margin 1111
25.3 Slider - Platform Specific Properties 1116
25.3.1 enableThumbTintColor 1116
25.3.2 maxLabel 1117
25.3.3 maxLabelSkin 1118
25.3.4 maxValueImage 1119
25.3.5 minLabel 1120
25.3.6 minLabelSkin 1121
25.3.7 minValueImage 1122
25.3.9 thickness 1124
25.3.10 thumbOffset 1125
25.3.11 thumbTintColor 1126
25.3.12 viewType 1127
25.4 Slider - Events 1129
25.4.2 onSlide 1130
26. TextArea 1132
26.1 TextArea - Basic Properties 1135
26.1.1 autoCapitalize 1135

26.1.3 id 1137
26.1.4 info 1138
26.1.6 keyBoardStyle 1140
26.1.7 maxTextLength 1143
26.1.8 numberOfVisibleLines 1144
26.1.10 secureTextEntry 1146
26.1.11 skin 1147
26.1.12 text 1148
26.1.13 textInputMode 1149
26.2 TextArea - Layout Properties 1151
26.2.3 hExpand 1153
26.2.4 margin 1155
26.2.6 padding 1158
26.3 TextArea - Platform Specific Properties 1164
26.3.1 autoCorrect 1164
26.3.3 closeButtonText 1166
26.3.5 keyboardActionLabel 1169

26.3.8 showCloseButton 1173
26.3.10 toolTip 1176
26.4 TextArea - Events 1176
26.4.1 onDone 1177
26.4.2 onBeginEditing 1178
26.4.3 onEndEditing 1179
26.4.4 onKeyUp 1180
26.4.5 onKeyDown 1181
26.4.6 onTextChange 1181
26.5 TextArea - Deprecated Properties 1182
26.5.1 editable 1182
26.5.2 No of Rows 1183
27. TextBox 1184
27.1 TextBox - Basic Properties 1187
27.1.1 autoCapitalize 1187
27.1.3 id 1190
27.1.4 info 1191
27.1.6 keyBoardStyle 1193
27.1.7 maxTextLength 1196
27.1.9 secureTextEntry 1198
27.1.10 skin 1199
27.1.11 text 1200
27.1.12 textInputMode 1201

27.1.13 toolTip 1202
27.2 TextBox - Layout Properties 1204
27.2.3 containerHeightMode 1206
27.2.6 hExpand 1209
27.2.7 margin 1211
27.2.9 padding 1214
27.3 TextBox - Platform Specific Properties 1219
27.3.1 autoComplete 1219
27.3.2 autoCorrect 1221
27.3.3 autoFilter 1222
27.3.5 closeButtonText 1225
27.3.6 filterList 1227
27.3.8 keyboardActionLabel 1228
27.3.9 leftViewImage 1230
27.3.10 nativeListFieldFocusSkin 1231
27.3.11 nativeListFieldSkin 1232
27.3.14 showClearButton 1236

27.3.15 showCloseButton 1237
27.3.17 toolTip 1240
27.3.18 viewType 1240
27.4 TextBox - Events 1242
27.4.1 onCancel 1243
27.4.2 onDone 1244
27.4.3 onBeginEditing 1245
27.4.4 onEndEditing 1245
27.4.5 onKeyUp 1247
27.4.6 onKeyDown 1248
27.4.7 onTextChange 1249
27.5 TextBox - Deprecated Properties 1251
27.5.1 inputStyle 1252
27.5.2 keyBoardType 1253
27.5.3 Type 1255
28. Advanced Widgets 1257
29. Browser 1258
29.1 Browser - Basic Properties 1262
29.1.1 detectTelNumber 1262
29.1.2 enableZoom 1263
29.1.3 htmlString 1264
29.1.4 id 1265
29.1.5 info 1266
29.1.7 requestURLConfig 1268

29.2 Browser - Layout Properties 1271
29.2.4 margin 1274
29.3 Browser - Platform Specific Properties 1277
29.3.1 enableOverviewMode 1277
29.3.3 useWideViewport 1279
29.3.4 zoomDensity 1280
29.4 Browser - Events 1281
29.4.1 handleRequest 1281
29.4.2 onFailure 1282
29.4.3 onSuccess 1283
29.5 Browser - Methods 1286
29.5.1 canGoBack 1286
29.5.2 canGoForward 1287
29.5.3 clearHistory 1288
29.5.4 goBack 1289
29.5.5 goForward 1290
29.5.6 loadData 1291
29.5.7 reload 1292
29.6 Browser - Deprecated Properties 1293
30. Camera 1295

30.1 Camera - Basic Properties 1299
30.1.1 base64 1299
30.1.2 compressionLevel 1300
30.1.4 id 1302
30.1.5 info 1303
30.1.7 maxSideOfTheImage 1305
30.1.8 rawBytes 1306
30.1.9 scaleFactor 1307
30.1.10 skin 1308
30.1.11 text 1309
30.2 Camera - Layout Properties 1309
30.2.3 hExpand 1312
30.2.4 margin 1314
30.2.6 padding 1317
30.2.8 vExpand 1320
30.3 Camera - Platform Specific Properties 1322
30.3.1 accessMode 1323
30.3.2 cameraOptions 1324
30.3.3 captureOrientation 1326
30.3.4 enableOverlay 1327
30.3.5 enableZoom 1328

30.3.6 enablePhotoCropFeature 1330
30.3.8 imageFormat 1331
30.3.9 nativeUserInterface 1332
30.3.10 overlayConfig 1333
30.3.11 toolTip 1335
30.4 Camera - Event 1336
30.4.1 onCapture 1336
30.4.2 onCaptureFailed 1337
30.4.3 onImageSaveFailed 1338
30.5 Camera - Methods 1338
30.5.1 closeCamera 1339
30.5.2 releaseRawBytes 1339
30.5.3 takePicture 1341
30.6 Camera - Deprecated Properties 1341
30.6.1 Auto store to disk 1342
30.6.2 mode 1342
31. HorizontalImageStrip 1346
31.1 HorizontalImageStrip - Basic Properties 1348
31.1.1 arrowConfig 1349
31.1.2 data 1350
31.1.4 id 1352
31.1.7 info 1355

31.1.11 showArrows 1359
31.1.13 skin 1361
31.1.14 spaceBetweenImages 1362
31.1.16 viewType 1364
31.2 HorizontalImageStrip - Layout Properties 1369
31.2.3 margin 1375
31.2.5 padding 1378
31.3 HorizontalImageStrip - Platform Specific Properties 1385
31.3.2 toolTip 1386
31.4 HorizontalImageStrip - Events 1388
31.5 HorizontalImageStrip - Methods 1392
31.5.1 addAll 1392

31.5.4 removeAt 1395
31.5.5 setData 1396
31.6 HorizontalImageStrip - Deprecated 1399
31.6.1 frameHeight 1399
31.6.2 height 1399
31.6.4 width 1401
32. ImageGallery 1402
32.1 ImageGallery - Basic Properties 1404
32.1.1 data 1404
32.1.3 id 1406
32.1.6 info 1408
32.1.10 skin 1412
32.1.11 spaceBetweenImages 1413
32.2 ImageGallery - Layout Properties 1414
32.2.3 margin 1420

32.3 ImageGallery - Platform Specific Properties 1426
32.3.2 itemsPerRow 1427
32.3.3 navigationBarPosition 1427
32.3.4 noofRowsPerPage 1428
32.4 ImageGallery - Events 1432
32.5 ImageGallery - Methods 1436
32.5.1 addAll 1436
32.5.5 setData 1439
32.6 ImageGallery - Deprecated Properties 1442
32.6.1 frameHeight 1442
32.6.2 height 1443
32.6.3 width 1443
32.6.4 showItemCount 1444
33. Map 1445
33.1 Map - Basic Properties 1453
33.1.1 calloutTemplate 1454
33.1.2 calloutWidth 1454
33.1.3 defaultPinImage 1455

33.1.4 id 1456
33.1.5 info 1457
33.1.7 locationData 1459
33.1.8 mapKey 1460
33.1.9 provider 1461
33.1.11 widgetDataMapForCallout 1463
33.2 Map - Layout Properties 1464
33.2.4 margin 1467
33.3 Map - Platform Specific Properties 1471
33.3.1 address 1471
33.3.2 mapHeight 1472
33.3.3 mapSource 1473
33.3.4 mapWidth 1474
33.3.5 mode 1475
33.3.6 navControlsImageConfig 1478
33.3.7 showCurrentLocation 1479
33.3.8 showZoomControl 1480
33.3.9 zoomLevel 1481
33.4 Map - Events 1483
33.4.1 onClick 1483
33.4.2 onPinClick 1484

33.5 Map - Methods 1486
33.5.1 addPolyline 1486
33.5.2 clear 1488
33.5.3 dismissCallout 1489
33.5.4 getBounds 1489
33.5.5 navigateTo 1490
33.5.6 navigateToLocation 1491
33.5.7 removePolyline 1493
33.6 Map - Templates 1494
33.6.1 What is a Template for Map callout 1494
33.6.2 Where to use a Map callout Template 1494
33.6.3 Creating a Template for Map callout 1494
33.6.4 Using Map callout Template 1494
34. ObjectSelector3D 1496
34.1 ObjectSelector3D - Basic Properties 1499
34.1.2 id 1500
34.1.3 info 1501
34.1.5 skin 1503
34.1.6 text 1504
34.2 ObjectSelector3D - Layout Properties 1505
34.2.3 hExpand 1507
34.2.4 margin 1509
34.2.6 padding 1512

34.2.8 vExpand 1515
34.3 ObjectSelector3D - Event 1518
34.3.1 onSelectionDone 1518
34.4 ObjectSelector3D - Methods 1519
34.4.1 addModel 1519
34.4.2 clearAllData 1520
34.4.3 defineSpecialModels 1521
34.4.4 getSelectedCells 1522
34.4.5 setCameraProperties 1523
34.4.6 setMapData 1524
34.4.7 setRequiredSelectionsCount 1525
34.4.8 setSelectedCells 1526
35. Phone 1528
35.1 Phone - Basic Properties 1530
35.1.2 id 1531
35.1.4 skin 1532
35.1.5 text 1532
35.2 Phone - Layout Properties 1532
35.2.3 hExpand 1535
35.2.4 margin 1536
35.2.6 padding 1538

35.2.8 vExpand 1541
36. PickerView 1544
36.1 PickerView - Basic Properties 1547
36.1.2 id 1549
36.1.3 info 1550
36.1.9 skin 1558
36.2 PickerView - Layout Properties 1559
36.2.2 hExpand 1560
36.2.3 margin 1562
36.3 PickerView - Event 1566
36.4 PickerView - Methods 1567
36.4.1 setComponentData 1568
36.4.2 setSelectedKeyInComponent 1569
37. SegmentedUI 1571
37.1 SegmentedUI - Basic Properties 1578
37.1.1 alternateRowSkin 1579

37.1.2 data 1580
37.1.4 id 1585
37.1.5 info 1586
37.1.7 needPageIndicator 1588
37.1.9 pageOnDotImage 1591
37.1.10 pageOffDotImage 1592
37.1.11 pullToRefreshI18NKey 1593
37.1.12 pullToRefreshSkin 1593
37.1.13 pushToRefreshI18NKey 1594
37.1.14 pushToRefreshSkin 1595
37.1.15 releaseToPullRefreshI18NKey 1596
37.1.16 releaseToPushRefreshI18NKey 1596
37.1.17 retainSelection 1597
37.1.18 rowSkin 1598
37.1.19 rowFocusSkin 1599
37.1.20 rowTemplate 1600
37.1.22 sectionHeaderSkin 1603
37.1.23 sectionHeaderTemplate 1604
37.1.24 selectedRowIndex 1606
37.1.25 selectedRowIndices 1607
37.1.26 selectedRowItems 1609
37.1.27 selectionBehavior 1609
37.1.28 selectionBehaviorConfig 1611
37.1.29 separatorColor 1612

37.1.30 separatorRequired 1613
37.1.31 separatorThickness 1614
37.1.33 viewType 1616
37.1.35 widgetDataMap 1625
37.1.36 widgetSkin 1627
37.2 SegmentedUI - Layout Properties 1628
37.2.4 gridCell 1632
37.2.8 margin 1636
37.2.10 padding 1639
37.3 SegmentedUI - Platform Specific Properties 1643
37.3.2 border 1644
37.3.3 bounces 1646
37.3.5 defaultSelection 1650
37.3.6 dockSectionHeaders 1651
37.3.7 editStyle 1652
37.3.8 enableDictionary 1654

37.3.9 indicator 1656
37.3.10 pressedSkin 1657
37.3.11 progressIndicatorColor 1658
37.3.12 searchBy 1660
37.3.13 searchCriteria 1661
37.4 SegmentedUI - Events 1666
37.4.1 onDidFinishDataLoading 1666
37.4.2 onEditing 1667
37.4.3 onRowClick 1668
37.4.4 onSwipe 1669
37.5 SegmentedUI - Methods 1676
37.5.1 addAll 1676
37.5.3 addSectionAt 1679
37.5.6 removeSectionAt 1683
37.5.7 setData 1684
37.5.9 setSectionAt 1686
37.6 SegmentedUI - Templates 1689
37.6.1 What is a Template for SegmentedUI 1689
37.6.2 Where to use a SegmentedUI (section) Template 1689

37.6.3 Creating a Template for SegmentedUI 1689
37.6.4 Using SegmentedUI Section Template 1690
38. Switch 1691
38.1 Switch - Basic Properties 1693
38.1.1 id 1693
38.1.2 info 1694
38.1.4 leftSideText 1696
38.1.5 Left Text i18n Key 1697
38.1.6 rightSideText 1698
38.1.7 Right Text i18n Key 1699
38.1.9 skin 1701
38.2 Switch - Layout Properties 1702
38.2.2 margin 1703
38.3 Switch - Events 1709
38.3.1 onSlide 1709
39. SignatureCapture 1711
39.1 SignatureCapture - Basic Properties 1712
39.1.1 id 1712
39.1.2 info 1713
39.1.4 penWidth 1715
39.1.5 rawBytes 1716
39.1.6 skin 1717

39.2 SignatureCapture - Layout Properties 1718
39.2.2 hExpand 1719
39.2.3 margin 1720
39.2.5 padding 1723
39.2.7 vExpand 1726
39.3 SignatureCapture - Platform Specific Properties 1729
39.3.1 accessMode 1729
39.4 SignatureCapture - Event 1731
39.4.1 onCapture 1731
39.5 SignatureCapture - Methods 1732
39.5.1 clear 1732
39.5.2 save 1733
40. Video 1734
40.1 Video - Basic Properties 1737
40.1.1 id 1737
40.1.3 skin 1739
40.1.4 source 1740
40.1.5 text 1741
40.2 Video - Layout Properties 1742
40.2.2 margin 1743
40.2.3 padding 1745

40.3 Video - Platform Specific Properties 1749
40.3.1 controls 1749
40.3.2 poster 1750
41. App Menu 1751
41.1 Common Properties 1753
41.1.1 Skin 1753
41.1.2 Focus Skin 1754
41.1.3 ID 1754
41.1.4 Title 1754
41.1.5 Icon 1755
41.1.6 Render 1755
41.1.7 i18n Key 1756
41.1.8 Event 1756
41.2 App Menu - Platform Specific Properties 1757
41.2.1 Needs Separator 1757
41.2.2 Appbar Button Style 1758
41.2.3 Position 1758
41.3 Methods 1759
41.3.1 createAppMenu 1759
41.3.2 setCurrentAppMenu 1761
41.3.3 getCurrentAppMenu 1762
41.3.4 setAppMenuFocusByID 1763
41.3.5 addAppMenuItemAt 1764
41.3.6 removeAppMenuItemAt 1765
41.3.7 setAppMenuBadgeValue 1766
41.3.8 getAppMenuBadgeValue 1767
41.4 Methods 1768
41.4.1 setAppMenu 1768

41.4.2 setAppMenuFocusIndex 1770
41.4.3 showAppMenuItems 1771
41.4.4 hideAppMenuItems 1771
42. Accessibility (508 Compliance) 1773
42.1 Defining accessibilityConfig for a Widget in Kony Studio 1775
42.2 Widget Behavior When Accessibility is Enabled 1778
42.3 Container Widgets 1779
42.3.1 Form 1779
42.3.2 HBox 1780
42.3.3 VBox 1781
42.3.4 ScrollBox 1782
42.3.5 Popup 1783
42.4 Basic Widgets 1784
42.4.1 Button 1785
42.4.2 Calendar 1785
42.4.3 CheckBox 1786
42.4.4 ComboBox 1787
42.4.5 Image 1788
42.4.6 Label 1789
42.4.7 Line 1789
42.4.8 Link 1789
42.4.9 ListBox 1790
42.4.10 RadioButton 1791
42.4.11 RichText 1792
42.4.12 Slider 1793
42.4.13 TextArea 1793
42.4.14 TextBox 1794
42.5 Advanced Widgets 1794

42.5.1 Alert 1794
42.5.2 Camera 1795
42.5.3 Hz Image Strip 1795
42.5.4 PickerView 1796
42.5.5 SegmentedUI - TABLEVIEW 1797
42.5.6 SegmentedUI - PAGEVIEW 1798
42.5.7 Switch 1799
42.6 Accessibility Best Practices 1799
42.7 Accessibility: Platform Specific Limitations 1799
42.7.1 SPA 1800
43. Widget Level Animation 1801
43.1 Layout Animation 1802
43.2 Animation Limitations 1804
44. Appendix A: Layout 1806
44.1 HBox Behavior 1807
44.1.1 Scenario 1 (General Layout) 1807
44.1.2 Scenario 2 (Alignment) 1810
44.2 VBox Behavior 1817
44.2.1 Scenario 1 1817
45. Appendix B: Platform Specific Limitations 1821
45.1 Desktop Web Limitations 1821
45.2 SPA Limitations 1822
45.3 Windows 7/8/8.1 Kiosk 1823
45.4 BlackBerry 10 1823
46. Glossary 1826

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 Explanation
n User input text, system prompts and responses
n File Path
Monospace n Commands
n Program Code
n File Names.
n Emphasis
Italic n Names of Books and Documents
n New Terminology.
n Windows
n Menus
n Buttons
Bold n Icons
n Fields
n Tabs
n 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 Tablet Windows Kiosk

Windows Phone 7.5 Windows 8.1 Windows 7 Kiosk
Windows Phone 8 Windows 8 Kiosk
Windows Phone 8.1 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
l HBox
l VBox
l TabPane
l Popup
l 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:

l Button
l Calendar
l CheckBoxGroup
l ComboBox
l DataGrid
l Image
l Label
l Line
l Link
l ListBox
l MenuItem
l RadioButtonGroup
l RichText
l Slider
l TextArea
l TextBox
2.1.3 Advanced Component Widgets
The following is a list of Advanced Component Widgets:
l Browser
l Camera
l Chart
l Hz Image Strip
l ImageGallery
l Map
l ObjectSelector3D
l Phone
l PickerView
l Segment
l Switch
l SignatureCapture
l Video
2.2 Widget Methods

The methods which are common for all the widgets are as follows:

l setVisibility
l setFocus
l setEnabled
l setGestureRecognizer
l removeGestureRecognizer
l setBadge
l 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
l VBox
l Button
l Calendar
l Image
l Label
l 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.
l 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.
l 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.
l 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.
l 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.

l constants.ANIMATION_CURVE_EASEOUT: Specifies the animation

effect to slowdown towards the end.
l constants.ANIMATION_CURVE_EASEINOUT: Specifies the animation
effect to start slow and slowdown towards the end.
l 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()
l 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
l 2 for SWIPE
l 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.
l 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.
l 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.
l 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

l 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.
l 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.
l gesturesetUpParams [object] - this array is the set up parameters passed
while adding the gesture recognizer.
l 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.
l 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.
l 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.
l 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.

l widgetWidth [number] - specifies the width of the widget (in pixels).
l 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
l Android
l BlackBerry
l Windows Phone
l 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
l Android
l BlackBerry
l Windows Phone
l 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
l 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:
Windows
Android/
iPhone Mango/ Mobile
Widget Android BlackBerry SPA/Playbook
/iPad Windows Web
Tablet
6.x
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
ComboBox Yes Yes Yes Yes
Image Yes Yes Yes Yes
Label Yes Yes Yes Yes Yes Yes
Line Yes Yes
Link Yes Yes Yes Yes
ListBox Yes Yes Yes Yes Yes
RadioButtonGroup Yes Yes Yes Yes Yes
Rich Text Yes Yes Yes

Windows
Android/
iPhone Mango/ Mobile
Widget Android BlackBerry SPA/Playbook
/iPad Windows Web
Tablet
6.x
TextArea Yes Yes Yes Yes
TextBox Yes Yes Yes Yes
ScrollBox Yes Yes Yes Yes Yes Yes
Yes
Signature (supported
on 6.x)
Video Yes Yes

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).

l Supports a skin for SegmentedUI only when the groupCells property is set to false.
l Does not support Font weight and style attributes for skins.
l Does not support adding skins for the default App Menu items.
J2ME
l Do not support transparency for widgets (background, font, and border).
BlackBerry
l Supports transparency for background and borders. Transparency is not supported for Fonts.
l 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.
l 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
l Platforms do not support adding skins for the default App Menu items.
Mobile Web
l Basic and BJS versions does not support rounded borders.

l Does not support Focus Skin.
l Devices that support BJS do not support vertical split and gradient attributes in the skin.
l 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
l 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

l 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
l 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.

l Transparency in font color, background color, and border colors.
l Borders for Label, Link, RichText, CheckBox, and RadioButton widgets.
l Focus skins for all widgets.
l Rounded corners for borders for all widgets.
l 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.
l 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.
l 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.

l 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.

l Focus skins for all widgets.
l Rounded corners for borders for all widgets.
l Vertical split and gradient for all widgets.
l 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.
l 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
l HBox
l VBox
l TabPane
l Popup
l 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,

l accessing its properties,
l for showing the form through the show method,
l 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
l form1.title

l 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 gridCell animateHeaderFooter
headers layoutMeta bounces
id layoutType captureGPS
info padding contextPath
menuFocusSkin paddingInPixel configureExtendTop
menuItems configureExtendBottom
menuNormalSkin configureBarStyle
needAppMenu defaultIndicatorColor
skin enablePeekGesture
extendTop
title extendBottom
type statusBarStyle
footerOverlap
formTransperencyDuringPostShow
headerOverlap
inputAccessoryViewType
inTransitionConfig
layout
maxAppMenuButtons
menuPosition
needsIndicatorDuringPostShow
noCache
outTransitionConfig
retainScrollPosition
scrollDirection
secureData
showBottomActionBar
showActionBar
showActionBarIcon
showMiniAppMenu
submitSecure
titleBar
titleBarConfig
titleBarSkin
windowSoftInputMode
Events Methods Deprecated

addWidgets add dockableAppMenu
init addAt dockableHeader
onActionBarBack show dockableFooter
onHide destroy enableback
onOrientationChange remove IgnoreEscape
onDeviceBack removeAt masterdataload
onDeviceMenu replaceAt menuRenderer
onDestroy widgets transactionaldataload
preShow setTitleBarLeftSideButtonSkin Undock App Header
postShow setTitleBarRightSideButtonSkin Undock App Footer


onLoadJS setTitleBarSkin
unLoadJS showTitleBar
hideTitleBar
scrollToWidget
scrollToBeginning
scrollToEnd
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.

l layoutConf is an object with layout properties.
l 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:

l Native
l Web-based
l Static
l 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 UIWebView UIWebView
to display form
UI definition (the
packaged along with the packaged along with the downloaded from the
widget layout and
application application server
skins)
UI logic (logic that
alters the user packaged along with the packaged along with the downloaded from the
experience based on application application server
business rules)
downloaded from the downloaded from the
Business Data downloaded from the server
server 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
l footers
l headers
l id

l info
l menuFocusSkin
l menuItems
l menuNormalSkin
l needAppMenu
l skin
l title
l 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
l iPhone
l BlackBerry
l 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",

var frmPSP ={};
//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)
l FORM_TYPE_STATIC
l 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
l gridCell
l layoutMeta
l layoutType
l padding
l 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.
l FORM_DISPLAY_ORIENTATION_LANDSCAPE - On the device the form is always turned sideways
so that the height of the screen becomes width.
l 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.
l rowSpan: Specifies the number of rows that a grid should span. Default value is 1.
l rowNo: Specifies the row number in where the widget is placed in a grid layout.
l 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
l 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
l 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.
l 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
l 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
4.2.6 paddingInPixel
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
l iPad
l Windows Phone
l BlackBerry 10

4.3 Form - Platform Specific Properties

The platform specific properties for Form Widget are as follows:
l actionBarIcon
l animateHeaderFooter
l bounces
l captureGPS
l contextPath
l configureExtendTop
l configureExtendBottom
l configureBarStyle
l defaultIndicatorColor
l enablePeekGesture
l extendTop
l extendBottom
l statusBarStyle
l footerOverlap
l formTransperencyDuringPostShow
l headerOverlap
l inputAccessoryViewType
l inTransitionConfig
l layout
l maxAppMenuButtons
l menuPosition
l needsIndicatorDuringPostShow
l noCache
l outTransitionConfig
l retainScrollPosition
l scrollDirection
l secureData
l showBottomActionBar
l showActionBar
l showActionBarIcon
l showMiniAppMenu
l submitSecure
l titleBar
l titleBarConfig

l titleBarSkin
l viewConfig
l 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
l 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)

l Server side Mobile Web (BJS)
l Server side Mobile Web (advanced)

4.3.6 configureExtendTop
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
l 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
l 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
l 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
l 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
l 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
l 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.
l 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
l 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
l 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
l 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
l iPad
4.3.17 inputAccessoryViewType
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.
l 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.
l 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.

l 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
l iPad
4.3.18 inTransitionConfig
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.
transitionDuration: Specifies the duration after which the transition is applied on the Form. The default value
is 0.3 seconds.
transitionDirection: Specifies the direction from which the Form 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 Y-
axis 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:{transitionDuration:"0.5", transitionEffec
t:"transitionMoveIn", 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.

l 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
l Windows Tablet
l 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

l FORM_MENU_POSITION_BEFORE_APPMENU
l 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
l 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

4.3.24 outTransitionConfig
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.

transitionDuration: Specifies the duration after which the transition is applied on the Form. The default value
is 0.3 seconds.
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 Y-
axis 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:{transitionDuration:"0.5", transitionEffe
ct:"transitionMoveIn", 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.
4.3.26 scrollDirection
Specifies the direction in which the form should scroll.
Default : SCROLL_VERTICAL
l SCROLL_VERTICAL: Specifies the form to scroll in vertical direction.

l 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
l 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

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
4.3.31 showMiniAppMenu
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


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.
l 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 iPhone 5th iPad (1st, 2nd, and 3rd
4th Generations Generation Generations)
Portrait Mode (Non-Retina) 320x44 px NA 768x44 px
Portrait Mode (Retina) 640x88 px 640x88 px 1024x44 px
Landscape Mode (Non-Retina) 480x32 px NA 1536x88 px
Landscape Mode (Retina) 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
l iPhone
l Android
l BlackBerry
l BlackBerry 10
l Windows Tablet
4.3.34 titleBarConfig
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.
3. Click the Ellipsis ( ) button to open the titleBarConfig screen for the respective platform.
l renderTitleText
l titleBarRightSideView
l closureRightSideView
l titleBarLeftSideView
l closureLeftSideView
l imageRightSideView
l imageLeftSideView
Following are the available options for Windows Tablet:

l Show Form Titlebar : Specifies if the form title must be visible or invisible.
l 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
l iPad
l Android
l 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
l Android
l 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, refer Kony Studio User Guide.
ViewConfig displays two types of views:
l Normal view
l Grid view - Windows 8 or 8.1
Following are the available properties:

n view: Specifies the type of view to be rendered. This option is available in both Normal grid and Grid
view. Following are the available options :
l constants.CONTAINER_LAYOUT_GRID (Default option)

l constants.CONTAINER_LAYOUT_GRIDVIEW
n gridSizeMode: Specifies the behavior of the grid with respect to size, rows, and columns. This option
is available in both Normal grid and Grid view. The available options are:
l fixed grid - Use this option to fix the number of rows and columns. For example, columns
= 4, rows = 2.
1234
5678
l Vertically expand - Use this option to fix the number of columns and rows can grow
indefinitely. For example, columns = 3, rows = infinite.
123
456
78
l Horizontally expand - Use this option to fix the number of rows are fixed and columns
can grow indefinitely. For example, rows = 3, columns = infinite.
147
258
36
n referenceWidth: Specifies the width of the cell. This option is supported in Grid view only.
Type: Number
Default Value: 0 (Accepts positive numbers only)
n referenceHeight: Specifies the height of the cell. This option is supported in Grid view only.
Type: Number
n onClick: If an onClick event is defined on a widget, the event callback is invoked by the platform when
the user performs a click action in each cell. This option is supported in Grid view only.
n enableItemClick: This property enables the click behavior on each cell in grid view.This option is
supported in Grid view only.
Type: Boolean
Default Value: false (item click is disabled)
n selectionMode: This property enables you to select the items in grid view. This option is supported in
Grid view only.

l 0 - None
l 1 - Single
l 2 - Multiple
Note: When you set righttap event using setGestureRecognizer to a container widget, the
selection mode will be considered from righttap gesture arguments, the values you entered are
ignored.
Type: Number
Default Value: 0
n onSelect: An event callback is invoked by the platform when you right tap using mouse or selects with
touch. This option is supported in Grid view only.
Note: This event is invoked only when you set selectionModeView!=0 (None). If you set
righttap event using setGestureRecognizer to a container widget, righttap gesture callback is
set to onSelect automatically.
n orientation: Specifies the orientation of the grid. This option is supported in Grid view only.
l 0 - Horizontal
l 1 - Vertical
Type: Number
Default Value: When the value is not provided, it the rowCount is more than 0
and gridSizeMode is set to constants.GRID_SIZE_MODE_VERTICAL, the
orientation is set to "vertical" else it is set to "Horizontal".
Syntax
JavaScript: viewConfig
Lua: viewconfig
Type
JavaScript:JSObject
Lua: table
Read / Write
Yes ( write will work only if it is called in application's preappinit() )

JavaScript Example
//Defining properties for a form with viewConfig

e"};
var frmPSP ={viewConfig: {
referenceHeight: 40,
gridSizeMode: constants.GRID_TYPE_FIXED,
referenceWidth: 30
};
};
//Creating a form.
Accessible from IDE
Yes
This property is available on Windows Tablet platform.
4.3.37 windowSoftInputMode
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.
l 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
l init
l onActionBarBack
l onHide
l onOrientationChange
l onDeviceBack
l onDeviceMenu
l onDestroy
l preShow
l postShow
l onLoadJS
l 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 re-
initialized 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

l 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.

l 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.

4.4.5 onOrientationChange
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
l BlackBerry 10
l Desktop Web
l 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
l addAt
l show
l destroy
l remove
l removeAt
l replaceAt
l widgets
l setTitleBarLeftSideButtonSkin
l setTitleBarRightSideButtonSkin
l setTitleBarSkin
l showTitleBar
l hideTitleBar
l scrollToWidget
l scrollToBeginning
l 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.
l 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.



to end.


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.
l constants.ANIMATION_EFFECT_FADE: Specifies the widget must
disappear gradually by increasing the transparency of the widget.

to end.


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.
l 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.



l constants.ANIMATION_EFFECT_FLIP_RIGHT: Specifies the widget

must flip from right to left.
l 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.

to end.



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
l 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();
4.5.9 setTitleBarLeftSideButtonSkin
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 and image properties only.
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.
4.5.10 setTitleBarRightSideButtonSkin
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 supports fontColor and image properties only.
callBack [event call back]- Mandatory

Specifies the event call back to be invoked on tapping right button.
Return Values
None
Exceptions
None
4.5.11 setTitleBarSkin
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
4.5.14 scrollToWidget
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.
4.5.15 scrollToBeginning
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
l dockableHeader
l dockableFooter
l enableback
l Ignore Escape
l masterdataload
l menuRenderer
l transactionaldataload
l undockappheader
l undockappfooter

Alternative Property to be
Deprecated Properties
used
dockableAppMenu By default appmenu should dock
dockableHeader headers
dockableFooter footers
enableback na
ignoreescape na
masterdataload init
menuRenderer na
transactionaldataload init
undockappheader
undockappfooter
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
l 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
l 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
l 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
l 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
Basic Properties Layout Properties
Properties
focusSkin containerWeight blockedUISkin
id gridCell borderCollapse
info layoutMeta contextMenu
isVisible layoutType hoverSkin
orientation layoutAlignment viewConfig
position margin
skin marginInPixel
padding
paddingInPixel
percent
vExpand
widgetAlignment

onClick add
onHover addAt
onRightClick remove
preOnclickJS removeAt
postOnclickJS 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.

l layoutConf is an object with layout specific configuration properties.
l 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
l id
l info
l isVisible
l orientation
l position
l 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.

l BOX_POSITION_AS_HEADER: The box is fixed at the top of the form.
l BOX_POSITION_AS_FOOTER: The box is fixed at the bottom of the form.
l 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
l gridCell
l layoutMeta
l layoutType
l layoutAlignment
l margin
l marginInPixel
l padding
l paddingInPixel
l percent
l vExpand
l widgetAlignment
5.2.1 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.
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:
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
l 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
l Desktop Web
5.2.4 layoutType
Defines the type of the layout of container widget. Following are the available options:
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
l Desktop Web
5.2.5 layoutAlignment
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.

l BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets placed inside a box are aligned center.
l 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 ( ) button against the property to open 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
l iPad
l 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.

l Windows Phone/Windows Kiosk - Not supported for Box, Image Gallery due to Browser limitation.
l Mobile Web (BJS) - Not supported for ComboBox, Form, and ListBox due to Browser limitations.
l 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
l iPad
l 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.
Note: For SPA or Desktop web, if percent value is set to false (percent=false), and if Hbox has Vbox in it,
rendering may not be consistent with richclients. If Hbox has any Vbox inside it, avoid using false as a value
for percent and instead, use true (percent=true).
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.
5.2.12 widgetAlignment
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)

l WIDGET_ALIGN_TOP_CENTER
l WIDGET_ALIGN_TOP_RIGHT
l WIDGET_ALIGN_MIDDLE_LEFT
l WIDGET_ALIGN_CENTER - (BlackBerry 10 supports this option)
l WIDGET_ALIGN_MIDDLE_RIGHT
l WIDGET_ALIGN_BOTTOM_LEFT

l WIDGET_ALIGN_BOTTOM_CENTER
l 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

l SPA
l Desktop Web

5.3 HBox - Platform Specific Properties

The platform specific properties for HBox Widget are as follows:
l blockedUISkin
l borderCollapse
l contextMenu
l hoverSkin
l 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
5.3.2 borderCollapse
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

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).

l You can choose to add icons to indicate the menu items in the context menu (applicable only on
BlackBerry versions 6.x and above).
l 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.
l 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.
l 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 Touch Device BlackBerry Non-Touch

BlackBerry 6.x
(<6.x) 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
l Windows Phone
l 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
l Desktop Web
5.3.5 viewConfig
l Normal view

= 4, rows = 2.
1234
5678
123

456
78
147
258
36
Type: Number
Type: Number
Type: Boolean
Grid view only.
l 0 - None
l 1 - Single
l 2 - Multiple
ignored.
Type: Number
Default Value: 0


l 0 - Horizontal
l 1 - Vertical
Type: Number
Syntax
Lua: viewconfig
Type
JavaScript:JSObject
Lua: table
Read / Write
Yes
JavaScript Example
//Defining the properties for a Box

var PSPConfBox = { viewConfig: {
referenceHeight: 0,
gridSizeMode: "constants.GRID_TYPE_FIXED",
referenceWidth: 0
}
};
//Creating the box.

boxIdTest = new kony.ui.Box(basicConfBox, layoutConfBox, PSPConfBox );

Accessible from IDE
Yes

5.4 HBox - Events

HBox Widget has the following event associated with it:
l onClick
l onHover
l onRightClick
l preOnclickJS
l 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

{
}

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.

l When the mouse moves with in the widget region.
l 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;
l Data / computing intense operations should not be performed in onHover callback.

l Avoid network calls in onHover event as it affects the performance.
l Use this event to update the skin.
l When an onHover event is defined to both parent and child widgets, the onHover event executes as
follows:

o When mouse moves into parent widget, then MOUSE_ENTER event gets fired on the parent
widget.
o When mouse moves inside the parent widget, then MOUSE_MOVE event is fired continuously
till mouse moves inside the parent widget.
o When mouse moves into the child widget area, then MOUSE_ENTER event gets fired on the
child widget.
o When mouse moves inside the child widget area, then MOUSE_MOVE event is fired on child
widget and also on the parent widget.
o 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.
o 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
l addAt
l remove
l removeAt
l replaceAt
l 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)
Note: The parameter animationConfig is supported only on iOS (version 5.0 and above) and Android
Lua:box.addat (boxid, widgetref, index)

Input Parameters

Reference of the widget to be added




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.


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.




must collapse gradually by decreasing the height of the widget.

to end.



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

animationConfig[JSObject] - Optional




to end.



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
l 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);

5.6 Context Menu- Templates
Note: Context Menu templates are supported only on Desktop Web platform.
5.6.1 What is a Template for a Context Menu
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.
5.6.2 Where to use a Context MenuTemplate
Context Menu Templates are used to display how the data is presented to the end user when a context menu
pops up.
5.6.3 Creating a Template for Context Menu
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.
5.6.4 Using Context Menu Template
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
id gridCell borderCollapse
info layoutMeta contextMenu
isVisible layoutType hoverSkin
orientation layoutAlignment viewConfig
skin margin
marginInPixel
padding
paddingInPixel
widgetAlignment

onClick add
onHover addAt
onRightClick remove
preOnclickJS removeAt
postOnclickJS 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.

l layoutConf is an object with layout specific configuration properties.
l 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
l id
l info
l isVisible
l orientation
l 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
l gridCell
l layoutMeta
l layoutType
l layoutAlignment
l margin
l marginInPixel
l padding
l paddingInPixel
l 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:

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
l 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
l Desktop Web

6.2.4 layoutType
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
l 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.

l BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets placed inside a box are aligned center.
l 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
l 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.

l Windows Phone/Windows Kiosk - Not supported for Box, Image Gallery due to Browser limitation.
l Mobile Web (BJS) - Not supported for ComboBox, Form, and ListBox due to Browser limitations.
l 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
l iPad

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
l Desktop Web

6.3 VBox - Platform Specific Properties

The platform specific properties for VBox Widget are as follows:
l blockedUISkin
l borderCollapse
l contextMenu
l hoverSkin
l 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
6.3.2 borderCollapse
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

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.

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 Touch Device BlackBerry Non-Touch

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
l Windows Tablet
l Desktop Web
6.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE
Yes

l Windows Tablet
l Desktop Web
6.3.5 viewConfig
l Normal view

= 4, rows = 2.
1234
5678
123
456
78
147
258
36
Type: Number
Type: Number

Type: Boolean
Grid view only.
l 0 - None
l 1 - Single
l 2 - Multiple
ignored.
Type: Number
Default Value: 0
l 0 - Horizontal
l 1 - Vertical
Type: Number
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
l onHover
l onRightClick
l preOnclickJS
l 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.

l When the mouse moves with in the widget region.
l 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;
l Data / computing intense operations should not be performed in onHover callback.

l Avoid network calls in onHover event as it affects the performance.
l Use this event to update the skin.
l When an onHover event is defined to both parent and child widgets, the onHover event executes as
follows:

o When mouse moves into parent widget, then MOUSE_ENTER event gets fired on the parent
widget.
o When mouse moves inside the parent widget, then MOUSE_MOVE event is fired continuously
till mouse moves inside the parent widget.
o When mouse moves into the child widget area, then MOUSE_ENTER event gets fired on the
child widget.
o When mouse moves inside the child widget area, then MOUSE_MOVE event is fired on child
widget and also on the parent widget.
o 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.
o 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
l addAt
l remove
l removeAt
l replaceAt
l 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






to end.


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.




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

to end.



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

animationConfig[JSObject] - Optional




to end.



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
l 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();


6.6 Context Menu- Templates
Note: Context Menu templates are supported only on Desktop Web platform.
6.6.1 What is a Template for a Context Menu
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.
6.6.2 Where to use a Context MenuTemplate
Context Menu Templates are used to display how the data is presented to the end user when a context menu
pops up.
6.6.3 Creating a Template for Context Menu
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.
6.6.4 Using Context Menu Template
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.

enableScrollByPage containerHeight bounces
id containerHeightReference contextMenu
info containerWeight scrollArrowConfig
isVisible layoutAlignment viewConfig
orientation margin
position marginInPixel
pullToRefreshI18NKey padding
pullToRefreshSkin paddingInPixel
pushToRefreshI18NKey percent
pushToRefreshSkin
releaseToPullRefreshI18NKey
releaseToPushRefreshI18NKey
scrollDirection
showScrollBars
skin
Methods Events Deprecated

add scrollingEvents fixedHeight
addAt heightReference
remove scrollOption
removeAt sizePercent
scrollToBeginning WidgetDirection
scrollToEnd Use widget size %
scrollToWidget
widgets
Creating a ScrollBox using a constructor: kony.ui.ScrollBox
var scrollbox1 = new kony.ui.ScrollBox(basicConf, layoutConf, pspConf)


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.

l padding: Defines the space between the content of the widget and the widget boundaries.
l 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 non-
percentage layout the width of the ScrollBox varies across platforms.
l If you set the scrollDirection as SCROLLBOX_SCROLL_VERTICAL or SCROLLBOX_SCROLL_
BOTH, specifying a containerHeight is mandatory.
l 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.

l For BlackBerry platforms, to navigate the contents within a ScrollBox, arrows are used instead of
scrollbars.
l Only Horizontal Scrolling is applicable for BlackBerry.
7.1 ScrollBox - Basic Properties

The basic properties of ScrollBox Widget are as follows:
l enablesScrollByPage
l id
l info
l isVisible
l orientation
l position
l pullToRefreshI18NKey
l pullToRefreshSkin
l pushToRefreshI18NKey
l pushToRefreshSkin
l releaseToPullRefreshI18NKey
l releaseToPushRefreshI18NKey
l scrollDirection
l showScrollbars
l 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
l 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 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 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.
l 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.
l BOX_POSITION_AS_FOOTER: Specifies the position of the ScrollBox is fixed at the bottom of the
Form.
l BOX_POSITION_AS_NORMAL: Retains the original position of the ScrollBox.
l 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.
l 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.
7.1.7 pullToRefreshI18NKey
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
7.1.8 pullToRefreshSkin
Specifies the skin to be applied to the pull to refresh title.
Following are the skin definition properties:
l font_weight
l font_style
l font_size
l font_color
l font_name
l background_color
l bg_type
l 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
7.1.9 pushToRefreshI18NKey
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
7.1.10 pushToRefreshSkin
Specifies the skin to be applied to the push to refresh title.
l font_weight
l font_style
l font_size
l font_color
l font_name

l background_color
l bg_type
l background_style
Syntax
JavaScript: pushToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE
Yes
7.1.11 releaseToPullRefreshI18NKey
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

7.1.12 releaseToPushRefreshI18NKey
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
7.1.13 scrollDirection
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.
l SCROLLBOX_SCROLL_VERTICAL: Enables you to scroll the content within the ScrollBox vertically.
(Applicable on iPhone and Android platforms only)
l SCROLLBOX_SCROLL_BOTH: Enables you to scroll the content within the ScrollBox horizontally as
well as vertically. (Applicable on iPhone and Android platforms only)
l 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
7.1.14 showScrollbars
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 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 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
l containerHeightReference
l containerWeight
l layoutAlignment
l margin
l marginInPixel
l padding
l paddingInPixel
l percent

7.2.1 containerHeight
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.
Additional rules for containerHeight property based on the scrollDirection:
l When the scrollDirection is set to SCROLLBOX_SCROLL_NONE or SCROLLBOX_SCROLL_

HORIZONTAL preferred height is determined by the child widget.
l When the scrollDirection is set to SCROLLBOX_SCROLL_BOTH or SCROLLBOX_SCROLL_
VERTICAL preferred height is determined as follows:
containerHeight containerHeightReference Result

Height determined by its
Not provided Not provided
child widgets
SCROLLBOX_HEIGHT_BY_FORM_REFERENCE / Height determined by its
Not provided
SCROLLBOX_HEIGHT_BY_PARENT_WIDTH child widgets
Assume
containerHeightReferenc
>=0 Not provided e as SCROLLBOX_
HEIGHT_BY_FORM_
REFERENCE
Based on
containerHeight and
>=0 SCROLLBOX_HEIGHT_BY_FORM_REFERENCE
e appropriately
Based on
containerHeight and
>=0 SCROLLBOX_HEIGHT_BY_PARENT_WIDTH
e appropriately
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 scrollPSP = {};

P);
Accessible form IDE
No
Platform availability
7.2.2 containerHeightReference
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.
l 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
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.containerHeightRef
erence);
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.

l BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets are aligned center.
l 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
5,5], containerHeight:100, percent:false, layoutAlignment:constants.BOX_LA
YOUT_ALIGN_FROM_CENTER};
var scrollPSP = {};

P);
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 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.

5,5], containerHeight:100, percent:true, marginInPixel:true};
var scrollPSP = {};
//Creating a ScrollBox.
P);
Accessible from IDE
Yes
l iPhone
l 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
l 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
l contextMenu
l scrollArrowConfig
l showFadingEdges
l 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 scrollPSP = {bounces:true };

P);
Accessible from IDE
Yes
l iPhone
l iPad
7.3.2 contextMenu
Note: The property is available only on BlackBerry platform.

The following images illustrates the context menu on various BlackBerry devices:
BlackBerry Non-Touch
BlackBerry 6.x BlackBerry Touch Device
Device
Syntax
Lua: contextmenu
Type
Lua: Table
Read / Write
JavaScript Example
//Defining contextMenu items for Windows 8 platform.

allbackMenuItem1 };
var appMenu3 = {id:"appmenuitemid3", text:"Edit", image:"tc.png",

onclick:callbackMenuItem3};
callbackMenuItem4};
{
}
{
}
{
}
{
}
//Defining properties for a ScrollBox with contextMenu:[appMenu1,appMenu2,

appMenu3,appMenu4]
var scrollPSP = {contextMenu:[appMenu1,appMenu2,appMenu3,appMenu4]};

P);
Accessible from IDE
No
l BlackBerry
l 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.

l rightArrow : Specifies the image location of the right arrow.
l topArrow : Specifies the image location of the top arrow.
l 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 scrollPSP = {scrollArrowConfig:["leftArrow.png", "topArrow.png", "rig
htArrow.png", "bottomArrow.png"] };

P);
Accessible from IDE
Yes

l Desktop Web

7.3.4 showFadingEdges
Specifies whether the horizontal and vertical edges of the ScrollBox should appear as faded when it is scrolled
horizontally or vertically.
Default:true
If set to false, the scroll view horizontal and vertical edges are not faded when scrolled.
If set to true, the scroll view horizontal and vertical edges will appear as faded when scrolled.
Syntax
JavaScript: showFadingEdges
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining properties for a ScrollBox with showFadingEdges:true

var scrollPSP = {showFadingEdges:true };

P);
Accessible from IDE
No
This property is available on Android platform.
7.3.5 viewConfig
Note: For more information on applying the Grid layout please refer Kony Studio User Guide.

l Normal view
l 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
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 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
7.4.1 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.
l 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
l addAt
l remove
l removeAt
l scrollToBeginning
l scrollToEnd
l scrollToWidget
l 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 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 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
l Android
l SPA(iPhone/Android)
l Windows Tablet
l 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
l Android
l SPA(iPhone/Android)
l Windows Tablet
l 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
l Android
l Windows Tablet
l Windows Phone
l 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.

activeFocusSkin containerHeight pageSkin
activeSkin containerHeightReference progressIndicatorColor
activeTabs containerWidget showProgressIndicator
id gridCell tabHeaderTemplate
inactiveSkin layoutMeta tabHeaderHeight
info layoutType
isVisible margin
retainPositionInTab marginInPixel
screenLevelWidget padding
viewConfig paddingInPixel
viewType
Events Methods
onTabClick addTab
preOnclickJS addTab
postOnclickJS 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.

l margin: Defines the space around the widget.
l activeSkin: Specifies the skin that must be applied to an active tab.
l activeFocusSkin: Specifies the skin that must be applied to the Tab in focus.
l 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
l Image
l Link
l Button
l HBox
l VBox
l 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.
o If you press the down key, the focus shifts to the next widget in the TabPane.
o 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.
o If you press the right or the left arrow keys, you move to next or previous tabs.
o 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)
l On devices which have a navigation key, the following are applicable:
l 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.
l 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.
l 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
l activeSkin
l activeTabs
l id
l inactiveSkin
l info
l isVisible
l retainPositionInTab
l screenLevelWidget
l viewConfig
l 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
8.1.9 screenLevelWidget
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

l TABPANE_COLLAPSIBLE_IMAGE_POSITION_RIGHT
tabNameAlignment: Specifies the alignment to the text on the tab. Following

are the available options:
l TABPANE_COLLAPSIBLE_TABNAME_ALIGNMENT_LEFT
l 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.
l 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.
l 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.
l 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
l TAB_HEADER_POSITION_BOTTOM
l TAB_HEADER_POSITION_LEFT
l 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
l TABPANE_VIEW_TYPE_COLLAPSIBLEVIEW
l TABPANE_VIEW_TYPE_PAGEVIEW (supported on iOS, Android, and Desktop Web only)
l 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:

l containerHeight
l containerWeight
l gridCell
l layoutMeta
l layoutType
l margin
l marginInPixel
l padding
l 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:
Windows Windows Windows

View Type
Phone Tablet Kiosk
Occupies form Occupies
TABPANE_VIEW_TYPE_TABVIEW Not Applicable
height content height
Occupies Occupies Occupies
TABPANE_VIEW_TYPE_COLLAPSIBLEVIEW
content height content height content height
Occupies form
TABPANE_VIEW_TYPE_PAGEVIEW Not Applicable Not Applicable
height
Occupies form
TABPANE_VIEW_TYPE_PANORAMAVIEW Not Applicable Not Applicable
height
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.
l 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:
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
l 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
l Desktop Web

8.2.6 layoutType
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
l 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
l 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
l iPad
8.3 TabPane - Platform Specific Properties

The platform specific properties for TabPane Widget are as follows:
l pageSkin
l progressIndicatorColor
l showProgressIndicator
l tabHeaderTemplate
l 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
Yes - ( Read and 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
l iPad
8.3.2 progressIndicatorColor
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.

l 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
l iPad
8.3.3 showProgressIndicator
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
l 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
l preOnclickJS
l 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
l addTab ( applicable only on Desktop Web platform)
l addTabAt
l removeTabAt
l 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); //image
should already be made available.
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.
l To display different tab headers for different Tab panes.
l 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
footers containerHeight bounces
headers containerHeightReference captureGPS
id containerWeight contextPath
info gridCell configureExtendTop
isModal layoutMeta draggable
skin layoutType extendTop
title padding footerOverlap
transparencyBehindThePopup paddingInPixel headerOverlap
inputAccessoryViewType
inTransitionConfig
layout
minimizeOnLostFocus
noCache
outTransitionConfig
popupStyle
resizable
secureData
showMiniAppMenu
submitSecure
titleBarConfig
viewConfig
windowSoftInputMode

addWidgets add closureLeftSideView
init addAt closureRightSideView
onHide destroy dockableAppMenu
onDeviceBack dismiss imageLeftSideView
onLoadJS navigateTo imageRightSideView
unLoadJS remove nift
removeAt onOrientationChange
scrollToBeginning orientationmode
scrollToEnd renderTitleText
scrollToWidget Reset Focus to top of the Form
setContext Skin Around Popup
setTitleBarLeftSideButtonSkin titleBar


setTitleBarRightSideButtonSkin titleBarLeftSideView
setTitleBarSkin titleBarRightSideView
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
l 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.
l By default, all Popups are in full screen mode. The Popups are not positioned based on the widget
context.
l 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
l headers
l id
l info

l isModal
l skin
l title
l 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
l containerWeight
l gridCell
l layoutMeta
l layoutType
l padding
l 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.
l 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.
l 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:
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
l 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
l Desktop Web
9.2.6 layoutType
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
l 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
l iPad

9.3 Popup - Platform Specific Properties

The platform specific properties for Popup Widget are as follows:
l bounces
l captureGPS
l contextPath
l configureExtendTop
l draggable
l extendTop
l footerOverlap
l headerOverlap
l inputAccessoryViewType
l inTransitionConfig
l layout
l minimizeOnLostFocus
l noCache
l outTransitionConfig
l popupStyle
l resizable
l secureData
l showMiniAppMenu
l submitSecure
l titleBarConfig
l viewConfig
l 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
l 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

9.3.4 configureExtendTop
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
l 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
l 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
l 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
l iPad
9.3.9 inputAccessoryViewType
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.
l 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.
l 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.

l 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
l iPad
9.3.10 inTransitionConfig
Specifies the configuration to be used when the user arrives on this form. It accepts hash values.
transitionDuration: Specifies the duration after which the transition is applied on the popup. The default
value is 0.3 seconds.
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:{transitionDuration:"0.5", transitionEffec
t:"transitionMoveIn", 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.

l 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


9.3.14 outTransitionConfig
Specifies the type of transition effect to be applied when the popup is going out of view. It accepts hash
values.
transitionDuration: Specifies the duration after which the transition is applied on the popup. The default
value is 0.3 seconds.
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:{transitionDuration:"0.5", transitionEffe
ct:"transitionMoveIn", 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.

l 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

9.3.18 showMiniAppMenu
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

9.3.20 titleBarConfig
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
l 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.
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
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

9.3.22 windowSoftInputMode
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.
l 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
l init
l onHide
l onDeviceBack
l onLoadJS
l 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

l 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.

l 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
l addAt
l destroy
l dismiss
l navigateTo
l remove
l removeAt
l scrollToBeginning
l scrollToEnd
l scrollToWidget
l setContext
l setTitleBarLeftSideButtonSkin
l setTitleBarRightSideButtonSkin
l setTitleBarSkin
l showTitleBar
l hideTitleBar
l show
l 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
9.5.12 setTitleBarLeftSideButtonSkin
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.

Specifies the skin of the button. It supports fontColor, fontSize, and Image properties.
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);
9.5.13 setTitleBarRightSideButtonSkin
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.

Specifies the skin of the button. It supports fontColor, fontSize, and Image properties.
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);
9.5.14 setTitleBarSkin
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
l closureRightSideView
l defaulttransition
l dockableAppMenu
l formanimation
l formtransition
l imageLeftSideView
l imageRightSideView
l inTransitKey
l inTransitMode
l nift
l onOrientationChange

l orientationmode
l outTransitKey
l outTransitMode
l renderTitleText
l Reset_Focus_to_top_of_the_Form
l Skin_Around_Popup
l titleBar
l titleBarLeftSideView
l titleBarRightSideView
l transition
l transitionDirection
l transitionEffect
Deprecated Properties Alternative Properties

defaulttransition Mapped to InTransitionConfig
formanimation Mapped to InTransitionConfig
formtransition Mapped to InTransitionConfig
inTransitKey Mapped to InTransitionConfig
inTransitMode Mapped to InTransitionConfig
outTransitKey Mapped to OutTransitionConfig
outTransitMode Mapped to OutTransitionConfig
transition Mapped to InTransitionConfig
transitionDirection Mapped to InTransitionConfig
transitionEffect Mapped to InTransitionConfig
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)

l Mobile Web (BJS)
l 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
l Windows Phone
9.6.7 onOrientationChange
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
l J2ME
9.6.12 titleBar
Type
Boolean
Read / Write
No
Accessible from IDE
Yes
l iPhone/iPad
l 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
l Calendar
l CheckBoxGroup
l ComboBox
l DataGrid
l Image
l Label
l Line
l Link
l ListBox
l MenuContainer
l MenuItem
l RadioButtonGroup
l RichText
l Slider
l TextArea
l 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.
Platform Specific
Properties
id contentAlignment contextMenu
info displayText externalURL
isVisible hExpand glowEffect
rawBytes margin hoverSkin
skin marginInPixel pressedSkin
text padding showProgressIndicator
paddingInPixel submitURL
vExpand toolTip
widgetAlignment
Events Deprecated
onClick focusimage
preOnclickJS image
postOnclickJS normalimage
Creating a Button using a constructor: kony.ui.Button
var button1 = new kony.ui.Button(basicConf, layoutConf, pspConf)

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.
l focusSkin: Specifies the focus skin.

l hExpand: Expand the button horizontally.

l 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.
l 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
l id
l info
l isVisible
l rawBytes
l skin
l text
l 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
l contentAlignment
l displayText
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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
11.2.2 contentAlignment
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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the button.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the button.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the button.
l CONTENT_ALIGN_CENTER- Specifies the text should align at center of the button.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the button.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the button.
l CONTENT_ALIGN_BOTTOM_CENTER- Specifies the text should align at bottom center of the
button.
l 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

11.2.6 marginInPixel
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
l iPad
l 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
l iPad
l 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.


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
l contextMenu
l externalURL
l glowEffect
l hoverSkin
l pressedSkin
l submitURL
l tooltip
11.3.1 blockedUISkin
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.

BlackBerry Touch BlackBerry Non-Touch

BlackBerry 6.x
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.
l The menu items are displayed as text (no support for icons).
l 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
l 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
l iPhone
11.3.5 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE
Yes

l Windows Tablet
l 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
l 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 third-
party 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
l Desktop Web

11.4 Button - Events

Button has the following events associated with it:
l onClick
l preOnclickJS
l 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
11.4.3 postOnclickJS
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
l image
l 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
calenderIcon containerWeight cellTemplate
dateComponents contentAlignment containerHeight
dateFormat hExpand containerHeightReference
day margin dateEditable
focusSkin marginInPixel data
formattedDate padding dayTextAlignmentInCell
hour paddingInPixel displayedMonth
id vExpand hideDaysHeader
info widgetAlignment hideMonthsHeader
isVisible hoverSkin
minutes mode
month noOfMonths
placeholder titleOnPopup
seconds toolTip
skin widgetDataMapForCell
validStartDate wheelBackgroundColor
validEndDate
viewConfig
viewType
year

onSelection clear date
clearData format
enableRangeOfDates monthI18Nkey
navigateToPreviousMonth weekdayI18Nkey
navigateToNextMonth
removeDataAt
setData
setDataAt
setEnabled


setEnableAll
setDateSkin
setContext
Creating a Calendar using a constructor: kony.ui.Calendar
var mycal = new kony.ui.Calendar(basicConf, layoutConf, pspConf)

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

iPhone
Windows Phone

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:

The Calendar widget has the following important considerations for Mobile Web:
l The default height of calendar widget is 28px.

l If you apply padding to a Calendar widget for Mobile web the default height set for a calendar widget
(28px) is ignored.
l If you do not specify an image for popup view then a default image is provided.
l 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.
l On Android platform, restricting the date selection between validStartDate and validEndDate is not
possible with Native Calendar View.
l 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
l dateComponents
l dateFormat
l day
l focusSkin
l formattedDate
l hour
l id
l info
l isVisible
l minutes
l month
l placeholder
l seconds
l skin
l validStartDate
l validEndDate
l viewConfig
l viewType
l 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
1. Click the Ellipsis ( ) 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
l dd/MM/yyyy (default)
l 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
l 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:
SPA
Android / Server side Server side /Desktop
Windows
viewType iOS BlackBe Mobile Web Mobile Web Web
Phone
rry (BJS) (Advanced) /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

SPA
Android / Server side Server side /Desktop
Windows
viewType iOS BlackBe Mobile Web Mobile Web Web
Phone
rry (BJS) (Advanced) /Windows
Kiosk
CALENDAR_VIEW_TYPE_WHEEL_
ONSCREEN
Yes No No No No No
CALENDAR_VIEW_TYPE_WHEEL_
POPUP Yes* No No No No No
CALENDAR_VIEW_TYPE_LISTBOXES_
ONSCREEN
No No No Yes Yes No
CALENDAR_VIEW_TYPE_LISTBOXES_
POPUP
No No No No No No
CALENDAR_VIEW_TYPE_METRO 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:

l containerWeight
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the Calendar.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the Calendar.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the Calendar.
l CONTENT_ALIGN_CENTER- Specifies the text should align at center of the Calendar.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the Calendar.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the Calendar.
Calendar.
l 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
l 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
l 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
l containerHeight
l dateEditable
l data
l dayTextAlignmentInCell
l displayedMonth
l hideDaysHeader
l hideMonthsHeader
l hoverSkin
l mode
l noOfMonths
l titleOnPopup
l toolTip

l widgetDataMapForCell
l wheelBackgroundColor
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
You can define a template using the following widgets:
l HBox
l VBox
l Label
l Button
l Image
Syntax
JavaScript: cellTemplate
Type
JavaScript: kony.ui.Box - [Mandatory]
Read / Write
JavaScript Example
//Defining the properties for Calendar with cellTemplate:calcellTemplate

TYPE_GRID_ONSCREEN, validStartDate:[01,01,2012], validEndDate:[31,12,2012],
placeholder:"JSCalendar", calendarIcon:"cal.png"};
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 iOS

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
l 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.
l 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
l 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:
1. Click the Ellipsis ( ) button against the cellTemplate property. The Select/Search gridCalendars
window appears.
2. Select the template and click OK. The template is now assigned to a calendar.

3. Click the Ellipsis ( ) button against the data property.The Master Data for GridCalendar window
appears.
4. Click 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 iOS
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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the Calendar Day
cell.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the Calendar Day cell.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the Calendar Day
cell.
l CONTENT_ALIGN_CENTER- Specifies the text should align at center of the Calendar Day cell.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the Calendar
Day cell.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the Calendar
Day cell.
Calendar Day cell.
l 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 iOS
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: The property displayedMonth takes precedence over the dataComponents when both are specified
during the construction of the widget.
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 iOS
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

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 iOS
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.

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 iOS
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)

l CALENDAR_VIEW_TYPE_WHEEL_POPUP (applicable on WHEEL mode only)
l CALENDAR_WHEEL_ONLY_DATE (Default)
l CALENDAR_WHEEL_ONLY_TIME
l 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
l 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


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
l SPA
l 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: "dataId1",
widgetId2: "dataId2",
widgetId4: "secDataId1"
}
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 iOS
12.3.16 wheelBackgroundColor
Specifies the background color for the wheel that is displayed when you click the Calendar. This property is
applicable only when you set the viewType as CALENDAR_VIEW_TYPE_WHEEL_POPUP.
Syntax
JavaScript: wheelBackgroundColor
Type
Read / Write

JavaScript Example
//Defining the properties for Calendar.

var calBasic ={id:"cal1", isVisible:true};
var calLayout = {containerWeight:100};
var calPSP= {viewType:constants.CALENDAR_VIEW_TYPE_WHEEL_POPUP };

cal1 = new kony.ui.Calendar(calBasic, calLayout, calPSP);
//Setting the color for wheelbackground

form.cal1.wheelBackgroundColor = "0000ff00";
Accessible from IDE
No
l iPad
l iPhone

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
l clearData
l enableRangeOfDates
l navigateToPreviousMonth
l navigateToNextMonth
l removeDataAt
l setData
l setDataAt
l setEnabled
l setEnableAll
l setDatesSkin
l setContext
l addAppointments
l deleteAppointments
l modifyAppointments
l getAppointments
l clearAppointments
l switchToDate
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

var calBasicConf = {id : "calID", isVisible:true, dateComponents:

[31,12,2012,04,30,55], skin:"konytextar", focusSkin:"calFocus", dateFormat

:"dd/MM/yyyy", viewType:constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStar
tDate:[01,01,2012], validEndDate:[31,12,2012], date:[31,12,2012], placehol
der:"JSCalendar", calendarIcon:"cal.png"};

f);
//Calendar clearData Method call.

Calendar.clearData();
l iOS
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 iOS
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


f);
//navigateToNextMonth Method call.

Calendar.navigateToNextMonth();
l iOS
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

12,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],

f);
//removeDataAt Method call.

Calendar.removeDataAt("31/12/2012");
l iOS
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 iOS
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
Specifies the dates in a table format which follows {dd/mm/yyyy} convention.

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 iOS
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

Specifies the dates in a table format which follows {dd,mm,yyyy} convention.

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

Specifies the dates in a table format which follows {dd,mm,yyyy} convention.


Return Values
None
Exceptions
None
JavaScript Example


f);
//setDateSkin Method call.

Calendar.setDateSkin([[27,04,2012],[30,04,2012],[01,04,2012]], skin:"konyt
extar");

12.5.12 setContext
Specifies the calendar that must be displayed for the context and also helps you to position the calendar on
the screen. The calendar 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 calendar must be shown and also the
anchoring of the calendar on the widget (left, right, center, top, or bottom).
Signature
Lua: calendar.setcontext(calname, context)
Input Parameters
calname [widgetref] - Mandatory

Reference to the calendar.

calendar on the screen.
It is a set of flags that are used to anchor the calendar with respect to the dimensions
of the widget. Possible values are ("top", "bottom", "right", "left").
Reference to an existing widget with respect to which the calendar has to be

anchored (Pass the Formid if the calendar is to be positioned with respect to a Form.
This Form is assumed to be the form on which the calendar will be overlaid).
Return Values
None
Exceptions
None

JavaScript Example


f);

var context1={"widget":frmApis.Calendar,"anchor":"bottom"};

frmApis.setContext(context1);
Available on Desktop Web platform
12.5.13 addAppointments
do that.
Signature
JavaScript: addAppointments(array of appointments)
Input Parameters




Return Values
None
Exceptions
None
JavaScript Example


f);



12.5.14 deleteAppointments
do that.
Signature
Input Parameters



Return Values
None
Exceptions
None
JavaScript Example

yy", viewType:constants.CALENDAR_VIEW_TYPE_GRID_POPUP, validStartDate:



f);


12.5.15 modifyAppointments
do that.
Signature
Input Parameters




Return Values
None
Exceptions
None
JavaScript Example


f);


12.5.16 getAppointments
do that.
Signature

Input Parameters



Return Values
None
Exceptions
None

JavaScript Example


f);


12.5.17 clearAppointments
do that.
Signature
Input Parameters




Return Values
None
Exceptions
None
JavaScript Example


f);


12.5.18 switchToDate
do that.

Signature
Input Parameters



Return Values
None
Exceptions
None
JavaScript Example


var Calendar = new kony.ui.Calendar(calBasicConf, calLayoutConf,

calPSPConf);


12.6 Calendar - Deprecated Properties

The deprecated properties for Calendar widget are as follows:
l date
l format
l monthI18Nkey
l 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
1. Click the Ellipsis ( ) 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)
l MM/dd/yyyy
l 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
l VBox
l Button
l Image
l 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.

l to achieve the behavior of having widgets such as an Image and a label for a Calendar Day cell.
l 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. Select viewType as CALENDAR_VIEW_TYPE_GRID_ONSCREEN or CALENDAR_VIEW-TYPE_
GRID_POPUP.
7. To set the template to a Calendar, select the Calendar and go to Properties window.
8. Select cellTemplate and Select/Search gridCalendar window appears. Select the template, which
you want to set to the Calendar.
9. 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.

focusSkin containerWeight focusTickedImage
id itemOrientation focusUnTickedImage
info margin groupCells
isVisible marginInPixel hoverSkin
masterData padding tickedImage
masterDataMap paddingInPixel toolTip
selectedKeys widgetAlignment unTickedImage
selectedKeyValues viewType
skin
Events
onSelection
preOnclickJS
postOnclickJS
Creating a CheckBox using a constructor: kony.ui.CheckBoxGroup
var checkBox = new kony.ui.CheckBoxGroup(basicConf, layoutConf, pspConf)

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.

l 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.

l 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.
Server side Mobile Web
l Focus skin is not supported.

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 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.
l 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
l id
l info
l isVisible
l masterData
l masterDataMap
l selected Keys
l selected KeyValues
l 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 ( ) button against the property to open the MasterData for
CheckBox window.
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
13.1.6 masterDataMap
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

13.1.8 selectedKeyValues
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
l itemOrientation
l margin
l marginInPixel
l padding
l paddingInPixel
l widgetAlignment

Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
JavaScript Example
//Defining the properties for CheckBox with containerWeight:50


Accessible from IDE
No
13.2.2 itemOrientation
Specifies the alignment of the check boxes as horizontal or vertical.
l CHECKBOX_ITEM_ORIENTATION_VERTICAL (default)
l 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
l iPad
l 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
l iPad
l Windows Kiosk


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
l focusUnTickedImage
l groupCells
l hoverSkin
l tickedImage
l toolTip
l unTickedImage
l viewType
13.3.1 focusTickedImage
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
l J2ME
13.3.2 focusUnTickedImage
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
l 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
l iPhone

13.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Accessible from IDE
Yes
l Windows Tablet
l 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
l iPhone
l BlackBerry
l J2ME
l Windows Phone
l 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
l Windows Tablet
l Windows Kiosk
13.3.7 unTickedImage
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
l iPhone
l BlackBerry
l J2ME
l Windows Phone
l Windows Tablet
l 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
l CHECKBOX_VIEW_TYPE_TABLEVIEW
l 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
l 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
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};


form.checkBox.wheelBackgroundColor = "0000ff00";

Accessible from IDE
No
l iPad
l iPhone

13.4 CheckBox - Events

CheckBox has the following event associated with it:
l onSelection
l preOnclickJS
l 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
Platform Specific
Properties
id contentAlignment dropDownImage
info hExpand groupCells
isVisible margin hoverSkin
masterData marginInPixel placeholder
masterDataMap padding popupFocusSkin
selectedKey paddingInPixel popupSkin
selectedKeyValue vExpand popupTitle
skin widgetAlignment tickedImage
toolTip
singleLineText
singleLineTextInPopup
textTruncatePosition
textTruncatePositionInPopup
unTickedImage
viewType
viewConfig
wheelBackgroundColor
Events Deprecated
onSelection placeholderi18nkey
preOnclickJS
postOnclickJS
Creating a ComboBox using a constructor: kony.ui.ComboBox
var mycombobox = new kony.ui.ComboBox (basicConf, layoutConf, pspConf)


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
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:
Android
BlackBerry
iPhone

Windows Phone
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.

l skin: Used to specify the skin.
l focusSkin: Used to specify the focus skin.
Pitfalls
The following are the pitfalls to avoid for a ComboBox:
l 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.
l (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.

l All platforms: You cannot place images inside a ComboBox.
l 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
l http://developer.android.com/guide/developing/tools/draw9patch.html
l J2ME platform: If you do not specify the focusSkin, it is not possible to identify the traversal.
l 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.
l Due to Browser restriction, you cannot apply padding for a ComboBox.

l The hExpand property is not applicable.

l focusSkin is not supported.
14.1 ComboBox - Basic Properties

The basic properties of ComboBox widget are as follows:
l focusSkin
l id
l info
l isVisible
l masterData
l masterDataMap
l selectedKey
l selectedKeyValue
l 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 comboLayout = {containerWeight:100};
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)

14.1.8 selectedKeyValue
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
l contentAlignment
l hExpand

l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the ComboBox.
l 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
l iPad
l 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
l iPad
l 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.

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
l dropDownImage
l groupCells
l hoverSkin
l placeholder
l popupFocusSkin
l popupSkin
l popupTitle
l singleLineText
l singleLineTextInPopup
l textTruncatePosition
l textTruncatePositionInPopup
l tickedImage
l toolTip
l unTickedImage
l viewType
l 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
14.3.2 dropDownImage
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
l iPhone
l BlackBerry
l 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
l iPhone
14.3.4 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE
Yes
l Windows Tablet
l 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
l iPhone
l BlackBerry
l Windows Phone
l 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 singleLineText
If the length of the text is more than the space available, the selected options text will be displayed truncated,
in a single line with (...) ellipses. The position of the ellipses is controlled by textTruncatePosition property.
The default ellipses position is at the end of the line if textTruncatePosition property is not set.
Default:False

Syntax
JavaScript: singleLineText
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for ComboBox

var comboPSP= {popupTitle:"ComboPopUp", singleLineText: true};

Accessible from IDE
No
This property is available on Android/Android Tablet platform
14.3.10 singleLineTextInPopup
If the length of the text is more than the space available, the popup options text will be displayed truncated, in
a single line with (...) ellipses. The position of the ellipses is controlled by textTruncatePositionInPopup
property. The default ellipses position is at the end of the line if textTruncatePositionInPopup property is not
set.
Default:False
Syntax
JavaScript: singleLineTextInPopup
Type
JavaScript: Boolean
Read / Write

JavaScript Example

var comboPSP= {popupTitle:"ComboPopUp", singleLineTextInPopup: true};

//Reading the popupTitle of the ComboBox

alert("ComboBox popupTitle is ::"+combo.popupTitle);
Accessible from IDE
No
14.3.11 textTruncatePosition
When the property singleLineText is set to true, this property controls the position of the ellipses (...), in the
selected option text.
The options are:
l constants.TEXT_TRUNCATE_START
l constants.TEXT_TRUNCATE_MIDDLE
l constants.TEXT_TRUNCATE_END
Default:constants.TEXT_TRUNCATE_END
Syntax
JavaScript: textTruncatePosition
Type
JavaScript: Number
Read / Write

JavaScript Example

var comboPSP= {popupTitle:"ComboPopUp", singleLineText: true, textTruncate
Position: constants.TEXT_TRUNCATE_MIDDLE};

Accessible from IDE
No
14.3.12 textTruncatePositionInPopup
When the property singleLineTextInPopup is set to true, this property controls the position of the ellipses (...),
in the popup options text.
The options are:
Syntax
JavaScript: textTruncatePositionInPopup
Type
JavaScript: Number
Read / Write

JavaScript Example
//Defining the properties for ComboBox.

var comboPSP= {popupTitle:"ComboPopUp", singleLineText: true, textTruncate
PositionInPopup: constants.TEXT_TRUNCATE_MIDDLE};

Accessible from IDE
No
14.3.13 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
l iPhone
14.3.14 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
l iPhone
14.3.16 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)

l COMBOBOX_VIEW_TYPE_EDITVIEW (applicable on Desktop Web only)
l COMBOBOX_VIEW_TYPE_TABLEVIEW (applicable on iPhone and iPad platforms)
l COMBOBOX_VIEW_TYPE_TOGGLEVIEW (applicable on iPhone and iPad platforms)
l 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
l iPhone
l Windows Tablet
l Desktop Web
14.3.17 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
l COMBOBOX_TOGGLE_VIEW_STYLE_BORDERED
l 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
l iPhone
l 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
l iPhone

14.4 ComboBox- Events

ComboBox has the following event associated with it:
l onSelection
l preOnclickJS
l 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

14.5.1 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
l 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.
Platform Specific
Properties
columnHeadersConfig containerWeight containerHeight
data contentAlignment containerHeightInPixel
gridHeight margin dockingHeader
headerSkin padding enableScrollBar
id widgetAlignment gridlineColor
info hoverSkin
isMultiSelect selectedCellItem
isVisible selectedCellIndex
rowAlternateSkin toolTip
rowCount
rowFocusSkin
rowNormalSkin
scrollable
selectedIndex
selectedIndices
selectedItem
selectedItems
showColumnHeaders
Event Methods
onRowSelected addAll
addDataAt
applyCellSkin
removeAll
removeAt
selectAllRows
setCellDataAt
setData
setDataAt
Creating a DataGrid using a constructor: kony.ui.DataGrid
var dgrid = new kony.ui.DataGrid(basicConf, layoutConf, pspConf)


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.
l headerSkin: Specifies the skin to be applied to the DataGrid Header.
l rowNormalSkin: Specifies the skin to be applied when the row is not in focus.
l rowAlternateSkin: Specifies the skin to be applied to every even row when not in focus.
l 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.
l 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.
l contentAlignment for cell is supported only on iOS platform.
15.1 DataGrid - Basic Configuration Properties

The basic configuration properties for the DataGrid widget are as follows:
l columnHeadersConfig
l data
l gridHeight
l headerSkin
l id
l info
l isMultiSelect
l isVisible
l rowAlternateSkin
l rowCount
l rowFocusSkin
l rowNormalSkin
l scrollable
l selectedIndex
l selectedIndices
l selectedItem
l selectedItems
l 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.

l columnType[Mandatory] - Specifies the type of the column. Following are the available options:

l DATAGRID_COLUMN_TYPE_TEXT (default)
l DATAGRID_COLUMN_TYPE_IMAGE
l DATAGRID_COLUMN_TYPE_TEMPLATE (supported on desktop web only)
l columnHeaderText [Mandatory] - The text string that is displayed as header of column.
l 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.)
l columnDataTemplate [Mandatory]- The template box reference to be used to create a row cell for this
column (supported on desktop web only.)
l 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.
l 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.
l columnOnClick [Optional]- The event callback is invoked by the platform when a column is clicked.
l 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
l CONTENT_ALIGN_TOP_CENTER
l CONTENT_ALIGN_TOP_RIGHT
l CONTENT_ALIGN_MIDDLE_LEFT
l CONTENT_ALIGN_CENTER (default)
l CONTENT_ALIGN_MIDDLE_RIGHT
l CONTENT_ALIGN_BOTTOM_LEFT
l CONTENT_ALIGN_BOTTOM_CENTER
l 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.

l If column type is DATAGRID_COLUMN_TYPE_IMAGE, the value should be of String datatype
representing the image filename or url.
l 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,
1. Click the Ellipsis ( ) 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"}]

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.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
No
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"

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

Checking",col2:"494", col3:"$2000.34"}, {col1:"Savings",col2:"567", col3:"
$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
15.1.11 rowFocusSkin
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
No
15.1.14 selectedIndex
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
15.1.15 selectedIndices
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
15.1.16 selectedItem
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
l contentAlignment
l margin
l padding
l 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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the widget.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the widget.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the widget.
l CONTENT_ALIGN_CENTER - Specifies the text should align at center of the widget.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the widget.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the widget.
widget.
l 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


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
l containerHeightInPixel
l dockingHeader
l enableScrollBar
l gridlineColor
l hoverSkin
l selectedCellItem
l selectedCellIndex
l 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.

l 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
l 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
l 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
l 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
l addDataAt
l applyCellSkin
l removeAll
l removeAt
l selectAllRows
l setCellDataAt
l setData
l 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.

l support template type to headers.
l 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
l VBox
l Button
l Calendar
l CheckBoxGroup
l ComboBox
l Image
l Label
l Line
l Link
l RadioButtonGroup
l RichText
l TextArea
l 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.

l to display a snapshot.
l to provide an illustration.
Image provides you with an option to set Basic Properties, Layout Properties, Platform Specific Properties,
and an Event.
Platform Specific
Properties
base64 containerWeight glossyEffect
id imageScaleMode hoverSkin
imageWhenFailed margin renderAsAnchor
imageWhileDownloading marginInPixel skin
info padding toolTip
isVisible paddingInPixel
rawBytes referenceHeight
src referenceWidth
widgetAlignment
Events Deprecated
onDownloadComplete hExpand
scaleMode
vExpand
Creating an Image using a constructor: kony.ui.Image2
var myimage = new kony.ui.Image2 (basicConf, layoutConf, pspConf)

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.
l 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:

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.

l The file name must start only with an alphabet.
l The file name can contain numbers.
l Do not use any reserved words or keywords ( of JavaScript) as the file names for the images.
l 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

The file name is invalid because it
myicon.PNG Myicon.png
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
l id
l imageWhenFailed
l imageWhileDownloading

l info
l isVisible
l rawBytes
l 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
16.1.3 imageWhenFailed
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
16.1.4 imageWhileDownloading
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
l imageScaleMode
l margin
l marginInPixel
l padding
l paddingInPixel
l referenceHeight
l referenceWidth
l 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
16.2.2 imageScaleMode
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.

l 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.
l 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.
l 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.
l IMAGE_SCALE_MODE_CROP: This scale mode preserves the original size of the Source Image. In
case,
cropped or clipped to fit the ImageWidget.
Image Widget size is calculated for this mode 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.
l 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.
l 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.
l 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
l iPad
l 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
l iPad
l Windows Kiosk
16.2.7 referenceHeight
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
16.2.8 referenceWidth
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:

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
l hoverSkin
l renderAsAnchor
l skin
l 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
l IMAGE_GLOSSY_EFFECT_LINEAR
l 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
l 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

16.3.3 renderAsAnchor
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

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
l iPad
l BlackBerry
l 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
l 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
l scaleMode
l 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.

l 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.

id containerWeight hoverSkin
info contentAlignment pasteboardType
isVisible hExpand renderAsAnchor
skin margin textCopyable
text marginInPixel toolTip
padding wrapping
paddingInPixel
vExpand
widgetAlignment
Creating a Label using a constructor: kony.ui.Label
var lbl1 = new kony.ui.Label(basicConf, layoutConf, pspConf)

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:

l 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.
l 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.
l 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
l info
l isVisible
l skin
l text
l 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
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the label.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the label.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the label.
l CONTENT_ALIGN_CENTER- Specifies the text should be horizontally and vertically centered on the
label.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the label.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the label.
l CONTENT_ALIGN_BOTTOM_CENTER- Specifies the text should align at bottom center of the label.
l 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
l iPad


l Windows Kiosk
17.2.6 padding
To define the padding values for a platform, click the Ellipsis ( ) button against the property to open the
Note: On iOS platform, padding is not respected when no text is provided to Label widget.

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
l iPad
l 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.


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
l pasteboardType
l renderAsAnchor
l textCopyable
l toolTip
l 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
l Desktop Web
17.3.2 pasteboardType
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.
l 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.
l 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.
l 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
l iPad
17.3.3 renderAsAnchor
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

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
l Android
l 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
l 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.

l 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.
l 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
l 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.
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)

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.

l An HLine in an HBox takes the width as specified in the containerWeight.
l 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
l info
l isVisible
l 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
l marginInPixel
l 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
l iPad
l 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.
Platform Specific
Properties
id contentAlignment contextMenu
info hExpand externalURL
isVisible margin glowEffect
skin marginInPixel hoverSkin
text padding showProgressIndicator
paddingInPixel submitURL
widgetAlignment toolTip
Events Deprecated
onClick focusImage
preOnclickJS image
postOnclickJS 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)

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:

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).
l If you do not specify a focusSkin, the default focus skin is applied to the link (link appears in black font
and is underlined).
l If you specify a skin or focusSkin without an underline, when rendered, the link will appear without an
underline on the platform.
l 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
l id
l info
l isVisible
l skin
l text
l 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
Available on all platforms except on all Server side Mobile Web and SPA (Windows 7.5 nth) platforms
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
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l 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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the button.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the button.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the button.
l CONTENT_ALIGN_CENTER- Specifies the text should align at center of the button.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the button.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the button.
button.
l 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
l iPad
l 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
l iPad
l Windows Kiosk


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
l contextMenu
l externalURL
l glowEffect
l hoverSKin
l submitURL
l 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

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.

BlackBerry Touch BlackBerry Non-Touch Device

BlackBerry 6.x
Device (<6.x) (<6.x)
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
l 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
l 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
l 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 third-
party 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
l Desktop Web

19.4 Link - Events

Link has the following event associated with it:
l onClick
l preOnclickJS
l 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
l image
l 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.
Platform Specific
Properties
focusSkin containerWeight applySkinsToPopup
id contentAlignment blockedUISkin
info hExpand dropDownImage
isVisible margin groupCells
masterData marginInPixel hoverSkin
masterDataMap padding nativeListFieldSkin
selectedKey paddingInPixel nativeListFieldFocusSkin
selectedKeys vExpand placeholder
selectedKeyValue widgetAlignment placeholderSkin
selectedKeyValues popupIcon
skin popupTitle
singleLineText
singleLineTextInPopup
textTruncatePosition
textTruncatePositionInPopup
tickedImage
toolTip
untickedImage
viewType
viewConfig
Events Deprecated
onSelection multiple
preOnclickJS placeholderi18nkey
postOnclickJS selectedkeys
selectedkeyvalues
Creating a ListBox using a constructor: kony.ui.ListBox
var listbox1 = new kony.ui.ListBox (basicConf, layoutConf, pspConf)


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.

l 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
l id
l info
l isVisible
l masterData
l masterDataMap
l selectedKey
l selectedKeys
l selectedKeyValue
l selectedKeyValues
l 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.
Note: For iOS platform, only background color is supported.
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
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.
Note: On SPA platform, only two options are supported CONTENT_ALIGN_MIDDLE_LEFT and
CONTENT_ALIGN_MIDDLE_RIGHT. The default option is CONTENT_ALIGN_MIDDLE_LEFT.
l CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the ListBox.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the ListBox.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the ListBox.
l CONTENT_ALIGN_MIDDLE_LEFT - Specifies the text should align at middle left of the ListBox.
(Android and SPA platforms support this option only).
l CONTENT_ALIGN_CENTER - Specifies the text should align at center of the ListBox. (Android
platform supports this option only).
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the ListBox.
(Android and SPA platforms support this option only).
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the ListBox.
ListBox.
l 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
l iPad
l Windows Phone
l 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
l iPad
l Windows Phone
l 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

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
l blockedUISkin
l dropDownImage
l groupCells
l hoverSkin
l multiSelect
l multiSelectRows
l nativeListFieldSkin
l nativeListFieldFocusSkin
l placeholder
l placeholderSkin
l popupIcon
l popupTitle
l singleLineText
l singleLineTextInPopup
l textTruncatePosition
l textTruncatePositionInPopup
l tickedImage
l toolTip
l untickedImage
l viewType
l 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
l iPhone
l 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
l 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
l 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
20.3.8 nativeListFieldSkin
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
20.3.9 nativeListFieldFocusSkin
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
l iPhone
l BlackBerry
l Windows Phone
l Windows Kiosk

20.3.11 placeholderSkin
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 singleLineText
If the length of the text is more than the space available, the selected options text will be displayed truncated,
in a single line with (...) ellipses. The position of the ellipses is controlled by textTruncatePosition property.
The default ellipses position is at the end of the line if textTruncatePosition property is not set.
Default:False
Syntax
JavaScript: singleLineText
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for Listbox

stFSkin"};
var listPSP = {viewType: constants.LISTBOX_VIEW_TYPE_LISTVIEW, singleLineT
ext: true};

Accessible from IDE
No
20.3.15 singleLineTextInPopup
If the length of the text is more than the space available, the popup options text will be displayed truncated, in
a single line with (...) ellipses. The position of the ellipses is controlled by textTruncatePositionInPopup
property. The default ellipses position is at the end of the line if textTruncatePositionInPopup property is not
set.

Default:False
Syntax
JavaScript: singleLineTextInPopup
Type
JavaScript: Boolean
Read / Write
JavaScript Example

stFSkin"};
extInPopup: true};

Accessible from IDE
No
20.3.16 textTruncatePosition
When the property singleLineText is set to true, this property controls the position of the ellipses (...), in the
selected option text.
The options are:
Syntax
JavaScript: textTruncatePosition

Type
JavaScript: Number
Read / Write
JavaScript Example

stFSkin"};
var listPSP = {viewType: constants.LISTBOX_VIEW_TYPE_LISTVIEW, textTruncat
ePosition: true, textTruncatePosition: constants.TEXT_TRUNCATE_MIDDLE};

Accessible from IDE
No
20.3.17 textTruncatePositionInPopup
When the property singleLineTextInPopup is set to true, this property controls the position of the ellipses (...),
in the popup options text.
The options are:
Syntax
JavaScript: textTruncatePositionInPopup
Type
JavaScript: Number

Read / Write
JavaScript Example

stFSkin"};
extInPopup: true, textTruncatePositionInPopup: constants.TEXT_TRUNCATE_MID
DLE};

Accessible from IDE
No
20.3.18 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
l iPhone
20.3.19 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],


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
l iPhone
20.3.21 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)

l LISTBOX_VIEW_TYPE_TABLEVIEW (applicable on iPhone and iPad platforms)
l LISTBOX_VIEW_TYPE_TOGGLEVIEW (applicable on iPhone and iPad platforms)
l LISTBOX_VIEW_TYPE_ONSCREENWHEEL (applicable on iPhone and iPad platforms)
l 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
l iPhone
l Android/Android Tablet ( only Spinner view is available for the platform)
20.3.22 viewConfig
toggleViewConfig: The property to configure the properties of LISTBOX_VIEW_TYPE_TOGGLEVIEW.
l LISTBOX_TOGGLE_VIEW_STYLE_PLAIN
l LISTBOX_TOGGLE_VIEW_STYLE_BORDERED
l LISTBOX_TOGGLE_VIEW_STYLE_BAR
Syntax
Lua: viewconfig
Type
Lua: Table

Read / Write
Accessible from IDE
Yes
l iPad
l 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

stFSkin"};
var listPSP = {viewType: constants.LISTBOX_VIEW_TYPE_ONSCREENWHEEL};


form.listbx.wheelBackgroundColor = "0000ff00";
Accessible from IDE
No

l iPad
l iPhone

20.4 ListBox - Events

ListBox has the following event associated with it:
l onSelection
l preOnclickJS
l 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
l multiple
l placeholderi18nKey
l selectedkeys
l 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)

l 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
20.5.3 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
l 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
l VBox
l Image
l Label
l 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.

l to perform an action on an onClick event of a menu.
l 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.
Platform Specific
Properties
activeSkin containerWeight contextMenu
collapsedImage margin collapsedImage
data marginInPixel expandedImage
expandedImage padding viewType
hoverSkin paddingInPixel
id widgetAlignment
info
isVisible
menuItemTemplate
orientation
selectedMenuIndex
selectedMenuItem
skin
widgetDataMap

Event Methods
onClick addAll
onRightClick addDataAt
removeAll
removeAt
setData
setDataAt
Creating a MenuContainer using a constructor: kony.ui.MenuContainer
var menuContainer = new kony.ui.MenuContainer(basicConf, layoutConf, pspCo

nf)

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
l data
l hoverSkin
l id
l info
l isVisible
l menuItemTemplate
l orientation
l selectedMenuIndex
l selectedMenuItem
l skin
l 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: []
}
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.
l 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.

l [0, 2 ] indicates 2nd menu item which is under the first menu item in the menu container.
l [ 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

21.1.12 widgetDataMap
Note: It is developer responsibility to ensure that widget data map to accommodate all the widget ids
{
widgetId3: "dtaId3",
}
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
l margin
l marginInPixel
l padding
l paddingInPixel
l 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: []
}
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
l WIDGET_ALIGN_CENTER
l 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:

l contextMenu
l collapsedImage
l expandedImage
l 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: []
}
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: []
}
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.
l 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.
l 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.
l 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
l 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
l addDataAt
l removeAll
l removeAt
l setData
l 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
l 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
l VBox
l Image
l Label
l 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.

l have uniform look and feel when an item is focused in a MenuContainer.
l perform an action on the event of an onclick of an item in the MenuContainer.
l 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 onClick
id
info
image
title
type
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.

l 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
l id
l info
l image
l title
l 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
l BlackBerry 10
l 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
l BlackBerry
l BlackBerry 10
l J2ME
22.1.3 info


Syntax
JavaScript: info
Lua: info
Type
Lua: UserData
Read / Write
Accessible from IDE
No
l BlackBerry
l BlackBerry 10
l 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
l BlackBerry 10
l 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
l BlackBerry 10
l 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
l 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
l BlackBerry 10
l 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
Platform Specific
Properties
focusSkin containerWeight dropdownImage
id hExpand focusTickedImage
info itemOrientation focusUnTickedImage
isVisible margin groupCells
masterData marginInPixel hoverSkin
masterDataMap padding placeholder
selectedKey paddingInPixel tickedImage
selectedKeyValue vExpand toolTip
skin widgetAlignment untickedmage
viewType
viewConfig
wheelBackgroundColor
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:

The following are the important considerations for the RadioButtonGroup widget.
All Platforms
l RadioButtonGroup widget is always a group widget.

l 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.

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 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
l id
l info
l isVisible
l masterData
l masterDataMap
l selectedKey
l selectedKeyValue
l 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
l hExpand
l itemOrientation
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.
23.2.3 itemOrientation
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.
l 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
l iPad
l Windows Phone Mango
l 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
l iPad
l Windows Phone Mango
l 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.

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
l focusTickedImage
l focusUnTickedImage
l groupCells
l hoverSkin
l placeholder
l tickedImage
l toolTip
l unTickedImage
l viewType
l 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
l iPhone
23.3.2 focusTickedImage
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
l J2ME
23.3.3 focusUnTickedImage
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
l 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
l iPhone
23.3.5 hoverSkin
Syntax
Lua: hoverskin
Type
JavaScript: String
Lua: String
Read / Write
Yes
Accessible from IDE
Yes
l Windows Tablet
l 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
l 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.

l iPhone - applicable only when the viewType is selected as tableView.
l BlackBerry
l Windows Tablet
l 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.

l iPhone - applicable only when the viewType is selected as tableView.
l BlackBerry

l Windows Tablet
l 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
l RADIOGROUP_VIEW_TYPE_TABLEVIEW
l RADIOGROUP_VIEW_TYPE_TOGGLEVIEW
l 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
l iPhone
23.3.11 viewConfig
toggleViewConfig: The property to configure the properties of RADIOGROUP_VIEW_TYPE_

TOGGLEVIEW.
l RADIOGROUP_TOGGLE_VIEW_STYLE_PLAIN
l RADIOGROUP_TOGGLE_VIEW_STYLE_BORDERED
l RADIOGROUP_TOGGLE_VIEW_STYLE_BAR

Syntax
Lua: viewconfig
Type
Lua: UserData
Read / Write
Accessible from IDE
No
l iPad
l 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
l iPhone

23.4 RadioButtonGroup - Events

RadioButtonGroup has the following events associated with it:
l onSelection
l preOnclickJS
l 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.
Platform Specific
Properties
id containerWeight hoverSkin
info contentAlignment linkFocusSkin
isVisible hExpand superScriptSkin
linkSkin margin telephoneLinkSkin
skin marginInPixel toolTip
text padding wrapping
paddingInPixel
vExpand
widgetAlignment
Event
onClick
preOnclickJS
postOnclickJS
Creating a RichText using a constructor: kony.ui.RichText
var RichText1 = new kony.ui.RichText(basicConf, layoutConf, pspConf)

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> 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
<a href=""> </a>
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 .

Subscript
<sup>Superscript</sup> Displays text as Superscript.
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.

Displays a telephone number on Native
<tel number=""></tel>
Applications.

Tags Description
Displays a telephone number on Mobile Web
<a href="tel:"></a>
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:

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.
l 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>
l 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 "DBOzoneX-
BoldItalic", then the font name during integration should be "DBOzoneX-BoldItalic.ttf".
l 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
l info
l isVisible
l linkSkin
l skin
l 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
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.

l CONTENT_ALIGN_TOP_LEFT - Specifies the text should align at top left corner of the RichText.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the RichText.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the RichText.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the RichText.
l CONTENT_ALIGN_CENTER- Specifies the text should align at center of the RichText.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the RichText.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the RichText.
RichText.
l 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
l iPad
l Windows Phone
l Windows Kiosk
l 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
l iPad
l 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
Available on all platforms except Server side Mobile Web and Desktop Web platforms

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
l linkFocusSkin
l superScriptSkin
l telephoneLinkSkin
l toolTip
l 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
l J2ME
l Desktop Web
l SPA (iOS, Android, BlackBerry, and all Windows channels except on Windows 7.5 platform)
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
l Windows Tablet
l 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.

l 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.
l 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
l iPhone

24.4 RichText - Events

RichText widget has the following event associated with it:
l onClick
l preOnclickJS
l 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

focusThumbImage containerWeight
id margin
info marginInPixel
isVisible widgetAlignment
leftSkin
max
min
rightSkin
selectedValue
step
thumbImage
Platform Specific Properties Events

enableThumbTintColor onSelection
maxLabel onSlide
maxLabelSkin
maxValueImage
minLabel
minLabelSkin
minValueImage
orientation
thickness
thumbTintColor
viewType
Creating a Slider using a constructor: kony.ui.Slider
var slider = new kony.ui.Slider(basicConf, layoutConf, pspConf)

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:
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.
l rightSkin: Specifies the skin to be applied to the background of the slider on right side of the thumb
image of the seekbar.
l minLabel: Specifies the text or number to be displayed for the minimum value of the slider.
l maxLabel: Specifies the text or number to be displayed for the maximum value of the slider.
l thickness: Specifies the thickness of the seekbar.
l minLabelSkin: Specifies the skin for the minLabel property of the slider.
l 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.
l 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
l id
l info
l isVisible
l leftSkin
l max
l min
l rightSkin
l selectedValue
l step
l 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:

l containerWeight
l margin
l marginInPixel
l 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
l iPad
l Windows Kiosk

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
l maxLabel
l maxLabelSkin
l maxValueImage
l minLabel
l minLabelSkin
l minValueImage
l orientation
l thickness
l thumbTintColor
l 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
l 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)
l Windows Kiosk
l 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
l 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
l 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
l 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.
l 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
l Windows Kiosk
l Windows Phone
l 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
l 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.
l 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
l 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.
Platform Specific
Properties
autoCapitalize contentAlignment autoCorrect
id hExpand closeButtonText
info margin keyboardActionLabel
isVisible marginInPixel pasteboardType
keyBoardStyle padding placeholderSkin
maxTextLength paddingInPixel showCloseButton
numberOfVisibleLines widgetAlignment showProgressIndicator
placeholder toolTip
secureTextEntry
skin
text
textInputmode
Events Deprecated
onDone editable
onBeginEditing No of Rows
onEndEditing
onTextChange
Creating a TextArea using a constructor: kony.ui.TextArea2
var setTextArea1 = new kony.ui.TextArea2 (basicConf, layoutConf, pspConf)

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:

The following are the important considerations for the TextArea widget:

l Editing on devices with small form factor takes place in a new screen.
l Editing on devices with medium or large form factor takes place in the same screen.
l 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.
l For Desktop Web platform, transparency ( border/font) is not support in Internet Explorer 7 and Internet
Explorer 8.
l 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
l focusSkin
l id
l info
l isVisible
l keyBoardStyle
l maxTextLength
l numberOfVisibleLines
l placeholder
l secureTextEntry
l skin
l text
l textInputmode
26.1.1 autoCapitalize
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.
l 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.

l TEXTAREA_AUTO_CAPITALIZE_SENTENCES: This option changes the first character of all the

sentences to uppercase. (Not supported on BlackBerry platform)
l 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
26.1.6 keyBoardStyle
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.
l TEXTAREA_KEY_BOARD_STYLE_EMAIL: Specifies the keyboard to enter email address.

Supported in BlackBerry 10 platform.
l TEXTAREA_KEY_BOARD_STYLE_URL: Specifies the keyboard to enter URL address.
l 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.

l TEXTAREA_KEY_BOARD_STYLE_DEFAULT: Specifies the default numeric keyboard.
l TEXTAREA_KEY_BOARD_STYLE_DECIMAL: Specifies the keyboard to enter decimals.
l TEXTAREA_KEY_BOARD_STYLE_NUMBER_PAD: Specifies the keyboard to enter numbers. (Not

supported in Windows Phone platform)
l TEXTAREA_KEY_BOARD_STYLE_PHONE_PAD: Specifies the keyboard to enter phone numbers.

(Not supported in Windows platform)
l TEXTAREA_KEY_BOARD_STYLE_SIGNED_NUMBER: Specifies the keyboard to enter negative

numbers( for example -345). This option is applicable to Android platform only.
l 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
26.1.7 maxTextLength
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.
Note: In Android platform, you cannot fix the height of the TextArea to any value. The form by default is a
vertical scroll container, if you restrict the height of TextArea, you will not be able to scroll the content,
because of double scrolling issue. For example,
If the numberOfVisibleLines property is set to 10, then the height of the TextArea will be at least 10 lines tall.
As you enter text more than 10 lines, TextArea height expands accordingly.
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)
26.1.10 secureTextEntry
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
26.1.13 textInputMode
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.
l 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
l containerWeight
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l 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.
l constants.CONTENT_ALIGN_TOP_RIGHT: Specifies the text should align at top right of the
TextArea.
l constants.CONTENT_ALIGN_TOP_CENTER: Specifies the text should align at top center of the
TextArea.
l constants.CONTENT_ALIGN_MIDDLE_LEFT: Specifies the text should align from left of the
TextArea.
l constants.CONTENT_ALIGN_CENTER: Specifies the test should align at the center of the TextArea.
l constants.CONTENT_ALIGN_MIDDLE_RIGHT: Specifies the text should align from right of the
TextArea.
l constants.CONTENT_ALIGN_BOTTOM_LEFT: Specifies the text should align at bottom left of the
TextArea.
l constants.CONTENT_ALIGN_BOTTOM_CENTER: Specifies the text should align at bottom center
of the TextArea.
l 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
l iPad

l Windows Phone
l 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
l iPad
l Windows Phone
l Windows Kiosk

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
l blockedUISkin
l closeButtonText
l hoverSkin
l keyboardActionLabel
l pasteboardType
l placeholderSkin
l showCloseButton
l 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
l SPA (iPhone/Android/BlackBerry)
l 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
l Server side Mobile Web (Advanced)
26.3.3 closeButtonText
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
l Desktop Web

26.3.5 keyboardActionLabel
Specifies if the text to be displayed in action key of the keyboard.
Default: TEXTBOX_KEYBOARD_LABEL_DONE
l TEXTBOX_KEYBOARD_LABEL_DONE
l TEXTBOX_KEYBOARD_LABEL_GO
l TEXTBOX_KEYBOARD_LABEL_SEARCH
l TEXTBOX_KEYBOARD_LABEL_NEXT
l TEXTBOX_KEYBOARD_LABEL_SEND
l TEXTBOX_KEYBOARD_LABEL_GOOGLE
l TEXTBOX_KEYBOARD_LABEL_JOIN
l TEXTBOX_KEYBOARD_LABEL_ROUTE
l TEXTBOX_KEYBOARD_LABEL_YAHOO
l 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
l 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

l 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.
l 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.
l 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
l 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
l BlackBerry
l Windows Phone
26.3.8 showCloseButton
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
l 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
l onBeginEditing

l onEndEditing
l onKeyUp
l onKeyDown
l 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

26.4.2 onBeginEditing
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
l iPad
l Desktop Web
l 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)

l Click on the Done button on the Next Previous bar.
l 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
l 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
l iPad
l Desktop Web
l 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
l No of Rows

editable setEnabled API
No. of Rows numberOfVisibleLines
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
l 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.
Platform Specific
Properties
autoCapitalize containerHeight autoComplete
focusSkin containerHeightReference autoCorrect
id containerHeightMode autoFilter
info containerWeight blockedUISkin
isVisible contentAlignment closeButtonText
keyBoardStyle hExpand filterlist
maxTextLength margin hoverSkin
placeholder marginInPixel keyboardActionLabel
secureTextEntry padding leftViewImage
skin paddingInPixel nativeListFieldFocusSkin
text widgetAlignment nativeListFieldSkin
textInputMode pasteboardType
placeholderSkin
showClearButton
showCloseButton
showProgressIndicator
toolTip
viewType
Events Deprecated
onCancel inputMode
onDone inputStyle
onBeginEditing keyBoardType
onEndEditing type
onKeyUp
onKeyDown
onTextChange
preOnclickJS
postOnclickJS
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:


27.1 TextBox - Basic Properties

The basic properties for TextBox Widget are as follows:
l autoCapitalize
l focusSkin
l id
l info
l isVisible
l keyBoardStyle
l maxTextLength
l placeholder
l secureTextEntry
l skin
l text
l textInputMode
l toolTip
27.1.1 autoCapitalize
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.
l 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.
l TEXTBOX_AUTO_CAPITALIZE_SENTENCES: This option changes the first character of all the
sentences to uppercase. (Not supported on BlackBerry platform)
l 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:
SENTENC
Browsers/Devices NONE WORDS All
ES
Not Not
IE8 Supported Not supported
supported supported
Not Not
supported supported
Not Not
supported supported
Not Not
Chrome 29.0 Supported Not supported
supported supported
Not Not
Firefox 23.0.0 Supported Not supported
supported supported

Not Not
Safari 5 Supported Not supported
supported supported
Not Not
iPhone4 OS 4.2 Not supported Supported
supported supported
iPhone5 OS 6.1.3 Supported Supported Supported Supported
Not Not
Android 2.3.3 Supported Not supported
supported supported
Not Not
Android 4.2 Supported Not supported
supported supported
Not Not
BlackBerry Supported Not supported
supported supported
Not Not
Windows Supported Not supported
supported 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
27.1.6 keyBoardStyle
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.

l TEXTBOX_KEY_BOARD_STYLE_EMAIL: Specifies the keyboard to enter email address. Supported

in BlackBerry 10 platform.
l TEXTBOX_KEY_BOARD_STYLE_URL: Specifies the keyboard to enter URL address. Supported in

BlackBerry 10 platform.
l 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.

l TEXTBOX_KEY_BOARD_STYLE_DECIMAL: Specifies the keyboard to enter decimals.
l TEXTBOX_KEY_BOARD_STYLE_NUMBER_PAD: Specifies the keyboard to enter numbers. (Not

supported in Windows platform)
l TEXTBOX_KEY_BOARD_STYLE_PHONE_PAD: Specifies the keyboard to enter phone numbers.

(Not supported in Windows platform)
l TEXTBOX_KEY_BOARD_STYLE_SIGNED_NUMBER: Specifies the keyboard to enter negative

numbers( for example -345). This option is applicable to Android platform only.
l 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.
27.1.7 maxTextLength
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)
27.1.9 secureTextEntry
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
27.1.12 textInputMode
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.
l 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
l containerHeightMode
l containerWeight
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l 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.
l 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.
l TEXTBOX_FONT_METRICS_DRIVEN_HEIGHT: This the default option on Android, Blackberry, and
Windows Phone platforms. It is supported on all platforms.
l 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
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 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.
l constants.CONTENT_ALIGN_TOP_RIGHT: Specifies the text should align at top right of the
TextBox.
l constants.CONTENT_ALIGN_TOP_CENTER: Specifies the text should align at top center of the
TextBox.
l constants.CONTENT_ALIGN_MIDDLE_LEFT: Specifies the text should align from left of the
TextBox.
l constants.CONTENT_ALIGN_CENTER: Specifies the test should align at the center of the TextBox.
l constants.CONTENT_ALIGN_MIDDLE_RIGHT: Specifies the text should align from right of the
TextBox.
l constants.CONTENT_ALIGN_BOTTOM_LEFT: Specifies the text should align at bottom left of the
TextBox.
l constants.CONTENT_ALIGN_BOTTOM_CENTER: Specifies the text should align at bottom center
of the TextBox.
l 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
l iPad

l Windows Phone
l 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
l iPad
l Windows Phone
l Windows Kiosk

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 Alignment on the device

top-left, top-right, top-center Top
middle-left, middle-right, middle-center Middle
bottom-left, bottom-right, bottom-
Bottom
center
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
l autoCorrect
l autoFilter
l blockedUISkin
l closeButtonText
l filterList
l hoverSkin
l keyboardActionLabel
l leftViewImage
l nativeListFieldFocusSkin
l nativeListFieldSkin
l pasteboardType
l placeholderSkin
l showClearButton
l showCloseButton
l toolTip
l 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

Below is the browser specific limitations on SPA platform when autoComplete property is set to true/false.
Browsers/Devices True False

IE8 Not supported Supported
Supported if form is
Chrome 29.0 Supported
submitted to an external url
Supported if form is
Firefox 23.0.0 Supported
submitted to an external url
Safari 5 Not supported Supported
iPhone4 OS 4.2 Not supported Supported
iPhone5 OS 6.1.3 Not supported Supported
Android 2.3.3 Not supported Supported
Android 4.2 Not supported Supported
BlackBerry Not supported Supported
Windows Not 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
l Server side MobileWeb (Advanced)
Below is the browser specific limitations on SPA platform when autoCorrect property is set to true/false.

Browsers/Devices True False

Chrome 29.0 Not supported Supported
Firefox 23.0.0 Not supported Supported
Safari 5 Not supported Supported
iPhone4 OS 4.2 Supported Supported
iPhone5 OS 6.1.3 Supported Supported
Android 2.3.3 Not supported Supported
Android 4.2 Not supported Supported
BlackBerry Not supported Supported
Windows Not 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:

l None - No criteria is specified. If you leave the selection unchanged, the event
associated with ontextchange is triggered.
l StartsWith: Filters and displays all the values that start with the value defined in this
mode.
l StartsWithCaseSensitive: Filters and displays all the values that start with the value
defined in this mode with case sensitivity.
l StartsWithOrdinal: Filters and displays all the values that start with the sequence of
values defined in this mode.
l StartsWithOrdinalCaseSensitive: Filters and displays all the values that start with the
sequence of values defined in this mode with case sensitivity.
l Contains: Filters and displays all the values that contain the value defined in this mode.
l ContainsCaseSensitive: Filters and displays all the values that contain the value defined
in this mode with case sensitivity.
l ContainsOrdinal: Filters and displays all the values that contain the sequence of values
defined in this mode.
l ContainsOrdinalCaseSensitive: Filters and displays all the values that contain the
l Equals: Filters and displays all the values that are equal to the value defined in this
mode.
l EqualsCaseSensitive: Filters and displays all the values that are equal to the value
defined in this mode with case sensitivity.
l EqualsOrdinal: Filters and displays all the values that are equal to the sequence of
values defined in this mode.
l 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
l Windows Mobile
l Android
l 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

27.3.5 closeButtonText
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
l Windows Mobile
l Android
l 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
l Desktop Web
27.3.8 keyboardActionLabel
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
l TEXTBOX_KEYBOARD_LABEL_JOIN
l TEXTBOX_KEYBOARD_LABEL_ROUTE
l TEXTBOX_KEYBOARD_LABEL_YAHOO
l 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
l 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
l iPad
27.3.10 nativeListFieldFocusSkin
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
27.3.11 nativeListFieldSkin
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

l 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.
l 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.
l 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.

l 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
l 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
l iPad
l Android

l 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
l iPad
27.3.15 showCloseButton
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
l 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:

l TEXTBOX_VIEW_TYPE_DEFAULT - This is the default selection and if this option is unchanged, the
appearance of the Textbox remains unchanged.
l 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
l iPad
l Android
27.4 TextBox - Events

TextBox has the following events associated with it:
l onCancel
l onDone
l onBeginEditing
l onEndEditing
l onKeyUp
l onKeyDown
l onTextChange

l preOnclickJS
l 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

27.4.3 onBeginEditing
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
l iPad
l 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:

l Click on any other focusable widget(for example, another TextBox)

l Click on the Done button on the Next Previous bar.
l 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
l ondone
Note: In Android platform, onEndEditing event will be triggered when the focus is lost from the textbox.
Example, click on any other focusable widget, like a Button.
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
l iPad
l 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 Mobile Web 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:onTextChangeCallBack};
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)
{
}

var txtBasic = {id:"txtBox", isVisible:true, onTextChange:onTextChangeCall
Back};
var txtPSP ={preOnclickJS:preOnclickJSCalBck};

Accessible from IDE
Yes

Syntax
Lua: postonclickjs
Read / Write
JavaScript Example
function postOnclickJSCalBck(txtBox)
{
}

var txtBasic = {id:"txtBox", isVisible:true, onTextChange:onTextChangeCall
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
l keyBoardType
l 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.
l Capitalize Words: This option changes the first character of all the words to uppercase.
l Capitalize sentence: This option changes the first character of all the sentences in a string to
uppercase.
l ALL CAPS: This option changes all the characters to uppercase.
l 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).
l Signed Number: This option allows you to enter a positive or negative sign at the beginning of the
number.
l Decimal Number: This option allows you to enter a decimal point to enter fractional values.
l 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.
l 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)
l NumbersAndPunctuation
l URL
l DigitPad

l PhonePad
l NamePhonePad
l EmailAddress
On Mobile Web and SPA platform, the available keyboard types are as follows:
l default (set as default)

l digitpad
l emailpad
l urlpad
l telpad
l search
On Mobile Web and SPA platform, the available keyboard types are as follows:
l Default - Specifies the default keyboard type.

l Chat - Specifies the keyboard which is helpful for chatting.
l Url - Specifies the keyboard which is helpful for entering URL address.
l Email Name or Address - Specifies the keyboard which is helpful for entering email or address.
l Name or Phone Number - Specifies the keyboard which is helpful for entering names and numbers.
l Postal Address - Specifies the keyboard which is helpful for entering postal address.

l Telephone Number - Specifies the telephone number keyboard.

l Digits - Specifies the keyboard which is helpful for entering numbers.
l Search - Specifies the keyboard which is helpful for searching.
l Formula - Specifies the keyboard which is helpful for entering text and formula.
Type
String
Read / Write
No
Accessible from IDE
Yes
l iPhone
l iPad
l windows phone/windows kiosk
l Mobile Web ( Advanced)
l 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
l Camera
l Hz Image Strip
l ImageGallery
l Map
l ObjectSelector3D
l Phone
l PickerView
l SegmentedUI
l Switch
l SignatureCapture
l Video
l Charts2D3D
l 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.
Platform Specific
Properties
detectTelNumber containerHeight enableOverviewMode
enableZoom containerHeightReference showProgressIndicator
htmlString containerWeight useWideViewport
id margin zoomDensity
info marginInPixel
isVisible
requestURLConfig
screenLevelWidget
Events Methods
handleRequest canGoBack
onFailure canGoForward
onSuccess clearHistory
scrollingEvents goBack
goForward
loadData
reload
Creating a Browser using a constructor: kony.ui.Browser
Var webtemp = new kony.ui.Browser(basicConf, layoutConf, pspConf)

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.
l The Browser widget, unlike other widgets, is considered to be "heavy" widget as far as memory and
performance is considered.
l The Browser widget uses a lot of initial RAM. The RAM usage grows in proportion to the number of
images and static text rendered.
l 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.
l 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.
l You must not use the Browser widget as a RichText widget. It should only be used to display large
HTML content.
l 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.
l On BlackBerry device placing widgets below the browser widget can lead to focus issues especially
when using the trackpad or the trackball.
l 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.
l Server side Mobile Web platform does not support Browser widget in startup form.
l On SPA platform, <script> tag is not supported.
l 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
l enableZoom
l htmlString
l id
l info
l isVisible
l requestURLConfig
l 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
No
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 a 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.
l BROWSER_REQUEST_METHOD_POST
l 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
l containerWeight
l margin
l 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.
l 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]


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
l iPad
l Windows Kiosk

29.3 Browser - Platform Specific Properties

The platform specific properties for Browser Widget are as follows:
l enableOverviewMode
l useWideViewport
l zoomDensity
l The enableOverviewMode and zoomDensity properties are supported only from API level 7 onwards .
The minSDK and target SDK of an application should be 2.1 or above.
l When useWideViewport is set to true, enableOverviewMode and zoomDensity properties are set to
browser widget, then enableOverviewMode takes precedence over zoomDensity property.
l screenLevel browser widget should be directly placed inside a form only then the enableOverviewMode
property will work.
l zoomDensity property is supported only upto Android version 4.3. From Android 4.4 onwards the
desired functionality can be achieved by adjusting the 'width' and 'initial-scale' attributes of page meta
viewport tag or enable “enableOverviewMode” property.
l ZoomDensity property may not be respected in android OS version 4.2.2.
l Refer http://developer.android.com/guide/webapps/targeting.html for information on designing web
pages for Android devices.
l The properties encodeUrlForBrowser, encodeNetAPI, encodeImageURL, and encodeOpenURL are
supported only on iOS platform. These properties are not exposed by IDE. You have to set these
properties in info.plist, using Xcode. By default these properties are set to true. If you do not want
encoding, you can set these properties to false.
29.3.1 enableOverviewMode
Specifies whether the browser should load pages in overview mode. For example, zoom out the content to fit
in the screen width.
Note: To use this property, you must set useWideViewport property and screenLevelWidget property to
true, else the behavior is undefined.
Default: false
Syntax
JavaScript: enableOverviewMode
Type
JavaScript: Boolean

Read / Write
Yes- (Write only)
JavaScript Example
//Defining properties for a Browser widget with containerHeight:100.


frm.browser.enableOverviewMode = true;
Accessible form IDE
No
Available on Android / Android Tablet platforms.
Specifies if the progress indicator must be displayed before loading the URL or executing an event.
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 false.
Syntax
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining properties for a Browser widget to hide progressIndicator.



frm.browser.showProgressIndicator = false;
Accessible from IDE
No
l iOS
l Android/ Android Tablet
29.3.3 useWideViewport
Specifies whether the browser should enable support for the "viewport" HTML meta tag or should use the wide
viewport. If this property is set to true, it loads the browser with the attributes defined in the meta tag of the
webpage. It scales the web page as defined in the html.
Default: false
Syntax
JavaScript: useWideViewport
Type
JavaScript: Boolean
Read / Write
Yes - (Write only)
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};

frm.browser.useWideViewport = true;
Accessible from IDE
No

29.3.4 zoomDensity
Specifies the default zoom density of the page. Following are the available options:
l 0 - FAR ( makes 100% with 240dpi)

l 1 - MEDIUM (makes 100% with 160dpi)
l 2 - CLOSE (makes 100% with 120dpi)
Syntax
JavaScript: zoomDensity
Type
JavaScript: Number
Read / Write
Yes - (Write only)
JavaScript Example
//Defining properties for a Browser widget with containerWeight:100.


frm.browser.zoomDensity = 0;
Accessible from IDE
No

29.4 Browser - Events

Browser Widget has the following events associated:
l handleRequest
l onFailure
l onSuccess
l scrollingEvents
29.4.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:

l Constants.BROWSER_REQUEST_METHOD_GET
l 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
l iPad
29.4.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.4.3 onSuccess
An event callback which gets invoked by the 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.
Note: This event gets called whenever the URL is loaded, or we navigate from one URL to another, or
browser URL internally redirects to another URL. This event is also called whenever the content is loaded,
when a URL contains any third party contents using iframe.
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.

l 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.5 Browser - Methods

Browser Widget has the following methods associated with it:
l canGoBack
l canGoForward
l clearHistory
l goBack
l goForward
l loadData
l reload
29.5.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.5.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.5.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.

browser.clearHistory()
Available on all platforms except on all Server side Mobile Web, SPA, Desktop Web, BlackBerry 10, and
iPhone
29.5.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.5.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.5.6 loadData
This method enables you to load the data into the Browser with the provided configuration.
Signature
JavaScript: <browser>.loadData(data, dataConfig)
Input Parameters
data [String/RawBytes] - Mandatory

The contents of the resource file or image that has to be loaded into the Browser. The contents
should be raw bytes returned by the camera or kony.io.File API.
Note: On Android platform, only string is accepted. The string should be a base64 encoded
image.
dataConfig [JSObject] - Optional

A configuration dictionary for the specified data. Following are the options:
o mimeType [String] [Optional]: Specifies the mime type of the data. the
default mime type is assumed as "text/html". For example,
application/pdf, application/vnd.ms-powerpoint
o encoding [String] [Optional]: Specifies the encoding to be used. The
default encoding is UTF-8. For example, UTF-8 or UTF-16.
o baseURL [String] [Optional]: The base URL for the content. The value is
string specifying the file path.
Return Values
None
Exceptions
This method throws the following exceptions
ERROR CODE ERROR NAME ERROR MESSAGE

100 Error Invalid type of parameters
101 Error Invalid number of arguments
JavaScript Example
//Defining the properties for a Browser widget.

var pdfFile = kony.io.File(path/to/pdf/file);
var data = pdfFile.read();
var config = {"mimeType": "application/pdf", "encoding": "UTF-8"};

browserWidget.loadData(data,config);
Guidelines and limitations of this method
Following are the guidelines and limitations of this method:
1. This method should be called on the Browser widget from the post show of the form.
2. In Android platform, data parameter of the loadData method accepts only a string parameter. All other
parameter types are ignored. Following are the allowed formats for data parameter:
l HTML content string
l base64 image string
3. On iPhone OS version 2.2.1 supports the following documents types:
l Excel (.xls)
l PDF (.pdf)
l PowerPoint (.ppt)
l Word (.doc)
Note: The document formats Excel, PowerPoint, and Word must be saved using Microsoft Office 97 or
newer formats.
29.5.7 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.6 Browser - Deprecated Properties

The deprecated properties for Browser widget are as follows:
l masterData
29.6.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

l 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
base64 containerWeight accessMode
compressionLevel contentAlignment cameraOptions
focusSkin hExpand captureOrientation
id margin enableOverlay
info marginInPixel enableZoom
isVisible padding enablePhotoCropFeature
maxSideOfTheImage paddingInPixel hoverSkin
rawBytes vExpand imageFormat
scaleFactor widgetAlignment nativeUserInterface
skin overlayConfig
text toolTip
Event Methods Deprecated

onCapture closeCamera Auto Store to disk
onCaptureFailed releaseRawBytes mode
onImageSaveFailed takePicture
Creating a Camera using a constructor: kony.ui.Camera
var mycamera = new kony.ui.Camera(basicConf, layoutConf, pspConf)

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.
l 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.
l The click events on camera Overlay form works only if hideControlBar property is set to true.
l On iOS devices, due to technical limitation, avoid overlayForm option when nativeUserInterface
is set to true.
l Using custom controls (like Tap anywhere) is not allowed with hideControlBar property is set to
true.
l For overlay forms that require orientation works only if hideControlBar property is set to true.
l Kony popup added to any of the overlay form widget must be anchored.
l cameraOptions should not be modified in camera preview mode.
l Only pre-show and post show events of the overlay form are respected.
l 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).
l BlackBerry: The following are the important considerations:
l Does not support the overlay form.

l Will always create a file on the local file system.
l The image format is always JPEG.
l 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.

l 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.
l 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
l compressionLevel
l focusSkin
l id
l info
l isVisible
l maxSideOfTheImage
l rawBytes
l scaleFactor
l skin
l text
30.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/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:

l containerWeight
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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.
l CONTENT_ALIGN_TOP_CENTER - Specifies the text should align at top center of the Camera.
l CONTENT_ALIGN_TOP_RIGHT- Specifies the text should align at top right of the Camera.
l CONTENT_ALIGN_MIDDLE_LEFT- Specifies the text should align at middle left of the Camera.
l CONTENT_ALIGN_CENTER- Specifies the text should align at center of the Camera.
l CONTENT_ALIGN_MIDDLE_RIGHT- Specifies the text should align at middle right of the Camera.
l CONTENT_ALIGN_BOTTOM_LEFT- Specifies the text should align at bottom left of the Camera.
Camera.
l 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
l iPad
l 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
l iPad
l 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


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
l cameraOptions
l captureOrientation

l enableOverlay
l enableZoom
l enablePhotoCropFeature
l hoverSkin
l imageFormat
l nativeUserInterface
l overlayConfig
l 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.
l 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.
l 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
l iPad
l Windows Phone
l Windows Kiosk
l 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.

l constants.FLASH_MODE_ON: Specifies the flash must be turned on when you take a picture.
l constants.FLASH_MODE_OFF: Specifies the flash must not be turned on even when you take
a picture.

l 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.
l 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.
l 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.
l 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
l iPad
l 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.
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.
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.

l 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
l 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


//Reading enableOverlay of Camera

Accessible from IDE
Yes
l iPhone
l iPad
l Windows Kiosk
30.3.5 enableZoom
Set this property as true to enable pinch to zoom of camera preview in overlay mode. This property is
supported only when enableOverlay property is set to true.

Note: This property works only on devices with OS 2.2.x and above, which support camera zooming . When
the camera is zoomed, the actual picture size may be smaller than the picture size setting as per Native
Android Documentation.
Default : false
If set to true, the pinch to zoom of camera preview is enabled.
If set to false, the pinch to zoom of camera preview is disabled.
Syntax
JavaScript: enableZoom
Type
JavaScript: Boolean
Read / Write
JavaScript Example
//Defining the properties for a Camera with enableOverlay:true and enableZ

oom:true

frm.camera1.enableZoom = true;
//Reading enableOverlay of Camera

Accessible from IDE
Yes
l Android
l Android Tablet

30.3.6 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
Yes ( Read and 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.7 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.8 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.
l 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
l iPad
30.3.9 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 camPSP={nativeUserInterface:true};

//Reading nativeUserInterface of Camera.

alert("Camera nativeUserInterface::"+camera1.nativeUserInterface);
Accessible from IDE
Yes
l iPhone
l iPad
30.3.10 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

l 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
l 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
l captureButtonSkin : Specifies the skin for a captured button. This option is applicable to Android
platform only.
l 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
l iPad
l Windows Tablet
30.3.11 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
l onCaptureFailed
l onImageSaveFailed
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.4.2 onCaptureFailed
An event callback is invoked when the user has tapped on Don't Allow over permission alert and also when
camera privacy is turned off under iPhone settings. If the user taps on Allow for the very first time it will
immediately open the camera screen. Camera screen will not be shown until the user has set the permission.
Callback will be invoked asynchronously when user selects Don't Allow over permission alert.
The camera permission alert shows up once in app lifecycle. Upgrading or deleting or reinstalling the app will
not trigger the alert, if it has already been shown.
For subsequent camera access, onCaptureFailed is called with status as RESOURCE_ACCESS_

STATUS_DENIED if the user has selected as Don't Allow for the first time or when camera privacy is turned
off under iPhone settings.
Signature
JavaScript: onCaptureFailed
Read / Write
JavaScript Example
//The below function is the callback for onCaptureFailed event of the Came
ra widget.
function onCaptureFailedCalBck(camera)
{
//Write logic here
}

era", isVisible:true, onCaptureFailed:onCaptureFailedCalBck};
var camPSP={};

Accessible from IDE
No
Available on iOS platform

30.4.3 onImageSaveFailed
An event callback is invoked when the user has performed some action over permission alert and also when
image cannot be saved to photo album or due to data save error.
Signature
JavaScript: onImageSaveFailed
Read / Write
JavaScript Example
//The below function is the callback for onImageSaveFailed event of the Ca

mera widget.
function onImageSaveFailedCalBck(camera, status)
{
//Write logic here
}

era", isVisible:true, onImageSaveFailed:onImageSaveFailedCalBck};
var camPSP={};

Accessible from IDE
No
Available on iOS platform
30.5 Camera - Methods

Camera has the following methods associated with it:
l closeCamera
l releaseRawBytes
l 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
l 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 in-
memory.
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
l 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
l iPhone
30.6 Camera - Deprecated Properties

The deprecated properties for Camera widget are as follows:

l Auto store to disk

l 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
l iPhone
l 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
l iPhone
l 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
arrowConfig containerWeight hoverSkin
data imageScaleMode toolTip
focusSkin margin
id marginInPixel
imageWhenFailed padding
imagewhileDownloading paddingInPixel
info referenceHeight
isVisible referenceWidth
selectedIndex widgetAlignment
selectedItem
showArrows
showScrollbars
skin
spaceBetweenImages
viewConfig
viewType

onSelection addAll frameHeight
preOnclickJS addDataAt height
postOnclickJS removeAll width
removeAt
setData
setDataAt
Creating an HorzontalImgStrip using a constructor: kony.ui.HorzontalImageStrip2
var HorizontalImgStrip = new kony.ui.HorizontalImageStrip2 (basicConf, lay

outConf, pspConf)


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.
l 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.
l 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.
l You can scroll through one or more images at a time (platform dependent).
l 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.
l In Android platform, images are displayed from the middle of the widget.
l 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
l data
l focusSkin
l id
l imageWhenFailed

l info
l isVisible
l selectedIndex
l selectedItem
l showArrows
l showScrollbars
l skin
l spaceBetweenImages
l viewConfig
l 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.

l leftArrowFocusImage : Accepts the image to be set as left arrow when in focus.
l rightArrowImage : Accepts the image to be set as right arrow.
l 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.

l [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
31.1.10 selectedItem
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
31.1.14 spaceBetweenImages
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)

l 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)
l 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)
l 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)
l 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.
l 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)
l 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:
BlackBerry /J2ME/
Windows BlackBerry
viewType iPhone Android Windows
Phone/SPA Kiosk 10
HORIZONTAL_IMAGESTRIP_VIEW_TYPE_
STRIPVIEW
Yes Yes Yes Yes Yes
SLOTVIEW
Yes Yes Yes No Yes
LINEAR
Yes No No No No
ROTARY
Yes No No No No
INVERTED_ROTARY
Yes No No No No
CYLINDRICAL
Yes No No No No
INVERTED_CYLINDRICAL
Yes No No No No
COVERFLOW
Yes Yes No No No
COVERFLOW2
Yes No No No No
STACK
Yes No No No No
PAGEVIEW
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.
l 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.
l 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.

l 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.
l 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.
l 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.

l 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.
l 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.

l HORIZONTAL_IMAGESTRIP_VIEW_TYPE_COVERFLOW2 : Similar to the Cover flow view with

more skewing or tilting.
l 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.
l 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
l imageScaleMode
l margin
l marginInPixel
l padding
l paddingInPixel
l referenceHeight
l referenceWidth
l 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.




width.

scalemode.
case,



supported on Mobile Web and SPA. they will render the sourceImage as its actual size.



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
l iPad
l 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
l iPad
l 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


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
l 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
l preOnclickJS
l 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
l addDataAt
l removeAll
l removeAt
l setData
l 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 at index 1 using removeAt method.

hIS.removeAt(1);
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
l height
l viewConfig
l 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)
l coverflowDepth: Accepts a number (in density independent pixel) representing the depth at
which the non-focused images should be rendered. (Available only on android)
l 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
l 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.
l 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)
l 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.

focusSkin containerWeight hoverSkin
Id imageScaleMode itemsPerRow
imageWhenFailed margin navigationBarPosition
imageWhileDownloading marginInPixel noofRowsPerPage
info referenceHeight viewType
isVisible referenceWidth viewConfig
selectedIndex
selectedItem
skin
spaceBetweenImages

onSelection addAll frameHeight
preOnclickJS addDataAt height
postOnclickJS removeAll width
removeAt showItemCount
setData
setDataAt
Creating an Image Gallery using a constructor: kony.ui.ImageGallery
var imagegallery1 = new kony.ui.ImageGallery2 (basicConf, layoutConf, pspC

onf)

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.
l 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.
l referenceHeight: Specifies the reference height of the ImageGallery in pixels.
l referenceWidth: Specifies the reference width of the ImageGallery in pixels.
l skin: Specify the skin to be applied to the images in the Image Gallery.
l 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.

l On devices which have a navigation key, you can use the up or down keys to navigate through the
images.
l 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).
l For Symbian, Image gallery always uses an image size of 64x64 pixels.
l 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
l focusSkin
l id
l imageWhenFailed
l info
l isVisible
l selectedIndex
l selectedItem
l skin
l 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

l [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
32.1.11 spaceBetweenImages
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
l imageScaleMode
l margin
l marginInPixel
l referenceHeight
l 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.




width.

scalemode.
case,



supported on Mobile Web and SPA. they will render the sourceImage as its actual size.



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
l iPad

l 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
l itemsPerRow
l navigationBarPosition
l noofRowsPerPage
l viewType
l 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.
l 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
l preOnclickJS
l 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
l addDataAt
l removeAll
l removeAt
l setData
l 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 removeAll method.

imgGallery.removeAll();

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
l height
l width
l showItemCount

frameHeight referenceHeight
height referenceWidth
width referenceHeight
showItemCount 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.

32.6.4 showItemCount
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
BlackBerry Maps
above)
BlackBerry (Version below 4.5) Google Static Maps
Windows Bing Maps
Google Static Maps, Native maps of the device, and interactive maps
Mobile Web (advanced)
(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
calloutTemplate containerHeight address
calloutWidth containerHeightReference mapHeight
defaultPinImage containerWeight mapSource
id margin mapWidth
info marginInPixel mode
isVisible navControlsImageConfig
locationData showCurrentLocation
mapKey showZoomControl
provider zoomlevel
screenLevelWidget
widgetDataMapForCallout

onClick addPolyline
onPinClick clear


onSelection dismissCallout
getBounds
navigateTo
navigateToLocation
removePolyline
Creating a Map using a constructor: kony.ui.Map
var mymap = new kony.ui.Map(basicConf, layoutConf, pspConf)

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
l Zoom
l 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 Desktop Web platforms.
On BlackBerry platform (Version 4.1 and above), you must ensure the following:

l 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).
l The Map widget should be the last widget on the form. You must ensure this for a good user
experience.
l 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 ip-
address [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
l calloutWidth
l defaultPinImage

l id
l info
l isVisible
l locationData
l mapKey
l provider
l screenlevelwidget
l 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.

l longitude [Number] [Mandatory] : Specifies the longitude of the location.
l name [String] [Mandatory] : Specifies a short description for the location.
l desc [String] [Mandatory]: Specifies a long description for the location.
l image [String] [Mandatory]: Specifies the map pin image that overrides the defaultPinImage.
l showcallout [Boolean] [Optional]: Shows the callout popup. Default value is true.
l 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}
l 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)
l 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
l containerWeight
l margin
l 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.
l 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
l iPad
l Windows Kiosk

33.3 Map - Platform Specific Properties

The platform specific properties for Map Widget are as follows:
l address
l mapHeight
l mapSource
l mapWidth
l mode
l navControlsImageConfig
l showCurrentLocation
l showZoomControl
l 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.
l Server side Mobile Web (BJS) - Location Pin marker is not supported.
l Server side Mobile Web (advanced) - Address popup will not be displayed.
l 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

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.
l MAP_SOURCE_NON_NATIVE : If you select this option, the application uses the map that is on the
device.
l 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)
l 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

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 Satellite Hybrid Street Polygon Traffic Terrain

IOS Yes Yes Yes No No No No
Windows
Yes Yes Yes No No No No
Phone/Kiosk
Android Yes Yes No No No Yes No
SPA Yes Yes Yes No Yes No Yes
Mobile Web
Yes Yes Yes No No No Yes
(basic)
Mobile Web (BJS) Yes Yes Yes No No No Yes
Mobile Web
Yes Yes Yes No Yes No Yes
(Advanced)
DesktopWeb 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
l iPad
l Android
l Server side MobileWeb (basic,BJS,Advanced)
l 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
l zoomOut
l navLeft
l navRight
l navTop
l 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

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
l MAP_VIEW_SHOW_CURRENT_LOCATION_AS_PIN
l 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
l 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.

l Android range: [1-21], default 15.
l 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
l iPhone/iPad
l Windows Tablet
l Windows Kiosk
l BlackBerry 10

33.4 Map - Events

Map has the following events associated with it:
l onClick
l onPinClick
l 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
l clear
l dismissCallout
l getBounds
l navigateTo
l navigateToLocation
l 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.
l 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.
l 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.
l 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.
l 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.
o 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
l 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
l 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.
l northeast [JSObject] : Specifies the latitude and longitude keys and associated values.
l southwest [JSObject] : Specifies the latitude and longitude keys and associated values.
l latspan [number] : Specifies the spanning latitudes in degrees.
l 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
l 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] - Mandatory

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] - Mandatory

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
l 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.
l To display different callouts for different maps.
l 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.

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 walk-
through 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 containerWeight addModel
id contentAlignment clearAllData
info hExpand defineSpecialModels
isVisible margin getSelectedCells
skin marginInPixel setCameraProperties
text padding setMapData
paddingInPixel setRequiredSelectionsCount
vExpand setSelectedCells
widgetAlignment
Event
onSelectionDone
Creating a ObjectSelector3D using a constructor: kony.ui.ObjectSelector3D
var myOS3D = new kony.ui.ObjectSelector3D (basicConf, layoutConf, pspConf)

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.
l 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.

l 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.
l For performance reasons, the models being used must be specifically designed for real-time rendering.
l 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
l id
l info
l isVisible
l skin
l 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
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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

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
l clearAllData
l defineSpecialModels
l getSelectedCells
l setCameraProperties
l setMapData
l setRequiredSelectionsCount
l 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 (SPA), you can use phone.dial API in your
application to initiate a call. But, the Server side 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.
l 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.

focusSkin containerWeight
id contentAlignment
isVisible hExpand
skin margin
text 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.
l 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
l id
l isVisible
l skin
l 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 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 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
l contentAlignment
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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 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
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 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

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.

focusSkin containerWeight
id hExpand
info margin
isVisible marginInPixel
masterData widgetAlignment
masterDataMap
selectedKeys
selectedKeyValues
skin
Events Methods
onSelection setComponentData
setSelectedKeyInComponent
Creating a PickerView using a constructor: kony.ui.PickerView
var picker = new kony.ui.PickerView(basicConf, layoutConf, pspConf)

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
l id
l info
l isVisible
l masterData
l masterDataMap
l selectedKeys
l selectedKeyValues
l 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
l hExpand
l margin
l marginInPixel
l 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
l iPad

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
l 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
l Button
l Image
l Label
l Line
l Link
l RichText
l Phone
l 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 Properties Description

An array of key value pairs with
CheckBoxGroup selectedKeys, selectedKeyValues
the keys as mentioned.
RadioButtonGroup selectedKey, selectedKeyValue
ComboBox selectedKey, selectedKeyValue
TextBox text
TextArea text
An array of the date
Calendar dataComponents
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.

alternateRowSkin containerHeight blockedUISkin
data containerHeightReference border
groupCells containerWeight bounces
id gridCell defaultSelection
info layoutMeta editStyle
isVisible layoutType enableDictionary
needPageIndicator layoutAlignment indicator
orientation margin pressedSkin
pageOnDotImage marginInPixel progressIndicatorColor
pageOffDotImage padding searchBy
pullToRefreshI18NKey paddingInPixel searchCriteria
pullToRefreshSkin showProgressIndicator
pushToRefreshI18NKey viewConfig
pushToRefreshSkin
releaseToPullRefreshI18NKey
releaseToPushRefreshI18NKey
retainSelection
rowSkin
rowFocusSkin
rowTemplate
screenLevelWidget
sectionHeaderSkin
sectionHeaderTemplate
selectedRowIndex
selectedRowIndices
selectedRowItems
selectionBehavior
selectionBehaviorConfig
separatorColor
separatorRequired
separatorThickness
showScrollbars
viewType
viewConfig
widgetDataMap
widgetSkin
Events Methods
onDidFinishDataLoading addAll
onEditing addDataAt
onRowClick addSectionsAt

Events Methods
onSwipe removeAll
scrollingEvents removeAt
preOnclickJS removeSectionsAt
postOnclickJS setData
setDataAt
setSectionAt
Creating a SegmentedUI using a constructor: kony.ui.SegmentedUI2
var seg = new kony.ui.SegmentedUI2 (basicConf, layoutConf, pspConf)

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:
l To provide a list of records or rows from which a user can make a single or multiple selections.
l To display a hierarchy of information. Each row item can lead to different subset of information
displayed in a new list.
l 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:

l 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.
l 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.
l 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.
l 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.
l You can dynamically change the skin of the widgets in the segment by using the Segment Alternate
Methods.
l 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.
l 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.
l 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.
l 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
l data
l groupCells
l id
l info
l isVisible
l needPageIndicator
l orientation
l pageOnDotImage
l pageOffDotImage
l pullToRefreshI18NKey
l pullToRefreshSkin
l pushToRefreshI18NKey
l pushToRefreshSkin
l releaseToPullRefreshI18NKey
l releaseToPushRefreshI18NKey
l retainSelection
l rowSkin
l rowFocusSkin
l rowTemplate
l screenLevelWidget
l sectionHeaderSkin
l sectionHeaderTemplate
l selectedRowIndex
l selectedRowIndices
l selectedRowItems
l selectionBehavior
l selectionBehaviorConfig
l separatorColor
l separatorRequired
l separatorThickness
l showScrollbars
l viewType
l viewConfig

l widgetDataMap
l 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.

l Format 2: Set the data with sections where section header is a name.
l 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 Key Type Comments
JavaScript:
Object Indicates the template to be used for the specific
template Not Applicable
row
Lua: UserData

JavaScript:
metaInfo ( in JS)
Object
Allows to capture row level attributes
metainfo ( in Lua)
Lua: Table
JavaScript:
Boolean Specifies if the row is clickable and supported by
clickable
all platforms.
Lua: Boolean
JavaScript:
Number
Lua: Number
Possible values
eidtMode is only applicable if the editStyle has
constants.SEG been set to either constants.SEGUI_EDITING_
UI_EDIT_ STYLE_ICON or constants.SEGUI_EDITING_
MODE_ STYLE_SWIPE
INSERT (
editMode ( in JS) displays a "+"
If the editMode property is not specified for a row
icon on the left then it is not enabled for editing (even though an
editmode ( in Lua)
handside of the editStyle has been set).
row)
constants.SEGUI_EDIT_MODE_INSERT is not
constants.SEG applicable for constants.SEGUI_EDITING_
UI_EDIT_ STYLE_SWIPE
MODE_
DELETE (
displays a "-"
icon on the left
handside of the
row)
JavaScript:
Object ID of the skin that needs to be applied to the
skin
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.

l BOX_LAYOUT_HORIZONTAL: Enables you to stack the content within the SegmentedUI

horizontally.
l 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
37.1.11 pullToRefreshI18NKey
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
37.1.12 pullToRefreshSkin
Specifies the skin to be applied to the pull to refresh title. This property does not support image as
background.

l font_weight
l font_style
l font_size
l font_color
l font_name
l background_color
l bg_type
l background_style
Syntax
JavaScript: pullToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE
Yes
37.1.13 pushToRefreshI18NKey
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
37.1.14 pushToRefreshSkin
Specifies the skin to be applied to the push to refresh title. This property does not support image as
background.
l font_weight
l font_style
l font_size
l font_color
l font_name
l background_color
l bg_type
l background_style
Syntax
JavaScript: pushToRefreshSkin
Type
JavaScript: String
Read / Write
Accessible from IDE
Yes

37.1.15 releaseToPullRefreshI18NKey
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
37.1.16 releaseToPushRefreshI18NKey
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 side Mobile 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
l iPhone
l Windows Phone
l 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
37.1.19 rowFocusSkin
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
JavaScript Example
//Defining the properties for a Segment with rowTemplate:box1, where box1

is a box that should be created and made accessible.
owSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",

sectionHeaderSkin:"secHSkin", widgetDataMap:{widgetId1:"dataid1", widgetId

2:"dataId2", widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDa
taId2" },rowTemplate:box1, sectionHeaderTemplate:box2, separatorRequired:t
rue, separatorThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,s
creenLevelWidget:false, groupCells:true, retainSelection:true, needPageInd
icator:true, pageOnDotImage:"dot.png", pageOffDotImage:"off.png", selectio
nBehavior:constants.SEGUI_MULTI_SELECT_BEHAVIOR, selectionBehaviorConfig:{
imageIndetifier:img, selectedStateImage:"sel.png", unselectedStateImage:"u
nSel.png"}, selectedRowIndex:4,selectedRowIndices:[4,5]};
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
l 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.
l 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.

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, 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 screenLevelWidget of the SegmentedUI

alert("SegmentedUI screenLevelWidget ::"+segment.screenLevelWidget);
Accessible from IDE
Yes
l iPad
l iPhone
l Windows Phone
l 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".

widgetId3:"dataId3", widgetId4:"secDataId1", widgetId5:"secDataId2" },rowT
rThickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW, screenLevelWid
electedRowIndex:4,selectedRowIndices:[4,5]};
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
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.
[1,4] indicates 5th 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.

stants.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, ...],
[sectionIndex3, [rowIndex4, rowIndex5, ...],
.....
]
For example:
l [ [0, [2] ] ] indicates 3rd row is selected in the first selection.

l [ [0, [1, 4] ] ] indicates 2nd and 5th rows are selected in the first section.
l [ [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
Thickness:20, viewType:constants.SEGUI_VIEW_TYPE_PAGEVIEW ,screenLevelWidg
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.
l 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.
l 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).
l 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",


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.
l 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.
l 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.

l 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.
l 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.

l 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.
l 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
On Android platform, 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.
3. Click the Ellipsis ( ) 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.
l spaceBetweenRowItems [Number]: Specifies the space between each row. It accepts

the value in pixels.
l rowItemWidth[Number]: Specifies the width in percentage relative to its parent width. It

accepts a range between 1 and 100.
l 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.
On iOS platform, this property is applicable only when enableDictionary property is set to true. The index of
the dictionary is displayed as a bar on the right side of the segment. This property helps you to customize the
indexColor, indexBackgroundColor, and indexTrackingBackgroundColor.
This property is a map with the following key:
tableViewConfig[JSObject]: This is a string key whose value is a map which accepts the configurations for
customizing the index bar of the table view. Following are the keys and their respective values:
indexColor [String]: Specifies the color of the index in hex format as a string. This option is
available from iOS 6 and above.
indexBackgroundColor [String]: Specifies the background color of the index in hex format as
a string. This option is available from iOS 7 and above.
indexTrackingBackgroundColor [String]: Specifies the tracking background color of the

index in hex format as a string. This option is available from iOS 6 and above.
Note: All the above keys are optional.
In the below snapshots, the indexBackgroundColor is set as blue and indexTrackingBackgroundColor is set
as red. When the form is loaded, indexBackgroundColor is displayed as blue, but when you scroll then the red
color is applied to the bar.

Syntax
Type
Read / Write
JavaScript Example for Android
//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 ={};


JavaScript Example for iOS
//Defining the properties for a Segment with viewConfig.

Template:box1, viewConfig:{tableViewConfig:{indexColor:"ffffff64", indexBa
ckgroundColor: "ffffff00", indexTrackingBackgroundColor: "ffff0000"}}};
var segPSP ={};

Accessible from IDE
Yes (only for Android )
l iPad
l iPhone
37.1.35 widgetDataMap
Note: It is developer responsibility to ensure that Widget datamap to accommodate all the widget ids
{
widgetId3: "dtaId3",
}
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
lectedRowIndex: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
l containerWeight
l gridCell
l layoutMeta
l layouType
l layoutAlignment
l margin
l marginInPixel
l padding
l 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.
l 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:
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
l Desktop Web
37.2.5 layoutMeta
Syntax
Lua: layoutmeta
Type
Lua: Table
Read / Write
JavaScript Example
//Defining the properties for a Segment with layoutMeta.

rowSkn", rowFocusSkin:"rowFSkn", alternateRowSkin:"altSkin",


taId2" }, rowTemplate:box1};
layoutMeta: {
"cols": 8,
"colmeta": ["15", "15", "15", "15", "15", "15", "5", "5"],
"rows": 4
}};
var segPSP ={};

Accessible from IDE
Yes
l Windows Tablet
l Desktop Web
37.2.6 layoutType
Defines the type of the layout of widget. Following are the available options:
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
l 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.

l BOX_LAYOUT_ALIGN_FROM_CENTER: The widgets placed inside a SegmentedUI are aligned
center.
l 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
l iPad
l 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
l border
l bounces
l contextMenu
l defaultSelection
l dockSectionHeaders
l editStyle
l enableDictionary
l indicator
l pressedSkin
l progressIndicatorColor
l searchBy
l searchCriteria
l 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.

l SEGUI_BORDER_TOP_ONLY: The border is displayed on top of the segment.
l SEGUI_BORDER_BOTTOM_ONLY: The border is displayed at the bottom of the segment.
l SEGUI_BORDER_BOTH_BOTTOM_TOP: The border is displayed on top and bottom of the segment.
Note: This property is applicable only when the segment viewType is set to SEGUI_VIEW_TYPE_TABLE_
VIEW.

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
VIEW.
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
l 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
BlackBerry Touch BlackBerry Non-Touch

BlackBerry 6.x
Device (<6.x) Device (<6.x)

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
l Windows Phone
l 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.
VIEW.
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

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 set to
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

l SEGUI_EDITING_STYLE_ICON: An icon will be displayed on the left hand side of each row.
l 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.
l SEGUI_EDITING_STYLE_NONE: No special edit styles are applied.
VIEW.
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
l 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, viwType is set to SEGUI_
VIEW_TYPE_TABLE_VIEW, 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
l 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
l 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.
37.3.11 progressIndicatorColor
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

l 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
l 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 and viewType
is set to SEGUI_VIEW_TYPE_TABLE_VIEW.
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
l 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, viewType is
set to SEGUI_VIEW_TYPE_TABLE_VIEW, 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.
l SEGUI_SEARCH_CRITERIA_ENDSWITH: The search is performed on the strings that end with the
input string.
l 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",


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:
{imageIndetifier:img, selectedStateImage:"sel.png", unselectedStateImage:"
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
l 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
l 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
l onEditing
l onRowClick
l onSwipe
l scrollingEvents
l preOnclickJS
l 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
l 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
l SEGUI_VIEW_TYPE_COVERFLOW (iOS and Android)
l SEGUI_VIEW_TYPE_STACK (iOS)
l SEGUI_VIEW_TYPE_LINEAR (iOS)
l SEGUI_VIEW_TYPE_ROTATORY (iOS)
l SEGUI_VIEW_TYPE_INVERTED_ROTARY (iOS)
l SEGUI_VIEW_TYPE_CYLINDER (iOS)
l 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
l Segment viewType must be set as SEGUI_VIEW_TYPE_TABLEVIE
l 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
l addDataAt
l addSectionAt
l removeAll
l removeAt
l removeSectionAt
l setData
l setDataAt
l 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 SegmentedUI - Templates
37.6.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.6.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.

l to achieve the behavior of having widgets such as an Image and a label for all the section headers of
the segment.
l to perform an action on the event of an onclick of an item or a widget in the section header.
37.6.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.6.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 containerWeight onSlide
info margin
isVisible marginInPixel
leftSideText widgetAlignment
Left Text i18n Key
rightSideText
Right Text i18n Key
selectedIndex
skin
Creating a Switch using a constructor: kony.ui.Switch
var myswitch = new kony.ui.Switch(basicConf, layoutConf, pspConf)

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.
l 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.

l 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.
l Following are the changes and behavior of Switch widget in iOS7 and above:
l Right background color has no effect.

l Size of the switch is fixed as 51 x 31 px. Hence the hExpand property has no effect.
l Left side text and right side text has no effect.
l 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
l info
l isVisible
l leftSideText
l Left Text i18n Key
l rightSideText
l Right Text i18n Key
l selectedIndex
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l Desktop Web
38.2 Switch - Layout Properties

The layout properties for Switch Widget are as follows:
l containerWeight
l margin
l marginInPixel
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l Desktop Web

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
l Windows Phone

l Windows Tablet
l SPA
l 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
l Windows Phone
l Windows Tablet
l SPA
l 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.
Platform Specific
Properties
id containerWeight accessMode
info hExpand
isVisible margin
penWidth marginInPixel
rawBytes padding
skin paddingInPixel
vExpand
widgetAlignment
Event Methods
onCapture clear
save
Creating a Signature using a constructor: kony.ui.SignatureCapture
var mysignature = new kony.ui.SignatureCapture(basicConf, layoutConf, pspC

onf)

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, signatureLay
out, {})

//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.
l 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 id
l info
l isVisible
l penWidth
l rawBytes
l skin
39.1.1 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"


out, {})
//Reading the id of the SignatureCapture.

alert("SignatureCapture id is ::"+signature.id);
Accessible from IDE
Yes
l Windows Tablet
l Windows Phone
39.1.2 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
l Windows Phone
39.1.3 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
l Windows Phone
39.1.4 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


out, {})
Accessible from IDE
Yes
l Windows Tablet
l Windows Phone
39.1.5 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
l Windows Phone
39.1.6 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
l Windows Phone
39.2 SignatureCapture - Layout Properties

The layout properties for SignatureCapture Widget are as follows:
l containerWeight
l hExpand
l margin
l marginInPixel
l padding
l paddingInPixel
l vExpand
l 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
l 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:constan
ts.WIDGET_ALIGN_TOP_LEFT, containerWeight:100};

out, {})
Accessible from IDE
Yes
l Windows Tablet
l 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
l 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
l 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
l 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
l 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.



out, {})
Accessible from IDE
Yes
l Windows Tablet
l Windows Phone
Syntax
Type
JavaScript: Number
Lua: Number
Read / Write
No

JavaScript Example
//Defining the properties for a SignatureCapture with widgetAlignment.


out, {})
Accessible from IDE
Yes
l WindowsTablet
l 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.
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.
l 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
l 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 the signature and clicks on a button or image where the
save method is called.
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_INMEMOR
Y};

out, signaturePSP )
Accessible from IDE
Yes
l Windows Tablet
l Windows Phone 8

39.5 SignatureCapture - Methods

SignatureCapture widget has the following methods associated with it:
l clear
l save
39.5.1 clear
This method enables you to clear the area where a signature is captured.
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
l Windows Phone

39.5.2 save
Saves the signature as an image and executes onCapture callback. You can access the saved image through
rawBytes property. This property is also used to assign image to Image or Button widget as background
image.
Signature
JavaScript: save ()
Lua:signaturecapture.save(signaturecatureId)
Input Parameters
signaturecatureId[widgetref] - Mandatory
Return Values
None
JavaScript Example


out, {})
//signature save method call.

signature.save();
Error Codes
None
l Windows Tablet
l 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.
l To play an advertisement within the form.
l To play a video which provides product features.

id containerWeight controls
isVisible margin poster
skin padding
source widgetAlignment
text
Creating a Video using a constructor: kony.ui.Video
var video = new kony.ui.Video(basicConf, layoutConf, pspConf)

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:
widgetAlignment: Specifies the alignment of the widget.
margin: Defines the space around a widget.
padding: Defines the space between the content of the widget and the widget boundaries.
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.
l If you have two videos in a form, you can only play one at a time.
Supported devices and video formats for SPA platform.
Video XHTML
Format Mandatory
Category and
OS Browser (WebM, Attributes Comments
Device
OGG, MP4, Height/Wi
OGV) dth
BB Non Touch - Native BB Video tag doesn't render without
BB 6 MP4 Supported
BlackBerry 9780 bold Browser XHTML attributes
BB 7.0 (touch) -
Native BB
BlackBerry 9900 Bold BB 7 MP4 na
and BlackBerry 9860
Browser
BB 6.0 (touch) -
Native BB not
BlackBerry 9800 BB 6 na
Torch
Browser supported
Windows Phone
not
Mango - Dell Venue Win 7.5 IE9 na
Pro
supported
Native
Samsung Galaxy S2 - Android
Android MP4 na
amsung I9100 2.3.3
Webkit
Native
Android MP4 na
amsung I9100 4.0.4
Webkit
Native
Android MP4 na
amsung I9100 4.0.4
Webkit
iPhone - iPhone iOS 4.2.1 Safari MP4 na
iPhone - iPhone iOS 6.1.3 Safari MP4 na
Windows Phone 8 -
Windows Phone 8 OS8 IE10 MP4 na
(Nokia)

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
l isVisible
l skin
l source
l 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"};

//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
l margin
l padding
l 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

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
l 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)
l 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 Mobile Web (advanced)

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.
Platform Specific
Common Properties Methods
Properties
Skin Needs Separator createAppMenu
Focus Skin Appbar Button Style setCurrentAppMenu
ID Position 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.
l You cannot specify a skin for the App Menu.
BlackBerry Specific Behavior
l Image for a App Menu item will not be displayed.

l 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.
l 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.
o Use show/hide app menu items as required.
o 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.
l The text describing the app menu icons are always in a lowercase.
l Only One Color Background style is supported for the App Menu.
l 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.
l 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
l Focus Skin
l ID
l Title
l Icon
l Render
l i18n Key
l 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.
Note: When an application supports more than one locale and you require different text for a different locale,
you have to destroy the form before locale change. Even if the forms are destroyed, the appmenu will remain
in the old locale. To overcome this behavior, you have to re-create the appmenu every time locale is
changed. To recreate the appmenu, use createAppMenu method.
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
l Appbar Button Style
l 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
l BOTTOM_RIGHT
l TOP_LEFT
l 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
l setCurrentAppMenu
l getCurrentAppMenu
l setAppMenuFocusByID
l addAppMenuItemAt
l removeAppMenuItemAt
l setAppMenuBadgeValue
l 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.

l menuitemName: Name of the menu item.

l menuitemImage: The image to be used for the menu item (image will not be displayed on
Blackberry platform).
l menuitemClosure: onclick event to be executed for the menu item.
l 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.

l menuitemImage: The image to be used for the menu item (image will not be displayed
on BlackBerry platform).
l menuitemSeparator: (Applicable on BlackBerry only) A boolean value to hide/show the
separator below the menu item. Default: true (the separator is shown).
l 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
l setAppMenuFocusIndex
l showAppMenuItems
l 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.

l menuitemImage: The image to be used for the menu item (image will not be displayed on
Blackberry platform).
l 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?

l Navigation Keys
l Achieving 508 Compliance Using Kony Studio
l 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 table below shows different platforms and their assistive technology:
Platform Assistive Technology

iOS VoiceOver
Android TalkBack
SPA 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 Android touch

based devices Purpose (Android 4.1 and iOS touch
(desktop) higher) (talkback)
To move focus in One finger right/down
Tab One finger right flick gesture
forward direction flick gesture
To move focus in One finger left/up flick
Shift+Tab One finger left flick gesture
reverse direction gesture
To take action on the
Enter /Space One finger double tap One finger double tap
focused widget
To increase the value
Right Arrow/Up selection on specific
One finger up flick gesture
Arrow widgets like
slider/picker
To decrease the value
Left Arrow/Up selection on specific
One finger up flick gesture
Arrow widgets like
slider/picker
To scroll up/left of the
Two/three finger up/left
Page Up content in a scroll Three fingers up/right flick gesture
flick gesture
container.
To scroll down/right the
Two/three finger
Page Down content in a scroll Three fingers down/right flick gesture
down/right flick gesture
container
Starts reading from the
Two fingers up flick gesture
beginning of the page
Starts reading from the
Two fingers down flick gesture
current focused item
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
l iOS: https://www.apple.com/in/accessibility/osx/voiceover/
l 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.
3. Click the Ellipsis ( ) 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.
l 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.
l a11yHint: Specifies the descriptive text that explains the action about the widget.
l 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.
l 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
l Android
l 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
l HBox
l VBox
l ScrollBox
l Popup
42.3.1 Form
l Tab key or equivalent touch gesture moves the focus to the first
focusable child widget of the form.
l Multiple tabs move the focus to the interactive child widgets of the
Keyboard/Gesture-based form.
Interactions l 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.
l The a11yLabel overrides the text of the title property.

l The a11yValue, a11yHint, and a11yHidden fields are not applicable to
Default Behavior form and are ignored.
l accessibilityConfig property is supported in iPhone, Android, and SPA-
iPhone platforms.

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.
l 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.
l In Android OS versions less than 4.2, form does not scroll, although it
Limitations 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.
l Accessibility capability of the ActionBar is left to the device default
behavior.
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.
l SPA-Android: accessibilityconfig is not supported
42.3.2 HBox
l Tab key or equivalent touch gesture moves the focus along the tab
order when:
a. Box is clickable
Keyboard/Gesture based b. accessibilityConfig is defined.

Interactions
l With a focus on the HBox, press Spacebar or Enter or equivalent
gesture action to select the HBox when it is clickable.
l 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

Default Behavior
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.
l 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.
42.3.3 VBox
order when:
a. Box is clickable.
Keyboard/Gesture based b. accessibilityConfig is defined.

Interactions
l With a focus on the VBox, press Space or Enter or equivalent gesture
action to select the VBox when it is clickable.
l Multiple tabs or navigation keys help in navigating focus to the child
widgets that are actionable.

Default Behavior
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 l 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.
l 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.
42.3.4 ScrollBox
order when accessibilityConfig is defined.
Keyboard/Gesture based l Multiple tabs or navigation keys help in navigating focus to the child
Interactions widgets that are actionable.
l Page Up / Page Down or equivalent key/gesture allows you to scroll
the content of the ScrollBox.

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.
l 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.
42.3.5 Popup
l Tab key or equivalent touch gesture moves the focus to the first
Keyboard/Gesture based focusable child widget of the Popup.
Interactions l Multiple tabs move the focus to the interactive child widgets of the
Popup.
l The a11yLabel overrides the text of the title property.
l The a11yValue, a11yHint, and a11yHidden fields are not applicable to
Default Behavior Popup and are ignored.
l accessibilityConfig property is supported in iPhone, Android, and SPA-
iPhone platforms.

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.
l 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
Limitations 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.
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.
l 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
l Calendar
l CheckBox
l ComboBox
l Image
l Label
l Line
l Link
l ListBox
l RadioButton
l RichText
l Slider

l TextArea
l TextBox
42.4.1 Button
l With a focus on the Button, press the Spacebar or Enter key or

equivalent gesture action to select the Button.
Keyboard/Gesture based
Interactions l Single finger double tap to execute the action.
l Accessible by the tab key or equivalent touch gesture along tab order.

Default Behavior
platforms.
iOS: None
Android: None
SPA:
Limitations
l SPA-iPhone: None
l 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 l CALENDAR_VIEW_TYPE_DEFAULT (Android)

l CALENDAR_VIEW_TYPE_WHEEL_POPUP (iPhone)
l CALENDAR_VIEW_TYPE_ GRID_POPUP (iPhone and SPA)
l With a focus on the Calendar, press the Spacebar or Enter key or
equivalent gesture action to launch the date selector.
Interactions
l You can reach to each available day, month, and year in a calendar
through one/some of the keys or touch gestures.
Default Behavior l accessibilityConfig property is supported in iPhone, Android, and SPA

platforms.

l a11yValue is not applicable.

l It is recommended to provide accessibility text to the assistive
technology to read the date when the tab focus/gesture makes a
Limitations selection.
l accessibilityConfig is not supported for the viewTypes that are not
focused as a whole.
42.4.3 CheckBox
l Multiple tabs or navigation keys help in navigating the focus to each
Keyboard/Gesture based check button in the group.
Interactions
l 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.

iOS: Following are the limitations of iOS platform based on the selected
viewType:
viewType accessibilityConfig
Items within
Widget Level
widget
CHECKBOX_VIEW_TYPE_LISTVIEW Respected Ignored *
CHECKBOX_VIEW_TYPE_TOGGLEVIEW Ignored Respected
CHECKBOX_VIEW_TYPE_
Ignored Ignored
ONSCREENWHEEL
CHECKBOX_VIEW_TYPE_TABLEVIEW Ignored Respected
* accessibilityConfig is ignored when set through masterData or

masterDataMap to the items within the widget that pops up as pickerview
Limitations
from the bottom.
Android: None
SPA:
l 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.
l 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
Example code Click here to view the sample code
42.4.4 ComboBox
l Tab key or equivalent touch gesture along tab order.

l With a focus on the ComboBox, press the Spacebar or Enter key or
equivalent gesture action to open the drop-down list.
Interactions l 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:
Items Within
Widget Level
Widget
COMBOBOX_VIEW_TYPE_LISTVIEW Respected Ignored *
COMBOBOX_VIEW_TYPE_TABLEVIEW Ignored Respected
COMBOBOX_VIEW_TYPE_TOGGLEVIEW Ignored Respected
COMBOBOX_VIEW_TYPE_
Ignored Ignored
ONSCREENWHEEL

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:
l 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.
l 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
Tab key or equivalent touch gesture along tab order.
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
SPA-Android: The option a11yHint is not supported.

42.4.6 Label
Description A Label widget is used to display non-editable text to the user.

Tab key or equivalent touch gesture along tab order.
Interactions
accessibilityConfig property is supported in iPhone, Android, and SPA-

Default Behavior
Android platforms.
iOS: None
Android: None
SPA:
Limitations
l SPA-iPhone: accessibilityConfig property is not supported.
l SPA-Android:The option a11yHint is not supported
42.4.7 Line
Not accessible by the tab key or equivalent touch gesture.
Interactions
Default Behavior accessibilityConfig property is not supported.
Limitations None
42.4.8 Link
l With a focus on the link, press the Spacebar or Enter key or equivalent
gesture action to select the link.
Interactions l Single finger double tap to execute the action.
l Tab key or equivalent touch gesture along tab order.

Default Behavior
platforms.

iOS: None
Android: None
SPA:
Limitations
l SPA-iPhone: None
42.4.9 ListBox
l With a focus on the ListBox, press the Spacebar or Enter key or
equivalent gesture to open the drop-down list.
Interactions l 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.

viewType:
Items Within
Widget Level
Widget
LISTBOX_VIEW_TYPE_LISTVIEW Supported Ignored *
LISTBOX_VIEW_TYPE_TABLEVIEW Ignored Supported
LISTBOX_VIEW_TYPE_TOGGLEVIEW Ignored Supported
LISTBOX_VIEW_TYPE_
Ignored Ignored
ONSCREENWHEEL

from the bottom.
Limitations
Android: If the accessibilityConfig is set, it will override the selected item.
SPA:
l 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.
l 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
l With a focus on the RadioButton, press the Spacebar or Enter key or
equivalent gesture to change the selection state of the focused item.
Interactions
item in the RadioButton.

platforms.

iOS: Following are the limitations of the iOS platform based on the selected
viewType:
Items Within
Widget Level
Widget
RADIOGROUP_VIEW_TYPE_LISTVIEW Supported Ignored *
RADIOGROUP_VIEW_TYPE_
Ignored Supported
TABLEVIEW
Ignored Supported
TOGGLEVIEW
Ignored Ignored
ONSCREENWHEEL
Limitations * accessibilityConfig is ignored when set through masterData or
from the bottom is ignored.
Android: None
SPA:
l SPA-iPhone: accessibilityConfig for RadioButton as a whole is not

supported, but the items within the widget are supported.
l 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
Accessible by the tab key or equivalent touch gesture along tab order.
Interactions

Default Behavior
platforms.
On all platforms, links inside a RichText widget are not accessible.
Limitations SPA-Android: The option a11yHint is not supported.

42.4.12 Slider
Keyboard/Gesture based l With a focus on the Slider, press the Right / Up key or equivalent
Interactions gesture to increase the value of the slider. Press the Left / Down key or
equivalent gesture to decrease the value of the slider.

platforms.
Android: Android OS cannot change the slider value when accessibility is set.
SPA:
l SPA-iPhone: Browsers cannot change the slider value when

Limitations
accessibility is set.
l SPA-Android: Browsers cannot change the slider value when
accessibility is set.
42.4.13 TextArea
l With a focus on the TextArea, press the Spacebar or equivalent

gesture to open the soft keypad for touch devices.
Keyboard/Gesture based l Single finger double tap to execute the action.
Interactions
l Soft keypad gains focus on explicit touch on the soft keypad.

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
l With a focus on the TextBox, press the Spacebar or equivalent gesture

to open the soft keypad for touch devices.
Keyboard/Gesture based l Single finger double tap to execute the action.
Interactions
l 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
l Camera
l Hz Image Strip
l PickerView
l SegmentedUI
l Switch
42.5.1 Alert
Description An Alert is a dialog displayed to show an alert message.

l Touch gesture: Single finger double tap.

l Accessible by the tab key or equivalent touch gesture to navigate and
Keyboard/Gesture based focus on the buttons and messages of the Alert dialog box.
Interactions l With a focus on the Alert button, press the Enter or Spacebar or
equivalent gesture to select the button.
l 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

Keyboard/Gesture based l Accessible by the tab key or equivalent touch gesture along tab order.
Interactions
l With a focus on the camera, press the Enter or Spacebar or equivalent
gesture to launch the camera.
Default Behavior l accessibilityConfig property is supported in iPhone and Android

platforms.
Limitations accessibilityConfig property is not supported in SPA platform
42.5.3 Hz Image Strip

Keyboard/Gesture based l On multiple tabs or equivalent touch gesture, move the focus to the
Interactions images where accessibility is configured and visible on the screen.
l 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.
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
Limitations 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:
l 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.
l 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.
Example code sample code
42.5.4 PickerView

l Every column in the PickerView is reachable by the tab key or
equivalent touch gesture.
Interactions l 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.
l With a focus on the PickerView, press the Enter or Spacebar or
equivalent gesture to select the focused item in the PickerView.
l accessibilityConfig property is supported in Android platforms.
Default Behavior

iOS: accessibilityConfig is not supported
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
Limitations
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.
42.5.5 SegmentedUI - TABLEVIEW
A SegmentedUI is a container widget to display multiple rows of information in

Description
vertical order.
l Accessible by the tab key or equivalent touch gesture along the tab
order moves the focus to the first row.
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
Interactions
focus to the next row until it reaches the last visible row.
l 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.
l 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.
l accessibilityConfig is applied to the row template, and then
Default Behavior accessibility is applied to each row, unless overridden by the row data.
l 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.

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 SPA:
l SPA-iPhone: If the accessibilityConfig is set to a row of a

SegmentedUI, then actionable child widgets of the row become
inaccessible.
l 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.
42.5.6 SegmentedUI - PAGEVIEW
A SegmentedUI is a container widget to display multiple rows of information in

Description
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
Keyboard/Gesture based focus out of the widget.
Interactions
l 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.
l 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.
l At widget level accessibilityConfig property is not respected. It is
respected only for the page level in iPhone, Android, and SPA
platforms.
l accessibilityConfig applied to the row template and its internal widgets
Default Behavior are applied to each row, unless overridden by the row data.
l 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.

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.
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.
Limitations
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.
l 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.
42.5.7 Switch
Interactions l With a focus on the Switch, press the Enter key or Spacebar or
equivalent gesture to toggle the state and initiate the action.
Default Behavior l accessibilityConfig property is supported in iPhone and SPA

platforms.
iOS: The option a11yValue is not supported.
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
l addAt: This method is used to add widgets to the container at the specified index.
l removeAt: This method removes a widget at the given index from the container.
l replaceAt: This method replaces a widget with another widget in the container.
l setVisibility: This method is used to set the visibility of the widget.
l 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.

l Replace a widget with another widget.
l 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
l animDuration

l animDelay
l animCurve
l 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
l HBox
l VBox
l Button
l Label
l Image
l Calendar
l 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.
l constants.ANIMATION_CURVE_EASEOUT: This option specifies the

animation effect to slowdown towards the end.
l constants.ANIMATION_CURVE_EASEINOUT: This option specifies the

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

specifies the animation effect to continue with the same speed from start
to end.



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.
l animDuration: The default option is set to 1 second.

l animDelay: The default option is set to 0 seconds.
l animCurve: The default option is set to constants.ANIMATION_CURVE_LINEAR
43.2 Animation Limitations

This section provides the knows limitations of animations:

l Animation callbacks are expected to be light weight and avoid calling heavy end operations such as
network calls, SQL Lite, etc.
l 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.
l Touching a widget, when an animation is in progress may lead to undefined behavior.
l The animation effect constants.ANIMATION_PLATFORM_DEFAULT is not respected when used in
animation configuration while invoking an operation.
l 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.
l 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:
l You must add parent widget and then child widget with animation.
l If you remove some widgets, then remove the child widgets first with animation and then the
parent widget.
l If you replace a widget using replaceAt method, do not make layoutAnimConfig applicable for
the new widget to avoid unwanted animations.
l 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.
l 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.
l 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).
l 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.
l 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.

l 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.
l 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.

l A VBox cannot be placed within another VBox.
l The width of a widget in a VBox is the width of the VBox.
l The height of a VBox is the cumulative height of the child widgets.
l 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 Desktop Web 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
l 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 except on
Button, SegmentedUI, HBox, and VBox. For example, the below code will not work.
form.map.onPinClick = callback method()

//The callback method is a JSObject
7. 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.
8. The property focusSkin is not supported for TextBox widget.
9. The font style with underline is not supported for TextBox widget.
10. Skin font style with underline is supported only for widgets RichText and Link.
11. All BlackBerry 10 supported widget events are not writable.

12. 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.
13. 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.
14. 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.

15. 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.
16. Following are the RadioButton widget limitations:

c. Overriding the default ticked and unTicked images is not supported.
17. Following are the Calendar widget limitations:

c. Grid calendar view is not supported.
d. Skin is not supported for Calender widget.

46. Glossary
base64
Returns the base64 encoded string of the image raw bytes. It is applic-
able for few widgets such as Image, Camera, and SignatureCapture wid-
gets.
Basic Properties
Widgets properties are classified into three groups. Basic properties, Lay-
out Properties and Platform Specific Properties. Most of the Basic Prop-
erties 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.
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 read-
only view of a small amount of data in a tabular format.
Event
Events are functions that are associated with respective widgets are
executed to perform a sequence of actions, when the condition is sat-
isfied.
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 wid-
gets. 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 foot-
ers scroll together. A form is also the top most container widget. A form
can contain any number of widgets but cannot contain another form.
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 lim-
itations, 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
Specifies the look and feel of a widget when the cursor hovers on the wid-
get.
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
Label
Label widget is used to display non-editable text on the form and is non-
interactive.

Layout Properties
Widgets properties are classified into three groups. Basic properties, Lay-
out Properties and Platform Specific Properties. Most of the Layout Prop-
erties 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, wid-
getAlignment 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 exper-
ience.
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.
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 ele-
ment.
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.
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.
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 bot-
tom 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 dis-
played 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.
Platform Specific Properties

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 con-
tent, 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.
RadioButtonGroup
RadioButtonGroup is a widget that allows you to define a set of radio but-
tons and the user can choose one of it as an option. A radio button usu-
ally 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 dis-
play text with styles (bold, underlined etc.), links, and images. You can
use a RichText widget to show a read-only text.
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.
TabPane
TabPane widget is a container widget that allows you to organize mul-
tiple 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.
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 align-
ment attribute. For example, WIDGET_ALIGN_TOP_LEFT specifies the
vertical alignment as TOP and horizontal alignment as LEFT.

Examen Itil v3 Preguntas y Respuestas

Cargado por

Información del documento

Título original

Derechos de autor

Formatos disponibles

Compartir este documento

Compartir o incrustar documentos

Opciones para compartir

¿Le pareció útil este documento?

¿Este contenido es inapropiado?

Copyright:

Formatos disponibles

Examen Itil v3 Preguntas y Respuestas

Cargado por

Copyright:

Formatos disponibles

Kony Studio

Cloud and On-Premises Widget

Copyright © 2012 Kony, Inc.

All Rights Reserved.

Copyright © 2012 Kony, Inc. All Rights Reserved. Page 2 of 1833

Date Document Version Description of Modifications/Release

l Widget Level Animation

5/13/2014 16.0 l Minor enhancements for SegmentedUI and ScrollBox

Copyright © 2012 Kony, Inc. All Rights Reserved. Page 3 of 1833

Date Document Version Description of Modifications/Release

12/24/2014 18.0 Document Release for 5.6.4

Copyright © 2012 Kony, Inc. All Rights Reserved. Page 4 of 1833

1.2 Intended Audience 61

1.3 Typographical Conventions 61

1.4 Reference Documents 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.3 Widget Skins 79

2.3.1 Dynamic Skinning 80

2.3.2 Platform Specific Skin Limitations 82

4.1 Form - Basic Properties 90

Copyright © 2012 Kony, Inc. All Rights Reserved. Page 5 of 1833

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

Copyright © 2012 Kony, Inc. All Rights Reserved. Page 6 of 1833

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