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/java/javase/downloads/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.
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".
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:
For instance, here's how we provide an icon for the Browser app in the sample project:
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.
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:
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.
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:
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:
> 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:
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:
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".
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/developing/tools/draw9patch.html
http://developer.android.com/guide/topics/graphics/2d-graphics.html#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/topics/resources/drawable-resource.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:
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:
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:
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.
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/publishing/app-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/publishing/versioning.html
That's it! I hope this tutorial contains enough information to get you started working on your own themes. Happy theming!
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/java/javase/downloads/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.
- Extract the sample archive file to your hard drive.
- Open Eclipse, choose "Import..." from the File menu.
- In the Import dialog, choose "Existing Projects into Workspace" under General, and click Next. Then browse to the sample project directory and click Finish.
- 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.
- 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.
- Navigate to and open "strings.xml" under "res/values" and change the theme information to your needs.
- 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.
- 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:
<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:
<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:
<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 144x144It 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:
<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:
<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:
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:
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:
<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:
<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/developing/tools/draw9patch.html
http://developer.android.com/guide/topics/graphics/2d-graphics.html#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/topics/resources/drawable-resource.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:
<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:
<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.
- Connect your phone/tablet to the computer via USB.
- Turn on USB debugging via System settings > Developer options > USB debugging.
- In Eclipse, right click your theme project, select "Run As > Android Application".
- On your device, launch Apex theme settings and select your new theme.
- Apply the theme and restart the launcher.
- 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/publishing/app-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/publishing/versioning.html
That's it! I hope this tutorial contains enough information to get you started working on your own themes. Happy theming!
Last edited:
