▼Framework:   Racket GUI Application Framework
On this page:
preferences:  get
preferences:  set
preferences:  get/  set
preferences:  add-callback
preferences:  set-default
preferences:  default-set?
preferences:  set-un/  marshall
preferences:  restore-defaults
preferences:  register-save-callback
preferences:  unregister-save-callback
exn:  make-unknown-preference
exn:  unknown-preference?
exn:  struct:  unknown-preference
preferences:  low-level-put-preferences
preferences:  low-level-get-preference
preferences:  snapshot?
preferences:  restore-prefs-snapshot
preferences:  get-prefs-snapshot
preferences:  new-layer
preferences:  layer?
preferences:  current-layer
  top  ← prev  up  next → 

28 Preferences, Textual

 (require framework/preferences) package: gui-lib

procedure

(preferences:get sym) → any/c

  sym : symbol?
Returns the value for the preference sym.

Raises an exception matching exn:unknown-preference? if the preference’s default has not been set.

Use preference:set-default to set the default value of the preference before calling this function.

procedure

(preferences:set sym val) → void?

  sym : symbol?
  val : any/c
Sets the preference sym to val. It should be called when the user requests a change to a preference; preferences:set immediately writes the preference value to disk.

It raises an exception matching exn:unknown-preference? if the preference’s default has not been set.

Use preference:set-default to set the default value of the preference before calling this function.

procedure

(preferences:get/set pref)

 → (case-> (-> any/c) (-> any/c void?))
  pref : symbol?
Returns a procedure that when applied to zero arguments retrieves the current value of the preference named pref and when applied to one argument updates the preference named pref.

Added in version 1.18 of package gui-lib.

procedure

(preferences:add-callback p f [weak?]) → (-> void?)

  p : symbol?
  f : (-> symbol? any/c any)
  weak? : boolean? = #f
This function adds a callback which is called with a symbol naming a preference and its value, when the preference changes. preferences:add-callback returns a thunk, which when invoked, removes the callback from this preference.

If weak? is true, the preferences system will only hold on to the callback weakly.

The callbacks will be called in the order in which they were added.

If you are adding a callback for a preference that requires marshalling and unmarshalling, you must set the marshalling and unmarshalling functions by calling preferences:set-un/marshall before adding a callback.

The result thunk removes the callback from the same preferences layer that p was in when preferences:add-callback was originally called.

This function raises an exception matching exn:unknown-preference? if the preference default has not been set via preferences:set-default.

procedure

