nimble kit doc

NimbleKit SDKDocumentation

Version 1.9.7

Created on 25.03.09Last modified on 28.06.11

Authors:

Alexander Voloshyn! ! [email protected] Belyakov ! ! ! [email protected]

Editors:

Anna Novikova! ! ! [email protected]

NimbleKit SDK! v. 1.9.7

Copyright © VolnaTech 2009-2010! 1

mailto:[email protected]?subject=

mailto:[email protected]?subject=

mailto:[email protected]




Contents:NimbleKit SDK Documentation! 13

• Overview! 13

• Requirements! 13

• Compatibility and Dependencies! 13

• Documentation! 13

• Quick Start! 13

• Registering NimbleKit! 13

NKTabBarController class reference! 14

• Overview! 14

• NKTabBarController()! 14

• destroy()! 14

• setTabBarForPage(page, title, image)! 14

• setBadgeCountAtIndex(badgeCount, index)! 14

• selectTabAtIndex(index)! 14

• getTabPotionsArray()! 14

• setMoreBarTintColor(red, green, blue)! 15

• setOnTapCallback(callback)! 15

• getSelectedTab()! 15

• setTabForPageDisabled(page, disabled)! 15

NKNavigationController class reference! 16

• Overview! 16

• setTitle(title)! 16

• setImage(imageName)! 16

• setTintColor(r, g, b)! 16

• hide()! 16

• show()! 16

• addNavigationItem(title, callback, image)! 16

• removeNavigationItem()! 16

• gotoPage(pageName)! 17

• setStyle(style)! 17

• goBack()! 17

• setUsesPreloading(isUsePreloading)! 17



• destroy()! 17

• setTitleForPage(title, page)! 17

• popToRootView(isAnimated)! 17

Examples:! 17

NKInternetPlayer class reference ! 18

• Overview! 18

• NKInternetPlayer()! 18

• playFromURL(url)! 18

• stop()! 18

• mute()! 18

• notifyPlayingStarted(callback)! 18

• notifyPlayingStopped(callback)! 18

• seekToPosition(seconds)! 18

• getDurationInSeconds()! 18

• getCurrentPositionInSeconds()! 18

• setVolume(volume)! 18

• getCurrentMetaString()! 18

• forceDecoderFormat(format)! 19

• setMaximumBuffersCount(count)! 19

Examples:! 19

NKApplication class reference ! 20

• Overview! 20

• setStatusBarStyle(style)! 20

• setIdleTimerDisabled(isDisabled)! 20

• vibrate()! 20

• setBadgeCount(count)! 20

• iPhoneOSVersion()! 20

• getCurrentLocale()! 20

NKSlider! 21

• Overview! 21

• init(x, y, width, callback)! 21

• show()! 21

• hide()! 21

• setValue(value)! 21



NKBanner! 22

• Overview! 22

• init(x, y, isHorizontal)! 22

• show()! 22

• hide()! 22

Callbacks:! 22

bannerViewDidLoadAd()! 22

didFailToReceiveAdWithError(error)! 22

bannerActionShouldBeginWillLeaveApplication(isLeaving)! 22

bannerViewActionDidFinish()! 22

Please see callbacks usage in the sample code below! 22

NKButton! 24

• Overview! 24

• init(x, y, width, height, callback)! 24

• show()! 24

• hide()! 24


• setTitleColor(r, g, b)! 24


NKToolBar! 25

• Overview! 25

• init(y)! 25

• show()! 25

• hide()! 25

• addButton(title, imageName, callback)! 25

• insertButtonAtIndex(index, title, image, callback)! 25

• addDoneButton(title, callback)! 25

• addFlexibleSpace()! 25


• setTintColor(red, green, blue)! 25

• destroy()! 25

• removeButtonAtIndex(index)! 26

NKTextView! 27



• Overview! 27

• init(x, y, width, height)! 27

• show()! 27

• hide()! 27

• setString(value)! 27

• getString()! 27

• setFontSize(size)! 27

• setEditable(value)! 27

NKTextField! 28

• Overview! 28


• show()! 28

• hide()! 28


• getString()! 28

• setKeyboardType(keyboardType)! 28

• setTextChangeCallback(callback)! 28

• setBorderStyle(style)! 28

• setPlaceholder(placeHolder)! 28

• dismissKeyboard()! 28

• showKeyboard()! 29

• setSecure(isSecure)! 29

NKLabel! 30

• Overview! 30

• init(x, y, width, height, value)! 30

• show()! 30

• hide()! 30

• setString(newValue)! 30

• setTextFontSize(size)! 30

• setTextColor(r, g, b)! 30

NKTableView! 31

• Overview! 31

• init(x, y, width, heigh, style)! 31

• show()! 31



• hide()! 31

• setEditing(isEditing)! 31

• setUserCanEditRows(canEdit)! 31

• insertCategoryNamed(name)! 31

• insertRecord(title, subtitle, image, sectionNumber, rightImage, callback)! 31

• bindToDataBase(dbName, tableName, optionalQuery)! 31

• commitDatabaseChanges()! 32

• setShowsIndex(indexAllowed)! 32

• setRowHeight(height)! 32

• insertRecords(records)! 32

• setOnRowRemovedCallback(callback)! 32

NKModalWindow! 34

• Overview! 34

• show()! 34

• dismiss()! 34

• addControl(control)! 34

NKImageView! 35

• Overview! 35

• init(x, y, width, height, imageName)! 35

• show()! 35

• hide()! 35


• setOnClickCallback(callback)! 35

NKSwitch! 36

• Overview! 36

• init(x, y,callback)! 36

• show()! 36

• hide()! 36

• getState()! 36

• setState(value)! 36

NKProgressBar! 37

• Overview! 37

• init(x, y, width)! 37

• show()! 37



• hide()! 37

• setPosition(value)! 37

NKActivityIndicator! 38

• Overview! 38

• init(x, y, size, style)! 38

• show()! 38

• hide()! 38

• stop()! 38

• spin()! 38

NKContact! 39

• Overview! 39

• contacts()! 39

• searchContact(argument)! 39

• showPeoplePicker(callback)! 39

NKAudioPlayer! 40

• Overview! 40

• loadFile(fileName)! 40

• loadFileFromDocuments(fileName)! 40

• play()! 40

• stop()! 40

• pause()! 40

• resume()! 40

• getDurationInSeconds()! 40

• setPositionInSeconds(seconds)! 40

• getCurrentPositionInSeconds()! 40

• setPlayingFinishedCallback(callback)! 40

• setLoopMode(isInLoop)! 40

• setVolume(volume)! 40

• dispose()! 40

• setIgnoreLock(isIgnored)! 41

NKVideoPlayer! 42

• Overview! 42

• openURL(url)! 42

• openFileName(fileName)! 42



• play()! 42

• stop()! 42

NKSystemVolumeControl! 43

• Overview! 43

• init(x, y, width)! 43

NKAlertSheet! 44

• Overview! 44

• init(callback)! 44

• addButtonWithTitle(title)! 44



• setRedButtonIndex(index)! 44

• setBlackButtonIndex(index)! 44

NKFile! 46

• Overview! 46

• open(fileName)! 46

• openFromDocuments(filename)! 46

• read(position, length)! 46

• position()! 46

• close()! 46

• size()! 46

• deleteFile()! 46

NKSettings! 47

• Overview! 47

• getValueForKey(key)! 47

• setValueForKey(value, key)! 47

NKFileDownloader! 48

• Overview! 48

• openURL(url)! 48

• start(fileName)! 48

• stop()! 48

• getProgress()! 48

NKSQLite! 49



• Overview! 49

• openDatabase(name, rewrite)! 49

• executeSQL(query)! 49

• getResults()! 49

• closeDatabase()! 49

NKMapView! 50

• Overview! 50

• init(x,y,width,height)! 50

• show()! 50

• hide()! 50

• showUserlocation()! 50

• setMapType()! 50

• getUserLocation(callback)! 50

• isUserLocationUpdating()! 50

• setDisplayRegion(lat, longtitude, latDelta, longtitudeDelta)! 50

• addAnnotation(lat, longitude, title, subtitle, image, color, callback)! 50

• selectAnnotation(title)! 51

• setDelegateCallback(callback)! 51

• clearAnnotations()! 51

