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

FreeBSD Manual Pages

  
 
  

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

______________________________________________________________________________

NAME
       Tk_RestrictEvents - filter and selectively delay	X events

SYNOPSIS
       #include	<tk.h>

       Tk_RestrictProc *
       Tk_RestrictEvents(proc, clientData, prevClientDataPtr)

ARGUMENTS
       Tk_RestrictProc *proc (in)			 Predicate   procedure
							 to call to filter in-
							 coming	   X   events.
							 NULL means do not re-
							 strict	events at all.

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

       ClientData *prevClientDataPtr (out)		 Pointer to  place  to
							 save argument to pre-
							 vious restrict	proce-
							 dure.
______________________________________________________________________________

DESCRIPTION
       This  procedure	is useful in certain situations	where applications are
       only prepared to	receive	certain	X events.  After Tk_RestrictEvents  is
       called,	Tk_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 clientData,
		  XEvent *eventPtr);
       The  clientData	argument  is a copy of the clientData passed to	Tk_Re-
       strictEvents; 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	Tk_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 prevClientDataPtr to	return
       information  about  the current event restriction procedure (a NULL re-
       turn 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	Tk_DoOneEvent  to  re-
       trieve the desired event(s).

KEYWORDS
       delay, event, filter, restriction

Tk							  Tk_RestrictEvents(3)

NAME | SYNOPSIS | ARGUMENTS | DESCRIPTION | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk_RestrictEvents.tk85&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help