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

7    Palm OS Emulator Advanced Topics

Using Palm OS® Emulator

Palm OS Developer Suite

This chapter contains descriptions of the following topics:

Using Emulator Skin Files ^TOP^

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 ^TOP^

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 called Skins or skins.

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 ^TOP^

This section describes how to use existing skin files.

  1. Download additional skins from:

http://www.palmos.com/dev/tools/emulator/

Archived skin file packages are available for Windows, Macintosh, and Unix.

  1. Unarchive the skin file package you just downloaded.
  2. Create a Skins directory, as described in the section "How Skin Files Work".
  3. Place the skin files (the unarchived contents of the downloaded package) into your Skins directory.
  4. 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 ^TOP^

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:

<attribute>=<value>

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:
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 image file.
Example:
File1x = MySkin1.jpg
File2x This is the name of the double-scale image file.
Example:
File2x = MySkin2.jpg
Note: Two image files must be specified: one for single-scale and one for double-scale.
Image files are expected to be in the same directory as the SKIN file, though a relative path may be specified. Both image files must exist and be specified.
Macintosh relative-path format example:
File1x = :Small Images:MySkin.jpg
File2x = :Large Images:MySkin.jpg
Windows relative-path format example:
File1x = Small Images\MySkin.jpg
File2x = Large Images\MySkin.jpg
BackgroundColor This field defines the normal color used when displaying the LCD area of Emulator'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 This field define the backlighting color used when displaying the LCD area of Emulator'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 input area.
LCD - The application screen area, excluding the input 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 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 ^TOP^

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 ^TOP^

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 ^TOP^

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:

  • ReadMem
  • WriteMem
  • RPC
  • RPC2

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 ^TOP^

#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.
DRegMask A bitmask indicating which D registers need to be set to make this call.
ARegMask A bitmask indicating which A registers need to be set to make this call.
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.