• getDisplayRegion()! 51

• setCenterCoordinate(latitude, longitude, isAnimated)! 51

Callbacks:! 51

mapTouchedAtCoordinates(latitude, longitude)! 51

NKAppStore! 53

• Overview! 53

• getAvailableProducts(callback, productIDs)! 53

• requestInfoForProductAtIndex(index, callback)! 53

• buyProductWithID(identificator, callback)! 53

NKPasteboard! 54

• Overview! 54

• getString()! 54


• getURL()! 54

• setURL(value)! 54



NKImage! 55

• Overview! 55

• loadURL(url)! 55

• loadFromDocuments(fileName)! 55

• loadFromBundle(fileName)! 55

• loadFromBase64(base64String)! 55

• getBase64(compression)! 55

• setSize(width, height)! 55

• saveToLibrary()! 55

• saveToDocuments(name)! 55

• getSize()! 55

• rotate(degrees)! 55

NKMailComposer! 56

• Overview! 56

• show()! 56

• setSubject(subject)! 56

• setRecipient(recipients)! 56

• setCC(value)! 56

• setBCC(value)! 56

• setBody(body)! 56

• addImage(image)! 56

NKSMSComposer! 57

• Overview! 57

• setRecipient(value)! 57

• setBody(text)! 57

• show()! 57

NKPopoverController! 58

• Overview! 58

• init(contentPage)! 58

• show(x, y, width, height)! 58

• hide()! 58

• setContentSize(width, height)! 58

NKWebView! 59

• Overview! 59




• show()! 59

• hide()! 59

• loadURL(url)! 59

• setScalesToFit(isScaled)! 59

• loadHTML(html, baseURL)! 59

• loadFromBundle(name)! 59

• goBack()! 59

• goForward()! 59

• reload()! 59

• setOnFinishCallback(callback)! 59

• setDetectsPhoneNumbers(detectionAllowed)! 59

NimbleKit functions! 61

• NKGetUniqueIdentifier()! 61

• NKGetDeviceType()! 61

• NKSetPageOpaque(page, isOpaque)! 61

• NKSetBackground(fileName)! 61

• NKIsInternetAvailableViaCellularNetwork! 61

• NKIsInternetAvailableViaWifi ! 61

• NKAlert(title, message)! 61

• NKMoveToPageAnimated(pageName, animation)! 61

• NKOpenURLInSafari(url)! 62

• NKOpenDocument(name, source)! 62

• NKStartPreloadingPage(pageName)! 62

• NKReloadPage(pageName)! 62

• NKGetLibraryVersion()! 62

• NKSetWebViewBackgroundColor(red, green, blue, alpha)! 62

• NKGetParameter(name)! 62

• NKLog(message)! 62

• NKConfirm(title, message, bTitle1, bTitle2, callback)! 62

• NKExecuteJavascriptOnPage(jscode, pagename)! 63

• NKGetAppVersion()! 63

• NKPreloadPage(pageName, callback)! 63

General Native Controls functions! 64

• Overview! 64



• NKNativeControlRotate(control, degrees)! 64

• NKSetControlAutoresizingMask(control, mask)! 64

• NKNativeControlSetAlpha(control, alpha)! 64

• NKNativeControlEnable(control, isEnabled)! 64

• NKControlSetBackgroundColor(control, r, g, b, a)! 65

Location services usage (GPS)! 66

• Overview! 66

• NKUpdateLocation(callback)! 66

Photo library/camera support! 67

• Overview! 67

• NKTakePicture(callback, source)! 67

• NKPickImageObject(callback, source, x, y, width, height)! 67

Orientation support! 68

• NKIsPageSupportsAutoOrientation()! 68

• pageWillRotate(degree)! 68

• pageDidRotate()! 68

Application Events! 69

• OnApplicationQuit()! 69

• OnApplicationPause()! 69

• OnApplicationResume()! 69

• onPageShown(caller)! 69

• onPageHidden()! 69

FAQ ! 70

1. How to add fullscreen company logo on application start?! 70

2. How to set image behind page so it is visible when user scrolls page?! 70

Troubleshooting! 71

• Overview! 71

• Threading! 71



NimbleKit SDK DocumentationOverview

NimbleKit SDK is a library which simplifies development for iOS platform allowing to create full featured applications using just html and JavaScript.

RequirementsMac OS X 10.6.2 or neweriPhone SDK 4.2 or newer

Compatibility and DependenciesProducts created with NimbleKit SDK will run on Apple devices with iOS 3.0 and newer.

DocumentationDocumentation updates with every release of NimbleKit, for an updated documentation please visit http://nimblekit.com and download latest version.

Quick StartAfter you installed Nimble SDK there will be added new Xcode template which has to be used to create Nimble Kit based applications.

Registering NimbleKitAfter NimbleKit SDK is purchased, projects can be activated to run on iOS devices. To do that open project and navigate to file named YOUR_APPLICATION_NAMEDelegate.m and enter serial in “serial” field for example:

Nimble *nimble = [[Nimble alloc] initWithRootPage:@"main.html" window:window serial:@"YOUR-SERIAL-HERE"];



http://nimblekit.com


NKTabBarController class referenceOverview

TabBarController class is used to manipulate pages giving user more freedom in navigation.

NKTabBarController()Creates and initializes NKTabBarController object also makes empty tab controller to appear on screen.

destroy()Completely removes controller from page

setTabBarForPage(page, title, image)Every tab should be created using this method, normally current page, for instance main.html, should be setup first.

Parameters:page - name of page to be displayed when tab selectedtitle - title to be displayed on tab iconimage - image to be displayed over tab title, if you want to use standard iPhone images, you can specify image number from the list instead of filename:

UITabBarSystemItemFavorites = 1UITabBarSystemItemFeatured = 2UITabBarSystemItemTopRated = 3UITabBarSystemItemRecents = 4UITabBarSystemItemContacts = 5UITabBarSystemItemHistory = 6UITabBarSystemItemBookmarks = 7UITabBarSystemItemSearch = 8UITabBarSystemItemDownloads = 9UITabBarSystemItemMostRecent = 10UITabBarSystemItemMostViewed = 11

Example: var tabController = new NKTabBarController(); tabController.setTabBarForPage("main.html", "Home", "home.png");

setBadgeCountAtIndex(badgeCount, index)sets badges count for tab at given index (small red circles shown on top of tabs)

selectTabAtIndex(index)selects tab at given index

getTabPotionsArray()returns javascript array of tab pageNames sorted in order as user reordered them having "more" tab, used to save the positions of rearranged tabs and be able to restore same order on next application launch.



setMoreBarTintColor(red, green, blue)sets color of the navigation controller which appears when “More” tab pressed (if you have more then 5 tabs “More” tab will appear automatically).

setOnTapCallback(callback)sets callback to be called when user taps on tab bar, callback format is following callback(pageName), where pageName is the name of the page been taped.

getSelectedTab()returns a file name of currently selected tab, for instance “main.html”

Example:var tabController = new NKTabBarController;var settings = new NKSettings;var array = settings.getValueForKey("tabOrder");if (array.length>0 && array!="(null)") {! for (i=0; i<array.length; i++)! ! tabController.setTabBarForPage(array[i], array[i], "");}else {! tabController.setTabBarForPage("main.html", "main.html", "");! tabController.setTabBarForPage("1.html", "1.html", "");! tabController.setTabBarForPage("2.html", "2.html", "");! tabController.setTabBarForPage("3.html", "3.html", "");! tabController.setTabBarForPage("4.html", "4.html", "");! tabController.setTabBarForPage("5.html", "5.html", "");! tabController.setTabBarForPage("6.html", "6.html", "");}

function OnApplicationQuit(){! array = tabController.getTabPositionsArray();! settings.setValueForKey(array, "tabOrder");}

setTabForPageDisabled(page, disabled)sets tab disabled or enabledpage - page name of tab you want to set state fordisabled - state you want to set. pass true or 1 to disable, false or 0 to enable

Example:var tabController = new NKTabBarController;tabController.setTabForPageDisabled(“main.html”, true);



NKNavigationController class referenceOverview

NKNavigationController class allows to make navigation in application.

setTitle(title)Set navigation controller title for current page.

setImage(imageName)Set navigation controller image for current page.

setTintColor(r, g, b)sets tint color for navigation bar.

