To get started, let’s take a relatively simple scenario. Suppose you want to create an application that displays a pop-up dialog window when a gadget is clicked, as shown in the following images.

Table 4.1. Displaying a pop-up dialog window using a script

Main Application Window	Main Application Window with Pop-up Window

To program this type of functionality, you must:

The following code samples demonstrate how it works.

<?xml version="1.0" encoding="utf-8" ?>
<?import href="box://ocpToolkit/content/inputPack/inputGadgets.box"?>
<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>

<window xmlns="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd"
  xmlns:on="http://www.aol.com/boxely/reaction.xsd" 
  s:fill="white"
  title="My Application"
   s:height="200"
  s:width="275" >

  <library xmlns="http://www.aol.com/boxely/resource.xsd"
    xmlns:box="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd" 
    xmlns:on="http://www.aol.com/boxely/reaction.xsd"  >

    <gadget id="myGadget" >
      <parts>
        <box:text id="buttonLabel" value="Click Here" />
      </parts>
    </gadget>
    <style tag="myGadget" stroke="black" strokeWidth="1"  strokeCornerRadius="4"
         fill="#dddddd" fillCornerRadius="4" padding="1 4 2 4" margin="10" 
         vAlign="center" hAlign="center">
      <part name="buttonLabel" textColor="black"/>
    </style>

  </library>

  <vbox>
    <multilineLabel  value="This application demonstrates how to program a 
        gadget to perform a task.  The following button is a custom, user-defined 
        gadget. When clicked, it displays a pop-up window."  
        s:margin="40 10 10 10" />
    <box s:height="10" />
    <myGadget/> 
  </vbox> 

</window>

<?xml version="1.0" encoding="utf-8" ?>
<?import href="box://ocpToolkit/content/inputPack/inputGadgets.box"?>
<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>

<window xmlns="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"
    xmlns:on="http://www.aol.com/boxely/reaction.xsd"
    s:fill="white"
    s:minHeight="100"
    s:maxHeight="100"
    s:minWidth="200"
    s:maxWidth="200"
    title="My Pop-up Window">

  <library xmlns="http://www.aol.com/boxely/resource.xsd"
    xmlns:box="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd">

    <gadget id="informationArea">
      <parts>
        <box:multilineLabel  value="This is the pop-up window." />
      </parts>
    </gadget>
    <style tag="informationArea" flex="1" hAlign="center" vAlign="center"/>

  </library> 
  <informationArea id="dialog" dragMode="window"/>
</window>

// The component function is called when the gadget is instantiated
function component (_gadget) { }

// The displayPopupWindow is called when myGadget is clicked
component.prototype.displayPopupWindow = function ()
{
  shell.openScene("popupwindow.box", 
    this.scene, "PopupWindow", null, null, true);
}

<library xmlns="http://www.aol.com/boxely/resource.xsd"
  xmlns:box="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd"  
  xmlns:on="http://www.aol.com/boxely/reaction.xsd" >

    <gadget id="myGadget"   language="jscript"
          code="myGadget.js" >
      <parts>
        <box:text id="buttonLabel" value="Click Here" />
      </parts> 
      <behavior>
        <reaction event="click" action="gadget:displayPopupWindow();"/>
      </behavior>
    </gadget>
    <style tag="myGadget" stroke="black" strokeWidth="1"  strokeCornerRadius="4"
         fill="#dddddd" fillCornerRadius="4" padding="1 4 2 4" margin="10" 
         vAlign="center" hAlign="center">
      <part name="buttonLabel" textColor="black"/>
    </style>

</library>

Testing Your Application

Once you’ve associated JavaScript functions with a gadget, you can test your work by running the .box file that controls the application.

If you’ve programmed the application correctly, the main application window displays and, when you press the "click here" gadget, a pop-up window opens.

Note

If you are unsuccessful running your program, refer to the Appendix D: Troubleshooting Reference section of this guide.

When running a Boxely application, several singleton objects are available to you: shell, scene, and appUtils. These objects, and some of the methods available to them, are described in this section.

