Zebra works on mobile devices as is. This is very essential difference between other WEB based mobile frameworks and Zebra: “Zebra uses the same code base for mobile and none mobile devices.” You don’t find special mobile Zebra edition. Everything what developers need is still Zebra. The same packages, modules, classes and API for mobile devices, PCs, laptops, tablets etc.

Zebra abstractions, easy OOP coding and the manner Zebra UI is implemented makes Zebra less dependent from a browser context and more like to native mobile application development. Remember Zebra is rendered from scratch on HTML Canvas element. UI is fully customizable, extendable, controllable.

Writing Zebra mobile application

WEB development for mobile devices requires some specific things have to take in account: touch and multi-touch event handling, adding special meta tags into html to make application closer to native platform and so on. Zebra tries to do things smoothly. Some extra simple activities are still required from developers.

Mobile application HTML template

HTML page that is supposed to be used on mobile devices has to include two special meta tags. In general Zebra mobile application HTML template should look as follow:

<!DOCTYPE html>
<html>
    <head>
    <!-- 
       special meta tags should be added into HTML that is supposed to be 
       loaded on mobile devices 
    -->
 	<meta name="viewport" 
              content="width=device-width,initial-scale=1.0, user-scalable=0"/>
	<meta name="msapplication-tap-highlight" content="no" />

   <!-- reference to Zebra JavaScript code  -->
	<script src='http://repo.zebkit.org/latest/zebra.min.js'type='text/javascript'>
    </script>

   <!-- Zebra application "ready" section -->
	<script type='text/javascript'>
            zebra.ready(function() {
               // write zebra code here
               ...
            });
	</script>
   </head>
<body> ... </body>
</html>

Full screen mode

One more thing developers usually should do on mobile platform is aligning application size to occupy the full browser window size. Do it as follow:

// create canvas
var canvas = new zebra.ui.zCanvas();

// fill it with UI elements
canvas.root.setLayout(new zebra.layout.BorderLayout());
canvas.root.add(zebra.layout.CENTER, new zebra.ui.Button("Test"));
...

// force canvas to occupy full browser window size
canvas.fullScreen();

Mobile platforms scrolling

Scrolling is implemented on the level of Zebra UI components. Use “zebra.ui.ScrollPan” panel as a container for an UI that has to be scrolled. For instance let’s create long list and make it scrollable:

// create canvas and set border layout for root panel
var r = new zebra.ui.zCanvas(150, 250).root;
r.setLayout(new zebra.layout.BorderLayout());

// create list UI component
var list = new zebra.ui.List();

// add 100 items to the UI list component
for(var i=0; i<100; i++) {
   list.model.add("List item " + i);
}

// add scroll panel to root panel and add 
// list to the scroll panel  
r.add(zebra.layout.CENTER, 
      new zebra.ui.ScrollPan(list));

That is all. It doesn’t matter whether it is run on a mobile platform or on PCs. What does matter is reproducing by Zebra scroll panel behavior that is natural and standard for most of mobile platforms:

  • Scrolling by touch move event. Content has to be scrolled by moving your finger in vertical or horizontal directions
  • Scrolling has to be inertial. The speed of vertical or horizontal scrolling has to be dependent on how fast user move his finger
  • Auto hide scrollers UI elements. Scrollbars elements have to appear only during scrolling

All these features are available in Zebra out of box. Developers have to do nothing. Zebra itself configure scroll panel behavior to follow the rules listed above.

Touch events handling

To make development more easy and less dependent from platform Zebra maps touch events into appropriate mouse events. Pay attention that is not the same to how it is done by mobile browsers. Mobile browsers emulate touch events via mouse events, but this emulation exposes noticeable differences between real touch events handling and mouse emulated touch events handling. Zebra does it correct and does it without introducing special touch event listeners and events.

The mapping between touch and mouse events are shown in the table below:

