|
Bitmap buttons behave differently on different PalmOS versions
|   |
|
Bitmap buttons behave differently on different PalmOS versions
| |
Problem: Bitmap buttons behave differently on different PalmOS versions. To create graphical button controls, developers often use a "clear" button control (a visible button with no label and no border) with a bitmap control overlaid on top, referred to herein as a bitmap button. This enables you to design more visually appealing applications. However, the behaviour of bitmap buttons unfortunately differs depending on the version of PalmOS on the device.
With PalmOS versions prior to 4.0, a clear button placed underneath a bitmap control would receive the pen tap on the form, thus enabling you to take action when the user tapped on the bitmap image. However, starting with PalmOS 4.0, PalmSource changed this default behaviour so that the foreground control receives the pen tap. In this case, the pen tap would be directed to the bitmap control, which does not respond to click events, thus nothing would happen when the user tapped on the bitmap image. For PalmOS 4.0 and higher devices, including PalmOS 5.x devices, the clear button must be placed overtop of the bitmap control in order to receive the pen taps from the user.
Solution: If your application is designed solely for devices running PalmOS 3.5, you can place clear buttons underneath bitmap controls in order to implement bitmap buttons in your application. It is unlikely, however, that many applications are intended solely for PalmOS 3.5 devices.
If your application is designed solely for devices running PalmOS 4.0 or higher, for example PalmOS 5.x devices only, then you can implement bitmap buttons by placing the clear button controls overtop of the bitmap controls.
If you wish to support all PalmOS devices running PalmOS 3.5 and higher, there are four options for implementing bitmap buttons:
In order to support bitmap buttons on PalmOS 3.5 and higher devices, you can place clear button controls both underneath the bitmap control and overtop the bitmap control. We use the term "button sandwich" as the bitmap control is "sandwiched" between two clear button controls. Often, developers will have one of the button controls in sandwich call the .execaction method of the other button control, instead of duplicating the action or OnClick script on both buttons. This makes code maintenance easier since you do not need to make changes to both button controls.
This is the simplest and most efficient method to implement bitmap buttons that behave the same regardless of the PalmOS version.
Rather than implementing bitmap buttons with a clear button control, you can handle the pen down and pen up events on the form directly. This enables you to process pen taps within the bounds of the bitmap control without using a clear button at all. While this method offers the advantage of working the same across all PalmOS versions, it does have some distinct disadvantages that may make it impractical in your application. In particular, the OnPenDown/OnPenUp scripts needed to handle the pen taps are much more complex than using a clear button or button sandwich, especially when you have more than one bitmap button on a form. As well, the bitmap control is not visually inverted when the pen is touching the screen, as it is when clear buttons are used, so there is less visual feedback to the user that tapping on the bitmap will make it act like a button.
Part of the complexity comes from the fact that in order to properly behave like a button, you must track where the pen touches the screen (in the OnPenDown event) and follow it until it is lifted from the screen (the OnPenUp event), and only take action if the pen both touched and was lifted from the correct screen coordinates. If the pen touches down in the desired screen location, but the user slides it away out of the bitmap location before lifting, you should not consider that a valid pen "tap".
A sample set of OnPenDown and OnPenUp scripts to handle a "home" icon in the upper left corner of the screen is presented below. They use a pair of global variables named gPenX and gPenY.
'OnPenDown track pen for home icon
GetPenStatus(gPenX, gPenY)
if (gPenX >= 146) and (gPenY <= 12) then
while GetPenStatus(gPenX, gPenY) = true
'do nothing except update the gPenX and gPenY location vars for OnPenUp checking
wend
endif
'OnPenUp track pen for home icon
if (gPenX >= 146) and (gPenY <= 12) then
beep(7) 'click
forms("Main").show 'go home!
endif
As you can see, adding support for multiple bitmap buttons using this method will soon become unwieldy, as you will need to track multiple bitmap location boundaries.
SFOnClick is a custom control extension available from PalmDataPro. See the SatForms Solutions Guide entry for SFOnClick here: http://www.satelliteforms.net/solutions/?10054
SFOnClick can be used to implement bitmap buttons that behave the same on PalmOS versions 3.5 and higher. However, this is again more complex than using the button sandwich approach, and requires the use of a commercial extension. In addition, the bitmap control is not inverted visually when the pen is touching it, thus there is less visual feedback to the user. See the sample application that comes with SFOnClick for implementation details.
SFBitmapView (http://www.satelliteforms.net/solutions/?10061) and SFJPGView (http://www.satelliteforms.net/solutions/?10035) are custom controls available commercially from PalmDataPro that present an alternative to the standard bitmap control in Satellite Forms. One of the options that these controls have is the ability to respond directly to pen taps, by providing an OnClick event for the control. The disadvantage of using this approach is that it requires the purchase of a custom control extension.
Keywords: bitmap, button, sandwich, onclick, icon
KB ID: 10023
Updated: 2006-10-02
Satellite Forms KnowledgeBase Online