< Home < Developers < Development Support < Documentation

## 44 Preferences

Table of Contents | < Previous | Next > | Index

| Title - Palm OS® Programmer's API Reference Part II: System Management 44 Preferences Preferences Data Types MeasurementSystemType SecurityAutoLockType SoundLevelTypeV20 SystemPreferencesChoice Preferences Constants Preferences Functions PrefGetAppPreferences PrefGetAppPreferencesV10 PrefGetPreference PrefGetPreferences PrefOpenPreferenceDB PrefOpenPreferenceDBV10 PrefSetAppPreferences PrefSetAppPreferencesV10 PrefSetPreference PrefSetPreferences |  |  |  | This chapter describes the preferences API as declared in the header file Preferences.h. It discusses the following topics: Preferences Data Types Preferences Constants Preferences Functions For more information on preferences, see the section "Preferences" of the Palm OS Programmer's Companion, vol. I. ## Preferences Data Types ## MeasurementSystemType The MeasurementSystemType enum specifies the preference for units of measure.
    typedef enum {
      unitsEnglish = 0,
      unitsMetric
    } MeasurementSystemType;
#### Value Descriptions #####
unitsEnglish | The English measurement system (feet, inches, and so on).
unitsMetric | The Metric system (meters, centimeters, and so on).
## New SecurityAutoLockType 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.
    typedef enum {
      never = 0,
      uponPowerOff,
      atPresetTime,
      afterPresetDelay
    } SecurityAutoLockType;
#### Value Descriptions #####
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 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.
    typedef enum {
      slOn = 0,
      slOff = 1
    } SoundLevelTypeV20;
