Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

3    Using Skin Files

Palm OS® Cobalt Simulator Guide

Palm OS Cobalt Version 6.1

Using Simulator Skin Files ^TOP^

Palm OS Cobalt Simulator uses skin files to present the image of a handheld. Note that the skin is simply a graphic; it does not change the ROM or the handheld being emulated. The skin simply changes the appearance of the Simulator window.

The skin choices available are dependent on the handheld selection. When you select a handheld, Simulator reads through the available SKIN files for the skin names that support the selected handheld.

Palm OS Emulator comes with a built-in Generic skin. This skin is suitable for doing your own application testing and debugging.

However, there are times when you want Simulator to look more like a specific handheld, such as when you are using Simulator to demonstrate your application to others. This section describes how to use additional skins that are available, and how to modify or create your own skins.

Using Skin Files ^TOP^

You can select the skin file for your simulation session by using Settings > Display > Skin.

Modifying or Creating Skin Files ^TOP^

Skins are defined by a pair of files: an image file and a SKIN file that describes the image file. The image file is a graphic; currently, only BMP format is supported.

The associated SKIN file is a text file that describes the image. The text file is made up of a series of lines, each line defining an attribute of the image. Each definition is of the form:

<attribute>=<value>

This is similar to the way INI files are stored on Windows, and how Simulator saves its own preferences.

Conditions for Skin File Entries

The following conditions apply for the definitions in SKIN files:

  • The attribute is case-sensitive. For example, "Name" and "name" are not equivalent.
  • There can be only one definition of each attribute. For example, if the skin can be used with multiple handhelds, specify both handhelds on the same "Devices" definition. This definition is correct:
Devices = Pilot1000, Pilot5000

However, this definition is not correct:

Devices = Pilot1000
Devices = Pilot5000
  • White space is optional, both around the equal sign and in the specification of the value. For example, "color=1,2,3" is the same as "color = 1, 2, 3".
  • The file can include comments, which are ignored when the file is parsed. Comments appear on their own lines, and start with "#" or ';'.
  • Invalid files are detected and silently ignored. There is currently no error reporting when invalid values are encountered. Your only indication that something is wrong is that your skin won't show up in the Skins menu or dialog box.

Specifying Attributes in Skin Files

This list defines the attributes that you can use in skin files, and a describes how to specify the attribute's values.

Name
This is the name of the skin. The value is what appears in the Skin menu in the New Session dialog box and in the Skins dialog box.
Example:
Name = Keith's Cool Skin
File1x
This is the name of the single-scale BMP image file.
Example:
File1x = MySkin1.bmp
BackgroundColor
This field defines the normal color used when displaying the LCD area of Simulator's display. The value is specified as an RGB set of values. The three components are provided as hexadecimal or decimal values in the range from 0 to 255, separated by commas.
Example:
BackgroundColor = 0x7B, 0x8C, 0x5A
HighlightColor
Note: This setting is not currently supported in this release of Palm OS Cobalt Simulator.
This field defines the backlighting color used when displaying the LCD area of Simulator's display. (That is, the color used for when the user turns on backlighting by holding down the power button.)
The value is specified as an RGB set of values. The three components are provided as hexadecimal or decimal values in the range from 0 to 255, separated by commas.
Example:
HighlightColor = 132, 240, 220
Devices
Provides the list of handhelds with which this skin can be used. One or more handhelds can be provided, separated by commas. The current list of valid handhelds is:
Pilot, Pilot1000, Pilot5000, PalmPilot, PalmPilotPersonal, PalmPilotProfessional, PalmIII, PalmIIIc, PalmIIIe, PalmIIIx, PalmV, PalmVx, PalmVII, PalmVIIEZ, PalmVIIx, PalmM100, m100, PalmM105, m105, PalmM125, m125, PalmM130, m130, PalmM500, m500, PalmM505, m505, PalmM515, m515, PalmI705, i705, Symbol1500, Symbol1700, Symbol1740, TRGpro, HandEra330, Visor, VisorPlatinum, VisorPrism, VisorEdge
Examples:
Devices = Pilot1000, Pilot5000
Devices = PalmIIIc
Element#
A class of attributes that describes the layout of the image. There is one attribute for each item in the image that can be clicked on. There are also attributes for the LCD and touchscreen areas.
The value for each attribute is a list of 5 items: the name of the element and its coordinates on the screen. The current set of valid element names is:
PowerButton
The hardware on/off button.
UpButton
The hardware scroll up button.
DownButton
The hardware scroll down button.
App1Button
The first application button (usually the Date Book application button).
App2Button
The second application button (usually the Address Book application button).
App3Button
The third application button (usually the To Do List application button).
App4Button
The fourth application button (usually the Memo Pad application button).
CradleButton
The HotSync® operation button.
Antenna
The trigger for raising the antenna.
ContrastButton
The hardware dial for setting screen contrast.
Touchscreen
The full screen area, including the area.
LCD
The application screen area, excluding the area.
Symbol-specific Values:
TriggerLeft
TriggerCenter
TriggerRight
UpButtonLeft
UpButtonRight
DownButtonLeft
DownButtonRight

All elements except for Touchscreen and LCD are optional.

The coordinates of each element are provided by specifying the left coordinate, the top coordinate, the element width, and the element height. Only single-scale coordinates can be provided; double-scale coordinates are derived from these. Coordinate values can be specified in hexadecimal or decimal.

Each attribute name must start with the text "Element", and must be suffixed with characters that make it unique from all the other element-related attributes.

Listing 3.1 shows an example of a skin file.

Listing 3.1 Example of a Skin File


# This is a skin file for Palm OS Cobalt Simulator.  See the ReadMe.txt 
# file in this directory for a description of its contents. 
 
Name                    = Standard-English 
File1x                  = Palm_III_16.bmp 
BackgroundColor         = 0x7B, 0x8C, 0x5A 
HighlightColor          = 0x64, 0xF0, 0xDC 
Devices                 = PalmIII 
 
#                                                x    y    w    h  
#                                                ---- ---- ---- ----  
Element1                = PowerButton,           10, 295,  16,  24 
Element2                = UpButton,             110, 292,  20,  21 
Element3                = DownButton,           110, 313,  20,  21 
Element4                = App1Button,            37, 295,  23,  25 
Element5                = App2Button,            76, 297,  23,  25 
Element6                = App3Button,           141, 297,  23,  25 
Element7                = App4Button,           180, 294,  23,  25 
Element11               = Touchscreen,           39,  44, 160, 220 
Element12               = LCD,                   39,  44, 160, 160