====== Code examples ======

These depend on Jiggy 0.17

===== Common code =====

Most of the examples here, rely on the same basic set-up - the code below:

<code javascript>
Plugins.load( "UIKit" );

var window = new UIWindow( UIHardware.fullScreenApplicationContentRect );
window.setHidden( false );
window.orderFront();
window.makeKey();
window.backgroundColor = [ 1 , 1 , 1 , 1 ];

var mainView = new UIView();

window.setContentView( mainView );
</code>
----
===== Navigation bar ===== 

The navigation bar (UINavigationBar) is that blue-ish bar you see at the top of most iPhone apps. It lets you show one or two buttons and the button on the left can be a "back" button - it shows with a pointed corner on its left side.

The navigation bar also lets you add navigation items - so that you can easily provide feedback and a back button as users navigate deeper into a hierarchy.

Let's start with the simplest case: a navigation bar with only a right button:
(Add the code below to the common code)

<code javascript>
var bar = new UINavigationBar( [ 0 , 0 , window.bounds[ 2 ] , 48 ] );
bar.showButtonsWithLeftTitle( null , "Right" , false );

mainView.addSubview( bar );
</code>

You will see a single button on the right side labeled "Right" and no title for the navigation bar. The thing to notice here is that you can pass **null** to **showButtonsWithLeftTitle** to keep it from showing either one of the two buttons.

==== Button presses ====

If you want to know when the user presses one of the buttons in the navigation bar, just attach an **onButtonClicked** event handler to it like this:

<code javascript>
bar.onButtonClicked = 
function( theBar , theButton )
{
  log( "You clicked button # " + theButton );
}
</code>

In that function the parameter **theButton** is a number: 0 for the right button and 1 for the left button. Note that to see the **log** output, you will need to run your app from the terminal.

==== Navigation items ====

UINavigationItems let you not only set the title of the navigation bar, but they also make it easy to create a **stack** of entries that work almost automatically. Lets start by adding a title to our navigation bar:

<code javascript>
var itemOne = new UINavigationItem( "The first one" );
bar.pushNavigationItem( itemOne );
</code>

You will now see that our navigation bar has the title "The first one" - because we added a navigation item to it. Navigation items have a **tag** property which is a simple integer that lets you identify it from others. Lets get a little fancier and show how you can navigate easily.

<code javascript>
var bar = new UINavigationBar( [ 0 , 0 , window.bounds[ 2 ] , 48 ] );
bar.showButtonsWithLeftTitle( null , "Next" , false );

mainView.addSubview( bar );

var itemOne = new UINavigationItem( "Level 0" );

bar.pushNavigationItem( itemOne );

bar.onButtonClicked = 
function( theBar , theButton )
{
  if ( theButton == 0 )
  {
    var newItem = new UINavigationItem( "Level " + theBar.navigationItems.length );  

    theBar.pushNavigationItem( newItem );
  }
  else 
  {
    theBar.popNavigationItem();
  }    
}
</code>

In this example, you can navigate endlessly and back. The UINavigationBar takes care of showing the right back buttons with the right titles at the right time.  
----
===== Accelerometer =====

[[http://jiggyapp.com/download/examples/accelerometer.js|Download the code for this example]]

It is very easy to work with the iPhone's accelerometer, but please note that **it only works when you launch your app from SpringBoard; you have to stop Jiggy go back to the main menu and launch your app by touching its icon. It won't work at all if you run your app from the Jiggy IDE**.

To catch accelerometer events, you just implement a global function called **onAccelerate** like this: (Don't forget to add this to the common code above)

<code javascript>
var xlabel = new UITextLabel( [ 10 , 0 , window.bounds[ 2 ] - 20 , 60 ] );
var ylabel = new UITextLabel( [ 10 , 60 , window.bounds[ 2 ] - 20 , 60 ] );
var zlabel = new UITextLabel( [ 10 , 120 , window.bounds[ 2 ] - 20 , 60 ] );

mainView.addSubview( xlabel );
mainView.addSubview( ylabel );
mainView.addSubview( zlabel );

function onAccelerate( x , y , z )
{
  xlabel.text = "X = " + String( x );
  ylabel.text = "Y = " + String( y );
  zlabel.text = "Z = " + String( z );  
}
</code>

Save that code, stop Jiggy and launch your app from SpringBoard - you will see the three labels showing the accelerometer values. For a good description of what the values mean, [[http://www.tuaw.com/2007/09/10/iphone-coding-using-the-accelerometer/|see this great article]].
----
===== Animation =====

[[http://jiggyapp.com/download/examples/animation.js|Download the source code]]

As of Jiggy 0.17 there are a few basic animations available. The process is very straight forward, you create a kind of animation, setting up a few parameters and a target **view** and then pass it to the **Animator** class to deal with. 
In Jiggy 0.17 you can do alpha animations (fading), frame animations (change size and/or position) and rotation animations. Here is an example that animates a text label until it is no longer visible.

<code javascript>
var label = new UITextLabel( [ 40 , 40 , window.bounds[ 2 ] - 80 , 120 ] );
label.backgroundColor = [ 0 , 0 , 0 , 1 ];
label.text = "Animate Me!";
label.setFont( new Font( "Trebuchet MS" , 0 , 36 ) );
label.color = [ 1 , 1 , 1 , 1 ];
label.centersHorizontally = true;

mainView.addSubview( label );

var endFrame = label.frame;
endFrame[ 0 ] += endFrame[ 2 ] / 2;
endFrame[ 1 ] += endFrame[ 3 ] / 2;
endFrame[ 2 ] = 0;
endFrame[ 3 ] = 0;

var animation = new UIFrameAnimation( label , 3 , label.frame , endFrame );

Animator.addAnimation( animation , 2 , true ); 
</code>

After we set up a label to animate, we calculate a new **frame** for it - a new size and position. Then, we create a **UIFrameAnimation**. To it, we pass the label, a value for the **curve** (0=ease in and out,1=ease in,2=ease out and 3=linear) and two rectangles - the start one and the end one.
Then, we pass that animation to the global Animator object - with a duration of **2 seconds** and telling it to start the animation right away.

Now, we will do two animations at once:

<code javascript>
var shrink = new UIFrameAnimation( label , 3 , label.frame , endFrame );
var fade = new UIAlphaAnimation( label , 0 , 1 , 0 );

Animator.addAnimation( shrink , 2 , true ); 
Animator.addAnimation( fade , 2 , true );
</code>

The label will shrink as it becomes completely transparent.

==== Events ====

You can easily tell when an animation starts or is finished, by attaching **onStart** and **onStop** event handlers to it, like this:

<code javascript>
var fade = new UIAlphaAnimation( label , 0 , 1 , 0 );

fade.onStop = function() { log( "I have faded!" ); };
</code>

Note that you won't see the log message unless you are running Jiggy from the terminal.

===== More Examples =====

More sample code can be found here:

http://jiggyapp.com/download/examples