1uevent(n) User events uevent(n)
2______________________________________________________________________________
6
8 uevent - User events
9
11 package require Tcl 8.4
12 package require uevent ?0.2?
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_________________________________________________________________
32
34 This package provides a general facility for the handling of user
35 events. Allows the binding of arbitrary commands to arbitrary events on
36 arbitrary tags, removal of bindings, and event generation.
37 The main difference to the event system built into the Tcl/Tk core is
39 that the latter can generate only virtual events, and only for widgets.
40 It is not possible to use the builtin facilities to bind to events on
41 arbitrary (pseudo-)objects, nor is it able to generate events for such.
42 Here we can, by assuming that each object in question is represented by
44 its own tag. Which is possible as we allow arbitrary tags.
45 More differences:
47 [1] The package uses only a two-level hierarchy, tags and events, to
49 handle everything, whereas the Tcl/Tk system uses three levels,
50 i.e. objects, tags, and events, with a n:m relationship between
51 objects and tags.
52 [2] This package triggers all bound commands for a tag/event combi‐
54 nation, and they are independent of each other. A bound command
55 cannot force the event processing core to abort the processing
56 of command coming after it.
57
59 The package exports three commands, as specified below:
60 ::uevent::bind tag event command
62 Using this command registers the command prefix to be triggered
63 when the event occurs for the tag. The result of the command is
64 an opaque token representing the binding. Note that if the same
65 combination of <tag,event,command> is used multiple times the
66 same token is returned by every call.
67 The signature of the command prefix is
69 command tag event details
71 where details contains the argument(s) of the event. Its contents are
73 event specific and have to be agreed upon between actual event genera‐
74 tor and consumer. This package simply transfers the information and
75 does not perform any processing beyond that.
76 ::uevent::unbind token
78 This command releases the event binding represented by the
79 token. The token has to be the result of a call to
80 ::uevent::bind. The result of the command is the empty string.
81 ::uevent::generate tag event ?details?
83 This command generates an event for the tag, triggering all com‐
84 mands bound to that combination. The details argument is simply
85 passed unchanged to all event handlers. It is the responsibility
86 of the code generating and consuming the event to have an agree‐
87 ment about the format and contents of the information carried
88 therein. The result of the command is the empty string.
89 Note that all bound commands are triggered, independently of
91 each other. The event handlers cannot assume a specific order.
92 They are also not called synchronously with the invokation of
93 this command, but simply put into the event queue for processing
94 when the system returns to the event loop.
95 Generating an event for an unknown tag, or for a <tag,event>
97 combination which has no commands bound to it is allowed, such
98 calls will be ignored.
99 ::uevent::list
101 In this form the command returns a list containing the names of
102 all tags which have events with commands bound to them.
103 ::uevent::list tag
105 In this format the command returns a list containing the names
106 of all events for the tag with commands bound to them. Specify‐
107 ing an unknown tag, i.e. a tag without event and commands, will
108 cause the command to throw an error.
109 ::uevent::list tag event
111 In this format the command returns a list containing all com‐
112 mands bound to the event for the tag. Specifying an unknown tag
113 or unknown event, will cause the command to throw an error.
114
116 This document, and the package it describes, will undoubtedly contain
117 bugs and other problems. Please report such in the category uevent of
118 the Tcllib SF Trackers [http://source‐
119 forge.net/tracker/?group_id=12883]. Please also report any ideas for
120 enhancements you may have for either package and/or documentation.
121
123 bind, event, generate event, unbind
124
126 Copyright (c) 2007 Andreas Kupries <andreas_kupries@users.sourceforge.net>
127uev 0.2 uevent(n)