Preferences
 

 < 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
2
The country for which the device was built.
prefDateFormat
2
The short format used to display dates. For example:

95/12/31

prefLongDate
Format
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
2
The format used to display time values.
prefNumber
Format
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
2
Specifies whether system sounds are enabled or disabled.
prefGameSound
LevelV20
2
Specifies whether game sound effects are on or off.
prefAlarmSound
LevelV20
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
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
7
The system of measurement to use.
prefShow
Private
Records
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
9
The country selected to specify what the time zone is.
prefAutoLockType
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
9
The language that the device should use.
prefAttention
Flags
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
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

-> creatorCreator ID of the application that owns the preferences.
-> idID number of the preferences resource to retrieve. The IDs 0x8000 through 0xFFFF are reserved for system use.
<- prefsPointer to a buffer to hold the preferences.
<-> prefsSizePointer 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.
-> savedIf 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

-> typeCreator ID of the application that owns the preferences.
-> versionVersion number of the application's preferences.
<- prefsPointer to a buffer to hold preferences.
-> prefsSizeSize 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

-> choiceA 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

<- pPointer 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

-> savedIf 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

-> creatorCreator ID of the application that owns this preference.
-> idID number of the preference to set. An application can have multiple preferences. The IDs 0x8000 through 0xFFFF are reserved for system use.
-> versionVersion number of the application's preferences.
-> prefsPointer to a buffer that holds the current value of the preferences structure. Pass NULL if you want to delete the preferences.
-> prefsSizeSize of the buffer passed. Pass 0 if you want to delete the preferences structure.
-> savedIf 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

-> creatorCreator ID of the application that owns this preference.
-> versionVersion number of the application.
-> prefsPointer to a buffer holding preferences.
-> prefsSizeSize 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.
-> valueValue 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

-> pPointer 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