In the previous section, you were introduced to the overall process for incorporating program logic into an application using scripting and event handling. In this section, we’ll take a closer look at event handling.

To be of use to us, an application must be able to respond to events that take place during its runtime, such as movement of the mouse, the initialization of a scene, or even the completion of an animation.

Some of the events to which a Boxely application can respond are:

As the developer, it’s your job to program an application to listen for and respond to events, using one (or both) of the following methods:

Event Handling Using Behaviors and Reactions

To program a gadget to listen for and respond to an event, you can use the behavior and reaction elements. The reaction element listens for an event; when the event occurs, it calls a corresponding action. The behavior element serves as a container for the reaction elements defined for the gadget.

Let’s look at an example. Suppose you want to program a gadget to call a specific function when the user places his or her mouse over the gadget and another function when the user clicks the gadget. To do so, you would add a behavior element and two contained reaction elements to the gadget’s definition, as shown below in bold:

<gadget id="myGadget" language="jscript" code="4a_eventHandling.js" >
  <parts>
    <box:text id="myPart" value="Change Gadget Fill" />
  </parts> 
  <behavior>
    <reaction event="mouseOver" action="gadget:changeFill();" />
    <reaction event="click" action="gadget:oneNewWindow();" />
  </behavior>
</gadget>

In this example, functions are invoked when an event occurs in any part of the gadget, as shown in the images below:

Table 4.2. The gadget changes the fill color when the mouse goes over it

Upon loading, the gadget displays in its initial state. When the mouse is placed over any part of the gadget, the changeFill function is invoked.

The following code demonstrates how to program a box within the gadget to respond to events:

<gadget id="myGadget" language="jscript" 
  code="../../content/appendix/4a_eventHandling.js"  >
  <parts>
    <box:text id="myPart" value="Change Gadget Fill" > 
      <box:reaction event="mouseOver" action="gadget:changeFill();" />
      <box:reaction event="click" action="gadget:oneNewWindow();" />
    </box:text>
  </parts>
</gadget>

In this example, functions are invoked when an event occurs in the myPart box. If the user interacts with any part of the gadget that is outside the myPart box, nothing happens.

Table 4.3. The gadget changes the fill color when the mouse goes over the "change gadget fill" box

Upon loading, the gadget displays in its initial state. When the mouse is placed over the gadget, but not over the box within it, nothing happens. When the mouse is placed over the box within the gadget, the changeFill function is invoked.

<window xmlns="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd" 
  xmlns:on="http://www.aol.com/boxely/reaction.xsd"
  title="My Application" ... >

</window>

<window xmlns="http://www.aol.com/boxely/box.xsd"
  title="My Application" ... >

  <library xmlns="http://www.aol.com/boxely/resource.xsd"
    xmlns:box="http://www.aol.com/boxely/box.xsd"
    xmlns:s="http://www.aol.com/boxely/style.xsd"  
    xmlns:on="http://www.aol.com/boxely/reaction.xsd" >

    ...

  </library>
</window>

on:eventName="someFunction();"

<gadget id="myGadget" script="someJavaScript.js" >
  <parts>
    <box:box  on:mouseOver="gadget:changeFill()"
             on:click="gadget:openNewWindow();" >
      <box:text id="myPart" value="Change Gadget Fill" />
    </box:box>
  </parts>
</gadget>

If you are unsuccessful running a Boxely application, refer to the Troubleshooting Reference for general debugging and troubleshooting tips.

Now that you’ve been introduced to the steps involved in programming a gadget, let’s try it out with the "To-Do List" application.

The first area that requires programming is the titleArea gadget. Up until this point, the date and time value shown within the titleArea gadget has been a static value of "00/00/00 12:00:00 PM." In this exercise, you’ll learn how to program the gadget to retrieve and display the current system time, as shown in the image on the right.

Table 4.4. A titleArea gadget with and without programming

titleArea Gadget (without programming)	titleArea Gadget (with programming)

Follow these steps to complete the exercise:

Step 1: Creating common JavaScript functions

The first function needed in this exercise is the getDate function, a function that retrieves and formats the current system date. Because this function is potentially of use to many gadgets, it should reside in a common file with global scope.

