Create Themes

Think you can create a nice theme for Android Pro Widgets?
Here is all the info you need.
If you have any question just post a comment or email us.
The templates are still work in progress but are completely usable.

Prerequisite

  • You will need to set up some development environment but you do not need any programming knowledge. 
  • Learn 9 patch format
  • Know how to use Photoshop or Paint .NET ;) 

Download

UPDATE (01/22/2012)
As of version 1.2.4 APW targets ICS so themes should set padding as 0 on API level 14.
I updated the template accordingly and also added new ICS theme template.

Environment setup

  • Follow Steps 1-4 of this page.
    On step 4 you only need Basic components with API 8. 
  • Open Eclipse 
  • From Eclipse go to Window → Preferences → Android
  • Make sure the path of the SDK Location is correct and that Android 2.2 is included in the table below. Click OK but keep Eclipse open. 
  • From Eclipse go to File → Import → General → Existing Project Into Workspace
  • Set Archive File to the Template Theme Project you downloaded before and click OK. 
  • You will see on the Package Explorer the new project 
  • Right click on the project and select Refactor → Rename. Give the project your own name. 
  • Right click on the project and select Android Tools → Rename Application Package. Change the package name to your own name. 
  • From Package Explorer open the file res/values/strings.xml and change app_name to your own theme name. Make sure it starts with APW Theme. 

Project structure

From this point you will only need to make changes in the res folder.

For a simple theme you can skip all this and just replace the images in drawable-hdpi (See the Images section) and change values/bool/use_dark_text to match your background image.

> color
Advanced color resources to be used internally from your layout files.
You may change existing files or add new files.

> drawabe
Android targets multiple devices so there are several directories for images named drawable-*:
drawable - A folder for shapes created by XML - this allows both simple shapes like rectangle and advanced drawables for using different images depending on current state (see button_background_selectol.xml for example).
drawable-hdpi - A folder for most common resolutions (480x800, 480x854). Usually you only need to create images in this directory and android will scale the images properly on other resolutions.
Use 9 patch format where the images should stretch.
drawable-mdpi - A folder for medium resolution devices.
drawable-ldpi - A folder for low resolution devices.
drawable-xhdpi - A folder for extra high resolution devices like tablets and galaxy nexus. For high resolution themes that will look good on any device create big images here (see dimensions below to understand how scaling will affect your images).
You can read more here.

> values
Here you can add constant values like colors and strings.
You can add values that will be used internally by your layout but you can also add values that will be used by APW to override the default theme's values. These values can be overridden:
  • values/bool/no_thin_frame - Indicated thin frame mode support 
  • values/bool/show_scrollbars - Set to false to disable scroll bars in lists and grids. 
  • values/bool/calendar_short_header - Set to true to show today in calendar header (short format). 
  • values/bool/use_dark_text - Set to true if your background is light, set to false otherwise. Remove this entry if you want to keep the current user setting (useful for fully transparent themes). 
  • values/color/links_color - Change links color in the Timeline/Facebook/Twitter widgets. 
  • values/color/header_text_color- Override header text color. Normally you don't want to add this value because the theme already uses whatever you put in your layout files. 
  • values/color/text_color- Override text color to all text fields in the widget.
> layout 
Here you define the widget's layout.
A layout file can be included in another layout using the <include> tag.
You can see a preview of your work while creating the theme in the Graphical Layout tab.
Be aware that you are not allowed to remove existing items or change the footer's size!
The Standard template also includes comments that will help you get started.
  • base_widget_frame is the main layout used for all widgets by default.
  • base_widget_frame_thin is the layout to be used in thin frame mode.
    Has no effect if bool/no_thin_frame is set to false. 
  • widget_frame_bookmarks - layout to be used for the bookmarks widget. 
  • widget_frame_calendar - layout to be used for the calendar widget. 
  • widget_frame_facebook - layout to be used for the facebook widget. 
  • widget_frame_greader - layout to be used for the APW Google Reader. 
  • widget_frame_messaging - layout to be used for the messaging widget. 
  • widget_frame_people - layout to be used for the people widget. 
  • widget_frame_timeline - layout to be used for the timeline widget. 
  • widget_frame_twitter - layout to be used for the twitter widget.
If you don't include a layout for a specific widget then base_widget_frame or base_widget_frame_thin will be used.

Dimensions

Android targets multiple devices and thus dimensions are not measures in pixels.
sp - Scaled Pixels. Use this units for text only.
dip - Device Independent Pixels. You can also use dp which is the same.
One dip in pixels:
  • xhdpi - 2 px (tablets)
  • hdpi - 1.5 px (common phones)
  • mdpi - 1 px
  • ldpi - 0.75 px


Images

Android supports a format called 9 patch.
This format allows to to tell android how to scale your image when needed.
The top and left lines specify which parts of the image can stretch. The right and bottom lines specify content area and is used only in the header, footer and background images.
Files in this format end with .9.png. Rename to .png if your image isn't in 9 patch format.

You should change the application icon (icon.png) in all drawable-* folders.
The best practice is to create a big 512x512 icon to be used in the Android Market page and then scale it down to the appropriate size for each drawable-* folder.

The following images can be overridden by a theme:
  • widget_background_default (background of widget) 
  • widget_footer_bg_default (background of footer) 
  • widget_header_bg_default (background of header) 
  • widget_header_shadow (image below header) 
  • button_add 
  • button_agenda (calendar change to agenda view) 
  • button_calendar (calendar change to month view) 
  • button_check (messaging mark as as read action) 
  • button_compose 
  • button_edit (edit button for people widget) 
  • button_menu (header menu button for thin frame mode) 
  • button_save (save button for people widget) 
  • button_now (back to current time in calendar widget) 
  • ic_button_down (down button for calendar or any widget when scrolling is disabled) 
  • ic_button_up (up button for calendar or any widget when scrolling is disabled) 
  • ic_button_scroller (scroll button on launchers without scrolling support) 
  • button_preferences 
  • button_refresh 
  • button_home_center 
  • button_home_center_selected 
  • button_home_right 
  • button_home_right_selected 
  • button_mentions_left 
  • button_mentions_left_selected 
  • button_messages_right 
  • button_messages_right_selected 
  • button_wall_left 
  • button_wall_left_selected 
  • calendar_busy_mark (Image to be shown when a day in the calendar has an event) 
  • calendar_busy_mark_dark (Image to be shown when a day in the calendar has an event and use dark text is set to checked in settings) 
  • calendar_today (Image to be shown on the calendar's current day cell) 
  • calendar_empty (Image to be shown on all other calendar cells ) 
  • bookmarks_picture_border (grab from graphics theme for an example)
  • people_picture_border (grab from graphics theme for an example)
These are also replaceable but has no effect on some launchers (mainly Launcher Pro). If you don't want to change them just delete them from your project:
  • divider_horizontal_bright 
  • list_item_background 
  • agenda_item_background 
  • agenda_item_header_background 
  • agenda_item_header_background_light


Promoting your theme
After uploading your theme to Play Store:

  • Make sure APW Theme is mentioned in the description so it would be discoverable via search.
  • Post a link in our Facebook page and we would share it on Facebook and Twitter.