Kony Widget User Guide

Kony Studio

Cloud and On-Premises WidgetGuide

Release 5.6

Kony Widget User Guide - Ver 17.0

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

Copyright 2012 Kony, Inc.

All Rights Reserved.

September, 2014

This document contains information proprietary to Kony, Inc., is bound by the Kony license agreements andmay not be used except in the context of understanding the use andmethods of Kony Inc, software withoutprior, express, written permission. Kony, Empowering Everywhere, Kony MobileFabric, and Kony Visualizerare trademarks of Kony, Inc. Microsoft, theMicrosoft logo, Internet Explorer, Windows, andWindows Vistaare 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 otherterms, trademarks, or servicemarks mentioned in this document have been capitalized and are to beconsidered the property of their respective owners.



Revision History

Date Document Version Description of Modifications/Release

31/08/2012 1.0Document Release. 2D/3DChart wizard is dropped in 5.0 andfuture versions will have support for revamped and sophisticatedcharts.

20/09/2012 2.0 Updated onDestroy event for Form and Popup.09/11/2012 3.0 Updated Windows 8 and Desktop Web platform.

14/12/2012 4.0 Updated MenuContainer and enhancements of SegmentedUIand TabPane.11/01/2013 5.0 Updated Windows Phone and minor changes.

05/03/2013 6.0 New methods added for ScrollBox widget, and info added forMap V2 for Map Widget. Added SignatureCapture Widget05/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 platform8/30/2013 10.0 New event added for Browser widget and minor enhancements

9/24/2013 11.0Updated 5.5 features. New features added for Calendar, Slider,SegmentedUi, Map, TextBox, Popup, ScrollBox,SignatureCapture and Tabpane widgets.

10/25/2013 12.0 Added BlackBerry 10 platform12/3/2013 13.0 Document Release for 5.52/21/2014 14.0 Document Release for 5.5.2. Charts widget updated3/28/2014 15.0 Added onCancel event for TextBox

5/13/2014 16.0

l Added Accessibility properties for applicable widgets

l Widget Level Animation

l Minor enhancements for SegmentedUI and ScrollBoxwidgets.

l iOS7 support for Form, Popup, Slider,RadioButton,ComboBox, ListBox, and AppMenu widgets.



Date Document Version Description of Modifications/Release

8/1/2014 17.0

Added new properties in the following widgets for 5.6.2release:

l ScrollBox

l TabPane

l Popup

l Calendar

l CheckBox

l ComboBox

l DataGrid

l ListBox

l RadioButton

l TextArea

l TextBox

l Browser

l SegmentedUI



Table of Contents

1. Overview 61

1.1 Scope 61

1.2 Intended Audience 61

1.3 Typographical Conventions 61

1.4 Reference Documents 62

1.5 Contact Us 62

2. Working with Widgets 63

2.1 Widget Classification 64

2.1.1 ContainerWidgets 64

2.1.2 Basic Widgets 64

2.1.3 Advanced Component Widgets 65

2.2 Widget Methods 65

2.2.1 setVisibility 66

2.2.2 setFocus 69

2.2.3 setEnabled 70

2.2.4 setGestureRecognizer 71

2.2.5 removeGestureRecognizer 75

2.2.6 setBadge 76

2.2.7 getBadge 77

2.3 Widget Skins 79

2.3.1 Dynamic Skinning 80

2.3.2 Platform Specific Skin Limitations 82

3. Container Widgets 85

4. Form 86

4.1 Form - Basic Properties 90

4.1.1 enabledForIdleTimeout 91

4.1.2 footers 92



4.1.3 headers 93

4.1.4 id 94

4.1.5 info 95

4.1.6 menuFocusSkin 96

4.1.7 menuItems 97

4.1.8 menuNormalSkin 98

4.1.9 needAppMenu 99

4.1.10 skin 100

4.1.11 title 101

4.1.12 type 102

4.2 Form - Layout Properties 103

4.2.1 displayOrientation 103

4.2.2 gridCell 105

4.2.3 layoutMeta 106

4.2.4 layoutType 107

4.2.5 padding 108

4.2.6 paddingInPixel 110

4.3 Form - Platform Specific Properties 112

4.3.1 actionBarIcon 113

4.3.2 animateHeaderFooter 113

4.3.3 bounces 114

4.3.4 captureGPS 115

4.3.5 contextPath 117

4.3.6 configureExtendTop 118

4.3.7 configureExtendBottom 118

4.3.8 configureBarStyle 119

4.3.9 defaultIndicatorColor 120

4.3.10 enablePeekGesture 120



4.3.11 extendTop 121

4.3.12 extendBottom 122

4.3.13 statusBarStyle 123

4.3.14 footerOverlap 124

4.3.15 formTransparencyDuringPostShow 125

4.3.16 headerOverlap 126

4.3.17 inputAccessoryViewType 127

4.3.18 inTransitionConfig 130

4.3.19 layout 134

4.3.20 maxAppMenuButtons 135

4.3.21 menuPosition 135

4.3.22 needsIndicatorDuringPostShow 136

4.3.23 noCache 137

4.3.24 outTransitionConfig 138

4.3.25 retainScrollPosition 142

4.3.26 scrollDirection 143

4.3.27 secureData 144

4.3.28 showBottomActionBar 145

4.3.29 showActionBar 146

4.3.30 showActionBarIcon 147

4.3.31 showMiniAppMenu 147

4.3.32 submitSecure 149

4.3.33 titleBar 150

4.3.34 titleBarConfig 151

4.3.35 titleBarSkin 152

4.3.36 viewConfig 153

4.3.37 windowSoftInputMode 155

4.4 Form - Events 157



4.4.1 addWidgets 157

4.4.2 init 158

4.4.3 onActionBarBack 159

4.4.4 onHide 160

4.4.5 onOrientationChange 161

4.4.6 onDeviceBack 161

4.4.7 onDeviceMenu 162

4.4.8 onDestroy 163

4.4.9 preShow 164

4.4.10 postShow 165

4.4.11 onLoadJS 166

4.4.12 unLoadJS 167

4.5 Form -Methods 169

4.5.1 add 169

4.5.2 addAt 170

4.5.3 show 173

4.5.4 destroy 174

4.5.5 remove 175

4.5.6 removeAt 176

4.5.7 replaceAt 179

4.5.8 widgets 182

4.5.9 setTitleBarLeftSideButtonSkin 183

4.5.10 setTitleBarRightSideButtonSkin 183

4.5.11 setTitleBarSkin 184

4.5.12 showTitleBar 185

4.5.13 hideTitleBar 185

4.5.14 scrollToWidget 186

4.5.15 scrollToBeginning 187



4.5.16 scrollToEnd 187

4.6 Form - Deprecated Properties and Events 188

4.6.1 Dockable Appmenu 189

4.6.2 Dockable Header 189

4.6.3 Dockable Footer 190

4.6.4 Enable Back 190

4.6.5 Ignore Escape 191

4.6.6 masterdataload 191

4.6.7 menu Renderer 191

4.6.8 transactionaldataload() 192

4.6.9 undockappheader 192

4.6.10 undockappfooter 193

5. HBox 194

5.1 HBox - Basic Properties 195

5.1.1 focusSkin 195

5.1.2 id 196

5.1.3 info 197

5.1.4 isVisible 198

5.1.5 orientation 199

5.1.6 position 200

