ADW Theming Guide

TABLE OF CONTENTS

INTRODUCTION

What it is:

This guide aims to consolidate the knowledge of those who have created ADW themes and present it to anyone who wants to create their own theme thus making it the official ADW theme guide.

In doing so, this guide will attempt to assist those who want to start making their own ADW themes by setting up the theme template into the Eclipse IDE and thoroughly break down every file found on the theme template.

An additional Deeper Look section will guide you through the process of gathering the proper names, how to name the images and troubleshoot most of the common errors you may encounter along the way.

The theme template requires us to use -and learn to use if you haven’t done so already- the Eclipse IDE with the ADT plug-in.

Eclipse is an Integrated Development Environment (IDE) used by programmers to write and debug applications written in many languages, in this case, that language is Java but there are many other versions of Eclipse and/or plug-ins to make Eclipse a one stop IDE. The IDE contains all the tools necesary to write, build and run Java code as default, so how can we use Eclipse to make our ADW themes? Well, luckily the wonderful engineers at Google made a nifty plug-in to use in conjunction with the Eclipse IDE called the Android Development Tools (ADT). This plug-in, along with the Android SDK, will allow us to use Eclipse and provide us with error corrections and/or hints that make it the key component in building your themes. or at times giving you headaches and/or loss of sleep – kiding, I’m just kidding.

If you’re used to making themes by reverse engineering the application packages (.apks) – ie root themes – or
if you’ve experimented with compiling from source via the command line interface using the T-Mobile theme engine
themes, then you’ll find that making an ADW theme a bit more challenging since you’ll be learning something entirely new.

At the end of the day you’ll either like or dislike working with the Eclipse IDE and the ADT plug-in. I find it much easier to use at times because of my programming background but that is certainly not the case for everyone since there are those times that one edit to an icon name, a 9 patch or an XML name can give you multiple errors. Most of those errors will be covered in Common Issues with Eclipse

What it isn’t:

This guide will not walk you through on installing the appropriate tools that you will need.

This assumes that you already have the appropriate tools -covered in the Prerequisites on the next section- necessary to start on your themes. If you don’t have these tools on your development machine then you need to head on over to http://developer.android.com. The site will guide you on what components you need to install and how to install them to get you up and running.

PREREQUISITES

To begin making your ADW themes on your development machine, you must have the following checklist completed and preferably in the same order:

  1. The latest version of the Java 1.6 Development Kit (JDK)
  2. The latest version of Eclipse IDE for Java developers (tested fine on Galileo, Helios and Indigo. They all work fine)
  3. Have the ADT plug-in installed from within Eclipse IDE and is up to date
  4. The Android SDK updated and ready to go (latest API installed).
  5. And finally having the ADT plug-in configured to look for the Android SDK directory (on your computer) from within Eclipse

Again, if you do not meet any of these requirements I suggest you go and visit the android developers site as previously mentioned by going to http://developer.android.com/sdk/ and read up on how to install the necessary software/plug-ins. This guide will not go through the tedious steps of installing all of the aforementioned pieces of software/tools because that can be a separate guide altogether. So without further delay let’s get started with our ADW theme.

IMPORTING THE TEMPLATE TO THE ECLIPSE IDE

The official ADW theme template is available for anyone to use and modify. Go here and use git or click the “ZIP” button to download. Save it somewhere safe and easily accessible. Once it’s finished downloading and you’ve unzipped the template with your favorite archiving application -7zip, WinRAR, etc- you will find the all important README file with basic instructions to get you started along with the template’ structured layout of folders and XML files.

If this is your first time starting up the Eclipse IDE, you will be asked for a workbench directory. The default
workbench directory is fine just make sure you know where the default workspace directory is and tick the check-box so Eclipse IDE won’t ask you for a workbench every time you load it -unless you want to switch your workspace every time you start up Eclipse. Once you get past this step you will be presented with the Welcome Page. Simply hit the workbench Icon to enter the workbench. The Eclipse workbench is the standard development view. The theme template will be presented as a project once we import it. This will allow us to compile/debug the theme.

Screenshots taken with Eclipse Galileo.
Welcome Page The Eclipse workbench

The next step is to import the theme template.
Selecting New Project Configuring New Project

So let’s load the theme but before we do that we must make sure/configure Eclipse to use Java 1.6 compiler. To do this we must go to Window > Preferences open the Java tree on the left hand side and select Compiler. Here is where you must make sure that Compiler compliance level is set to 1.6. If you installed the JDK 1.7 you will get a warning saying to install a 1.6 JRE. To avoid this just download the 1.6 JDK. Now let’s start our job:

