[GUIDE] Apex Launcher Theme Tutorial

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.

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".


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:

• 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:


> 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.

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/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!

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

shader.xml tutorial

How to: use the shader.xml

So after playing with code and research, i now know how a shader actually works.

Shader.xml is a piece of code that can modify the attributes of your icons:

Each line of code says execute, target, mode, value.
basically it says in plain english "this thing, do something to it, this much:

TargetRegister: (Generally we are executing a line for its output)
O = Output
B = I don't know

TargetChannel: (This is the colour channel we wish to modify)
A = Alpha (opacity)
R = Red
G = Green
B = Blue

Mode (Mode is the modification we want to make to the colour channel)
W= Write
S = Subtract
M = Multiply
D = Divide
A = Add

Values:

InputRegister = I

InputChannel:
A = Alpha (opacity)
R = Red
G = Green
B = Blue

RegisterValue
I = Intensity (at each pixel)
H = Overall brightness of image
(so a value of "IA" outputs the same value as the alpha channel had on input)

Value = 0 - 255

Ok Sam, all very interesting and technical, how do I use it?

First off, (mostly for noobs) wrap everything else inside this:


Next the (target)channels need to be written down before anything else.
Tip
Even if you modify one channel only, you still need to 'write' them all


In effect this piece of code writes each channel down as it is: "output target is write input channel" (write down what you have) from here you can make modifications.


Now we can modify the parameters, most of these thing happen in 2 or 3 steps,
i'll start with an easy one bear with me here...

Example A. - Change Alpha levels
Write Channels > make Alpha 75%

My 192 Series themes: 192 Series Colours Plus, 192 Series Colours Lite are designed around having every icon semi transparent. The alpha level of each icon is 192 (see what i did there?)

I wanted to make the alpha level of any unthemed icon 192.

I know the required output is (up to) 192
I know the input is (up to) 255
Maths tells me thats 75% of the original value, so its easy to Multiply by 0.75

It is also possible to Divide 255 / 1.33 = 192, or Subtract 255 - 63 = 192


Example B - Greyscale
Write channels [Colour neutral/Grey] > make alpha 75%

We know that "II" is "Input Intensity" the below code will write Alpha as it is and the colours neutral - Most people are now familiar with the greyscale code:
Then I Add the Alpha, this works on my 192 Series Black Theme

Example C - Add Colour
Write channels [Colour neutral/Grey] > make alpha 75% > Colour Red

This will colour every unthemed icon in my 192 Series Red theme, surprisingly enough, red.........


Example D - Contrast
Write channels > Subtract the overall brightness > Multiply each channel by 1.2 > Add the overall brightness back.



Example E - Saturation

Write channels > Subtract Intensity > Multiply each channel by 1.4 > Add Intensity



Example F - Invert

This one's kind of neat, pretty much says, write 255, then subtract the input value
So what ever you colour channel value is, the will give you the opposite, inverting the icon.





That should give you all an understanding of how the shader works, specific examples, and the ability to write your own..

Just a heads up, Android 4.3 has a new activity for the Phone/Dialer. You'll need to add an additional line into your appfilter. The correct pkg/activity is as follows:


You should get this taken care of now before everyone starts upgrading, otherwise you may get stuck with lower ratings on the market or a flooded inbox.

pooley:) said:

Would be nice if someone can post a shader code for :
- only display black/white icons (well it's more greyscale but not pure black)
- only display bluescale
- vivid colors

thanks guys

Click to expand...

Click to collapse

Don't exactly know what you want from words,
but give you some examples here

- only display black/white icons (well it's more greyscale but not pure black)

- only display bluescale

- vivid colors
I am not sure what "vivid color" is, maybe increase contrast can lead to the result