tk/doc/EventHndlr.3

   1 '\"
   2 '\" Copyright (c) 1990 The Regents of the University of California.
   3 '\" Copyright (c) 1994-1996 Sun Microsystems, Inc.
   4 '\"
   5 '\" See the file "license.terms" for information on usage and redistribution
   6 '\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
   7 '\"
   8 '\" RCS: @(#) $Id$
   9 '\"
  10 .so man.macros
  11 .TH Tk_CreateEventHandler 3 "" Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_CreateEventHandler, Tk_DeleteEventHandler \- associate procedure callback with an X event
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 \fBTk_CreateEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
  20 .sp
  21 \fBTk_DeleteEventHandler\fR(\fItkwin, mask, proc, clientData\fR)
  22 .SH ARGUMENTS
  23 .AS "unsigned long" clientData
  24 .AP Tk_Window tkwin in
  25 Token for window in which events may occur.
  26 .AP "unsigned long" mask in
  27 Bit-mask of events (such as \fBButtonPressMask\fR)
  28 for which \fIproc\fR should be called.
  29 .AP Tk_EventProc *proc in
  30 Procedure to invoke whenever an event in \fImask\fR occurs
  31 in the window given by \fItkwin\fR.
  32 .AP ClientData clientData in
  33 Arbitrary one-word value to pass to \fIproc\fR.
  34 .BE
  35
  36 .SH DESCRIPTION
  37 .PP
  38 \fBTk_CreateEventHandler\fR arranges for \fIproc\fR to be
  39 invoked in the future whenever one of the event types specified
  40 by \fImask\fR occurs in the window specified by \fItkwin\fR.
  41 The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
  42 this mechanism only works in programs that dispatch events
  43 through \fBTk_HandleEvent\fR (or through other Tk procedures that
  44 call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
  45 \fBTk_MainLoop\fR).
  46 .PP
  47 \fIProc\fR should have arguments and result that match the
  48 type \fBTk_EventProc\fR:
  49 .CS
  50 typedef void Tk_EventProc(
  51         ClientData \fIclientData\fR,
  52         XEvent *\fIeventPtr\fR);
  53 .CE
  54 The \fIclientData\fR parameter to \fIproc\fR is a copy of the \fIclientData\fR
  55 argument given to \fBTk_CreateEventHandler\fR when the callback
  56 was created.  Typically, \fIclientData\fR points to a data
  57 structure containing application-specific information about
  58 the window in which the event occurred.  \fIEventPtr\fR is
  59 a pointer to the X event, which will be one of the ones
  60 specified in the \fImask\fR argument to \fBTk_CreateEventHandler\fR.
  61 .PP
  62 \fBTk_DeleteEventHandler\fR may be called to delete a
  63 previously-created event handler:  it deletes the first handler
  64 it finds that is associated with \fItkwin\fR and matches the
  65 \fImask\fR, \fIproc\fR, and \fIclientData\fR arguments.  If
  66 no such handler exists, then \fBTk_HandleEvent\fR returns
  67 without doing anything.  Although Tk supports it, it's probably
  68 a bad idea to have more than one callback with the same \fImask\fR,
  69 \fIproc\fR, and \fIclientData\fR arguments.
  70 When a window is deleted all of its handlers will be deleted
  71 automatically;  in this case there is no need to call
  72 \fBTk_DeleteEventHandler\fR.
  73 .PP
  74 If multiple handlers are declared for the same type of X event
  75 on the same window, then the handlers will be invoked in the
  76 order they were created.
  77
  78 .SH KEYWORDS
  79 bind, callback, event, handler