Add two documentation files describing the format of config and skin files.

1 files changed, 221 insertions, 0 deletions

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.