1uevent(n)                         User events                        uevent(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       uevent - User events
9

SYNOPSIS

11       package require Tcl  8.4
12
13       package require uevent  ?0.3.1?
14
15       package require logger
16
17       ::uevent::bind tag event command
18
19       command tag event details
20
21       ::uevent::unbind token
22
23       ::uevent::generate tag event ?details?
24
25       ::uevent::list
26
27       ::uevent::list tag
28
29       ::uevent::list tag event
30
31       ::uevent::watch::tag::add pattern command
32
33       {*}command bound tag
34
35       {*}command unbound tag
36
37       ::uevent::watch::tag::remove token
38
39       ::uevent::watch::event::add tag_pattern event_pattern command
40
41       {*}command bound tag event
42
43       {*}command unbound tag event
44
45       ::uevent::watch::event::remove token
46
47______________________________________________________________________________
48

DESCRIPTION

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
54       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
59       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
62       More differences:
63
64       [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
69       [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

API

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
79       ::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
86              The signature of the command prefix is
87
88              command tag event details
89
90       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
95       ::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
100       ::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
108              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
114              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
118       ::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
122       ::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
128       ::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
133       ::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
138              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
142              The signature of the command prefix is
143
144              {*}command bound tag
145
146              {*}command unbound tag
147
148       The result of the command is a token representing the watcher.
149
150       ::uevent::watch::tag::remove token
151              This command removes a watcher for (un)bind events on tags.
152
153              The result of the command is the empty string.
154
155       ::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
160              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
164              The signature of the command prefix is
165
166              {*}command bound tag event
167
168              {*}command unbound tag event
169
170       The result of the command is a token representing the watcher.
171
172       ::uevent::watch::event::remove token
173              This  command removes a watcher for (un)bind events on tag/event
174              combinations.
175
176              The result of the command is the empty string.
177

BUGS, IDEAS, FEEDBACK

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
185       When proposing code changes, please provide unified diffs, i.e the out‐
186       put of diff -u.
187
188       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

SEE ALSO

194       hook(n)
195

KEYWORDS

197       bind, event, generate event, hook, unbind
198

CATEGORY

200       Programming tools
201
203       Copyright (c) 2007-2012 Andreas Kupries <andreas_kupries@users.sourceforge.net>
204
205
206
207
208tcllib                               0.3.1                           uevent(n)
Impressum