TabletsAndMojo

From WebOS101

Contents 1 Basics 2 Detecting Tablets 3 Disabling Initial Keyboard Focus 4 Button to Open FilterField in FilterList 5 Limiting Width 6 Tuning Lists

Basics

Mojo apps can run on tablets, but there are some considerations. By default, apps run in "Mojo Compatibility Mode" -- a phone-sized window with a virtual gesture area (which only generates "back" gestures) and a button to open the on-screen keyboard. An app which adds

"uiRevision": 2

to its appinfo.json file can use the full screen, but loses the virtual gesture area and keyboard button. Such apps must provide a "back" button wherever needed, but only when running on tablets.

Detecting Tablets

Tablets have three important differences from previous webOS phones

• larger screen size
• no hardware keyboard
• no gesture area

Each of these differences needs to be handled differently (in general).

As of mid-August 2011, each of these characteristics separates tablets from phones. However, the introduction of a "slab phone" (no hardware keyboard) would change that.

The constants in Mojo.Environment.DeviceInfo tell you two of these:

• Mojo.Environment.DeviceInfo.screenWidth (and screenHeight) tell you the screen size
• Mojo.Environment.DeviceInfo.keyboardAvailable tells you whether there's a hardware keyboard

The lack of a gesture area is most important -- but the OS gives no indication of whether a device has a gesture area or not.

Disabling Initial Keyboard Focus

The lack of a hardware keyboard is straightforward to deal with. By default, Mojo gives keyboard focus to the first text field in a scene. This results in the on-screen keyboard popping up, even if the user doesn't intend to enter text. Thus, most scenes containing a text field should have the following code in the setup method:

if (! Mojo.Environment.DeviceInfo.keyboardAvailable && this.account.domain)
	this.controller.setInitialFocusedElement(null);

Button to Open FilterField in FilterList

Mojo FilterLists are very useful, but there is no indication to the user that he/she can "just type" to filter the list. On tablets, there's no default way to use the filter at all. Adding a "Search" button eliminates the need for hints and FAQs, and enables filtering on tablets.

Typically, this button will be a "command" button in the Command Menu. There's even a standard "search" icon available:

this.commandMenuModel = {visible: true, items: [{icon: "search", command: "search"}]};
// Currently, all models without gesture areas also lack keyboards.
if (! Mojo.Environment.DeviceInfo.keyboardAvailable)
	this.commandMenuModel.items.push({label: $L("Back"), command: "back"});
this.controller.setupWidget(Mojo.Menu.commandMenu, {}, this.commandMenuModel);

Your scene must have a handleCommand method to respond to command buttons. On tablets, there's no "back" gesture (if your app is set uiRevision: 2) to cancel search, so typically you'll want the search button to toggle the FilterField open or closed. The FilterField widget can't tell you whether it's open or closed, but its widget assistant can:

FaqAssistant.prototype.handleCommand = function (event) {
	var ff, ffAsst;
	try {
		switch (event.type) {				
			case Mojo.Event.command:
		        switch (event.command) { 
					case "search":
						ff = this.controller.get("faqList").down("div[x-mojo-element=FilterField]");
						ffAsst = ff._mojoController.assistant;
						if (ffAsst.filterOpen)
							ff.mojo.close();
						else
							ff.mojo.open();
						break;
 
					case Mojo.Menu.helpCmd:
		        	case "back":
		        		event.stopPropagation();
		        		this.controller.stageController.popScene();
						break;
				}
				break;
 
		    default:
		    	break;
		}
	} catch (error) {
		Warn.bannerError("debug", Object.inspect(error), "caught error in FaqAssistant.handleCommand");
	}
};

Limiting Width

Mojo accommodates a range of screen sizes, but does not deal gracefully with 10" screens. Generally, a two- or three-column layout is best on that size screen, and Mojo has no provision for that. With its focus on scrolling lists, most Mojo apps accommodate a taller screen. Adding the following to your stylesheet will constrain your app to 600 pixels wide. System scenes such as the File Picker will not be changed.

html {
	background-color: black;
}
 
body, .palm-header, .palm-menu.command-menu, .palm-menu-panel {
	max-width: 600px;
	margin-left: auto;
	margin-right: auto;
}
 
.palm-dialog-box {
	max-width: 320px;
	left: 50%;
	margin-left: -160px;	
}

Tuning Lists

A larger screen can display more items in a List or FilterList. You may need to adjust lookahead and renderLimit to avoid dropouts. You need to test on real hardware to determine what works best for your app, but the following works well for me:

lookahead: 35 + Mojo.Environment.DeviceInfo.touchableRows,
renderLimit: 30 + Mojo.Environment.DeviceInfo.touchableRows,