(preferences:set-default symbol 
  value 
  test 
  [#:aliases aliases 
  #:rewrite-aliases rewrite-aliases]) 
 → void?
  symbol : symbol?
  value : any/c
  test : (any/c . -> . any)
  aliases : (listof symbol?) = '()
  rewrite-aliases : (listof (-> any/c any))
   = (map (lambda (x) values) aliases)
This function must be called every time your application starts up, before any call to preferences:get or preferences:set (for any given preference).

If you use preferences:set-un/marshall, you must call this function before calling it.

This sets the default value of the preference symbol to value. If the user has chosen a different setting, (reflected via a call to preferences:set, possibly in a different run of your program), the user’s setting will take precedence over the default value.

The test argument is used as a safeguard. That function is called to determine if a preference read in from a file is a valid preference. If test returns #t, then the preference is treated as valid. If test returns #f then the default is used.

The aliases and rewrite-aliases arguments aids in renaming preferences. If aliases is present, it is expected to be a list of symbols that correspond to old versions of the preferences. It defaults to '(). If rewrite-aliases is present, it is used to adjust the old values of the preferences when they are present in the saved file.

Changed in version 1.23 of package gui-lib: Allow preferences:set-default to be called even after a snapshot has been grabbed.

procedure

(preferences:default-set? pref) → boolean?

  pref : symbol?
Returns #t if pref has been passed to preferences:set-default, #f otherwise

procedure

(preferences:set-un/marshall symbol    
  marshall    
  unmarshall) → void?
  symbol : symbol?
  marshall : (any/c . -> . printable/c)
  unmarshall : (printable/c . -> . any/c)
preferences:set-un/marshall is used to specify marshalling and unmarshalling functions for the preference symbol. marshall will be called when the users saves their preferences to turn the preference value for symbol into a printable value. unmarshall will be called when the user’s preferences are read from the file to transform the printable value into its internal representation. If preferences:set-un/marshall is never called for a particular preference, the values of that preference are assumed to be printable.

If the unmarshalling function returns a value that does not meet the guard passed to preferences:set-default for this preference, the default value is used.

The marshall function might be called with any value returned from read and it must not raise an error (although it can return arbitrary results if it gets bad input). This might happen when the preferences file becomes corrupted, or is edited by hand.

preferences:set-un/marshall must be called before calling preferences:get,preferences:set.

See also serialize and deserialize.

procedure

(preferences:restore-defaults) → void?

(preferences:restore-defaults) restores the users’ configuration to the default preferences.

procedure

(preferences:register-save-callback callback) → symbol?

  callback : (-> boolean? any)
Registers callback to run twice for each call to preferences:set—once before the preferences file is written, with #t, and once after it is written, with #f. Registration returns a key for use with preferences:unregister-save-callback. Caveats:

  • The callback occurs on whichever thread happened to call preferences:set.

  • Pre- and post-write notifications are not necessarily paired; unregistration may cancel the post-write notification before it occurs.

procedure

(preferences:unregister-save-callback key) → void?

  key : symbol?
Unregisters the save callback associated with key.

procedure

(exn:make-unknown-preference message 
  continuation-marks) 
 → exn:unknown-preference?
  message : string?
  continuation-marks : continuation-mark-set?
Creates an unknown preference exception.

procedure

(exn:unknown-preference? exn) → boolean?

  exn : any/c
Determines if a value is an unknown preference exn.

value

exn:struct:unknown-preference : struct-type?

The struct type for the unknown preference exn.

parameter

(preferences:low-level-put-preferences)

 → (-> (listof symbol?) (listof any/c) any)
(preferences:low-level-put-preferences put-preferences) → void?
  put-preferences : (-> (listof symbol?) (listof any/c) any)
This parameter’s value is called to save preference the preferences file. Its interface should be just like mzlib’s put-preferences.

The default value calls put-preferences and, if there is an error, then starts using a hash-table to save the preferences instead. See also

parameter

(preferences:low-level-get-preference)

 → (->* (symbol?) [(-> any)] any)
(preferences:low-level-get-preference get-preference) → void?
  get-preference : (->* (symbol?) [(-> any)] any)
This parameter’s value is called to get a preference from the preferences file. Its interface should be just like get-preference.

The default value calls get-preferences and, if there is an error, then starts using a hash-table to save the preferences instead.

procedure

(preferences:snapshot? arg) → boolean?

  arg : any/c
Determines if its argument is a preferences snapshot.

See also preferences:get-prefs-snapshot and preferences:restore-prefs-snapshot.

procedure

(preferences:restore-prefs-snapshot snapshot) → void?

  snapshot : preferences:snapshot?
Restores the preferences saved in snapshot, updating all of the preferences values to the ones they had at the time that preferences:get-prefs-snapshot was called.

See also preferences:get-prefs-snapshot.

procedure

(preferences:get-prefs-snapshot) → preferences:snapshot?

Caches all of the current values of the known preferences and returns them. For any preference that has marshalling and unmarshalling set (see preferences:set-un/marshall), the preference value is copied by passing it through the marshalling and unmarshalling process. Other values are not copied, but references to them are instead saved.

See also preferences:restore-prefs-snapshot.

procedure

(preferences:new-layer previous-preferences-layer)

 → preferences:layer?
  previous-preferences-layer : (or/c #f preferences:layer?)
Creates a preferences layer that extends previous-preferences-layer.

Added in version 1.30 of package gui-lib.

procedure

(preferences:layer? v) → boolean?

  v : any/c
Determines if v is a preferences layer.

A preferences layer gives a form of scoping to preferences. When a new preference is first registered with this library (via a call to preferences:set-default or preferences:add-callback) it is put into the layer in preferences:current-layer (and not into any of that layer’s previous layers). When preferences:get, preferences:set, preferences:set-un/marshall are called, they consult and manipulate only the layer where the preference was first installed. Accordingly, preference layers give a way to discard some set of calls to preference:set-default and other preference configuration and to start over with a new set. Note that this affects only the configuration of the preferences for the library; the values are all stored centrally (see preferences:low-level-put-preferences) and are unaffected by the layers.

Examples:
> (define original-layer (preferences:current-layer))
> (define layer2 (preferences:new-layer original-layer))
> (parameterize ([preferences:current-layer layer2])
    ; initialize 'a-pref in layer2
    (preferences:set-default 'a-pref 5 real?)
    (preferences:set 'a-pref 6)
    (preferences:get 'a-pref))

6

> (define layer3 (preferences:new-layer original-layer))
> (parameterize ([preferences:current-layer layer3])
    ; initialize 'a-pref again, this time in layer3
    ; without the new layer in place, this would be an error
    (preferences:set-default 'a-pref 5 real?)
    ; the actual value of the preference remains
    ; from the previous call to preferences:set
    (preferences:get 'a-pref))

6

Added in version 1.30 of package gui-lib.

parameter

(preferences:current-layer) → preferences:layer?

(preferences:current-layer preferences-layer) → void?
  preferences-layer : preferences:layer?
Determines the current preferences layer.

Added in version 1.30 of package gui-lib.

  top  ← prev  up  next →