Load the template into Eclipse:

  1. In Eclipse, select “New -> Android Project”
  2. On the new project screen, select “Project from existing source” and select the theme template directory
  3. Click “Finish”

If you’ve been following along you should be using the latest API but make sure to double check before you click Finish. If you downloaded any previous API’s make sure that this source build target is Android 2.2 at minimum. You will get a lot of errors and headaches if you choose a lower build target. Also, if you want your theme to be available for devices that have an older version of Android, simply adjust the AndroidManifest.xml, specifically the following line:


<uses-sdk android:minSdkVersion=”4″/>

After we have the template loaded up onto Eclipse, we proceed to give our theme a package name which is step 2 on the README:

Modify the app package name and path (you should change if from x.x.x to your.package.name)

  1. In Eclipse, look into your project explorer, right-click the x.x.x package and select “Refactor->Rename…” write your own package name and follow the instructions.
  2. Once the operation is finished, look for lines similar to import x.x.x.R; inside the java files and delete them.
  3. Make sure that the AndroidManifest.xml also has the new name instead of x.x.x
    in the package field.
  4. Finally search the line on the Android Manifest.xml called <provider android:name……..”x.x.x.DocksProvider” /&gt and change the “x.x.x” to match your.package.name

Sometimes the rename proccess doesn’t change the x.x.x in the Android Manifest so you should make sure that it does match in case it didn’t happen automatically.

Congratulations! If you’ve successfully made it this far, you should now have imported the ADW theme template onto Eclipse! At this point you shouldn’t have any Java errors. If you do, make sure to double-check that on every Java file the import x.x.x.R; statement is removed and that that package statement on each Java file matches the your.package.name that you selected. If everything appears to be correct and you’re still having Java issues go to the Problems window on the bottom window (visible on any of the above screen shots) and delete the errors it has. Clean your project by choosing Project -> Clean on the menu bar (see screen shots). In the event that Eclipse gives you future errors, the above steps are found to be way to fix them.

You now should have the theme template imported onto your Eclipse workbench. So what does
this theme contain? Well, besides the errors that Eclipse originally complained about, there are some important things to note about the template:

The theme template allows us to configure the main theme “Skin”, and optionally include both a dock pack and an icon pack to give your theme some extra flare. These are optional of course but are strongly recommended to have since the docks and icons can be mixed and matched by the user to create a unique look on their device.

CONFIGURING YOUR THEME

Now that we have all of the errors sorted out hopefully, and understand what it is we can change in the theme template, it is time to start making icons, docks, skin and many other changes to ADW.Launcher which can be done through your theme.

Your assets make the theme. From the color scheme, the docks, wallpaper to the icons themselves, creating a consistent look and feel is a bit of work but this section aims to outline the editable assets on the theme template.

RESOURCE TYPES

