The printable version is no longer supported and may have rendering errors. Please update your browser bookmarks and please use the default browser print function instead.

PreferenceLoader is an open-source^[1] MobileSubstrate based utility that allows developers to add entries to the Settings application, similar to the Settings bundles that AppStore apps use.

The approach PreferenceLoader takes is different from other approaches in that the Settings-iPhone.plist and Settings-iPod.plist files are not modified on disk. When the Settings application is loaded, entries are read from plists in /Library/PreferenceLoader/Preferences/ and are dynamically added to the list before the AppStore applications' preferences group.

PreferenceLoader also allows PreferenceBundles to be loaded from /Library/PreferenceBundles/^[2]^[3].

Entry file

	PreferenceLoader
	Error creating thumbnail: File missing
Cydia Package
Developer	Dustin Howett
Package ID	preferenceloader
Latest Version	2.2.0-1

Main article: Preferences specifier plist

Each entry is defined in its own plist. There are at least three ways to approach preferences support for your tweaks.

Reduced approach

Provides a switch on the root section of the preferences (like Airplane Mode). Recommended for configuration-less tweaks.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>entry</key>
	<dict>
		<key>cell</key>
		<string>PSSwitchCell</string>
		<key>defaults</key>
		<string>com.test.TestSettings</string>
		<key>label</key>
		<string>Test</string>
		<key>key</key>
		<string>enabled</string>
		<key>default</key>
		<true/>
		<key>icon</key>
		<string>TestIcon.png</string>
		<key>PostNotification</key>
		<string>com.test.TestSettings/preferences.changed</string>
	</dict>
</dict>
</plist>

This sets up an entry called Test with an icon loaded from TestIcon.png to the left and a UISwitch on the right, starting in the ON position, saving the value in [NSHomeDirectory() stringByAppendingFormat:@"/Library/Preferences/%s.plist", "com.test.TestSettings"] for the key enabled and posting a Darwin notification named com.test.TestSettings/preferences.changed.

Simple Approach

Provides a pane where other cells can appear (like Wi-Fi). Recommended for configuration-friendly tweaks. Here's an example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>entry</key>
	<dict>
		<key>cell</key>
		<string>PSLinkCell</string>
		<key>icon</key>
		<string>TestIcon.png</string>
		<key>label</key>
		<string>Test</string>
	</dict>
	<key>title</key>
	<string>Test Settings</string>
	<key>items</key>
	<array>
		<dict>
			<key>cell</key>
			<string>PSSwitchCell</string>
			<key>defaults</key>
			<string>com.test.TestSettings</string>
			<key>key</key>
			<string>enabled</string>
			<key>label</key>
			<string>Enabled</string>
			<key>default</key>
			<true/>
			<key>PostNotification</key>
			<string>com.test.TestSettings/preferences.changed</string>
		</dict>
	</array>
</dict>
</plist>

This sets up an entry called Test with an icon loaded from TestIcon.png to the left. The pushed page has the title set to Test Settings. The page will only contain a cell with the label Enabled UISwitch on the right, starting in the ON position, saving the value in [NSHomeDirectory() stringByAppendingFormat:@"/Library/Preferences/%s.plist", "com.test.TestSettings"] for the key enabled and posting a Darwin notification named com.test.TestSettings/preferences.changed.

For more preferences values you can add specifier dictionaries to the items array.

There is a good tutorial on how to create settings plists on MMi.

PreferenceBundle Approach

You can create custom settings pages that are able to execute code. This only requires a plist that loads a PreferenceBundle. Here's an example:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
	<key>entry</key>
	<dict>
		<key>cell</key>
		<string>PSLinkCell</string>
		<key>label</key>
		<string>Test</string>
		<key>icon</key>
		<string>TestIcon.png</string>
		<key>isController</key>
		<true/>
		<key>bundle</key>
		<string>TestSettings</string>
	</dict>
</dict>
</plist>

This sets up an entry called Test with an icon loaded from TestIcon.png to the left. The rest of the details are up to the bundle named TestSettings.

Filtering^[4]

In a way similar to that of MobileSubstrate, PreferenceLoader supports filters for entry plists and specifiers. The filter should be a dictionary for the key pl_filter which can contain these keys:

CoreFoundationVersion (array): The entry or specifier is loaded or displayed only if the version of CoreFoundation.framework is above the specified value or within the specified range. Currently, only the first 2 values are checked.

Firmware	CoreFoundation version
2.0	478.23
2.1	478.26.1
2.2	478.29
3.0	478.47.7
3.1	478.52
3.2	478.61
4.0	550.32
4.1	550.38.1
4.2	550.52
4.3	550.58.1
5.0	675.00
5.1	690.10
6.0	793.00
6.1	793.00
7.0	847.20
7.1	847.24
8.0	1140.10
8.1	1141.14
8.2	1142.16
8.3	1144.17
8.4	1145.15
9.0	1240.10
9.1	1241.11
9.2	1242.13
9.3	1280.38
10.0	1348.00
10.1	1348.00
10.2	1348.22
10.3	1349.56
11.0	1443.00
11.1	1445.32
11.2	1450.14
11.3	1452.23
11.4	1452.23
12.0	1556.00
12.1	1560.10
12.2	1570.15
12.3	1575.13
12.4	1575.17
12.5	1575.23
13.0	1665.15
13.1	1671.101
13.2	1673.126
13.3	1674.102
13.4	1675.129
13.5	1676.104
13.6	1677.104
13.7	1677.104
14.0	1751.108
14.1	1751.108
14.2	1770.106
14.3	1770.300
14.4	1774.101
14.5	1775.118
14.6	1776.103
14.7	1777.103
14.8	1778.101
15.0	1854
15.1	1855.105
15.2	1856.105
15.3	1856.105
15.4	1858.112

Below sample specifier will filter for iOS 6.0 or later.

To provide a range specify the lower bound first (checked as "greater or equal than") and the upper bound second (checked as "less than"). The filter below will filter for iOS 4.X.

NeXTSTEP style

XML style

{
	pl_filter = {
		CoreFoundationVersion = (
			"550.32",
			"675.00"
		);
	};
}

	<key>pl_filter</key>
	<dict>
		<key>CoreFoundationVersion</key>
		<array>
			<string>550.32</string>
			<string>675.00</string>
		</array>
	</dict>

Localization^[2]

Preferences.framework can localize strings in specifier properties, such as titles and labels.

Place your specifier plists and icons in a folder within /Library/PreferenceLoader/Preferences/. For each file.plist file and for each language you have translations for, create a file.strings.

See this paste for an example: https://ghostbin.com/paste/xcg38 (XML) • https://ghostbin.com/paste/cfhmb (NeXTSTEP)

Example code

https://github.com/Sassoty/theos-examples/tree/master/preferenceloader

References

↑ PreferenceLoader Source
↑ ^2.0 ^2.1 PreferenceLoader version 1.2 and later
↑ Bundles can also be loaded from /System/Library/PreferenceBundles/, but this is no longer the preferred method as of PreferenceLoader 1.2
↑ PreferenceLoader version 2.2.0-1 and later

External links

Settings how to

[1] PreferenceLoader Source

[1.2-2] 2.0 ^2.1 PreferenceLoader version 1.2 and later

[3] Bundles can also be loaded from /System/Library/PreferenceBundles/, but this is no longer the preferred method as of PreferenceLoader 1.2

[2.2.0-1-4] PreferenceLoader version 2.2.0-1 and later

[1]

[2]

[3]

[4]