David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 1 | Android Emulator Skin File Specification: |
| 2 | ========================================= |
| 3 | |
Siva Velusamy | 2abcdc4 | 2012-10-04 17:44:27 -0700 | [diff] [blame] | 4 | Revisions: |
| 5 | ---------- |
David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 6 | Revision 2. Dated 2009-12-07 |
Siva Velusamy | 2abcdc4 | 2012-10-04 17:44:27 -0700 | [diff] [blame] | 7 | Dynamic Layout support added 10/2012 |
David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 8 | |
| 9 | Introduction: |
| 10 | ------------- |
| 11 | |
| 12 | The Android emulator program is capable of displaying a window containing |
| 13 | an image of a fake handset and associated controls (e.g. D-Pad, trackball, |
| 14 | keyboard). |
| 15 | |
| 16 | The content of this window is dictated by a "skin", i.e. a collection of |
| 17 | images and configuration data that indicates how to populate the window. |
| 18 | Each skin can have several "layouts" (e.g. "landscape" and "portrait") |
| 19 | corresponding to different orientation / physical configurations of the |
| 20 | emulated handset. |
| 21 | |
| 22 | This document specifies how to generate a new skin for the emulator. |
Siva Velusamy | 2abcdc4 | 2012-10-04 17:44:27 -0700 | [diff] [blame] | 23 | The emulator also supports dynamically creating the layout section of |
| 24 | the skin, thereby removing the necessity to create skins for each new |
| 25 | handset type. See the last section regarding info on dynamic controls. |
David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 26 | |
| 27 | General File Format: |
| 28 | -------------------- |
| 29 | |
| 30 | Each "skin" has a unique name and corresponds to a directory filled with |
| 31 | various files. All skins are located under a parent "skin-dir" directory. |
| 32 | You can use the '-skin-dir <path>' and '-skin <name>' options when starting |
| 33 | the emulator to specify them. This will instruct the program to look into |
| 34 | |
| 35 | <path>/<name>/ |
| 36 | |
| 37 | For skin-specific files. Without these options, the emulator will look for |
| 38 | skins in the SDK in a way described later in this document. |
| 39 | |
| 40 | The most important file in a skin must be named 'layout', as in: |
| 41 | |
| 42 | <path>/<name>/layout |
| 43 | |
| 44 | The format of this file must follow the "aconfig" specification, see |
| 45 | docs/ANDROID-CONFIG-FILES.TXT for details about it. |
| 46 | |
| 47 | |
| 48 | Layouts & Parts: |
| 49 | ---------------- |
| 50 | |
| 51 | Each skin file must define a list of 'parts' and a list of 'layouts'. |
| 52 | |
| 53 | A 'skin part' correspond to a named item that can contain a set of |
| 54 | visual/control elements that can be of the following types: |
| 55 | |
| 56 | - 'background': A background image in PNG format. |
| 57 | |
| 58 | - 'display': An emulated LCD screen area. |
| 59 | |
| 60 | - 'buttons': A set of clickable control areas (e.g. for a D-Pad, or |
| 61 | a Keyboard) |
| 62 | |
| 63 | Each part can be independently positioned and/or rotated in a 'layout'. |
| 64 | A 'skin layout' is simply a specific arrangement of parts. A typical device |
| 65 | skin file contains two layouts: one for landscape mode, and another one for |
| 66 | portrait mode. More layouts can be used if needed. For example, one could |
| 67 | use portrait + landscape-with-keyboard-closed + landscape-with-keyboard-opened) |
| 68 | |
| 69 | |
| 70 | Skin Layouts: |
| 71 | ------------- |
| 72 | |
| 73 | Each skin layout is a named sub-key of the top-level 'layouts' key in the |
| 74 | config file, for example: |
| 75 | |
| 76 | layouts { |
| 77 | portrait { |
| 78 | .... |
| 79 | } |
| 80 | landscape { |
| 81 | .... |
| 82 | } |
| 83 | } |
| 84 | |
| 85 | Defines two layouts named 'portrait' and 'landscape'. |
| 86 | |
| 87 | Each layout can have the following keys (and corresponding values): |
| 88 | |
| 89 | - 'width': The width of the emulator window in pixels, as an integer |
| 90 | |
| 91 | - 'height': The height of the emulator window in pixels, as an integer |
| 92 | |
| 93 | - 'color' : Background color to be used to fill the emulator window. |
| 94 | this is a 32-bit ARGB value, the 0x prefix can be used to |
| 95 | use hexadecimal notation. |
| 96 | |
| 97 | - 'event' : An optional specific Linux event code that is generated whenever |
| 98 | the emulator switches/initializes this layout. This is used to |
| 99 | emulate the 'keyboard-lid open/close' events when emulating |
| 100 | certain devices with a hardware keyboard. |
| 101 | |
| 102 | The value must be of the format: |
| 103 | |
| 104 | <type>:<code>:<value> |
| 105 | |
| 106 | Where the event type, code and value are numerical values or, |
| 107 | in certain cases string aliases for Linux input-subsystem event |
| 108 | codes. You can use the following emulator console commands to |
| 109 | print valid types and codes: |
| 110 | |
| 111 | event types -> prints all valid types |
| 112 | event codes <type> -> prints all valid codes for <type> |
| 113 | |
| 114 | The typical event to be used is EV_SW:0:1 for portrait mode |
| 115 | and EV_SW:0:0 for landscape ones. They corresponds to "keyboard |
| 116 | closed" and "keyboard opened" respectively, and would match a |
| 117 | device like the T-Mobile G1 or the Verizon Droid. |
| 118 | |
Arthur Blume | 03dadd1 | 2014-03-04 18:03:27 -0500 | [diff] [blame] | 119 | - 'onion' : Specifies an image to overlay on the display. Each such key may |
| 120 | contain the following sub-keys: |
| 121 | - 'image' [required]: Filename of image to overlay |
| 122 | - 'alpha' [optional]: How opaque the image should be, from 0 (not |
| 123 | visible at all) to 100 (fully opaque). Default is 50. |
| 124 | - 'rotation' [optional]: Integer in the 0..3 range, specifying the |
| 125 | rotation of the image in 90-degree increments. |
| 126 | |
David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 127 | - 'part<n>': Individual part references for the layout. They are named |
| 128 | in incremental numerical order, starting from 'part1', as in |
| 129 | 'part1', 'part2', 'part3', etc... |
| 130 | |
| 131 | Each such key must contain the following sub-keys: |
| 132 | |
| 133 | - 'name': The name of the corresponding part to be displayed |
| 134 | as defined in the rest of the configuration file |
| 135 | |
| 136 | - 'x': Horizontal offset where the part is displayed |
| 137 | - 'y': Vertical offset where the part is displayed |
| 138 | |
| 139 | - 'rotation': An optional sub-key which value is a integer |
| 140 | in the 0..3 range specifying the rotation |
| 141 | (in 90-degrees increment) to apply to the part |
| 142 | before display. |
| 143 | |
| 144 | - 'dpad-rotation': |
| 145 | An option integer in the 0..3 range indicating which |
| 146 | counter-rotation (in 90-degrees increments) to apply to the |
| 147 | D-Pad keys for proper usage. |
| 148 | |
| 149 | This is needed because the Android framework considers that |
| 150 | the DPad is in landscape mode when the device is in landscape |
| 151 | mode and will-auto-rotate the D-Pad value. This setting is used |
| 152 | to counter-effect this correction for certain skins which |
| 153 | do not rotate the DPad in landscape mode. |
| 154 | |
Arthur Blume | 03dadd1 | 2014-03-04 18:03:27 -0500 | [diff] [blame] | 155 | |
| 156 | |
David 'Digit' Turner | 39fd849 | 2009-12-07 16:44:47 -0800 | [diff] [blame] | 157 | Skin Parts: |
| 158 | ----------- |
| 159 | |
| 160 | Each skin part is a sub-key of the top-level 'parts' key in the configuration |
| 161 | file. For example: |
| 162 | |
| 163 | parts { |
| 164 | foo { |
| 165 | ... |
| 166 | } |
| 167 | bar { |
| 168 | ... |
| 169 | } |
| 170 | zoo { |
| 171 | ... |
| 172 | } |
| 173 | } |
| 174 | |
| 175 | Defines three parts named 'foo', 'bar' and 'zoo'. |
| 176 | |
| 177 | Each part can have one or more elements of the following type/key name that |
| 178 | will determine its visual appearance: |
| 179 | |
| 180 | - 'background': |
| 181 | A background image in PNG format. This is a tree key that can |
| 182 | have the following sub-keys: |
| 183 | |
| 184 | - 'image': Name of the PNG image in the skin directory |
| 185 | - 'x' : Optional horizontal offset in pixels (integer) |
| 186 | - 'y' : Optional vertical offset in pixels (integer) |
| 187 | |
| 188 | - 'display': |
| 189 | An optional rectangular area that will appear on top of the |
| 190 | background image to display an emulated LCD screen. Valid sub-keys |
| 191 | are: |
| 192 | |
| 193 | - 'x' : Optional horizontal offset in pixels (integer) |
| 194 | - 'y' : Optional vertical offset in pixels (integer) |
| 195 | - 'width' : Width in pixels (integer) |
| 196 | - 'height' : Height in pixels (integer) |
| 197 | - 'rotation': Optional rotation value (0..3) in 90 degrees |
| 198 | increments. |
| 199 | |
| 200 | - 'buttons': |
| 201 | Used to define a list of rectangular clickable control areas with |
| 202 | an optional high-lighting image. Each sub-key must have a unique |
| 203 | name, and may contain the following sub-sub-keys: |
| 204 | |
| 205 | - 'x' : Horizontal offset in pixels (integer) |
| 206 | - 'y' : Vertical offset in pixels (integer) |
| 207 | - 'image' : PNG image of the high-lighting for the button |
| 208 | |
| 209 | Each highlight image will be drawn on top of the background are for |
| 210 | the button. A typical one has 50% opacity. The highlight will be drawn |
| 211 | twice to simulate 'clicked' state. |
| 212 | |
| 213 | The image's dimensions are used to determine the size of the control |
| 214 | area. |
| 215 | |
| 216 | The name of each button must correspond to the list of key symbols |
| 217 | defined in the _keyinfo_table array defined in android/skin/file.c. |
| 218 | |
| 219 | Other top-level keys: |
| 220 | --------------------- |
| 221 | |
| 222 | A few other top-level keys are supported for legacy reasons, but the |
| 223 | corresponding definition is best defined in the hardware properties/config |
| 224 | file instead: |
| 225 | |
| 226 | - 'keyboard.charmap': |
| 227 | Optional, must be the name of the charmap being used for this |
| 228 | skin. Currently unused so ignore this. |
| 229 | |
| 230 | - 'network.speed': |
| 231 | Default network speed for this skin. Values correspond to the |
| 232 | -netspeed <speed> emulator command-line option. |
| 233 | |
| 234 | - 'network.delay': |
| 235 | Default network latency for this skin. Values correspond to the |
| 236 | -netdelay <delay> emulator command-line option. |
Siva Velusamy | 2abcdc4 | 2012-10-04 17:44:27 -0700 | [diff] [blame] | 237 | |
| 238 | Dynamic Layouts: |
| 239 | ---------------- |
| 240 | |
| 241 | The emulator also supports a skin that is dynamically generated. This |
| 242 | skin (present in folder "dynamic" in the skins folder) follows the same |
| 243 | format as other skins, except that it only defines the list of parts/controls |
| 244 | that can be used in the skin. The layouts section is generated at |
| 245 | runtime by the emulator. The parts section describes all the controls that |
| 246 | can be used in any handset. All these parts have both an enabled and a |
| 247 | disabled version defined in the skin, and at runtime the emulator reads |
| 248 | the hardware definition and decides which of those two controls to actually |
| 249 | use. |