Using Custom Events in Android Apps

There are two major concepts that provide a foundation for building scalable, native Android applications: loosely coupling requests and responses via events, and moving CPU intensive operations off the main thread. This post looks at events. It seems the online documentation on putting together all the pieces of  using custom events is sparse, at best. I’ll show you one example of how to put all the pieces together to create, dispatch and listen for custom events.  The end result is you will be able to decouple your application and make them more flexible and much less likely to break.

I’ve talked about event-based architectures before, and I think they are even more important when building applications for devices. They give you the ability to take into account processor delays and inconsistent internet connections. Between the three pieces of working with custom events described below you should be able to get up and running pretty quickly. I don’t go into much detail on what’s inside the various example as you can find those individual details by searching for them. It’s putting it all together that’s typically the hardest part.

The Event Class. Here’s an example of the content of an Event Class. I’ve taken this several steps further than most examples to include showing how to handle multiple Event types, which are accessed in this example as enums, and implementing multiple listeners. You can also extend your listeners with additional information of just about any type. In this example, I show using String’s for passing messages, but you could just as easily use custom Objects. This should give you a more realistic example of what goes into a commercial application.

	public class MapViewControllerEvent extends EventObject{

		private static final long serialVersionUID = 1L;

		public MapViewControllerEvent(Object source){
			super(source);
		}
	}

	public enum MapViewEvent{
		/**
		 * Connection to the internet has been lost.
		 */
		CONNECTION_LOST("Connection to the internet has been lost."),
		/**
		 * Connection to the internet has been restored.
		 */
		CONNECTION_RESTORED("Connection to the internet has been restored"),
		/**
		 * The LocationService has shutdown. Check logcat for errors.
		 */
		LOCATION_EXCEPTION("There was an unknown error related to the LocationService"),
		/**
		 * Indicates the LocationService is initialized and ready.
		 */
		LOCATION_INITIALIZED("The LocationService has been initialized. NOTE: it still may fail after a start() attempt."),

		private String description;
		private MapViewEvent(String description){
			this.description = description;
		}
	}

	public interface MapViewControllerEventListener extends EventListener{
		/**
		 * Indicates there has been a location change received from LocationService.
		 * @param event
		 * @param message
		 */
		public void onLocationChangeEvent(MapViewControllerEvent event,String message);
		/**
		 * Indicates whether or not device has internet connectivity.
		 * @param event
		 * @param message
		 */
		public void onConnectionChangeEvent(MapViewControllerEvent event,String message);
	}

	protected EventListenerList eventListenerList = new EventListenerList();

	/**
	 * Adds the eventListenerList for MapViewController
	 * @param listener
	 */
	public void addEventListener(MapViewControllerEventListener listener){
		eventListenerList.add(MapViewControllerEventListener.class, listener);
	}

	/**
	 * Removes the eventListenerList for MapViewController
	 * @param listener
	 */
	public void removeEventListener(MapViewControllerEventListener listener){
		eventListenerList.remove(MapViewControllerEventListener.class, listener);
	}

	/**
	 * Dispatches CONNECTION and LOCATION events
	 * @param event
	 * @param message
	 */
	public void dispatchEvent(MapViewControllerEvent event,String message){
		Object[] listeners = eventListenerList.getListenerList();
		Object eventObj = event.getSource();
		String eventName = eventObj.toString();
		for(int i=0; i<listeners.length;i+=2){
			if(listeners[i] == MapViewControllerEventListener.class){
				if(eventName.contains("CONNECTION"))
				{
					((MapViewControllerEventListener) listeners[i+1]).onConnectionChangeEvent(event, message);
				}
				if(eventName.contains("LOCATION")){
					((MapViewControllerEventListener) listeners[i+1]).onLocationChangeEvent(event, message);
				}
			}
		}
	}

Setup Listeners. Here’s how to set up the listener in your Activity. As an example, I called my Event Class MapViewController, but you can name it anything you like:

_mapViewController = new MapViewController(this);
_mapViewController.addEventListener(new MapViewControllerEventListener() {

	@Override
	public void onLocationChangeEvent(MapViewControllerEvent event,
			String message) {
		String eventName = event.getSource().toString();
		if(eventName.contains("EXCEPTION")){
			//TODO let user know
		}
		else{
			//TODO push UX change
		}

	}

	@Override
	public void onConnectionChangeEvent(MapViewControllerEvent event,
			String message) {
		// TODO Auto-generated method stub

	}
});