You can create the getDate function on your own by writing a JavaScript function that returns a string representing the current system date and time. To save time, you can use the getDate function provided in the common.js exercise file, which is located in the ToDoList/common directory.

Step 2: Creating JavaScript functions for the titleArea gadget

Next, you need to create JavaScript functions to represent the titleArea gadget and set the gadget’s dateTime display based on the current system date and time. These functions pertain to the titleArea gadget only, therefore the must reside in a single file named titleAreaGadgets.js.

In a text editor, create a new file named titleAreaGadgets.js and add the following code. Be sure to save the file in the same directory (/samples/TodoList) where the other "To-Do List" application files reside.

// The component function is called when the gadget is first instantiated
function component (_gadget) { }

// Declare properties for use in the gadget
component.prototype.dateTime = null;

// The onInitialized function is called when the gadget is created, 
// but not yet presented (i.e. it’s called before it’s visible)
component.prototype.onInitialized = function()
{
  // Get each part within the gadget based on its id attribute
  this.dateTime = this._gadget.getPartById("dateTime");

  // Set the value attribute of the dateTime box to the value getDate() returns
  this.dateTime.setAttribute("value", getDate());
}

This is how the above code works:

The component function represents the titleArea gadget. The OCP Toolkit creates an instance of the component object when the gadget is first instantiated.

The onInitialized function uses the getPartById method to retrieve the gadget’s part identified as "dateTime". It then uses the setAttribute method to set the value of the dateTime part equal to the value returned by the getDate function. (The getDate function resides in the common.js file; in the next section, you will learn how make this function available to the gadget by including the file in your gadget’s definition.)

Step 3: Associating JavaScript functions with the titleArea gadget

Now, let’s edit the titleAreaGadgets.box file to:

The code shown below in bold demonstrates how to do this.

<gadget id="titleArea"  language="jscript" 
    code="titleAreaGadgets.js" >
   <script id="common" language="jscript" 
      href="../../common/common.js" />
  <parts>
    <box:label id="title" value="My To Do List"/>
    <box:label id="dateTime" value="Date/Time: 00/00/0000 12:00:00 PM" />
  </parts> 
  <behavior>
    <reaction event="initialized" action="gadget:onInitialized();" />
  </behavior>
</gadget>

Step 4: Testing your application

Now that you’ve created the required JavaScript files and modified the titleArea gadget’s definition to call the appropriate function when it is first initialized, you can test your "To-Do List" application.

The current system time should display in the dateTime part of the titleArea gadget, as shown in the image below.

In the "To-Do List" application, the buttonsArea gadget provides all navigational options available to the user:

Let’s start with the first option: creating a new To-Do List item. The user experience should involve two phases:

Table 4.5. Creating a new To-Do List item

Select "Create To-Do Item"	Enter item information and click "Insert Item"

To implement this functionality, follow these steps:

Step 1: Creating JavaScript functions for the ToDoList gadget

First, you need to create a JavaScript file to represent the ToDoList gadget and open the "Create New Item" dialog box.

In a text editor, create a new file named ToDoList.js and add the following code. Be sure to save the file in the same directory where other "To-Do List" application files reside.

// The component function is called when the gadget is first instantiated
function component (_gadget) { }

// Declare properties for use in gadget
component.prototype.titleArea = null;
component.prototype.noteArea = null;
component.prototype.buttonsArea = null;

component.prototype.items = Array();
component.prototype.currentItem = -1;

// The onInitialized function is called when the gadget is created, 
// but not yet presented (i.e. visible)
component.prototype.onInitialized = function ()
{
  // get each part of the gadget by their respective id attributes
  this.titleArea = this._gadget.getPartById("titleArea");
  this.noteArea = this._gadget.getPartById("noteArea");
  this.buttonsArea = this._gadget.getPartById("buttonsArea");

  // You now have access to the individual gadgets and can call their 
  // functions and access their properties
}

