Nimble Kit

NimbleKit SDK! v. 1.9.
NimbleKit SDK
Documentation
Version 1.9.6
Created on 25.03.09
Last modified on 23.03.11
Authors:
Alexander Voloshyn! ! voloshyn@nimblekit.com

Eugen Belyakov !! ! belyakov@nimblekit.com
Editors:
Anna Novikova! ! ! novikova@nimblekit.com
Copyright © VolnaTech 2009-2010! 1

NimbleKit SDK! v. 1.9.6
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
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
• setRowHeight(height)! 32
• insertRecords(records)! 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
NimbleKit functions! 60
• NKGetUniqueIdentifier()! 60
• NKGetDeviceType()! 60
• NKSetPageOpaque(page, isOpaque)! 60
• NKIsInternetAvailableViaCellularNetwork! 60
• NKIsInternetAvailableViaWifi ! 60
• NKAlert(title, message)! 60
• NKMoveToPageAnimated(pageName, animation)! 60
• NKOpenURLInSafari(url)! 60
• NKStartPreloadingPage(pageName)! 61
• NKReloadPage(pageName)! 61
• NKGetLibraryVersion()! 61
• NKSetWebViewBackgroundColor(red, green, blue, alpha)! 61
• NKGetParameter(name)! 61
• NKLog(message)! 61
• NKConfirm(title, message, bTitle1, bTitle2, callback)! 61
• NKExecuteJavascriptOnPage(jscode, pagename)! 61
• NKGetAppVersion()! 61
• NKPreloadPage(pageName, callback)! 62
General Native Controls functions! 63
• Overview! 63
• NKNativeControlRotate(control, degrees)! 63
• NKSetControlAutoresizingMask(control, mask)! 63
• NKNativeControlSetAlpha(control, alpha)! 63
• NKNativeControlEnable(control, isEnabled)! 63
• NKControlSetBackgroundColor(control, r, g, b, a)! 64
Location services usage (GPS)! 65
• Overview! 65
• NKUpdateLocation(callback)! 65
Photo library/camera support! 66
• Overview! 66
• NKTakePicture(callback, source)! 66

• NKPickImageObject(callback, source, x, y, width, height)! 66
Orientation support! 67
• NKIsPageSupportsAutoOrientation()! 67
• pageWillRotate(degree)! 67
• pageDidRotate()! 67
Application Events! 68
• OnApplicationQuit()! 68
• OnApplicationPause()! 68
• OnApplicationResume()! 68
• onPageShown(caller)! 68
• onPageHidden()! 68
FAQ! 69
1. How to add fullscreen company logo on application start?! 69
2. How to set image behind page so it is visible when user scrolls page?! 69
Troubleshooting! 70
• Overview! 70
• Threading! 70

NimbleKit SDK Documentation

Overview
NimbleKit SDK is a library which simplifies development for iOS platform allowing to
create full featured applications using just html and JavaScript.
Requirements
Mac OS X 10.6.2 or newer
iPhone SDK 4.2 or newer
Compatibility and Dependencies

Products created with NimbleKit SDK will run on Apple devices with iOS 3.0 and newer.
Documentation
Documentation updates with every release of NimbleKit, for an updated documentation
please visit http://nimblekit.com and download latest version.
Quick Start
After you installed Nimble SDK there will be added new Xcode template which has to be
used to create Nimble Kit based applications.
Registering NimbleKit
After 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"];

NKTabBarController class reference

Overview
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 selected
title - title to be displayed on tab icon
image - 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 = 1
UITabBarSystemItemFeatured = 2
UITabBarSystemItemTopRated = 3
UITabBarSystemItemRecents = 4
UITabBarSystemItemContacts = 5
UITabBarSystemItemHistory = 6
UITabBarSystemItemBookmarks = 7
UITabBarSystemItemSearch = 8
UITabBarSystemItemDownloads = 9
UITabBarSystemItemMostRecent = 10
UITabBarSystemItemMostViewed = 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", "");
}
function OnApplicationQuit()
{
! array = tabController.getTabPositionsArray();
! settings.setValueForKey(array, "tabOrder");
}
setTabForPageDisabled(page, disabled)
sets tab disabled or enabled
page - page name of tab you want to set state for
disabled - 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 reference

