FORUMS

Analysis & Opinion

Top Forum Discussions

[GUIDE] Apex Launcher Theme Tutorial

267 posts
Thanks Meter: 2,711
 
By dennisxl, Senior Member on 12th May 2012, 10:00 AM
Post Reply Subscribe to Thread Email Thread
Introduction

This tutorial helps you get started creating your own themes for Apex Launcher. Since themes are packaged and distributed in the form of APK files, you'll need to know the basics about Android app development to make themes.

Prerequisites

Before you begin, you need to set up your development environment. Please install the required software in the following order.

JDK 6
http://www.oracle.com/technetwork/ja...ads/index.html

Android SDK
http://developer.android.com/sdk/index.html

Eclipse IDE
http://www.eclipse.org/downloads/

ADT Plugin for Eclipse
http://developer.android.com/sdk/eclipse-adt.html

How to install these developer tools is not within scope of this tutorial, For details, make sure to read and follow the instructions in the links provided above.

Creating Your Theme

Apex Launcher supports different components in its theme engine. Icon packs replace app icons on the desktop, dock, and in the drawer. Apex skins allows the customization of the look and feel of the launcher itself, including dock background, folder background, icon label color, etc. You may also change the font of icon labels and provide a bunch of wallpapers along with your theme. Each theme may contain one or more components.

Here are two sample themes to help you get started. If you are just creating an icon pack, please use the icon pack sample as a base and follow the instructions below to add icons to the theme. If you want to go for a complete theme design, start with the other theme sample which includes all types of components.

Download Apex Icon Pack Sample

Download Apex Theme Sample

Regardless of which sample theme you choose, the first step is to import the sample project into Eclipse. Here are the instructions.
  1. Extract the sample archive file to your hard drive.
  2. Open Eclipse, choose "Import..." from the File menu.
  3. In the Import dialog, choose "Existing Projects into Workspace" under General, and click Next. Then browse to the sample project directory and click Finish.
  4. Change the package name. To do this, first expand the ApexIconPackSample (or ApexThemeSample) project in the Project Explorer and then expand the src folder. Now right click "com.yourname.iconpackname" (or "com.yourname.themename") and select "Refactor > Rename...". Enter your desired package name and click OK to save the change.
  5. Right click on your theme project in the Eclipse Project Explorer and select "Android Tools > Rename Application Package". Enter the same package name (as used in the previous step) and click OK.
  6. Navigate to and open "strings.xml" under "res/values" and change the theme information to your needs.
  7. Replace the icon.png files under the drawable folders to use your own icons. Note that the sample projects are configured in a way such that they will not show up in the drawer. However, the icons are still visible in the Apex Launcher theme settings.
  8. Provide a feature graphic and up to 5 preview images in your theme. These are optional, so you may just delete the entries from "strings.xml" and the corresponding image files if you decide not to provide these images.

Now, let's get down to the different components. Again, you may include any combination of the following components in your theme.

Icon Pack

First of all, please make sure config_iconpack is set to true in "strings.xml".

HTML Code:
<bool name="config_iconpack">true</bool>
This will let Apex's theme engine know that your theme includes an icon pack component.

Next, open the appfilter.xml file under the res/xml directory. (Note: This file used to be located under the assets directory, but the new app encryption feature in JellyBean made it impossible for the theme engine to access assets of paid themes.) You need to add an entry for each activity that you provide an icon for, in the following format:

HTML Code:
<item component="ComponentInfo{com.package.name/com.package.name.ActivityName}" drawable="icon_name"/>
For instance, here's how we provide an icon for the Browser app in the sample project:

HTML Code:
<item component="ComponentInfo{com.android.browser/com.android.browser.BrowserActivity}" drawable="com_android_browser_browseractivity" />
<item component="ComponentInfo{com.google.android.browser/com.android.browser.BrowserActivity}" drawable="com_android_browser_browseractivity" />
Some apps (Browser, Camera, etc.) may have different package names but they share the same activity name. Therefore, specifying both the package name and the activity name can help avoid any ambiguity if you need to provide separate icons for such apps. Please note that we do not include the file extension (.png) for the drawable attribute value.