Parameters: red, green and blue component of the color

hide()Hides navigation bar.

show()Shows navigation bar if it was hidden.

addNavigationItem(title, callback, image)adds a button to the right side of navigation controller.

Parameters:title - a string title to appear on buttoncallback - a string function name to be called when user pressed navigation itemimage - name of the image to use or index of the image from standard icon list starting from 1:

UIBarButtonSystemItemDone, = 1 UIBarButtonSystemItemCancel, UIBarButtonSystemItemEdit, UIBarButtonSystemItemSave, UIBarButtonSystemItemAdd, UIBarButtonSystemItemFlexibleSpace, - does nothing UIBarButtonSystemItemFixedSpace, - does nothing UIBarButtonSystemItemCompose, UIBarButtonSystemItemReply, UIBarButtonSystemItemAction, UIBarButtonSystemItemOrganize, UIBarButtonSystemItemBookmarks, UIBarButtonSystemItemSearch, UIBarButtonSystemItemRefresh, UIBarButtonSystemItemStop, UIBarButtonSystemItemCamera, UIBarButtonSystemItemTrash, UIBarButtonSystemItemPlay, UIBarButtonSystemItemPause, UIBarButtonSystemItemRewind, UIBarButtonSystemItemFastForward, UIBarButtonSystemItemUndo,! ! // available in iOS 3.0 UIBarButtonSystemItemRedo,! ! // available in iOS 3.0

removeNavigationItem()removes navigation item added by addNavigationItem() method



gotoPage(pageName)navigates to given page creating “back” navigation button to allow to go to the previous pageyou also allowed to pass GET parameters to ʻpageNameʼ, for example “page.html?id=35&name=me”, see NKGetParameter function for retrieving parameters.

Parameters:pageName - name of the page to navigate to

setStyle(style)sets the style of navigation controller

Parameters:style is one of two values available: “Default” and “Black” (not case sensitive).

goBack()returns to previous page

setUsesPreloading(isUsePreloading)manages state of automatic page preloading isUsePreloading can take state “yes”, “no”, “1” and “0”.

destroy()completely removes controller from page

setTitleForPage(title, page)sets navigation controllerʼs title for specified page

popToRootView(isAnimated)returns to the first page in pages stack either animated or instantly, can take parameters “yes”/”no” or “1”/”0”

Examples:

<html><head><meta name = "viewport" content = "width = 320, initial-scale = 1.0, user-scalable = no" /></head><body><script type="text/javascript" src="NKit.js"></script><script type="text/javascript">

var navController = new NKNavigationController();navController.setTitle("Colored");navController.setTintColor(0xFF, 0, 100);</script><a href="#" onClick="navController.gotoPage('nextPage.html')">Go forward</a></body></html>



NKInternetPlayer class referenceOverview

Internet player allows you to played streamed media. MP3 and AAC streams supported.

NKInternetPlayer()creates and initializes InternetPlayer instance, which acts as singleton, so if you created InternetPlayer before current instance will just reuse resources.

playFromURL(url)tries to play streamed media from given URL

stop()stops current InternetPlayer, does nothing if no media

mute()mutes current InternetPlayer, does nothing if no media

notifyPlayingStarted(callback)notifies when caching is finished and actual playback started, callback is a string name of the function to be called

notifyPlayingStopped(callback)notifies when playback stopped, callback is a string name of the function to be called

seekToPosition(seconds)seeks to specified position in seconds, works when playing file from internet, does not work on ʻrealʼ streams.

getDurationInSeconds()returns duration of the streamed file in seconds (duration may change during playback and is approximated)

getCurrentPositionInSeconds()returns current position in streamed file, this value is approximated

Parameters:callback - javascript function to be called when playback started, should not contain any parameters.

setVolume(volume)sets volume for current audio stream

Parameters:volume - volume value [0..100]

getCurrentMetaString()returns current streamʼs metadata (StreamTitle and optionally StreamUrl). Works with Shoutcast and Icecast stream services



forceDecoderFormat(format)specifies decoder format to use, this is often an issue for AAC or AAC+ streams when server does not provide information about decoder to be used, can take values “aac” and “mp3”.

setMaximumBuffersCount(count)sets maximum buffers to use, consider using smaller amount for real streamed audio (2-16) and bigger amount for static files hosted in the web (16-128). Each buffer has size of 32 Kilobytes. Default value is 64 buffers, which is 2Mb cache and most suitable for most cases.

Examples: function playRadio() { var radio = new NKInternetPlayer(); radio.notifyPlayingStarted("stopLoadingIndicator"); radio.forceDecoderFormat("aac"); radio.playFromURL("http://radio.myserver.com:8080"); } function stopRadio() { var radio = new NKInternetPlayer(); radio.stop(); }



http://radio.myserver.com:8080

http://radio.myserver.com:8080

NKApplication class referenceOverview

Used to modify application global behavior and appearance. Works as singleton, you can create instance of this class in any page.

setStatusBarStyle(style)sets the color and style of topmost status bar

Parameters:style - can be one of three available values: “Default”, “Black”, “BlackTranslucent” (not case sensitive).

Example: var application = new NKApplication(); application.setStatusBarStyle("black");

setIdleTimerDisabled(isDisabled)Controls applicationʼs idle timer. You should set idle timer disabled only if itʼs really necessary and be sure to enable idle timer when the need no longer exists. By default idle timer enabled.

Parameters:isDisabled - boolean value to specify idle timer state

vibrate()Makes iPhone device to vibrate

setBadgeCount(count)sets number of application badges (shown on application icon in red circle)

iPhoneOSVersion()retrieves string which represents iOS version (i.e. “3.0”)

getCurrentLocale()returns current locale (i.e. en_US, etc)



NKSliderOverview

Creates native Cocoa Touch slider. Control is created on the top layer of page, so if there are html elements on given coordinates control will overlap them.

init(x, y, width, callback) Initializes slider

Parameters:x - left coordinate of the controly - bottom coordinate of the controlwidth - horizontal size of the control callback - javascript function to be called when slider changes value. This callback uses 2 parameters - absolute value of slider value and controlID which is an ID of the control, in case you have one callback for many controls.

show()shows initialized slider, does nothing if itʼs shown already

hide()hides initialized slider, does nothing if itʼs hidden already

setValue(value)setʼs current value [0..100]

Example:

function VolumeChanged(volume) { radio.setVolume(volume); }

var slider = new NKSlider(); slider.init(20, 325, 280, "VolumeChanged"); slider.setValue(20); slider.show();



NKBannerOverview

NKBanner class is used to add advertisement to iPhone apps running iOS 4.0 and newer (iAd).

init(x, y, isHorizontal)initializes advertisement view with given coordinates, multiple calls to this method change only position without reinitializing the control (hidden by default). isHorizontal parameter can take values "yes"/"no" or 1/0 which is used to specify orientation for the banner requested.

show()shows initialized banner view (banners are initially hidden)

hide()hides advertisement view

Callbacks:

All callbacks have to be implemented on the page where specific NKBanner was created, they will be called automatically.

bannerViewDidLoadAd()called when iAd banner is loaded and ready to be shown. Usually only in this method you need to show the ad. If you show the banner before then application can be rejected in the App Store.

didFailToReceiveAdWithError(error)called when error happened during iAd retrieving. This method must be implemented and if case error happened and invoked error must be processed and appropriate actions taken otherwise the application may be rejected in the App Store.

bannerActionShouldBeginWillLeaveApplication(isLeaving)this callback is called when iAd banner was clicked. isLeaving parameter can be either “YES” or “NO” means either ad needs to quit the application to proceed or ad can show the information without closing the application.

bannerViewActionDidFinish()called when banner action view has been dismissed and the application is active again.

Please see callbacks usage in the sample code below

Sample usage:

var banner = new NKBanner;banner.init(0, 0);

function bannerViewDidLoadAd(){! NKLog("We have the banner loaded, now we can show it");! NKLog("Btw, after creating we still can reposition it by calling init function");! banner.init(0, 410); // show the banner at the bottom! banner.show();



}

function didFailToReceiveAdWithError(error){! NKLog(error);}

function bannerActionShouldBeginWillLeaveApplication(isLeaving){! if (isLeaving == "YES")! {! ! NKLog("iad quits this app to proceed");! }! else! {! ! NKLog("iad clicked, but the app is still remains launched");! }}