Touch event Corresponding mouse event
touch start mouse pressed
touch end mouse released, if no touch move event has occurred between touch start and end events mouse clicked event will be also generated
touch move mouse drag started, mouse dragged, mouse drag ended events sequence

The code below is ready to handle touch events on mobile devices or mouse events on PCs:

// instantiate UI panel that listens mouse or touch events 
var p = new zebra.ui.Panel([
    // touch start event or mouse pressed event handler
    function mousePressed(e) {
      ... 
    },

    // touch end event or mouse released event handler
    function mouseReleased(e) {
       ...
    },

    // touch move event or mouse dragged event handler 
    function mouseDragged(e) {
       ...
    }
]);

To restrict the code above to handle only single (one finger) touch events add simple condition to an even handler. The condition works if the number of active touches (fingers you keep on the screen) equals to one. For instance:

// instantiate UI panel that listens mouse or touch events 
var p = new zebra.ui.Panel([
    // touch start event or mouse pressed event handler
    function mousePressed(e) {
        // test if this is the single (one finger) touch
        if (e.touchCounter == 1) {
           ... // handle
        }
    }
]);

The code above is also applicable for handling mouse events on PCs, since “touchCounter” field is always set to “1” in this case.

Mouse/touch events handlers get an “zebra.event.MouseEvent” class instance as its parameter. The object describes a mouse event has occurred. Except standard fields described in “Event handling” chapter it provides number of touch screen specific fields. Find its explained in the table below:

Mouse event class field Description
touchCounter indicates how many touches are active at the current moment. In the case of real mouse events the field is never greater than "1"
touches array of all touches that are active at the given moment
touch the touch event description that is processed by the given event handler
touch.direction touch move event direction. Can have one of the following values: zebra.layout.TOP, zebra.layout.BOTTOM, zebra.layout.LEFT, zebra.layout.RIGHT
touch.identifier unique touch identification. It helps to differentiate multi touch events from each other
touch.dx,touch.dy touch horizontal and vertical position delta since previous touch move event

Multi-touch events handling

Handling multitouch events practically has no differences from single touch or mouse events handling. Zebra processes every particular touch individually. The picture illustrates how mouse pressed and released events are triggered when we touch screen with one finger then with second finger and un-touch it in reverse order:
touchevents

As you can see mouse pressed and mouse released handlers are called correspondently to a number of occurred touch and un-touch events.

Let’s write simple application to draw lines on the screen with many fingers:

eval(zebra.Import("ui", "layout"));

var z = new zCanvas(), root = z.root;
if (zebra.isMobile) z.fullScreen();
root.setLayout(new BorderLayout());

root.add(CENTER, new Panel([
    function mouseDragStarted(e) {
      if (!this.paths) this.paths = {};
      this.paths[e.touch?e.touch.identifier:1]=[e.x,e.y];
    },

    function mouseDragged(e) {
      this.paths[e.touch?e.touch.identifier:1].push(e.x,e.y);
      this.repaint(); 
    }, 

    function paint(g) {
       if (this.paths) {
          g.setColor("red");
          g.lineWidth = 3;
	  for(var k in this.paths) {
	     var path = this.paths[k];
    	     g.beginPath();
    	     for(var i=0; i < path.length; i+=2) {
    	        g.moveTo(path[i],   path[i+1]);
    	        g.lineTo(path[i+2],   path[i+3]);
    	     }
    	     g.stroke();
    	  }
       }
    }
])); 

Mobile keyboard input

Mobile devices provide own specific way of inputing text. It is impossible to control or customize it from WEB context. That brings to the situation when only WEB native text input element can be safely used. Zebra has two special UI text input components that have to be utilized for text inputing. These components are actually zebra wrappers around native one:

 

var z = new zebra.ui.zCanvas();
z.root.setLayout(new zebra.layout.BorderLayout());

// add native text input component into zebra layout
z.root.add(zebra.layout.TOP, new zebra.ui.HtmlTextField());

Examples of Zebra mobile applications