5.1.7 skin 202

5.2 HBox - Layout Properties 203

5.2.1 containerWeight 203

5.2.2 gridCell 204



5.2.5 layoutAlignment 207

5.2.6 margin 208



5.2.7 marginInPixel 210

5.2.8 padding 211


5.2.10 percent 214

5.2.11 vExpand 216

5.2.12 widgetAlignment 217

5.3 HBox - Platform Specific Properties 219

5.3.1 blockedUISkin 219

5.3.2 borderCollapse 220

5.3.3 contextMenu 221

5.3.4 hoverSkin 225


5.4 HBox - Events 228

5.4.1 onClick 228

5.4.2 onHover 229

5.4.3 onRightClick 232

5.4.4 preOnclickJS 233

5.4.5 postOnclickJS 234

5.5 HBox - Methods 235

5.5.1 add 235

5.5.2 addAt 236

5.5.3 remove 239

5.5.4 removeAt 240

5.5.5 replaceAt 243

5.5.6 widgets 246

5.6 Context Menu- Templates 247

5.6.1 What is a Template for a Context Menu 247

5.6.2 Where to use a Context MenuTemplate 247



5.6.3 Creating a Template for Context Menu 247

5.6.4 Using Context Menu Template 247

6. VBox 249

6.1 VBox - Basic Properties 250

6.1.1 focusSkin 250

6.1.2 id 251

6.1.3 info 252

6.1.4 isVisible 253


6.1.6 skin 255

6.2 VBox - Layout Properties 256


6.2.2 gridCell 257




6.2.6 margin 262


6.2.8 padding 265



6.3 VBox - Platform Specific Properties 270


6.3.2 borderCollapse 271


6.3.4 hoverSkin 276


6.4 VBox - Events 278



6.4.1 onClick 278

6.4.2 onHover 279




6.5 VBox - Methods 285

6.5.1 add 285

6.5.2 addAt 286

6.5.3 remove 289

6.5.4 removeAt 290

6.5.5 replaceAt 293

6.5.6 widgets 296

6.6 Context Menu- Templates 298

6.6.1 What is a Template for a Context Menu 298

6.6.2 Where to use a Context MenuTemplate 298

6.6.3 Creating a Template for Context Menu 298

6.6.4 Using Context Menu Template 298

7. ScrollBox 300

7.1 ScrollBox - Basic Properties 302

7.1.1 enableScrollByPage 302

7.1.2 id 303

7.1.3 info 304

7.1.4 isVisible 305


7.1.6 position 307

7.1.7 pullToRefreshI18NKey 308

7.1.8 pullToRefreshSkin 309

7.1.9 pushToRefreshI18NKey 310



7.1.10 pushToRefreshSkin 310

7.1.11 releaseToPullRefreshI18NKey 311

7.1.12 releaseToPushRefreshI18NKey 312

7.1.13 scrollDirection 312

7.1.14 showScrollbars 313

7.1.15 skin 314

7.2 ScrollBox - Layout Properties 315

7.2.1 containerHeight 316

7.2.2 containerHeightReference 317



7.2.5 margin 320


7.2.7 padding 323


7.2.9 percent 326

7.3 ScrollBox - Platform Specific Properties 327

7.3.1 bounces 327


7.3.3 scrollArrowConfig 330


7.4 ScrollBox - Events 333

7.4.1 scrollingEvents 333

7.5 ScrollBox - Methods 336

7.5.1 add 336

7.5.2 addAt 337

7.5.3 remove 338

7.5.4 removeAt 339






7.5.8 widgets 343

8. TabPane 345

8.1 TabPane - Basic Properties 348

8.1.1 activeFocusSkin 348

8.1.2 activeSkin 349

8.1.3 activeTabs 350

8.1.4 id 351

8.1.5 inactiveSkin 352

8.1.6 info 353

8.1.7 isVisible 354

8.1.8 retainPositionInTab 355

8.1.9 screenLevelWidget 356


8.1.11 viewType 359

8.2 TabPane - Layout Properties 360




8.2.4 gridCell 364



8.2.7 margin 368


8.2.9 padding 371




8.3 TabPane - Platform Specific Properties 374

8.3.1 pageSkin 374

8.3.2 progressIndicatorColor 376

8.3.3 showProgressIndicator 377

8.3.4 tabHeaderTemplate 378

8.3.5 tabHeaderHeight 378

8.4 TabPane - Events 380

8.4.1 onTabClick 380



8.5 TabPane -Methods 384

8.5.1 addTab 384

8.5.2 addTab 385

8.5.3 addTabAt 386

8.5.4 removeTabAt 387

8.5.5 removeTabByld 388

8.6 Tab header - Templates 390

8.6.1 What is a Template for tabHeader and where to use it 390

8.6.2 Creating a Template for tabHeader 390

8.6.3 Using tabHeader Template 390

9. Popup 392

9.1 Popup - Basic Properties 394

9.1.1 footers 395

9.1.2 headers 396

9.1.3 id 396

9.1.4 info 397

9.1.5 isModal 398

9.1.6 skin 399



9.1.7 title 400

9.1.8 transparencyBehindThePopup 401

9.2 Popup - Layout Properties 403




9.2.4 gridCell 406



9.2.7 padding 409


9.3 Popup - Platform Specific Properties 413

9.3.1 bounces 413

9.3.2 captureGPS 414

9.3.3 contextPath 416

9.3.4 configureExtendTop 416

9.3.5 draggable 417

9.3.6 extendTop 418

9.3.7 footerOverlap 419

9.3.8 headerOverlap 420

9.3.9 inputAccessoryViewType 420

9.3.10 inTransitionConfig 423

9.3.11 layout 426

9.3.12 minimizeOnLostFocus 427

9.3.13 noCache 428

9.3.14 outTransitionConfig 429

9.3.15 popupStyle 431

9.3.16 resizable 432



9.3.17 secureData 433

9.3.18 showMiniAppMenu 434

9.3.19 submitSecure 435

9.3.20 titleBarConfig 436


9.3.22 windowSoftInputMode 439

9.4 Popup - Events 441

9.4.1 addWidgets 441

9.4.2 init 441

9.4.3 onHide 442

9.4.4 onDeviceBack 443

9.4.5 onLoadJS 444

9.4.6 unLoadJS 445

9.5 Popup - Methods 447

9.5.1 add 447

9.5.2 addAt 448

9.5.3 destroy 449

9.5.4 dismiss 450

9.5.5 navigateTo 451

9.5.6 remove 452

9.5.7 removeAt 453




9.5.11 setContext 456

9.5.12 setTitleBarLeftSideButtonSkin 458

9.5.13 setTitleBarRightSideButtonSkin 459

9.5.14 setTitleBarSkin 460



9.5.15 showTitleBar 461

9.5.16 hideTitleBar 462

9.5.17 show 462

9.5.18 widgets 463

9.6 Popup - Deprecated Properties 464

9.6.1 closureLeftSideView 465

9.6.2 closureRightSideView 466

9.6.3 dockableAppMenu 466

9.6.4 imageLeftSideView 466

9.6.5 imageRightSideView 467

9.6.6 nift 467

9.6.7 onOrientationChange 467

9.6.8 orientationmode 468

9.6.9 renderTitleText 468

9.6.10 reset Focus to top of the Form 468

9.6.11 skin Around Popup 469

