Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

48    Preferences

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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 ^TOP^

MeasurementSystemType Enum ^TOP^

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 ^TOP^

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 ^TOP^

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

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 Enum ^TOP^

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 page900 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 page908 specifies which system preference is set by each user interface field in these two applications.

Table 48.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 made by dragging the pen from the input 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.

prefDefFepPlugInCreator

UInt32

10

Creator ID of the default FEP plug-in.

prefColorThemeID

DmResID

11

Resource ID of the color theme.

prefHandednessChoice

UInt16

12

Reserved for future use.

prefHWRCreator

UInt32

12

Creator ID of the handwriting recognition library.

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

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 ^TOP^

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.

preferenceDataVer10

10

Version 10 of the system preferences structure, used for Palm OS Garnet version 5.0.

preferenceDataVer11

11

Version 11 of the system preferences structure, used for Palm OS Garnet version 5.1.

preferenceDataVer12

12

Version 12 of the system preferences structure, used for Palm OS Garnet version 5.3SC.

preferenceDataVerLatest

preference
DataVer12

The latest version of the system preferences structure.

Preferences Functions ^TOP^

PrefGetAppPreferences Function ^TOP^

Purpose

Return a copy of an application's preferences resource.

Declared In

Preferences.h

Prototype

Int16 PrefGetAppPreferences (
   UInt32creator,
   UInt16id,
   void*prefs,
   UInt16*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 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. (Note that the pointer and the value to which it points must be initialized before you call PrefGetApPreferences.) Upon return, contains the number of bytes actually written or the number of bytes needed for the prefs structure.
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.
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.

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 ^TOP^

Purpose

Return a copy of an application's preferences.

Declared In

Preferences.h

Prototype

Boolean PrefGetAppPreferencesV10 (
   UInt32type,
   Int16version,
   void*prefs,
   UInt16prefsSize
)

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 ^TOP^

Purpose

Return a system preference. Use this function instead of PrefGetPreferences().

Declared In

Preferences.h

Prototype

UInt32 PrefGetPreference(
   SystemPreferencesChoicechoice
)

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 ^TOP^

Purpose

Return a copy of the system preferences.

Declared In

Preferences.h

Prototype

void PrefGetPreferences (
   SystemPreferencesPtrp
)

Parameters

p
Pointer to system preferences.

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

PrefSetPreferences()

PrefOpenPreferenceDB Function ^TOP^

Purpose

Return a handle to either the saved or unsaved preference database.

Declared In

Preferences.h

Prototype

DmOpenRef PrefOpenPreferenceDB (
   Booleansaved
)

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.

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 ^TOP^

Purpose

Return a handle to the system preference database.

Declared In

Preferences.h

Prototype

DmOpenRef PrefOpenPreferenceDBV10 (
   void
)

Parameters

None.

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 ^TOP^

Purpose

Set an application's preferences in the specified preferences database.

Declared In

Preferences.h

Prototype

void PrefSetAppPreferences (
   UInt32creator,
   UInt16id,
   Int16version,
   constvoid*prefs,
   UInt16prefsSize,
   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 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.

Returns

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 Function ^TOP^

Purpose

Save an application's preferences in the preferences database.

Declared In

Preferences.h

Prototype

void PrefSetAppPreferencesV10 (
   UInt32creator,
   Int16version,
   void*prefs,
   UInt16prefsSize
)

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

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 Function ^TOP^

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(
   SystemPreferencesChoicechoice,
   UInt32value
)

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 ^TOP^

Purpose

Set the system preferences.

Declared In

Preferences.h

Prototype

void PrefSetPreferences (
   SystemPreferencesPtrp
)

Parameters

p
Pointer to system preferences.

Returns

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()