Posts Tagged ‘android’

Creating a contact with multiple fields in Android

For the impatient: skip the article, download the code.

Recently, when writing a physician directory for the Canton of Geneva, I wanted to include a feature for adding a new contact. That is, I wanted a button that would pop up the “Add a new contact” screen, with various fields (such as phone number, postal address, and email address) already filled in. Piece of cake, right?

Adding a contact in the physicians app.

Adding a contact in the physicians app.

Unfortunately, it turns out that the Android docs and Stack Overflow are pretty bereft of clear, concise instructions for creating a contact with multiple fields of various types, e.g. work phone, mobile phone, or home fax (if such a thing still exists).

Plus, the entire ContactsContract changed in API level 11 (Honeycomb), meaning that anything written for ICS or Jelly Bean wouldn’t work in Gingerbread, and vice-versa. Oh joy.

Luckily for you — assuming you stumbled across this post after a frustrated trip to Google — I’ve written a helper class to do all the heavy lifting. It provides a simple, fluent API that works for Android version 2.1 (Eclair) through 4.2 (Jelly Bean), and it’s open source.

You create a contact like this:

Intent intent = new AddContactIntentBuilder("Joe Blow")
    .addFormattedAddress("123 Fake Street, Springfield USA",
        StructuredPostal.TYPE_HOME)
    .addPhone("555-867-5309", Phone.TYPE_HOME)
    .addPhone("555-123-4567", Phone.TYPE_WORK)
    .addPhone("555-987-6543", Phone.TYPE_FAX_WORK)
    .addEmail("joe.blow@gmail.com", Email.TYPE_HOME)
    .addEmail("joe@blow.com", Email.TYPE_WORK)
    .build();

startActivity(intent);

And here’s what this code produces, in both Jelly Bean and Gingerbread:

Adding a contact in Jelly Bean and Gingerbread.

Adding a contact in Jelly Bean and Gingerbread.

Happy contact creating!

Download or fork the code from GitHub.

KeepScore version 1.2: more style, more substance

KeepScore v1.2

I had always thought of KeepScore as a fairly simple app. Functional, yes. But beautiful? Meh.

It’s a counting app. Counting apps only have to do one thing right, and that’s count. This is not brain surgery, people. Just keep it simple, and you’re already 95% of the way there.

A few weeks ago, though, I decided to make KeepScore my guinea pig for trying out some new design elements from the “Holo” theme, introduced in Android 3.0. At the same time, I also added some fit-and-finish features that were sorely needed, giving the app a much more coherent feel.

The result is KeepScore version 1.2, probably the biggest update I’ve ever written for the app. It looks and functions so differently now, I feel like I barely recognize my own app.

What I like most about this update, though, is that it adds a fresh coat of paint without subtracting anything from the usability. In fact, I think KeepScore is actually much easier to use than it was before, to the point where I feel a little embarrassed for having bragged about it in previous posts.

New home screen

The new home screen is a design I’ve been wanting to do for awhile. Here’s a side-by-side comparison of the old and new looks:

Out with the old, in with the new.

The new design basically takes the “Load Game” screen and transplants it onto the welcome screen. I find it’s a huge improvement. There was a ton of wasted space with the old design, and plus it took two clicks to get to your saved games. Now everything the user needs is front and center, without sacrificing any usability or app branding.

I also wanted to make sure that the new design wasn’t so cluttered that it would confuse first-time users. Their experience is still pretty streamlined: there’s a big “New Game” button the size of a barn that you can’t possibly miss.

Big gray squares. Your thumb is drawn to them.

The new home screen also makes use of the “Action Bar” paradigm, which was introduced in Android 3.0 and back-ported thanks to the wonderful Action Bar Sherlock library.

The in-game view

In-game, not a whole lot has changed. If it ain’t broke, why fix it? All I added was a very small graphical flourish:

Never change, KeepScore. Never change.

Did ya miss it? The last score in the score history now has a “fade-out” gradient, to indicate that the list has been cut off at the bottom.

This is to solve a common problem I heard from users, which is that they could never remember whether the list was ordered top-down or bottom-up. Hell, I kept forgetting myself! So hopefully this subtle change will make that clearer.

Rematch button

