diff options
| -rw-r--r-- | android/utils/ini.h | 32 | ||||
| -rw-r--r-- | docs/ANDROID-CONFIG-FILES.TXT | 103 | ||||
| -rw-r--r-- | docs/ANDROID-SKIN-FILES.TXT | 221 |
3 files changed, 325 insertions, 31 deletions
diff --git a/android/utils/ini.h b/android/utils/ini.h index a176bfe..83d2027 100644 --- a/android/utils/ini.h +++ b/android/utils/ini.h @@ -15,37 +15,7 @@ #include <stdint.h> /* the emulator supports a simple .ini file format for its configuration - * files. Here's the BNF for it: - * - * file := <line>* - * line := <comment> | <LF> | <assignment> - * comment := (';'|'#') <noLF>* <LF> - * assignment := <space>* <keyName> <space>* '=' <space>* <valueString> <space>* <LF> - * keyName := <keyNameStartChar> <keyNameChar>* - * keyNameStartChar := [A-Za-z_] - * keyNameChar := [A-Za-z0-9_.-] - * valueString := <noLF>* - * space := ' ' | '\t' - * LF := '\r\n' | '\n' | '\r' - * noLF := [^<LF>] - * - * Or, in English: - * - * - no support for sections - * - empty lines are ignored, as well as lines beginning with ';' or '#' - * - lines must be of the form: "<keyName> = <value>" - * - key names must start with a letter or an underscore - * - other key name characters can be letters, digits, underscores, dots or dashes - * - * - leading and trailing space are allowed and ignored before/after the key name - * and before/after the value - * - * - there is no restriction on the value, except that it can't contain - * leading/trailing space/tab characters or newline/charfeed characters - * - * - empty values are possible, and will be stored as an empty string. - * - any badly formatted line is discarded (and will print a warning) - * + * files. See docs/ANDROID-CONFIG-FILES.TXT for details. */ /* an opaque structure used to model an .ini configuration file */ diff --git a/docs/ANDROID-CONFIG-FILES.TXT b/docs/ANDROID-CONFIG-FILES.TXT new file mode 100644 index 0000000..633b57a --- /dev/null +++ b/docs/ANDROID-CONFIG-FILES.TXT @@ -0,0 +1,103 @@ +Android Emulator Config File Formats: +==================================== + +Introduction: +------------- + +The Android emulator supports several file formats for its configuration +files, depending on specific usage. This file documents them. + + +I. Android .ini configuration files: +------------------------------------ + +The code in android/utils/ini.[hc] is used to support a simple .ini file +format for some configuration files. Here's the BNF for it: + + file := <line>* + line := <comment> | <LF> | <assignment> + comment := (';'|'#') <noLF>* <LF> + assignment := <space>* <keyName> <space>* '=' <space>* <valueString> <space>* <LF> + keyName := <keyNameStartChar> <keyNameChar>* + keyNameStartChar := [A-Za-z_] + keyNameChar := [A-Za-z0-9_.-] + valueString := <noLF>* + space := ' ' | '\t' + LF := '\r\n' | '\n' | '\r' + noLF := [^<LF>] + +Or, in plain English: + + - No support for sections + - Empty lines are ignored, as well as lines beginning with ';' or '#' + - Lines must be of the form: "<keyName> = <value>" + - Key names must start with a letter or an underscore + - Other key name characters can be letters, digits, underscores, dots or + dashes + + - Leading and trailing space are allowed and ignored before/after the key + name and before/after the value + + - There is no restriction on the value, except that it can't contain + leading/trailing space/tab characters or newline/charfeed characters + + - Empty values are possible, and will be stored as an empty string. + - Any badly formatted line is discarded (and will print a warning) + + +II. Android 'aconfig' configuration files: +------------------------------------------ + +Alternatively, another configuration file format is supported by the code +in android/config.[hc]. Its purpose is to support each config file as a +tree of key/value pairs. More specifically: + + - Each key or value is a string + - Each key can be associated either to a value, or a sub-tree + - A (key,value) pair is written in the config file as: + + <keyname> <value> + + which means the key name, some spaces, then the value. + + - Dots can be used to separate keys in a tree path, as in: + + some.other.name value + + corresponding to a top-level key named 'some' with a single + sub-key 'other' which itself has a sub-key 'name' associated to + value 'value'. + + - As a consequence, key names *cannot* contain a dot. + + - Alternatively, braces can be used to group sub-keys, as in: + + some { + other { + name value + name2 other-value + } + } + + which defines a top-level 'some' key with two sub-keys 'name' and + 'name2' + + - Brace and dot notations are equivalent, so the above config file + can also be written as: + + some.other.name value + some.other.name2 other-value + + - If a key appears twice in the config file, it replaces any + assigned value, hence: + + some-key foo + some-key bar + + defines 'some-key' to 'bar' + + - If a sharp (#) appears whenever a key name is expected by the parser, + then it is considered a comment and will be ignored along anything that + follows on the current line. + + diff --git a/docs/ANDROID-SKIN-FILES.TXT b/docs/ANDROID-SKIN-FILES.TXT new file mode 100644 index 0000000..004f83d --- /dev/null +++ b/docs/ANDROID-SKIN-FILES.TXT @@ -0,0 +1,221 @@ +Android Emulator Skin File Specification: +========================================= + + Revision 2. Dated 2009-12-07 + + +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. + +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 <path>' and '-skin <name>' options when starting +the emulator to specify them. This will instruct the program to look into + + <path>/<name>/ + +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: + + <path>/<name>/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: + + <type>:<code>:<value> + + 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 <type> -> prints all valid codes for <type> + + 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<n>': 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 <speed> emulator command-line option. + +- 'network.delay': + Default network latency for this skin. Values correspond to the + -netdelay <delay> emulator command-line option. |