tk/doc/HandleEvent.3

   1 '\"
   2 '\" Copyright (c) 1990-1992 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_HandleEvent 3 "" Tk "Tk Library Procedures"
  12 .BS
  13 .SH NAME
  14 Tk_HandleEvent \- invoke event handlers for window system events
  15 .SH SYNOPSIS
  16 .nf
  17 \fB#include <tk.h>\fR
  18 .sp
  19 \fBTk_HandleEvent\fR(\fIeventPtr\fR)
  20 .SH ARGUMENTS
  21 .AS XEvent *eventPtr
  22 .AP XEvent *eventPtr in
  23 Pointer to X event to dispatch to relevant handler(s).
  24 .BE
  25
  26 .SH DESCRIPTION
  27 .PP
  28 \fBTk_HandleEvent\fR is a lower-level procedure that deals with window
  29 events.  It is called by \fBTk_ServiceEvent\fR (and indirectly by
  30 \fBTk_DoOneEvent\fR), and in a few other cases within Tk.
  31 It makes callbacks to any window event
  32 handlers (created by calls to \fBTk_CreateEventHandler\fR)
  33 that match \fIeventPtr\fR and then returns.  In some cases
  34 it may be useful for an application to bypass the Tk event
  35 queue and call \fBTk_HandleEvent\fR directly instead of
  36 calling \fBTk_QueueEvent\fR followed by
  37 \fBTk_ServiceEvent\fR.
  38 .PP
  39 This procedure may be invoked recursively.  For example,
  40 it is possible to invoke \fBTk_HandleEvent\fR recursively
  41 from a handler called by \fBTk_HandleEvent\fR.  This sort
  42 of operation is useful in some modal situations, such
  43 as when a
  44 notifier has been popped up and an application wishes to
  45 wait for the user to click a button in the notifier before
  46 doing anything else.
  47
  48 .SH KEYWORDS
  49 callback, event, handler, window