Built-in Applications and System Data

System Data

Functions for Accessing User Configuration Data

19

The global functions

GetUserConfig

and

SetUserConfig

get and set the

values of user configuration variables in the system soup. These variables, see
"User Configuration Variables" (page 16-101) in Newton Programmer's Reference.
A list of these variables is available in the Summary; see 19 "User Configuration
Variables."

Your application can also register with the system to receive notification of changes
to these variables. To do this, use the functions

RegUserConfigChange

and

UnRegUserConfigChange

described in Newton Programmer's Reference.

The

RegUserConfigChange

global function registers a

callback function for execution in response to changes the user
configuration variables. This callback function must not call

RegUserConfigChange

or

UnRegUserConfigChange

.

Storing Application Preferences in the System Soup

19

Each application that needs to save user preference or state information should
create a single entry in the system soup to store its data. Each entry in the system
soup must contain a slot named

tag

whose value is a string uniquely identifying

the application to which the entry belongs. The system soup is indexed on the

tag

slot, allowing quick access to your application's entry.

Use the utility function

GetAppPrefs

to add your application's preferences entry

to the system soup.

GetAppPrefs

takes a default frame as a parameter, so you do

not need to create an entry in the system soup. The default is used if one doesn't
already exist. The following sample code illustrates how this is done:

//define a default frame
constant kDefaultPrefs :=

'{curCity : "Cupertino",
//... and other application specific slots.
// Note: we do not include a 'tag slot,
// this will be added by GetAppPrefs.
}

// then when we have information to store...
ourPrefsEntry := GetAppPrefs(kAppSymbol, kDefaultPrefs);
ourPrefsEntry.curCity := newCity;
EntryChange(ourPrefsEntry);

The

GetAppPrefs

function is described in Newton Programmer's Reference.