Debian Codegraph @

closure-library/closure/goog/tweak/tweak.js

raw
1 // Copyright 2009 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15 /**
16 * @fileoverview Provides facilities for creating and querying tweaks.
17 * @see http://code.google.com/p/closure-library/wiki/UsingTweaks
18 *
19 * @author [email protected] (Andrew Grieve)
20 */
21
22 goog.provide('goog.tweak');
23 goog.provide('goog.tweak.ConfigParams');
24
25 goog.require('goog.asserts');
26 goog.require('goog.tweak.BaseSetting');
27 goog.require('goog.tweak.BooleanGroup');
28 goog.require('goog.tweak.BooleanInGroupSetting');
29 goog.require('goog.tweak.BooleanSetting');
30 goog.require('goog.tweak.ButtonAction');
31 goog.require('goog.tweak.NumericSetting');
32 goog.require('goog.tweak.Registry');
33 goog.require('goog.tweak.StringSetting');
34
35
36 /**
37 * Calls to this function are overridden by the compiler by the processTweaks
38 * pass. It returns the overrides to default values for tweaks set by compiler
39 * options.
40 * @return {!Object<number|string|boolean>} A map of tweakId -> defaultValue.
41 * @private
42 */
43 goog.tweak.getCompilerOverrides_ = function() {
44 return {};
45 };
46
47
48 /**
49 * The global reference to the registry, if it exists.
50 * @type {goog.tweak.Registry}
51 * @private
52 */
53 goog.tweak.registry_ = null;
54
55
56 /**
57 * The boolean group set by beginBooleanGroup and cleared by endBooleanGroup.
58 * @type {goog.tweak.BooleanGroup}
59 * @private
60 */
61 goog.tweak.activeBooleanGroup_ = null;
62
63
64 /**
65 * Returns/creates the registry singleton.
66 * @return {!goog.tweak.Registry} The tweak registry.
67 */
68 goog.tweak.getRegistry = function() {
69 if (!goog.tweak.registry_) {
70 var queryString = window.location.search;
71 var overrides = goog.tweak.getCompilerOverrides_();
72 goog.tweak.registry_ = new goog.tweak.Registry(queryString, overrides);
73 }
74 return goog.tweak.registry_;
75 };
76
77
78 /**
79 * Type for configParams.
80 * TODO(agrieve): Remove |Object when optional fields in struct types are
81 * implemented.
82 * @typedef {{
83 * label:(string|undefined),
84 * validValues:(!Array<string>|!Array<number>|undefined),
85 * paramName:(string|undefined),
86 * restartRequired:(boolean|undefined),
87 * callback:(Function|undefined),
88 * token:(string|undefined)
89 * }|!Object}
90 */
91 goog.tweak.ConfigParams;
92
93
94 /**
95 * Applies all extra configuration parameters in configParams.
96 * @param {!goog.tweak.BaseEntry} entry The entry to apply them to.
97 * @param {!goog.tweak.ConfigParams} configParams Extra configuration
98 * parameters.
99 * @private
100 */
101 goog.tweak.applyConfigParams_ = function(entry, configParams) {
102 if (configParams.label) {
103 entry.label = configParams.label;
104 delete configParams.label;
105 }
106 if (configParams.validValues) {
107 goog.asserts.assert(
108 entry instanceof goog.tweak.StringSetting ||
109 entry instanceof goog.tweak.NumericSetting,
110 'Cannot set validValues on tweak: %s', entry.getId());
111 entry.setValidValues(configParams.validValues);
112 delete configParams.validValues;
113 }
114 if (goog.isDef(configParams.paramName)) {
115 goog.asserts.assertInstanceof(
116 entry, goog.tweak.BaseSetting, 'Cannot set paramName on tweak: %s',
117 entry.getId());
118 entry.setParamName(configParams.paramName);
119 delete configParams.paramName;
120 }
121 if (goog.isDef(configParams.restartRequired)) {
122 entry.setRestartRequired(configParams.restartRequired);
123 delete configParams.restartRequired;
124 }
125 if (configParams.callback) {
126 entry.addCallback(configParams.callback);
127 delete configParams.callback;
128 goog.asserts.assert(
129 !entry.isRestartRequired() || (configParams.restartRequired == false),
130 'Tweak %s should set restartRequired: false, when adding a callback.',
131 entry.getId());
132 }
133 if (configParams.token) {
134 goog.asserts.assertInstanceof(
135 entry, goog.tweak.BooleanInGroupSetting,
136 'Cannot set token on tweak: %s', entry.getId());
137 entry.setToken(configParams.token);
138 delete configParams.token;
139 }
140 for (var key in configParams) {
141 goog.asserts.fail(
142 'Unknown config options (' + key + '=' + configParams[key] +
143 ') for tweak ' + entry.getId());
144 }
145 };
146
147
148 /**
149 * Registers a tweak using the given factoryFunc.
150 * @param {!goog.tweak.BaseEntry} entry The entry to register.
151 * @param {boolean|string|number=} opt_defaultValue Default value.
152 * @param {goog.tweak.ConfigParams=} opt_configParams Extra
153 * configuration parameters.
154 * @private
155 */
156 goog.tweak.doRegister_ = function(entry, opt_defaultValue, opt_configParams) {
157 if (opt_configParams) {
158 goog.tweak.applyConfigParams_(entry, opt_configParams);
159 }
160 if (opt_defaultValue != undefined) {
161 entry.setDefaultValue(opt_defaultValue);
162 }
163 if (goog.tweak.activeBooleanGroup_) {
164 goog.asserts.assertInstanceof(
165 entry, goog.tweak.BooleanInGroupSetting,
166 'Forgot to end Boolean Group: %s',
167 goog.tweak.activeBooleanGroup_.getId());
168 goog.tweak.activeBooleanGroup_.addChild(
169 /** @type {!goog.tweak.BooleanInGroupSetting} */ (entry));
170 }
171 goog.tweak.getRegistry().register(entry);
172 };
173
174
175 /**
176 * Creates and registers a group of BooleanSettings that are all set by a
177 * single query parameter. A call to goog.tweak.endBooleanGroup() must be used
178 * to close this group. Only goog.tweak.registerBoolean() calls are allowed with
179 * the beginBooleanGroup()/endBooleanGroup().
180 * @param {string} id The unique ID for the setting.
181 * @param {string} description A description of what the setting does.
182 * @param {goog.tweak.ConfigParams=} opt_configParams Extra configuration
183 * parameters.
184 */
185 goog.tweak.beginBooleanGroup = function(id, description, opt_configParams) {
186 var entry = new goog.tweak.BooleanGroup(id, description);
187 goog.tweak.doRegister_(entry, undefined, opt_configParams);
188 goog.tweak.activeBooleanGroup_ = entry;
189 };
190
191
192 /**
193 * Stops adding boolean entries to the active boolean group.
194 */
195 goog.tweak.endBooleanGroup = function() {
196 goog.tweak.activeBooleanGroup_ = null;
197 };
198
199
200 /**
201 * Creates and registers a BooleanSetting.
202 * @param {string} id The unique ID for the setting.
203 * @param {string} description A description of what the setting does.
204 * @param {boolean=} opt_defaultValue The default value for the setting.
205 * @param {goog.tweak.ConfigParams=} opt_configParams Extra configuration
206 * parameters.
207 */
208 goog.tweak.registerBoolean = function(
209 id, description, opt_defaultValue, opt_configParams) {
210 // TODO(agrieve): There is a bug in the compiler that causes these calls not
211 // to be stripped without this outer if. Might be Issue #90.
212 if (goog.tweak.activeBooleanGroup_) {
213 var entry = new goog.tweak.BooleanInGroupSetting(
214 id, description, goog.tweak.activeBooleanGroup_);
215 } else {
216 entry = new goog.tweak.BooleanSetting(id, description);
217 }
218 goog.tweak.doRegister_(entry, opt_defaultValue, opt_configParams);
219 };
220
221
222 /**
223 * Creates and registers a StringSetting.
224 * @param {string} id The unique ID for the setting.
225 * @param {string} description A description of what the setting does.
226 * @param {string=} opt_defaultValue The default value for the setting.
227 * @param {goog.tweak.ConfigParams=} opt_configParams Extra configuration
228 * parameters.
229 */
230 goog.tweak.registerString = function(
231 id, description, opt_defaultValue, opt_configParams) {
232 goog.tweak.doRegister_(
233 new goog.tweak.StringSetting(id, description), opt_defaultValue,
234 opt_configParams);
235 };
236
237
238 /**
239 * Creates and registers a NumericSetting.
240 * @param {string} id The unique ID for the setting.
241 * @param {string} description A description of what the setting does.
242 * @param {number=} opt_defaultValue The default value for the setting.
243 * @param {goog.tweak.ConfigParams=} opt_configParams Extra configuration
244 * parameters.
245 */
246 goog.tweak.registerNumber = function(
247 id, description, opt_defaultValue, opt_configParams) {
248 goog.tweak.doRegister_(
249 new goog.tweak.NumericSetting(id, description), opt_defaultValue,
250 opt_configParams);
251 };
252
253
254 /**
255 * Creates and registers a ButtonAction.
256 * @param {string} id The unique ID for the setting.
257 * @param {string} description A description of what the action does.
258 * @param {!Function} callback Function to call when the button is clicked.
259 * @param {string=} opt_label The button text (instead of the ID).
260 */
261 goog.tweak.registerButton = function(id, description, callback, opt_label) {
262 var tweak = new goog.tweak.ButtonAction(id, description, callback);
263 tweak.label = opt_label || tweak.label;
264 goog.tweak.doRegister_(tweak);
265 };
266
267
268 /**
269 * Sets a default value to use for the given tweak instead of the one passed
270 * to the register* function. This function must be called before the tweak is
271 * registered.
272 * @param {string} id The unique string that identifies the entry.
273 * @param {string|number|boolean} value The new default value for the tweak.
274 */
275 goog.tweak.overrideDefaultValue = function(id, value) {
276 goog.tweak.getRegistry().overrideDefaultValue(id, value);
277 };
278
279
280 /**
281 * Returns the value of the boolean setting with the given ID.
282 * @param {string} id The unique string that identifies this entry.
283 * @return {boolean} The value of the tweak.
284 */
285 goog.tweak.getBoolean = function(id) {
286 return goog.tweak.getRegistry().getBooleanSetting(id).getValue();
287 };
288
289
290 /**
291 * Returns the value of the string setting with the given ID,
292 * @param {string} id The unique string that identifies this entry.
293 * @return {string} The value of the tweak.
294 */
295 goog.tweak.getString = function(id) {
296 return goog.tweak.getRegistry().getStringSetting(id).getValue();
297 };
298
299
300 /**
301 * Returns the value of the numeric setting with the given ID.
302 * @param {string} id The unique string that identifies this entry.
303 * @return {number} The value of the tweak.
304 */
305 goog.tweak.getNumber = function(id) {
306 return goog.tweak.getRegistry().getNumericSetting(id).getValue();
307 };