prefs

Last updated 6 months ago

Provides access to application preferences, typically stored via NSUserDefaults or CFProperties. To access the preferences, simply pass in the Bundle ID (eg. "com.apple.Preview") and it will return a table whose keys can be accessed or updated, or iterated via ipairs.

For example:

local previewPrefs = require("cp.app.prefs").new("com.apple.Preview")
previewPrefs.MyCustomPreference = "Hello world"
print(previewPrefs.MyCustomPreference) --> "Hello world"
for k,v in pairs(previewPrefs) do
print(k .. " = " .. tostring(v))
end

API Overview

  • Functions - API calls offered directly by the extension

  • Constructors - API calls which return an object, typically one that offers API methods

API Documentation

Functions

bundleID

Signature

cp.app.prefs.bundleID(prefs) -> string

Type

Function

Description

Retrieves the bundleID associated with the cp.app.prefs instance.

Parameters

prefs - the prefs object to query

Returns

The Bundle ID string, or nil if it's not a cp.app.prefs.

get

Signature

cp.app.prefs.get(prefs, key[, defaultValue]) -> value

Type

Function

Description

Retrieves the specifed key from the provided prefs.

Parameters

prefs - The prefs instance. * key - The key to retrieve. * defaultValue - The value to return if none is currently set.

Returns

The current value, or defaultValue if not set.

is

Signature

cp.app.prefs.is(thing) -> boolean

Type

Function

Description

Checks if the thing is a cp.app.prefs instance.

Parameters

thing - The value to check

Returns

true if if's a prefs, otherwise false.

prop

Signature

cp.app.prefs.prop(prefs, key[, defaultValue]) -> cp.prop

Type

Function

Description

Retrieves the cp.prop for the specified key. It can be watched for changes.

Parameters

prefs - The prefs instance. * key - The key to get/set. * defaultValue - The value if no default values is currently set.

Returns

The cp.prop for the key.

set

Signature

cp.app.prefs.set(prefs, key, value) -> none

Type

Function

Description

Sets the key/value for the specified prefs instance.

Parameters

prefs - The prefs instance. * key - The key to set. * value - the new value.

Returns

Nothing.

watch

Signature

cp.app.prefs.watch(prefs, watchFn) -> nil

Type

Function

Description

Adds a watch function which will be notified when the preferences change.

Parameters

prefs - The prefs instance to watch. * watchFn - The function that will get called.

Returns

Nothing

Constructors

new

Signature

cp.app.prefs.new(bundleID) -> cp.app.prefs

Type

Constructor

Description

Creates a new cp.app.prefs instance, pointing at the specified bundleID.

Parameters

bundleID The Bundle ID to access preferences for.

Returns

A new cp.app.prefs with read/write access to the application's preferences.