发信人: kevins()
整理人: jkf(2001-07-15 20:38:07), 站内信件
|
This is a development overview for Palm OS? software version 3.5. This overview predates the final documentation and final SDK 3.5. Download these for more info, and before you begin development, check out the Palm OS 3.5 Top Issues page.
At PalmSource? Summit 1999, Palm introduced developers to the new features of the 3.5 release of the Palm OS? software. This is a summary of the presentation material; as the OS and SDK releases progress there will be official documentation releases made available.
For ROM images of this software, see the Development Seeding area of the Pavilion.
If you are new to Palm OS? programming, see the New Developers page.
Introduction
The 3.5 release of the Palm OS? software is designed to be a platform release, meaning that it is an OS release designed for all of the Palm OS? platform devices. The various device manufacturers, OEMs and licensees will control the timing and method of release of the newer OS to their customers; some might release it as a flashable upgrade if their devices support such an upgrade.
Overview of Improvements
The 3.5 release contains improvements in the user-oriented features, in licensee abilities, and developer APIs and features. There are changes to the built-in applications and system UI, but the data format of the built-in applications have not changed except for the Launcher application. Developers should expect the data format of the built-in applications to change in the future, so be particularly careful to check error codes and watch for future information releases.
There were only minor changes to the desktop software and the Web Clipping software in this release. For example the HotSync? Manager has been rebuilt with Visual C++ version 6.0, so that developers don't need to use the older version of the compiler to build conduits. This should have no discernable effect on users, but should make conduit development easier.
This OS release also is significant in that it contains all of the functionality from Palm OS? software versions 3.1, 3.2, and 3.3, which were not all supersets of each other. The 3.5 codebase includes all of the features from each release, and thus so does the 3.5 SDK, which solves the previous temporary need for separate include file hierarchies, one of which was for 3.1 support and the other for Palm VII organizer support. Note that this does not mean that every device running Palm OS? software 3.5 will have every software or hardware feature that 3.5 supports; device manufacturers have the option of tailoring the feature set as makes sense for their customers.
This OS release also provided an opportunity to add and improve OS items and features which were not specifically device-oriented, but apply to all Palm OS? platform device products and help licensees and developers.
Application and System UI changes
There are many changes and improvements throughout the built-in applications and system UI. A partial list includes:
The Graphics System includes support for 1, 2, 4, and 8 bit color and grayscale.
The Datebook's new Agenda view combines a view of a day's appointments with the day's ToDo tasks
The Alarm dialog now has larger buttons to facilitate finger operation, as well as a "Snooze" button
When beaming an entire category, the receiver's dialog allows selection of the destination category in which to place the items
The Title, Company, City, State and Country fields in the Address book support auto-completion of the input text
Masked records
The Command bar
Tapping the title tab of an application shows the menu bar
Double-tapping on a word in a field selects it; triple-tapping selects the line
The category indicator has changed to differentiate between when the data is changing versus when the view of the data is changing. See the memo pad edit screen for an example.
Other changes that are not directly visible to users, but which help developers, include:
Extended Gadgets, which call back a function in your application when it is time to draw, erase, handle pen input, etc.
Color picker to let users choose a RGB value, or entry from the active color palette
Slider controls
Graphic buttons
The Notification Manager informs your application of events it is interested in, such as power-off
The Menu Manager supports showing, hiding, and adding menu items.
The dynamic heap is sized based on the amount of memory available to the system, and is generally larger than before.
The SDK has clarified and the type definitions and parameter declarations in the include files and made them more consistent.
Error checking in the Debug ROM has been improved, and the release rom has less debugging code and fewer ErrFatalDisplay() calls.
Many other APIs have been added or improved, bugs fixed, and so forth.
Graphics system
The most major and obvious change in Palm OS software 3.5 is the graphics system, which now supports 1, 2, 4, and 8 bit color and grayscale. Not all hardware running 3.5 can support all of these graphics modes, but for example 4-bit grayscale (16 shades) is possible and is officially supported on some devices running the DragonBall EZ, such as the Palm V device family.
There are new API functions to fully support color and grayscale, as well as new API routines to address limitations of the previous APIs - for instance WinGetPixel and WinSetPixel, routines long requested by developers, now have been created.
The preliminary 3.5 SDK contains some early documentation on the new graphics system, and the 3.0 version of the Palm OS Emulator supports emulating a color screen, so with the 3.5 color rom image developers can start creating color applications immediately, without having to wait for a device manufacturer to ship actual hardware.
Masked Records
A record in an application can be private, if the user chooses to set it that way, and the system has allowed private records to be shown or hidden by using the Security application. In 3.5 the user has a third choice: to show the record's presence but have its data masked out with a gray box.
The system preference prefShowPrivateRecords now returns an enum telling the application whether to show, hide, or mask private records. There are also new APIs that applications can use to let the user switch easily between the three modes, and then the application can change its display as appropriate. The functions are SecSelectViewStatus() and SecVerifyPW().
Tables also have support for setting a row or column to be masked; TblSetRowMasked(), TblSetColumnMasked, and TblRowMasked(). When a row is masked, the table will draw the gray box and the lock icon for you. When your application gets a TtblSelectEvent, you would use code similar to this to let the user easily switch modes:
if (TblRowMasked(tblPtr, theRow)) {
SecVerifyPW(showPrivateRecords);
RedrawEverything();
}
Command Bar
Writing the Graffiti command stroke (bottom left to upper right) used to bring up a "Command:" display on the bottom of the screen. It now brings up a command bar across the full bottom of the screen, which applications can place appropriate icons upon.
When your application gets a menuCmdBarOpenEvent, make calls to MenuCmdBarAddButton() specifying where to add the button, the id of the 5x13 bitmap to display, the result action (menu command, character, etc.) and the text to display for the button if it isn't a menu command. If the button mirrors a menu command, the command bar will send a standard menu event to your application when the user taps that button, so handling the menuCmdBarOpenEvent code would be the only code change necessary.
The buttons displayed on the command bar should be determined by the user's context; for instance if there is no text selection, there should not be "copy" or "cut" buttons shown. Furthermore, the number of buttons should be restricted to 4, to leave room for the feedback text.
If a field has focus when the command bar is opened, the field package will automatically add undo, cut, copy and/or paste buttons, as appropriate. If your application does not want this default behavior, set the event->data.menuCmdBarOpen.preventFieldButtons boolean to true.
Applications may need to call MenuEraseStatus() more than before, since the command bar covers more space than the simple "Command:" text did. The system will automatically hide the command bar when windows are opened and closed, but your application may need to hide the bar if it is going to draw to that area of the screen based on menu commands or other events that could result from use of the command bar. (Note that the rom released at PalmSource didn't hide the bar as much as it will in future releases of 3.5.)
Extended Gadgets
A Gadget used to be a form object which was nothing more than a set of coordinates and a bit of memory for your application to use as it wanted, and the system provided no extra support for gadgets. The Gadgets created by the 3.5 version of PalmRez, or by FrmNewGadget(), are "Extended Gadgets" which support a callback function pointer, set by the new routine FrmSetGadgetHandler(). The system will call this callback routine to let it handle drawing and erasing itself, as well as for pen taps and other events.
When your callback gets the formGadgetDrawCmd, if you do any drawing in response you must set gadgetP->attr.visible so that the system will know to send you a formGadgetEraseCommand when appropriate. If you do set that bit but don't handle the formGadgetEraseCommand, the system will erase the bounding rectangle of the gadget for you. Other events and commands sent include frmGadgetEnterEvent (sent when the user taps on the object), frmGadgetMiscEvent (for you to send app-specific messages to the gadget) and formGadgetDeleteCmd (sent when the form is being destroyed - but not in the PalmSource seed version).
Color Picker
The new UIPickColor() routine lets you bring up a color picking form which has two UI modes: RGB sliders, and "chits". Your application can request either or both of the modes to be available to the user.
If you pass pointers to get both an index value and a RGB value to be returned, both will have appropriate data in them, but the RGB value may be "more correct" in the case where the user has picked a color with the RGB sliders, but the color doesn't appear in the current palette. If your application wants to precisely match the user's selection, it must use the appropriate API routines to change the screen's color palette.
Slider Controls
The slider control, as previously seen in the Adjust Contrast form in a Palm V device, is now a standard control usable in other applications. Constructor has added support for it, or it can be created at runtime by calling CtlNewSliderControl().
There are two styles of sliders; sliderCtl and feedbackSliderCtl, mirroring the way that text buttons have a "repeating" version which keeps sending events while the user is using the control. A feedbackSliderControl will send ctlRepeatEvents to the application so that it can update its display as appropriate.
CtlGetSliderValues() and CtlSetSliderValues() can be used to get and set the slider's information.
Graphical Buttons
Graphical Buttons are very similar to normal text buttons, but display an image instead of text. They have two bitmaps, one for the normal display and one as a "selected" image shown when the user is pressing it with the pen.
The older style used by some applications of overlaying a form bitmap object with a borderless button with no text, to get the same functionality, does not work as well on a device using more shades of gray or color - both because it is far less efficient in terms of code to invert each pixel when it is pressed, and also because inverting a color image rarely looks good.
The updated Constructor can create Graphical Buttons, or they can be created at runtime with CtlNewGraphicControl(). CtlSetGraphics() can be used to change what images are drawn, at runtime.
Notification Manager
The Notification Manager is designed for the system (or other applications) to inform applications of events, if the applications have registered as being interested in that particular event. This is a far more efficient and extensible manner than having the system broadcast launch codes to every application on the device, and can also be used to send notifications to a function - making it suitable for hacks, libraries, and other non-application uses.
An application would call SysNotifyRegister() to inform the system of which events it is interested in notifications for, and SysNotifyUnregister() when it is quitting or doesn't care any more. Applications and the OS will call SysNotifyBroadcast() and SysNotifyBroadcastDeferred() to send notifications out at the appropriate times.
The notifications currently sent by the system include:
Time Changed
Antenna Raised
DisplayChange (palette or screen depth changed)
HotSync process starting and ending
Reset finished
Password forgotten
Sleep (multiple notifications)
Sleep notification consists of four stages: Request, Notify, EarlyWakeup and LateWakeup. Sleep notifications are not guaranteed to be sent. If your application wants to know when the device is turned on, register for LateWakeup. Very few will want to register for EarlyWakeup, since that can be sent in situations where the device is not truly being turned on, from the user's perspective.
Menus
The Menu Manager now adds support for applications who want to modify their menus at runtime. The new functions are MenuHideItem(), MenuShowItem() and MenuAddItem(). They are not to be used in the same manner as a desktop system grays out temporarily invalid selections; the Palm OS UI scheme strongly discourages this sort of usage.
The menuOpenEvent event is sent by the OS when the menus are being loaded from your application's resources. This is a signal to your application that it should immediately edit any menus which need changes, since the menu is about to be shown or used.
On some Japanese devices, the OS can add items to standard Edit menus. Other than that, any other use would be under your application's control.
Misc. new APIs
ResLoadConstant() is a utility function which finds a resource, locks it, copies 32 bits of data from it, unlocks it and returns the 32 bit value to your application. This can be used as an aid to localization, to decrease the amount of data hard-coded in an application while also reducing code size.
TblGetItemPtr() - the function TblSetItemPtr() never had a corresponding "Get" accessor. Now it does.
FrmNewGsi() - most other UI objects could be created dynamically, at runtime, but the Graffiti-shift state indicator wasn't creatable at runtime until now.
EvtSetAutoOffTimer() - some applications need more careful control over the Auto-Off timer, which lets the device turn off after a period of inactivity. This function lets developers control the timer in several ways.
DateTemplateToAscii() - lets you format Dates based on a template, so you can get exactly the format you want.
FrmCustomResponseAlert() - like FrmCustomAlert() but includes an input field and a pointer to a callback routine that you can write to validate the input.
The Dynamic Heap
The Dynamic heap is now sized based on the amount of memory available to the system. The size which will be used is as follows:
Device RAM size
Heap size
< 2 mb of ram
64 k
>= 2 mb
128 k
>= 4 mb
256 k
Misc. API changes
FtrPtrNew() allows allocating chunks larger than 64k. These are allocated in the Storage heap, so you need to use DmWrite to modify them, but reading from them can still be done with a normal C pointer. Do keep in mind standard issues with allocating large chunks of memory: there might not be enough contiguous space, and it can impact system performance.
FrmHideObject() and FrmShowObject() now work on list objects
The "Edit Category" line can be hidden; previously its text could be changed but it couldn't ever be hidden.
StrToLower() now works on characters other than A to Z; it knows about other languages.
ScrDisplayMode() has been renamed to WinScreenMode()
SelectTime() now optionally has an "All Day" button, and a new parameter controls what hours define "All Day". The old SelectTime() routine is renamed SelectTimeV33() and works the same as before.
SDK include files
The contents of the SDK include files have been moved around, some things renamed (for example, "PalmOS.h" instead of "Pilot.h"
There is now a better distinction between public and private structures and functions, so that you know which ones are safe to use
Most private functions and information have been moved out of the public include files, as well; they will be available to developers through the ROM Source Code license but since they are implementation details that are subject to change, they don't belong in the SDK.
Types have changed for clarity and consistency; for example Int is now Int16, and Word is UInt16 to indicate which is signed and unsigned, and their size. The previous convention of declaring a FooPtr typedef for each Foo structure has been retired in favor of the simple "Foo *" or "FooType *" method.
These type changes will require a "search and replace" on application source files when they use the new SDK, but does not change binary compatibility of built applications. We are in the process of writing a comprehensive guide to help you switch to the newer SDK with minimal disruption and maximum benefit.
Debug ROMs
The Debug ROMs now contain much more code to validate parameters, check that drawing windows are selected properly, etc. The Release ROMs now do less error checking than before, for things that ought to be caught by the original developers using the debug roms.
Many incorrect ErrFatalDisplay calls in the rom have been replaced by returning error codes to the calling application.
FormDrawForm and FormEraseForm changes to identify drawing at incorrect times, or failing to handle frmUpdateEvents
Unique UI colors used on color debug roms, screen background is cleared to UICaution (currently yellow) when switching apps; FrmCopyLabel() sees if there's room for the new text; DmReleaseResource() validates the handle passed to it; buffers and the stack get set to 0xFE or other such values to help catch uninitialized memory, etc.
|
|