Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
Tk_RestrictEvents(3)	     Tk	Library	Procedures	  Tk_RestrictEvents(3)


       Tk_RestrictEvents - filter and selectively delay	X events

       #include	<tk.h>

       Tk_RestrictProc *
       Tk_RestrictEvents(proc, arg, prevArgPtr)

       Tk_RestrictProc *proc (in)		  Predicate  procedure to call
						  to filter incoming X events.
						  NULL	means  do not restrict
						  events at all.

       ClientData arg (in)			  Arbitrary argument  to  pass
						  to proc.

       ClientData *prevArgPtr (out)		  Pointer to place to save ar-
						  gument to previous  restrict

       This  procedure	is useful in certain situations	where applications are
       only prepared to	receive	certain	X events.  After Tk_RestrictEvents  is
       called,	Tcl_DoOneEvent	(and  hence  Tk_MainLoop)  will	filter X input
       events through proc.  Proc indicates whether a given  event  is	to  be
       processed  immediately,	deferred  until	some later time	(e.g. when the
       event restriction is lifted), or	discarded.  Proc is a  procedure  with
       arguments and result that match the type	Tk_RestrictProc:
	      typedef Tk_RestrictAction	Tk_RestrictProc(
		      ClientData arg,
		      XEvent *eventPtr);
       The  arg	 argument is a copy of the arg passed to Tk_RestrictEvents; it
       may be used to provide proc with	information it needs to	filter events.
       The  eventPtr  points  to an event under	consideration.	Proc returns a
       restrict	action (enumerated type	Tk_RestrictAction) that	indicates what
       Tcl_DoOneEvent  should  do  with	 the  event.   If  the return value is
       TK_PROCESS_EVENT, then the event	will be	handled	immediately.   If  the
       return  value  is  TK_DEFER_EVENT,  then	 the event will	be left	on the
       event queue for later processing.   If  the  return  value  is  TK_DIS-
       CARD_EVENT,  then  the  event  will be removed from the event queue and
       discarded without being processed.

       Tk_RestrictEvents uses its return value and prevArgPtr to return	infor-
       mation  about  the  current  event restriction procedure	(a NULL	return
       value means there are currently no restrictions).  These	values may  be
       used  to	restore	the previous restriction state when there is no	longer
       any need	for the	current	restriction.

       There are very few places where Tk_RestrictEvents is needed.   In  most
       cases, the best way to restrict events is by changing the bindings with
       the bind	Tcl command or by calling Tk_CreateEventHandler	 and  Tk_Dele-
       teEventHandler  from C.	The main place where Tk_RestrictEvents must be
       used is when performing synchronous actions (for	example, if  you  need
       to  wait	for a particular event to occur	on a particular	window but you
       do not want to invoke any handlers for any other	events).   The	"obvi-
       ous"  solution  in  these  situations is	to call	XNextEvent or XWindow-
       Event, but these	procedures cannot be used because  Tk  keeps  its  own
       event  queue  that  is  separate	from the X event queue.	 Instead, call
       Tk_RestrictEvents to set	up a filter, then call Tcl_DoOneEvent  to  re-
       trieve the desired event(s).

       delay, event, filter, restriction

Tk							  Tk_RestrictEvents(3)


Want to link to this manual page? Use this URL:

home | help