// The onCreateItem function is called when the ‘create to-do item’ 
// button is pressed.
component.prototype.onCreateItem = function ()
{
  shell.print("ToDoList::onCreateItem");

  var paramDictionary = shell.serviceManager.basics.dictionary;
  paramDictionary.setValueForKey(this._gadget,"parentGadget");

  // open a custom dialog
  shell.openSceneAndWait("../../common/CreateNewItemDialog.box", 
                          this.scene, "CreateNewItemDialog", paramDictionary);
}

component.prototype.insertItem = function (item)
{
  this.items.push(item);
  this.currentItem = this.items.length - 1;
}

The above code does the following:

The component function represents the ToDoList gadget. The OCP Toolkit creates an instance of the component object when the gadget is first instantiated.

The onInitialized function retrieves the parts within the ToDoList gadget and stores them in variables for later use.

The onCreateItem function first defines the paramDictionary object, a basics dictionary that can hold key-value pairs. In our case, the key is "parentGadget" and the value is a reference to the instance of the ToDoList gadget. We then call the openSceneAndWait function to open the dialog window defined by the CreateNewItemDialog.box file, passing the paramDictionary object to the dialog window. When the CreateNewItemDialog gadget’s onInitialized is called, it uses the setCallback function to store a reference to the ToDoList JavaScript object so that its insertItem function may be called when a new item has been created. This reference was obtained from the scene’s basics dictionary, which we passed through the openSceneAndWait function.

The insertItem function takes one parameter, item, which it adds to the items array. It then sets the location of the currentItem property equal to the position of the new item in the array.

Step 2: Associating JavaScript functions with the ToDoList gadget

Next, you need to edit the ToDoList.box file to:

The code shown below in bold demonstrates how to do this.

<gadget id="ToDoList"  language="jscript" 
    code="ToDoList.js" >
  <parts>
    <box:titleArea id="titleArea"/>
    <box:noteArea id="noteArea"/>
    <box:buttonsArea id="buttonsArea"/>
  </parts> 
  <behavior>
    <reaction event="initialized" action="gadget:onInitialized();" />
  </behavior>
</gadget>

Step 3: Building the "Create New Item" dialog window

The Create New Item dialog window contains the fields and buttons shown in the image below:

To create a new window within your application, you must create a new .box file that describes the window, as well as any JavaScript functions required to construct and support its layout.

To save time, the .box file that describes the "Create New Item" dialog window (createNewItemDialog.box) and its corresponding JavaScript file (createNewItemDialog.js) have been prepared for you and are available in the ToDoList/common directory.

Some of the functions in the createNewItemDialog.js that are worth noting are:

Step 4: Testing the "Create New Item" interface

Once you’ve downloaded the "Create New Item" interface, you can test it by running the CreateNewItemDialog.box file.

You should see a window that looks like this:

To test the "Create New Item" interface:

Step 5: Creating JavaScript functions for the buttonsArea gadget

Now, you must create a JavaScript file to represent the buttonsArea gadget and initiate the "Create To-Do Item" function by calling the appropriate parent object function. (The parent object is the ToDoList.)

In a text editor, create a new file named buttonsAreaGadgets.js and add the following code. Be sure to save the file in the same directory where other "To-Do List" application files reside.

// The component function is called when the gadget is first instantiated
function component (_gadget) { }

// Declare properties for use in gadget
component.prototype.parent = null;

// The onInitialized function is called when the gadget is created, 
// but not yet presented (i.e. visible)
component.prototype.onInitialized = function()
{
  component.prototype.parent = this._gadget.gadgetParent;
}

/*
 * Button Commands
 * We pass off these commands to the parent gadget.
 * We assume the parent gadget will know what to do.
 */
// create new item command
component.prototype.onCreateItem = function()
{
  this.parent.onCreateItem();
}

This is how it works:

The component function represents the buttonsArea gadget. The OCP Toolkit creates an instance of the component object when the gadget is first instantiated.

The onInitialized function uses the gadgetParent method to retrieve the parent object and store it in the parent property. (As mentioned before, the parent object is the ToDoList.)

The onCreateItem function calls the onCreateItem method defined for the parent object. (You created the parent object’s onCreateItem function in step one.)

