- In Finder navigate to your Xcode project.
- Create a new folder called Settings.
- Inside the folder create a new file called Root.plist. See below for an empty Root.plist example.
- Rename the Settings folder to Settings.bundle. Finder will ask if you really want to do this. You do. Root.plist will “disappear” into the Settings.bundle file.
- In Xcode Command-click on Resources in your project. Select Add > Existing Files…
- Select Settings.bundle and click Add twice.
- You should now see the Settings.bundle file in Xcode and if you expand it Root.plist will appear again.
If you know of a less convoluted way to create this structure in Xcode, please let me know in the comments.
Empty Root.plist file:
<?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">
<!--
Root.plist
Preference settings for MyApp
-->
<plist version="1.0">
<dict>
</dict>
</plist>
Edit Root.plist
If you double click on Root.plist in Xcode the file will open in a standard text editor. A better alternative is to command-click Root.plist and select Open With Finder. That will open the Property List Editor.
- Expand the Root node and click the New Child button.
- Name the child Title, select the String class and enter the name of your application as the value.
- With the new Title node selected, click the New Sibling button.
- Name the new node PreferenceSpecifiers, and select the Array class. (You can’t enter a value for an Array.)
- With the PreferenceSpecifiers node selected, click the New Child button.
- Select the class Dictionary for the new node. (You can’t change the name of the node nor the value for a Dictionary entry.)
- Expand the new node and click on the New Child button.
- Name the new child Title, leave it as a String class, and give it a value that will have meaning to a user of your application.
- Click on the New Sibling button. Give the node these values: name = Type, class = String, value = PSTextFieldSpecifier. This will allow a user to enter a preference value in a text field.
- Click on the New Sibling button. Give the node these values: name = Key, class = String, value = something that has meaning in your code. This is the key your code will use to lookup this preference value.
- Click on the New Sibling button. Give the node these values: name = DefaultValue, class = String, value = a meaningful default. This value will be used unless the user has set the preference to something else.
- Save the Root.plist file.
If you expand all the nodes in the Property File Editor it should look something like this:
If you view the file in an Xcode text editor it will look like this:
<?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>PreferenceSpecifiers</key> <array> <dict> <key>DefaultValue</key> <string>2</string> <key>Key</key> <string>delayBeforeDialing</string> <key>Title</key> <string>Delay before dialing</string> <key>Type</key> <string>PSTextFieldSpecifier</string> </dict> </array> <key>Title</key> <string>DTMF Dialer</string> </dict> </plist>
Build and run your app. Exit your app and tap the Settings app. You should now see a new entry that matches the name of your app. Tap this entry and your own custom preferences will show up. The user can edit and save these preferences without you having to write any code. Pretty neat.
Multi Value Specifier Preference
If the user should select between multiple pre-defined values you can use a PSMultiValueSpecifier. Enter the visible titles as an Array under the name Titles, and the values your code sees as an Array under the name Values.
Something like this:
Other Types of Preference Values
- PSToggleSwitchSpecifier – for boolean values
- PSSliderSpecifier – for a range of values
July 4th, 2008 at 12:09
What I can’t find out how to do (from the Apple documentation) is what the Mail preferences do i.e. add a new account. I presume this is allowing the user to add a new child node to the preferences bundle but I can’t see how.
In my application I would like the user to be able to add new sections to a routine (add new section would be equivalent of add new mail account) but I can’t see how to do it. The alternative it to write all my own settings screens.
Any ideas?
Roger
July 10th, 2008 at 12:34
Roger,
I don’t know of a way to do this without writing your own settings screen. The Root.plist file is inside the app bundle, and it’s bad form to update that file after the app has been deployed. And as far as I know there is no way to tell the Settings app about any custom property list files.
Nick
August 6th, 2008 at 11:53
Small error, it is actually PSToggleSwitchSpecifier for boolean values
August 6th, 2008 at 15:25
Thanks! I’ve updated the post.
Nick
August 13th, 2008 at 10:13
Thanks Nick, this tutorial works great.
I was looking at the documentation and i couldnt find the answer to this anywhere ….
Is there any way to make the text field password protected?
, Jesse
August 13th, 2008 at 10:34
hey,
you should also add in some code showing how to access the PSTextFieldSpecifier text value from with in the code.
August 14th, 2008 at 15:19
Jesse,
Yes, you can make the text field “secure” for entry of passwords. Use the same Type of PSTextFieldSpecifier and then add IsSecure as another key with the value true.
Search for PSTextFieldSpecifier in Xcode documentation for more information.
Nick
August 20th, 2008 at 12:38
It would be nice if somebody could post a line of code to show how you actually read these settings in your app. Anyone..?
August 22nd, 2008 at 15:33
Jesse and Jason,
See this post: How To Access Preferences From Your iPhone App
Nick
September 2nd, 2008 at 14:05
how do u set the prefernce file to have an image (in settings.app)
September 6th, 2008 at 14:29
My application shows its preferences in the SDK settings menu. But, after i use installer to install my app, the settings do not appear.
Could you help me on that?
September 24th, 2008 at 06:59
Hi, thanks for the tutorial. I’m wondering why Apple’s AppPrefs example is more complicated? In the app delegate they manually set all the defaults because their request from NSUserDefaults apparently fails on their first request. I.e. they do:
NSString *testValue = [[NSUserDefaults standardUserDefaults] stringForKey:kFirstNameKey];
if (testValue == nil)
{
// no default values have been set, create them here based on what’s in our Settings bundle info
//
…..
}
October 23rd, 2008 at 00:42
Hi, thanks for the nice tutorial. What if we would like to internationalize the preferences?
I have tried to move the Settings.bundle under the directory en.lproj/ but the preferences don’t appear anymore under the native Settings.
Could anyone give me a hint on how to internationalize the process described in this tutorial?
Thanks.
October 23rd, 2008 at 08:06
Actually I have got it solved: you need to create sub-directories under Settings.bundle named according to the internationalization (e.g. for English en.lproj/ ) and place in each of those directories the localized version of Root.plist
Thanks.
October 23rd, 2008 at 23:32
Hi again,
what would it be the setting item to be defined for having a read-only setting?
November 7th, 2008 at 01:26
Hi, Anyone able to make it work on the device??
February 16th, 2009 at 06:45
“what would it be the setting item to be defined for having a read-only setting?”
If its read-only, why not just hard code it in a constant?
March 9th, 2009 at 05:28
How To Create An iPhone Preferences File…
You’ve been kicked (a good thing) – Trackback from iPhoneKicks.com – iPhone SDK links, community driven…
March 27th, 2009 at 09:29
So has anyone got this to work on a device? It works fine in the simulator but when I install it, I don’t see the settings for my app.
March 27th, 2009 at 10:29
Oh and also, a less convoluted way — Select “New File” from the “File” menu, under the iPhone OS, select the “Settings Bundle” icon. When you expand the bundle you should see a Root.plist ready to personalize.
May 20th, 2009 at 07:20
I got here by googling “iphone application settings adding array” because I wanted to have an array of items in settings, like Roger Hyam above, where the user could add or remove nodes from it.
I see from the response this isn’t possible, but in my case this is probably better left put in the app itself anyway. I wanted to add a list of automated equipment that can be queried by IP address. Users rarely get new equipment – most own only one – but IP addresses change frequently enough that this probably belongs in the app itself. Stuff presented in the settings app is supposed to be set it and forget it.
I will have to add a tab bar with only two choices to my app to accommodate but I may need it for a future feature choice later anyhow.
May 29th, 2009 at 10:09
where is Finder on my iphone? My iphone calendar has a background color that makes it difficult to read. it is a bright teal with white lettering. I didn’t change it but somehow it is this color. can anyone help? how do i change it? I use Microsoft Outlook on my desktop and it downloads to my iphone. thanks
June 3rd, 2009 at 07:05
@Donna: There is no Finder on the iPhone. And there is no way to change the background colors of the calender.
August 3rd, 2009 at 09:39
An easier way? Using Xcode 3.1.3, I do the following to create Settings.bundle:
File
New File
[iPhone OS / Resource]
Settings Bundle
Next
Finish
Settings.bundle is added to the project – it looks like a little white Lego block. A sample Root.plist is also built with a few controls, and a string localization file. I deleted the “Item(s)” I didn’t need, copied the ones I needed more of and edited from there (making sure to rename the keys).
August 3rd, 2009 at 16:13
Isn’t it a little easier to just do File –> New File –> iPhone OS Resource –> Settings Bundle?
This gives you a nice base of examples to work off of too if you are a beginner.
>> Gabe Said: how do u set the preference file to have an image (in settings.app)
If you mean the icon, just get a 29×29 image into your app bundle…
call it ‘Icon-Settings.png’ and you should be golden…
if you want to put a pic on the settings page tho I don’t think it can be done…
October 23rd, 2009 at 04:00
In the iPhone settings I would want to set an area to display large text for copyright notice. Which control do I need to use? I tried using PSTextFieldSpecifier but the entire string seems to appear on a single line rather than taking the entire screen space.
Any help would be appreciated
October 23rd, 2009 at 19:14
@Raghu: The Title in PSGroupSpecifier can span multiple lines.
October 24th, 2009 at 10:02
I wanted the answer to Raghu’s question as well:
I wanted to add a lega link similar to iphone’s about box:
settings->general settings->About->Legal
I want to display the entire page rather than a single line. I have not been able to do so.
October 24th, 2009 at 10:06
@Nick
The title in PSGroupSecifier does span over multiple lines but it is does not have a white background, but is grayed out. I wanted a white background.
April 3rd, 2010 at 23:05
Can I get the setting.app to input a proxy.pac file? I am creating an iPhone app for my college and we use certain proxy settings. I would really like to have those setting put in when you run the app. Just trying to figure out a way if it is at all possible…
May 3rd, 2010 at 04:17
“If its read-only, why not just hard code it in a constant?”
Sometimes it useful to show the setting (because it will be in the settings bundle) BUT the UI supplied by the settings app might not make it possible to change that setting – i.e. for which playlist to use for playing music.
July 12th, 2010 at 21:36
Thanks a lot. Do you know how to create Localized for Preferences File.
For example, the Title is ‘DTMF Dialer’ in English, I would like to create a Chinese localized content for it with ‘DTMF 拨号’. So it display ‘DTMF 拨号’ in Settings UI when the iPhone’s Language is setted to Chinese.
January 8th, 2012 at 22:38
that is what i looking for because when i try to edit it and adding any field other then text type my x-code get crashed
February 2nd, 2012 at 03:45
Hi, Thanks for briefing on this & an excellent post .
Now, using the same plist file concept I would like write the JSON String i.e Array & dictionary within it, is possible.The problem with it this the JSON Structure which is somewhat like this :
>ARRAY
>Dictionary
>Key value pair
>Key value pair having ARRAY
>Dictionary
>Key value pair
>Key value pair having ARRAY
.
.
.
How can I add this to my plist file ?Though I am able to add just a single array with Single Dictionary within it.