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