I’m working on an Android app and the documentation didn’t stop me making a stupid mistake. If it weren’t open-source, that might have been a problem.
For the first time in my Android life, I wanted to use a Notification. The instructions are straightforward, except for I was worried about what size graphic to use in the pull-down notification (as opposed to in the status bar); it didn’t seem like they could be the same size, and the nice list of icon sizes didn’t have one labeled “Notification pulldown”. So I tried guessing but that didn’t work out very well. Worse than that, the usual plan B, typing “notification pulldown icon size” into Google, didn’t help much.
Then I looked at the other notifications in the pulldown and noticed that one of them, with a nice icon, said “USB debugging connected”. So I hopped over to my AOSP source tree and said:
find . -name '*.xml' -print | xargs egrep 'USB debugging connected'The output from some strings.xml file gave the string’s internal name:
adb_active_notification_title. So I said:
find . -name '*.java' -print | \
xargs egrep adb_active_notification_titleAfter which I knew that the code I wanted to see was in a file called
NotificationManagerService.java, seven (!) levels deep in the
source tree. I opened that up, searched for adb_active, and was
looking at notification-setup code. Right away I learned a couple of
useful tricks for my own app; then I noticed that the icon it was
jamming into the notification was called
R.drawable.stat_sys_adb. Hah:
find . -print | grep stat_sys_adbWhich turned up a couple of PNG files, and a quick glance told me that the hdpi version was 38x38, the mdpi 25x25. Which is to say, yep, the same icon for status bar and notification drop-down. And the framework arranges to render them at whatever the appropriate size is.
There you go. In an ideal world, I’d have been smart enough to deduce that since they didn’t say anything about different icon sizes, I could just use the same one in both places. In some future even more ideal world, the AI-driven documentation would deduce that I was overthinking it and say “Yes, you moron, you can use the same icon for status bar and drop-down.”
We live in a non-ideal world. In such a world, Open Source wins.
Your Opinions · I just got around to moderating comments, and to save space, let me just report, without copying them all in, that there were a bunch of comments saying “You’re horrible people because your documentation isn’t complete and I might have to grep the source” and another pile saying “You’re horrible people because you haven’t released 100% of the source so there are parts I can’t grep.”
I did accept comments that weren’t dupes of one of those gripes.
Contributions
Comment feed for ongoing:
From: Ian Lake (Sep 20 2011, at 11:33)
The Status Bar Icon Design Guidelines page on the Android Developer site (http://developer.android.com/guide/practices/ui_guidelines/icon_design_status_bar.html) goes through all of the details and best practices on status bar icons which 'are used to represent notifications from your application', assuming you are using the default Notification constructor. Although, you can always define a custom content view and make the image whatever size you want, separate from the status bar icon.
Even with the excellent documentation on the Android Developer website, I would agree that there are many cases that having the source has been most helpful - sometimes seeing exactly what they are doing is the only way to find out what I've been doing wrong all along.
[link]
From: Christopher (Sep 20 2011, at 11:34)
Thankfully the API to build Notifications has finally been made sane (well, from 3.0 onwards)!
Indeed, the source is a real boon when you need to figure out details like this.
Alternatively, rather than using grep (or better, ack), I also find Google Code Search with "package:android.git [query]" to be useful. Especially right now that kernel.org remains down! :)
However, the technique you describe currently only works for pre-3.0 code, as the core Android parts don't seem to be available on AOSP.
Any idea if this will change with the upcoming release?
[link]
From: Dave Rogers (Sep 20 2011, at 11:42)
One non-ideal aspect of "the world" is its inhabitants' relentless, not to say mindless, insistence in viewing it as a zero-sum game.
[link]
From: Mike Ellery (Sep 20 2011, at 13:57)
Is this, perhaps, a deficiency in the documentation? Or was this more likely a refinement to your app that few should need to make, thus not worthy of general docs?
I wonder if there ought to be a way for the community to annotate the SDK docs for android with bits of insight (such as this). Of course, this would have to be heavily moderated to avoid the oodles of spam that would ensue.
[link]
From: Andy Reitz (Sep 20 2011, at 14:20)
Lately, I've been enjoying the excellent "ack" utility for grep'ing source code, rather than the find/grep combo:
http://betterthangrep.com/
Recommended.
[link]
From: Patrick Gibson (Sep 20 2011, at 15:51)
In fairness to non-opensource platforms (I think we all know what is meant), besides having a rich set of documentation that outlines any image or icon you need to supply, it's also the case that you don't have to worry about this sort of thing. The upcoming release uses the application's icon for the new notification system, and I think this works pretty great. I personally would be annoyed if I was getting notifications that used icons that didn't match what I was used to seeing as the application icon and therefore could be confusing to identify the source.
[link]
From: Wingding (Sep 20 2011, at 17:15)
The logical world can sometimes be briefly confusing. Without comment about the icons, it would take a second thought to conclude that the same could be used in both places.
[link]
From: Douglas Drumond (Sep 20 2011, at 18:09)
I have a cscope database in the root of my android source (ie, the directory where I called repo init), then I just use cscope to look for what I want. It's faster than grepping and finding.
In fact, I have two scripts, genscope and runscope with the appropriate parameters.
Also, I just found this page:
http://naseer.in/use-cscope-to-browse-the-android-source-code
[link]
From: Rob Sayre (Sep 20 2011, at 21:46)
I was just told about a tool called 'ack'. It's a perl thing present in most package managers. It might be called 'p5-ack', 'ack-perl5', etc.
so, you could write
ack adb_active_notification_title --java
It's recursive by default, and it's really fast. Never going back.
[link]
From: Michael Domanski (Sep 21 2011, at 01:45)
Do you often dismember your gearbox to acquire knowledge how to change a gear?
Educating as it may be, this also may lead to a loss of time or abusing the knowledge of internal workings of a given system for a "just-this-once-hack"
[link]
From: Jeffrey Yasskin (Sep 21 2011, at 10:35)
It would be nice if there were SDK packages that would install the source for each version of Android in a way that eclipse could find. Or even if http://developer.android.com/sdk/eclipse-adt.html would give instructions for downloading the source and attaching it to the jars in Eclipse.
[link]
From: Bryan Liles (Sep 21 2011, at 11:12)
Looks good to me! ack will cure you from typing find ... | xargs egrep all time.
[link]
From: Yuku (Sep 21 2011, at 19:22)
Consulting the source is always beneficial, but I'm suspecting that somehow the documentation is scarce because the writer thinks "The developers have access to the source, let them see it by themselves". Compare Android SDK docs with iOS SDK docs, and you will see so much difference.
[link]
From: Mike Kale (Sep 28 2011, at 20:06)
I love this about Android, and have done similar things myself several times. I wish Apple would publish the source to UIKit for the same reason. They wouldn't have to make it real open source or accept patches, but being able to see the implementation of the layer below your code has many benefits.
[link]