head	1.5;
access;
symbols
	core-8-5-9:1.4
	core-8-5-8:1.4
	macosx-cocoa-merge:1.5
	macosx-cocoa-premerge:1.5
	macosx-carbon-freeze:1.5
	core-8-5-7:1.4
	core-8-5-6:1.4
	core-8-6-b1:1.5
	core-8-6-a3:1.5
	core-8-5-5:1.4
	core-8-6-a2:1.5
	core-8-5-4:1.4
	core-8-5-3:1.4
	core-8-6-a1:1.4
	core-8-4-19:1.1
	core-8-5-branch:1.4.0.2
	core-8-5-2:1.4
	core-8-4-18:1.1
	core-8-5-1:1.4
	core-8-4-17:1.1
	core-8-5-0:1.4
	core-8-5-b3:1.3
	core-8-5-b2:1.2
	core-8-4-16:1.1
	core-8-5-b1:1.2
	core-stablilizer-merge:1.2
	core-stabilizer-branch:1.2.0.2
	core-stabilizer-merge:1.4
	core-8-4-15:1.1
	core-8-5-a6:1.2
	core-8-5-a5:1.2
	core-8-4-14:1.1
	core-8-5-a4:1.2
	core-8-4-13:1.1
	core-8-4-12:1.1
	core-8-4-11:1.1
	core-8-5-a3:1.2
	core-8-4-10:1.1
	core-8-4-9-branch:1.1.0.12
	core-8-5-a2:1.2
	core-8-4-9:1.1
	core-8-4-8:1.1
	core-8-4-7:1.1
	core-8-5-a1:1.1
	core-8-4-6:1.1
	core-8-4-5:1.1
	mistachkin-dev-branch:1.1.0.10
	core-8-4-4:1.1
	core-8-4-3:1.1
	core-8-4-branch:1.1.0.8
	core-8-4-2:1.1
	core-8-4-1:1.1
	core-8-4-0:1.1
	macosx-8-4-merge-2002-08-31-trunk:1.1
	macosx-8-4-premerge-2002-08-31-branch:1.1
	macosx-8-4-premerge-2002-08-31-trunk:1.1
	macosx-8-4-merge-2002-08-30-branch:1.1
	macosx-8-4-merge-2002-08-30-trunk:1.1
	macosx-8-4-merge-2002-08-20-branch:1.1
	macosx-8-4-merge-2002-08-20-trunk:1.1
	core-8-4-b2:1.1
	core-8-4-b1:1.1
	macosx-premerge-6-9-02:1.1
	core-8-4-a4:1.1
	macosx-8-4-branch:1.1.0.6
	macosx-8-4-branchpoint:1.1
	core-8-4-a3:1.1
	dgp-privates-into-namespace:1.1.0.4
	core-8-4-win-speedup:1.1.0.2
	core-8-4-a2:1.1
	core-8-4-a1:1.1;
locks; strict;
comment	@.\" @;


1.5
date	2008.06.30.22.57.00;	author dkf;	state Exp;
branches;
next	1.4;

1.4
date	2007.12.13.15.23.42;	author dgp;	state Exp;
branches;
next	1.3;

1.3
date	2007.10.29.16.04.12;	author dkf;	state Exp;
branches;
next	1.2;

1.2
date	2004.09.19.16.05.36;	author dkf;	state Exp;
branches
	1.2.2.1;
next	1.1;

1.1
date	2000.06.03.08.57.34;	author hobbs;	state Exp;
branches;
next	;

1.2.2.1
date	2007.11.01.16.37.11;	author dgp;	state Exp;
branches;
next	;


desc
@@


1.5
log
@Minor doc updates (removing out of date changebars, improving typedef formatting,
 etc.)
@
text
@'\"
'\" 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.4 2007/12/13 15:23:42 dgp 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 is not 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 \fBTk_ClientMessageProc\fR(
        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 was not 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
@


1.4
log
@merge stable branch onto HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CrtCmHdlr.3,v 1.2.2.1 2007/11/01 16:37:11 dgp Exp $
a24 1

a26 1

d42 3
a44 3
typedef int Tk_ClientMessageProc(
    Tk_Window \fItkwin\fR,
    XEvent *\fIeventPtr\fR);
a64 1

@


1.3
log
@Lots more GOOBE stuff. Now works with 'make html'!
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CrtCmHdlr.3,v 1.2 2004/09/19 16:05:36 dkf Exp $
@


1.2
log
@Standardize style of section refs & public symbols. Remove displayed tabs
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CrtCmHdlr.3,v 1.1 2000/06/03 08:57:34 hobbs Exp $
d30 1
a30 1
in the future whenever a ClientMessage X event occurs that isn't handled by
d52 1
a52 1
the \fIproc\fR is called if it wasn't handled as a \fBWM_PROTOCOL\fR.
@


1.2.2.1
log
@merge updates from HEAD
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id: CrtCmHdlr.3,v 1.2 2004/09/19 16:05:36 dkf Exp $
d30 1
a30 1
in the future whenever a ClientMessage X event occurs that is not handled by
d52 1
a52 1
the \fIproc\fR is called if it was not handled as a \fBWM_PROTOCOL\fR.
@


1.1
log
@	* doc/CrtCmHdlr.3: new doc for ClientMessage handler procs
@
text
@d7 1
a7 1
'\" RCS: @@(#) $Id:  Exp $
d45 2
a46 2
	Tk_Window \fItkwin\fR,
	XEvent *\fIeventPtr\fR);
@