Dispatch Event. And, here’s how to dispatch an Event:

dispatchEvent(new MapViewControllerEvent(MapViewEvent.LOCATION_INITIALIZED),"Attempting to start location service.");

EventListenerList Class. For some reason, which I would characterize as a major oversite, Android does not currently provide a public EventListenerList Class. This Class makes creating custom events so much easier. However, the folks of the Firefly Client project for Android saved the day and were kind enough to create and post one publicly under an Apache License. The code is a bit dated, and shows some minor warnings when building Android v4, but it will work just fine. You’ll need to include a copy of this Class in your project to make things work.

So, that’s pretty much it. I hope this info helps you build better and more succesful projects.

References:

Java Tutorial – General Information about Writing Event Listeners

Firefly Client Android – EventListenerList Source Code

[Edited: June 7, 2012 – fixed various minor typos]

7 Critical Things to Know When Building Any Mobile App

This blog post builds on concepts proposed in an earlier post about not all mobile apps being created equally. If you are a developer who is in the process of migrating to mobile this post is for you. It’s intended to raise awareness of important items to consider in your requirements. My goal is to help you identify some of the major gotchas early on in the development process and improve your chances for success.

There are many more details to learn on the topics I’ve described below. The good news is that in the last few years the amount of deeply helpful documentation has expanded considerably. Where possible I’ve tried to include links related to each topic.

Touch-based Workflows. Recent research has shown that people use their smartphones more often than web apps, and they spend roughly 80% of their time on social media and games. Because of this and the fact that smartphones today are touch driven and not mouse driven, you have to take that into account in your user interface design. Touch implies many things including gestures and multi-touch. You can toss your old conceptions of user interface design based on desktops and tablets, and check out Android’s recommendations as well as Apple’s. My strong recommendation is to hire a UX designer to help you through building a user interface.

Mutliple form factors come with various screen sizes and densities. Long gone are the days of building for just three main browser types. Now you have to take into consideration iPhones, iPads, tablets, numerous different style androids as well as desktop and laptops. Android defines the following screen sizes and, as you can see, this is quite varied and smaller than a typical laptop or desktop. Those typically run 1024 x 768 or greater.

  • xlarge screens are at least 960dp x 720dp
  • large screens are at least 640dp x 480dp
  • normal screens are at least 470dp x 320dp
  • small screens are at least 426dp x 320dp

This is important to know because an app that looks good on an iPad may not look good, or display correctly, on the four inch display of a Motorola Atrix at 960 x 540. A button that looks correctly sized on one smartphone may look too big on another. A whopping 84% of all Android screens are what Android defines as normal size (>=  470dp x 320dp) and between either medium dpi (~160dpi) or high dpi (~240dpi). But, you still have to take into consideration other densities. I also recommend taking a look at new HTML5 browser-based technologies to help with addressing this problem, such as CSS media queries.

Inconsistent Internet. It’s a best practice to check if internet connections exist and gracefully handle HTTP requests when the internet is down, as I blogged about here.  Depending on your application and needs, you should also monitor whether or not a wireless connection can be made and then allow the application to switch to wireless where possible. Wireless also has the advantage of using less battery power.

Slower Connections. And, on a related note, you can’t always depend on 4G connections having consistent maximum download speeds. Over the course of a user session, the connection speed will vary widely and you should plan for that. I’ve been trying to find some stats on mobile internet quality world-wide, if they are out there they are hard to find. But, we’ve all experience spotty mobile internet coverage. Take this into account if you are transferring large amounts of data between your servers and your app. You should also consider detecting when the user is in an area of greater bandwidth and use that to download more data less often. Use loosely coupled and event driven architectures. Test app load times on various devices and around town and away from your office.

Less CPU Horsepower. While the latest generation of four core phones are certainly the most powerful phones yet. In general, applications and web pages will run slower on phones than they do on your development machine running a desktop browser. Take older generation phones into account because they are usually significantly slower than the newer phones. There are a few workarounds in HTML5 to help with this, in that done correctly they can offload rendering to the hardware. In native applications be aware of memory leaks because, remember, more memory usage means less battery life and applications that can run slower over time.

