Objective

To be able to get and set system and application preferences.

 Concepts

System preferences vs Application preferences

Preferences are used to store data such as system parameters (volume sound, date formats...) or application settings (sorting options in AddressBook, repeat every X minutes in DateBook...). System preferences are defined by the team who develops Palm OS whereas application preferences are defined by the application's author, who is free to determine the nature, type and meaning of each parameter s/he defines as a preference.

Getting and setting preferences

System-wide preferences may be managed with a couple of APIs:

• gSysSoundVolume = PrefGetPreference(prefSysSoundVolume);
• PrefSetPreference(prefSysSoundVolume, gSysSoundVolume);

Application-wide prefs use the following APIs:

• if (
       PrefGetAppPreferences(creatorID, 0, &gAppPrefs, &nAppPrefsSize, true)
       == noPreferenceFound
     )
     MemSet(&gAppPrefs, sizeof(gAppPrefs), 0);
  creatorID is what helps Palm OS determine what prefs belong to what app. gAppPrefs is a struct{...} that you have to define as the container of your preferences. It is recommended that the return code be checked against noPreferenceFound, and that nAppPrefsSize be check against the expected size of your preferences, because any corrupted or undefined preference may cause the app to behave in an unexpected and hard-to-figure-out way. Instead, you should detect such error and force the preferences to default values that make sense for your app.
  
• PrefSetAppPreferences(creatorID, 0, versionID, &gAppPrefs, sizeof(gAppPrefs), true);
  You may use versionID to manage the evolution of the data structure of your prefs.

 Exercise

Download the ZIP file.

The user of this app will be able to change system preferences (System sound volume, Stay on in cradle, Calibrate digitizer at reset) and application preferences (a boolean, a number and a string).

In prefs.h:

• define ID MainAppBoolean for the POPUPTRIGGER that contains a boolean value
• define ID MainAppBooleanList for the "No/Yes" LIST linked to the POPUPTRIGGER
• define ID MainAppNumber for the FIELD that contains a numerical value
• define ID MainAppString for the FIELD that holds our string value

In prefs.rcp:

• add a button to save app prefs: title is "Save!", ID is MainSaveApp, position is (CENTER@120 PREVTOP AUTO AUTO), style is BOLDFRAME
• add a No/Yes control for our boolean parameter, like this:
  POPUPTRIGGER "Select" ID MainAppBoolean AT (PREVRIGHT PREVTOP 80 AUTO)
  LIST "No" "Yes" ID MainAppBooleanList AT (PREVLEFT PREVTOP AUTO AUTO) VISIBLEITEMS 2 NONUSABLE
  POPUPLIST ID MainAppBoolean MainAppBooleanList
• same for our numerical parameter:
  FIELD ID MainAppNumber AT (PREVRIGHT PREVTOP 20 AUTO) LEFTALIGN EDITABLE UNDERLINED MAXCHARS 4 NUMERIC RIGHTALIGN
• same for our string: a FIELD whose ID is MainAppString, position is (PREVRIGHT PREVTOP 60 AUTO), left-aligned, editable, underlined, maximum # of chars is 10
  

In prefs.c:

• define creatorID as 'TuPr' and versionID as 1
• define our prefs structure as follows:
  struct
  {
    Boolean b;
    UInt ui;
    Char s[11];
  }
  gAppPrefs;
  
• when user taps "save" on sys prefs, add this chunk of code to save the last 2 sys parameters:
  PrefSetPreference(prefStayOnWhenPluggedIn, GetList(MainForm, MainStayOnWhenPluggedInList) ? 1 : 0);
  PrefSetPreference(prefCalibrateDigitizerAtReset, GetList(MainForm, MainCalibrateDigitizerAtResetList) ? 1 : 0);
• add this one to save app prefs:
  gAppPrefs.b = GetList(MainForm, MainAppBooleanList) ? true : false;
  gAppPrefs.ui = StrAToI(GetField(MainForm, MainAppNumber));
  StrNCopy(gAppPrefs.s, GetField(MainForm, MainAppString), sizeof(gAppPrefs.s)-1);
  PrefSetAppPreferences(creatorID, 0, versionID, &gAppPrefs, sizeof(gAppPrefs), true);
• in AppStart(), get sys prefs like this:
  gAutoOffDuration = PrefGetPreference(prefAutoOffDuration);
  gSysSoundVolume = PrefGetPreference(prefSysSoundVolume);
  gStayOnWhenPluggedIn = PrefGetPreference(prefStayOnWhenPluggedIn);
  gCalibrateDigitizerAtReset = PrefGetPreference(prefCalibrateDigitizerAtReset);
• and app prefs like that:
  nAppPrefsSize = sizeof(gAppPrefs);
  if (PrefGetAppPreferences(creatorID, 0, &gAppPrefs, &nAppPrefsSize, true) == noPreferenceFound)
     MemSet(&gAppPrefs, sizeof(gAppPrefs), 0);
  

 Solution

Here's the ZIP file.

And here's how the app should like:

Next topic