Step 6: Associating JavaScript functions with the buttonsArea gadget

Next, you need to edit the buttonsAreaGadgets.box file to:

The code shown below in bold demonstrates how to do this.

<library xmlns="http://www.aol.com/boxely/resource.xsd"
  xmlns:box="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd"  
  xmlns:on="http://www.aol.com/boxely/reaction.xsd" >

  <gadget id="buttonsArea"  language="jscript" 
      code="buttonsAreaGadgets.js" >
    <parts>
      <box:hbox id="prevNextButtons">
          <box:textButton label="&#171; Prev Note" 
              tooltip="Go to your previous Note."/>
          <box:hbox s:flex="1"/>
          <box:textButton label="Next Note &#187;" 
              tooltip="Go to your next Note."/>

      </box:hbox>
      <box:button  on:command="gadget:onCreateItem();" s:flex="1" 
          defaultButton="true" icon="../../theme/images/iconWrite.png" 
          label="Create To-Do Item" tooltip="Create new To-Do Note." />
      <box:hbox>
        <box:button s:flex="1" 
          icon="../../theme/images/iconClearItem.png" 
          label="Clear To-Do Item" tooltip="Remove this Note from your list."/>
        <box:button s:flex="1" 
          icon="../../theme/images/iconClearList.png" 
          label="Clear To-Do List" tooltip="Remove all Notes from your list."/>
      </box:hbox>
    </parts> 
    <behavior>
      <reaction event="initialized" action="gadget:onInitialized();" />
    </behavior>
  </gadget>
  <style tag="buttonsArea" height="88" orient="vertical" >
    <part name="prevNextButtons" flex="1" margin="0 0 12 0"/>
  </style>
</library>

Step 7: Testing your application

Now, when you run the "To-Do List" application, you should be able to select the "Create New Item" button and then enter information about a new item, as shown in the images here:

Table 4.6. Creating a new To-Do List item

Select "Create To-Do Item"	Enter information about the item and click "Insert Item"

While this is a great start, there is still a lot more to do. Proceed to the next section to learn how to program the noteArea and ToDoList gadgets to display items in the items array.

In this exercise, you will program the noteArea and ToDoList gadgets to display items in the items array. Perform the following steps to complete the exercise.

Step 1: Adding attributes to the noteArea gadget

First, in the noteArea gadget, you will use the attributes element to define a set of default data attributes and values associated with the gadget: title, date, description, and image. (These attributes represent data elements of a "to-do" item in the items array.) Then, using the inherits attribute, you will reference these attributes from the relevant parts of the noteArea gadget.

Generally, when you have data associated with a gadget that needs to be manipulated in your application, you should use the attributes element in conjunction with the inherits attribute to manage the data. This method allows the gadget to control the data, without having to access and manipulate the parts within it.

To complete this step, edit the noteAreaGadgets.box file and:

The code shown below in bold demonstrates how to do this.

<?xml version="1.0" encoding="utf-8" ?>
<?import href="box://ocpToolkit/content/inputPack/inputGadgets.box"?>
<?import href="box://ocpToolkit/content/core/coreGadgets.box"?>
<?import href="box://ocpToolkit/theme/default/toolkit.box"?>

<library xmlns="http://www.aol.com/boxely/resource.xsd"
  xmlns:box="http://www.aol.com/boxely/box.xsd"
  xmlns:s="http://www.aol.com/boxely/style.xsd">

  <gadget id="noteArea"> 
    <attributes title="" date="" description="" image="" />
    <parts>
      <box:label id="itemTitle"  inherits="value=title" />
      <box:label id="itemDate"  inherits="value=date" />
      <box:vbox id="descriptionContainer">
        <box:multilineLabel id="itemDescription" 
             inherits="value=description" />
      </box:vbox>
      <box:image id="itemImage"  inherits="src=image" />
    </parts>
  </gadget>
  <style tag="noteArea" orient="vertical" margin="12 0" flex="1" 
    fill="url(#notepadImage)"  hAlign="center" vAlign="top">
    <part name="itemTitle" padding="0" margin="8 0 0 0" fontFamily="Arial" 
        fontSize="22pt"/>
    <part name="itemDate" padding="0" margin="0" fontFamily="Arial"  
        fontSize="12pt"/>
    <part name="descriptionContainer" overflow="scroll" minHeight="90" 
        maxHeight="90" minWidth="280" maxWidth="280" hAlign="center" 
        margin="14 0"/>
    <part name="itemDescription" width="240" minHeight="80" 
        fontFamily="Brush Script" fontSize="14pt"/>
    <part name="itemImage" maxWidth="240" maxHeight="180"/>
  </style>