9.6.12 titleBar 469

9.6.13 titleBarLeftSideView 470

9.6.14 titleBarRightSideView 470

10. Basic Widgets 471

11. Button 472

11.1 Button - Basic Properties 475

11.1.1 focusSkin 475

11.1.2 id 476

11.1.3 info 477

11.1.4 isVisible 478

11.1.5 rawBytes 479

11.1.6 skin 480



11.1.7 text 481

11.2 Button - Layout Properties 482


11.2.2 contentAlignment 483

11.2.3 displayText 485

11.2.4 hExpand 486

11.2.5 margin 488


11.2.7 padding 491


11.2.9 vExpand 494


11.3 Button - Platform Specific Properties 497



11.3.3 externalURL 500

11.3.4 glowEffect 501

11.3.5 hoverSkin 502

11.3.6 pressedSkin 503


11.3.8 submitURL 505

11.3.9 toolTip 506

11.4 Button - Events 507

11.4.1 onClick 507



11.5 Button - Deprecated Properties 510

11.5.1 focusimage 510



11.5.2 image 511

11.5.3 normalimage 511

12. Calendar 512

12.1 Calendar - Basic Properties 519

12.1.1 calendarIcon 519

12.1.2 dateComponents 520

12.1.3 dateFormat 522

12.1.4 day 523


12.1.6 formattedDate 525

12.1.7 hour 526

12.1.8 id 527

12.1.9 info 528


12.1.11 minutes 530

12.1.12 month 531

12.1.13 placeholder 532

12.1.14 seconds 533

12.1.15 skin 534

12.1.16 validStartDate 535

12.1.17 validEndDate 536


12.1.19 viewType 539

12.1.20 year 541

12.2 Calendar - Layout Properties 541



12.2.3 hExpand 544



12.2.4 margin 546


12.2.6 padding 549


12.2.8 vExpand 552


12.3 Calendar-Platform Specific Properties 555

12.3.1 cellTemplate 556



12.3.4 dateEditable 559

12.3.5 data 560

12.3.6 dayTextAlignmentInCell 562

12.3.7 displayedMonth 563

12.3.8 hideDaysHeader 564

12.3.9 hideMonthsHeader 565


12.3.11 mode 567

12.3.12 noOfMonths 568

12.3.13 titleOnPopup 569

12.3.14 toolTip 570

12.3.15 widgetDataMapForCell 571

12.4 Calendar - Event 573

12.4.1 onSelection 573

12.5 Calendar - Methods 574

12.5.1 clear 574

12.5.2 clearData 575

12.5.3 enableRangeOfDates 576



12.5.4 navigateToPreviousMonth 577

12.5.5 navigateToNextMonth 578

12.5.6 removeDataAt 579

12.5.7 setData 580

12.5.8 setDataAt 581

12.5.9 setEnabled 582

12.5.10 setEnableAll 584

12.5.11 setDatesSkin 585

12.6 Calendar - Deprecated Properties 586

12.6.1 date 586

12.6.2 format 588

12.6.3 monthI18Nkey 588

12.6.4 weekdayI18Nkey 589

12.7 gridcalender - Templates 589

12.7.1 What is a Template for gridcalendar 589

12.7.2 Where to use a gridcalendar Template 590

12.7.3 Creating a Template for gridcalendar 590

12.7.4 Using gridcalendar Template 590

13. CheckBoxGroup 592

13.1 CheckBox - Basic Properties 596


13.1.2 id 597

13.1.3 info 598


13.1.5 masterData 600

13.1.6 masterDataMap 602

13.1.7 selectedKeys 604

13.1.8 selectedKeyValues 605



13.1.9 skin 605

13.2 CheckBox - Layout Properties 606


13.2.2 itemOrientation 607

13.2.3 margin 608


13.2.5 padding 611



13.3 CheckBox - Platform Specific Properties 616

13.3.1 focusTickedImage 616

13.3.2 focusUnTickedImage 617

13.3.3 groupCells 617


13.3.5 tickedImage 619

13.3.6 toolTip 620

13.3.7 unTickedImage 621

13.3.8 viewType 622

13.3.9 wheelBackgroundColor 625

13.4 CheckBox - Events 627




14. ComboBox 631

14.1 ComboBox - Basic Properties 635


14.1.2 id 637

14.1.3 info 638






14.1.7 selectedKey 643

14.1.8 selectedKeyValue 644

14.1.9 skin 645

14.2 ComboBox - Layout Properties 646



14.2.3 hExpand 648

14.2.4 margin 649


14.2.6 padding 652


14.2.8 vExpand 655


14.3 ComboBox - Platform Specific Properties 659


14.3.2 dropDownImage 660




14.3.6 popupFocusSkin 664

14.3.7 popupSkin 665

14.3.8 popupTitle 665


14.3.10 toolTip 667







14.4 ComboBox- Events 676




14.5 ComboBox - Deprecated Properties 678

14.5.1 placeholderi18nKey 679

15. DataGrid 680

15.1 DataGrid - Basic Configuration Properties 684

15.1.1 columnHeadersConfig 684

15.1.2 data 686

15.1.3 gridHeight 689

15.1.4 headerSkin 690

15.1.5 id 691

15.1.6 info 692

15.1.7 isMultiSelect 693


15.1.9 rowAlternateSkin 696

15.1.10 rowCount 697

15.1.11 rowFocusSkin 698

15.1.12 rowNormalSkin 699

15.1.13 scrollable 700

15.1.14 selectedIndex 701

15.1.15 selectedIndices 702

15.1.16 selectedItem 703

15.1.17 selectedItems 705



15.1.18 showColumnHeaders 706

15.2 DataGrid - Layout Properties 707



15.2.3 margin 710

15.2.4 padding 712


15.3 DataGrid - Platform Specific Properties 717


15.3.2 containerHeightInPixel 718

15.3.3 dockingHeader 719

15.3.4 enableScrollBar 720

15.3.5 gridlineColor 721


15.3.7 selectedCellItem 723

15.3.8 selectedCellIndex 724

15.3.9 toolTip 725

15.4 DataGrid - Events 727

15.4.1 onRowSelected 727

15.5 DataGrid - Methods 729

15.5.1 addAll 729

15.5.2 addDataAt 730

15.5.3 applyCellSkin 731

15.5.4 removeAll 733

15.5.5 removeAt 734

15.5.6 selectAllRows 735

15.5.7 setCellDataAt 736

15.5.8 setData 737




15.6 DataGrid - Templates 741

15.6.1 What is a Template for DataGrids 741

15.6.2 Where to use aGrid Template 741

15.6.3 Creating a Template for DataGrid 741

15.6.4 Using Grid Template 742

16. Image 743

16.1 Image - Basic Properties 745

16.1.1 base64 746

16.1.2 id 747

16.1.3 imageWhenFailed 748

16.1.4 imageWhileDownloading 749

16.1.5 info 750


16.1.7 rawBytes 752

16.1.8 src 753

16.2 Image - Layout Properties 754


16.2.2 imageScaleMode 755

16.2.3 margin 760


16.2.5 padding 763


16.2.7 referenceHeight 766

16.2.8 referenceWidth 767


16.3 Image - Platform Specific Properties 770

16.3.1 glossyEffect 770




16.3.3 renderAsAnchor 772

16.3.4 skin 773

16.3.5 toolTip 774