This is something I struggled with for a long time. In early versions of KeepScore, I had a “Reset” button, which prompted the user with “Overwrite game or start new game with same players?” Knowing that users don’t read anything, though, I was unsatisfied with this dialog.

The old, confusing dialog.

In later versions, I replaced it with “Reset” and “Copy Game”:

“Reset” and “Copy Game” buttons.

Now I’ve combined them both into “Rematch”:

New “Rematch” button.

What I realized about “Reset” and “Copy Game” is that they’re an inelegant solution to a common problem. 99% of the time, if you’re still using the app after the game is over, it’s because you want to start a new game with the same players. However, I didn’t want users to overwrite their old scores, because then they’d lose all their history from the previous game. Hence the option of copying the game before resetting it.

“Rematch” captures this concept much more succinctly than “Copy Game” and “Reset.” And plus, it makes it more difficult for users to shoot themselves in the foot, i.e. by overwriting their scores.

Unfortunately I can’t take the credit for this idea. I borrowed it from Rounds, which is a pretty slick round-based score keeper that was actually originally built on KeepScore’s source code. When I saw the “Rematch” button in that app, I slapped myself on the forehead and wondered how I’d never thought of it.

Edit Players

This is a pretty nifty new feature. In the previous versions, I had an “Add Player” button and a “Shuffle” button, but there was no way to manually reorder players or delete players.

Every day I’m shuffling, and adding, players.

Now all of that is handled in a separate “Edit Players” screen, which makes it a breeze to change players mid-game. You can even touch and drag to get the order exactly right.

Clearly, Storm Eagle should go after Mega Man.

This screen also makes it easier to change players’ names. Previously, the only way to do that was to long-press on a player’s name, which is kind of low on discoverability. But hopefully the button with the pencil icon is a lot easier to figure out.

A tip of my hat goes to Carl Bauer for the drag-and-drop list implementation.

History chart

One occasionally-requested feature was a line chart to show the players’ scores over time. Well, ask and ye shall receive:

Fact: nerds love data. And gamers are all nerds.

Players’ scores are on the Y axis, rounds on the X axis. It’s probably useless for any non-round-based game, but kind of neat nonetheless.

I realize the history chart is probably the most unpolished out of the new visual features I added. The colors are pretty bland, and it’s all very MS Paint-esque, because Android has no native graphing library, so I had to whip this up from scratch. But I’m not too concerned, since most people don’t bother going into the History anyway. And for those that do, I think it’s a nice little feature.

Other new features

Besides all the UI changes, I also added some new functionality:

  • Backup/restore. Back up your games to an XML file on USB storage, and load them later. Duplicates are handled automatically based on unique game IDs.
  • Undo/redo. Self-explanatory. Any action in-game can be undone or redone, i.e. scores subtracted, scores added, etc.
  • Better German translations. Germany is the Mecca of modern-day board gaming, so this has got to be worth something. The app is already available in French and Japanese.
  • Dropped support for pre-Eclair devices. Android 1.5 and 1.6 only account for 0.5% of the user base, and the new backup/restore feature required some XML libraries from Eclair. Sorry, Cupcake and Donut! You were delicious while you lasted.

So there you have it. KeepScore v1.2 has a fresh new look, a better UI, and it’s still free and open-source. So go grab it from the Google Play Store!

CatLog jives with Jelly Bean, goes open-source

CatLog

CatLog is an app I’ve always been immensely proud of. I wrote the initial version in the span of a weekend, and yet it grew to be my second-biggest Android app, after the now-defunct Pokédroid. Even though it’s a pretty esoteric app, and nobody except developers will find it very useful, I’m glad I could contribute something valuable to the Android community and help make Android development a bit less of a pain. It’s cool to see fan-made instructional videos on YouTube and all the forum posts where people say, “Just download CatLog and send me a log report.”

But lo, all is not well in CatLog Land. As of the newest version of Android (4.1 Jelly Bean), Android apps can no longer read each other’s logs using the READ_LOGS permission. You’re limited to your own logs, unless you’re a system app or you gain root privileges. Uh oh.

Now, this is a defensible position on Google’s part. After all, there was a pretty high-profile security hole found in the Facebook Android SDK due to developers carelessly writing sensitive information to the system log. And in general, most apps don’t need to read each other’s logs, so the change is understandable. Stay in your own sandbox and all that.