function bannerViewActionDidFinish(){! NKLog("Banner action is finished and now we returned back to the our application");}

Available only on devices running iOS 4.0 or newer, added in NimbleKit version 1.9.2iAd callbacks added in v 1.9.3



NKButtonOverview

Creates native Cocoa Touch button. Control is created on the top layer of page, so if there are html elements on given coordinates control will overlap them.

init(x, y, width, height, callback) Initializes button

Parameters:x - left coordinate of the controly - top coordinate of the controlwidth - horizontal size of the control height - vertical size of the controlcallback - javascript function to be called when slider changes value. This callback has one parameter - controlID, which is an ID of the control, in case you have one callback for many controls

show()shows initialized button, does nothing if itʼs shown already

hide()hides initialized slider, does nothing if itʼs hidden already

setImage(imageName)sets the image to be displayed over the button, images are not scaled and appear in real size.

setTitleColor(r, g, b)sets the color of the button title, specified in r, g, b, as color components of red, green and blue. Parameters can take values in range [0..255].

setTitle(title)sets the title to be displayed over the button

Example: function playRadio() { var radio = new NKInternetPlayer(); radio.playFromURL("http://myradio.com:8000"); }

var playButton = new NKButton(); playButton.init(15, 390, 60, 20, "playRadio"); playButton.setImage("play.png"); playButton.show();



http://myradio.com:8000


NKToolBarOverview

Class is used as an utility toolbar

init(y)Initializes toolbar with vertical position ʻyʼ

show()shows initialized toolbar

hide()hides initialized toolbar

addButton(title, imageName, callback)creates button on toolbar

Parameters:title - button title to be displayed (ignored if imageName specified)imageName - the filename of bundled image to be displayed on button (discards title)callback - javascript function name to be called when button pressed

insertButtonAtIndex(index, title, image, callback)creates button on toolbar

Parameters:index - index, used to specify button position, count starts from 1title - button title to be displayed (ignored if imageName specified)imageName - the filename of bundled image to be displayed on button (discards title)callback - javascript function name to be called when button pressed

addDoneButton(title, callback)creates blue button on toolbar, which has same style is used for “Done” buttons

addFlexibleSpace()adds flexible space into toolbar, used to align buttons

setStyle(style)sets the style of toolbar, possible values are: “black”, “blacktranslucent”, “default”

setTintColor(red, green, blue)sets color for the toolbar, color components are values in range [0..255]

destroy()removes and destroys toolbar and resources allocated for it.



removeButtonAtIndex(index)removed button at specified index (starts at 0)



NKTextViewOverview

This control is used to display large amount of text.

init(x, y, width, height)initializes text view with given coordinates and size

show()shows control (not creating)

hide()hides control (not destroying)

setString(value)sets string value in control

getString()synchronous method returning contents of the control in string form (if you need other type please use parseInt, parseFloat, etc)

setFontSize(size)sets the font size for initialized view

setEditable(value)enables/disables ability to edit for user. Variable value can take following values: «yes», «no», 1, 0.

Example:

var textView = new NKTextView;textView.init(0, 0, 320, 100);textView.setEditable("no");textView.setString("HELLO WORLD HELLO WORLD HELLO WORLD HELLO WORLD HELLO WORLD HELLO WORLD");textView.setFontSize(20);textView.show();



NKTextFieldOverview

This control is used for user text input

init(x, y, width, height)initializes text field with given coordinates and size

show()shows control (not creating)

hide()hides control (not destroying)

setString(value)sets string value in control

getString()synchronous method returning contents of the control in string form (if need you other type please use parseInt, parseFloat, etc)

setKeyboardType(keyboardType)sets the type of keyboard

Parameters:keyboardType: the type of keyboard to use, available values are: “ASCII”, “NumbersAndPunctuation”, “URL”, “NumberPad”, “PhonePad” and “EmailAddress”, from iOS 4.1 “DecimalPad” also available, if the device has older OS “NumberPad” will be used automatically instead.

setTextChangeCallback(callback)sets the callback which will be called every time text field is modified, format is following callback(newValue), where newValue is the new modified value of the text field

setBorderStyle(style)sets border style for the text view, possible values are: "none", "line", "bezel", "rounded", the default value is "rounded".

setPlaceholder(placeHolder)sets placeholder string which will be shown before user input starts

Available in NimbleKit 1.7 or newer

dismissKeyboard()dismisses text field keyboard



showKeyboard()makes text field first responder. Should be used ONLY after all controls are created, for example if you call show keyboard and then create new button then it wonʼt work.

Available in NimbleKit 1.7 or newersetSecure(isSecure)

sets the secure type of keyboard, all input will be replaced by bullets. Takes parameters “yes” or “no”.


Example:

var textFied = new NKTextField();textFied.init(20, 120, 200, 30);textFied.setKeyboardType("PhonePad");textFied.show();



NKLabelOverview

NKLabel class is used to display static text

init(x, y, width, height, value)initializes NKLabel with itʼs frame and initial value, this method is mandatory to call right after class creation.

show()shows initialized label on current view

hide()hides initialized label from current view

setString(newValue)sets new value to the labelʼs text

setTextFontSize(size)sets the font size for initialized label

setTextColor(r, g, b)sets the color of the text using red, green and blue components [0..255]



NKTableViewOverview

TableView objects are used to present hierarchical lists of information.

init(x, y, width, heigh, style)initializes table view object with initial frame, where it will be displayed.style - table style. Can be “grouped” or “plain”

show()shows initialized table view on the screen

hide()hides initialized table view (allowing click-though)

setEditing(isEditing)switches tableview to editing mode, where user can manipulate table rows, reorder and remove any rows. Parameter isEditing can be either “yes” or “no”.

setUserCanEditRows(canEdit)enables/disables ability to delete rows using swipe gestures, be default this is disabled.

insertCategoryNamed(name)inserts new category/section in table view with specified name.

insertRecord(title, subtitle, image, sectionNumber, rightImage, callback)

inserts new row to the table.Parameters:

title - rowʼs main titlesubtitle - rowʼs subtitle, usually it is a description for the titleimage - NKImage instance, which represents the image to be displayed in the left part of the row. Images larger then row height will be down scaled to row height. Images smaller then row height will appear at their original size.sectionNumber - number of the section where the row must be inserted (starting from 0).rightImage - small image to be displayed in the right part of the row, usually showing that the item is clickable, if empty then default OSʼs action image will be used.callback - is a real javascript code to be executed when the item is clicked.

bindToDataBase(dbName, tableName, optionalQuery)binds tableview to the given database using it’s table as datasource, binding the database will destroy all the content in table view which was added earlier. optionalQuery is an optional parameter used to specify raw sql query to select table's content from database, for example: "SELECT * FROM products WHERE category='Fruits'". Of course you can use the query to load data sorted and to do other things which are allowed by SQL SELECT queries. To let NimbleKit know how data in a table view must be presented you need to have 6 columns in the database table, which



are named exactly like following:category - name of the category to which the row is related (for example “Fruits”)title - Rowʼs main title (for example “Apple”)subtitle - Rowʼs subtitle/description (for example “Nice green fruit”)image - the name of the image file which will be used in the left part of the row, can be the name from application bundle, documents folder or even an url to the image in the internet.right_image - the image name if the small image to be displayed in the right part of the row, usually showing that the item is clickable, if empty then default OSʼs action image will be used. Can be the name from application bundle, documents folder or even an url to the image in the internet.js - javascript code to be executed when the row is clicked. This is very useful as it will be loaded much faster then the code on the page, making application more responsive and page to load faster improving user experience.If you want to apply filter or resort data in table view you can call bindToDatabase multiple times with different "optionalQuery"s.

commitDatabaseChanges()flushes changes made to the table view (using setEditing) into the database.This method isnʼt must have, on application quit changes will be flushed anyway, however different situations may occur. This function works only if database has been bound to the table view.Warning: if you quit iPhone simulator using CMD+Q then changes arenʼt written into the database, make sure youʼr either using commitDtaabaseChanges or quit simulator app using home button, this warning is only applies for iPhone/iPad simulator.

setShowsIndex(indexAllowed)allows showing/hiding index in table view. indexAllowed can take values “yes” and “no”