16.4 Image - Events 775

16.4.1 onDownloadComplete 775

16.5 Image - Deprecated Properties 776

16.5.1 hExpand 776

16.5.2 scaleMode 777

16.5.3 vExpand 778

17. Label 780

17.1 Label - Basic Properties 782

17.1.1 id 782

17.1.2 info 783


17.1.4 skin 785

17.1.5 text 786

17.1.6 toolTip 787

17.2 Label - Layout Properties 788



17.2.3 hExpand 791

17.2.4 margin 793


17.2.6 padding 796


17.2.8 vExpand 799




17.3 Label - Platform Specific Properties 802

17.3.1 hoverSKin 802

17.3.2 pasteboardType 803

17.3.3 renderAsAnchor 804

17.3.4 textCopyable 805

17.3.5 toolTip 806

17.3.6 wrapping 807

18. Line 809

18.1 Line - Basic Properties 811

18.1.1 id 811

18.1.2 info 812


18.1.4 skin 814

18.2 Line - Layout Properties 815

18.2.1 margin 815


18.2.3 thickness 818

18.3 Line - Platform Specific Properties 819

18.3.1 toolTip 819

18.3.2 Line - Platform Specific Properties 821

19. Link 822

19.1 Link - Basic Properties 825


19.1.2 id 826

19.1.3 info 827


19.1.5 skin 829

19.1.6 text 830



19.1.7 toolTip 831

19.2 Link - Layout Properties 832



19.2.3 hExpand 835

19.2.4 margin 836


19.2.6 padding 839



19.3 Link - Platform Specific Properties 844



19.3.3 externalURL 847

19.3.4 glowEffect 848



19.3.7 submitURL 851

19.3.8 toolTip 852

19.4 Link - Events 854

19.4.1 onClick 854



19.5 Link - Deprecated Properties 857

19.5.1 focusImage 857

19.5.2 image 858

19.5.3 normalImage 858

20. ListBox 859



20.1 ListBox - Basic Properties 860


20.1.2 id 862

20.1.3 info 863








20.1.11 skin 872

20.2 ListBox - Layout Properties 873



20.2.3 hExpand 876

20.2.4 margin 877


20.2.6 padding 880


20.2.8 vExpand 883


20.3 ListBox - Platform Specific Properties 887

20.3.1 applySkinsToPopup 887







20.3.6 multiSelect 893

20.3.7 multiSelectRows 894

20.3.8 nativeListFieldSkin 894

20.3.9 nativeListFieldFocusSkin 895


20.3.11 placeholderSkin 898

20.3.12 popupIcon 898

20.3.13 popupTitle 900


20.3.15 toolTip 902





20.4 ListBox - Events 910




20.5 ListBox - Deprecated Properties 913

20.5.1 listStyle 913

20.5.2 multiple 914

20.5.3 placeholderi18nKey 915



21. MenuContainer 917

21.1 MenuContainer - Basic Properties 921

21.1.1 activeSkin 921

21.1.2 data 923




21.1.4 id 926

21.1.5 info 928


21.1.7 menuItemTemplate 930


21.1.9 selectedMenuIndex 933

21.1.10 selectedMenuItem 934

21.1.11 skin 936

21.1.12 widgetDataMap 938

21.2 MenuContainer - Layout Properties 939


21.2.2 margin 941


21.2.4 padding 944



21.3 MenuContainer - Platform Specific Properties 949


21.3.2 collapsedImage 952

21.3.3 expandedImage 954

21.3.4 viewType 955

21.4 MenuContainer - Event 958

21.4.1 onClick 958


21.5 MenuContainer - Methods 963

21.5.1 addAll 963





21.5.4 removeAt 968

21.5.5 setData 970


21.6 Menu - Templates 975

21.6.1 What is a Template for Menu 975

21.6.2 Where to use aMenu Template 975

21.6.3 Creating a Template for Menu 975

21.6.4 UsingMenu Templates 976

22. MenuItem 978

22.1 MenuItem - Basic Properties 980

22.1.1 focusImage 980

22.1.2 id 981

22.1.3 info 981

22.1.4 image 982

22.1.5 title 983

22.1.6 type 983

22.2 Menuitem - Event 985

22.2.1 onClick 985

23. RadioButtonGroup 986

23.1 RadioButtonGroup - Basic Properties 990


23.1.2 id 991

23.1.3 info 992








23.1.9 skin 1000

23.2 RadioButtonGroup - Layout Properties 1001


23.2.2 hExpand 1002

23.2.3 itemOrientation 1003

23.2.4 margin 1005


23.2.6 padding 1008


23.2.8 vExpand 1011


23.3 RadioButtonGroup - Platform Specific Properties 1015


23.3.2 focusTickedImage 1016

23.3.3 focusUnTickedImage 1017





23.3.8 toolTip 1022


23.3.10 viewType 1024



23.4 RadioButtonGroup - Events 1031






24. RichText 1035

24.1 RichText - Basic Properties 1038

24.1.1 id 1039

24.1.2 info 1039


24.1.4 linkSkin 1041

24.1.5 skin 1042

24.1.6 text 1043

24.2 RichText - Layout Properties 1044



24.2.3 hExpand 1047

24.2.4 margin 1048


24.2.6 padding 1051


24.2.8 vExpand 1054


24.3 RichText - Platform Specific Properties 1057


24.3.2 linkFocusSkin 1058

24.3.3 superScriptSkin 1059

24.3.4 telephoneLinkSkin 1060

24.3.5 toolTip 1061

24.3.6 wrapping 1061

24.4 RichText - Events 1064

24.4.1 onClick 1064





25. Slider 1068

25.1 Slider - Basic Configuration Properties 1070

25.1.1 focusThumbImage 1071

25.1.2 id 1072

25.1.3 info 1072


25.1.5 leftSkin 1075

25.1.6 max 1076

25.1.7 min 1077

25.1.8 rightSkin 1078

25.1.9 selectedValue 1079

25.1.10 step 1080

25.1.11 thumbImage 1081

25.2 Slider - Layout Properties 1082


25.2.2 margin 1084



25.3 Slider - Platform Specific Properties 1089

25.3.1 enableThumbTintColor 1089

25.3.2 maxLabel 1090

25.3.3 maxLabelSkin 1091

25.3.4 maxValueImage 1092

25.3.5 minLabel 1093

25.3.6 minLabelSkin 1094

25.3.7 minValueImage 1095




25.3.9 thickness 1097

25.3.10 thumbOffset 1098

25.3.11 thumbTintColor 1099

25.3.12 viewType 1100

25.4 Slider - Events 1102


25.4.2 onSlide 1103

26. TextArea 1105

26.1 TextArea - Basic Properties 1108

26.1.1 autoCapitalize 1108


26.1.3 id 1110

26.1.4 info 1111


26.1.6 keyBoardStyle 1113

26.1.7 maxTextLength 1116

26.1.8 numberOfVisibleLines 1117


26.1.10 secureTextEntry 1119

26.1.11 skin 1120

26.1.12 text 1121

26.1.13 textInputMode 1122

26.2 TextArea - Layout Properties 1124



26.2.3 hExpand 1126

26.2.4 margin 1128




26.2.6 padding 1131



26.3 TextArea - Platform Specific Properties 1137

26.3.1 autoCorrect 1137


26.3.3 closeButtonText 1139


26.3.5 keyboardActionLabel 1142