This change is going to have a big impact on certain varieties of apps, though. Not only will it affect log-reading apps (like CatLog and aLogcat), but also apps that rely on log-reading in some way. For instance, you can say goodbye to the various “app lock”-type programs that rely on reading the system log to determine when other apps are being launched. If you don’t believe me, check out the permissions page for those apps. See where it says “read sensitive log data”? That’s the death knell for these types of apps, unless somebody figures out a smarter way to detect when another app is launched. (My own AppTracker works in the same way. So it’s toast as well.)

So what does this mean for CatLog? Well, in the future, it means it will only work on rooted phones, which basically limits its appeal to developers and root-happy techies. Until now, it had also come in handy for end users, since it gave them a way to easily submit bug reports (in cases where, for whatever reason, the default reporting mechanism wasn’t available). But starting with Jelly Bean, CatLog will require root access, which means it’s basically worthless for Joe Android User now.

So given that this is more or less CatLog’s swan song, I’m taking a pretty radical step with it. I’m open-sourcing it. Yep, CatLog is now free to remix and re-use, released under the ultra-permissive WTFPL license, just like my other apps.

Why such a permissive license? Well, because I honestly don’t care. CatLog was always a free app, and although I’m grateful for the nice pocket change I make from the donate version (about $20 per month), I doubt open-sourcing it will affect the donations much, and anyway the app was never about making money for me. So there’s really no reason to lock down the source code. I mean, yeah, there are already some copycat apps out there that stand to benefit, but they’re not really doing anyone any harm hanging out in sixth or seventh place in the search results. CatLog’s main advantage is its reputation on the Google Play Store.

On the other hand, if you do want to re-use CatLog’s code, the only thing I ask for is attribution. Sure, the WTFPL doesn’t require it, but this is just one of those “don’t-be-a-jerk” requests.

I have another strong reason for wanting to open-source CatLog: I’m bored of it. Frankly, I haven’t been able to give it much attention lately, because I think 99% of its useful features are finished, and everything that’s left is just flourishes and fine-tuning. It needs a facelift and probably some tweaks to the filter syntax, but with the enthusiasm I’ve shown for the app lately, I’m obviously just not the one to do it.

Also, I find myself turning away from Android development in general. I started writing Android apps when the system was still in its infancy, with only two phones available – the HTC Dream and the Magic. I found it a lot more fun when Android was still simple and untamed, when the market wasn’t flooded with glitzy, polished apps all competing for users’ mind-share. Back in those days, you could even write a simple Pokémon app with an ugly UI and people would love you for it. Development was easy, and the exposure was fun.

Nowadays the Play Store is much more crowded, and Android development is more difficult in general, what with supporting hundreds of devices with multiple form factors (including tablets), and multiple Android versions stretching from 1.5 Cupcake to 4.1 Jelly Bean. The APIs have grown incredibly complicated, and I can’t count the number of times I’ve discovered bugs that only appeared on a certain Android version or on a certain phone. It’s a huge headache trying to maintain all this compatibility, which is why I still haven’t updated any of my apps to the new “Holo” theme from ICS.

However, my lack of enthusiasm shouldn’t limit CatLog’s potential. When you’ve lost interest in a software project, I think it’s your duty to make it open-source, so that somebody else has a chance to grab the baton and run with it. And that’s exactly what I’m doing with CatLog. So if you have any features or bugfixes you’d like to write, fork me on GitHub and go nuts!

A slight makeover for KeepScore

Recently I went to the trouble of de-uglifying the “Load Games” screen for KeepScore. The whole screen is just one big ListView, so taking a cue from my own recent post, I added some fast scroll sections divided by date. I think the effect is more pleasing to the eye, and it also makes it easier to navigate through your past games.

The old version of the UI is on the left, and the new one is on the right:

There. Isn’t that much nicer? The important information (i.e. the player names) pops right out, whereas the other stuff is banished to a light gray subtitle. The icons to the left give the user the feeling that each row refers to some tangible object, saved somewhere, and the checkmarks on the right are useful for doing bulk-delete operations.

Here are some more screenshots:

I’m especially proud of the little row of buttons there at the bottom. They pop up when any boxes are checked, and gracefully recede when the boxes are unchecked, similar to the Gmail app. It was really tough to get them to actually hover over the ListView as they animate upwards, and then have the ListView concede screen space once the animation is complete. I report with some satisfaction that even the Gmail app (version 2.3.5.2) doesn’t do this – when the animation starts, the ListView jumps upward, leaving an awkward little white space for the buttons to pop over.

Awkward white space in Gmail

No awkward space in KeepScore

Overall, the new UI is cleaner, prettier, and more usable. And the code is open source for anyone who wants to borrow it.

Spruce up your ListView by dividing it into sections

If there’s one piece of the core Android framework that every Android dev struggles with, it’s ListView. ListView is incredibly flexible and complex, and you’ll probably find you need it more than once in any decent-sized app. If you haven’t already slammed your keyboard and screamed at ListView before, you probably haven’t been writing Android apps very long. It’s so important, Google even had a whole session about it at their I/O conference in 2010.

ListView is the crucible, the teeth-cutting, the rite of passage for all aspiring Androidians. It’s like Luke seeing Darth Vader in the cave on Dagobah. Once you’ve battled with ListView and emerged from the cave victorious, you’ll know you’re a true Android developer.

This is just one story about ListView.

When I was writing Pokédroid, I came across an interesting problem. The first screen of the app was just a huge list of creatures, but it was too difficult to navigate through. Depending on what game you had, you were only interested in the ones numbered 1-151 (first generation), 152-251 (second gen), 252-386 (third gen), 387-493 (fourth gen), or 494-649 (fifth gen). This meant that the newer (and therefore more interesting) Pokémon were at the bottom, where they were hard to get at. But assuming the National Pokédex numbering, this was just the proper order.

Problem: there were too many goddamn Pokémon.

Too goddamn many.

The solution I came up with was to make the list more navigable by showing “fast scroll” overlays with the names of the various Pokémon generations. Named after the games’ regions, they go “Kanto,” “Johto,” “Hoenn,” etc. That way, the user could immediately know what section of the list they were in, and they could quickly scroll between sections.

Lots of Android apps do a similar thing. The Contacts and Music apps, for instance, show overlays to let you know which part of the alphabet you’re on:

This is made possible by the use of the “fast scroll thumb,” i.e the little grooved square to the right. It allows you to zoom through your list contents and hone in on the item you want. It’s like blasting down the highway and watching the exit signs, versus crawling down a suburban street, inspecting each house number one-by-one. It’s a much better user experience.

So the fast scroll thumb is awesome. And to use it, all you have to do is add fastScrollEnabled=”true” to your ListView’s XML. The only catch? If you want to use it for anything other than alphabetical sorting, your section overlays are going to look like this:

Bleccch.

Yup, the overlay has a fixed width, so you can only really use it for single characters. What’s a poor Android developer to do?

As it turns out, the only way to fix this problem is to implement your own version of the Contacts app’s internal FastScrollView and hack it yourself. I wasn’t the first to discover this, but I did post some snippets of the solution to Stack Overflow back when I first implemented it in Pokédroid. Since then, I’ve been getting some questions and clarification requests on the original post, so I decided to go ahead and write a full demo app to show how it works. After all, Pokédroid is and will probably always remain closed-source, but this code at least is probably worth sharing.

The demo app is on GitHub. Since Pokémon is kind of an esoteric subject, I decided to go with the topic of countries and continents instead. In this example, we’ve got a big list of countries, sorted either by continent or by country name. When you use continent-sorting, you can see overlays of the continents:

…and when you sort by the country name, you see alphabetic overlays instead:

Of course, if you wanted to get really fancy, you could vary the width of the overlay based on what kind of sorting you’re using. But it should be clear enough how to do that from the source code. In any case, with Pokédroid, I had a handful of different sorting mechanisms, but the most common ones had rather long titles, so I just kept the width the same for all of them. In the end, it looked like this:

That’s Pokémon sorted by generation, type, and base HP. The possibilities are pretty endless. You can take your ListView and sort it, divide it, slice-n-dice it however you want.