When providing icons, please make sure they are of the right size (i.e., resolution) depending on the screen density you are targeting. Generally, Android supports these density buckets: ldpi, mdpi, hdpi, xhdpi, and xxhdpi. Please keep in mind that xxhdpi is supported starting from JellyBean, so devices running ICS may not pick it up properly. The screen resolution and icon size for each density bucket is listed below.

Code:
Density    Screen     Icon (px)
  ldpi     ~120dpi    36x36
  mdpi     ~160dpi    48x48
  hdpi     ~240dpi    72x72
 xhdpi     ~320dpi    96x96
xxhdpi     ~480dpi    144x144
It is not required to support every density bucket listed above, as icons generally can be scaled to the right size automatically. If you are targeting higher-end devices, we recommend using xhdpi (96x96) as a starting point, which should provide enough detail on high resolution screens. After you decide on the density to support, export icons as transparent PNG files and put them in the correct folder (e.g., drawable-hdpi, drawable-xhdpi).

Since it is impossible to create a themed icon for every single app, you may provide default icon background images to achieve a uniform look and feel. If provided, these background images will be placed behind each icon that does not have a specific icon created for it. If you decide to take advantage of this feature, please declare your background images in the appfilter.xml file, like this:

HTML Code:
<iconback img1="iconback" />
<iconmask img1="iconmask" />
<iconupon img1="iconupon" />
<scale factor="0.75" />
The corresponding iconback image file (e.g., iconback.png) is placed under the proper drawable directory. The sample icon pack project only provides one iconback image, but you can have multiple iconback images as well, and the theme engine would randomly pick an image for each icon.

HTML Code:
<iconback img1="iconback1" img2="iconback2" img3="iconback3" img4="iconback4" img5="iconback5" />
All the unthemed icons will be scaled to fit atop an iconback. The scale factor is also declared in appfilter.xml, with 1.0 being the actual size (no scaling).

The Apex theme engine also allows you to mask icons using a transparent image (i.e., iconmask) or place an overlay (i.e., iconupon) on top of the icons. You may use a transparent iconupon image to decorate the icons (e.g., to achieve glossy effects).

The iconback, iconmask, iconupon, and scale tags described above are all optional, so if you do not want to use these features, just delete the tags from appfilter.xml and the corresponding image files from the sample project. In addition, the theme engine supports the icon shader feature for manipulating color values in icons.

For compatibility reasons, Apex also supports icon packs that do not use an appfilter. In this case, you must name the icon files properly so that Apex Launcher can detect and use them. Here's the naming convention:
  • Icon file name should be based on the full activity name
  • Always use lower case letters for file names
  • Replace dots with underscores

For example, to add an icon for the stock Android browser (com.android.browser.BrowserActivity) in your icon pack, add an icon with the name "com_android_browser_browseractivity.png" in the proper drawable directory. In case of conflicts, appfilter has higher priority and the icon file specified there will be used.

Finding the Correct Component/Activity Name

If you do not know the name of the activity, the "Activities" shortcut list may come in handy. Just long press on your home screen and select Shortcuts > Activities. The name of each activity will be listed under the label after you expand the desired app.

Since Apex Launcher 2.0, the activity picker has been improved to help you quickly find the correct component name for the app you want to theme. For each app, the package name is listed under the name of the app, and the name of each public activity is listed under the activity label. When the package name matches the activity name prefix, the activity name starts with a dot and the prefix is omitted for brevity. Otherwise, the full activity name is provided. Note that the main activity of each app is marked in blue and is the one that will appear in the app drawer. Here are two examples:

> Messaging
com.android.mms
>> Messaging
.ui.ConversationList

The activity name starts with a dot, which means you should concatenate it with the package name. The full component name for the Messaging app should be:

HTML Code:
ComponentInfo{com.android.mms/com.android.mms.ui.ConversationList}
> Chrome
com.android.chrome
>> Chrome
com.google.android.apps.chrome.Main