26.3.8 showCloseButton 1146


26.3.10 toolTip 1149

26.4 TextArea - Events 1149

26.4.1 onDone 1150

26.4.2 onBeginEditing 1151

26.4.3 onEndEditing 1152

26.4.4 onKeyUp 1153

26.4.5 onKeyDown 1154

26.4.6 onTextChange 1154

26.5 TextArea - Deprecated Properties 1155

26.5.1 editable 1155

26.5.2 No of Rows 1156

27. TextBox 1157

27.1 TextBox - Basic Properties 1160

27.1.1 autoCapitalize 1160




27.1.3 id 1163

27.1.4 info 1164


27.1.6 keyBoardStyle 1166

27.1.7 maxTextLength 1169


27.1.9 secureTextEntry 1171

27.1.10 skin 1172

27.1.11 text 1173

27.1.12 textInputMode 1174

27.1.13 toolTip 1175

27.2 TextBox - Layout Properties 1177



27.2.3 containerHeightMode 1179



27.2.6 hExpand 1182

27.2.7 margin 1184


27.2.9 padding 1187



27.3 TextBox - Platform Specific Properties 1192

27.3.1 autoComplete 1192

27.3.2 autoCorrect 1194

27.3.3 autoFilter 1195




27.3.5 closeButtonText 1198

27.3.6 filterList 1200


27.3.8 keyboardActionLabel 1201

27.3.9 leftViewImage 1203

27.3.10 nativeListFieldFocusSkin 1204

27.3.11 nativeListFieldSkin 1205



27.3.14 showClearButton 1209

27.3.15 showCloseButton 1210


27.3.17 toolTip 1213

27.3.18 viewType 1213

27.4 TextBox - Events 1215

27.4.1 onCancel 1216

27.4.2 onDone 1217

27.4.3 onBeginEditing 1218

27.4.4 onEndEditing 1218

27.4.5 onKeyUp 1220

27.4.6 onKeyDown 1221

27.4.7 onTextChange 1222



27.5 TextBox - Deprecated Properties 1224

27.5.1 inputStyle 1224

27.5.2 keyBoardType 1225



27.5.3 Type 1228

28. Advanced Widgets 1229

29. Browser 1230

29.1 Browser - Basic Properties 1234

29.1.1 detectTelNumber 1234

29.1.2 enableZoom 1235

29.1.3 htmlString 1236

29.1.4 id 1237

29.1.5 info 1238


29.1.7 requestURLConfig 1240


29.2 Browser - Layout Properties 1243




29.2.4 margin 1246


29.3 Browser - Events 1249

29.3.1 handleRequest 1249

29.3.2 onFailure 1250

29.3.3 onSuccess 1251


29.4 Browser - Methods 1254

29.4.1 canGoBack 1255

29.4.2 canGoForward 1256

29.4.3 clearHistory 1256

29.4.4 goBack 1257



29.4.5 goForward 1258

29.4.6 reload 1259

29.5 Browser - Deprecated Properties 1260


30. Camera 1262

30.1 Camera - Basic Properties 1266

30.1.1 base64 1266

30.1.2 compressionLevel 1267


30.1.4 id 1269

30.1.5 info 1270


30.1.7 maxSideOfTheImage 1272

30.1.8 rawBytes 1273

30.1.9 scaleFactor 1274

30.1.10 skin 1275

30.1.11 text 1276

30.2 Camera - Layout Properties 1276



30.2.3 hExpand 1279

30.2.4 margin 1281


30.2.6 padding 1284


30.2.8 vExpand 1287


30.3 Camera - Platform Specific Properties 1289



30.3.1 accessMode 1290

30.3.2 cameraOptions 1291

30.3.3 captureOrientation 1293

30.3.4 enableOverlay 1294

30.3.5 enablePhotoCropFeature 1295


30.3.7 imageFormat 1297

30.3.8 nativeUserInterface 1298

30.3.9 overlayConfig 1299

30.3.10 toolTip 1301

30.4 Camera - Event 1302

30.4.1 onCapture 1302

30.5 Camera - Methods 1302

30.5.1 closeCamera 1303

30.5.2 releaseRawBytes 1304

30.5.3 takePicture 1305

30.6 Camera - Deprecated Properties 1306

30.6.1 Auto store to disk 1306

30.6.2 mode 1307

31. HorizontalImageStrip 1310

31.1 HorizontalImageStrip - Basic Properties 1312

31.1.1 arrowConfig 1313

31.1.2 data 1314


31.1.4 id 1316



31.1.7 info 1319






31.1.11 showArrows 1323


31.1.13 skin 1325

31.1.14 spaceBetweenImages 1326


31.1.16 viewType 1328

31.2 HorizontalImageStrip - Layout Properties 1333



31.2.3 margin 1339


31.2.5 padding 1342





31.3 HorizontalImageStrip - Platform Specific Properties 1349


31.3.2 toolTip 1350

31.4 HorizontalImageStrip - Events 1352




31.5 HorizontalImageStrip - Methods 1356

31.5.1 addAll 1356





31.5.4 removeAt 1359

31.5.5 setData 1360


31.6 HorizontalImageStrip - Deprecated 1363

31.6.1 frameHeight 1363

31.6.2 height 1363


31.6.4 width 1365

32. ImageGallery 1366

32.1 ImageGallery - Basic Properties 1368

32.1.1 data 1368


32.1.3 id 1370



32.1.6 info 1372




32.1.10 skin 1376

32.1.11 spaceBetweenImages 1377

32.2 ImageGallery - Layout Properties 1378



32.2.3 margin 1384






32.3 ImageGallery - Platform Specific Properties 1390


32.3.2 itemsPerRow 1391

32.3.3 navigationBarPosition 1391

32.3.4 noofRowsPerPage 1392



32.4 ImageGallery - Events 1396




32.5 ImageGallery - Methods 1400

32.5.1 addAll 1400




32.5.5 setData 1403


32.6 ImageGallery - Deprecated Properties 1406

32.6.1 frameHeight 1406

32.6.2 height 1407

32.6.3 width 1407

32.6.4 showItemCount 1408

33. Map 1409

33.1 Map - Basic Properties 1417

33.1.1 calloutTemplate 1418



33.1.2 calloutWidth 1418

33.1.3 defaultPinImage 1419

33.1.4 id 1420

33.1.5 info 1421


33.1.7 locationData 1423

33.1.8 mapKey 1424

33.1.9 provider 1425


33.1.11 widgetDataMapForCallout 1427

33.2 Map - Layout Properties 1428




33.2.4 margin 1431


33.3 Map - Platform Specific Properties 1435

33.3.1 address 1435

33.3.2 mapHeight 1436

33.3.3 mapSource 1437

33.3.4 mapWidth 1438

33.3.5 mode 1439

33.3.6 navControlsImageConfig 1442

33.3.7 showCurrentLocation 1443

33.3.8 showZoomControl 1444

33.3.9 zoomLevel 1445

33.4 Map - Events 1447

33.4.1 onClick 1447



33.4.2 onPinClick 1448


33.5 Map -Methods 1450

33.5.1 addPolyline 1450

33.5.2 clear 1452

33.5.3 dismissCallout 1453

33.5.4 getBounds 1453

33.5.5 navigateTo 1454

33.5.6 navigateToLocation 1455

33.5.7 removePolyline 1457