setRowHeight(height)sets the row height for all rows in table.height - rowʼs height in pixels

insertRecords(records)inserts array of records to the tablerecords - array of records

setOnRowRemovedCallback(callback)adds callback to be called when user manually removed a row in the table view (setUserCanEditRows is enabled). The callback itself is a string name of the function which takes 2 parameters: section number and row number.

Example: var tableView = new NKTableView();! tableView.init(20, 20, 280, 300, 'plain'); !! tableView.show();! tableView.insertCategoryNamed('FirstGroup');! tableView.insertCategoryNamed('SecondGroup');! tableView.setOnRowRemovedCallback(“itemRemoved”);! var image = new NKImage();



! image.loadFromBundle('arrow.png');

! var firstRecord = new Object;! firstRecord.title = "Record1";! firstRecord.subTitle = "subtitle"! firstRecord.imageID = image.id;//note image ID is used! firstRecord.rightImageID = image.id;//note image ID is used! firstRecord.section = 0;! firstRecord.callback = "onRowClick()";!! var secondRecord = new Object;! secondRecord.title = "Record2";! secondRecord.section = 1;

! var records = new Array();!! records[0] = firstRecord;! records[1] = secondRecord;! tableView.insertRecords(records);

function itemRemoved(section, rowInSection) { NKAlert("Row removed", "at section:"+section+" row:"+rowInSection); }



NKModalWindowOverview

This class is used to present modal dialogs and “wait screens” when user should not access any other controls except those placed on modal window

show()shows modal window on top of all controls

dismiss()removes modal window from the screen

addControl(control)adds control to the modal window, can take value of standard NimbleKit controls, like NKActivityIndicator, NKButton, NKLabel, etc

Example:! modal = new NKModalWindow();! modal.show();! var indicator = new NKActivityIndicator();! indicator.init(90, 165, 30, "white");! indicator.show();! indicator.spin();! modal.addControl(indicator);!! var label = new NKLabel();! label.init(140, 158, 140, 40, "Please wait...");! modal.addControl(label);! label.show();

! var button = new NKButton();! button.init(120, 210, 100, 40, "buttonClick");! button.setTitle("Dismiss");! modal.addControl(button);! button.show();

// This example shows modal window with 3 controls on it



NKImageViewOverview

Image view class is used to display images on top of a web view.

init(x, y, width, height, imageName)Initializes new NKImageView control with given size, position and image (can be URL to image in the internet)

show()shows on screen initialized NKImageView class instance

hide()hides on screen initialized NKImageView class instance

setImage(imageName)sets new image to be displayed, can be either name of the bundled image or URL to the image in the internet. From v 1.7 this API is deprecated, use setImageObject instead

setOnClickCallback(callback)Sets the callback to be called when user taps on image view.Callback is a string name of javascript function to be called (i.e. “myOnclickHandler()”)



NKSwitchOverview

This control is used as switch which has boolean value

init(x, y,callback)initializes switch control with given coordinates and callback (name of the function as string) to be called when switch value has been changed, callback format should be functionName(newValue, controlID), "newValue" can be either 1 or 0 and controlID is an ID of the control, in case you have one callback for many controls.

show()shows switch

hide()hides switch control

getState()asynchronous method which returns state of the switch (0 or 1)

setState(value)sets the state of the switch with animation

Example:

<script type="text/javascript">var uiswitch = new NKSwitch();uiswitch.init(20, 70);uiswitch.show();</script><a href="#" onClick="uiswitch.setState(!uiswitch.getState());">Switch State</a>



NKProgressBarOverview

Creates native Cocoa Touch progress view. Control is created on the top layer of page, so if there are html elements on given coordinates control will overlap them.

init(x, y, width) Initializes progress bar

Parameters:x - left coordinate of the controly - bottom coordinate of the controlwidth - horizontal size of the control

show()shows initialized progress bar, does nothing if itʼs shown already

hide()hides initialized progress bar, does nothing if itʼs hidden already

setPosition(value)sets position of the slider.

Example:

var progress = new NKProgressBar();progress.init(70,70,100);progress.setPosition(35);progress.show();



NKActivityIndicatorOverview

Creates native Cocoa Touch activity indicator. Control is created on the top layer of page, so if there are html elements on given coordinates control will overlap them.

init(x, y, size, style) Initializes activity indicator

Parameters:x - horizontal coordinate of the controly- vertical coordinate of the controlsize - vertical and horizontal size of the controlstyle - specifies the color of the control, can be one out of two values: “grey”, “white”.

show()shows initialized and stopped activity indicator

hide()hides initialized activity indicator, no matter which state it has

stop()stops controlʼs animation, does nothing if itʼs not animating

spin()starts controlʼs animation, does nothing if control already animating

Example:In this example activity indicator created and started when play button pressed and stopped when radio finished caching and started to play

var indicator = new NKActivityIndicator();indicator.init(10,10,20,"white");

function radioStartedToPlay(){ indicator.stop();}

function playRadio(){ var radio = new NKInternetPlayer(); radio.notifyPlayingStarted("radioStartedToPlay"); indicator.show(); indicator.spin(); radio.playFromURL("http://myradio.com:8000");}





NKContactOverview

Used to retrieve information from address book

contacts()retrieves all contacts from address book and returns them as a string in format “name, phone<br>”

searchContact(argument)searches for specific contact which has occurrence of “ argument” in name or phone number

showPeoplePicker(callback)shows modal dialog with contents of address book, when phone selected ʻcallbackʼ functions will be called with 3 parameters: name, phone number and e-mail.

Example:

var addressBook = new NKContact();

document.write("<a href=\"#\" onClick=\"addressBook.showPeoplePicker('personSelected()')\">Show People Picker</a>");

function personSelected(name, phone, email){ NKAlert("Person selected", "Name: "+name+" phone: "+phone+" email: "+email);}



NKAudioPlayerOverview

Used to play audio files bundled in the application

loadFile(fileName)Loads the content of file specified by fileName parameter and prepares it to play

loadFileFromDocuments(fileName)Loads the content of file and prepares it to play, looking for given file name in documents folder

play()starts to play loaded file

stop()stops currently playing audio

pause()pauses currently played audio

resume()resumes playback from paused state

getDurationInSeconds()returns integer value specifying duration in seconds of the loaded audio

setPositionInSeconds(seconds)sets playback position in seconds

getCurrentPositionInSeconds()returns current position measured in seconds

setPlayingFinishedCallback(callback)Used to get information about when playback finished

Parameters:callback - function name to be called when playback finished

setLoopMode(isInLoop)setʼs if player should repeat loaded file, can take argument “yes”, “no”, “1” and “0”

setVolume(volume)setʼs current volume for player, parameter has to be in range [0..100]

dispose()disposes resources allocated for player



setIgnoreLock(isIgnored)if this function is set to “yes” then application will still continue to play even if user locked the phone.


Example of controlling one player from different pages

page1.html:var player1 = new NKAudioPlayer();player1.loadFile("music.mp3");var settings = new NKSettings();settings.setValueForKey(player_id,”playerID”);//save player1.id in NKSettings

page2.html:var player2 = new NKAudioPlayer();player2.dispose(); // release second's player resources as we will use resources of the first playervar settings = new NKSettings();player2.id = settings.getValueForKey(“playerID”);player2.play(); // launch play of the first player



NKVideoPlayerOverview

Class is used to play video files in iPhone compatible format. Be advised that supported formats are:▪ H.264 Baseline Profile Level 3.0 video, up to 640 x 480 at 30 fps. Note that B ! frames are not supported in the Baseline profile.▪ MPEG-4 Part 2 video (Simple Profile)Also this class can open and play audio files including AAC-LC audio at up to 48 kHz.

openURL(url)opens video stream from URL

openFileName(fileName)opens video file stored in application bundle

play()starts video playback

stop()stops current video playback



NKSystemVolumeControlOverview

This class is used to control iOS sound volume

init(x, y, width)initializes and shows UI control to control system sound volume, looks similar to progress bar. Can be called multiple times to reposition control if needed.



NKAlertSheetOverview

This class is used to confirm user destructive actions or provide a choice between different actions.

init(callback)initializes alert sheet with callback, which to be called when any button clicked on alert sheet. The function “callback” has to take one parameter which is an index of clicked button.

