This chapter documents the APIs you use when getting and setting system-wide and application-specific preferences. The material in this chapter is organized as follows:
Preferences Structures and Types
Preferences Constants
Preferences Functions and Macros
The header file Preferences.h
declares the API that this chapter describes. For more information on preferences, see Chapter 3, "Preferences."
Preferences Structures and Types
PrefActivePanelParamsType Struct
Purpose
Defines the parameter block that accompanies a prefAppLaunchCmdSetActivePanel
launch code. This parameter block identifies the active panel.
Declared In
Preferences.h
Prototype
typedef struct { uint32_t activePanel; } PrefActivePanelParamsType
typedef PrefActivePanelParamsType *PrefActivePanelParamsPtr
Fields
Preferences Constants
MeasurementSystemType Typedef
Purpose
The system of measurement that the system is to use.
Declared In
Preferences.h
Prototype
typedef Enum8 MeasurementSystemType
Constants
-
unitsEnglish = 0
- The English measurement system (feet, inches, and so on).
-
unitsMetric
- The Metric system (meters, centimeters, and so on).
SoundLevelTypeV20 Typedef
Purpose
Specifies whether certain sounds are enabled or disabled.
Declared In
Preferences.h
Prototype
typedef Enum8 SoundLevelTypeV20
Constants
SystemPreferencesChoice Typedef
Purpose
A system preference value. You can pass these values to PrefGetPreference()
and PrefSetPreference()
to retrieve or set a system preference value. There is one constant for each field in the SystemPreferencesType
structure, which should be considered private.
Declared In
Preferences.h
Prototype
typedef Enum8 SystemPreferencesChoice
Constants
The following table lists and describes the constants that this enum defines. For each constant, it shows what type of data is returned by PrefGetPreference()
for that constant.
The country for which the device was built. This preference is intended to be used by applications running under PACE—although such applications should really use the |
||
The short format used to display dates. For example: |
||
The long format used to display dates. For example: |
||
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 (not west, as the name implies) 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 silk-screen 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 status bar icon. |
||
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 |
||
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 language that the device should use. This preference is intended to be used by applications running under PACE—although such applications should really use the |
||
The device's current locale, which specifies the country and language. This preference is intended to be used by applications running under PACE. Native ARM applications should call |
||
The user's preferences for receiving attention signals. The returned value is a bit mask that should be tested (using the |
||
Creator ID of the application that is launched after a reset. If 0, the system default application is launched. |
||
Comments
Most of the system preferences can be set in the Preferences and Security applications. Table 3.1 on page 39 specifies which system preference is set by each user interface field in these two applications.
Preferences Launch Codes
prefAppLaunchCmdSetActivePanel
Purpose
Declared In
Preferences.h
Prototype
#define prefAppLaunchCmdSetActivePanel (sysAppLaunchCmdCustomBase + 1)
Parameters
The launch code's parameter block pointer references a PrefActivePanelParamsType
structure.
See Also
Chapter 6, "Common Launch Codes," in Exploring Palm OS: Programming Basics
Preferences Functions and Macros
PrefGetAppPreferences Function
Purpose
Return a copy of an application's preferences resource.
Declared In
Preferences.h
Prototype
int16_t PrefGetAppPreferences ( uint32_tcreator
, uint16_tid
, void*prefs
, uint32_t*prefsSize
, Booleansaved
)
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. -
→ 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.
To determine the required size for the prefs
structure, set prefsSize
to 0 and pass NULL
for prefs
. Upon return, the prefsSize
parameter contains the required size. Never set prefs
to NULL
without also setting prefsSize
to 0. After allocating the required amount of memory to obtain a copy of the application's preferences resource, then call PrefGetAppPreferences()
a second time to actually obtain the preference values.
NOTE: Always compare the value returned in the
prefsSize
parameter with the value you passed in. If the two values differ, you need to resize the prefs
structure and call this function again.
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 "Updating Preferences Upon a New Release."
See Also
PrefGetPreference()
, PrefSetAppPreferences()
PrefGetPreference Function
Purpose
Declared In
Preferences.h
Prototype
uint32_t 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.
See Also
PrefGetAppPreferences()
, PrefSetPreference()
PrefSetAppPreferences Function
Purpose
Set an application's preferences in the specified preferences database.
Declared In
Preferences.h
Prototype
void PrefSetAppPreferences ( uint32_tcreator
, uint16_tid
, int16_tversion
, const void*prefs
, uint32_tprefsSize
, Booleansaved
)
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.
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" 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 "Updating Preferences Upon a New Release."
See Also
PrefGetAppPreferences()
, PrefSetPreference()
PrefSetPreference Function
Purpose
Declared In
Preferences.h
Prototype
void PrefSetPreference ( SystemPreferencesChoicechoice
, uint32_tvalue
)
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.
See Also
PrefGetPreference()
, PrefSetAppPreferences()