33.6 Map - Templates 1458

33.6.1 What is a Template for Map callout 1458

33.6.2 Where to use aMap callout Template 1458

33.6.3 Creating a Template for Map callout 1458

33.6.4 UsingMap callout Template 1458

33.7 Appendix: Generating and ConfiguringMap API Keys 1459

33.7.1 Application Level MapWidget Key 1459

33.7.2 GoogleMap Key for Android 1461

33.7.3 BingMap Key forWindows 1463

33.7.4 Appendix: Generating and ConfiguringMap API Keys 1463



34. ObjectSelector3D 1476

34.1 ObjectSelector3D - Basic Properties 1479


34.1.2 id 1480

34.1.3 info 1481




34.1.5 skin 1483

34.1.6 text 1484

34.2 ObjectSelector3D - Layout Properties 1485



34.2.3 hExpand 1487

34.2.4 margin 1489


34.2.6 padding 1492


34.2.8 vExpand 1495


34.3 ObjectSelector3D - Event 1498

34.3.1 onSelectionDone 1498

34.4 ObjectSelector3D -Methods 1499

34.4.1 addModel 1499

34.4.2 clearAllData 1500

34.4.3 defineSpecialModels 1501

34.4.4 getSelectedCells 1502

34.4.5 setCameraProperties 1503

34.4.6 setMapData 1504

34.4.7 setRequiredSelectionsCount 1505

34.4.8 setSelectedCells 1506

35. Phone 1508

35.1 Phone - Basic Properties 1510


35.1.2 id 1511




35.1.4 skin 1512

35.1.5 text 1512

35.2 Phone - Layout Properties 1513



35.2.3 hExpand 1515

35.2.4 margin 1516


35.2.6 padding 1519


35.2.8 vExpand 1521


36. PickerView 1524

36.1 PickerView - Basic Properties 1527


36.1.2 id 1529

36.1.3 info 1530






36.1.9 skin 1538

36.2 PickerView - Layout Properties 1539


36.2.2 hExpand 1540

36.2.3 margin 1542





36.3 PickerView - Event 1546


36.4 PickerView -Methods 1547

36.4.1 setComponentData 1548

36.4.2 setSelectedKeyInComponent 1549

37. SegmentedUI 1551

37.1 SegmentedUI - Basic Properties 1558

37.1.1 alternateRowSkin 1559

37.1.2 data 1560


37.1.4 id 1565

37.1.5 info 1566


37.1.7 needPageIndicator 1568


37.1.9 pageOnDotImage 1571

37.1.10 pageOffDotImage 1572

37.1.11 pullToRefreshI18NKey 1573

37.1.12 pullToRefreshSkin 1573

37.1.13 pushToRefreshI18NKey 1574

37.1.14 pushToRefreshSkin 1575

37.1.15 releaseToPullRefreshI18NKey 1576

37.1.16 releaseToPushRefreshI18NKey 1576

37.1.17 retainSelection 1577

37.1.18 rowSkin 1578

37.1.19 rowFocusSkin 1579

37.1.20 rowTemplate 1580




37.1.22 sectionHeaderSkin 1583

37.1.23 sectionHeaderTemplate 1584

37.1.24 selectedRowIndex 1586

37.1.25 selectedRowIndices 1587

37.1.26 selectedRowItems 1589

37.1.27 selectionBehavior 1589

37.1.28 selectionBehaviorConfig 1591

37.1.29 separatorColor 1592

37.1.30 separatorRequired 1593

37.1.31 separatorThickness 1594


37.1.33 viewType 1596


37.1.35 widgetDataMap 1604

37.1.36 widgetSkin 1606

37.2 SegmentedUI - Layout Properties 1607




37.2.4 gridCell 1610




37.2.8 margin 1615


37.2.10 padding 1618




37.3 SegmentedUI - Platform Specific Properties 1622


37.3.2 border 1623

37.3.3 bounces 1625


37.3.5 defaultSelection 1629

37.3.6 dockSectionHeaders 1630

37.3.7 editStyle 1631

37.3.8 enableDictionary 1633

37.3.9 indicator 1635

37.3.10 pressedSkin 1636

37.3.11 progressIndicatorColor 1637

37.3.12 searchBy 1639

37.3.13 searchCriteria 1640



37.4 SegmentedUI - Events 1645

37.4.1 onDidFinishDataLoading 1645

37.4.2 onEditing 1646

37.4.3 onRowClick 1647

37.4.4 onSwipe 1648




37.5 SegmentedUI - Methods 1655

37.5.1 addAll 1655


37.5.3 addSectionAt 1658





37.5.6 removeSectionAt 1662

37.5.7 setData 1663


37.5.9 setSectionAt 1665

37.6 Segment - Deprecated Properties 1667

37.6.1 addAt 1667

37.6.2 editable 1668

37.6.3 focusedIndex 1669

37.6.4 focusedItem 1669

37.6.5 navigationSkin 1669

37.6.6 needSectionHeader 1670


37.6.8 selectedIndices 1672

37.6.9 ondeleteclick 1673

37.6.10 oninsertclick 1673

37.6.11 onselect 1674

37.6.12 retainHeaderFooter 1674

37.6.13 showItemCount 1675

37.6.14 spaceBetweenSections 1676


37.7 SegmentedUI - Templates 1678

37.7.1 What is a Template for SegmentedUI 1678

37.7.2 Where to use a SegmentedUI (section) Template 1678

37.7.3 Creating a Template for SegmentedUI 1678

37.7.4 Using SegmentedUI Section Template 1679

38. Switch 1680



38.1 Switch - Basic Properties 1682

38.1.1 id 1682

38.1.2 info 1683


38.1.4 leftSideText 1685

38.1.5 Left Text i18n Key 1686

38.1.6 rightSideText 1687

38.1.7 Right Text i18n Key 1688


38.1.9 skin 1690

38.2 Switch - Layout Properties 1691


38.2.2 margin 1692



38.3 Switch - Events 1698

38.3.1 onSlide 1698

39. SignatureCapture 1700

39.1 SignatureCapture - Basic Properties 1701

39.1.1 base64 1701

39.1.2 id 1702

39.1.3 info 1703


39.1.5 penWidth 1705

39.1.6 rawBytes 1706

39.1.7 skin 1707

39.2 SignatureCapture - Layout Properties 1707




39.2.2 hExpand 1709

39.2.3 margin 1710


39.2.5 padding 1713


39.2.7 vExpand 1716


39.3 SignatureCapture - Platform Specific Properties 1719

39.3.1 accessMode 1719

39.4 SignatureCapture - Event 1721

39.4.1 onCapture 1721

39.5 SignatureCapture - Methods 1722

39.5.1 clear 1722

39.5.2 getAsRawBytes 1723

39.5.3 save 1723

40. Video 1725

40.1 Video - Basic Properties 1728

40.1.1 id 1728


40.1.3 skin 1730

40.1.4 source 1731

40.1.5 text 1732

40.2 Video - Layout Properties 1733


40.2.2 margin 1734

40.2.3 padding 1736


40.3 Video - Platform Specific Properties 1740



40.3.1 controls 1740

40.3.2 poster 1741

41. App Menu 1742

41.1 Common Properties 1744

41.1.1 Skin 1744

41.1.2 Focus Skin 1745

41.1.3 ID 1745

41.1.4 Title 1745

