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

33    Preferences

System Management

Exploring Palm OS®

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

PrefActivePanelParamsType Struct ^TOP^

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

activePanel
The active panel.

Preferences Constants ^TOP^

MeasurementSystemType Typedef ^TOP^

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

Purpose

Specifies whether certain sounds are enabled or disabled.

Declared In

Preferences.h

Prototype

typedef Enum8 SoundLevelTypeV20

Constants

slOn = 0
Enabled.
slOff = 1
Disabled.

SystemPreferencesChoice Typedef ^TOP^

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.

Constant

Type

Description

prefVersion

uint16_t

The preferences version number.

prefCountry68K

CountryType

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 prefLocale value instead. Native ARM applications should call LmGetFormatsLocale() to find out what locale the user has selected in the Formats panel, and LmSetFormatsLocale() to change it.

prefDateFormat

DateFormatType

The short format used to display dates. For example:
95/12/31

prefLongDateFormat

DateFormatType

The long format used to display dates. For example:
31 Dec 1995

prefWeekStartDay

int8_t

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

The format used to display time values.

prefNumberFormat

NumberFormatType

The format used for numbers, with regards to the thousands separator and the decimal point.

prefAutoOffDuration

uint8_t

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.

prefSysSoundLevelV20

SoundLevelTypeV20

Specifies whether system sounds are enabled or disabled.

prefGameSoundLevelV20

SoundLevelTypeV20

Specifies whether game sound effects are on or off.

prefAlarmSoundLevelV20

SoundLevelTypeV20

Specifies whether alarm sounds are on or off.

prefHidePrivateRecordsV33

Boolean

If true, applications should not display database records that have the secret attribute bit set.

prefDeviceLocked

Boolean

If true, the device is locked. When the device is locked, it remains so until the user enters the password.

prefLocalSyncRequiresPassword

Boolean

If true, the user must enter a password before a HotSync® operation can be performed.

prefRemoteSyncRequiresPassword

Boolean

If true, the user must enter a password on the desktop computer before a HotSync operation can be performed.

prefSysBatteryKind

Sys
Battery
Kind

The type of batteries installed. Use SysBatteryInfo() to retrieve the battery type instead of this preference.

prefAllowEasterEggs

prefMinutesWestOfGMT

uint32_t

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 prefTimeZone instead.

prefDaylightSavings

DaylightSavingsTypes

The type of daylight savings correction. For preferences version 9 and higher, use prefDaylightSavingAdjustment instead.

prefRonamaticChar

uint16_t

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.

prefHard1CharAppCreator

uint32_t

The creator ID of the application to be launched by the left-most hard key (the Date Book button by default).

prefHard2CharAppCreator

uint32_t

The creator ID of the application to be launched by the second hard key from the left (the Address button by default).

prefHard3CharAppCreator

uint32_t

The creator ID of the application to be launched by the second hard key from the right (the To Do List button by default).

prefHard4CharAppCreator

uint32_t

The creator ID of the application to be launched by the right-most hard key (the Memo Pad button by default).

prefCalcCharAppCreator

uint32_t

The creator ID of the application to be launched by the Calculator silk-screen button.

prefHardCradleCharAppCreator

uint32_t

The creator ID of the application to be launched by the hard key on the HotSync cradle.

prefLauncherAppCreator

uint32_t

The creator ID of the application to be launched by the status bar icon.

prefSysPrefFlags

prefHardCradle2CharAppCreator

uint32_t

The creator ID of the application to be launched by the HotSync button on the modem.

prefAnimationLevel

AnimationLevelType

Reserved for future use.

prefSysSoundVolume

uint16_t

The sound level for system sounds, such as taps and beeps. This is a value from 0 to sndMaxAmp.

prefGameSoundVolume

uint16_t

The sound level for game sounds. This is a value from 0 to sndMaxAmp.

prefAlarmSoundVolume

uint16_t

The sound level for alarms. This is a value from 0 to sndMaxAmp.

prefBeamReceive

Boolean

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.

prefCalibrateDigitizerAtReset

Boolean

If true, the user must recalibrate the digitizer after a soft reset. The default is false.

prefSystemKeyboardID

uint16_t

The resource ID of the keyboard panel.

prefDefSerialPlugIn

uint32_t

The creator ID of the default serial plug-in database.

prefStayOnWhenPluggedIn

Boolean

If true, the device stays powered on when it is in the cradle.

prefStayLitWhenPluggedIn

Boolean

If true and prefStayOnWhenPluggedIn is true, the device stays lit when it is in its cradle.

prefAntennaCharAppCreator

uint32_t

The creator ID of the application to launch when the antenna is raised (used only for devices with built-in antennas).

prefMeasurementSystem

MeasurementSystemType

The system of measurement to use.

prefShowPrivateRecords

privateRecordViewEnum

Specifies whether the private records should be displayed, masked, or completely hidden.

prefAutoOffDurationSecs

uint16_t

Seconds of user idle time before the device powers off. The default value for this preference is specified by the defaultAutoOffDurationSecs constant.

prefTimeZone

int16_t

The time zone given as minutes east of Greenwich Mean Time (GMT).
Changing the value of this preference does not update the current time.

prefDaylightSavingAdjustment

int16_t

The number of minutes to add to the current time for daylight savings time.
Changing the value of this preference does not update the current time.

prefAutoLockType

Private structure

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_t

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 time-out value given as a number of seconds from the current time.

prefAutoLockTimeFlag

Boolean

If true, prefAutoLockTime is given in minutes. If false, the time is given in hours.

prefLanguage68K

LanguageType

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 prefLocale value instead. Native ARM applications should call LmGetFormatsLocale() to find out what locale the user has selected in the Formats panel, and LmSetFormatsLocale() to change it.

prefFormatsLocale68K

LmLocaleType

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 LmGetFormatsLocale() to find out what locale the user has selected in the Formats panel, and LmSetFormatsLocale() to change it.

prefTimeZoneCountry

CountryType

The country selected to specify what the time zone is.

prefAttentionFlags

AttnFlagsType

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
kAttnFlagsUserWantsSound
kAttnFlagsUserWantsVibrate
kAttnFlagsUserWantsCustomEffect
Note that you can override the values in this preference when you make Attention Manager function calls.

prefDefaultAppCreator

uint32_t

Creator ID of the application that is launched after a reset. If 0, the system default application is launched.

prefDefFepPlugInCreator

uint32_t

Creator ID of the default FEP plug-in.

prefColorThemeID

DmResourceID

Resource ID of the color theme.

reservedPrefs1

Reserved for future use.

reservedPrefs2

Reserved for future use.

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

prefAppLaunchCmdSetActivePanel ^TOP^

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

PrefGetAppPreferences Function ^TOP^

Purpose

Return a copy of an application's preferences resource.

Declared In

Preferences.h

Prototype

int16_t PrefGetAppPreferences (
   uint32_t creator,
   uint16_t id,
   void *prefs,
   uint32_t *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. (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.
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.

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

Purpose

Return a system preference.

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

Purpose

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

Declared In

Preferences.h

Prototype

void PrefSetAppPreferences (
   uint32_t creator,
   uint16_t id,
   int16_t version,
   const void *prefs,
   uint32_t 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.

Returns

Returns nothing.

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

Purpose

Set a system preference.

Declared In

Preferences.h

Prototype

void PrefSetPreference (
   SystemPreferencesChoice choice,
   uint32_t 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.

See Also

PrefGetPreference(), PrefSetAppPreferences()