addButtonWithTitle(title)adds button to alert sheet with specified title

setStyle(style)sets style of the alert sheet, by default style is automatic, possible values are: ”black”, “blacktranslucent” and “automatic”.

setTitle(title)sets the title of the alert sheet.

setRedButtonIndex(index)sets the index of button to be shown as «red button», this button has to have destructive sense and used only when user is going to loose data or application closed, etc.

setBlackButtonIndex(index)sets the index of button to be shown as «black button» which used as cancel button in most of the dialogs.

Example:function actionSheetButtonPressed(number){! NKAlert("Button pressed", number);}

function showActionSheet(){! var sheet = new NKAlertSheet();! sheet.init("actionSheetButtonPressed");! sheet.addButtonWithTitle("ok");! sheet.addButtonWithTitle("no way");! sheet.addButtonWithTitle("I don't know");! sheet.setStyle("black");! sheet.setTitle("Make your choice");! sheet.show();}



NKFileOverview

Used to read files bundled in the application

open(fileName)Opens file with given filename for reading, should be just name and file extension, returned value is either “1” or “0” identifying if file was opened.

openFromDocuments(filename)Opens file with given filename for reading which located in documents folder, should be just name and file extension, returned value is either “1” or “0” identifying if file was opened.

read(position, length)Returns buffer of bytes read from given position in the file and with given length

position()Returns the value identifying current offset in the file

close()Closes file and frees all resources allocated for it

size()Returns size of the opened file in bytes

deleteFile()deletes current file, can only be used on files opened from documents folder. Bundled files are read-only.

Discussion (possible crashes):NKFile should be used carefully, because all methods of this class are synchronous and may result main thread to freeze for more then 5 seconds, which is time maximum allowed for javascript function to run. In case if 5 seconds limit reached unpredictable situations can appear. Please refer to Troubleshooting section for solution.



NKSettingsOverview

Used to save application settings

getValueForKey(key)Retrieves saved value for specified key (can be javascript object from v1.6.2)

setValueForKey(value, key)Saves “value” in application settings for specified key (can take any object value staring from v1.6.2)

Example:In this example we use NKSettings class to save/retrieve username from application settings.

var settings = new NKSettings();settings.setValueForKey("UserName", "user");var username = settings.getValueForKey("user");

Discussion (possible crashes):To be safe it is better to call settings before creating interface, as NKSettings methods work synchronously and they would wait until all all interface elements loaded which can cause javascript function to be canceled as it takes too long.



NKFileDownloaderOverview

This class is used to download files from internet to documents folder (later those files can be opened with NKFile).

openURL(url)Initializes current downloader with url

start(fileName)Starts asynchronous download process.

filename - name of the output file to be created in documents folder

stop()Stops download

getProgress()Returns percentage of downloaded data or -1 if error occured

Example:var download = new NKFileDownloader();download.openURL("http://www.nimblekit.com/nimblekit.dmg");download.start("nimblekit.dmg");setTimeout(updateProgress, 1000);

function updateProgress(){ var progress = download.getProgress(); if (progress == -1) { NKLog("Could not download file"); } else { NKLog("downloaded: "+progress); if (download.getProgress()<100) setTimeout(updateProgress, 1000); }}

This example will download nimblekit.dmg file to iPhoneʼs Documents folder



http://www.nimblekit.com/nimblekit.dmg

http://www.nimblekit.com/nimblekit.dmg

NKSQLiteOverview

This class is used to access database and use sqlite databases. NKSQLite is global singleton class so you can access opened database from any page, but if you open new one, previous will be closed automatically. So itʼs preferable to use 1 database with multiple tables to open/close database only once.

openDatabase(name, rewrite)opens database with given name and rewrites it if “rewrite” is set to “1” or “yes”.

Discussion:SQLite database file is stored in application bundle, but the location is not writable so when we call openDatabase NimbleKit tries to open database with this name from writable location in documents folder of iPhone, it there is no such file - NimbleKit copies it from bundle to writable location and opens again. So once you opened your database on current device, database file in bundle wonʼt be accessed, but of course if you changed tables or put new data in initial table you can put rewrite variable to “1” or “yes” to rewrite database at writable location.

executeSQL(query)executes standard SQL query, (i.e. “SELECT * FROM mytable”)

getResults()returns the result as javascript array of dictionaries (This API was redesigned in v1.7, please update old code)

closeDatabase()closes current database

Example:var database = new NKSQLite();database.openDatabase("nk.sqlite", "no");database.executeSQL("CREATE TABLE todo(pk INTEGER PRIMARY KEY, text VARCHAR(25), priority INTEGER, complete BOOLEAN)");database.executeSQL("INSERT INTO todo(text,priority,complete) VALUES('Take out the trash',3,0)");database.executeSQL("INSERT INTO todo(text,priority,complete) VALUES('Do Computer Science homework',1,0)");database.executeSQL("INSERT INTO todo(text,priority,complete) VALUES('Learn Objective C',1,0)");database.executeSQL("INSERT INTO todo(text,priority,complete) VALUES('DIGG this tutorial',2,0)");database.executeSQL("SELECT * FROM todo");results = database.getResults();for (i=0; i<results.length; i++){! document.body.innerHTML+="<p>"+results[i].priority+" | "+results[i].complete+" | "+results[i].text+"</p>";}database.closeDatabase();



NKMapViewOverview

init(x,y,width,height)initializes map view with given width, height and coordinates on webview

show()shows initialized map view

hide()hides initialized map view

showUserlocation()triggers core location services to track user location and show it on the map, can take parameters "yes" or "no"

setMapType()sets the map type, can take parameters "standard", "satellite", "hybrid"

getUserLocation(callback)retrieves current user location, takes callback parameter of format “callback(newLocation)”, new location returned as callback argument

isUserLocationUpdating()indicates if CoreLocation is turned on to update user location, returns "1" or "0"

setDisplayRegion(lat, longtitude, latDelta, longtitudeDelta)scrolls the map so specified location could be visible in span

latitudeDeltaThe amount of north-to-south distance (measured in degrees) to use for the span. Unlike longitudinal distances, which vary based on the latitude, one degree of latitude is approximately 111 kilometers (69 miles) at all times.

longitudeDeltaThe amount of east-to-west distance (measured in degrees) to use for the span. The number of kilometers spanned by a longitude range varies based on the current latitude. For example, one degree of longitude spans a distance of approximately 111 kilometers (69 milies) at the equator but shrinks to 0 kilometers at the poles.

addAnnotation(lat, longitude, title, subtitle, image, color, callback)

adds marker on the map on given coordinates with specified title and subtitlecolor is an index of standard colors for annotation pin, can take 3 values [0..2], callback is a javascript function name to be called when user taps on annotation pin. Image can be either bundled image name or NKImage object instance.



selectAnnotation(title) selects annotation with the title specified when annotation was added, do not use this method directly after annotation was added as it has no time to initialize, use setTimeout function to select annotation after a small delay like half a second.

setDelegateCallback(callback)sets delegate callback to be called when map is loading, loaded or failed to load. The callback format is following "callback(state)", where state can take following values: 0 for loading, 1 for loaded and -1 if loading failed

clearAnnotations()removes all annotations added to the map previously

getDisplayRegion()returns display region which is visible to the user at the moment, the region returned as a string with 4 components divided by comma: center longitude, center latitude, span longitude delta and span latitude delta, for example: “102.122,34.65,12.1,2.06”

setCenterCoordinate(latitude, longitude, isAnimated)Changing the center coordinate centers the map on the new coordinate without changing the current zoom level. It also updates the values in the region property to reflect the new center coordinate and the new span values needed to maintain the current zoom level.

Callbacks:mapTouchedAtCoordinates(latitude, longitude)

Implement this callback on the page where NKMapView was created and it will be called automatically every time user touches the map returning latitude and longitude as callback parameters. If you donʼt need user input just ignore this callback and donʼt implement it.

Example: var map = new NKMapView(); map.init(0, 100, 320, 460); lat = 50; lon = 30; map.setDisplayRegion(lat, lon, 0.007435, 0.003130); map.showUserLocation("YES"); map.addAnnotation(lat, lon, "Here", "subtitle"); map.show(); setTimeout(selectAnnotation, 500); //wait for half second

function selectAnnotation() { ! map.selectAnnotation('Here'); }

