User Guide

This guide is written for 0.3.1, and might not be correct for other versions.

About

AndroidIconUtils is an application to easy managing icons for Android developers.
It gives you a list of all icons in the Android SDK (or other icon bundles), and an easy way to copy the icons matching qualifiers (DPIs etc) to your projects.
This is recommended by Google to keep your application backwards compatible and makes it easier to get the application to look the same across different SDK versions.

You should look at the tooltips in the application for additional information.

Features

Application:
  • Multiple Icon Sources
    • Support multiple versions Android SDK
    • Support external icon sources / icon bundles
    • Support existing projects
  • Parses qualifiers for all icons
  • Groups physical icons by name
  • Icon preview
  • Filtering on icon name
  • Sorting by icon qualifiers
  • Selecting specific icons for copying
  • Support for projects
    • LRU list
    • CLI argument for opening a project on application start
Code:
  • Unittests
  • Javadoc for all public methods and classes
  • Continuous integration
  • Free permissive license

Background

Developing for smartphones presents other challenges than developing for web or desktop.
You're faces with a wide range of devices with different screen sizes, resolutions and capabilities.
In order to give the best user experience, you need icons tailored for the screen in question.

The Android OS has many versions in use. Each version has a standard set of icons developers might use.
These are available directly on the phone so you can reference them in your project.
The OS will choose the best version of the icon based on the device screen and orientation, and scale them to make them fit properly.
If an icon isn't a good enough match though, the icon might not look right (low quality icon scaled up, stretched etc).

Another challenge between Android versions is that the icons might change. Old icons might be changed or removed, and new ones added.
An application that looks good on your phone might look horrible (or not even have correct icons) on another version of the SDK.
To make an application work in a predictable manner on as many devices as possible, it's recommended that you package the icons you use in the application.

Unfortunately, it's time consuming to locate the icons you need as they are spread across multiple folders based on qualifiers.

This is the problem Android Icon Utils is trying to solve: Make it easy to locate the icons you need, and package them with your application.

Installation

Download here

The program is distributed as a java package (.jar file), so you might need to start it manually using
java -jar Android-icon-utils-0.3.1.jar

There's also a snapshot available at our CI server.

Usage

If you encounter any problems or would like to contribute, use the links in the Help menu.
To be able to post issues and ask for support, you'll need to register at the site.
When clicking these links, you should see a Register link in the top right corner of the page.

Icon sources

Edit -> Preferences

The program can support multiple SDKs, in addition to external icon bundles.

Upon starting the application for the first time, you'll get a dialog asking you to fill in the location to your Android SDK.
The same dialog is available through Edit -> Preferences.

Select the folder for your Android SDK using browse (platforms/android-<version>) and press OK.
For Android SDKs, the name should be set automatically.
Press Add to add this source.

The settings takes effect when pressing Ok, and the icon list will immediately be refreshed.

Populating the icon list is quite slow as the user interface is scaling the icons to fit nicely in the icon list, and it doesn't do this on the GPU.

You can add any other icon bundles that follows the Android SDK naming scheme for icon folders, including existing projects you might have.
An "Android naming scheme" is icons located in subfolders that contain qualifiers, e.g. drawable-land-xhpdi/icon.png.

Currently, the following icon types is supported:
  • png
  • 9.png
  • jgp
  • jpeg
  • gif

Icon list

Icon list

The background color is default pink to better see white icons on transparent backgrounds. You can toggle this using the Toggle background color checkbox. To the right, you'll see how many icons is matching your current filter. Remember that sort doesn't filter out any icons, just reorders them.


Filter

Filter by filename

You can filter the icon list based by parts of the filename. The filtering is case-insensitive.

The filter will take effect a short time after you stop typing.


Sort icons

Qualifier sort options

Select the qualifiers you need in the sort box. The icons gets sorted by best match (see the tooltip for more information).
Android will automatically scale icons that's not an exact match for the devices DPI, so no icons is actually filtered away using this method.
Using sort, you can first see icons best matching your criteria before searching through icons that might be scaled and thus not look as pretty.

The sort will take effect a short time after you stop pressing qualifiers.


Copy icons

Icon selection pane

By selecting a icon in the list, you'll see a (possibly) higher resolution image in the right pane, and get a list of the available icons.

Select the icons you'd like to copy to your project and press Copy.

  • If you have a project open, the icons gets copied directly to that projects output path (visible at the top of the screen).
  • If you do not hav a project open, you'll be presented with a dialog for choosing the destination folder.

In both cases, the application will automatically create the <your destination folder>/res/drawable-<qualifiers> folders.


Projects

Selecting output folder for icons each time you copy icons is tedious. The application supports projects to avoid this.
To create a project, follow these steps:
  1. Select File -> New Project
  2. Select project file
  3. Select output folder (the root directory of your application)

The projects are stored in a Recently Used List, or you can open it from File -> Open Project.

If you wish to integrate the application with IDEs, you can use the command-line parameter --project <your projectfile here> (without <>).
This accepts a filename for a project file that is opened when the application starts.

Integrate with Eclipse

  1. Create your Android Icon Utils project using File -> New Project
  2. In Eclipse, go to Run -> External Tools -> External Tools Configuration
  3. Fix paths (see image below)
    1. Your java executable
    2. Your Android-icon-utils-x.y.z.jar
    3. The project file you created in step 1

Contributing

If you wish to contribute, you can do so by submitting bugs or feature requests, or start Hacking the code.

filter_filename.png - Filter by filename (1.5 KB) Simen Endsjø, 2013-05-04 13:20

edit_preferences.png - Edit -> Preferences (7.88 KB) Simen Endsjø, 2013-05-04 13:20

sort.png - Qualifier sort options (5.34 KB) Simen Endsjø, 2013-05-04 13:20

icon_qualifier_selection.png - Icon selection pane (6.75 KB) Simen Endsjø, 2013-05-04 13:20

icon_list.png - Icon list (4.95 KB) Simen Endsjø, 2013-05-04 13:20

init.PNG (2.87 KB) Magnus Eriksen, 2013-05-11 13:18

Tool.PNG (26.4 KB) Magnus Eriksen, 2013-05-11 13:21

Also available in: PDF HTML TXT