In this guide, the theme resources/assets are marked as different types:

  • STRING: text elements, usually go inside the theme_config.xml or skin_theme.xml like so:

    <string name=”name_of_the_asset”>text of the asset</string>

    Sample: To provide your theme name you must include this STRING within res/theme_config.xml

    <string name=”theme_title”>My Cool ADW Theme</string>

  • COLOR: the theme defined colors, these usually go inside the skin_theme.xml like so:

    <color name=”name_of_the_asset”>#FFFFFFFF</color>

    Sample: To provide different icon highlight color you must include this COLOR within res/skin_theme.xml

    <color name=”config_highlights_color”>#FFFF0000</color>

  • INTEGER: integer numbers, these usually go inside the skin_theme.xml like so:

    <integer name=”name_of_the_asset”>15</integer>

    Sample: To specify different dock icon size, the INTEGER tag within res/skin_theme.xml is the place to edit.

    <integer name=”dock_icon_scale”>7</integer>

  • BOOLEAN: true or false, these usually go inside the skin_theme.xml like so:

    <bool name=”name_of_the_asset”>true</bool>

    Sample:

    <bool name=”dock_reflections”>false</bool>

  • DRAWABLES: graphical assets that go inside the appropriate res/drawable# folder. The following shows the basic idea.

    Sample:

    ASSET NAME: name_of_the_asset.jpg
    SAMPLE DIRECOTRY: res/drawable-hdpi/name_of_the_asset.jpg

    • More information can be found on the Icons section.

    THEME INFORMATION

    Within the res/values directory, there is a file named “theme_config.xml” where the important information for the theme can be modified. This includes:

    STRINGS

    theme_title: your theme title
    authorName: your Personal/professional name
    authorLink/developer_link: Url to your web/blog/etc
    developerName/developer_name: your Google Play developer name (used for theme search)
    theme_description/theme_info: Long text description of your theme

    DRAWABLES

    theme_preview/theme_feature: Header image for the theme info screen. Shouldn’t be bigger than 250×100 but is not mandatory.

    SPECIAL ITEMS

    You can include some preview images to showoff your theme. Unfortunately, to maintain compativility with other launcher themes, they don’t follow the resources guidelines.
    First you need to put your images in the res/drawable# directory of choice with, for example, the following names: myscreenshot1.jpg, myscreenshot2.jpg,…
    Then you have 2 alternatives:

    • Open the file res/xml/themecfg.xml and edit this line:

      <preview img1=”myscreenshot1″ img2=”myscreenshot2″…/>
    • Or open your res/theme_config.xml file and add the following lines:

      <string name=”theme_preview1″>myscreenshot1</string>
      <string name=”theme_preview2″>myscreenshot2</string>

      (…upto theme_preview5)

    SKIN

    The main theme Skin is composed with lots of differents assets that can be included to alter the way ADW.Launcher looks. Each element is NOT MANDATORY, this means you don’t have to include all of them to create a theme. Just add what you want.

    The following listing shows every asset that can be included in your theme:

    Overall Color Scheme

    Asset name/s: overall_theme

    Asset type: STRING

    Possible values:

    • 0: Light theme
    • 1: Dark theme

    Sample: to use the dark theme, just add a line inside res/values/skin_theme.xml like this:


    <string name=”overall_theme”>1</string>

    Wallpaper

    Asset name/s: theme_wallpaper/default_wallpaper

    Asset type: DRAWABLE

    Sample: To include a default wallpaper for your theme you can include a “theme_wallpaper” DRAWABLE asset this way:

    res/drawable-hpdi/theme_wallpaper.jpg

    Or

    Recommended Way: To include a default wallpaper for your theme you can include a “default_wallpaper” DRAWABLE asset this way:

    res/drawable-hpdi/default_wallpaper.jpg
    and create an alias inside res/values/skin_theme.xml like this:

    <drawable name=”theme_wallpaper”>@drawable/default_wallpaperr</drawable>

    Main Font

    Rename your font to themefont.tff and it under the assets folder like so assets/themefont.ttf

    App Dock

    The App Dock size can be changed by your theme with the following

    Asset type: INTEGER

    Asset name: dock_icon_scale

    Values range: from 5 to 15 (meaning from 50% to 150% of the regular icon size).

    Sample: to make the App Dock 80% of the regular size, just add a line inside res/values/skin_theme.xml like this:


    <integer name=”dock_icon_scale”>8</integer>

    Its appearance can be modified providing the following assets:

    Asset type: DRAWABLE

    Asset names:

    • dockbar_bg: Horizontal design for the dock
    • dockbar_bg_land: Vertical design for the dock

    Recommended: name your designs files in res/drawable# whatever you like (i.e. my_cool_dock_horizontal.png and my_cool_dock_vertical.png) and create an alias inside res/values/skin_theme.xml like this:


    <drawable name=”dockbar_bg”> @drawable/my_cool_dock_horizontal </drawable>
    <drawable name=”dockbar_bg_land”> @drawable/my_cool_dock_vertical </drawable>

    Asset type: BOOLEAN

    Asset name: dock_reflections

    Set it to true to enable dock icon reflections by default on your theme

    Sample:


    <bool name=”dock_reflections”>true</bool>

    Desktop Indicators

    Your theme can decide the indicator style you want as default with the following:

    Asset type: STRING

    Asset name:config_desktop_indicator_type

    Possible values:

    • 0: disable the desktop indicator
    • 1: Dots at the top
    • 2: Slider at the bottom
    • 3: Slider at the top
    • 4: ICS Slider
    • 5: Dots over the dock

    Then, you can theme the desktop indicators in two different ways. Just change their colors or provide completely new drawable assets for them.

    Asset type: DRAWABLE

    Asset names:

    • indicator_dot_active: drawable shown in the DOTS style indicators for the current screen.
    • indicator_dot_normal: drawable shown in the DOTS style indicators for the other screens.
    • indicator_line: drawable shown in the LINES and ICS style indicators.
    • indicator_ics_bg: drawable shown in the ICS style indicator as background.

    Asset type: COLOR

    Asset names:

    • desktop_indicator_color: main color for the simple desktop indicators. Background color for the ICS indicator.
    • desktop_indicator_fgcolor: main color for the ICS indicator.
    • desktop_indicator_shadowcolor: shadow color for the indicators.

    ActionBar

    The ActionBar can be modified by the theme in 2 different ways: by choosing one of the predefined styles or by providing your own assets.

    First you should modify the style with the following:

    Asset type: STRING

    Asset name:actionbar_style

    Possible values:

    • 0: disable the ActionBar
    • 1: Transparent/Themed ActionBar. You MUST select this one if you want to provide your own graphics assets
    • 2: Default Light ActionBar
    • 3: Default Dark ActionBar
    • 4: Default Frame ActionBar

    If you want to specify custom assets, use the following:

    Asset type: DRAWABLE

    Asset names:

    • actionbar_bg: Horizontal design for the ActionBar background
    • actionbar_bg_landscape: Vertical design for the ActionBar background
    • actionbar_search_logo: Horizontal design for the ActionBar search logo
    • actionbar_search_logo_land: Vertical design for the ActionBar search logo
    • actionbar_search_voice: Horizontal design for the ActionBar voice search icon
    • actionbar_search_voice_land: Vertical design for the ActionBar voice search icon
    • actionbar_menu:ActionBar icon to open the ADW Menu (only shown on tablets)
    • actionbar_allapps:ActionBar icon to open the Application Drawer
    • ic_delete:The icon where users drop icons to delete them.
    • ic_appinfo:The icon where users drop icons to show the app information.

    Folders

    Your theme can decide the folder previews style you want as default with the following:

    Asset type: STRING

    Asset name:folder_preview_style

    Possible values:

    • -1: disable the folder previews and show the regular icon.
    • 0: Stack previews.
    • 1: Fan previews
    • 2: Grid previews

    Also you can select the previews background image, leaving the user choose from 4 different styles. You don’t need to provide all of them, instead just setup your theme to use one and provide only that specific drawable. But maybe your users will be happy if you allow them to select their preferred themed style

    Asset type: STRING

    Asset name:folder_iconbg_style

    Possible values:

    • 0: Circle
    • 1: Square
    • 2: Plate
    • 3: Hole

     

    Then you can change different properties:

    Asset type: COLOR

    Asset names:

    • folder_text_color: color for the icon’s text
    • folder_shadow_color: color for the icon’s text shadow

    Asset type: DRAWABLE

    Asset names:

    • qa_popup: Folders background when open.
    • folder_ring: Folders’ icon background when “folder previews” are enabled for the Circle style.
    • folder_square: Folders’ icon background when “folder previews” are enabled for the Square style.
    • folder_plate: Folders’ icon background when “folder previews” are enabled for the Plate style.
    • folder_hole: Folders’ icon background when “folder previews” are enabled for the Hole style.
    • ic_launcher_folder: Folders’ icon when “folder previews” are disabled.

    App Drawer

    The App Drawer is where all the installed applications are shown to the user. You can modify the following assets:

    Asset type: COLOR

    Asset names:

    • config_drawer_color: color for the app drawer background.
    • drawer_text_color: color for the icon’s text
    • drawer_shadow_color: color for the icon’s text shadow.

    At the top of the Application Drawer, there is a new Drawer Tab Bar. This is where all of the user’s application groups are displayed. Your theme can provide assets to modify its appearance:

    Asset type: DRAWABLE

    Asset names:

    • drawer_tabbar: The whole TabBar background.
    • tab_indicator: Each tab background.
    • actionbar_overflow: The “menu” icon show to the right.

    Desktop

    The desktop overall appearance can also be modified with the following assets:

    Asset type: COLOR

    Asset names:

    • config_highlights_color: color for the icons background when pressed/selected.
    • icon_text_color: color for the icon’s text
    • icon_shadow_color: color for the icon’s text shadow.
    • icon_label_color: color for the icon’s background rectangle.
    • sense_previews_bg_color: color for the sense desktop previews background.

    Asset type: DRAWABLE

    Asset names:

    • shortcut_selector: an image to use as desktop icon background
    • desktop_outlines: Screen background while the user is scrolling the desktop/dragging items
    • preview_bg: Screens background for the Screens Editor

    ADW.Launcher specific Action Icons

    ADW.Launcher includes a few own icons to perform common actions like opening the app drawer, moving to an specific screen, toggle the dock, etc. You can theme those icons too by providing the following assets:

    Asset type: DRAWABLE

    Asset names:

    • all_apps_button: Open/close App Drawer
    • movetodefault_button: Move to default screen
    • showpreviews_button: Show desktop previews
    • showhidestatusbar_button: Show/Hide the statusbar
    • openclosenotifications_button: Open the notifications panel
    • openclosedockbar_button: Show/Hide the App Dock
    • opencloseactionbar_button: Show/Hide the ActionBar
    • adwsettings_button: Open ADWSettings
    • showcategory_button: Show an App Drawer Group
    • movetoscreen_button: Move to an specific screen
    • adw_config: Show the ADW Setup Grid
    • openclosenotifsettings_button: Open the quick settings panel (android 4.2+)
    • nextscreen_button: Scroll to the next screen
    • previousscreen_button: Scroll to the previous screen

    ADW Setup dialog

    The dialog used in ADW when long-pressing the screen, pressing the menu button, etc, can also be themed with the following:

    Asset type: DRAWABLE

    Asset names:

    • adwconfig_tab_indicator: Background for each tab (ADWConfig/Add).
    • adwconfig_tabbar: The whole tab bar background.
    • adwconfig_background: The whole screen background

    Asset type: COLOR

    Asset names:

    • adwconfig_tab_text_color: Text color for tabs.
    • adwconfig_tab_text_shadow_color: Text shadow color for tabs.

    Also this screen’s icons can be themed too:

    Asset type: DRAWABLE

    Asset names:

    • adw_settings: Device settings
    • adw_adwsettings: ADW Settings
    • adw_lock: Lock desktop
    • adw_arrange: Arrange screens
    • adw_resize: Resize screens
    • adw_wallpaper: Wallpaper
    • adw_actions: Launcher Actions
    • adw_shirtcut: Shortcut
    • adw_customshirtcut: Custom shortcut
    • adw_widget: Widgets
    • adw_folder: New Folder

    Default Search Widget

    ADW Includes a basic search widget. Your theme can modify its appearance with the following assets:

    Asset type: DRAWABLE

    Asset names:

    • search_floater: Widget background
    • textfield_searchwidget: Search logo background
    • placeholder_google: Search logo
    • search_button_voice: Voice search icon
    • btn_search_dialog_voice: Voice search background

    APPLICATION ICONS

    Icons are probably the most popular part of any ADW theme. Of course we can’t really give you a creative boost here (that’s your job!), but we can show you how to size and export your icons so they work correctly.

    There are two methods for setting up your theme icons to work with ADW.Launcher. The first one is the recommended one and works only for ADW.Launcher and ADWLauncher EX since version 1.3.3.7. The second one is the legacy way maintained for compatibility.

    But for both methods you first need to gather some information about the applications’ icons you want to theme. This information is called the application’s component name

    The component name is composed with the application’s package name and the application’s activity name. Check the App Databases section for detailed information on how to obtain the required component names for the applications.

    Once you get the application’s component name, these are the two options to include that application icon into the theme:

    For this example, we are going to theme the Browser application’s icon. We’ve created our cool Browser theme icon and put it within res/drawable-hdpi/my_cool_browser_icon.png and obtained the component name as com.android.browser/com.android.browser.BrowserActivity

    • APPFILTER way:Open the theme file res/xml/appfilter.xmlAdd the following line to it:


      <item component=”ComponentInfo{com.android.browser/com.android.browser.BrowserActivity}” drawable=”my_cool_browser_icon” />

      That’s it. Easy, isn’t it? You just need to put a line like the previou one for each application icon you want to theme.

    • LEGACY way:To use the legacy way, instead of using the appfilter.xml file, your theme must include a drawable with a name that matches the application’s icon activity name modified as per the following convention:

      The proper naming scheme is as described in the theme template’s README. All punctuation in the activity name should be replaced with underscores (_).

      Punctuation next to each other, such as a forward slash and a period, should be replaced by a single underscore. Your finished icon name for the current example should look similar to this: com_android_browser_browseractivity

      So, as we have our icon PNG within res/drawable-hdpi/my_cool_browser_icon.png we open the res/values/icon_aliases.xml file and put the following line:


      <drawable name=”com_android_browser_browseractivity”>@drawable/my_cool_browser_icon</drawable>

      That’s it.

      You could alternatively just rename your my_cool_browser_icon.png file to com_android_browser_browseractivity.png, but this would lead to long and frustrating file names and difficult icon management for you. Check the XML Tips and Tricks section for more info about it.

    Icons Special Features

    If a theme does NOT include an icon for a specific application, that application will have a regular icon for your theme breaking the look and feel of the theme. Fortunately there is a way of spicing up those icons so every icon in your theme is not the default one. I’ve called them Icon Layers.

    You can create assets to combine with the default icons creating special drawables this way:

    1. Icon Background: a base image to use as background for every icon.
    2. Icon Overlay: a base image to use as overlay for every icon.
    3. Icon Mask: an image to use as transparency mask for every icon.
    4. Icon Scale: the original icon will be scaled to the specified ration before merging it with the other layers.

    Combining those assets can help you to create a unique and complete icon theme. You can even include more than one for each layer, so the theme engine mixes them.

    To use the Icon Layers feature, just create your desired image layers and put them in your preferred res/drawable# directory. Then open the /res/xml/appfilter.xml file and put something like this:


    <iconback img1=”icon_bg_1″ img2=”icon_bg_2″ img3=”icon_bg_3″…/>
    <iconupon img1=”icon_overlay_1″ img2=”icon_overlay_2″…/>
    <iconmask img1=”icon_mask_1″ img2=”icon_mask_2″…/>
    <scale factor=”0.8″ />

    Sample:

    • Original Icon:
    • Icon Background
    • Icon Overlay
    • Icon Mask
    • Icon Scale1.2
    • Result

    /res/xml/appfilter.xml


    <iconback img1=”icon_bg”/>
    <iconupon img1=”icon_overlay”/>
    <iconmask img1=”icon_mask”/>
    <scale factor=”1.2″ />

    ICON PACK

    The icon pack’s purpose is to list all your icons so the user can select them when editing shortcuts on the homescreen or mixing and matching on the theme section. An example would be if say your theme has alternative icons for music apps, messaging apps, etc or simply the user wants to mix and match the theme which is perfectly fine as long as you include the file names in the res/values/icon_pack.xml. The maximum number of icons on the icon_pack.xml is 500.

    The inclusion of the icon pack is optional, it’s all up to you if you want to include them. In order to use the icon pack you must make sure to configure the /res/theme_config.xml file and modify this line:


    <bool name=”enableIconPack”>true</bool>

    Sample:found in res/values/icon_pack.xml


    <?xml version=”1.0″ encoding=”utf-8″?>
    <resources>
    <string-array name=”icon_pack” translatable=”false”>
    <item>nameoficon1</item>
    <item>nameoficon2</item>
    <item>nameoficon3</item>
    </string-array>
    </resources>

    DOCK PACKS

    The theme template comes with the ability to include additional docks which are declared in the res/values/dock_pack.xml file.

    The inclusion of the dock pack is simply to add customization to your theme, but it’s all up to you if you want to include them. In order to use the dock pack you must make sure to configure the /res/theme_config.xml file and modify this line:


    <bool name=”enableDockPack”>true</bool>

    The docks are regular drawables that ADW will put and stretch/adapt to the user configured dock.

    The following is the res/values/dock_pack.xml. This is an array XML in which you simply list your dock names without the file extension.

    The following listing shows a sample dock_pack.xml. In this example we’ve created 3 different docks and put them within res/drawable-hdpi directory, calling them my_cool_dock1.png,my_cool_dock2.png and my_cool_dock3.png

    Sample:found in res/values/dock_pack.xml

    <?xml version=”1.0″
    encoding=”utf-8″?>
    <resources&gt
    <string-array name=”dock_pack” translatable=”false”>
    <item>my_cool_dock1</item>
    <item>my_cool_dock2</item>
    <item>my_cool_dock3</item>
    </string-array>
    </resources>

    That’s it, now your theme includes three additional docks for your user’s to choose.

    USEFUL INFORMATION

    IMAGE SIZES

    As we’re sure you know, Android devices come in all shapes and sizes. Included in this assortment is the screen densities. As such, the system displays things differently depending on what display the device has. Android is smart however, and will re-size icons to fit its hardware. All you need to do is tell it to do so.

    Here are some of the common screen density designations in the Android ecosystem:

    Designation Resolution
    LDPI ~120dpi screens
    MDPI ~160dpi screens
    HDPI ~240dpi screens
    XHDPI ~320dpi screens

    Sometimes it’s difficult comparing screen resolution/size to density, as manufacturers can use smaller displays with higher densities, and vice versa. This guide provided by Google is generally accurate and can help you figure out your own device’s density:


    Again, these are rough generalizations of screen density. For instance, according to this
    the Motorola Droid 1′s 3.7in screen should probably be a normal, MDPI screen, but its 854×480 resolution makes it an HDPI.

    Now that you know what levels of density there are, which ones should you support? It really depends on your project: Do you plan to distribute your theme, or just keep it for yourself? If you’re moving towards the former, supporting at least the first three densities is important. If the latter, you’ll only need to support whatever your device(s) is/are.

    To begin creating your icons, we recommend you use a 72x72px area to work in. This provides enough detail for each screen density while keeping the file size low.

    After designing your icons, export them as PNG files with a transparent background. This way any shadow or blank area will look correct on your screen. For now, name the icon after the app it represents. We’ll cover correct naming conventions later.

    Bottom line – stay consistent, stay readable, and stay fun!

    9 PATCHES

    The 9 patch images are special png files that are are stretchable based on the guides they contain. These guides tell Android where to place content and where to stretch the image. These are very tricky to make/understand in the beginning so it is very advisable to read this official documentation to figure out how they work.

    Most of the skin assets can be done using the 9 patch technique to improve their scalability. Things like Docks, ActionBar backgrounds, Folders backgrounds, etc would benefit from this feature.

    Don’t be scared of using them, they’re relly simpler than you could expect. You just have to create 2 or 3 to get things working

    SELECTORS

    Most graphics assets can be tweaked so they display different images depending on the item’s state. They are caled StateList drawables or commonly just Selectors

    For example, consider the skin asset named shortcut_selector or the asset named tab_indicator. These assets provide a custom background for the desktop icons and the app drawer tabs respectively. If you want those backgrounds to react to user interaction (i.e. changing color when the user taps on them) consider using selectors instead of plain PNGs.

    It is very advisable to read this official documentation to figure out how they work.

    A simple example is the following:

    Imagine you want your app drawer tabs to be “cool”, so you create different images for each state this way:

    • res/drawable-hdpi/my_cool_tab_red.png
    • res/drawable-hdpi/my_cool_tab_yellow.png
    • res/drawable-hdpi/my_cool_tab_orange.png

    Now, as the drawer tab’s theme asset is named tab_indicator you create the following file within /res/drawable/tab_indicator.xml


    <?xml version=”1.0″ encoding=”utf-8″?>
    <selector xmlns:android=”http://schemas.android.com/apk/res/android”>
    <item android:state_pressed=”true” android:drawable=”@drawable/my_cool_tab_red” />
    <item android:state_selected=”true” android:drawable=”@drawable/my_cool_tab_orange” />
    <item android:drawable=”@drawable/my_cool_tab_yellow” />
    </selector>

    This way, your tabs will be yellow when not active, orange when active and red when pressed. Better than showing always the same picture, isn’t it?

    WARNING: Take special care when you create this kind of assets. Make sure you don’t ever create a recursive drawable that can make your theme (and ADW.Launcher) to crash.

    For example, if you create a drawable file named res/drawable/tab_indicator.xml and put inside something like this:


    <?xml version=”1.0″ encoding=”utf-8″?>
    <selector xmlns:android=”http://schemas.android.com/apk/res/android”>
    <item android:drawable=”@drawable/tab_indicator” />
    </selector>

    You are trying to load the drawable named tab_indicator INSIDE the drawable called tab_indicator, and this one is trying to load a drawable called tab_indicator, and… that’s an issue.

    IF YOU EVER TRY TO LOAD A THEME INTO ADW.LAUNCHER AND IT JUST CRASH, CHANCES ARE 99% THE ISSUE IS CAUSED BY ONE OF THIS MISTAKES

    My advice is: never put the same name for 2 files of different types. I.e.: never create a tab_indicator.xml AND a tab_indicator.png. If you’re going to use selectors, name your PNGs any other way (i.e: my_cool_tab.png)

    ICON DATABASES

    What are the icon package and activity names you might ask? Well they are based on their given application package name and activity name which were created during the development process, therefore, each application package and activity name is unique to each application. So, each icon in the drawer corresponds to an activity, when you click the icon to open the app its respective activity is launched.

    Samples:

    • Application Name:Android Desk Clock
    • Activity Name:com.android.deskclock/.DeskClock
    • AppFilter String:ComponentInfo{com.android.deskclock/com.android.deskclock.DeskClock}
    • Converted Legacy Stringcom_android_deskclock_deskclock
    • Application Name:Google Play
    • Activity Name:com.android.vending/com.android.vending.AssetBrowserActivity
    • AppFilter String:ComponentInfo{com.android.vending/com.android.vending.AssetBrowserActivity}
    • Converted Legacy Stringcom_android_vending_assetbrowseractivity

    As you can see in the second example above (for the legacy naming convention), sometimes the activity name repeats itself. In this case we have the string com.android.vending on both sides of the backslash. For this example all you need to is cut anything that comes before the second com.android.vending, convert the text to all lower case characters and finally replace the periods (.) with an underscore (_).

    Where do you find these Component Names?

    There are a few different ways; we’ll start with the easiest. There are two public databases that contain finished activity names available to us. One is community driven in which anyone can contribute. It can be found here.

    The other one was created by Jon F. Hancock. His method requires users to install an opt-in app -available to download from Google Play here. It collects all the activity names on a user’s device and uploads them on his site: http://activities.droidicon.com/

    To find an activity name, just run a search for the app’s name and receive the proper name with the aforementioned naming convention. Sometimes it will show more than one name for the app in question which then becomes a trial and error process to find out which one is the the correct one.

    If none of these databases have the proper name of the application you want to theme, your last resort is to use DDMS (Dalvik Debug Monitor Server) (or one of the many log applications available in Google Play) and your device. More info on DDMS can be found here

    Here is quick video on how to manually get the activity names using DDMS and your device. The same procedure can be used with a simple log application, the only difference is that your computer has more screen real estate vs your phone.

    XML TIPS AND TRICKS

    If you’ve ever poked around in an apk by either reverse engineering it or looked at an apps source code, you’d know that most
    Android apps use a lot of XML’s to call upon images, layouts, styles, strings, etc. If you’re a seasoned root theme maker then you already know how these XML calls work. For the rest this might be something completely new. I’d suggest to get familiar with the way Android XML files work.

    CREATING ALIAS IMAGES VIA XML

    Sometimes you want to reuse drawables, for different theme assets (for example, to use the same icon PNG for different applications, use the same image drawable for different theme assets, or when you want your theme to support other launcherswith different asset names without duplicating images).

    Imagine you need to theme the launcher dock “dockbar_bg” and the folders popup “qa_popup” with the same image (a cool square you made with whatever graphics program).

    There are two options. One is to simply copy the image twice renaming it with each asset name, but now you have two images with different names and your apk got bigger in size.

    The second option is as easy as the first. You can simply create one image and remember that you can call drawables through an alias within an XML file. So now you can use a single image more than once. This reduces file size and makes images re-usable across all of Android.

    The process to use an XML to call the image is straight-forward, instead of copying twice the cool image you made for the dock and the folders and renaming it, just name your image something different (for example, my_cool_square.9.png).

    Now create an XML file in your theme project inside res/values, call it whatever valid name (for example, icon_aliases.xml).

    Inside this XML file we would have the following code:


    <resources>
    <drawable name=”dockbar_bg”>
    @drawable/my_cool_square
    </drawable>
    <drawable name=”qa_popup”>
    @drawable/my_cool_square
    </drawable>
    </resources>

    This code inside the XML file tells Android to use the same image (my_cool_square.9.png) for both assets (the dock and the folder popup). Now we have 1 image being used for on two assets like before but the only difference being you have a smaller apk size.

    The same process can be done as many times as you need it. All you need to do is add aliases to that XML file with whatever asset names you need pointing to your desired png drawables.

    HANDLING SPECIAL CHARACTERS

    This information is irrelevant if you use the APPFILTER method to setup your icon theme. But if you prefer the legacy method, go on and read.

    There is an issue with some application activity names where they might have special characters that if you try to use them, Eclipse throws errors at you. The classic example here is the YouTube app.

    If we apply what we learned from the App Databases section to the YouTube app, you’ll have something like this:

    Activity name: com.google.android.youtube.app.honeycomb.Shell$HomeActivity

    Drawable name:com_google_android_youtube_app_honeycomb_shell$homeactivity.png

    The work around is to make a drawable alias as seen in the previous section :


    <drawable name=”com_google_android_youtube_app_honeycomb_shell$homeactivity”>
    @drawable/my_cool_youtube_icon
    </drawable>

    This way you can use the “$” symbol for the icon name.

    COMMON ISSUES WITH ECLIPSE

    Eclipse can be a little fickle, it’s just the fact of life. Some errors even baffle me but a quick search on the Internet usually helps me find the answer.

    Eclipse only allows the use of lower case letters [a-z], numbers [0-9] and underscore. If you try to use spaces or periods on the name, Eclipse will throw out errors. Sometimes an XML you added has a misspelling inside it or you forgot to put images inside the proper /drawable folder, etc. any little thing will cause Eclipse to show errors, sometimes giving you multiple errors. To fix these errors you would need to clean your project by going to Project->Clean and select the project name and repeat the process if you continue to see these errors. Sometimes deleted the Errors on the Error List then cleaning your project can fix the issue.

    CREDITS

    This document was a group project and there are many people to thank:

    • Google for the acquiring Andy
      Rubin      ‘s OS and bringing Android to the masses!
    • Asher S. aka Vazguard for his contributions, editing, making things look great, and his easy-to-follow videos.
    • Lue G. aka Klinster for starting this awesome document and keeping ADW theme creation accessible to anyone!

Comments are closed.