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.
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 typed into this area. We will use 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. Press the add button in the items List. The display will immediately switch to the editor page, with all the text erased. To verify that this code is really working, you can enter some text into the editor, and then 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. Try changing 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. Each change that you make is immediately integrated into your program running in the Emulator. Change the code back to

editor.setString("");

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.