Adding commands

---

The To Do list is still only a skeleton at this point. There is a list page, and an editor page, but no way to add the text in the editor to the list. We will now add Commands, which are the way that MIDlets can execute code and move from one screen to another based on user responses.

1. Select the List named items in the Parts Tree.
2. Press the Display this List button to show the list in the Emulator. The Emulator should now show the screen with a title of "Things to Do".
3. On the Mobile Devices Palette, click the mouse button on the 'Commands' tab. There is only one item on the Commands tab, the Command. Drag a command to the List named items in the Parts tree. Note that a Command cannot be dragged directly to the Display node. When a Command is dropped, it immediately adds three items to the tree: the command (with a name similar to Command1), and a Code before and Code after area.
4. The Command1 page should be showing in the Composer. Change the Command label to 'add'. Note that the command in the Emulator is updated as well as the display in the Parts tree.
5. When the user presses the 'add' command, we want to switch the display to the editor. In the then goto choice box on the bottom right of the composer, choose editor. In addition, we would like the editor to be cleared of text before it is displayed. To do this, we will create the code in the Code before area of the Add command.
6. Choose the Code before node in the Parts tree. A new Code area appears, with the title of Code before. Any valid java code can be entered into this area. There are several different ways you can enter code into a code area. We will start by using the Code Sourcerer to create the code we want.
7. Press the Code Sourcerer button in the Property sheet. This should be directly underneath the contextual help.
8. A dialog appears with a list of choices. We want to clear the text in the editor screen. If it is not already selected, choose the first item, labelled 'Change a property of an existing part...'. Press Next.
9. The Code Sourcerer now asks you which part you would like to change. The list it generates is a dynamic list of all the parts currently in the MIDlet which may be changed. Choose 'editor'. Press Next.
10. The Code Sourcerer now presents you with a list of the editor TextBox's properties that can be changed. Choose the first choice, 'Change text of Text Box...'. Press Next.
11. The Code Sourcerer now asks you where to get the new text for the TextBox. We want to simply erase the current text, so choose the first option and leave the text field to the right blank. Press Done.
    The following code will appear in the code area.

try {
editor.setString("");
}
catch ( IllegalArgumentException excpt0 ) {
}

Now you can test the code that you have just created. The Emulator should still be showing the items List titled "Things to Do". Press the add button at the bottom of the Emulator. The Emulator will immediately switch to the editor page titled "Add an Item", with any text that was there erased. To verify that this code is really working, you can enter some text into the editor. Next switch back to the items page by selecting it in the Parts tree and pressing the Display this List button and then pressing add again. You will go to the "Add an Item" editor page again, but the text that you had entered is erased.

Next we will try changing the code by hand. Change the code in the Code before area of the add button to

editor.setString("Hello world!");

and press the add button in the items List. The "Add an Item" page now starts off showing the new "Hello World!" text. As you can see, each change that you make is immediately integrated into your program running in the Emulator, without the need to save and compile. This feature is known as Execution-on-the-fly.

In addition to using the Code Sourcerer and typing in code by hand, you may also use Simplicity's code completion feature called the Sourcerer's Apprentice in a code area. Change the code to

editor.

With the cursor after the '.' on this line, press control-space. A new window called the Sourcerer's apprentice will appear. This window has a list of all the methods which you can use with the TextBox class (which editor is an instance of). Choose 'setString' from the list of Methods on the left. Note that information about this method is displayed at the bottom of the window, and the text setString("") appears in the box at the bottom. Press Ok and that text will be added to the Code area for you, so the line now reads

editor.setString("")

Note that if you try to verify that this code is working, the Java Console will appear, with an error message that looks something like "Syntax error in Code before of add of items on line 2: Missing ';' : found EOF" That's because we didn't put in the ; to end the Java statement. With Simplicity, you can test your code as you write it. Add the ; to the end of the line to continue.

We will now create the code to add the item from the editor to the List.

12. Drag a command from the Mobile Devices Palette to the TextBox named editor in the Parts tree.
13. Change the label to Ok.
14. Change the Command type to 'Ok' by choosing that from the drop down list. The Command Type is a way that the author of a MIDlet can signal to the MIDP device the specific type of command which is being used.

If the user triggers the Ok command, the text in the editor should be added to the To Do list, and then the display should be switched back to the To Do list.

15. Select the Ok command in the Parts tree. In the then goto choicebox on the bottom right of the composer, choose items.
16. Select the Code before of the Ok command in the Parts tree
17. Press the Code Sourcerer Button. Choose 'Change a property of an existing part...'. Press Next.
18. Choose 'items'. Press Next.
19. The Code Sourcerer now presents you with a list of the items List's properties that can be changed. Choose the first choice, 'Add item to end of List...'. Press Next.
20. The Code Sourcerer now asks you where to get the text for the new List Item. We want to get the text from the editor, so choose the second option 'Another part' and then select editor from the dropdown list. Press Next.
21. List items may have images associated with them; in this case we don't want an image. Choose 'Don't include an image'. Press Done.

The following code should have appeared in the code area.

items.append(editor.getString(),null);

Test this code by typing something into the editor and then pressing the Ok button in the editor. The emulator will display the list, with a new item added to it. The box around an item indicates the 'cursor' in the emulator.

The editor you have just created is missing a crucial command: a cancel command. This command should let the user decide not to add a new item after all.

22. Drag another command to the editor TextBox in the Parts tree. This command may be below or above the Ok command.
23. Change the Command label to Cancel and the Command type to Cancel.
24. This command does not need to execute any code; simply have the command switch to the items display by selecting items in the then goto checkbox.

Now the editor has both an Ok and a Cancel Command. The only command missing is one to exit the To Do MIDlet.

25. Drag another Command to the List named items in the Parts tree.
26. Set the Command Label and Command Type to 'Exit'.
27. This command will exit the Midlet. It will not go to another display, but will need to execute code.
28. Select the Code before area of the Exit command.
29. Press the Code Sourcerer Button. Choose 'MIDlet control operations...'. Press Next.
30. Choose the last option, 'Exit this MIDlet'. Press Done.

The Code Sourcerer will create the following lines of code.

try { destroyApp(true);} catch (Exception e) {}
notifyDestroyed();

This will run any code in the destroyApp method of the MIDlet, then notify the MID-device that the MIDlet is ready to be destroyed.

Pressing the Exit button in the emulator will destroy the instance of your MIDlet running in the emulator and show the copyright screen you saw when you started. To restart the MIDlet, choose Reload selected Midlet from the MIDlet menu of the Composer.

You have now finished designing your To Do list.

You may view the code that Simplicity will create by choosing View Code from the File Menu. This will open the Code Viewer window, which will show you all the code which Simplicity will generate.

Finally Save your work by choosing Exit from the File menu in the Composer. Choose Save All to save your changes.