41.1.5 Icon 1746

41.1.6 Render 1746

41.1.7 i18n Key 1747

41.1.8 Event 1747

41.2 AppMenu - Platform Specific Properties 1748

41.2.1 Needs Separator 1748

41.2.2 Appbar Button Style 1749

41.2.3 Position 1749

41.3 Methods 1750

41.3.1 createAppMenu 1750

41.3.2 setCurrentAppMenu 1752

41.3.3 getCurrentAppMenu 1753

41.3.4 setAppMenuFocusByID 1754

41.3.5 addAppMenuItemAt 1755

41.3.6 removeAppMenuItemAt 1756

41.3.7 setAppMenuBadgeValue 1757

41.3.8 getAppMenuBadgeValue 1758

41.4 Methods 1759

41.4.1 setAppMenu 1759

41.4.2 setAppMenuFocusIndex 1761



41.4.3 showAppMenuItems 1762

41.4.4 hideAppMenuItems 1762

42. Accessibility (508 Compliance) 1764

42.1 Defining accessibilityConfig for aWidget in Kony Studio 1766

42.2 Widget BehaviorWhen Accessibility is Enabled 1769

42.3 ContainerWidgets 1770

42.3.1 Form 1770

42.3.2 HBox 1771

42.3.3 VBox 1772

42.3.4 ScrollBox 1773

42.3.5 Popup 1774

42.4 Basic Widgets 1775

42.4.1 Button 1776

42.4.2 Calendar 1776

42.4.3 CheckBox 1777

42.4.4 ComboBox 1778

42.4.5 Image 1779

42.4.6 Label 1780

42.4.7 Line 1780

42.4.8 Link 1780

42.4.9 ListBox 1781

42.4.10 RadioButton 1782

42.4.11 RichText 1783

42.4.12 Slider 1784

42.4.13 TextArea 1784

42.4.14 TextBox 1785

42.5 AdvancedWidgets 1785

42.5.1 Alert 1785



42.5.2 Camera 1786

42.5.3 Hz Image Strip 1786

42.5.4 PickerView 1787

42.5.5 SegmentedUI - TABLEVIEW 1788

42.5.6 SegmentedUI - PAGEVIEW 1789

42.5.7 Switch 1790

42.6 Accessibility Best Practices 1790

42.7 Accessibility:Platform Specific Limitations 1790

42.7.1 SPA 1791

43. Widget Level Animation 1792

43.1 Layout Animation 1793

43.2 Animation Limitations 1795

44. Appendix A: Layout 1797

44.1 HBox Behavior 1798

44.1.1 Scenario 1 (General Layout) 1798

44.1.2 Scenario 2 (Alignment) 1801

44.2 VBox Behavior 1808

44.2.1 Scenario 1 1808

45. Appendix B: Platform Specific Limitations 1812

45.1 DesktopWeb Limitations 1812

45.2 SPA Limitations 1813

45.3 Windows 7/8/8.1 Kiosk 1814

45.4 BlackBerry 10 1814

46. Glossary 1817



1. OverviewWidgets are visual components that enhance development of mobile applications throughminimal codingeffort. When the widgets are combined with an application, the widgets hold all the applications data and theavailable interactions with this data.

Widgets often take the form of on-screen tools. The developers use different implementations of the widgetsavailable in the Integrated Development Environment (IDE) to buildGraphical User Interfaces (GUI). All thewidgets described in this document are drag-and-drop widgets

All the Kony supported devices, development languages, and browsers are listed at, Supported Devices andBrowsers.

1.1 ScopeThis document describes the usability of widgets, properties, and events within the IDE. This documentexplains the classification and structure of all the widgets within the IDE and also describes the Layout.

1.2 Intended AudienceThis document is targeted at the developers who want to have an understanding of the widget properties andare familiar with the Kony Studio.

1.3 Typographical ConventionsThe following are the typographical conventions used throughout the document:

Conventions Explanation

Monospace

n User input text, system prompts and responses

n File Path

n Commands

n Program Code

n File Names.

Italic

n Emphasis

n Names of Books and Documents

n New Terminology.

Bold

n Windows

n Menus

n Buttons

n Icons

n Fields

n Tabs

n Folders.URL Active link to a URL.Note: Provides helpful hints or additional information.



1.4 Reference Documents1. Kony Studio Installation Guide

2. Kony Server Installation Guides

3. Kony Studio User Guide

4. Kony API ReferenceGuide

1.5 Contact UsWewelcome your feedback on our documentation. Write to us at [email protected] technicalquestions, suggestions, comments, or to report problems on Kony's product line, [email protected].



2. Working with WidgetsKony Studio widgets exploit the full capabilities of high-endmobile devices while scaling down gracefully onsmaller and less powerful mobile handsets. A complex and visually rich interface widget is scalable forsimpler devices; but you cannot scale up an under-designed interface. Hence, it is always a best approach todesign for the high-end and test on the low-endmobile devices.

Kony Studio widgets are small chunks of code that are re-used without additional compilation. Somewidgetssupport interaction with the user (for example: Button, Label, Checkbox, and so on). Others act as containersthat 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 ofapplications is known as Palette.

The following is a snapshot of a Palette:

The widgets are based on a common behavior definition and aremade available across all supported nativeand browser platforms, enabling you to deliver a consistent user experience across all devices using thesereusable components.

Kony Client libraries also include support for platform specific properties. The platform specific propertiesallow 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 specificproperties that are available only on certain platforms. Using this capability, you canmaintain one code base,but still deliver an optimized application experience for a specific device by configuring additional device orplatform properties provided by the platform.

Windows Platform Classification:

Follow are the supported OS versions supported inWindows Channels

Windows Phone Windows Tablet Windows KioskWindows Phone 7.5 Windows 8.1 Windows 7 KioskWindows Phone 8 Windows 8 KioskWindows Phone 8.1 Windows 8.1 Kiosk

2.1 Widget ClassificationWidgets are categorized as Containers, Components, and Advanced Components based on the behavior andcharacteristics of the widgets.

The following is a structural classification of the widgets:

1. Composite Widgets: Form and Popup

2. Command Input Widgets: Button andMenuItem

3. Data Input and Output Widgets: CheckBox, ComboBox, Link, ListBox, RadioButtonGroup,RichText, TextArea, TextBox, and Switch.

4. Informational Widgets: Calendar, Hz Image Strip, Image, ImageGallery, Label, Line, and Slider.

5. Advanced Widgets: Browser, Camera, Hz Image Strip, ImageGallery, 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 eventsupon receiving user actions. The following is a list of ContainerWidgets:

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 ContainerWidgets. The following is a list ofBasic 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 MethodsThemethods 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 thefollowing 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 isplaced in a Segment.When the widget is placed in a Segment, the default Visibility is set to true. If you want to change the valueto 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 ignoredand will be treated as widget without any animation. Passing an emptydictionary will make the API assume the defaults for each of the supported keyin 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 thevisibility is turned on. Specifies the widget must expand gradually byincreasing the height of the widget.

l constants.ANIMATION_EFFECT_COLLAPSE: This is applicable whenthe visibility is turned off. Specifies the widget must collapse gradually bydecreasing the height of the widget.

l constants.ANIMATION_EFFECT_REVEAL:This is applicable when thevisibility is turned on. Specifies the widget must appear gradually bydecreasing the transparency of the widget.

