Android Emulator Skin File Specification: ========================================= Revisions: ---------- Revision 2. Dated 2009-12-07 Dynamic Layout support added 10/2012 Introduction: ------------- The Android emulator program is capable of displaying a window containing an image of a fake handset and associated controls (e.g. D-Pad, trackball, keyboard). The content of this window is dictated by a "skin", i.e. a collection of images and configuration data that indicates how to populate the window. Each skin can have several "layouts" (e.g. "landscape" and "portrait") corresponding to different orientation / physical configurations of the emulated handset. This document specifies how to generate a new skin for the emulator. The emulator also supports dynamically creating the layout section of the skin, thereby removing the necessity to create skins for each new handset type. See the last section regarding info on dynamic controls. General File Format: -------------------- Each "skin" has a unique name and corresponds to a directory filled with various files. All skins are located under a parent "skin-dir" directory. You can use the '-skin-dir ' and '-skin ' options when starting the emulator to specify them. This will instruct the program to look into // For skin-specific files. Without these options, the emulator will look for skins in the SDK in a way described later in this document. The most important file in a skin must be named 'layout', as in: //layout The format of this file must follow the "aconfig" specification, see docs/ANDROID-CONFIG-FILES.TXT for details about it. Layouts & Parts: ---------------- Each skin file must define a list of 'parts' and a list of 'layouts'. A 'skin part' correspond to a named item that can contain a set of visual/control elements that can be of the following types: - 'background': A background image in PNG format. - 'display': An emulated LCD screen area. - 'buttons': A set of clickable control areas (e.g. for a D-Pad, or a Keyboard) Each part can be independently positioned and/or rotated in a 'layout'. A 'skin layout' is simply a specific arrangement of parts. A typical device skin file contains two layouts: one for landscape mode, and another one for portrait mode. More layouts can be used if needed. For example, one could use portrait + landscape-with-keyboard-closed + landscape-with-keyboard-opened) Skin Layouts: ------------- Each skin layout is a named sub-key of the top-level 'layouts' key in the config file, for example: layouts { portrait { .... } landscape { .... } } Defines two layouts named 'portrait' and 'landscape'. Each layout can have the following keys (and corresponding values): - 'width': The width of the emulator window in pixels, as an integer - 'height': The height of the emulator window in pixels, as an integer - 'color' : Background color to be used to fill the emulator window. this is a 32-bit ARGB value, the 0x prefix can be used to use hexadecimal notation. - 'event' : An optional specific Linux event code that is generated whenever the emulator switches/initializes this layout. This is used to emulate the 'keyboard-lid open/close' events when emulating certain devices with a hardware keyboard. The value must be of the format: :: Where the event type, code and value are numerical values or, in certain cases string aliases for Linux input-subsystem event codes. You can use the following emulator console commands to print valid types and codes: event types -> prints all valid types event codes -> prints all valid codes for The typical event to be used is EV_SW:0:1 for portrait mode and EV_SW:0:0 for landscape ones. They corresponds to "keyboard closed" and "keyboard opened" respectively, and would match a device like the T-Mobile G1 or the Verizon Droid. - 'part': Individual part references for the layout. They are named in incremental numerical order, starting from 'part1', as in 'part1', 'part2', 'part3', etc... Each such key must contain the following sub-keys: - 'name': The name of the corresponding part to be displayed as defined in the rest of the configuration file - 'x': Horizontal offset where the part is displayed - 'y': Vertical offset where the part is displayed - 'rotation': An optional sub-key which value is a integer in the 0..3 range specifying the rotation (in 90-degrees increment) to apply to the part before display. - 'dpad-rotation': An option integer in the 0..3 range indicating which counter-rotation (in 90-degrees increments) to apply to the D-Pad keys for proper usage. This is needed because the Android framework considers that the DPad is in landscape mode when the device is in landscape mode and will-auto-rotate the D-Pad value. This setting is used to counter-effect this correction for certain skins which do not rotate the DPad in landscape mode. Skin Parts: ----------- Each skin part is a sub-key of the top-level 'parts' key in the configuration file. For example: parts { foo { ... } bar { ... } zoo { ... } } Defines three parts named 'foo', 'bar' and 'zoo'. Each part can have one or more elements of the following type/key name that will determine its visual appearance: - 'background': A background image in PNG format. This is a tree key that can have the following sub-keys: - 'image': Name of the PNG image in the skin directory - 'x' : Optional horizontal offset in pixels (integer) - 'y' : Optional vertical offset in pixels (integer) - 'display': An optional rectangular area that will appear on top of the background image to display an emulated LCD screen. Valid sub-keys are: - 'x' : Optional horizontal offset in pixels (integer) - 'y' : Optional vertical offset in pixels (integer) - 'width' : Width in pixels (integer) - 'height' : Height in pixels (integer) - 'rotation': Optional rotation value (0..3) in 90 degrees increments. - 'buttons': Used to define a list of rectangular clickable control areas with an optional high-lighting image. Each sub-key must have a unique name, and may contain the following sub-sub-keys: - 'x' : Horizontal offset in pixels (integer) - 'y' : Vertical offset in pixels (integer) - 'image' : PNG image of the high-lighting for the button Each highlight image will be drawn on top of the background are for the button. A typical one has 50% opacity. The highlight will be drawn twice to simulate 'clicked' state. The image's dimensions are used to determine the size of the control area. The name of each button must correspond to the list of key symbols defined in the _keyinfo_table array defined in android/skin/file.c. Other top-level keys: --------------------- A few other top-level keys are supported for legacy reasons, but the corresponding definition is best defined in the hardware properties/config file instead: - 'keyboard.charmap': Optional, must be the name of the charmap being used for this skin. Currently unused so ignore this. - 'network.speed': Default network speed for this skin. Values correspond to the -netspeed emulator command-line option. - 'network.delay': Default network latency for this skin. Values correspond to the -netdelay emulator command-line option. Dynamic Layouts: ---------------- The emulator also supports a skin that is dynamically generated. This skin (present in folder "dynamic" in the skins folder) follows the same format as other skins, except that it only defines the list of parts/controls that can be used in the skin. The layouts section is generated at runtime by the emulator. The parts section describes all the controls that can be used in any handset. All these parts have both an enabled and a disabled version defined in the skin, and at runtime the emulator reads the hardware definition and decides which of those two controls to actually use.