Support across multiple operating system versions. Remember on Android that the vast majority of users are still running v2.2 – v2.3.7 even though v4.x is currently shipping. You’ll have to do some research on your target market and find out what versions and type of phones they are using. You can’t support everything, but you can make educated guesses. Apple, on the other hand, has a significantly more limited selection of phones and tablets that you have to support, and they do a great job helping you support those.

There are some solutions that help with building cross-platform mobile apps, to go into more detail will take another blog post. Here’s a few: Adobe Flex, PhoneGap and Titanium. Keep in mind that the future of Flex, as a development platform, is being called into question after Adobe open sourced everything but the browser and desktop runtimes to the Apache Foundation. PhoneGap and Titanium offer what is now being called “hybrid” solutions where you can build an application in JavaScript, for example, and then compile that code for native deployments on Android and iOS.

Battery Life. Ah, battery life is last but certainly not least. Be aware of how battery intensive your application is and try to minimize battery consumption as much as possible. The Android online docs have a number of highly information articles on this subject. Smaller app footprint in memory means less battery consumption. Heavy CPU usage means more battery usage. Minimize GPS usage through smart algorithms to help preserve battery life.  Switch to 802.11 wireless connections where possible, since this requires less battery power than 3G and significantly less power than 4G.

So, there you go. I hope these suggestions help. If you have more suggestions based on your own experience please post a comment!

References:

Android Gestures

Android Optimize Battery Life

Android Screen Sizes and Densities

CSS media queries

Android UI Design

Android Model for Best GPS Performance

iOS User Experience

HTML5 Hardware Acceleration

Event-based Architectures for Adobe Flex

Adobe Flex Mobile: Detecting View and Orientation Change with Event Listeners

There will be a time when you want to have more control over the transitions between Adobe Flex Views, or detecting when the device orientation changes. For example, I recently built an app that had some event listeners that stayed persistent even when the user changed views. So, I needed to listen for the change event when using tabbed view navigator <s:TabbedViewNavigatorApplication/> so I could remove those event listeners and I did it like this:

this.addEventListener(Event.REMOVED_FROM_STAGE,tabChangeHandler);

I also had a need to detect when the phone was tilted. Yeh, in a perfect world everything in the app’s user interface would automatically adjust to the new state, but that isn’t always the case especially when building more complex apps. What I did was listen for orientation changes like this:

stage.addEventListener(StageOrientationEvent.ORIENTATION_CHANGE,stageOrientationChangeHandler);

Even if you are using some other Flex methodology for your mobile app, hopefully these examples will give you some ideas!

Event-based architectures for Adobe Flex

I had a number of interesting conversations in the last few weeks with developers who were experiencing life-cycle issues in their Flex applications, especially when their apps were run on slower machines…or even smart phones. They eventually had figured out that there were certain places in their apps where they had hardcoded properties into Classes. And, when those properties weren’t initialized in the right order…the code block which requested those properties failed with null exception errors.

Since Flex doesn’t have threads we are dependant on the linear execution of the code, which just so happens to include MXML, ActionScript and occasionally JavaScript. That means, for the most part, that your code is executed one line at a time, in the order in which it was written. 

To give you an example of how this can go wrong: if you are expecting an MXML custom component to be initialized with all its properties populated, you’ll get null value exceptions if this hasn’t occurred when you try and display that custom component. And, when you look at in the debugger you’ll be astonished to see all your properties are null or uninitialized in some way.

The bottom-line is if you don’t understand the life-cycle of your app you could end up severely beating your head against a wall for hours (or days) trying to figure out what’s going wrong. I don’t know why, but Adobe doesn’t talk much about life-cycle. To me, it’s mission critical to understand it. If you want to build anything more than very simple applications, I gaurantee you’ll eventually have to deal with it. Now fortunately there are some excellent articles out there. I highly recommend this excellent PDF by DevelopmentArc. Read it!

I also recommend making your architectures more loosely coupled, and event-based, rather than expecting immediate results. It may seem counter-intuitive at first. What it means is you can tie your code together based on something that happens in the future. And, your app will wait until that event occurs, then it will proceed as directed and not a moment sooner. 

