Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A convenience wrapper to allow RubyMotion apps easy access to reading, writing, and persisting values via NSUserDefaults.
Pull request Compare This branch is even with AaronH:master.
Fetching latest commit...
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


An extension to allow RubyMotion apps easy access to reading, writing, and persisting user settings and other objects on iOS via NSUserDefaults.


Copy the rmsettable.rb and rmsettings.rb into your /app directory. As there isn't yet a convention for where to put these sorts of files, I'd recommend adding a /app/lib/rm_settings directory.



Given the way RubyMotion compiles files, you will probably need to add the RMSettings files to your Rakefile files_dependencies options.

Motion::Project::App.setup do |app|
  app.files_dependencies  'app/app_delegate.rb' => 'app/lib/rm_settings/rmsettable.rb',
                          'app/lib/rm_settings/rmsettable.rb' => 'app/lib/rm_settings/rmsettings.rb'




To begin, include RMSettable inside the AppDelegate class of /app/app_delegate.rb and call the rm_settable function with your other didFinishLaunchingWithOptions code.

class AppDelegate
  include RMSettable

  def application(application, didFinishLaunchingWithOptions:launchOptions)
    rm_settable :name, :background_color


In its simplest form, the rm_settable function is called with a list of symbols for the settings your app will save to the NSUserDefaults.

  rm_settable :name, :background_color

By default, the settings are stored as objects. If you wish to cast as a specific type, you may declare that as a hash on the key.

  rm_settable :name, age: {type: :integer}, completed_tutorial: {type: :boolean}

The types available derive from the NSUserDefault class. They can be :array, :boolean, :data, :dictionary, :double, :float, :integer, :object, :string_array, :string, or :url.


Additionally, you can include a hash of options to affect the way RMSettings works.

  rm_settable age:, name: {type: :string}, options: {autosave: false, default_type: :integer}
  rm_settable options: {lenient_keys: true}

Available Options

  • autosave (true)

    By default, settings are synchronized to the device as soon as it is updated. However, if you are updating a lot of items at once or would prefer to manually call save on the settings object, set this to false. Be aware that iOS will still save the settings periodically without being explicitly called.

    Regardless of this setting, settings will also be saved when applicationDidEnterBackground or applicationWillTerminate is called on the app. To prevent this behaviour, you must override these methods in your app_delegate.rb.

  • default_type (:object)

    Items are saved as objects. You many also specify a particular type when you declare the setting names. With this setting you may override the default type for all settings.

  • lenient_keys (false)

    If you don't want to declare any or all of the settings you will be storing, set this to true. Any setting not explicitly declared will still be stored and retrieved as the default setting type.

Reading and Writing User Settings

A method named settings is added to the application's delegate and supplies a simple interface to the user settings.

  # write a setting         = 'Karl Pilkington'
  UIApplication.sharedApplication.delegate.settings[:head_shape] = 'Orange'

  # read a setting
  @name       =
  @head_shape = UIApplication.sharedApplication.delegate.settings[:head_shape]

  # check a setting's boolean value or blankness

  # reset a setting to its default (also aliased as 'reset' or 'remove')
  UIApplication.sharedApplication.delegate.settings.delete :name


Convenience subclasses are provided for UIViewController and UIView called RMViewController and RMView. If you derive your views and controllers form these classes you will have even easier access to the application's settings.

class MyCoolView < RMView

  def headClassifier
    if !settings.head_shape? and settings.username =~ /karl\spilkington/i
      settings.head_shape = 'Orange'

To Do

  • Add tests
  • Add error reporting
  • Check that passed data types are valid
  • Add support for setting default value at declaration
Something went wrong with that request. Please try again.