1
This document describes usage of the uim-custom API and facility for
7
* Design basics and decisions
9
* How to define your own customs
11
* How to reflect defined customs into your IM code
13
To acquire a defined custom in your IM, describe as following in the
16
(require-custom "your-custom.scm")
18
Don't use ordinary 'require' to load a custom file. The
19
require-custom performs per-user configuration loading and reload
20
management, but ordinary 'require' does not.
22
"-custom" suffix of the filename is only a convention and not
23
required. But we recommend the naming convention to manage the files
27
* Invoke an arbitrary procedure when a custom variable has been set
29
The feature is usable via the hook named 'custom-set-hooks'. See
32
(custom-add-hook 'anthy-input-mode-actions
35
(puts "anthy-input-mode-actions has been set\n")
36
(anthy-configure-widgets)))
38
Any procedure that takes no argument can be placed into the third
39
argument to custom-add-hook. The procedure will be invoked when the
40
custom variable anthy-input-mode-actions has been set. Interprocess
41
custom variable update via uim-helper-server also triggers this
42
hook. So some variables edited on uim-pref will be propagated to any
43
processes and invokes the hook on the fly.
45
For example, dynamic file switching can be triggered by uim-pref
48
(custom-add-hook 'skk-dic-file-name
52
There are some limitations for the set-hook feature.
54
- Runtime version of the custom facility (custom-rt.scm) only
55
accepts at most one hook per custom variable (full-featured
56
version can handle multiple hooks)
58
- Custom API enabled only in full-featured version (custom.scm)
59
cannot be invoked in the hook procedure.
61
Enclose such code into conditional block as follows. This ensures
62
that custom-rt.scm ignores the hook.
64
(if custom-full-featured?
65
(custom-add-hook 'anthy-kana-input-method-actions
68
(custom-choice-range-reflect-olist-val
69
'default-widget_anthy_kana_input_method
70
'anthy-kana-input-method-actions
71
anthy-kana-input-method-indication-alist))))
74
* Control activity of a custom variable
76
Any custom variables has a state named 'activity'. This state
77
indicates whether the value set in the custom variable makes sense
78
or not. The state should be reflected to value editability of the
79
corresponding widget on preference tools. i.e. Use
80
gtk_widget_set_sensitive() for the corresponding widget to reflect
83
To control activity of a custom variable, configure the hook for the
84
custom variable. Otherwise all custom variables are always active.
87
Example1: Simple activity
89
Following example shows that the custom variable
90
my-frequently-used-string1 is active only when username is
91
"yamaken". The third argument of custom-add-hook can be any
92
predicate to indicate whether the custom variable is active or
95
The activity is tested by the predicate when:
97
- The custom variable has been acquired by uim_custom_get().
99
- Invoking custom-active? explicitly
101
- Any custom variable has been set. See next example for further
104
(define-custom 'my-frequently-used-string1 "I'm hungry! Give me some sweets."
107
(_ "My frequently used string 1")
108
(_ "long description will be here."))
110
(custom-add-hook 'my-frequently-used-string1
111
'custom-activity-hooks
113
(string=? (getenv "USER")
117
Example2: Dynamic activity update reflecting other custom variable
119
The activity alters when other custom variables have been set.
121
In following example, segment-separator will be active only when
122
show-segment-separator? is true. The activity will be changed
123
automatically and noticed to client of uim-custom via callback for
124
the segment-separator previously set immediately after new value of
125
show-segment-separator? has been set.
127
The predicate will be evaluated when any of custom variables have
128
been set (changing to different value is not required). So you can
129
place any flexible predicate as the third argument for the
132
All activity predicates will be evaluated and noticed via
133
corresponding callback when any of custom variables has been set.
135
No group relationships including subgrouping is not required to set
136
variable relationships.
138
(define-custom 'show-segment-separator? #f
141
(_ "Show segment separator")
142
(_ "long description will be here."))
144
(define-custom 'segment-separator "|"
147
(_ "Segment separator")
148
(_ "long description will be here."))
150
(custom-add-hook 'segment-separator
151
'custom-activity-hooks
153
show-segment-separator?))
added
removed
doc/CUSTOM