The important thing is that “fast scroll” sections make for a better user experience. ListViews can hold a lot of data, but that doesn’t mean you should let your list get bloated and then leave all the hard scrolling up to the user. I have an app on my phone where the developer uses an unsectioned ListView with over 200 items. Two hundred! It takes almost five seconds just to scroll from top to bottom! That may not sound like much, but in the UI world, five seconds is an eternity.

Just imagine your poor users, holding their phone in one hand and flipping your ListView with the other hand, over and over again, like they’re trying to light a wet match. Then reflect on how much you could improve that experience with some fast scroll sections.

Well, ListView-abusing Android developers (you know who you are): now you have no excuse. The CustomFastScrollView code is public and open-source, so go use it. Get cracking!

One-star reviews are lousy bug reports

Puzzling over cryptic bug reports is a frustrating and unavoidable part of being a developer. When users want to complain to you about a bug, they just usually don’t think through all the pieces of data that might help solve the problem.

What OS are you using? What version of the software? What were you doing to cause the bug? When users are angry, they don’t want to deal with such tedious details. They just want to vent.

This happens with large software companies, small software companies, and indie developers alike. It’s such a common gripe among developers that it’s not even worth describing any further. Any seasoned dev knows what I’m talking about.

In the Android world, dealing with bug reports is even more frustrating, because they usually come in the form of 1-star reviews on the Android Market. 1-star reviews provide all the cathartic venting that users desire, without any of the useful information that could actually solve the problem.

Here are some actual 1- and 2-star reviews I’ve gotten on the Android Market:

  • didn’t open… gutted
  • There is no sound on moment would give higher rating when fixed
  • always forced close on samsung galaxy s. I have to uninstall it.

Yeah, not so helpful. Figuring out a bug from comments like these is like trying to solve a detective story with half the pages torn out.

Worst of all, these kinds of comments are dispiriting for developers, because star ratings are so crucial to getting your application to be highly ranked in the Market. My own recent app KeepScore had only 4- and 5-star reviews, and was starting to get ranked pretty highly, before receiving an onslaught of these nasty little comments:

Angry? Yes. Helpful? No.

KeepScore is designed to save scores automatically. In particular, it’s supposed to automatically save your scores whenever the app leaves the foreground, as shown here in the source code.

I couldn’t reproduce the data loss described in these reviews. Even when an incoming call disrupts an ongoing game, KeepScore gracefully exits and displays a comforting message saying, “Game automatically saved.” I’ve never seen it lose data.

So what happened here? Did the Android system kill the app before it could call the onPause() method and save the data (which, according to the Android Activity Lifecycle, shouldn’t happen)? Did the users just accidentally create a new game, so that it replaced the old one in the “Resume Last Game” section, making them think that the data had been lost? Who knows. Without a proper bug report, I have no idea what to make of this.

Bad reviews make the author feel better, but they rarely lead to better applications. I’m going to try not to let these reviews sour my experience with KeepScore, though, or discourage me from putting more effort into it. I want to get to the root of this problem.

So, loyal KeepScore users, have any of you run into this particular issue? If so, please report it on the GitHub page, and let’s squash this bug! Oh, and if I do manage to fix it, please leave a nice little comment for my trouble, will ya? It’d be nice to have some good reviews to offset all these bug reports.

CatLog now supports external Intents

As of version 1.3.2, you can now start up the main CatLog activity using an external Intent, with parameters for filter text and log level.

For Android developers, the idea is that you can just put a switch in your app where, if some debug variable is enabled, you can press a button or access a menu item to start up CatLog and search for text related to your app. This should make it less painful to do debugging, in situations where you don’t have access to adb logcat.

I’ve written a simple demo app on GitHub to show how to use the new Intent.  But the basic gist is that you want to paste something like this into your code:

Intent intent = new Intent("com.nolanlawson.logcat.intents.LAUNCH");

intent.putExtra("filter", myFilterText);
intent.putExtra("level", myLevelText);

startActivity(intent);

That’s it! Full documentation is below.

Intent

com.nolanlawson.logcat.intents.LAUNCH

Parameters

filter

Text to filter by.  Case doesn’t matter, and you can search for either process ids, tags, or log text.

level

Log level to set CatLog to, case insensitive.  One of:

  • E (error)
  • W (warn)
  • I (info)
  • D (debug)
  • V (verbose)
  • F (what a terrible failure)