In this case, the activity name does not start with a dot, and is already the full name. The full component name for the Chrome app should be:

HTML Code:
ComponentInfo{com.android.chrome/com.google.android.apps.chrome.Main}
Besides the activity picker, you may also find the following websites useful:

http://activities.droidicon.com/
http://activities.tundem.com/

The next step is to declare the icons included in your icon pack. This can be done by adding an entry for each icon to the icon_pack array in "res/values/iconpack.xml". Here's an example:

HTML Code:
<string-array name="icon_pack" translatable="false">
    <item>com_android_browser_browseractivity</item>
</string-array>
Again, we do not include the file extension (.png) in this array.

These declarations are important for the icon picker that allows users to change icons for apps/folders on the home screen. Only declared icons will appear in the icon picker when the user chooses your theme from the list.

Skin

The theme engine of Apex Launcher allows you to customize the look and feel of your desktop, dock, and drawer, by providing certain images and color values in your theme. The ApexThemeSample project includes all the things you may change, and it provides the default images and color values as the basis for your modification.

If you include a skin in your theme, make sure config_apexskin is set to true in "strings.xml".

HTML Code:
<bool name="config_apexskin">true</bool>
Feel free to use the sample theme as a starting point and replace any image in the drawable-xhdpi directory to your needs.

You may notice that some of the images are 9-patch drawables (those ending with .9.png). A nine patch graphic is a stretchable image, which Android will automatically resize to accommodate the contents. You can define stretchable regions that Android scales when the image is resized. The Draw 9-patch tool from the Android SDK allows you to easily create a nine patch graphic using a WYSIWYG editor. To learn more about nine patch graphics and the Draw 9-patch tool, please read the following references on the Android Developer’s site:

http://developer.android.com/guide/d...raw9patch.html
http://developer.android.com/guide/t...tml#nine-patch

If you decide not to change certain images from the default theme, please delete the image from your theme package. For instance, if you do not want to theme the Apex action icons, you can just delete all the "ic_*.png" files from the drawable directory, and Apex will still use the default images. Doing so will help make your theme package slim by excluding unnecessary files and it also helps improve the performance of the launcher.

You may also notice a few xml files in the drawable directory. Those are state list drawables that select from different images based on their states. If you do not theme the drawer button, you will need to delete "all_apps_button_icon.xml" after removing both "ic_allapps.png" and "ic_allapps_pressed.png". Similarly, if you do not theme the drawer tabs, you will also need to delete the "tab_*.xml" files after removing the "tab_*.png" files. Otherwise, the project won't compile because these xml files depend on the other deleted images. For more information on state list drawables, please refer to the following link:
http://developer.android.com/guide/t...html#StateList

To customize the color values for UI elements, please edit "colors.xml" and change the color values as you please.

Font

Place your custom font file under the assets folder and name it themefont.ttf. If this file is present in your theme, it will be automatically picked up by Apex Launcher. Please make sure that the font is working properly by testing it on your device.

Wallpapers

You may bundle wallpapers in your theme by putting the images inside the proper drawable directory. You also need to update "res/values/wallpapers.xml" accordingly, so that Apex will recognize the wallpapers. Here's an example from the sample theme:

HTML Code:
<string-array name="wallpapers" translatable="false">
    <item>wallpaper_escape</item>
    <item>wallpaper_outofthebox</item>
</string-array>

<string name="default_wallpaper">wallpaper_outofthebox</string>
All the wallpapers declared in the wallpapers array will be available from the Apex Launcher wallpaper chooser, while the default_wallpaper will be applied along with your theme (if the user chooses to). Note that you also need a lower-resolution preview image with a _small suffix in the file name for each wallpaper. For instance, place both wallpaper_escape.jpg and wallpaper_escape_small.jpg under the drawable directory. The preview image is only used in the wallpaper picker and the original image is used when applying the wallpaper.

Linking to Apex Theme Settings

If you like, there is a special Intent that you can use to direct users to your theme's details page in Apex theme settings, where they can apply your theme. Here's how:

Code:
final String ACTION_SET_THEME = "com.anddoes.launcher.SET_THEME";
final String EXTRA_PACKAGE_NAME = "com.anddoes.launcher.THEME_PACKAGE_NAME";

Intent intent = new Intent(ACTION_SET_THEME);
intent.putExtra(EXTRA_PACKAGE_NAME, getPackageName());
intent.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK);
try {
    startActivity(intent);
} catch (ActivityNotFoundException e) {
    Toast.makeText(this, "Apex Launcher is not installed!", Toast.LENGTH_SHORT).show();
}
finish();
You may include this piece of code inside your theme's activity (e.g., in the onCreate method) to launch Apex's theme settings. Please note that the sample projects are configured in a way such that no icon will show up in the drawer. If you need an icon for your activity, insert the android.intent.category.LAUNCHER category into the <intent-filter> section of your activity in the manifest file like this:

HTML Code:
<intent-filter>
    <action android:name="android.intent.action.MAIN" />
    <category android:name="android.intent.category.LAUNCHER" />
    <category android:name="com.anddoes.launcher.THEME" />
</intent-filter>
It is important that you must include the com.anddoes.launcher.THEME category so that Apex can recognize your theme.

Testing Your Theme

It is very important that you test your theme on a device and make sure it looks exactly the way you expect it to be. You may follow these steps to test your new theme.
  1. Connect your phone/tablet to the computer via USB.
  2. Turn on USB debugging via System settings > Developer options > USB debugging.
  3. In Eclipse, right click your theme project, select "Run As > Android Application".
  4. On your device, launch Apex theme settings and select your new theme.
  5. Apply the theme and restart the launcher.
  6. Look around and see if everything works as expected.

After you have thoroughly tested your theme, you are ready to distribute it to users.

Signing and Releasing Your Theme

To release your theme to other Apex Launcher users, you need to sign, optimize, and export the APK file, which can be done seamlessly with Eclipse and the ADT plugin. For details, please read the publishing section on the Android Developers website.

http://developer.android.com/guide/p...p-signing.html

If you publish your theme on the Google Play Store, you may want to update it later. In this case, it is very important that you version your theme properly. You may find the following link helpful.

http://developer.android.com/guide/p...ersioning.html

That's it! I hope this tutorial contains enough information to get you started working on your own themes. Happy theming!
Last edited by dennisxl; 29th September 2014 at 06:41 AM.
The Following 194 Users Say Thank You to dennisxl For This Useful Post: [ View ]
 
 
12th May 2012, 10:00 AM |#2  
dennisxl's Avatar
OP Senior Member
Thanks Meter: 2,711
 
More
Apr 29, 2013
  • Apex Launcher 2.0 now comes with an improved activity picker to help you find the right component name.
  • Updated tutorial to include a new "Finding the Correct Component/Activity Name" subsection

Jan 17, 2013
  • Updated sample theme to include new Apex Action icons.

Dec 6, 2012
  • Updated sample projects to support iconmask.
  • Updated tutorial to include a brief discussion on icon sizes.

Oct 10, 2012
  • Updated sample theme to support icon label shadow colors.

Sep 24, 2012
  • Updated sample projects for better iconpack support.
  • Updated tutorial in accordance with latest Eclipse/ADT.

May 22, 2012
  • Added support for iconback and iconupon in v1.2.1
  • Updated sample projects to include default iconback and iconupon images
  • Updated tutorial with iconback and iconupon descriptions

May 18, 2012
  • Added support for appfilter in v1.2.0beta3
  • Updated sample projects to include appfilter and new Apex action icons
  • Updated tutorial with appfilter descriptions
Last edited by dennisxl; 30th April 2013 at 05:27 AM.
The Following 26 Users Say Thank You to dennisxl For This Useful Post: [ View ]
12th May 2012, 05:22 PM |#3  
arcanexvi's Avatar
Senior Member
Hoffman Estates, IL
Thanks Meter: 352
 
