|
Note
This is intended for native application developers to integrate the preferences of their application in Preferences.app. If you find any other use. like adding preferences from an existing native app, go crazy and do what you will.
Note 2
As this may seem complicated at first, I will attach a copy of my SummerBoard.plist so that you can follow along.
Note 3
If this is to difficult to follow, just provide me with the plist that contains the options of your application located in /private/var/root/Library/Preferences/ and I will make one for you.
Preparation
Make sure your app reads the values you want it to read from /private/var/root/Library/Preferences/com.(companyname).(appname) or this will not work.
Examining an existing menu
Here are things you are going to need to know, bit by bit. I will use the SummerBoard.plist from my CFW as an example:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>id</key>
<string>com.apple.preferences.touch</string>
<key>items</key>
<array>
This is how all preference .plist's must start. I don't think that the com.apple.preferences.touch is needed but I leave it there to remind me to specify a plist to write the options to which I will disscuss later
<dict>
<key>cell</key>
<string>PSGroupCell</string>
</dict>
<dict>
<key>cell</key>
<string>PSLinkListCell</string>
<key>defaults</key>
<string>com.apptapp.SummerBoard</string>
<key>detail</key>
<string>PSListItemsController</string>
<key>key</key>
<string>themeName</string>
<key>label</key>
<string>Theme</string>
<key>validTitles</key>
<array>
<string>Default</string>
<string>Leopard</string>
<string>Panther</string>
<string>SummerBoard</string>
</array>
<key>validValues</key>
<array>
<string>Default</string>
<string>Leopard</string>
<string>Panther</string>
<string>SummerBoard</string>
</array>
</dict>
This one here is a bit more intricate, so I'll break it down. PSLinkListCell means that it has a seperate page of something that will be defined later. defaults defines a plist in /private/var/root/Library/Preferences/ that these options are to be read/written from, minus the .plist extension. detail and the corresponding value are required to make it a functioning PSLinkListCell. key is the key that this option is going to be modifying. Go ahead and look in com.apptapp.SummerBoard.plist on your iPhone and you will see the key "themeName" among others. label is the label that it is given. validTitles are the titles assigned to the values that you can use, in this case themes. This usually should be the names of the values to avoid confusion, unless your values are long and you are making an application designed for noobs. validValues are the pre-defined values that you can select and will be read by the application accordingly. Wow, that was a long one.
Say you don't want to add to the .plist every time you install a new SummerBoard theme. If you are careful and make sure NOT to make a typo, you could do this:
<dict>
<key>cell</key>
<string>PSEditTextCell</string>
<key>detail</key>
<string>PSDetailController</string>
<key>defaults</key>
<string>com.apptapp.SummerBoard</string>
<key>key</key>
<string>themeName</string>
<key>label</key>
<string>Theme Value</string>
<key>placeholder</key>
<string>Enter Theme Value</string>
</dict>
Instead, evident from it being called PSEditTextCell, would make a keyboard appear and allow you to type in the name of a custom theme you have installed. If you actually decide to use this on your iPhone, make sure you do not misspell the theme value or Springboard won't be able to boot.
Okay, now let's go on with the rest of the plist:
<dict>
<key>cell</key>
<string>PSSwitchCell</string>
<key>default</key>
<real>1</real>
<key>defaults</key>
<string>com.apptapp.SummerBoard</string>
<key>key</key>
<string>skipLastRow</string>
<key>label</key>
<string>Skip Last Row</string>
</dict>
This is the most simple one you could make, and I suggest it as a starting point. It simply has a toggle on/off switch for anything that has the values <true/>/<false/>, <integer>1</integer>/<integer>0</integer>, etc. PSSwitchCell is the part that makes it toggle on and off, and default is what it's default value should be. The rest were described previously.
I have more than that in my plist, but there's nothing new, so let's go on to the end...
<dict>
<key>cell</key>
<string>PSGroupCell</string>
<key>isStaticText</key>
<true/>
</dict>
<dict>
<key>cell</key>
<string>PSTitleValueCell</string>
<key>label</key>
<string>Beta Build</string>
</dict>
This is not required, but it is what you see at the bottom of some preference menus. If you have SummerBoard, go to SMBPrefs.app and look at the bottom. It should say something like "SMBPrefs 3.0" Well this is what I've posted above defines, except it would say "Beta Build" instead.
Now, for the last part of the plist...
</array>
<key>title</key>
<string>Summerboard</string>
</dict>
</plist>
This is how all plists must end. One thing you must change is title, which would be the name of your plist.
Preparing your plist
After you have added all of the options you wanted to (If you are still confused don't worry I will go over more values later), then follow these steps to get the menus into Preferences.app
1. Name your plist. For the sake of the tutorial, I'll say mine is SummerBoard.plist
2. Wherever you want to put your plist, add the following snippet of code to the menu:
<dict>
<key>cell</key>
<string>PSLinkCell</string>
<key>label</key>
<string>SummerBoard</string>
</dict>
Replace "SummerBoard" with the name of your plist. Make sure it is the same exact name as your plist is or this will not work. For the sake of this tutorial add it to General.plist at the bottom and see if it and your options appear (when you tap it). If so, you are good to go, and can proceed.
Add an icon to your menu
Do you want to have an icon beside the name of your menu like the "Phone" and "Mail" menus do? It's very simple. Just modify the part you added your menu to in General.plist (or whatever else you used) to this:
<dict>
<key>cell</key>
<string>PSLinkCell</string>
<key>label</key>
<string>SummerBoard</string>
<key>icon</key>
<string>SummerBoard.png</string>
</dict>
Again, where label you would replace SummerBoard with the name of your plist, and same with the value for icon, but make sure to leave the .png. With icon it doesn't have to be the name of your plist to work though, it just has to be the name of the .png file you put in the Preferences.app directory of which you plan to use.
Cell Types:
PSSwitchCell - As discussed above, it is just an on/off switch
PSSliderCell - For use with anything that has a numerical value if you so choose. This is very easy to understand how to use, just take a look at Brightness.plist and you'll get it immediately.
PSEditTextCell - Makes a keyboard come up and allows you to imput the value
PSSecureEditTextCell - Same as PSEditTextCell, but makes all the letters you type show up as asterisks.
PSTitleValueCell - Haven't played with this too much. I just use it to add text to the complete bottom and have it centered. It can probably to more though
I will post a part two with more cell types and variables to use for even further customization, but for now anyone with IDA Pro can give it a looksee by decrypting the Preferences application
Good Luck!
PS: If you want to have a phone keypad instead of a full blown keyboard for PSEditTextCell, then just add this to your option:
<key>keyboard</key>
<string>phone</string>
|
12-23-2007, 11:20 AM
Should Wiki as well, it seems I should create a new section in the Wiki menu for Developers Guides.
Linear Mode
