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

FreeBSD Manual Pages


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


       Tk_CreateBindingTable,	  Tk_DeleteBindingTable,     Tk_CreateBinding,
       Tk_DeleteBinding, Tk_GetBinding,	 Tk_GetAllBindings,  Tk_DeleteAllBind-
       ings, Tk_BindEvent - invoke scripts in response to X events

       #include	<tk.h>



       unsigned	long
       Tk_CreateBinding(interp,	bindingTable, object, eventString, script, append)

       Tk_DeleteBinding(interp,	bindingTable, object, eventString)

       const char *
       Tk_GetBinding(interp, bindingTable, object, eventString)

       Tk_GetAllBindings(interp, bindingTable, object)

       Tk_DeleteAllBindings(bindingTable, object)

       Tk_BindEvent(bindingTable, eventPtr, tkwin, numObjects, objectPtr)

       Tcl_Interp *interp (in)			  Interpreter  to use when in-
						  voking bindings  in  binding
						  table.   Also	 used  for re-
						  turning results  and	errors
						  from binding procedures.

       Tk_BindingTable bindingTable (in)	  Token	  for  binding	table;
						  must have been  returned  by
						  some	  previous   call   to

       ClientData object (in)			  Identifies object with which
						  binding is associated.

       const char *eventString (in)		  String  describing event se-

       char *script (in)			  Tcl script  to  invoke  when
						  binding triggers.

       int append (in)				  Non-zero means append	script
						  to existing script for bind-
						  ing,	if any;	zero means re-
						  place	existing  script  with
						  new one.

       XEvent *eventPtr	(in)			  X  event  to	match  against
						  bindings in bindingTable.

       Tk_Window tkwin (in)			  Identifier for any window on
						  the  display where the event
						  occurred.  Used to find dis-
						  play-related	   information
						  such as key maps.

       int numObjects (in)			  Number of object identifiers
						  pointed to by	objectPtr.

       ClientData *objectPtr (in)		  Points to an array of	object
						  identifiers:	bindings  will
						  be  considered  for  each of
						  these	objects	in order  from
						  first	to last.

       These  procedures  provide a general-purpose mechanism for creating and
       invoking	bindings.  Bindings are	organized in terms of binding  tables.
       A  binding table	consists of a collection of bindings plus a history of
       recent events.  Within a	binding	table, bindings	 are  associated  with
       objects.	 The meaning of	an object is defined by	clients	of the binding
       package.	 For example, Tk keeps uses one	binding	table to hold  all  of
       the  bindings created by	the bind command.  For this table, objects are
       pointers	to strings such	as window names, class names, or other binding
       tags such as all.  Tk also keeps	a separate binding table for each can-
       vas widget, which manages bindings created by the canvas's bind	widget
       command;	  within  this table, an object	is either a pointer to the in-
       ternal structure	for a canvas item or a Tk_Uid identifying a tag.

       The procedure Tk_CreateBindingTable creates a new binding table and as-
       sociates	 interp	 with  it (when	bindings in the	table are invoked, the
       scripts will be evaluated in interp).  Tk_CreateBindingTable returns  a
       token  for  the	table, which must be used in calls to other procedures
       such as Tk_CreateBinding	or Tk_BindEvent.

       Tk_DeleteBindingTable frees all of the state associated with a  binding
       table.	Once it	returns	the caller should not use the bindingTable to-
       ken again.

       Tk_CreateBinding	adds a new binding to an existing table.   The	object
       argument	 identifies the	object with which the binding is to be associ-
       ated, and it may	be any one-word	value.	Typically it is	a pointer to a
       string  or  data	 structure.   The  eventString argument	identifies the
       event or	sequence of events for the binding;  see the documentation for
       the  bind  command  for a description of	its format.  script is the Tcl
       script to be evaluated when the	binding	 triggers.   append  indicates
       what   to  do  if  there	 already  exists  a  binding  for  object  and
       eventString:  if	append is zero then script replaces  the  old  script;
       if  append  is non-zero then the	new script is appended to the old one.
       Tk_CreateBinding	returns	an X event mask	for all	the events  associated
       with the	bindings.  This	information may	be useful to invoke XSelectIn-
       put to select relevant events, or to disallow the use of	certain	events
       in  bindings.   If  an error occurred while creating the	binding	(e.g.,
       eventString refers to a non-existent event), then 0 is returned and  an
       error message is	left in	interp-_result.

       Tk_DeleteBinding	 removes from bindingTable the binding given by	object
       and eventString,	if such	a binding exists.  Tk_DeleteBinding always re-
       turns TCL_OK.  In some cases it may reset interp-_result	to the default
       empty value.

       Tk_GetBinding  returns  a  pointer  to  the  script   associated	  with
       eventString and object in bindingTable.	If no such binding exists then
       NULL is returned	and an error message is	left in	interp-_result.

       Tk_GetAllBindings returns in interp-_result a list  of  all  the	 event
       strings	for  which  there are bindings in bindingTable associated with
       object.	If there are no	bindings for object then an  empty  string  is
       returned	in interp-_result.

       Tk_DeleteAllBindings  deletes  all of the bindings in bindingTable that
       are associated with object.

       Tk_BindEvent is called to process an event.  It makes  a	 copy  of  the
       event  in  an  internal history list associated with the	binding	table,
       then it checks for bindings that	match the  event.   Tk_BindEvent  pro-
       cesses  each  of	the objects pointed to by objectPtr in turn.  For each
       object, it finds	all the	bindings that match the	current	event history,
       selects	the  most  specific  binding  using the	priority mechanism de-
       scribed in the documentation for	bind, and invokes the script for  that
       binding.	  If  there  are no matching bindings for a particular object,
       then the	object is skipped.  Tk_BindEvent continues through all of  the
       objects,	handling exceptions such as errors, break, and continue	as de-
       scribed in the documentation for	bind.

       binding,	event, object, script

Tk				      4.0	      Tk_CreateBindingTable(3)


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

home | help