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 - 'part<n>': Individual part references for the layout. They are named 120 in incremental numerical order, starting from 'part1', as in 121 'part1', 'part2', 'part3', etc... 122 123 Each such key must contain the following sub-keys: 124 125 - 'name': The name of the corresponding part to be displayed 126 as defined in the rest of the configuration file 127 128 - 'x': Horizontal offset where the part is displayed 129 - 'y': Vertical offset where the part is displayed 130 131 - 'rotation': An optional sub-key which value is a integer 132 in the 0..3 range specifying the rotation 133 (in 90-degrees increment) to apply to the part 134 before display. 135 136 - 'dpad-rotation': 137 An option integer in the 0..3 range indicating which 138 counter-rotation (in 90-degrees increments) to apply to the 139 D-Pad keys for proper usage. 140 141 This is needed because the Android framework considers that 142 the DPad is in landscape mode when the device is in landscape 143 mode and will-auto-rotate the D-Pad value. This setting is used 144 to counter-effect this correction for certain skins which 145 do not rotate the DPad in landscape mode. 146 147 Skin Parts: 148 ----------- 149 150 Each skin part is a sub-key of the top-level 'parts' key in the configuration 151 file. For example: 152 153 parts { 154 foo { 155 ... 156 } 157 bar { 158 ... 159 } 160 zoo { 161 ... 162 } 163 } 164 165 Defines three parts named 'foo', 'bar' and 'zoo'. 166 167 Each part can have one or more elements of the following type/key name that 168 will determine its visual appearance: 169 170 - 'background': 171 A background image in PNG format. This is a tree key that can 172 have the following sub-keys: 173 174 - 'image': Name of the PNG image in the skin directory 175 - 'x' : Optional horizontal offset in pixels (integer) 176 - 'y' : Optional vertical offset in pixels (integer) 177 178 - 'display': 179 An optional rectangular area that will appear on top of the 180 background image to display an emulated LCD screen. Valid sub-keys 181 are: 182 183 - 'x' : Optional horizontal offset in pixels (integer) 184 - 'y' : Optional vertical offset in pixels (integer) 185 - 'width' : Width in pixels (integer) 186 - 'height' : Height in pixels (integer) 187 - 'rotation': Optional rotation value (0..3) in 90 degrees 188 increments. 189 190 - 'buttons': 191 Used to define a list of rectangular clickable control areas with 192 an optional high-lighting image. Each sub-key must have a unique 193 name, and may contain the following sub-sub-keys: 194 195 - 'x' : Horizontal offset in pixels (integer) 196 - 'y' : Vertical offset in pixels (integer) 197 - 'image' : PNG image of the high-lighting for the button 198 199 Each highlight image will be drawn on top of the background are for 200 the button. A typical one has 50% opacity. The highlight will be drawn 201 twice to simulate 'clicked' state. 202 203 The image's dimensions are used to determine the size of the control 204 area. 205 206 The name of each button must correspond to the list of key symbols 207 defined in the _keyinfo_table array defined in android/skin/file.c. 208 209 Other top-level keys: 210 --------------------- 211 212 A few other top-level keys are supported for legacy reasons, but the 213 corresponding definition is best defined in the hardware properties/config 214 file instead: 215 216 - 'keyboard.charmap': 217 Optional, must be the name of the charmap being used for this 218 skin. Currently unused so ignore this. 219 220 - 'network.speed': 221 Default network speed for this skin. Values correspond to the 222 -netspeed <speed> emulator command-line option. 223 224 - 'network.delay': 225 Default network latency for this skin. Values correspond to the 226 -netdelay <delay> emulator command-line option. 227 228 Dynamic Layouts: 229 ---------------- 230 231 The emulator also supports a skin that is dynamically generated. This 232 skin (present in folder "dynamic" in the skins folder) follows the same 233 format as other skins, except that it only defines the list of parts/controls 234 that can be used in the skin. The layouts section is generated at 235 runtime by the emulator. The parts section describes all the controls that 236 can be used in any handset. All these parts have both an enabled and a 237 disabled version defined in the skin, and at runtime the emulator reads 238 the hardware definition and decides which of those two controls to actually 239 use. 240