</library>

Step 2: Creating JavaScript functions for the noteArea gadget

For the noteArea gadget, you must first create JavaScript functions to represent and initialize the gadget. Then, you need to create functions to display a default item (when the application first loads) and the current item in the items array (after a new item has been created).

In a text editor, create a new file named noteAreaGadgets.js and add the following code. Be sure to save the file in the same directory where other "To-Do List" application files reside.

// The component function is called when the gadget is first instantiated.
function component (_gadget) { }

// The onInitialized function is called when the gadget is first created,
// but not yet presented (i.e. visible)
component.prototype.onInitialized = function()
{
}

// The setDisplay function populates the noteArea gadget parts with 
// the values in the element of the item array passed to the function.
component.prototype.setDisplay = function(item)
{
  this._gadget.setAttribute("title", item["title"]);
  this._gadget.setAttribute("date", formatDate(item["date"]));
  this._gadget.setAttribute("description", item["description"]);
  this._gadget.setAttribute("image", item["image"]);
}

// The blankDisplay function populates the noteArea gadget parts with
// default values.
component.prototype.blankDisplay = function()
{
  this._gadget.setAttribute("title", "[no note to display]");
  this._gadget.setAttribute("date", "");
  this._gadget.setAttribute("description", 
      "Instructions: Add a note with the button 'Create To-Do Item' below.");
  this._gadget.setAttribute("image", gDefaultImage);
}

This is how it works:

The component function represents the noteArea gadget. The OCP Toolkit creates an instance of the component object when the gadget is first instantiated.

The onInitialized function does nothing. (Don’t worry about it for now. In chapter nine, we’ll update this function to incorporate data binding.)

The setDisplay function sets the gadget’s data attributes (as defined in the gadget’s attributes element) equal to the values of the current item that was passed to the function.

The setAttribute method used in this function takes two parameters: the first is the name of the attribute to be set (the name must correspond to a value used in the gadget’s attributes element), the second is the value to which the attribute will be set.

The blankDisplay function sets the gadget’s attributes equal to static, default values.

Step 3: Associating JavaScript functions with the noteArea gadget

To use the noteArea JavaScript functions defined in the previous section, you must now edit the noteAreaGadgets.box file:

The code shown below in bold demonstrates how to do this.

<gadget id="noteArea"  language="jscript" 
    code="noteAreaGadgets.js" >
  <attributes title="" date="" description="" image="" />
   <script id="common" language="jscript" 
        href="../../common/common.js" />
  <parts>
    <box:label id="itemTitle" inherits="value=title" />
    <box:label id="itemDate" inherits="value=date" />
    <box:vbox id="descriptionContainer">
      <box:multilineLabel id="itemDescription"  
          inherits="value=description" />
    </box:vbox>
    <box:image id="itemImage" inherits="src=image" />
  </parts> 
  <behavior>
    <reaction event="initialized" action="gadget:onInitialized();" />
  </behavior>
</gadget>

Step 4: Adding JavaScript functions to the ToDoList gadget

Next, you need to add JavaScript functions to the ToDoList gadget to display the default item (when the application first loads) and the current item (after a new item has been created).

Open the ToDoList.js file and add the following code shown below in bold.

// The component function is called when the gadget is first instantiated
function component (_gadget) { }

// Declare properties for use in gadget
component.prototype.titleArea = null;
component.prototype.noteArea = null;
component.prototype.buttonsArea = null;

component.prototype.items = Array();
component.prototype.currentItem = -1;

