This chapter contains descriptions of the following topics:
- "Using Emulator Skin Files"
- "Creating Demonstration Versions of Palm OS Emulator"
- "Sending Commands to Palm OS Emulator"
Using Emulator Skin Files
Palm OS Emulator 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 Emulator window.
The skin choices available are dependent on the handheld selection. When you select a handheld, Emulator 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 Emulator to look more like a specific handheld, such as when you are using Emulator to demonstrate your application for others. This section describes how to use additional skins that are available, and how to modify or create your own skins.
How Skin Files Work
When Emulator starts an emulation session, it looks for a Skins
directory:
- On Windows and Macintosh systems, Emulator looks for the
Skins
directory in the same directory as the Emulator executable file. - On Unix, Emulator looks in the
$POSER_DIR
,$HOME
,/usr/local/share/pose
, and/usr/share/pose
directories, stopping at the first one that has a directory calledSkins
orskins
.
If Emulator cannot find a Skins
directory, Emulator will display a warning message at startup. However, this warning message is only displayed once, so you will not have to be bothered by the message if you are not interested in using skin files.
When Emulator has found the Skins
directory, then Emulator searches that directory and all subdirectories for SKIN
files (files with filetype skin
, that is, *.skin
).
Installing Additional Skin Files
This section describes how to use existing skin files.
http://www.palmos.com/dev/tools/emulator/
Archived skin file packages are available for Windows, Macintosh, and Unix.
- Unarchive the skin file package you just downloaded.
- Create a
Skins
directory, as described in the section "How Skin Files Work". - Place the skin files (the unarchived contents of the downloaded package) into your
Skins
directory. - Start Palm OS Emulator. Emulator is now able to use the skins you have installed.
You can select the additional skins from either the New Session dialog box (Figure 7.1) or the Skins dialog box (Figure 7.2).
Figure 7.1 Choosing a Skin in the New Session Dialog Box

Figure 7.2 Choosing a Skin in the Skins Dialog Box

Modifying or Creating Skin Files
PalmSource, Inc. provides skin files for most existing Palm Powered™ handhelds. However, it is fairly easy to modify or create your own skin file if you need to.
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 JPEG
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:
This is similar to the way INI
files are stored on Windows, and how the emulator 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:
However, this definition is not correct:
- 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.
SKIN
file, though a relative path may be specified. Both image files must exist and be specified. 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
Listing 7.1 shows an example of a skin file.
Listing 7.1 Example of a Skin File
# This is a skin file for the Palm OS Emulator. See the ReadMe.txt # file in this directory for a description of its contents. Name = Standard-English File1x = Palm_III_16.jpg File2x = Palm_III_32.jpg 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
Creating Demonstration Versions of Palm OS Emulator
If you are running Palm OS Emulator on Windows NT or on Windows 2000, you can create an executable that binds the Emulator program with a ROM image and optionally a RAM image. The bound program can then be used for demonstrations, training, and kiosk systems.
To save a demonstration version of the Emulator session, you can right-click on the Palm OS Emulator display (the Palm Powered handheld image) and select Save Bound Emulator...
NOTE: You cannot create a bound emulation session on Macintosh or on Windows 98. You must be running Windows NT or Windows 2000 to create a bound emulation session.
Bound Emulation Session Limitations
Because bound emulation sessions are intended to be used as demonstration versions, bound emulation sessions are different from regular Emulator session:
- All options in the Logging options dialog box are turned off.
- All options in the Debug options dialog box are turned off.
- You cannot load a saved emulation session (
PSF
file) into a bound emulation session. - The menu items are limited to the ones displayed in Figure 7.3.
Figure 7.3 Bound Emulator Menu Items

IMPORTANT: Because the bound emulation session contains a ROM image, you are restricted by your Palm OS Developer Program agreement from redistributing it. The Web Clipping ROM images are especially restricted because they contain strong encryption features.
For more information, review the Palm OS Developer Program's Prototype License and Confidentiality Agreement.
Sending Commands to Palm OS Emulator
You can use RPC packets to send commands to Palm OS Emulator. You can invoke any function in the Palm OS dispatch table, including the Host Control functions, which are described in Chapter 8, "Host Control API Reference."
The RPC packets use the same format as do packets that are sent to the debugger interface, which is described in Chapter 9, "Debugger Protocol Reference."
You use the socket defined by the RPCSocketPort
preference to make RPC calls to Palm OS Emulator. When you send a packet to the emulator, you must set the dest
field of the packet header to the value defined here:
#define slkSocketRPC (slkSocketFirstDynamic+10)
NOTE: You can disable the RPC command facility by setting the value of the
RPCSocketPort
preference to 0
.
You can send four kinds of command packets to the emulator:
The first three packet types are described in Chapter 9, "Debugger Protocol Reference." The fourth packet type, RPC2, is an extension of the RPC packet format that allows support for a wider range of operations.
RPC2 Packet Format
#define sysPktRPC2Cmd 0x20 #define sysPktRPC2Rsp 0xA0 struct SysPktRPCParamInfo { UInt8 byRef; UInt8 size; UInt16 data[1]; }; struct SysPktRPC2Type { _sysPktBodyCommon; UInt16 trapWord; UInt32 resultD0; UInt32 resultA0; UInt16 resultException; UInt8 DRegMask; UInt8 ARegMask; UInt32 Regs[1]; UInt16 numParams; SysPktRPCParamType param[1]; };Almost all of the RPC2 packet format is the same as the RPC format that is described in Chapter 9, "Debugger Protocol Reference." The RPC2 packet includes the following additional fields:
resultException
Stores the exception ID if a function call failed due to a hardware exception. Otherwise, the value of this field is 0
. Regs[1]
A variable-length array containing the values to be stored in the registers that need to be set. Only the registers that are being changed need to be supplied. Most of the time,
DRegMask
and ARegMask
are set to zero and this field is not included in the packet. If more than one register needs to be set, then the register values should appear in the following order: D0, D1, ..., D6, D7, A0, A1, ..., A6, A7. Again, only values for the registers specified in
DRegMask
and ARegMask
need to be provided.