Tk_CreateGenericHandler (3)
associate procedure callback with all X events
SYNOPSIS
#include <tk.h>
Tk_CreateGenericHandler(proc, clientData)
Tk_DeleteGenericHandler(proc, clientData)
ARGUMENTS
"Tk_GenericProc" clientData
Tk_GenericProc *proc in
Procedure to invoke whenever any X event occurs on any display.
ClientData clientData in
Arbitrary one-word value to pass to proc.
DESCRIPTION
Tk_CreateGenericHandler arranges for proc to be
invoked in the future whenever any X event occurs. This mechanism is
not intended for dispatching X events on windows managed by Tk
(you should use Tk_CreateEventHandler for this purpose).
Tk_CreateGenericHandler is intended for other purposes, such
as tracing X events, monitoring events on windows not owned by Tk,
accessing X-related libraries that were not originally designed for
use with Tk, and so on.
The callback to proc will be made by Tk_HandleEvent;
this mechanism only works in programs that dispatch events
through Tk_HandleEvent (or through other Tk procedures that
call Tk_HandleEvent, such as Tk_DoOneEvent or
Tk_MainLoop).
Proc should have arguments and result that match the
type Tk_GenericProc:
typedef int Tk_GenericProc(
ClientData clientData,
XEvent *eventPtr);
The clientData parameter to proc is a copy of the clientData
argument given to Tk_CreateGenericHandler when the callback
was created. Typically, clientData points to a data
structure containing application-specific information about
how to handle events.
EventPtr is a pointer to the X event.
Whenever an X event is processed by Tk_HandleEvent, proc
is called. The return value from proc is normally 0.
A non-zero return value indicates that the event is not to be handled
further; that is, proc has done all processing that is to be
allowed for the event.
If there are multiple generic event handlers, each one is called
for each event, in the order in which they were established.
Tk_DeleteGenericHandler may be called to delete a
previously-created generic event handler: it deletes each handler
it finds that matches the proc and clientData arguments. If
no such handler exists, then Tk_DeleteGenericHandler returns
without doing anything. Although Tk supports it, it's probably
a bad idea to have more than one callback with the same
proc and clientData arguments.
Establishing a generic event handler does nothing to ensure that the
process will actually receive the X events that the handler wants to
process.
For example, it is the caller's responsibility to invoke
XSelectInput to select the desired events, if that is necessary.
KEYWORDS
bind, callback, event, handler
'\"
'\" Copyright (c) 1995-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.
'\"
'\" RCS: @(#) $Id: DeleteImg.3,v 1.2 1998/09/14 18:22:47 stanton Exp $
'\"
'\" The definitions below are for supplemental macros used in Tcl/Tk
'\" manual entries.
'\"
'\" .AP type name in/out ?indent?
'\" Start paragraph describing an argument to a library procedure.
'\" type is type of argument (int, etc.), in/out is either "in", "out",
'\" or "in/out" to describe whether procedure reads or modifies arg,
'\" and indent is equivalent to second arg of .IP (shouldn't ever be
'\" needed; use .AS below instead)
'\"
'\" .AS ?type? ?name?
'\" Give maximum sizes of arguments for setting tab stops. Type and
'\" name are examples of largest possible arguments that will be passed
'\" to .AP later. If args are omitted, default tab stops are used.
'\"
'\" .BS
'\" Start box enclosure. From here until next .BE, everything will be
'\" enclosed in one large box.
'\"
'\" .BE
'\" End of box enclosure.
'\"
'\" .CS
'\" Begin code excerpt.
'\"
'\" .CE
'\" End code excerpt.
'\"
'\" .VS ?version? ?br?
'\" Begin vertical sidebar, for use in marking newly-changed parts
'\" of man pages. The first argument is ignored and used for recording
'\" the version when the .VS was added, so that the sidebars can be
'\" found and removed when they reach a certain age. If another argument
'\" is present, then a line break is forced before starting the sidebar.
'\"
'\" .VE
'\" End of vertical sidebar.
'\"
'\" .DS
'\" Begin an indented unfilled display.
'\"
'\" .DE
'\" End of indented unfilled display.
'\"
'\" .SO
'\" Start of list of standard options for a Tk widget. The
'\" options follow on successive lines, in four columns separated
'\" by tabs.
'\"
'\" .SE
'\" End of list of standard options for a Tk widget.
'\"
'\" .OP cmdName dbName dbClass
'\" Start of description of a specific option. cmdName gives the
'\" option's name as specified in the class command, dbName gives
'\" the option's name in the option database, and dbClass gives
'\" the option's class in the option database.
'\"
'\" .UL arg1 arg2
'\" Print arg1 underlined, then print arg2 normally.
'\"
'\" RCS: @(#) $Id: man.macros,v 1.2 1998/09/14 18:39:54 stanton Exp $
'\"
'\" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages.
t .wh -1.3i ^B
^l \n(.l
b
'\" # Start an argument description
AP
!"\\$4"" .TP \\$4
\{\
!"\\$2"" .TP \\n()Cu
.TP 15
|