More
Awesome addition to a great launcher. Looking forward to seeing some epic themes.
The Following 2 Users Say Thank You to arcanexvi For This Useful Post: [ View ]
12th May 2012, 07:03 PM |#4  
scottx .'s Avatar
Senior Member
Flag San Antonio, Texas
Thanks Meter: 816
 
More
Can't wait for some great themes. Apex is so win, uNF!

Sent from my Galaxy Tab 2 7.0 w/Tapatalk 2
12th May 2012, 11:42 PM |#5  
drakenabarion's Avatar
Senior Member
Flag Kildare
Thanks Meter: 136
 
More
Oh great. Well laid out template.

Just to check, I don't need to change XML files if I was to populate the hdpi/mdpi/ldpi folders with images in this template, as everything is already setup to accept those files? I just should delete whichever file entries from the XML that I don't want to theme?

Or has it been setup to only use the files from the XML folder at this point.

I am planning to make a red holo theme but haven't finished downloading the sdk yet. (Travelling, its going to take some time).

Sent from my GT-I9000 running CM9 (ICS 4.0.4) using XDA premium app
12th May 2012, 11:48 PM |#6  
LiLChris06's Avatar
Senior Member
Flag XDA
Thanks Meter: 1,282
 
More
Very nice!
The Following User Says Thank You to LiLChris06 For This Useful Post: [ View ]
13th May 2012, 03:13 AM |#7  
-DarkKnight-'s Avatar
Senior Member
Flag Gotham
Thanks Meter: 1,233
 
More
themes
will these themes be dependent on phone resolution or will they work on any phone with apex launcher because my phone is mdpi and i am worried that my phone will have no themes
The Following User Says Thank You to -DarkKnight- For This Useful Post: [ View ]
13th May 2012, 05:00 AM |#8  
kovdev's Avatar
Member
Thanks Meter: 59
 
More
If a theme already supports ADW/Go icon packs, do you recommend including the Apex specific code? I'm just trying to think about all the overlap between the various launchers and the resources included in the theme.

Edit: NVM. Just re-read the part about Apex free only supporting Apex themes. That means Apex code will definitely be needed. Thanks.
Last edited by kovdev; 13th May 2012 at 06:11 AM.
The Following User Says Thank You to kovdev For This Useful Post: [ View ]
13th May 2012, 07:17 AM |#9  
kovdev's Avatar
Member
Thanks Meter: 59
 
More
Two suggestions/questions.

A) If a theme supports multiple launchers, potentially /ignore the other configurations and only list Apex? See my screenshot for details. I also noticed that if you add Apex theme support, the Go launcher entry is no longer listed. I think it'd be smart to consolidate a theme (that supports multiple launchers) down to a single entry.

B) Would you be willing to add an intent, similar to GO/ADW.EX, that would allow a theme to direct a user to the Theme Settings activity? I'd really like the ability to bring a user directly to the settings from my dashboard.

Screenshot:

13th May 2012, 07:31 AM |#10  
docsparks's Avatar
Senior Member
Thanks Meter: 242
 
Donate to Me
More
Quote:
Originally Posted by Koveleski


B) Would you be willing to add an intent, similar to GO/ADW.EX, that would allow a theme to direct a user to the Theme Settings activity? I'd really like the ability to bring a user directly to the settings from my dashboard.

Thats key.

And/or have an intent we can flag so we can continue to use the 'apply theme' feature within our apps.
14th May 2012, 03:11 PM |#11  
joshuas_79's Avatar
Senior Member
Flag Cordoba
Thanks Meter: 499
 
More
well, here's my first theme for Apex Launcher
Last edited by diestarbucks; 16th July 2013 at 07:20 PM.
The Following 5 Users Say Thank You to joshuas_79 For This Useful Post: [ View ]

Read More
Post Reply Subscribe to Thread

Tags
apex, apex launcher, icon pack, launcher, theme

Guest Quick Reply (no urls or BBcode)
Message:
Previous Thread Next Thread
Thread Tools Search this Thread
Search this Thread:

Advanced Search
Display Modes