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

A    Structure Access Notifications

Using Palm OS® Emulator

Palm OS Developer Suite

In general, your Palm OS® application should not directly access the fields of structures for windows, forms, and form objects. Palm OS Emulator recognizes when structure access is valid, and will notify you if your application attempts any prohibited structure access.

The PalmOSGlue library, which is described in Palm OS Programmer's API Reference, provides functions that you should use in your application rather than using direct structure access.

Some versions of Palm OS have implemented an accessor trap function which prevents any access of data structures. The PalmOSGlue library checks for this accessor trap by checking for the sysFtrNumAccessorTrapPresent feature:

FtrGet (sysFtrCreator, sysFtrNumAccessorTrapPresent, &value)

Palm OS Emulator allows structure access for the structures listed in Table A.1, given that the accessor trap is not present. The Palm OS structures listed in the table can be accessed for the conditions described in the "Description" column.

Table A.1 Palm OS Structure Access Notification
Exceptions 

Palm OS Structure

Access Allowed

Description

ControlType attr

Read

Always allowed, primarily for PalmOSGlue functions CtlGlueGetGraphics and FrmGlueGetObjectUsable

ControlType attr

Read/Write

Always allowed, primarily for PalmOSGlue functions CtlGlueNewSliderConstrol and CtlGlueSetLeftAnchor

ControlType bitmapID

Read

For graphic controls, always allowed, primarily for PalmOSGlue function CtlGlueGetGraphics

ControlType font

Read/Write

Always allowed, primarily for PalmOSGlue functions CtlGlueGetFont and CtlGlueSetFont

ControlType selectedbitmapID

Read

For graphic controls, always allowed, primarily for graphic controls for PalmOSGlue function CtlGlueGetGraphics

ControlType style

Read

Always allowed, primarily for PalmOSGlue function CtlGlueGetControlStyle

FieldType attr

Read/Write

Before Palm OS 3.3

FieldType lines

Read

Always allowed, primarily for PalmOSGlue function FldGlueGetLineInfo

FormBitmapType attr

Read

Always allowed, primarily for PalmOSGlue function FrmGlueGetObjectUsable

FormBitmapType attr

Read/Write

Before Palm OS 3.2. The function FrmHideObject changes the usable attribute automatically after Palm OS 3.2, but before Palm OS 3.2, your application needed to change the usable attribute directly.

FormGadgetType (all fields)

All Access

No restrictions. Generally, your gadget code should use the correct accessor functions like any other form object. However, in a gadget callback function, your code needs to have direct access to the gadget's structure fields. Emulator makes no distinction for whether the access in the callback function, so the structure access is not restricted. Your application should still access gadgets using the correct accessor functions whenever possible.

FormLabelType attr

Read

Always allowed, primarily for PalmOSGlue function FrmGlueGetObjectUsable

FormLabelType font

Read/Write

Always allowed, primarily for PalmOSGlue functions FrmGlueGetLabelFont and FrmGlueSetLabelFont

FormType defaultButton

Read/Write

Always allowed, primarily for PalmOSGlue functions FrmGlueGetDefaultButtonID and FrmGlueSetDefaultButtonID

FormType handler

Read

Always allowed, primarily for PalmOSGlue function FrmGlueGetEventHandler

FormType helpRscID

Read/Write

Always allowed, primarily for PalmOSGlue functions FrmGlueGetHelpID and FrmGlueSetHelpID

FormType menuRscID

Read

Always allowed, primarily for PalmOSGlue function FrmGlueGetMenuBarID

ListType attr

Read/Write

Always allowed, primarily for PalmOSGlue functions FrmGlueGetObjectUsable and LstGlueSetIncrementalSearch

ListType font

Read/Write

Always allowed, primarily for PalmOSGlue function LstGlueGetFont and LstGlueSetFont

ListType itemsText

Read

Always allowed, primarily for PalmOSGlue function LstGlueGetItemsText

ListType topItem

Read

Before Palm OS 4.0. For Palm OS 4.0 and later, use LstGetTopItem. For compatibility, use PalmOSGlue function LstGlueGetTopItem.

TableType attr

Read/Write

Before Palm OS 4.0. For Palm OS 4.0 and later, use TblSetSelection. For compatibility, use PalmOSGlue function TblGlueSetSelection.

TableType currentColumn

Read/Write

Before Palm OS 4.0. For Palm OS 4.0 and later, use TblSetSelection. For compatibility, use PalmOSGlue function TblGlueSetSelection.

TableType currentRow

Read/Write

Before Palm OS 4.0. For Palm OS 4.0 and later, use TblSetSelection. For compatibility, use PalmOSGlue function TblGlueSetSelection.

TableType numColumns

Read

Before Palm OS 4.0. For Palm OS 4.0 and later, use TblGetNumberofColumns or TblSetSelection. For compatibility, use PalmOSGlue functions TblGlueGetNumberofColumns or TblGlueSetSelection.

TableType numRows

Read

Before Palm OS 4.0. For Palm OS 4.0 and later, use TblSetSelection. For compatibility, use PalmOSGlue function TblGlueSetSelection.

TableType topRow

Read

Before Palm OS 4.0. For Palm OS 4.0 and later, use TblGetTopRow. For compatibility, use PalmOSGlue function TblGlueGetTopRow.

ScrollBarType attr

Read

Always allowed, primarily for PalmOSGlue function FrmGlueGetObjectUsable

ScrollBarType attr

Read/Write

Before Palm OS 3.5. The functions FrmShowObject and FrmHideObject did not show and hide scrollbars before Palm OS 3.5, so your application needed to change the usable attribute directly.

WindowType bitmapP

Read

Before Palm OS 3.5. Do not directly access the memory used for the display buffer. Use the functions WinDrawBitmap or WinPaintBitmap, or use an offscreen window with WinGetBitmap and BmpGetBits.


NOTE: This field did not exist before Palm OS 3.5. It replaced the field gDeviceP which was defined before Palm OS 3.5.

WindowType displayWidthV20

Read

Before Palm OS 2.0. Use the function WinGetDisplayExtent instead.

WindowType displayHeightV20

Read

Before Palm OS 2.0 Use the function WinGetDisplayExtent instead.

WindowType displayAddrV20

Read

Before Palm OS 3.5. Do not directly access the memory used for the display buffer. Use the functions WinDrawBitmap or WinPaintBitmap, or use an offscreen window with WinGetBitmap and BmpGetBits.

WindowType frameType

Read/Write

Always allowed, primarily for Palm OSGlue functions WinGlueGetFrameType and WinGlueSetFrameType