#### Value Descriptions #####
slOn | Enabled
slOff | Disabled
#### 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 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 44.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 44.1 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 44.2 specifies which system preference is set by each user interface field in these two applications. #####
Table 44.1 SystemPreferencesChoice Constants
Constant | Type | Version | Description
--- | --- | --- | ---
prefVersion | UInt16 | 2 | The preferences version number.
prefCountry | CountryType | 2 | The country for which the device was built.
prefDateFormat | DateFormatType | 2 | The short format used to display dates. For example: 95/12/31
prefLongDate Format | DateFormatType | 2 | The long format used to display dates. For example: 31 Dec 1995
prefWeek StartDay | Int8 | 2 | The first day of the week (Sunday or Monday). Days of the week are numbered from 0 to 6 starting with Sunday = 0.
prefTimeFormat | TimeFormatType | 2 | The format used to display time values.
prefNumber Format | NumberFormatType | 2 | The format used for numbers, with regards to the thousands separator and the decimal point.
prefAutoOff Duration | UInt8 | 2 | Minutes of user idle time before the device powers off. The default value for this preference is specified by the defaultAutoOffDuration constant.
|  |  | prefAutoOffDuration is replaced by prefAutoOffDurationSecs in version 8 of the preferences structure.
prefSysSound LevelV20 | SoundLevelTypeV20 | 2 | Specifies whether system sounds are enabled or disabled.
prefGameSound LevelV20 | SoundLevelTypeV20 | 2 | Specifies whether game sound effects are on or off.
prefAlarmSound LevelV20 | SoundLevelTypeV20 | 2 | Specifies whether sound alarms are on or off.
prefHidePrivate RecordsV33 | Boolean | 2 | If true, applications should not display database records that have the secret attribute bit set.
prefDeviceLocked | Boolean | 2 | If true, the device is locked. When the device is locked, it remains so until the user enters the password.
prefLocal SyncRequires Password | Boolean | 2 | If true, the user must enter a password before a HotSync® operation can be performed.
prefRemote SyncRequires Password | Boolean | 2 | If true, the user must enter a password on the desktop computer before a HotSync operation can be performed.
prefSysBattery Kind | Sys Battery Kind | 2 | The type of batteries installed. Use SysBatteryInfo to retrieve the battery type instead of this preference.
prefMinutes WestOfGMT | UInt32 | 2 | The time zone given as minutes east of Greenwich Mean Time (GMT). For preferences version 9 and higher, use prefTimeZone instead.
prefDaylight Savings | DaylightSavingsTypes | 2 | The type of daylight savings correction. For preferences version 9 and higher, use prefDaylightSavingAdjustment instead.
prefRonamatic Char | UInt16 | 2 | The virtual character generated when the user enters the ronamatic stroke. The ronamatic stroke is dragging the pen from the Graffiti® area to the top of the screen.
prefHard1Char AppCreator | UInt32 | 2 | The creator ID of the application to be launched by the left-most hard key (the Date Book button by default).
prefHard2Char AppCreator | UInt32 | 2 | The creator ID of the application to be launched by the second hard key from the left (the Address button by default).
prefHard3Char AppCreator | UInt32 | 2 | The creator ID of the application to be launched by the second hard key from the right (the To Do List button by default).
prefHard4Char AppCreator | UInt32 | 2 | The creator ID of the application to be launched by the right-most hard key (the Memo Pad button by default).
prefCalcChar AppCreator | UInt32 | 2 | The creator ID of the application to be launched by the Calculator silkscreen button.
prefHardCradle CharAppCreator | UInt32 | 2 | The creator ID of the application to be launched by the hard key on the HotSync cradle.
prefLauncher AppCreator | UInt32 | 2 | The creator ID of the application to be launched by the Applications silkscreen button.
prefHardCradle2 CharAppCreator | UInt32 | 2 | The creator ID of the application to be launched by the HotSync button on the modem.
prefAnimation Level | AnimationLevelType | 2 | Reserved for future use.
prefSys SoundVolume | UInt16 | 3 | The sound level for system sounds, such as taps and beeps. This is a value from 0 to sndMaxAmp.
prefGame SoundVolume | UInt16 | 3 | The sound level for game sounds. This is a value from 0 to sndMaxAmp.
prefAlarm SoundVolume | UInt16 | 3 | The sound level for alarms. This is a value from 0 to sndMaxAmp.
prefBeamReceive | Boolean | 3 | If true, the device can receive beams from other devices. If false, the device cannot receive beams but can still send them.
|  |  | This preference is not currently used. Instead, use the ExgControl function with one of the constants described in "IR Control Constants."
prefCalibrate DigitizerAtReset | Boolean | 3 | If true, the user must recalibrate the digitizer after a soft reset. The default is false.
prefSystem KeyboardID | UInt16 | 4 | The resource ID of the keyboard panel.
prefDefSerial PlugIn | UInt32 | 4 | The creator ID of the default serial plug-in database.
prefStayOn WhenPluggedIn | Boolean | 5 | If true, the device stays powered on when it is in the cradle.
prefStayLit WhenPluggedIn | Boolean | 5 | If true and prefStayOnWhenPluggedIn is true, the device stays lit when it is in its cradle.
prefAntenna CharAppCreator | UInt32 | 6 | The creator ID of the application to launch when the antenna is raised (used only for devices with built-in antennas).
prefMeasurement System | MeasurementSystemType | 7 | The system of measurement to use.
prefShow Private Records | privateRecordViewEnum | 8 | Specifies whether the private records should be displayed, masked, or completely hidden.
prefAutoOff DurationSecs | UInt16 | 8 | Seconds of user idle time before the device powers off. The default value for this preference is specified by the defaultAutoOffDurationSecs constant.
prefTimeZone | Int16 | 9 | The time zone given as minutes east of Greenwich Mean Time (GMT). IMPORTANT: Changing the value of this preference does not update the current time.
prefDaylight Saving Adjustment | Int16 | 9 | The number of minutes to add to the current time for daylight savings time. IMPORTANT: Changing the value of this preference does not update the current time.
prefTimeZone Country | CountryType | 9 | The country selected to specify what the time zone is.
prefAutoLockType | SecurityAutoLockType | 9 | 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.
prefAutoLockTime | UInt32 | 9 | 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 prefAutoLockType, this value is either an absolute date and time given as the number of seconds since January 1, 1904 or a timeout value given as a number of seconds from the current time.
prefAutoLock TimeFlag | Boolean | 9 | If true, prefAutoLockTime is given in minutes. If false, the time is given in hours.
prefLanguage | LanguageType | 9 | The language that the device should use.
prefAttention Flags | AttnFlagsType | 9 | The user's preferences for receiving attention signals. The returned value is a bit mask that should be tested (using the & operator) with one of the following values:
|  |  | kAttnFlagsUserWantsLED kAttnFlagsUserWants Sound kAttnFlagsUserWants Vibrate kAttnFlagsUserWants CustomEffect
|  |  | Note that you can override the values in prefAttentionFlags when you make Attention Manager function calls. See the section "Getting the User's Attention" of the Palm OS Programmer's Companion, vol. I for more information.
prefDefault AppCreator | UInt32 | 9 | Creator ID of the application that is launched after a reset. If 0, the system default application is launched.
prefLocale | LmLocaleType | 9 | The device's current locale, which specifies the country and language.
#### Preferences in the User Interface Table 44.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 44.1. #####
Table 44.2 Preferences set in standard apps
Application/Panel | Field | SystemPreferencesChoice Constant
--- | --- | ---
Preferences application General panel | Auto-off After | prefAutoOffDuration, prefAutoOffDurationSecs (Palm OS 3.5 and higher)
Stay on in Cradle | prefStayOnWhenPluggedIn
System Sound | prefSysSoundLevelV20, prefSysSoundVolume
Alarm Sound | prefAlarmSoundLevelV20, prefAlarmSoundVolume
Alarm Vibrate1 | prefAttentionFlags
Alarm LEDa | prefAttentionFlags
Game Sound | prefGameSoundLevelV20, prefGameSoundVolume
Beam Receive field | prefBeamReceive
Preferences application Date & Time panel | Set Time Zone field | prefTimeZone
Daylight Saving | prefDaylightSaving Adjustment
Preferences application Formats panel | Preset to | prefCountry
Time | prefTimeFormat
Date | prefDateFormat, prefLongDateFormat
Week starts | prefWeekStartDay
Numbers | prefNumberFormat
Preferences application Buttons panel | Buttons on main panel | prefHard1CharAppCreator, prefHard2CharAppCreator, prefHard3CharAppCreator, prefHard4CharAppCreator, prefCalcCharAppCreator, prefLauncherAppCreator
Pen button | prefRonamaticChar
HotSync button | prefHardCradleCharApp Creator prefHardCradle2CharApp Creator
Security application | Current Privacy | prefHidePrivateRecordsV33, prefShowPrivateRecords
Security application | Lock & Turn Off button | prefDeviceLocked, prefAutoLockType, prefAutoLockTime, prefAutoLockTimeFlag
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. #####
Constant | Value | Description
--- | --- | ---
defaultAutoLockTime | 0 | Initial setting for the prefAutoLockTime preference.
defaultAutoLockTimeFlag | 0 | Initial setting for the prefAutoLockTimeFlag preference.
defaultAutoLockType | never | Initial setting for the prefAutoLockType preference.
defaultAutoOffDuration | 2 | Initial setting for the prefAutoOffDuration preference, given in minutes.
defaultAutoOffDuration Secs | 120 | Initial setting for the prefAutoOffDurationSecs preference, given in seconds. The value is 2 times the number of seconds in a minute, or 120 seconds.
defaultAlarmSoundLevel | slOn | Initial setting for the prefAlarmSoundLevelV20 preference.
defaultAlarmSoundVolume | sndMaxAmp | Initial setting for the prefAlarmSoundVolume preference.
defaultGameSoundLevel | slOn | Initial setting for the prefGameSoundLevelV20 preference.
defaultGameSoundVolume | sndMaxAmp | Initial setting for the prefGameSoundVolume preference.
defaultSysSoundLevel | slOn | Initial setting for the prefSysSoundLevelV20 preference.
defaultSysSoundVolume | sndMaxAmp | Initial setting for the prefSysSoundVolume preference.
noPreferenceFound | -1 | The value that PrefGetAppPreferences returns to indicate that preferences couldn't be found.
preferenceDataVer2 | 2 | Version 2 of the system preferences structure, used for Palm OS 2.0.
preferenceDataVer3 | 3 | Version 3 of the system preferences structure, used for Palm OS 3.0.
preferenceDataVer4 | 4 | Version 4 of the system preferences structure, used for Palm OS 3.1.
preferenceDataVer5 | 5 | Version 5 of the system preferences structure, used for Palm OS 3.2.
preferenceDataVer6 | 6 | Version 6 of the system preferences structure, used for Palm OS 3.3.
preferenceDataVer8 | 8 | Version 8 of the system preferences structure, used for Palm OS 3.5.
preferenceDataVer9 | 9 | Version 9 of the system preferences structure, used for Palm OS 4.0.
preferenceDataVerLatest | preference DataVer9 | The latest version of the system preferences structure.
## Preferences Functions ## PrefGetAppPreferences #### Purpose Return a copy of an application's preferences resource. #### 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 through 0xFFFF 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. Upon return, contains the number of bytes actually written or the number of bytes needed for the prefs structure.
#####
| You can determine the required size for the prefs structure by passing NULL for prefs. Upon return, the prefsSize parameter contains the required size.
#####
| 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. If false, retrieve the preferences from the "unsaved" preferences database, which is usually not backed up during a HotSync operation.
#### Result 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. 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 #### Purpose Return a copy of an application's preferences. #### 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.
#### Result 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 #### Purpose Return a system preference. Use this function instead of PrefGetPreferences. #### Prototype UInt32 PrefGetPreference (SystemPreferencesChoice choice) #### Parameters #####
-> choice | A constant that specifies what preference to retrieve. See SystemPreferencesChoice.
#### Result 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 #### Purpose Return a copy of the system preferences. #### Prototype void PrefGetPreferences (SystemPreferencesPtr p) #### Parameters #####
<- p | Pointer to system preferences.
#### Result 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 PrefSetPreferences ## PrefOpenPreferenceDB #### Purpose Return a handle to either the saved or unsaved preference database. #### Prototype DmOpenRef PrefOpenPreferenceDB (Boolean saved) #### Parameters #####
-> saved | If true, open the "saved" preferences database, which is backed up during a HotSync operation. If false, open the "unsaved" preferences database, which usually is not backed up during a HotSync operation.
#### Result 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 #### Purpose Return a handle to the system preference database. #### Prototype DmOpenRef PrefOpenPreferenceDBV10 (void) #### Parameters None. #### Result 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 #### Purpose Set an application's preferences in the specified preferences database. #### 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 through 0xFFFF 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.
#### Result Returns nothing. #### 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 ## PrefSetAppPreferencesV10 #### Purpose Save an application's preferences in the preferences database. #### 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.
#### Result Returns nothing. #### 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 #### Purpose Set a system preference. Using this function instead of PrefSetPreferences allows you to set selected preferences without having to access the whole structure. #### 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.
#### Result 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 #### Purpose Set the system preferences. #### Prototype void PrefSetPreferences (SystemPreferencesPtr p) #### Parameters #####
-> p | Pointer to system preferences.
#### Result Returns nothing. #### 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. #### See Also PrefGetPreferences |