Class | Preferences |
In: |
lib/preferences.rb
|
Parent: | Object |
The Preferences class is an easy way to make variables in an application persist in a file. See intro.txt for a general introduction.
filename | [RW] | Name of file in which preferences persist. Can be assigned a new value while application is open, in order to define a new location at which preferences are stored when save is called. |
Utility method for guessing a suitable directory to store preferences. On win32, tries APPDATA, USERPROFILE, and HOME. On other platforms, tries HOME and ~. Raises EnvError if preferences dir cannot be chosen. Not called by any of the Preferences library code, but available to the client code for constructing an argument to Preferences.new.
Create a Preferences instance which persists at filename. All directories containing filename will be created if they do not already exist.
If an object with preferences vars ceases to exist before prefs are saved with save, the app should dump the object’s pref vars using this method. Does not save prefs to disk, but only stores them so they can be saved later after the object has been collected. (Note that the preferences system keeps only a weak reference to each registered object, so they may be garbage collected if no other references exist. A good place to call this method is, for example, in the show/hide methods (or the SEL_MAP/ SEL_UNMAP handlers for FXWindow objects in Fox. See examples/life-cycle.rb)
A simplified interface that combines register_pref_key and register_pref_var in to one method call with a nice block.
Simply call the var method inside the block instead of calling register_pref_key.
For example:
PREFS.register "my app/window" do |entry| entry.var "x", "y" => "default_y" entry.var "z" end
This is recommended over using register_pref_key and register_pref_var directly.
The object whose preferences are regsitered is the self object in the current context. If you need to register prefs for an object that is not currently self, pass the object as a second argument to register:
subwindow = SubWindow.new(self) PREFS.register "my app/window/subwindow", subwindow do |entry| entry.var :x, :y end
It perfectly safe to call register more than once with the same key.
Register use of key for obj. The prefs of obj will be stored under this key. An object can have only one key, but it may be complex, like "foo/bar" or, equivalently, ["foo", "bar"]. Two objects can share a key. Any object, even a class or a module, can be registered. A suggested convention is to use strings for the key, so that there is no conflict with the symbols used for var names. (This is optional.)
Register the vars, which by convention are represented as symbols, as part of the persistent preferences for obj. Default values may be provided using hash syntax:
register_pref_var obj :v1, :v2, :v3 => default_for_v3
This method is typically called in an initialize method, after register_pref_key. At the time of registration (that is, when this method is called), the variable is updated from the persistent preferences, if the preferences specify a value for it. Otherwise, the default, if any, is applied. If the default is a Proc or Method, it is called to produce the default value. (This is useful if getting the default is an expensive operation.)
Should be called by the app when quitting or otherwise requested by the user to save preferences. If a registered object has been GC-ed, uses the last known values for the object (see dump_prefs_for).
If state is true, obj will be used by save as a source of data. Otherwise, the previous data will be used. Initially, the state is true. If a block is given, the state change is in force only during the block. This can be helpful when one knows that an object will lose access to the pref vars (e.g. a window is unmapped, so x and y become unreliable).