Mar 24
  1. In Finder navigate to your Xcode project.
  2. Create a new folder called Settings.
  3. Inside the folder create a new file called Root.plist. See below for an empty Root.plist example.
  4. 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.
  5. In Xcode Command-click on Resources in your project. Select Add > Existing Files…
  6. Select Settings.bundle and click Add twice.
  7. 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.

  1. Expand the Root node and click the New Child button.
  2. Name the child Title, select the String class and enter the name of your application as the value.
  3. With the new Title node selected, click the New Sibling button.
  4. Name the new node PreferenceSpecifiers, and select the Array class. (You can’t enter a value for an Array.)
  5. With the PreferenceSpecifiers node selected, click the New Child button.
  6. Select the class Dictionary for the new node. (You can’t change the name of the node nor the value for a Dictionary entry.)
  7. Expand the new node and click on the New Child button.
  8. 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.
  9. 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.
  10. 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.
  11. 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.
  12. Save the Root.plist file.

If you expand all the nodes in the Property File Editor it should look something like this:

Root.plist

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.

Custom Settings

 

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:

MultiValueSpecifier

 

Other Types of Preference Values

  • PSToggleSwitchSpecifier – for boolean values
  • PSSliderSpecifier – for a range of values

written by Nick \\ tags: , , , , , , ,

34 Responses to “How To Create An iPhone Preferences File”

  1. Roger Hyam Says:

    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

  2. Nick Dalton Says:

    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

  3. Malcolm Hall Says:

    Small error, it is actually PSToggleSwitchSpecifier for boolean values

  4. Nick Dalton Says:

    Thanks! I’ve updated the post.

    Nick

  5. Jesse Couch Says:

    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

  6. Jesse Couch Says:

    hey,

    you should also add in some code showing how to access the PSTextFieldSpecifier text value from with in the code.

  7. Nick Dalton Says:

    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

  8. Jason Says:

    It would be nice if somebody could post a line of code to show how you actually read these settings in your app. Anyone..?

  9. Nick Dalton Says:

    Jesse and Jason,

    See this post: How To Access Preferences From Your iPhone App

    Nick

  10. Gabe Jacobs Says:

    how do u set the prefernce file to have an image (in settings.app)

  11. Filipe Guerra Says:

    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?

  12. Marc Says:

    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
    //
    …..
    }

  13. Diego Says:

    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.

  14. Diego Says:

    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.

  15. Diego Says:

    Hi again,

    what would it be the setting item to be defined for having a read-only setting?

  16. Raj Says:

    Hi, Anyone able to make it work on the device??

  17. rey Says:

    “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?

  18. iPhoneKicks.com Says:

    How To Create An iPhone Preferences File…

    You’ve been kicked (a good thing) – Trackback from iPhoneKicks.com – iPhone SDK links, community driven…

  19. Suzanna Says:

    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.

  20. Suzanna Says:

    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.

  21. EmIce Says:

    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.

  22. Donna Says:

    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

  23. Nick Says:

    @Donna: There is no Finder on the iPhone. And there is no way to change the background colors of the calender.

  24. inked Says:

    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).

  25. JR Says:

    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…

  26. Raghu Says:

    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

  27. Nick Says:

    @Raghu: The Title in PSGroupSpecifier can span multiple lines.

  28. Devanshu Says:

    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.

  29. Devanshu Says:

    @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.

  30. Joe Says:

    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…

  31. MooCow Says:

    “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.

  32. Airfly Pan Says:

    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.

  33. Aalok Says:

    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

  34. Ajay Says:

    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.

Leave a Reply