This chapter describes the preferences API as declared in the header file Preferences.h
. It discusses the following topics:
For more information on preferences, see the section "Preferences" of the Palm OS Programmer's Companion, vol. I.
Preferences Data Types
MeasurementSystemType Enum
Purpose
The MeasurementSystemType
enum specifies the preference for units of measure.
Prototype
typedef enum { unitsEnglish = 0, unitsMetric } MeasurementSystemType;
Constants
-
unitsEnglish
- The English measurement system
(feet, inches, and so on). -
unitsMetric
- The Metric system (meters, centimeters, and so on).
SecurityAutoLockType Enum
Purpose
The SecurityAutoLockType
enum specifies the values for the auto-locking preference. The auto-locking preference specifies when the device will shut down and lock itself.
Prototype
typedef enum { never = 0, uponPowerOff, atPresetTime, afterPresetDelay } SecurityAutoLockType;
Constants
-
never
- The auto-lock feature is disabled.
-
uponPowerOff
- The device locks itself each time it is powered off.
-
atPresetTime
- The device locks itself at a certain time every day.
-
afterPresetDelay
- The device locks itself after a certain amount of idle time.
SoundLevelTypeV20 Enum
Purpose
The SoundLevelTypeV20
enum specifies whether certain sounds are enabled or disabled. This enum is used as the values for several of the system sound preferences.
Prototype
typedef enum { slOn = 0, slOff = 1 } SoundLevelTypeV20;
Constants
Compatibility
This enumerated type is obsolete in Palm OS® versions 3.0 and higher. The preferences that use this enum are replaced by preferences that indicate sound volume as well as whether the sound is on or off.
SystemPreferencesChoice Enum
The SystemPreferencesChoice
enum defines values that you can pass to PrefGetPreference()
and PrefSetPreference()
to retrieve or set a system preference value. SystemPreferencesChoice
defines one constant for each field in the SystemPreferencesType
structure, which should be considered a private structure.
Table 48.1 lists and describes the SystemPreferencesChoice
constants. For each constant, it shows what type of data is returned by PrefGetPreference
for that constant and which version of the system preferences structure contains this preference.
The system preferences structure keeps track of its own version information because it has been updated several times. Each Palm OS release that updates the system preferences structure increments the structure's version number. Table 48.1 on page 900 specifies which version of the system preferences structure introduced that preference. For each preferences version, there is a constant representing that version. See the section "Preferences Constants" for information on which preferences version corresponds with which Palm OS release. You should check the preference's version number before attempting to obtain the value of any preference introduced after version 2. For example:
LmLocaleType currentLocale;
if (PrefGetPreference(prefVersion) >=
preferenceDataVer9
) {
currentLocale = (LmLocaleType)
PrefGetPreference(prefLocale);
}
Most of the system preferences can be set in the Preferences and Security applications. Table 48.2 on page 908 specifies which system preference is set by each user interface field in these two applications.
Table 48.1 SystemPreferencesChoice Constants
The first day of the week (Sunday or Monday). Days of the week are numbered from 0 to 6 starting with Sunday = 0. |
|||
The format used for numbers, with regards to the thousands separator and the decimal point. |
|||
Minutes of user idle time before the device powers off. The default value for this preference is specified by the |
|||
|
|||
If |
|||
If |
|||
If |
|||
If |
|||
The type of batteries installed. Use |
|||
The time zone given as minutes east of Greenwich Mean Time (GMT). For preferences version 9 and higher, use |
|||
The type of daylight savings correction. For preferences version 9 and higher, use |
|||
The virtual character generated when the user enters the ronamatic stroke. The ronamatic stroke is made by dragging the pen from the input area to the top of the screen. |
|||
The creator ID of the application to be launched by the left-most hard key (the Date Book button by default). |
|||
The creator ID of the application to be launched by the second hard key from the left (the Address button by default). |
|||
The creator ID of the application to be launched by the second hard key from the right (the To Do List button by default). |
|||
The creator ID of the application to be launched by the right-most hard key (the Memo Pad button by default). |
|||
The creator ID of the application to be launched by the Calculator silkscreen button. |
|||
The creator ID of the application to be launched by the hard key on the HotSync cradle. |
|||
The creator ID of the application to be launched by the Applications silkscreen button. |
|||
The creator ID of the application to be launched by the HotSync button on the modem. |
|||
The sound level for system sounds, such as taps and beeps. This is a value from 0 to |
|||
The sound level for game sounds. This is a value from 0 to |
|||
The sound level for alarms. This is a value from 0 to |
|||
If |
|||
This preference is not currently used. Instead, use the |
|||
If |
|||
If |
|||
If |
|||
The creator ID of the application to launch when the antenna is raised (used only for devices with built-in antennas). |
|||
Specifies whether the private records should be displayed, masked, or completely hidden. |
|||
Seconds of user idle time before the device powers off. The default value for this preference is specified by the |
|||
The time zone given as minutes east of Greenwich Mean Time (GMT). |
|||
The number of minutes to add to the current time for daylight savings time. |
|||
Specifies when the auto-locking feature should take effect. Possibilities are upon power off, at a preset time, or after a certain number of seconds. |
|||
The time value for the auto-locking feature if the system should lock itself after a delay or at a preset time. Depending on the value of |
|||
If |
|||
The user's preferences for receiving attention signals. The returned value is a bit mask that should be tested (using the |
|||
Note that you can override the values in |
|||
Creator ID of the application that is launched after a reset. If 0, the system default application is launched. |
|||
The device's current locale, which specifies the country and language. |
|||
Preferences in the User Interface
Table 48.2 shows the SystemPreferencesChoice
constants and how they correspond to the values that users can set in the Preferences and Security applications. For further information about each preference, see Table 48.1.
Table 48.2 Preferences set in standard apps
|
||
Alarm Vibrate1 |
||
|
||
|
1. The Alarm Vibrate and Alarm LED preferences only appear on handhelds running Palm OS 4.0 and later that have the appropriate hardware capabilities. If you install Palm OS 4.0 on an older device, these preferences do not display.
|
Preferences Constants
The following table describes the constants defined in the Preferences.h
header file.
Initial setting for the |
||
Initial setting for the |
||
The value that |
||
Version 2 of the system preferences structure, used for Palm OS 2.0. |
||
Version 3 of the system preferences structure, used for Palm OS 3.0. |
||
Version 4 of the system preferences structure, used for Palm OS 3.1. |
||
Version 5 of the system preferences structure, used for Palm OS 3.2. |
||
Version 6 of the system preferences structure, used for Palm OS 3.3. |
||
Version 8 of the system preferences structure, used for Palm OS 3.5. |
||
Version 9 of the system preferences structure, used for Palm OS 4.0. |
||
Version 10 of the system preferences structure, used for Palm OS Garnet version 5.0. |
||
Version 11 of the system preferences structure, used for Palm OS Garnet version 5.1. |
||
Version 12 of the system preferences structure, used for Palm OS Garnet version 5.3SC. |
||
Preferences Functions
PrefGetAppPreferences Function
Purpose
Return a copy of an application's preferences resource.
Declared In
Preferences.h
Prototype
Int16 PrefGetAppPreferences ( UInt32 creator, UInt16 id, void *prefs, UInt16 *prefsSize, Boolean saved )
Parameters
-
→
creator
- Creator ID of the application that owns the preferences.
-
→
id
- ID number of the preferences resource to retrieve. The IDs
0x8000
through0xFFFF
are reserved for system use. -
←
prefs
- Pointer to a buffer to hold the preferences.
-
↔
prefsSize
- Pointer to the size of the
prefs
buffer passed in. (Note that the pointer and the value to which it points must be initialized before you callPrefGetApPreferences
.) Upon return, contains the number of bytes actually written or the number of bytes needed for theprefs
structure. - To determine the required size for the
prefs
structure, setprefsSize
to 0 and passNULL
forprefs
. Upon return, theprefsSize
parameter contains the required size. Never setprefs
toNULL
without also settingprefsSize
to 0. - Always compare the value returned in this parameter with the value you passed in. If the two values differ, you need to resize the
prefs
structure and call this function again. -
→
saved
- If
true
, retrieve the preferences from the "saved" preferences database, which is backed up during a HotSync operation. Iffalse
, retrieve the preferences from the "unsaved" preferences database, which is usually not backed up during a HotSync operation.
Returns
Returns the version number of the retrieved preferences resource, or returns the constant noPreferenceFound
if the preferences resource wasn't found. The returned version number is the same version number that was passed to the PrefSetAppPreferences()
function.
Comments
Use this function to retrieve the preferences that you previously set with the PrefSetAppPreferences()
function. You typically call this function in your StartApplication
function upon a normal launch. The values of the id
and saved
parameters should be the same as you specified when calling PrefSetAppPreferences()
, and the prefs
parameter should be a structure of the same type as you passed to PrefSetAppPreferences()
. Most applications store all preferences in a single preferences resource retrieved by a single call to PrefGetAppPreferences
, but this is not required. You can use multiple preferences resources if you wish.
Applications typically call PrefGetAppPreferences
twice: once with prefs
set to NULL
and prefsSize
set to 0 to determine how much memory to allocate for the preferences structure, and a second time after allocating the required amount of memory to obtain a copy of the application's preferences resource.
The version number returned by this function allows you to handle the case where a new version of the application is being run for the first time. You can compare the value returned by this function with the current version number to determine if you need to set default values for any preferences created by the current release. For more information, see the section "Updating Preferences Upon a New Release" of the Palm OS Programmer's Companion, vol. I.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
PrefSetPreferences()
, PrefGetAppPreferencesV10()
PrefGetAppPreferencesV10 Function
Purpose
Return a copy of an application's preferences.
Declared In
Preferences.h
Prototype
Boolean PrefGetAppPreferencesV10 ( UInt32 type, Int16 version, void *prefs, UInt16 prefsSize )
Parameters
-
→
type
- Creator ID of the application that owns the preferences.
-
→
version
- Version number of the application's preferences.
-
←
prefs
- Pointer to a buffer to hold preferences.
-
→
prefsSize
- Size of the buffer passed.
Returns
Returns false
if the preference resource was not found or the preference resource contains the wrong version number.
Comments
The content and format of an application preference is application-dependent.
Compatibility
This function corresponds to the 1.0 version of PrefGetAppPreferences
.
See Also
PrefSetPreferences()
, PrefGetAppPreferences()
PrefGetPreference Function
Purpose
Return a system preference. Use this function instead of PrefGetPreferences()
.
Declared In
Preferences.h
Prototype
UInt32 PrefGetPreference( SystemPreferencesChoice choice )
Parameters
-
→
choice
- A constant that specifies what preference to retrieve. See
SystemPreferencesChoice
.
Returns
Returns the system preference or 0 if the preference could not be found. On debug ROMs, a non-fatal error message is also displayed if the specified preference cannot be found.
Comments
This function replaces the 1.0 function PrefGetPreferences()
. While PrefGetPreferences
only lets you retrieve the whole system preferences structure, this function lets you specify which preference to retrieve.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
PrefSetPreference()
, PrefGetAppPreferences()
, PrefGetAppPreferencesV10()
PrefGetPreferences Function
Purpose
Return a copy of the system preferences.
Declared In
Preferences.h
Prototype
void PrefGetPreferences ( SystemPreferencesPtr p )
Parameters
Returns
Returns nothing. Stores the system preferences in p
.
Comments
The p
parameter points to a memory block allocated by the caller that is filled in by this function.
This function is often called in StartApplication
to get localized settings.
NOTE: This function can only be used to retrieve preferences that were in the 1.0 version of the preferences structure.
See Also
PrefOpenPreferenceDB Function
Purpose
Return a handle to either the saved or unsaved preference database.
Declared In
Preferences.h
Prototype
DmOpenRef PrefOpenPreferenceDB ( Boolean saved )
Parameters
-
→
saved
- If
true
, open the "saved" preferences database, which is backed up during a HotSync operation. Iffalse
, open the "unsaved" preferences database, which usually is not backed up during a HotSync operation.
Returns
Returns the handle, or 0 if an error results.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
PrefGetPreference()
, PrefSetPreference()
, PrefOpenPreferenceDBV10()
PrefOpenPreferenceDBV10 Function
Purpose
Return a handle to the system preference database.
Declared In
Preferences.h
Prototype
DmOpenRef PrefOpenPreferenceDBV10 ( void )
Parameters
Returns
Returns the handle, or 0 if an error results.
Compatibility
This function corresponds to the 1.0 version of PrefOpenPreferenceDB
.
See Also
PrefGetPreferences()
, PrefSetPreferences()
PrefSetAppPreferences Function
Purpose
Set an application's preferences in the specified preferences database.
Declared In
Preferences.h
Prototype
void PrefSetAppPreferences ( UInt32 creator, UInt16 id, Int16 version, const void *prefs, UInt16 prefsSize, Boolean saved )
Parameters
-
→
creator
- Creator ID of the application that owns this preference.
-
→
id
- ID number of the preference to set. An application can have multiple preferences. The IDs
0x8000
through0xFFFF
are reserved for system use. -
→
version
- Version number of the application's preferences.
-
→
prefs
- Pointer to a buffer that holds the current value of the preferences structure. Pass
NULL
if you want to delete the preferences. -
→
prefsSize
- Size of the buffer passed. Pass 0 if you want to delete the preferences structure.
-
→
saved
- If
true
, saves the preferences in the "saved" preferences database. If not, saves the preferences in the "unsaved" preferences database.
Returns
Comments
You typically call this function in your StopApplication
function to save the current state of the application or if the user has changed an application preference during the current session.
The "saved" preferences database is backed up when a user performs the HotSync operation. The "unsaved" preferences database is not backed up by default. (The user can use a third-party tool to set the backup bit in the "unsaved" preferences database, which would cause it to be backed up.) Both the "saved" and the "unsaved" preferences reside in the storage heap and thus persist across soft resets. The only way that preferences are lost is if a hard reset is performed. "Which Preferences Database to Use" of the Palm OS Programmer's Companion, vol. I describes how to choose between the "saved" and "unsaved" preferences databases.
The version number that you pass as the version
parameter is returned when the preferences are retrieved by PrefGetAppPreferences()
. You can use this version number to determine if a new release of the application is being run for the first time. For more information, see the section "Updating Preferences Upon a New Release" of the Palm OS Programmer's Companion, vol. I.
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
PrefSetAppPreferencesV10 Function
Purpose
Save an application's preferences in the preferences database.
Declared In
Preferences.h
Prototype
void PrefSetAppPreferencesV10 ( UInt32 creator, Int16 version, void *prefs, UInt16 prefsSize )
Parameters
-
→
creator
- Creator ID of the application that owns this preference.
-
→
version
- Version number of the application.
-
→
prefs
- Pointer to a buffer holding preferences.
-
→
prefsSize
- Size of the buffer passed.
Returns
Comments
The content and format of an application preference is application-dependent.
Compatibility
This function corresponds to the 1.0 version of PrefSetAppPreferences
.
See Also
PrefSetAppPreferences()
, PrefGetPreferences()
PrefSetPreference Function
Purpose
Set a system preference. Using this function instead of PrefSetPreferences
allows you to set selected preferences without having to access the whole structure.
Declared In
Preferences.h
Prototype
void PrefSetPreference( SystemPreferencesChoice choice, UInt32 value )
Parameters
-
→
choice
- A
SystemPreferencesChoice
constant specifying the preference to be set. -
→
value
- Value to assign to the preference.
Returns
Returns nothing. If the specified preference cannot be found, displays a non-fatal error message on debug ROMs. On release ROMs, this function fails silently.
Compatibility
Implemented only if 2.0 New Feature Set is present.
PrefSetPreferences Function
Purpose
Declared In
Preferences.h
Prototype
void PrefSetPreferences ( SystemPreferencesPtr p )
Parameters
Returns
Comments
Unless there's a reason for you to access the whole preferences structure, call PrefSetPreference()
instead.
NOTE: This function can only be used to set preferences that were in the 1.0 version of the preferences structure.