Fnd_Pref

Fnd_Pref_Alert

Fnd_Pref_Alert (message)

Displays an alert message. Uses the Foundation Dialog module alert if available.

Fnd_Pref_CreateTable

Fnd_Pref_CreateTable

Method Type:    Private

Fnd_Pref_Display

Fnd_Pref_Display (preferences form name)

Displays the Preferences window in a new process.

Fnd_Pref_DummyMethod

Fnd_Pref_DummyMethod

A generic method with no code. This is useful for assigning as the close box method for new windows (handle the close in the form method) or to use with ON ERR CALL to disable any automatic reaction to errors.

Deprecated 2026-08-22. Call Fnd_Gen_SilentError instead. The body was always empty, so the two methods were never different. This one served nothing — it had no caller in Foundation at all.

No parameters.

Fnd_Pref_Editor

Fnd_Pref_Editor

Opens the preferences editor: a list of the stored preferences, with their types and values, editable in place and deletable.

Local preferences are listed. Server scoped ones share the same store and are shown when the checkbox asks for them, since a preference that plainly exists should not look missing.

Fnd_Pref_Editor

No parameters.

Fnd_Pref_ErrorHandler

Fnd_Pref_ErrorHandler

Installed as an error handler by our preferences loading routines. Usually called because of an XML parsing error. Displays an alert to the user.

No parameters.

Fnd_Pref_GetBoolean

Fnd_Pref_GetBoolean (name{; default{; scope}}) --> Boolean

Retrieves a Boolean value in from user's preferences file. If an item with the specified name isn't found, the default value is returned (if specified). Otherwise False is returned.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, naming a namespace of the caller's own in [Fnd_Pref]. A label is read from that namespace alone, so nothing local shadows it; a constant only says where to store a default that has to be created, and does not filter the read.

Fnd_Pref_GetLongInt

Fnd_Pref_GetLongInt (name{; default{; scope}}) --> Longint

Retrieves a long integer value in from user's preferences file. If an item with the specified name isn't found, the default value is returned (if specified). Otherwise, 0 is returned.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, naming a namespace of the caller's own in [Fnd_Pref]. A label is read from that namespace alone, so nothing local shadows it; a constant only says where to store a default that has to be created, and does not filter the read.

Fnd_Pref_GetObject

Fnd_Pref_GetObject (name{; default{; scope}}) --> Object

Retrieves an Object in from user's preferences file. If an item with the specified name isn't found, the default value is returned (if specified). Otherwise, an empty object is returned.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, naming a namespace of the caller's own in [Fnd_Pref]. A label is read from that namespace alone, so nothing local shadows it; a constant only says where to store a default that has to be created, and does not filter the read.

Fnd_Pref_GetProcessWindowRef

Fnd_Pref_GetProcessWindowRef (process number) --> Number

Returns the window ref for the frontmost window of the specified process.

There's also a Fnd_Wnd_GetProcessWindowRef method, but it may not be installed.

Fnd_Pref_GetReal

Fnd_Pref_GetReal (name{; default{; scope}}) --> Real

Retrieves a real number value in from user's preferences file. If an item with the specified name isn't found, the default value is returned (if specified). Otherwise, 0 is returned.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, naming a namespace of the caller's own in [Fnd_Pref]. A label is read from that namespace alone, so nothing local shadows it; a constant only says where to store a default that has to be created, and does not filter the read.

Fnd_Pref_GetSharedValue

Fnd_Pref_GetSharedValue (pref name; ->value{; owner}) --> Boolean

Returns a shared preference value from the database.

With an owner, reads that owner's namespace instead of the shared one, which is how a labelled preference is read.

The value is only written through the pointer when the stored type matches the type of the variable pointed at, so a caller's default survives a mismatch. The same is true when the stored type is object but the stored text isn't valid JSON - the row is treated as not-found rather than raising out of this method.

Fnd_Pref_GetText

Fnd_Pref_GetText (name{; default{; scope}}) --> Text

Retrieves a text value in from user's preferences file. If an item with the specified name isn't found, the default value is returned (if specified).

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, naming a namespace of the caller's own in [Fnd_Pref]. A label is read from that namespace alone, so nothing local shadows it; a constant only says where to store a default that has to be created, and does not filter the read.

Fnd_Pref_GetWindow

Fnd_Pref_GetWindow (name; ->left; ->top; ->right; ->bottom)

Retrieves a text value in from user's preferences file. If an item with the specified name isn't found, the default value is returned (if specified).

Fnd_Pref_Info

Fnd_Pref_Info (label) --> Text

Returns requested information. See the Fnd_Gen_ComponentInfo method for more information.