l constants.ANIMATION_EFFECT_FADE:This is applicable when thevisibility is turned off. Specifies the widget must disappear gradually byincreasing 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 thelayout animations are applied on the Form.

animDuration - Optional

Specifies the duration of the animation effect in seconds. The default value is 1 second. Thenegative 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. Thenegative values are ignored and defaulted to 0 second.

animCurve - Optional

Specifies the animation curve to be applied while playing the animation. An animation curvedefines the speed of the animations at different intervals of the animation duration. Following arethe available options of animation curve:

l constants.ANIMATION_CURVE_EASEIN:Specifies the animationeffect to start slow in the beginning.



l constants.ANIMATION_CURVE_EASEOUT: Specifies the animationeffect to slowdown towards the end.

l constants.ANIMATION_CURVE_EASEINOUT:Specifies the animationeffect 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 startto end.

animCallBacks - Optional

It is a JS dictionary containing the events invoked by the platform during the animation lifecycle. Following are the available events:

l animStarted:Invoked at the beginning of the animation without anyparameters. 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 timeexceptions/ 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":startCallBackFunc,"animEnded":endCallBackFunc}});

Platform Availability

Available on all platforms except on Server sideMobileWeb platforms

2.2.2 setFocus

This method specifies the widget on which theremust be focus.

Note:We recommend you not to call this method in preShow of a form as it is not respected by allplatforms. In Android platform, this method is not respected in preShow of a form. You can give focus to aparticular 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 awidget 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};var form = new kony.ui.Form2(frmBasicConf,{},{});



//setFocus method call on the button.form.btn.setFocus(true);


Available on all platforms except on Server sideMobileWeb platforms

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 sideMobileWeb, SPA, and DesktopWebplatforms.

Note: This method is not applicable in Mapwidget.



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};var form = new kony.ui.Form2(frmBasicConf,{},{});



//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 seta 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 possiblevalues:

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 berespected for a gesture. Possible values are: 1. Default value is 1.

l taps [number] - specifies the maximum number of taps that must be respectedfor 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 berespected for a gesture. Possible values are: 1. Default value is 1.

l swipedistance [number] - specifies the distance between the pixel from wherethe swipe started to the pixel where the swipe stopped (finger is moved up orremoved). 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 pixelsper 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 isrecognized as LONGPRESS only if it lasts for at least 2 seconds. Defaultvalue is 1.

Note: This parameter is not customizable on Android platform. The defaultvalue on Android platform is 500 ms. Any value you pass to this parameter isignored 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 hasthe following signature:

onGesturefunction(widgetRef,gestureInfo)

l widgetRef - specifies the handle to the widget on which the gesture wasrecognized.

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 thefollowing key-value pairs:

l gestureType [number] - indicates the gesture type; 1 for TAP, 2 for SWIPE, and3 for LONGPRESS.

l gesturesetUpParams [object] - this array is the set up parameters passedwhile adding the gesture recognizer.

l gesturePosition [number] - indicates the position where the gesture wasrecognized. Possible values are: 1 for TOPLEFT, 2 for TOPCENTER, 3 forTOPRIGHT, 4 for MIDDLELEFT, 5 for MIDDLECENTER, 6 for MIDDLERIGHT,7 for BOTTOMLEFT, 8 for BOTTOMCENTER, 9 for BOTTOMRIGHT, 10 forCENTER.

Note: This parameter is applicable only on iPhone.

l swipeDirection [number] -indicates the direction of swipe. This parameter isapplicable only if the gesture type is SWIPE. Possible values are: 1 for LEFT, 2for RIGHT, 3 for TOP, 4 for BOTTOM.

l gestureX [number] - specifies the X coordinate of the point (in pixels) wherethe gesture has occurred. The coordinate is relative to the widget coordinatesystem.


l gestureY [number] - specifies the Y coordinate of the point (in pixels) wherethe gesture has occurred. The coordinate is relative to the widget coordinatesystem.




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 formfrm1var 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 thegesture 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 formfrm1var tapGesture=frm1.hbx1.setGestureRecognizer(1,setupTblTap,myTap)

//To remove the TAP gesture recognizer on a hbox with ID hbx1 placed on a



form frm1frm1.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 TextAreawidgets 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 greaterthan 1 the badge is a rounded rectangle. For example, if you specify the text of the badge as 88, thenumber appears in a rounded rectangular badge. If the length of the badge text is 1, the badge isalways a circle. The badge can occupy up to 70% of the width of the parent widget. For example, ona button with a width of 100 pixels, a badge with about 100 characters will occupy only 70 pixels ofthe button width. The badge text is truncated and shows about 30 characters followed by threedots.

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 placedon 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 theKony 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 TextAreawidgets 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 thefollowing code:var badgeVal =frm1.hbx1.getBadge();alert("badge value is::"+badgeVal);


l iPhone/iPad

l Android/Android Tablet

For more information about the badge APIs refer theKony API Reference Document.



2.3 Widget SkinsA widget skin defines the look and feel of the widget when it is rendered on the form in an application. You canspecify different skins for different widgets, or different skins for different platforms. The IDE allows you tocreate 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 inthe widget skin properties.

For more information about creating skins, see the sectionConfiguringWidget Skins in theKony Studio UserGuide.

The following sections describe the support for Dynamic Skinning and Platform Specific Skin Limitations.



2.3.1 Dynamic Skinning

A widget can havemore than one skin defined (for example, normal skin, focus skin, etc.) Dynamic Skinningallows 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 PhoneWidget, if you want to display different skins for successful andunsuccessful 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 dialattempt is a success, the successskin is applied.

Note: For Dynamic Skinning, youmust ensure that the skin exists for the widget in the IDE before the codeis executed. JavaScript is not supported onWindows 6.x platform.

The following table lists the widgets and platforms which support dynamic skinning:

WidgetAndroid/AndroidTablet

BlackBerry iPhone/iPad

WindowsMango/Windows

6.x

MobileWeb SPA/Playbook

Form Yes Yes Yes Yes Yes YesHBox Yes Yes Yes Yes Yes YesVBox Yes Yes Yes Yes Yes YesButton Yes Yes Yes Yes Yes YesCalendar Yes Yes Yes Yes YesCheckBoxGroup Yes Yes Yes Yes YesComboBox Yes Yes Yes YesImage Yes Yes Yes YesLabel Yes Yes Yes Yes Yes YesLine Yes YesLink Yes Yes Yes YesListBox Yes Yes Yes Yes YesRadioButtonGroup Yes Yes Yes Yes YesRich Text Yes Yes Yes



WidgetAndroid/AndroidTablet

BlackBerry iPhone/iPad

WindowsMango/Windows

6.x

MobileWeb SPA/Playbook

TextArea Yes Yes Yes YesTextBox Yes Yes Yes YesScrollBox Yes Yes Yes Yes Yes Yes

SignatureYes

(supportedon 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 AppMenu 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 datapoints are available, then segment may not apply style of the form or the CSS style depending on thetype of blackberry device.

Android

l Platforms do not support adding skins for the default AppMenu 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 isnot supported.Hence, for the widgets accessed fromMobileWeb onWindows Phone, transparency for widgets(background, font, and border) is not supported.

Windows Phone

l Do not support transparency for widgets (background, font, and border).

l Windows Phone browser (IE 7 browser) does not support transparency because the RGBA property isnot supp