1uevent(n) User events uevent(n)
2______________________________________________________________________________
6
8 uevent - User events
9
11 package require Tcl 8.4
12 package require uevent ?0.3.1?
14 package require logger
16 ::uevent::bind tag event command
18 command tag event details
20 ::uevent::unbind token
22 ::uevent::generate tag event ?details?
24 ::uevent::list
26 ::uevent::list tag
28 ::uevent::list tag event
30 ::uevent::watch::tag::add pattern command
32 {*}command bound tag
34 {*}command unbound tag
36 ::uevent::watch::tag::remove token
38 ::uevent::watch::event::add tag_pattern event_pattern command
40 {*}command bound tag event
42 {*}command unbound tag event
44 ::uevent::watch::event::remove token
46______________________________________________________________________________
48
50 This package provides a general facility for the handling of user
51 events. Allows the binding of arbitrary commands to arbitrary events on
52 arbitrary tags, removal of bindings, and event generation.
53 The main difference to the event system built into the Tcl/Tk core is
55 that the latter can generate only virtual events, and only for widgets.
56 It is not possible to use the builtin facilities to bind to events on
57 arbitrary (pseudo-)objects, nor is it able to generate events for such.
58 Here we can, by assuming that each object in question is represented by
60 its own tag. Which is possible as we allow arbitrary tags.
61 More differences:
63 [1] The package uses only a two-level hierarchy, tags and events, to
65 handle everything, whereas the Tcl/Tk system uses three levels,
66 i.e. objects, tags, and events, with a n:m relationship between
67 objects and tags.
68 [2] This package triggers all bound commands for a tag/event combi‐
70 nation, and they are independent of each other. A bound command
71 cannot force the event processing core to abort the processing
72 of command coming after it.
73
75 The package exports eight commands, as specified below. Note that when
76 the package is used from within Tcl 8.5+ all the higher commands are
77 ensembles, i.e. the :: separators can be replaceed by spaces.
78 ::uevent::bind tag event command
80 Using this command registers the command prefix to be triggered
81 when the event occurs for the tag. The result of the command is
82 an opaque token representing the binding. Note that if the same
83 combination of <tag,event,command> is used multiple times the
84 same token is returned by every call.
85 The signature of the command prefix is
87 command tag event details
89 where details contains the argument(s) of the event. Its contents are
91 event specific and have to be agreed upon between actual event genera‐
92 tor and consumer. This package simply transfers the information and
93 does not perform any processing beyond that.
94 ::uevent::unbind token
96 This command releases the event binding represented by the
97 token. The token has to be the result of a call to
98 ::uevent::bind. The result of the command is the empty string.
99 ::uevent::generate tag event ?details?
101 This command generates an event for the tag, triggering all com‐
102 mands bound to that combination. The details argument is simply
103 passed unchanged to all event handlers. It is the responsibility
104 of the code generating and consuming the event to have an agree‐
105 ment about the format and contents of the information carried
106 therein. The result of the command is the empty string.
107 Note that all bound commands are triggered, independently of
109 each other. The event handlers cannot assume a specific order.
110 They are also not called synchronously with the invokation of
111 this command, but simply put into the event queue for processing
112 when the system returns to the event loop.
113 Generating an event for an unknown tag, or for a <tag,event>
115 combination which has no commands bound to it is allowed, such
116 calls will be ignored.
117 ::uevent::list
119 In this form the command returns a list containing the names of
120 all tags which have events with commands bound to them.
121 ::uevent::list tag
123 In this format the command returns a list containing the names
124 of all events for the tag with commands bound to them. Specify‐
125 ing an unknown tag, i.e. a tag without event and commands, will
126 cause the command to throw an error.
127 ::uevent::list tag event
129 In this format the command returns a list containing all com‐
130 mands bound to the event for the tag. Specifying an unknown tag
131 or unknown event, will cause the command to throw an error.
132 ::uevent::watch::tag::add pattern command
134 This command sets up a sort of reverse events. Events generated,
135 i.e. the command prefix invoked, when observers bind to and
136 unbind from specific tags.
137 Note that the command prefix is only invoked twice per tag,
139 first when the first command is bound to any event of the tag,
140 and second when the last command bound to the tag is removed.
141 The signature of the command prefix is
143 {*}command bound tag
145 {*}command unbound tag
147 The result of the command is a token representing the watcher.
149 ::uevent::watch::tag::remove token
151 This command removes a watcher for (un)bind events on tags.
152 The result of the command is the empty string.
154 ::uevent::watch::event::add tag_pattern event_pattern command
156 This command sets up a sort of reverse events. Events generated,
157 i.e. the command prefix invoked, when observers bind to and
158 unbind from specific combinations of tags and events.
159 Note that the command prefix is only invoked twice per tag/event
161 combination, first when the first command is bound to it, and
162 second when the last command bound to the it is removed.
163 The signature of the command prefix is
165 {*}command bound tag event
167 {*}command unbound tag event
169 The result of the command is a token representing the watcher.
171 ::uevent::watch::event::remove token
173 This command removes a watcher for (un)bind events on tag/event
174 combinations.
175 The result of the command is the empty string.
177
179 This document, and the package it describes, will undoubtedly contain
180 bugs and other problems. Please report such in the category uevent of
181 the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please
182 also report any ideas for enhancements you may have for either package
183 and/or documentation.
184 When proposing code changes, please provide unified diffs, i.e the out‐
186 put of diff -u.
187 Note further that attachments are strongly preferred over inlined
189 patches. Attachments can be made by going to the Edit form of the
190 ticket immediately after its creation, and then using the left-most
191 button in the secondary navigation bar.
192
194 hook(n)
195
197 bind, event, generate event, hook, unbind
198
200 Programming tools
201
203 Copyright (c) 2007-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net>
204tcllib 0.3.1 uevent(n)