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
|
# Copyright (c) 1990 The Regents of the University of California.
# Copyright (c) 1994-1996 Sun Microsystems, Inc.
# See the file "license.terms" for information on usage and redistribution
# of this file, and for a DISCLAIMER OF ALL WARRANTIES.
#
#
=head1 NAME
Tk_CreateEventHandler, Tk_DeleteEventHandler - associate procedure callback with an X event
=for category C Programming
=head1 SYNOPSIS
B<#include E<lt>tk.hE<gt>>
B<Tk_CreateEventHandler>(I<tkwin, mask, proc, clientData>)
B<Tk_DeleteEventHandler>(I<tkwin, mask, proc, clientData>)
=head1 ARGUMENTS
=over 4
=item Tk_Window tkwin (in)
Token for window in which events may occur.
=item "unsigned long" mask (in)
Bit-mask of events (such as B<ButtonPressMask>)
for which I<proc> should be called.
=item Tk_EventProc *proc (in)
Procedure to invoke whenever an event in I<mask> occurs
in the window given by I<tkwin>.
=item ClientData clientData (in)
Arbitrary one-word value to pass to I<proc>.
=back
=head1 DESCRIPTION
B<Tk_CreateEventHandler> arranges for I<proc> to be
invoked in the future whenever one of the event types specified
by I<mask> occurs in the window specified by I<tkwin>.
The callback to I<proc> will be made by B<Tk_HandleEvent>;
this mechanism only works in programs that dispatch events
through B<Tk_HandleEvent> (or through other Tk procedures that
call B<Tk_HandleEvent>, such as B<Tk_DoOneEvent> or
B<Tk_MainLoop>).
I<Proc> should have arguments and result that match the
type B<Tk_EventProc>:
typedef void Tk_EventProc(
ClientData clientData,
XEvent *eventPtr);
The I<clientData> parameter to I<proc> is a copy of the I<clientData>
argument given to B<Tk_CreateEventHandler> when the callback
was created. Typically, I<clientData> points to a data
structure containing application-specific information about
the window in which the event occurred. I<EventPtr> is
a pointer to the X event, which will be one of the ones
specified in the I<mask> argument to B<Tk_CreateEventHandler>.
B<Tk_DeleteEventHandler> may be called to delete a
previously-created event handler: it deletes the first handler
it finds that is associated with I<tkwin> and matches the
I<mask>, I<proc>, and I<clientData> arguments. If
no such handler exists, then B<Tk_EventHandler> returns
without doing anything. Although Tk supports it, it's probably
a bad idea to have more than one callback with the same I<mask>,
I<proc>, and I<clientData> arguments.
When a window is deleted all of its handlers will be deleted
automatically; in this case there is no need to call
B<Tk_DeleteEventHandler>.
If multiple handlers are declared for the same type of X event
on the same window, then the handlers will be invoked in the
order they were created.
=head1 KEYWORDS
bind, callback, event, handler
|