// The onInitialized function is called when the gadget is created, 
// but not yet presented (i.e. visible)
component.prototype.onInitialized = function ()
{
  // get each part of the gadget by their respective id attributes
  this.titleArea = this._gadget.getPartById("titleArea");
  this.noteArea = this._gadget.getPartById("noteArea");
  this.buttonsArea = this._gadget.getPartById("buttonsArea");

  // you now have access to the individual gadgets and can call their 
  // functions and access their properties
 
  this.displayDefaultItem();
}

// The onCreateItem function is called when the ‘create to-do item’ 
// button is pressed
component.prototype.onCreateItem = function ()
{
  shell.print("ToDoList::onCreateItem");

  var paramDictionary = shell.serviceManager.basics.dictionary;
  paramDictionary.setValueForKey(this._gadget,"parentGadget");

  // open a custom dialog
  shell.openSceneAndWait("../../common/CreateNewItemDialog.box", 
                          this.scene, "CreateNewItemDialog", paramDictionary);

}

component.prototype.insertItem = function (item)
{
  this.items.push(item);
  this.currentItem = this.items.length - 1; 
  this.displayCurrentItem();
}
 
component.prototype.displayDefaultItem = function ()
{
  this.noteArea.blankDisplay();
}

component.prototype.displayItem = function (index)
{
  if (this.items.length == 0)
  {
    this.displayDefaultItem();
    return;
  }

  if (index > (this.items.length - 1))
  {
    this.currentItem = this.items.length - 1;
  }
  else if (index < 0)
  {
    this.currentItem = 0;
  }
  else
  {
    this.currentItem = index;
  }

  var item = this.items[this.currentItem];
  this.noteArea.setDisplay(item);
}


component.prototype.displayCurrentItem = function ()
{
  this.displayItem(this.currentItem);
}

This is how the code above works:

The displayDefaultItem function calls the noteArea’s blankDisplay function, which sets the noteArea gadget attributes equal to static, default values.

The displayItem function takes one parameter, index, which represents the location of the item in the items array that is to be displayed. The function first checks if the length of the items array is zero, in which case it displays the default item and exits. If the length of the items array is not zero, the functions sets the currentItem property based on the following logic:

Once the currentItem property it set, the noteArea’s setDisplay function is called, passing the item in the items array that has an index value equivalent to that stored in the currentItem property.

The displayCurrentItem function invokes the displayItem function, passing the currentItem as the index that represents the item to display.

Step 5: Testing your application

Now, when you first open the "To-Do List" application, you should see the default "to-do" item. When you create and insert a new item, that item should display, as shown in the images below:

Table 4.7. Inserting a new "to-do" item

Create a new item and then select "Insert Item".	The item displays in the main application window.

Now that you can create and display new "to-do" items in the application, it’s time to look at the other buttons in the buttonsArea gadget: "Prev Note", "Next Note", "Clear To-Do Item", and "Clear To-Do List". Proceed to the next exercise to learn how to program these buttons.

In the final exercise of this chapter, you will program the remaining buttons in the buttonsArea gadget: Prev Note, Next Note, Clear To-Do Item, and Clear To-Do List.

Because these buttons manipulate the core data in the application, the buttonsArea functions will invoke functions defined in the parent object (the ToDoList), where the items array is stored.

To complete the exercise, follow these steps:

Step 1: Adding JavaScript functions to the ToDoList gadget

First, you need to add JavaScript functions to the ToDoList gadget to display the previous or next item in the items array. In addition, you must define functions to clear one or all items in the items array.

Open the ToDoList.js file and add the following functions:

// navigation functions
component.prototype.onPreviousItem = function ()
{
  shell.print("ToDoList::onPreviousItem");
  this.displayItem(this.currentItem - 1);
}

component.prototype.onNextItem = function ()
{
  shell.print("ToDoList::onNextItem");
  this.displayItem(this.currentItem + 1);
}

// removal functions
component.prototype.onClearItem = function ()
{
  shell.print("ToDoList::onClearItem");

  // pop-up a confirm dialog
  var confirmed = this.scene.confirm
     ("Are you sure you want to remove the item?", "Remove this item?");
  if (confirmed.results)
  {
    // delete current item
    this.deleteItem(this.currentItem);
    this.displayCurrentItem();
  }
}

