PROG Mobile Java Application Development PROG Mobile Java Application Development Event Handling Creating Menus

8/28/2015Wendi Jollymore, ACES2 Review Recall that we created this application:

8/28/2015Wendi Jollymore, ACES3 Event Handling BlackBerry uses a Unicast Event model Each field can have only one listener Unlike desktop apps where a component can trigger multiple events If you try to register with more than one listener, you replace previous listener with new one Remember mobile devices have limited resources

8/28/2015Wendi Jollymore, ACES4 FieldChangeListener FieldChangeListener interface net.rim.device.api.ui.FieldChangeListener fieldChanged(Field field, int context) event handler method Field field –the field that triggered event int context – depends i.e. for custom fields can be used to send extra data Your screen class should implement this interface And obviously override fieldChanged() method Field.setChangeListener(listener) Registers a component with the event listener

8/28/2015Wendi Jollymore, ACES5 Add Event Handling Add event handling to your application: Reset should clear all fields Create and invoke a clearFields() method Reset all textboxes so that they’re empty Reset the date field to the current date “Assignment” should be selected in the radio button group

8/28/2015Wendi Jollymore, ACES6 Add Event Handling Submit button Create and invoke a submit() method Grab the grade and the max grade value from the text fields Both grade and max grade must be greater than or equal to 0 Calculate percentage grade / max * 100 Display in percentage label You can make this better with error handling, formatting, etc. See the notes for hints and tips

8/28/2015Wendi Jollymore, ACES7 Program Exit Recall that we never use System.exit() for exiting a mobile app MainScreen has close() and onClose() methods By default onClose() will call onSavePrompt() if screen is “dirty” Dirty means field data was changed We don’t need this functionality Default is to display the Save/Discard/Cancel dialog

8/28/2015Wendi Jollymore, ACES8 Program Exit public boolean onClose() { Dialog.alert("Exiting. Thanks!"); close(); return true; } Override onClose() method: Display an exit dialog alert Call close() method close() will pop the screen off the stack and, if stack is empty, will terminate the application

8/28/2015Wendi Jollymore, ACES9 Creating Menus net.rim.device.api.ui.MenuItem The class that models the menu items you click on to perform actions Implements Runnable interface This is used for creating threads or adding “activity” to classes Contains a run() method you must override Will run on main event thread, so this is where you put your event handling code for menu items Don’t do anything heavy in run() !!

8/28/2015Wendi Jollymore, ACES10 Creating Menus MenuItem constructor requires 3 things: Menu text Ordinal Where this item appears in the menu in relation to other menu items Higher ordinals near the bottom, lower ordinals near the top Priority What item is highlighted as default when menu opens Lowest priority item is highlighted

Creating Menus new MenuItem(“Reset”, 10, 20) new MenuItem(“Calculate”, 20, 10) 8/28/2015Wendi Jollymore, ACES OrdinalPriority

8/28/2015Wendi Jollymore, ACES12 Creating Menus To create a menu, override the MenuItem class Can use named inner class Can use anonymous inner class This is most popular Only use the menu item once! Default constructor should call super(menuText, ordinal, priority) To pass on the 3 values run() method contains event handler code

8/28/2015Wendi Jollymore, ACES13 Creating Menus private class ClearMenuItem extends MenuItem { public ClearMenuItem() { super("Clear", 10, 20); } public void run() { clearTextFields(); } }

8/28/2015Wendi Jollymore, ACES14 Creating Menus Next, you override MainScreen.makeMenu() method Adds a little more flexibility in app Invoked automatically when user does something to bring up a menu Overriding it allows us to customize the default menu makeMenu(Menu menu, int instance) Menu = the main menu you’re adding to instance = which context you’re using BlackBerry menus vary depending on context Where user clicked to get menu, if something was selected or not Constants define the different options

8/28/2015Wendi Jollymore, ACES15 Creating Menus makeMenu(), instance param, continued Menu.INSTANCE_CONTEXT menu displayed by clicking trackball (or touch menu button w/touch screen devices) usually context sensitive - just a few items off main menu that are relevant to object which had the focus automatically includes a "Full Menu" item so user can click this to get the full menu instead (Menu.INSTANCE_DEFAULT)

8/28/2015Wendi Jollymore, ACES16 Creating Menus makeMenu(), instance param, continued Menu.INSTANCE_CONTEXT_SELECTION same as above, but displayed when text is selected use for items that apply to selected/copied text Menu.DEFAULT menu is displayed when Menu key is pressed should contain all items in context menu plus items that apply to entire application Always call super.makeMenu() first inside method Keeps the default Close item and its functionality

8/28/2015Wendi Jollymore, ACES17 Creating Menus protected void makeMenu(Menu menu, int instance) { super.makeMenu(menu, instance); menu.add(new LoginMenuItem()); menu.add(new ClearMenuItem()); }

8/28/2015Wendi Jollymore, ACES18 Creating Menus You can also do this with anonymous inner classes instead of named inner classes A bit messier, but saves on resources for a mobile device protected void makeMenu(Menu menu, int instance) { super.makeMenu(menu, instance); menu.add(new MenuItem("Clear", 10, 20) { public void run() { clearTextFields(); } }); }

8/28/2015Wendi Jollymore, ACES19 Best Practices for Menu Implementation Always provide a full menu. Make sure that users can press the Menu key to open the full menu and to initiate an action when a menu item is highlighted. Make sure that users can also hold the Menu key to open the dialog box for switching applications. For the default menu item, use the menu item that users are most likely to select. Place the default menu item and other common menu items in the middle of the menu.

8/28/2015Wendi Jollymore, ACES20 Best Practices for Menu Implementation Verify that the order of menu items is consistent with the order of menu items in other BlackBerry device applications. Group menu items according to common usage or common functionality, and where possible, test your groupings with users. Insert separators between menu item groupings. Do not place menu items for conflicting actions close together. For example, do not place a "Delete" menu item beside an "Open" menu item.

8/28/2015Wendi Jollymore, ACES21 Best Practices for Menu Implementation Always include the "Switch application" and "Close" menu items. Place these menu items at the end of the menu. If you use standard components, these menu items are included automatically. Guidelines for menu labels: Use concise, descriptive labels that are no longer than 12 characters. If a label is too long, an ellipsis (...) appears to indicate that the text is truncated. Use verbs for labels. Use title case capitalization for labels.

8/28/2015Wendi Jollymore, ACES22 Best Practices for Menu Implementation Guidelines for menu labels, continued: Use an ellipsis in a menu item label to indicate that users must perform another action after they click the menu item. For example, if users click the Go To Date... menu item in the calendar, they must specify a date on the screen that appears. Avoid using symbols such as an asterisk (*) in labels.

8/28/2015Wendi Jollymore, ACES23 Add Menus to App Add menu items for “Reset” and “Submit” to your application. Hopefully you paid attention to instructions earlier Call your methods from earlier in the run() method E.g. to clear fields and calculate percentage

8/28/2015Wendi Jollymore, ACES24 Exercises and Homework Do Assignment #2 It’s on the web