How to label unlabelled buttons in android apps
Below is the process I follow for adding descriptions for unlabelled image buttons. It involves modifying the UI xml files in the apk package. If you have experience with flashing roms and installing kernels and the like, most of this is pretty straight forward. If you're new to android hacking, there will be a learning curve, but after you've done it once, it will be much easier the next time.
I used pandora for the example which turned out to be a poor choice, as there is a bug that prevents the package from rebuilding. I included a fix as a footnote in the end. If this is your first time, you may want to try another package instead. The bug is specific to the pandora app and I haven't encountered it with other apps I've modified. The mpdroid app can be rebuilt without errors. The steps are the same. I recommend starting with the app at the top of your accessibility wishlist. This will provide additional motivation.
I use linux and not windows, so the instructions are linux specific, but they should be adaptable for windows without too much trouble. Feel free to post them to your web site or blog. Just credit me (Trevor Astrope) as the original author.
Requirements
Before you can label the buttons, you will need to set up your environment.
1. Install and configure the android sdk from http://developer.android.com/sdk
2. Install the java runtime environment (jre) 6 (1.6) if you don't have it already. You can test with: java -version
3. Install apktool from http://code.google.com/p/android-apktool
4. Set up signing certificate and key or use the signing-tools.zip from http://wiki.rootzwiki.com/Signing
Ok, so by now you should have install all of the requirements above and
followed the instructions provided on each of the links.
If so, you're now ready to label those unlabelled buttons. I will
demonstrate the steps by labeling the unlabelled buttons in the pandora
app. While the pandora app itself is accessible, they forgot to label
the buttons in the widget, so we will label them.
1. You will need to copy the apk file to your workstation.
- If your device is rooted, you can find the apk in /data/app. Copy it
to /sdcard and use adb to copy it to your workstation.
adb shell
su
cp /data/app/com.pandora.android-1.apk /sdcard
exit
exit
adb pull /sdcard/com.pandora.android.apk .
- If your device isn't rooted, there are several ways to get the apk
file. I found one way here:
http://notepad2.blogspot.com/.../android-save-your-apk-files-from-google...
Note that you will need usb debugging enabled to use adb. If you have
never done this before, go to settings > developer options and enable
usb debugging. If you're on 4.1 or later, first enable developer options
by going to settings > about and tap (double tap with talkback) "the
build number 7 times. Then navigate up and go to developer options and
enable usb debugging.
Note that when connecting with adb over usb for the first time in 4.2.2
a dialog will popup on your device where you will need to confirm the
adb connection. Click the always checkbox so it doesn't ask each time
you connect from this machine.
2. Now that you have the apk on your workstation, you will need to
unpack it. Basically, the apk is just a zip file, but it is optimized or
odexed and will need to be de-odexed first. Thankfully, the apktool will
do this:
apktool d com.pandora.android-1.apk
The above command will extract the files and de-odex them into a
directory called com.pandora.android-1.
3. You're now ready to start adding labels to buttons.
Inside the com.pandora.android-1 directory is a "res" directory. This is
the directory where the UI files are located.
cd com.pandora.android-1/res
When you list the files, there should be a layout and a values directory
among other files and directories. The layout directory contains xml
files with ImageButton elements. You can use grep to find which files
have ImageButton elements, as not all files necessarily will have them.
cd layout
grep "
The android:id is a pretty good indicator of what the button does. In
this case it is "@id/thumb_down". Its pretty obvious this is the thumb
down button. Sometimes it isn't so obvious. In that case, the
android:src attribute might provide an additional clue. Other times you
just need to take a guess and fix it later if you get it wrong.
5. We need to now add an android:contentDescription attribute for the
button. Unfortunately, It isn't as easy as just adding a text label. You
need to reference a string that is defined in res/values/strings.xml.
In another window, open ../values/strings.xml and search for the word
"thumb_down". You'll find the line:
Thumb
Down
The text between the and tags is the value and the
name attribute is the text to reference. This is what we need.
Look at that, the name of the "Thumb Down" text is
"accessibility_description_thumb_down". It seems pandora is aware of the
need to label buttons. The widget must be an oversight, so hopefully
they will fix it when we tell them about it.
6. Go back to the widget.xml window and go to the end of the ImageButton
line, right before the '/>' and insert the following text:
android:contentDescription="@string/accessibility_description_thumb_down"
Note, the ImageButton element may sometimes contain a right angle
without the slash,as they are sometimes nested. Just be careful not to
remove or add any slashes before the right angle.
7. Repeat the steps 4 through 6 for the thumb up, play and skip buttons.
Here is what the ImageButton elements should look like after you are
done:
Note that sometimes you will not find a suitable string in the
strings.xml file. In those cases, you will need to make up one of your
own and add it to res/values/strings.xml.
8. Save the widget.xml file and cd to the com.pandora.android-1
directory. We will now run the apktool command to rebuild the apk file.
apktool b
If all goes well you shouldn't get any errors. (See footnote 1)
The last line of output should be:
I: Building apk file...
The apk file will be in the 'dist' directory.
Note that if you get errors, it is most likely a typo in a description
you added. Here are some things to check:
- The android:contentDescription attribute name is case sensitive (there
should be a capital D in Description)
- The string name is also case sensitive
- Make sure "@string/accessibility_description_thumb_down" is quoted and
there are no mismatched quotes.
- Make sure the string name exists in res/values/strings.xml exactly how
you entered it.
- Generally, if there are a lot of errors, they are usually related to
the first one in the output, so focus on that one and work your way from
there.
9. Change to the directory where you unzipped the signing-tools.zip in
the requirements step 4 and run the command below:
java -jar signapk.jar -w testkey.x509.pem testkey.pk8\
/path/to/com.pandora.android-1/dist/com.pandora.android-1.apk \
com.pandora.android-1.apk
Note that the above should be on a single line. I used backslashes to
escape the line breaks. Also, replace "/path/to" with the actual path.
10. Before you can install the new pandora apk, you will need to
uninstall the current version, since the signatures do not match. You
can do this by long pressing the app or in app manager or the play store
etc. You can also use adb or pm from the android shell.
Note that if you use adb or pm, you can't use the -k option to preserve
the app data, as the signatures need to match for this. It may be
possible to backup the app data with a backup tool like Titanium Backup
and restore it later, but I've never tried it.
11. Once the package is uninstalled, you can install your newly labeled
version. An easy way to do this is with adb:
adb install com.pandora.android-1.apk
12. Now open pandora from the app drawer, login and select a station.
Now go back to the home screen, open the widget drawer and drag the
pandora widget on to the home screen. The buttons will now be labeled.
Note that in a case where you were unsure of the label for a button,
and need to change it, just edit the res/layout file and follow the
steps to rebuild the package, sign it and upload it. You can use the
'-r' option with adb so you don't have to uninstall first:
adb install -r
13. You should now send your changes to the developer so they can
include them in the next release. The easiest way is to find the email
address listed in the play store entry and email the files you changed.
Alternatively, you could make a patch and mail that. If you have the
diff utility installed, follow the steps below:
- install the original apk file in the same location as last time, but
use this apktool command instead:
apktool d com.pandora.android-1.apk com.pandora.android-1.orig
- Now create the patch file:
diff -ur com.pandora.android-1.orig/res \
com.pandora.android-1/res > pandora-accessibility.patch
That's it!
Footnote 1:
There is a bug in the pandora package where the
blue_bar_close_normal.png and blue_bar_close_pressed.png are jpeg files
and not png files. This causes the build to fail. If you have
ImageMagick installed, you can fix it like this:
cd res
for file in drawable*/blue_bar_close_normal.png \
drawable*/blue_bar_close_pressed.png; do
convert $file temp.png
mv temp.png $file
done
Alternatively, you can use any software that converts files from jpeg to
png. The files are:
res/drawable/blue_bar_close_normal.png
res/drawable/blue_bar_close_pressed.png
res/drawable-hdpi/blue_bar_close_normal.png
res/drawable-hdpi/blue_bar_close_pressed.png
res/drawable-ldpi/blue_bar_close_normal.png
res/drawable-ldpi/blue_bar_close_pressed.png
res/drawable-mdpi/blue_bar_close_normal.png
res/drawable-mdpi/blue_bar_close_pressed.png
res/drawable-xhdpi/blue_bar_close_normal.png
res/drawable-xhdpi/blue_bar_close_pressed.png
