* doc/CrtCmHdlr.3: new doc for ClientMessage handler procs

1 files changed, 69 insertions, 0 deletions

diff --git a/doc/CrtCmHdlr.3 b/doc/CrtCmHdlr.3
new file mode 100644
index 0000000..f64e79b
--- /dev/null
+++ b/doc/CrtCmHdlr.3
@@ -0,0 +1,69 @@
+'\"
+'\" Copyright (c) 2000 Ajuba Solutions.
+'\"
+'\" See the file "license.terms" for information on usage and redistribution
+'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
+'\" 
+'\" RCS: @(#) $Id: CrtCmHdlr.3,v 1.1 2000/06/03 08:57:34 hobbs Exp $
+'\" 
+.so man.macros
+.TH Tk_CreateClientMessageHandler 3 "8.4" Tk "Tk Library Procedures"
+.BS
+.SH NAME
+Tk_CreateClientMessageHandler, Tk_DeleteClientMessageHandler \- associate procedure callback with ClientMessage type X events
+.SH SYNOPSIS
+.nf
+\fB#include <tk.h>\fR
+.sp
+\fBTk_CreateClientMessageHandler\fR(\fIproc\fR)
+.sp
+\fBTk_DeleteClientMessageHandler\fR(\fIproc\fR)
+.SH ARGUMENTS
+.AP Tk_ClientMessageProc *proc in
+Procedure to invoke whenever a ClientMessage X event occurs on any display.
+.BE
+
+.SH DESCRIPTION
+.PP
+
+\fBTk_CreateClientMessageHandler\fR arranges for \fIproc\fR to be invoked
+in the future whenever a ClientMessage X event occurs that isn't handled by
+\fBWM_PROTOCOL\fR.  \fBTk_CreateClientMessageHandler\fR is intended for use
+by applications which need to watch X ClientMessage events, such as drag and
+drop applications.
+.PP
+The callback to \fIproc\fR will be made by \fBTk_HandleEvent\fR;
+this mechanism only works in programs that dispatch events
+through \fBTk_HandleEvent\fR (or through other Tk procedures that
+call \fBTk_HandleEvent\fR, such as \fBTk_DoOneEvent\fR or
+\fBTk_MainLoop\fR).
+.PP
+\fIProc\fR should have arguments and result that match the
+type \fBTk_ClientMessageProc\fR:
+.CS
+typedef int Tk_ClientMessageProc(
+	Tk_Window \fItkwin\fR,
+	XEvent *\fIeventPtr\fR);
+.CE
+The \fItkwin\fR parameter to \fIproc\fR is the Tk window which is
+associated with this event.  \fIEventPtr\fR is a pointer to the X event.
+.PP
+Whenever an X ClientMessage event is processed by \fBTk_HandleEvent\fR,
+the \fIproc\fR is called if it wasn't handled as a \fBWM_PROTOCOL\fR.
+The return value from \fIproc\fR is normally 0.
+A non-zero return value indicates that the event is not to be handled
+further; that is, \fIproc\fR has done all processing that is to be
+allowed for the event.
+.PP
+If there are multiple ClientMessage event handlers, each one is called
+for each event, in the order in which they were established.
+.PP
+\fBTk_DeleteClientMessageHandler\fR may be called to delete a
+previously-created ClientMessage event handler: it deletes each handler it
+finds that matches the \fIproc\fR argument.  If no such handler exists,
+then \fBTk_DeleteClientMessageHandler\fR returns without doing anything.
+Although Tk supports it, it's probably a bad idea to have more than one
+callback with the same \fIproc\fR argument.
+
+.SH KEYWORDS
+bind, callback, event, handler