Fnd_Pref_Iso2Utf8

Fnd_Pref_Iso2Utf8 (text) --> Text

Converts ISO text to UTF-8-encoded text.

Fnd_Pref_LegacyPath

Fnd_Pref_LegacyPath --> Text

Returns the path to the preferences file written by versions before the move to JSON: an Apple property list, named .plist on macOS and .xml on Windows.

Read by Fnd_Pref_LoadLocalPrefs when there is no JSON file yet, so an installation converts itself the first time it runs. Nothing writes it any more, and it is left on disk rather than deleted so a downgrade still has something to read.

Fnd_Pref_LoadLegacyPrefs

Fnd_Pref_LoadLegacyPrefs

Reads the Apple property list that versions before the JSON file wrote, and puts what it holds into the preference arrays. Called by Fnd_Pref_LoadLocalPrefs when there is no JSON file yet, so an existing installation converts itself the first time it runs.

Nothing writes this file any more. It is left on disk rather than deleted, so a downgrade still finds it; the next save writes JSON and the JSON is read from then on.

No parameters.

Fnd_Pref_LoadLocalPrefs

Fnd_Pref_LoadLocalPrefs

Loads the preferences stored in the local external preference file into the preference arrays.

Called from Fnd_Pref_LoadPrefs, which handles the semaphore.

Reads the JSON file written by Fnd_Pref_SaveLocalPrefs. When there is none, reads the property list earlier versions wrote and repairs the doubled characters it holds, so an installation converts itself the first time it runs and nobody migrates anything by hand. The legacy file is left where it is; the next save writes JSON alongside it and the JSON wins from then on.

No parameters.

Fnd_Pref_LoadPrefs

Fnd_Pref_LoadPrefs

Reads the preferences file from the disk.

No parameters.

Fnd_Pref_LoadServerPrefs

Fnd_Pref_LoadServerPrefs

Loads the user's preferences from the database.

Does not load the shared preferences, since we need to get those when they're needed, since they may get changed by other users.

Called from Fnd_Pref_LoadPrefs, which handles the semaphore.

No parameters.

Fnd_Pref_Localize

Fnd_Pref_Localize

Passed the localization strings to the General and (if available) Localization components.

No parameters.

Fnd_Pref_Path

Fnd_Pref_Path --> Text

Returns the path to the preferences file (or at least where it should be).

The file is JSON and is named the same on every platform; the plist and .xml files earlier versions wrote are at Fnd_Pref_LegacyPath, which is read once and converted when this one is not there yet.

Fnd_Pref_Remove

Fnd_Pref_Remove (name{; scope}) --> Boolean

Deletes a preference. Returns True if there was one to delete.

The scope says where to delete from, which is not what it means on a getter - there it only says where to store a default. It is a constant or a label:

Fnd_Pref_Local, Fnd_Pref_Server : Storage.Fnd.Pref, and for a server preference the [Fnd_Pref] row that goes with it Fnd_Pref_Shared : the [Fnd_Pref] row owned by Fnd_Pref_SharedName a label : the [Fnd_Pref] row owned by that label

Local and Server name the same slot. The store holds one entry per name and the scope is a property of it, so a name cannot be local and server at once, and either constant removes whichever it is. Whether the row goes too is decided by the scope that was stored, not by the one asked for.

A local or server preference is gone from memory at once and out of the file at the next Fnd_Pref_SavePrefs. A shared or labelled one is gone from the data file immediately, as writing one is.

Fnd_Pref_SaveLocalPrefs

Fnd_Pref_SaveLocalPrefs

Writes the preferences file to disk, as JSON.

Called from Fnd_Pref_SavePrefs, which handles the semaphore.

The file is an object of preferences keyed by name, each holding the 4D type code it was stored under and its value in the JSON type that matches:

{ "format": 1, "preferences": { "Fnd_Nav: Open at Startup": { "type": 6,  "value": true }, "Fnd_Out: Columns":         { "type": 38, "value": { "width": 90 } }, "Fnd_Nav: Palette Window":  { "type": -1, "value": "10, 20, 310, 220" } } }

The type is recorded because JSON cannot tell a long integer from a real, and because a window - type -1 - has no JSON equivalent at all.

Only the local preferences are written. The server and shared ones live in [Fnd_Pref], and a labelled one never reaches the arrays.

No parameters.

Fnd_Pref_SavePrefs

Fnd_Pref_SavePrefs

Save's the user's local and server preferences.

No parameters.

Fnd_Pref_SaveServerPreference

Fnd_Pref_SaveServerPreference (owner; pref name; type; value; scope)