component.prototype.onClearAllItems = function ()
{
  shell.print("ToDoList::onClearAllItems");

  // pop-up a confirm dialog
  var confirmed = this.scene.confirm
     ("Are you sure you want to remove all the items?", "Remove ALL items?");
  if (confirmed.results)
  {
    // delete all items
    while (this.items.length > 0)
    {
      this.deleteItem(0);
    }
    this.displayCurrentItem();
  }
}

component.prototype.deleteItem = function (index)
{
  if (this.items == null || this.items[index] == null) { return; }

  this.items.splice(index, 1);
}

This is how it works:

The onPreviousItem function calls the displayItem function, passing the index of the previous item in the items array to the displayItem function.

The onNextItem function calls the displayItem function, passing the index of the next item in the items array to the displayItem function.

The onClearItem function prompts the user for confirmation that she or he would like to delete the item. If the users select yes, the deleteItem function is called, passing the index of the current item in the items array to the deleteItem function. Then, the displayCurrentItem function is invoked.

The onClearAllItems function prompts the user for confirmation that she or he would like to delete all items. If the user provides confirmation, the function loops through all items in the items array, calling the deleteItem function to delete the current item at each iteration. Upon completion, it invokes the displayCurrentItem function.

The deleteItem function first checks the index value that was passed to it. If the index is null, or if an item does not exist in the items array for the specified index value, the function exits without doing anything. Otherwise, if the index is not null and the item specified by the index exists in the items array, the splice method is invoked to remove the item.

Step 2: Adding JavaScript functions to the buttonsArea gadget

Next, you need to add JavaScript functions to the buttonsArea gadget to invoke the appropriate parent object function when a button is clicked.

Open the buttonsAreaGadgets.js file and add the following code:

// navigation commands
component.prototype.onPreviousItem = function()
{
  this.parent.onPreviousItem();
}

component.prototype.onNextItem = function()
{
  this.parent.onNextItem();
}

// remove item or items from the note list
component.prototype.onClearItem = function()
{
  this.parent.onClearItem();
}

component.prototype.onClearAllItems = function()
{
  this.parent.onClearAllItems();
}

Step 3: Associating JavaScript functions with the buttonsArea gadget

To call functions when buttons are clicked, edit the buttonsAreaGadgets.box file, as shown below in bold:

<gadget id="buttonsArea" language="jscript" 
    code="buttonsAreaGadgets.js" >
  <parts>
    <box:hbox id="prevNextButtons">
        <box:textButton  on:command="gadget:onPreviousItem();" 
            label="&#171; Prev Note" tooltip="Go to your previous Note."/>
        <box:hbox s:flex="1"/>
        <box:textButton  on:command="gadget:onNextItem();" 
            label="Next Note &#187;" tooltip="Go to your next Note."/>

    </box:hbox>
    <box:button on:command="gadget:onCreateItem();"  s:flex="1" 
        defaultButton="true" icon="../../theme/images/iconWrite.png" 
        label="Create To-Do Item" tooltip="Create new To-Do Note." />
    <box:hbox>
      <box:button  on:command="gadget:onClearItem();" s:flex="1" 
        icon="../../theme/images/iconClearItem.png" 
        label="Clear To-Do Item" tooltip="Remove this Note from your list."/>
      <box:button  on:command="gadget:onClearAllItems();" s:flex="1" 
        icon="../../theme/images/iconClearList.png" 
        label="Clear To-Do List" tooltip="Remove all Notes from your list."/>
    </box:hbox>
  </parts>
  <behavior>
    <reaction event="initialized" action="gadget:onInitialized();" />
  </behavior>
</gadget>

Step 4: Testing your application

After completing the previous three steps, you should be able to run the "To-Do List" application and:

In this chapter, you learned how to use scripting and event handling to make an application functional. Specifically, you learned how to:

To learn more advanced scripting and event-handling techniques, proceed to the next chapter, Chapter 5: Drag-and-Drop.