So what am I talking about? For example, if you make a request to a REST Web Service, you can assign an event dispatcher to fire off when the response payload has been received and an event listener somewhere else in your app will wait for that event to occur. Sometimes servers take a while to respond, or maybe the internet was slow, or maybe the smartphone temporarily had a bad cell connection. When that happens, it will delay when your app recieves the payload. Or if you don’t receive a payload back after a certain period of time, you can throw an error event. All these types of scenarios can be gracefully handled with built-in ActionScript events as well as custom events that you build.

What’s the alternative? If your application immediately asks for a result and the response payload got delayed, guess what? You’re app will fail or throw an error.

I also want to throw one more bone of caution your way. Events themselves are subject to what’s called propogation. You may not want to, but you really do need to read as much about propogation as you can! Once you have a basic understanding of both application life-cycle and propogation you will be able to build much more robust applications. And in the long run that translates to more time you can dedicate to watching basketball, football, or whatever else you want to do with your new found “free” time.

So, my suggestion is make judicious use of custom events. Here’s a short article from Adobe on how to do it.

References:

DevelopmentArc – Understanding the Adobe Flex® 3 Component and Framework Lifecycle

Adobe – Dispatching Custom Events

Adobe – Event Propogation

Best Practices for ActionScript Event Listeners

I see a lot of incorrect instantiation of event listeners, and I’ve also done it wrong quite a few times myself, especially when coding really fast. Doing it right is easy and the following four steps could save you a ton of debugging time later. 

Step 1: First, create the object. In this case I’m creating a Timer object using the ActionScript flash.utils.Timer Class:  

var myTimer:Timer = new Timer(1000);

Step 2: Second, always add your event listeners before executing any of the objects methods. And always, always attach the event listener to an object. Simply calling an addEventListener without attaching it to an object means the listener will receive any events broadcast for that type of event. This can become a nightmare in projects that may have dozens or even hundreds of event listeners running and you have to debug a problem. 

//myTimer is the object to which we will attach the listener.
//timer is the type of listener we want to observe.
//And, timerHandler the function to call when the event occurs.
myTimer.addEventListener(“timer”,timerHandler);

Step 3: Third, now you can call the objects method. I’m going to call the start() method which will kick off the Timer: 

myTimer.start();

Step 4: Lastly, when you are done with an object, always remove the event listener. Leaving event listeners active when they aren’t needed can cause memory leaks. If an object is not removed, it is still registered and it will remain in memory. By removing the event listener, you’ll allow the garbage collector to eventually deallocate it from memory. 

    myTimer.removeEventListener(“timer”,timerHandler);

Why do things in this order? If you add your event listeners after calling a method, such as start(), you can potentially miss an event that occurs right before the event listener is created. By only calling methods after event listeners are created you eliminate the possibility of missing something and banging your head against the wall while trying to debug it under a heavy deadline. 

Here’s a complete Flex 4 sample app that you can play with to try it out: 

<?xml version="1.0" encoding="utf-8"?>
<s:Application xmlns:fx="http://ns.adobe.com/mxml/2009"
    xmlns:s="library://ns.adobe.com/flex/spark"
    xmlns:mx="library://ns.adobe.com/flex/mx">
 <fx:Script>
     <![CDATA[   

       private var myTimer:Timer;

       public function timerHandler(event:TimerEvent):void
       {
          var date:Date = new Date();
          textArea1.text = date.hours.toString()+
             ":"+date.minutes.toString()+
             ":"+date.seconds.toString()+
             ":"+date.milliseconds.toString();
       }   

       protected function start_clickHandler(event:MouseEvent):void
       {
           myTimer = new Timer(1000);
           myTimer.addEventListener("timer", timerHandler);
           myTimer.start();
       }

       protected function stop_clickHandler(event:MouseEvent):void
       {
           myTimer.stop(); 
           myTimer.removeEventListener("timer", timerHandler);
       }
  ]]>
 </fx:Script>

 <s:TextArea id="textArea1" x="15" y="70" width="270" height="20"/>
 <s:Button x="15" y="28" label="Start" click="start_clickHandler(event)"/>
 <s:Button x="103" y="28" label="Stop" click="stop_clickHandler(event)"/>
</s:Application>