docs/ANDROID-SKIN-FILES.TXT - platform/external/qemu - Git at Google

 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 <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.

 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.
	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 <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.

	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.