PreferenceLoader

From iPhone Development Wiki
Revision as of 22:52, 13 November 2009 by Volatile-dev (talk | contribs) (Created page with 'PreferenceLoader is a MobileSubstrate based utility that allows developers to add entries to the Settings app, similar to the SettingsBundles that app store apps use. The approa…')
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
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 a MobileSubstrate based utility that allows developers to add entries to the Settings app, similar to the SettingsBundles that app store 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 PreferenceBundle 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