TkCreateBindingTable(3) Tk Library Procedures TkCreateBindingTable(3)

NAME
       TkCreateBindingTable,     TkDeleteBindingTable,     TkCreateBinding,
       TkDeleteBinding, TkGetBinding,  TkGetAllBindings,  TkDeleteAllBind-
       ings, TkBindEvent - invoke scripts in response to X events

SYNOPSIS
       ##iinncclluuddee <>

       TkBindingTable
       TTkkCCrreeaatteeBBiinnddiinnggTTaabbllee((interp))

       TTkkDDeelleetteeBBiinnddiinnggTTaabbllee((bindingTable))

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

       int
       TTkkDDeelleetteeBBiinnddiinngg((interp, bindingTable, object, eventString))

       CONST char *
       TTkkGGeettBBiinnddiinngg((interp, bindingTable, object, eventString))

       TTkkGGeettAAllllBBiinnddiinnggss((interp, bindingTable, object))

       TTkkDDeelleetteeAAllllBBiinnddiinnggss((bindingTable, object))

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

AARRGGUUMMEENNTTSS
       TclInterp        *interp        (in)      Interpreter   to   use  when
                                                  invoking bindings in binding
                                                  table.     Also   used   for
                                                  returning results and errors
                                                  from binding procedures.

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

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

       CONST char        *eventString   (in)      String    describing   event
                                                  sequence.

       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
                                                  replace existing script with
                                                  new one.

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

       TkWindow         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.



DESCRIPTION
       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 bbiinndd command.  For this table, objects are
       pointers to strings such as window names, class names, or other binding
       tags such as aallll.  Tk also keeps a separate binding table for each can-
       vas widget, which manages bindings created by the canvas's bbiinndd  widget
       command;   within  this  table,  an  object  is either a pointer to the
       internal structure for a canvas item or a TkUid identifying a tag.

       The procedure TTkkCCrreeaatteeBBiinnddiinnggTTaabbllee 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).  TTkkCCrreeaatteeBBiinnddiinnggTTaabbllee returns  a
       token  for  the  table, which must be used in calls to other procedures
       such as TTkkCCrreeaatteeBBiinnddiinngg or TTkkBBiinnddEEvveenntt.

       TTkkDDeelleetteeBBiinnddiinnggTTaabbllee frees all of the state associated with a  binding
       table.   Once  it  returns  the  caller should not use the bindingTable
       token again.

       TTkkCCrreeaatteeBBiinnddiinngg 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  bbiinndd  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.
       TTkkCCrreeaatteeBBiinnddiinngg returns an X event mask for all the events  associated
       with the bindings.  This information may be useful to invoke XXSSeelleeccttIInn-
       ppuutt 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.

       TTkkDDeelleetteeBBiinnddiinngg  removes from bindingTable the binding given by object
       and eventString, if such a  binding  exists.   TTkkDDeelleetteeBBiinnddiinngg  always
       returns  TCLOK.   In  some  cases  it  may reset interp->result to the
       default empty value.

       TTkkGGeettBBiinnddiinngg  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.

       TTkkGGeettAAllllBBiinnddiinnggss 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.

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

       TTkkBBiinnddEEvveenntt 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.   TTkkBBiinnddEEvveenntt  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
       described in the documentation for bbiinndd, and  invokes  the  script  for
       that  binding.   If  there  are  no  matching bindings for a particular
       object, then the object is skipped.  TTkkBBiinnddEEvveenntt continues through all
       of the objects, handling exceptions such as errors, bbrreeaakk, and ccoonnttiinnuuee
       as described in the documentation for bbiinndd.


KKEEYYWWOORRDDSS
       binding, event, object, script



Tk                                    4.0             TkCreateBindingTable(3)