Example 2:

Use NKMapView as gps without showing map on screen, we check here for new coordinates every second until they are obtained



NKAppStoreOverview

This class is used to make in-app purchasesgetAvailableProducts(callback, productIDs)

this function returns it's value via callback only when products are requested and updated via internet.

callback name of the function to be called when product list is updated, function prototype is following callback(productsCount)

productIDsthe list of product identifiers for the products you wish to retrieve descriptions of, it needs to be in format of a string where all identifiers separated by blank space, for example "my.company.prod1 my.company.prod2 my.company.prod3" will try to retrieve 3 products with given IDs.

requestInfoForProductAtIndex(index, callback)index

index of a product in returned via getAvailableProducts methoscallback

callback to be called with product information, format of callback is following: callback(title,description,productID,price)

buyProductWithID(identificator, callback)attempts to buy selected product

identificator unique product ID

callback a function name, which will notify if transaction was successful, will return either unique product ID or -1 if transaction failed, format is following “callback(result)”.



NKPasteboardOverview

this class is used to work with pasteboard

getString()returns a string which was previously copied to clipboard

setString(value)copies given string value to clipboard

getURL()returns url previously copied to clipboard

setURL(value)copies given string value of url to clipboard



NKImageOverview

NKImage is a class that used to represent, modify and save images. It is used by various classes as input or output, for example when you pick picture from camera it is an output object, which can be used as input object for NKImageView.

loadURL(url)load image from specified URL

loadFromDocuments(fileName)loads named image from documents folder

loadFromBundle(fileName)loads named image from application bundle

loadFromBase64(base64String)loads image data from base64 encoded string

getBase64(compression)returns base64 representation of jpeg image, compression is used to specify output quality (and size) can take values [0..1]

setSize(width, height)resizes image to gives rectangle

saveToLibrary()saves valid image object in iPhoneʼs photo library.

saveToDocuments(name)saves the image as a file in the documents folder with specified name

getSize()return current size of the image in format of the string where width and height are divided by comma, for example “800,600”

rotate(degrees)rotates the image with and angle specified in degrees parameter.

Available in NimbleKit 1.7 or newer.



NKMailComposerOverview

Composer is used to send e-mail messages without leaving the application and having content, subject and recipient pre-filled.

show()shows modal mail composer on top of application pages, call this after you already filled all fields you need (like subject, body or recipient).

setSubject(subject)sets mail composer subject

setRecipient(recipients)sets recipients as e-mail addresses, can take many addresses at once divided by comma.

setCC(value)sets carbon copy addresses divided by comma

setBCC(value)sets blind carbon copy addresses divided by comma

setBody(body)sets the body of the message.

addImage(image)adds image to composed e-mail, can be called multiple times to add many pictures. Image parameter is an instance of NKImage class.

Example:

function showComposer(){! var composer = new NKMailComposer();! composer.setRecipient("[email protected], [email protected]");! composer.setSubject("subject");!! composer.setBody("message body!");! composer.show();}

Class Available in NimbleKit 1.7 or newer







NKSMSComposerOverview

This class is used send SMS messages with the ability to compose or use pre-composed messages as message body.

setRecipient(value)sets recipients as phone numbers, can take many phone numbers at once divided by comma.

setBody(text)sets the text of SMS body

show()presents mail composer UI as modal view controller.

Class Available in NimbleKit 1.9.4 or newer



NKPopoverControllerOverview

You use popovers to present information temporarily but in a way that does not take over the entire screen like a modal view does

init(contentPage)initializes NKPopoverController with a page that represents popoverʼs content, can be called again in order to change the page in already initialized controller

show(x, y, width, height)shows initialized popover controller pointing with itʼs arrow to the rectangle specified in the parameters x, y, width, height. Note, this rectangle does not have any influence on the size of popover controller, use setContentSize method in order to change popoverʼs size.

hide()hides initialized and shown on the screen popover controller.

setContentSize(width, height)resizes content size of the popover controller. Can be called in any state when controller is hidden or shown (when shown it will resize animated).

Sample usage:! var popover = new NKPopoverController();! popover.init("popoverContent.html");! popover.setContentSize(100, 200);! popover.show(200,300,100,100);

Class Available in NimbleKit 1.9.4 or newer and requires iPad, any calls to this class are ignored on non-iPad device.



NKWebViewOverview

WebView native control which allows you to load external URLs and show itʼs content in your application.

init(x, y, width, height)Initializes newly created WebView with position and size.

show()shows initialized WebView (initially all native controls are hidden)

hide()hides initialized WebView

loadURL(url)loads given URL

setScalesToFit(isScaled)sets if WebView should scale page to fit or display the page in itʼs original size

loadHTML(html, baseURL)directly loads specified HTML code using baseURL as base URL for the content

loadFromBundle(name)loads html file from application bundle

goBack()loads previous page from history

goForward()loads next page from history

reload()reloads current page

setOnFinishCallback(callback)sets the callback which will be called when the page is loaded in the current web view. Callback is a string function name to be called.

setDetectsPhoneNumbers(detectionAllowed)enables/disables telephone numbers detection, can take values “yes” and “no”

Example:

var webView = new NKWebView;



webView.init(0,0,300,300);webView.loadURL("http://nimblekit.com/");webView.setScalesToFit("yes");webView.setOnFinishCallback("testcallback");webView.show();





NimbleKit functionsNKGetUniqueIdentifier()

Returns deviceʼs unique identifier based on hardware serial number.

NKGetDeviceType()returns device type, possible values:iPhone 1GiPhone 3GiPhone 3GSiPhone 4iPod Touch 1GiPod Touch 2GiPod Touch 3GiPod Touch 4GiPadiPhone Simulator

NKSetPageOpaque(page, isOpaque)Controls opaque state for specified page. isOpaque can be “yes”, “no”, 1 and 0. Set opaque to “no” when you want the page to be transparent.Available in NimbleKit 1.9.4 or newer

NKSetBackground(fileName)sets background behind the web page (visible if the page is transparent of user bounces the page)

NKIsInternetAvailableViaCellularNetworkReturned value can be either “1” or “0” which represents if internet access available using Cellular data network.

NKIsInternetAvailableViaWifiReturned value can be either “1” or “0” which represents if internet access available using Wi-Fi network.

NKAlert(title, message)Shows alert with provided title and message

NKMoveToPageAnimated(pageName, animation)Used to navigate between pages without navigation controller

Parameters:pageName - name of the html page to move, can accept parameters (i.e. ʻnext.html?id=25&name=userʼ), see NKGetParameter function for retrieving parameters.animation - name of the animation to use, currently supported animations: “Fade”, “PushLeft”, “PushRight”, “FastPushRight”, “FastPushLeft”, “FlipLeft”, “FlipRight”.In version 1.7 added “slidedown” and “slideup” animations.In version 1.9 added “curlup” and “curldown” animations.



NKOpenURLInSafari(url)opens given URL in mobile Safari browser

NKOpenDocument(name, source)Opens the document in the applications which registered to support that kind of document (i.e. pdf in iBooks or GoodReader, etc).

name - name of the file or documentʼs URLsource - specifies where to look for your document, can take 3 values: NKBundle, NKDocuments, NKURL

NKStartPreloadingPage(pageName)this function preloads the page with given name.Please be advised that loading many pages simultaneously can cause application to start very slow or greatly decrease performance. It is recommended to preload only pages critical to be preloaded.Example:

! NKStartPreloadingPage("page2.html");

NKReloadPage(pageName)Reload page specified (useful if you want tab content reloaded)

NKGetLibraryVersion()returns library version as string, for instance “1.6.3”

NKSetWebViewBackgroundColor(red, green, blue, alpha)sets background of the current webview, can be seen if scrolling used. All parameters are floating point variables and can take range [0..1].Example: NKSetWebViewBackgroundColor(1.0, 1.0, 0.0, 1.0);// this line will make background yellow

NKGetParameter(name)retrieves parameter passed as GET variable to the page, for instance navcontroller.gotoPage(“page.html?myVar=hello”); in page “page.html” you can use NKGetParameter(“myVar”); to retrieve the value of variable.

NKLog(message)logs provided message in the application run log or iPhones console log, used for debug purposes only. Available in NimbleKit 1.7 or newer

