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