Overview
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 button
callback - a string function name to be called when user pressed navigation item
image - 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 page
you 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 reference

Overview
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()
{
radio.stop();
}

NKApplication class reference

Overview
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”)

NKSlider
Overview
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 control
y - bottom coordinate of the control
width - 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();


NKBanner
Overview
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.2
iAd callbacks added in v 1.9.3

NKButton
Overview
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:
y - top coordinate of the control
height - vertical size of the control
callback - 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:
{
radio.playFromURL("http://myradio.com:8000");
}
var playButton = new NKButton();

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

NKToolBar
Overview
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 1
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
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)

NKTextView
Overview
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();

NKTextField
Overview
This control is used for user text input

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.
setSecure(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();

NKLabel
Overview
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]

NKTableView
Overview
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 title
subtitle - rowʼs subtitle, usually it is a description for the title
image - 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.
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 table
records - array of records
Example:
var tableView = new NKTableView();
! tableView.init(20, 20, 280, 300, 'plain');
!
! tableView.show();
! tableView.insertCategoryNamed('FirstGroup');
! tableView.insertCategoryNamed('SecondGroup');
! 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);

NKModalWindow
Overview
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

NKImageView
Overview
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()”)

NKSwitch
Overview
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:
var uiswitch = new NKSwitch();
uiswitch.init(20, 70);
uiswitch.show();
</script>
<a href="#" onClick="uiswitch.setState(!uiswitch.getState());">Switch State</a>

NKProgressBar
Overview
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:
y - bottom coordinate 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();

NKActivityIndicator
Overview
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 control
y- vertical coordinate of the control
size - vertical and horizontal size of the control
style - 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();
}
{
radio.notifyPlayingStarted("radioStartedToPlay");
indicator.show();
indicator.spin();
radio.playFromURL("http://myradio.com:8000");
}

NKContact
Overview
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);
}

NKAudioPlayer
Overview
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 player
player2.id = settings.getValueForKey(“playerID”);
player2.play(); // launch play of the first player

NKVideoPlayer
Overview
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

NKSystemVolumeControl
Overview
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.

NKAlertSheet
Overview
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();
}


NKFile
Overview
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.

NKSettings
Overview
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.

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.

NKFileDownloader
Overview
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

NKSQLite
Overview
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();

NKMapView
Overview
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
latitudeDelta
The 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.
longitudeDelta
The 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 subtitle
color 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

var oldLocation = "0.000000 0.000000 0.000000 0.000000";
var mapView = new NKMapView();

mapView.init(0, 0, 320, 420);
mapView.showUserLocation("YES");
checkIfUpdated();
function checkIfUpdated()
{
mapView.getUserLocation("alertLocation");
}
function alertLocation(newLocation){
! if (newLocation != oldLocation){
! ! oldLocation = newLocation;
! ! var location = new Array();
! ! location = newLocation.split(" ");
// now location is an array with 4 elements: x, y, precision and speed
! }
! else
! ! setTimeout(checkIfUpdated, 1000);
}
function mapTouchedAtCoordinates(latitude, longitude)

{
! NKLog("Latitude: "+latitude+"Longitude: "+longitude);
}

NKAppStore
Overview
This class is used to make in-app purchases
getAvailableProducts(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)
productIDs
the 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 methos
callback
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)”.

NKPasteboard
Overview
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

NKImage
Overview
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.

NKMailComposer
Overview
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("a.voloshyn@gmail.com, voloshyn@me.com");
! composer.setSubject("subject");!
! composer.setBody("message body!");
! composer.show();
}
Class Available in NimbleKit 1.7 or newer

NKSMSComposer
Overview
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

