1 Android Emulator Skin File Specification: 2 ========================================= 3 4 Revisions: 5 ---------- 6 Revision 2. Dated 2009-12-07 7 Dynamic Layout support added 10/2012 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. 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. 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 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 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 155 156 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. 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. 250