NKConfirm(title, message, bTitle1, bTitle2, callback)Shows an alert similar to NKAlert function with given title and message, bTitle1 and bTitle2 are titles for the buttons on alert, bTitle1 is necessary, but bTitle2 can be an empty string if you want just one button. callback is a function name to be called when user clicked a button on the alert, the format is callback(buttonIndex) where buttonIndex is a number of the button was clicked, count starts from 0.



NKExecuteJavascriptOnPage(jscode, pagename)executes provided javascript code on specified page

NKGetAppVersion()returns the version of the application (specified in info.plist file or set in Xcodeʼs target properties) Available in NimbleKit 1.8.3 or newer

NKPreloadPage(pageName, callback)starts asynchronous preloading of the page, taking as parameters name of the page to preload and a callback, which is a javascript function name, to be called when preloading is finished.



General Native Controls functionsOverview

Functions in this section will work with all native controls

NKNativeControlRotate(control, degrees)rotates native control (like NKTextField, NKButton, etc) with given angle specified in degrees.

NKSetControlAutoresizingMask(control, mask)sets the autoresizing mask of native control, which controls automatic autoresizing on device rotationcontrol - control for which you want to set autoresizing maskmask - autoresizing mask. Can be one of or any combination of following constants.

NKControlAutoresizingNone The view does not resize.NKControlAutoresizingFlexibleLeftMargin The view resizes by expanding or shrinking in the direction of the left margin.NKControlAutoresizingFlexibleWidth The view resizes by expanding or shrinking its width.NKControlAutoresizingFlexibleRightMargin The view resizes by expanding or shrinking in the direction of the right margin.NKControlAutoresizingFlexibleTopMargin The view resizes by expanding or shrinking in the direction of the top margin.NKControlAutoresizingFlexibleHeight The view resizes by expanding or shrinking its height.NKControlAutoresizingFlexibleBottomMargin The view resizes by expanding or shrinking in the direction of the bottom margin.

Example:

function createToolBar(){! var toolbar = new NKToolBar();! toolbar.init(0);! NKSetControlAutoresizingMask(toolbar, NKControlAutoresizingFlexibleWidth | NKControlAutoresizingFlexibleBottomMargin)! toolbar.show();}

this will make tab bar with flexible width and will make it “glue” to the top of the screen (as bottom margin is flexible and top margin is not).

NKNativeControlSetAlpha(control, alpha)sets the transparency of the native fixed iPhone control (like NKButton, NKSlider, etc) using provided alpha, value must be in range [0..1].Available in NimbleKit 1.9 or newer

NKNativeControlEnable(control, isEnabled)Controls enabled/disabled state of the native control. isEnabled can take values: “yes”, “no”, 1 and 0.Available in NimbleKit 1.9.4 or newer



NKControlSetBackgroundColor(control, r, g, b, a)Sets native controlʼs background color using 4 color components. All components are values in range [0..255]



Location services usage (GPS)Overview

Using location services you can obtain current latitude, longitude, precision and distance if coordinates changed after last update. Every time you want to update current location use NKUpdateLocation() function

NKUpdateLocation(callback)- callback is the name of a function callback to be called when device finished updating location, function has to take 5 parameters: latitude, longitude, precision, distance and error (0 returned if no error).

Usage:NKUpdateLocation("locationUpdated");

function locationUpdated(x, y, precise, moved, error){ NKAlert("Location updated", "x: "+x+" y: "+y+" precision: "+precise+" moved: "+moved);}



Photo library/camera supportOverview

NimbleKit allows to retrieve photos from your iPhone library or camera.

NKTakePicture(callback, source)This function pops up standard image picking dialog or photo camera dialog to choose/take picture

Parameters:- callback is a name os function to be called when user picked picture, has to have 1

parameter to receive base64 encoded image is jpeg format.- source is a name of source from which to take image, can take values:

“PhotoLibrary”, “SavedPhotoAlbum” and “Camera”. Please be advices that you can not take pictures from camera on iPhone Simulator as there is none.

This API is deprecated in NimbleKit 1.7, use NKPickImageObject instead

Example:<center> <div id="mypicture"></div></center><script type="text/javascript">NKTakePicture('picturePicked', 'photolibrary');

function picturePicked(imageBase64){ var node = document.getElementById("mypicture"); node.innerHTML = "<img height=\"300\" width=\"200\" src=\""+"data:image/jpg;base64,\n"+imageBase64+"\"/>";}</script>

NKPickImageObject(callback, source, x, y, width, height)This function pops up standard image picking dialog or photo camera dialog to choose/take picture

Parameters:- callback is a name os function to be called when user picked picture, has to have 1

parameter to receive NKImage object.- source is a name of source from which to take image, can take values:

“PhotoLibrary”, “SavedPhotoAlbum” and “Camera”. Please be advices that you can not take pictures from camera on iPhone Simulator as there is none.

- x, y, width, height are the parameters used for iPad implementation only and specify the frame where popover controller must point to. These parameters are optional.

Example:NKPickImageObject('picturePicked', 'camera');

function picturePicked(imageObj){! imageView = new NKImageView();! imageView.init(10, 10, 100, 100);! imageView.setImageObject(imageObj);! imageView.show();}Available in NimbleKit 1.7 or newer



Orientation supportiPhone application can change orientation, this sections describes how use this feature.

NKIsPageSupportsAutoOrientation()This function must be implemented and return “no” if you donʼt want to some specific page to have orientations supported. By default auto orientation is supported and possible orientations are read from your application plist file (in xcode4 those can be set in editor graphically)

Example: function NKIsPageSupportsAutoOrientation() { return "no"; }

pageWillRotate(degree)implement this function in order to receive information when iPhone is about to start orientation change to orientation specified in parameter.

Degree - can take 4 values: 0 - portrait -90 - landscape left 90 - landscape right180 - portrait upside down

pageDidRotate()implement this function to receive notification when orientation transition is complete



Application EventsOnApplicationQuit()

This callback is called right after application started quitting.Please do not use any alerts or similar UI actions as till the moment this function called there will be no application UI on the screen. Callback is called on every page, be sure not to overwrite many times your settings.

Example:function OnApplicationQuit(){ var settings = new NKSettings(); settings.setValueForKey("saved!!!", "isSaved");}

OnApplicationPause()This callback is called when application goes to background mode.You have to save your settings in this call back as application can be terminated by OS while in background without notification.Please do not use any alerts or similar UI actions as till the moment this function called there will be no application UI on the screen. Callback is called on every page, be sure not to overwrite many times your settings.

OnApplicationResume()This callback is called when application returns to foreground mode from background mode.

onPageShown(caller)This callback is called right before page is shown (but is fully loaded).

caller - the object which moved page in front, can be “tab_controller”, “nav_controller” or “window”

Example:

function onPageShown(caller){! NKAlert("Alert", "Page shown");}

onPageHidden()this callback is called when page lost focus. When UI is constructed can be called multiple times as if you create navigation controller page will be removed from the window and placed in navigation controller, so this function will be called when this happens.



FAQ1. How to add fullscreen company logo on application start?

You need to add file Default.png image to the project, it will be used automatically ! by iPhone OS

2. How to set image behind page so it is visible when user scrolls page?You need to add file nk_background.png image to the project, it will be used automatically by NimbleKit engine



TroubleshootingOverview

This section describes common problems and solutions for them

Threading• 10 seconds javascript limitThere is a limit of 10 seconds for all javascript functions to run. Some NimbleKit functions are asynchronous and some of them synchronous, main problem here is even if you use synchronous function which runs for less then 5 seconds it still can be executed for more then 5 seconds if before there was a call to asynchronous functions which are still executing, synchronous function will have to wait for them to finish. For instance all functions related to interface elements are asynchronous and used during loading time to build interface. All of those functions will return immediately, but in background will still work, which means if you call something like file reading during load time you can end up with crash because all file operations are synchronous and it will wait for all background functions to finish. Solution to this problem is simple, load all interface elements in <head> section and if you need to do some synchronous operations on load time move them to separate function and specify it to “onLoad” property of <body> section, so itʼs called after all interface is loaded.



nimble kit doc

Documents

nimblekit sdk documentation

copyright volnatech

nkapplication class

callbacks usage

alexander voloshyn

sample code

anna novikova

eugen belyakov