NKPopoverController
Overview
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.

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

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
Example:
var webView = new NKWebView;

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

NimbleKit functions
NKGetUniqueIdentifier()
Returns deviceʼs unique identifier based on hardware serial number.
NKGetDeviceType()
returns device type, possible values:
iPhone 1G
iPhone 3G
iPhone 3GS
iPhone 4
iPod Touch 1G
iPod Touch 2G
iPod Touch 3G
iPod Touch 4G
iPad
iPhone 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
NKIsInternetAvailableViaCellularNetwork
Returned value can be either “1” or “0” which represents if internet access available
using Cellular data network.
NKIsInternetAvailableViaWifi
Returned 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

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 functions

Overview
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 rotation
control - control for which you want to set autoresizing mask
mask - 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].
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 support

Overview
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>
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();
}

Orientation support
iPhone application can change orientation, this sections describes how use this feature.
NKIsPageSupportsAutoOrientation()
This function has to be implemented in javascript code in oder to let application know if
auto orientation is supported, by default it returns “no”.
Be aware if you use NKTabBarController all itʼs tabs have to support auto orientation,
otherwise considered that none of pages support orientation. With
NKNavigationController every separate page can specify if it supports orientation.
Example:
function NKIsPageSupportsAutoOrientation()
{
return "yes";
}
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 right
180 - portrait upside down
pageDidRotate()
implement this function to receive notification when orientation transition is complete

Application Events
OnApplicationQuit()
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()
{
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.

FAQ
1. 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

Troubleshooting
Overview
This section describes common problems and solutions for them
Threading
• 10 seconds javascript limit
There 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

Caricato da

Informazioni sul documento

Titolo originale

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

Nimble Kit

Caricato da

Copyright:

Formati disponibili

NimbleKit SDK! v. 1.9.

Alexander Voloshyn! ! voloshyn@nimblekit.com

Anna Novikova! ! ! novikova@nimblekit.com

Copyright © VolnaTech 2009-2010! 1

• Compatibility and Dependencies! 13

NKTabBarController class reference! 14

• setTabBarForPage(page, title, image)! 14

• setMoreBarTintColor(red, green, blue)! 15

NKNavigationController class reference! 16

• addNavigationItem(title, callback, image)! 16

Copyright © VolnaTech 2009-2010! 2

NKInternetPlayer class reference! 18

NKApplication class reference! 20

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

Please see callbacks usage in the sample code below! 22

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

• addButton(title, imageName, callback)! 25

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

• setTintColor(red, green, blue)! 25

Copyright © VolnaTech 2009-2010! 4

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

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

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

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

Copyright © VolnaTech 2009-2010! 5

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

• bindToDataBase(dbName, tableName, optionalQuery)! 31

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

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

Copyright © VolnaTech 2009-2010! 7

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

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

• setCenterCoordinate(latitude, longitude, isAnimated)! 51

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

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

Copyright © VolnaTech 2009-2010! 10

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

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

General Native Controls functions! 63

Location services usage (GPS)! 65

Photo library/camera support! 66

Copyright © VolnaTech 2009-2010! 11

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

Copyright © VolnaTech 2009-2010! 12

NimbleKit SDK Documentation

Compatibility and Dependencies

Nimble *nimble = [[Nimble alloc] initWithRootPage:@"main.html" window:window

Copyright © VolnaTech 2009-2010! 13

NKTabBarController class reference

setTabBarForPage(page, title, image)

Copyright © VolnaTech 2009-2010! 14

setMoreBarTintColor(red, green, blue)

Copyright © VolnaTech 2009-2010! 15

NKNavigationController class reference

addNavigationItem(title, callback, image)

Copyright © VolnaTech 2009-2010! 16

var navController = new NKNavigationController();

Copyright © VolnaTech 2009-2010! 17

NKInternetPlayer class reference

Copyright © VolnaTech 2009-2010! 19

NKApplication class reference

Copyright © VolnaTech 2009-2010! 20

init(x, y, width, callback)