25 Preferences, Textual

▼ |  | Framework: Racket GUI Application Framework

1 | Application
2 | Autosave
3 | Canvas
4 | Color Model
5 | Color Prefs
6 | Color
7 | Comment Box
8 | Editor Snip
9 | Editor
10 | Exit
11 | Finder
12 | Frame
13 | Group
14 | GUI Utilities
15 | Handler
16 | Icon
17 | Keymap
18 | Menu
19 | Mode
20 | Number Snip
21 | Panel
22 | Pasteboard
23 | Path Utils
24 | Preferences
25 | Preferences, Textual
26 | Racket
27 | Text
28 | Splash
29 | Test
30 | Version
| Index

On this page:

preferences: get
preferences: set
preferences: add-callback
preferences: set-default
preferences: set-un/ marshall
preferences: restore-defaults
exn: make-unknown-preference
exn: unknown-preference?
preferences: low-level-put-preferences
preferences: low-level-get-preference
preferences: snapshot?
preferences: restore-prefs-snapshot
preferences: get-prefs-snapshot

top← prev up next →

### 25`` Preferences, Textual

( require framework/preferences)

( preferences:get symbol) → any/c
symbol : symbol?

See also preferences:set-default.

preferences:get returns the value for the preference symbol. It raises exn:unknown-preference if the preference’s default has not been set.

( preferences:set symbol value) → void?
symbol : symbol?
value : any/c

See also preferences:set-default.

preferences:set-preference sets the preference symbol to value. This should be called when the users requests a change to a preference.

This function immediately writes the preference value to disk.

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

( preferences:add-callback p f [weak?]) → (-> void?)
p : symbol?
f : ( λ (x) ( and ( procedure? x) ( procedure-arity-includes? x 2)))
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.

This function raises exn:unknown-preference exn:unknown-preference if the preference has not been set.

( 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, 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.

( preferences:set-un/marshall |  | symbol |  |  |  |
|  | marshall |  |  |  |
|  | unmarshall) |  | → |  | void?

symbol : symbol?
marshall : ( any/c . -> . printable/c)
unmarshall : ( printable/c . -> . any/c)

preference: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 preference: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.

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

( preferences:restore-defaults) → void?

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

( exn:make-unknown-preference |  | message |
|  | continuation-marks) |

→ exn:unknown-preference?
message : string?
continuation-marks : continuation-mark-set?

Creates an unknown preference exception.

( exn:unknown-preference? exn) → boolean?
exn : any/c

Determines if a value is an unknown preference exn.

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

( 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 mzlib’s get-preference.

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

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

Restores the preferences saved in snapshot.

See also preferences:get-prefs-snapshot.

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

Caches all of the current values of the 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.

top← prev up next →