Tk Library Source Code

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421

hook(n) Hooks hook(n) ______________________________________________________________________________ NNAAMMEE hook - Hooks SSYYNNOOPPSSIISS package require TTccll 88..55 package require hhooookk ??00..11?? hhooookk bbiinndd ?_s_u_b_j_e_c_t? ?_h_o_o_k? ?_o_b_s_e_r_v_e_r? ?_c_m_d_P_r_e_f_i_x? hhooookk ccaallll _s_u_b_j_e_c_t _h_o_o_k ?_a_r_g_s...? hhooookk ffoorrggeett _o_b_j_e_c_t hhooookk ccggeett _o_p_t_i_o_n hhooookk ccoonnffiigguurree ooppttiioonn _v_a_l_u_e ... _________________________________________________________________ DDEESSCCRRIIPPTTIIOONN This package provides the hhooookk ensemble command, which implements the Subject/Observer pattern. It allows _s_u_b_j_e_c_t_s, which may be _m_o_d_u_l_e_s, _o_b_j_e_c_t_s, _w_i_d_g_e_t_s, and so forth, to synchronously call _h_o_o_k_s which may be bound to an arbitrary number of subscribers, called _o_b_s_e_r_v_e_r_s. A subject may call any number of distinct hooks, and any number of observers can bind callbacks to a particular hook called by a particu- lar subject. Hook bindings can be queried and deleted. This man page is intended to be a reference only. CCOONNCCEEPPTTSS IINNTTRROODDUUCCTTIIOONN Tcl modules usually send notifications to other modules in two ways: via Tk events, and via callback options like the text widget's --yyssccrroollllccoommmmaanndd option. Tk events are available only in Tk, and call- back options require tight coupling between the modules sending and receiving the notification. Loose coupling between sender and receiver is often desirable, however. In Model/View/Controller terms, a View can send a command (stemming from user input) to the Controller, which updates the Model. The Model can then call a hook _t_o _w_h_i_c_h _a_l_l _r_e_l_e_v_a_n_t _V_i_e_w_s _s_u_b_s_c_r_i_b_e_. The Model is decoupled from the Views, and indeed need not know whether any Views actually exist. At present, Tcl/Tk has no standard mechanism for implementing loose coupling of this kind. This package defines a new command, hhooookk, which implements just such a mechanism. BBIINNDDIINNGGSS The hhooookk command manages a collection of hook bindings. A hook binding has four elements: [1] A _s_u_b_j_e_c_t: the name of the entity that will be calling the hook. [2] The _h_o_o_k itself. A hook usually reflects some occurrence in the life of the _s_u_b_j_e_c_t that other entities might care to know about. A _h_o_o_k has a name, and may also have arguments. Hook names are arbitrary strings. Each _s_u_b_j_e_c_t must document the names and arguments of the hooks it can call. [3] The name of the _o_b_s_e_r_v_e_r that wishes to receive the _h_o_o_k from the _s_u_b_j_e_c_t. [4] A command prefix to which the _h_o_o_k arguments will be appended when the binding is executed. SSUUBBJJEECCTTSS AANNDD OOBBSSEERRVVEERRSS For convenience, this document collectively refers to subjects and observers as _o_b_j_e_c_t_s, while placing no requirements on how these _o_b_j_e_c_t_s are actually implemented. An object can be a TTccllOOOO or SSnniitt or XXOOTTccll object, a Tcl command, a namespace, a module, a pseudo-object managed by some other object (as tags are managed by the Tk text wid- get) or simply a well-known name. Subject and observer names are arbitrary strings; however, as hhooookk might be used at the package level, it's necessary to have conventions that avoid name collisions between packages written by different peo- ple. Therefore, any subject or observer name used in core or package level code should look like a Tcl command name, and should be defined in a namespace owned by the package. Consider, for example, an ensemble com- mand ::::ffoooo that creates a set of pseudo-objects and uses hhooookk to send notifications. The pseudo-objects have names that are not commands and exist in their own namespace, rather like file handles do. To avoid name collisions with subjects defined by other packages, users of hhooookk, these ::::ffoooo handles should have names like ::::ffoooo::::11, ::::ffoooo::::22, and so on. Because object names are arbitrary strings, application code can use whatever additional conventions are dictated by the needs of the appli- cation. RREEFFEERREENNCCEE Hook provides the following commands: hhooookk bbiinndd ?_s_u_b_j_e_c_t? ?_h_o_o_k? ?_o_b_s_e_r_v_e_r? ?_c_m_d_P_r_e_f_i_x? This subcommand is used to create, update, delete, and query hook bindings. Called with no arguments it returns a list of the subjects with hooks to which observers are currently bound. Called with one argument, a _s_u_b_j_e_c_t, it returns a list of the subject's hooks to which observers are currently bound. Called with two arguments, a _s_u_b_j_e_c_t and a _h_o_o_k, it returns a list of the observers which are currently bound to this _s_u_b_j_e_c_t and _h_o_o_k. Called with three arguments, a _s_u_b_j_e_c_t, a _h_o_o_k, and an _o_b_s_e_r_v_e_r, it returns the binding proper, the command prefix to be called when the hook is called, or the empty string if there is no such binding. Called with four arguments, it creates, updates, or deletes a binding. If _c_m_d_P_r_e_f_i_x is the empty string, it deletes any exist- ing binding for the _s_u_b_j_e_c_t, _h_o_o_k, and _o_b_s_e_r_v_e_r; nothing is returned. Otherwise, _c_m_d_P_r_e_f_i_x must be a command prefix taking as many additional arguments as are documented for the _s_u_b_j_e_c_t and _h_o_o_k. The binding is added or updated, and the observer is returned. If the _o_b_s_e_r_v_e_r is the empty string, "", it will create a new binding using an automatically generated observer name of the form ::::hhooookk::::oobb<nnuummbbeerr>. The automatically generated name will be returned, and can be used to query, update, and delete the binding as usual. If automated observer names are always used, the observer name effectively becomes a unique binding ID. It is possible to call hhooookk bbiinndd to create or delete a binding to a _s_u_b_j_e_c_t and _h_o_o_k while in an observer binding for that same _s_u_b_j_e_c_t and _h_o_o_k. The following rules determine what happens when hook bind $s $h $o $binding called during the execution of hook call $s $h [1] No binding is ever called after it is deleted. [2] When a binding is called, the most recently given command prefix is always used. [3] The set of observers whose bindings are to be called is determined when this method begins to execute, and does not change thereafter, except that deleted bindings are not called. In particular: [1] If $$oo's binding to $$ss and $$hh is deleted, and $$oo's binding has not yet been called during this execution of hook call $s $h might already have been called; and in all likelihood, it is probably deleting itself.) [2] If $$oo changes the command prefix that's bound to $$ss and $$hh, and if $$oo's binding has not yet been called during this execution of hook call $s $h be called when the time comes. (But again, it is probably $$oo's binding that is is making the change.) [3] If a new observer is bound to $$ss and $$hh, its binding will not be called until the next invocation of hook call $s $h hhooookk ccaallll _s_u_b_j_e_c_t _h_o_o_k ?_a_r_g_s...? This command is called when the named _s_u_b_j_e_c_t wishes to call the named _h_o_o_k. All relevant bindings are called with the specified arguments in the global namespace. Note that the bindings are called synchronously, before the command returns; this allows the _a_r_g_s to include references to entities that will be cleaned up as soon as the hook has been called. The order in which the bindings are called is not guaranteed. If sequence among observers must be preserved, define one observer and have its bindings call the other callbacks directly in the proper sequence. Because the hhooookk mechanism is intended to support loose coupling, it is presumed that the _s_u_b_j_e_c_t has no knowledge of the observers, nor any expectation regarding return values. This has a number of implications: [1] hhooookk ccaallll returns the empty string. [2] Normal return values from observer bindings are ignored. [3] Errors and other exceptional returns propagate normally by default. This will rarely be what is wanted, because the subjects usually have no knowledge of the observers and will therefore have no particular competence at handling their errors. That makes it an application issue, and so applications will usually want to define an --eerrrroorrccoommmmaanndd. If the --eerrrroorrccoommmmaanndd configuration option has a non-empty value, its value will be invoked for all errors and other exceptional returns in observer bindings. See hhooookk ccoonnffiigguurree, below, for more information on configuration options. hhooookk ffoorrggeett _o_b_j_e_c_t This command deletes any existing bindings in which the named _o_b_j_e_c_t appears as either the _s_u_b_j_e_c_t or the _o_b_s_e_r_v_e_r. Bindings deleted by this method will never be called again. In particular, [1] If an observer is forgotten during a call to hhooookk ccaallll, any uncalled binding it might have had to the relevant subject and hook will _n_o_t be called subsequently. [2] If a subject $$ss is forgotten during a call to hook call $s $h soon as the current binding returns. No further bindings will be called. hhooookk ccggeett _o_p_t_i_o_n This command returns the value of one of the hhooookk command's configuration options. hhooookk ccoonnffiigguurree ooppttiioonn _v_a_l_u_e ... This command sets the value of one or more of the hhooookk command's configuration options: --eerrrroorrccoommmmaanndd _c_m_d_P_r_e_f_i_x If the value of this option is the empty string, "", then errors and other exception returns in binding scripts are propagated normally. Otherwise, it must be a command prefix taking three additional arguments: [1] a 4-element list {subject hook arglist observer}, [2] the result string, and [3] the return options dictionary. Given this information, the --eerrrroorrccoommmmaanndd can choose to log the error, call iinntteerrpp bbggeerrrroorr, delete the errant binding (thus preventing the error from arising a second time) and so forth. --ttrraacceeccoommmmaanndd _c_m_d_P_r_e_f_i_x The option's value should be a command prefix taking four arguments: [1] a _s_u_b_j_e_c_t, [2] a _h_o_o_k, [3] a list of the hook's argument values, and [4] a list of _o_b_j_e_c_t_s the hook was called for. The command will be called for each hook that is called. This allows the application to trace hook execution for debugging purposes. EEXXAAMMPPLLEE The ::::mmooddeell module calls the <Update> hook in response to commands that change the model's data: hook call ::model <Update> The ..vviieeww megawidget displays the model state, and needs to know about model updates. Consequently, it subscribes to the ::model's <Update> hook. hook bind ::model <Update> .view [list .view ModelUpdate] When the ::::mmooddeell calls the hook, the ..vviieeww's ModelUpdate subcommand will be called. Later the ..vviieeww megawidget is destroyed. In its destructor, it tells the _h_o_o_k that it no longer exists: hook forget .view All bindings involving ..vviieeww are deleted. CCRREEDDIITTSS Hook has been designed and implemented by William H. Duquette. BBUUGGSS,, IIDDEEAASS,, FFEEEEDDBBAACCKK This document, and the package it describes, will undoubtedly contain bugs and other problems. Please report such in the category _h_o_o_k of the _T_c_l_l_i_b _S_F _T_r_a_c_k_e_r_s [http://source- forge.net/tracker/?group_id=12883]. Please also report any ideas for enhancements you may have for either package and/or documentation. SSEEEE AALLSSOO uevent(n) KKEEYYWWOORRDDSS callback, event, hook, observer, producer, publisher, subject, sub- scriber, uevent CCAATTEEGGOORRYY Programming tools CCOOPPYYRRIIGGHHTT Copyright (c) 2010, by William H. Duquette hook 0.1 hook(n)