Saves a single preference value in the database.

A scope of Fnd_Pref_Local deletes the row instead, which is how a preference that is no longer a server or shared one is cleaned up.

Fnd_Pref_SaveServerPrefs

Fnd_Pref_SaveServerPrefs

Saves the user's server preferences to the data file.

Called from Fnd_Pref_SavePrefs, which handles the semaphore.

No parameters.

Fnd_Pref_SetBoolean

Fnd_Pref_SetBoolean (name; value{; scope})

Saves a Boolean value in the user's preferences file.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, which becomes the owner of a row in [Fnd_Pref] and so gives the caller a namespace of its own, written through at once.

Fnd_Pref_SetLongInt

Fnd_Pref_SetLongInt (name; value{; scope})

Saves a long integer value in the user's preferences file.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, which becomes the owner of a row in [Fnd_Pref] and so gives the caller a namespace of its own, written through at once.

Fnd_Pref_SetObject

Fnd_Pref_SetObject (name; value{; scope})

Saves a Object value in the user's preferences file.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, which becomes the owner of a row in [Fnd_Pref] and so gives the caller a namespace of its own, written through at once.

Fnd_Pref_SetReal

Fnd_Pref_SetReal (name; value{; scope})

Saves a real number value in the user's preferences file.

The scope is a constant - Fnd_Pref_Local, Fnd_Pref_Server, Fnd_Pref_Shared - or a label: any text, which becomes the owner of a row in [Fnd_Pref] and so gives the caller a namespace of its own, written through at once.

Fnd_Pref_SetText

Fnd_Pref_SetText (name; value{; scope})

Saves a text value in the user's preferences file.

The scope can be one of these: 0 = store locally (Fnd_Pref_Local) 1 = store privately on server (Fnd_Pref_Server) 2 = store shared on server (Fnd_Pref_Shared) or a label: any text, which becomes the owner of a row in [Fnd_Pref] and so gives the caller a namespace of its own, written through at once.

Fnd_Pref_SetValue

Fnd_Pref_SetValue (name; type; value; scope)

Adds a preference item to Storage.Fnd.Pref. Doesn't check the semaphore. We assume the calling process has done that, since this method is only called internally by other Fnd_Pref routines.

Assumes Fnd_Pref_Init has been called.

The scope is either one of the three constants or a label. A label is an owner name in [Fnd_Pref] chosen by the caller, written through at once and never held in the arrays, exactly as Fnd_Pref_Shared is.

Fnd_Pref_SetWindow

Fnd_Pref_SetWindow ({name{; window ref}}) Option 2: Fnd_Pref_SetWindow (name; left; top; right; bottom)

Saves the coordinates of the current window in the user's preferences file.

If no name is specified, the current process name is used.

If no window is specified, the frontmost window of the current process is used.

Fnd_Pref_UserName

Fnd_Pref_UserName ({name}) --> Text

Gets and sets the current user name for the preferences system.

Fnd_Pref_Utf8ToText

Fnd_Pref_Utf8ToText (text) --> Text

Undoes the byte-pair expansion the old preferences writer applied to every character above 127, so a value read from a legacy preferences file comes back as what was stored rather than doubled.

Two adjacent characters whose codes are a UTF-8 two-byte sequence become the one character they encode. Anything else is passed through, so text that was never doubled is returned unchanged and the method is safe to run over a whole file.

Characters above U+07FF cannot be recovered: the old writer had no room for them and produced a first "byte" above 255, which is not a sequence this can read. They are left as they are.

Fnd_Pref_XmlDecode

Fnd_Pref_XmlDecode (text) --> Text

Decodes reserved XML characters. For example, > is converted to >.

Unlike HTML encoding, this routine only handles reserved XML characters, since accented characters are handled by the UTF-8 encoding.

Call Fnd_Pref_XmlEncode to reverse the process.

Fnd_Pref_XmlEncode

Fnd_Pref_XmlEncode (text) --> Text

Encodes reserved XML characters. For example, > is converted to > Unlike HTML encoding, this routine only handles reserved XML characters, since accented characters are handled by the UTF-8 encoding.

Call Fnd_Pref_XmlDecode to reverse the process.

Nothing writes with this any more - the preferences file is JSON, which needs no escaping of its own. It is kept as the reference Fnd_Pref_XmlDecode is checked against, that one still being live in the legacy reader, and retires when the legacy reader does.

Fnd_Pref_XmlParse

Fnd_Pref_XmlParse (element)

Parses the XML reference into an array of element IDs and a 2D array of values.

Reads the legacy property list only. Nothing writes that format any more, so this is the conversion path and not a round trip.