PreferenceLoader

From iPhone Development Wiki
Revision as of 07:29, 15 November 2009 by KennyTM~ (talk | contribs) (wikify.)
Jump to: navigation, search
PreferenceLoader
PrefLoaderScreenshot.png
Cydia Package
Developer Thomas Moore (volatile-dev)
Package ID preferenceloader
Latest Version 1.1


PreferenceLoader is a MobileSubstrate based utility that allows developers to add entries to the Settings app, similar to the Settings bundles that AppStore apps use.

The approach PreferenceLoader takes is different that other approaches in that the Settings plist files are not modified on disk. Entries are dynamically added to the list when the Settings app is loaded. PreferenceLoader gives the developer two options for entries. The first option is to simply create a single plist with basic options like PSSwitchCell or PSEditTextCell. The second option is allows the developer to create a full-blown PreferencesBundle.

Regardless of the approach taken, each new entry is specified in its own plist located at /Library/PreferenceLoader/Preferences/. The plist must contain a dictionary containing a dictionary element named entry, as shown TestSettngs.plist:

    <?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>
    </dict>
    </plist>

In this example, a new entry with the label "Test" is created that links to the settings page defined in Test.plist using the icon TestIcon.png. Both of these files should be placed in the Preferences directory with TestSettings.plist. One interesting thing that can be done is to combine the entry plist with the settings plist. This works because the settings plist has elements named items and title, so adding an entry element does not break anything. Here's an example of Test.plist that is combined:

    <?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>items</key>
          <array>
                 <dict>
                      <key>cell</key>
                      <string>PSSwitchCell</string>
                      <key>default</key>
                      <true/>
                      <key>defaults</key>
                      <string>com.test.TestSettings</string>
                      <key>key</key>
                      <string>testKey</string>
                      <key>label</key>
                      <string>Test Setting</string>
                </dict>
          </array>
          <key>title</key>
          <string>Test</string>
    </dict>
    </plist>

There is a good tutorial on how to create these settings plists on MMi at http://modmyi.com/forums/file-mods/22453-how-make-custom-menus-preferences-app-custom-preferences.html.

PreferenceBundles

For those of you that want to create more complex settings pages, then the PreferenceBundles is for you. With this technique, you can actually create custom pages that are able to execute code. Skylar Cantu has put together a very useful guide on PreferenceBundles at http://www.touchrepo.com/guides/preferencebundles/PreferenceBundles.doc

The only difference to his guide that is to be noted is that like the simple approach given above, the developer should create a plist in /Library/PreferenceLoader/Preferences/. Here's an example of an updated TestSettings.plist:

    <?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>bundle</key>
                <string>TestSettings</string>
                <key>cell</key>
                <string>PSLinkCell</string>
                <key>icon</key>
                <string>TestIcon.png</string>
                <key>isController</key>
                <true/>
                <key>label</key>
                <string>Test</string>
          </dict>
    </dict>
    </plist>

The difference here is that instead of loading Test.plist, this entry will load the TestSettings.bundle located at /System/Library/PreferenceBundles/. Unlike the simple method, all of the files except TestSettings.plist are located inside the bundle. A skeleton PreferenceBundle project can be found at http://www.volatile-dev.com/PreferenceLoader/TestSettings.zip