NAME
       event  -  Miscellaneous  event  facilities: define virtual
       events and generate events

SYNOPSIS
       event option ?arg arg ...?


DESCRIPTION
       The event command provides several facilities for  dealing
       with window system events, such as defining virtual events
       and synthesizing events.  The command has several  differ-
       ent  forms, determined by the first argument.  The follow-
       ing forms are currently supported:

       event add <<virtual>> sequence ?sequence ...?
              Associates the virtual event virtual with the phys-
              ical  event sequence(s) given by the sequence argu-
              ments, so that the virtual event will trigger when-
              ever  any one of the sequences occurs.  Virtual may
              be any string value and sequence may  have  any  of
              the values allowed for the sequence argument to the
              bind command.  If virtual is already  defined,  the
              new  physical  event  sequences add to the existing
              sequences for the event.

       event delete <<virtual>> ?sequence sequence ...?
              Deletes each of the sequences from those associated
              with  the  virtual event given by virtual.  Virtual
              may be any string value and sequence may  have  any
              of  the values allowed for the sequence argument to
              the bind  command.   Any  sequences  not  currently
              associated   with   virtual  are  ignored.   If  no
              sequence argument is provided, all  physical  event
              sequences are removed for virtual, so that the vir-
              tual event will not trigger anymore.

       event generate window event ?option value option value
       ...?
              Generates  a window event and arranges for it to be
              processed just as if it had come  from  the  window
              system.   Window  gives the path name of the window
              for which the event will be generated; it may  also
              be  an identifier (such as returned by winfo id) as
              long as it is for a window in the current  applica-
              tion.   Event  provides  a basic description of the
              event, such as <Shift-Button-2> or  <<Paste>>.   If
              Window  is  empty  the  whole  screen is meant, and
              coordinates are relative to the screen.  Event  may
              have  any  of  the  forms  allowed for the sequence
              argument of the bind command except  that  it  must
              consist  of a single event pattern, not a sequence.
              Option-value pairs may be  used  to  specify  addi-
              tional attributes of the event, such as the x and y
              mouse position;  see EVENT FIELDS  below.   If  the
              -when  option  is  not specified, the event is pro-
              cessed immediately:  all of the  handlers  for  the
              event  will complete before the event generate com-
              mand returns.  If the  -when  option  is  specified
              then  it  determines  when  the event is processed.
              Certain events, such as key  events,  require  that
              the window has focus to receive the event properly.

       event info ?<<virtual>>?
              Returns information about virtual events.   If  the
              <<virtual>>  argument  is omitted, the return value
              is a list of all the virtual events that  are  cur-
              rently  defined.   If <<virtual>> is specified then
              the return value is a list whose elements  are  the
              physical  event sequences currently defined for the
              given virtual event;  if the virtual event  is  not
              defined then an empty string is returned.


EVENT FIELDS
       The following options are supported for the event generate
       command.  These correspond to the ``%'' expansions allowed
       in binding scripts for the bind command.

       -above window
              Window  specifies  the  above  field for the event,
              either as a window path name or as an integer  win-
              dow  id.   Valid for Configure events.  Corresponds
              to the %a substitution for binding scripts.

       -borderwidth size
              Size must be a screen distance;  it  specifies  the
              border_width  field  for the event.  Valid for Con-
              figure events.  Corresponds to the %B  substitution
              for binding scripts.

       -button number
              Number must be an integer;  it specifies the detail
              field for a  ButtonPress  or  ButtonRelease  event,
              overriding  any button  number provided in the base
              event argument.  Corresponds to the %b substitution
              for binding scripts.

       -count number
              Number  must be an integer;  it specifies the count
              field for the  event.   Valid  for  Expose  events.
              Corresponds  to  the  %c  substitution  for binding
              scripts.

       -delta number
              Number must be an integer;  it specifies the  delta
              field  for  the MouseWheel event.  The delta refers
              to the direction and magnitude the mouse wheel  was
              rotated.   Note  the value is not a screen distance
              but are units of motion in the mouse wheel.   Typi-
              cally these values are multiples of 120.  For exam-
              ple, 120 should scroll the text widget up  4  lines
              and -240 would scroll the text widget down 8 lines.
              Of  course,  other  widgets  may  define  different
              behaviors  for mouse wheel motion.  This field cor-
              responds  to  the  %D  substitution   for   binding
              scripts.

       -detail detail
              Detail specifies the detail field for the event and
              must be one of the following:

                     NotifyAncestor          NotifyNonlinearVirtual
                     NotifyDetailNone        NotifyPointer
                     NotifyInferior          NotifyPointerRoot
                     NotifyNonlinear         NotifyVirtual

              Valid  for  Enter,  Leave,  FocusIn  and   FocusOut
              events.   Corresponds  to  the  %d substitution for
              binding scripts.

       -focus boolean
              Boolean must be a boolean value;  it specifies  the
              focus  field  for  the  event.  Valid for Enter and
              Leave events.  Corresponds to the  %f  substitution
              for binding scripts.

       -height size
              Size  must  be a screen distance;  it specifies the
              height field for the event.   Valid  for  Configure
              events.   Corresponds  to  the  %h substitution for
              binding scripts.

       -keycode number
              Number  must be an integer;  it specifies the  key-
              code  field  for the event.  Valid for KeyPress and
              KeyRelease events.  Corresponds to the %k substitu-
              tion for binding scripts.

       -keysym name
              Name must be the name of a valid keysym, such as g,
              space, or Return;  its corresponding keycode  value
              is  used as the keycode field for event, overriding
              any detail specified in the  base  event  argument.
              Valid  for  KeyPress and KeyRelease events.  Corre-
              sponds to the %K substitution for binding  scripts.

       -mode notify
              Notify  specifies  the mode field for the event and
              must be one of NotifyNormal, NotifyGrab,  NotifyUn-
              grab,  or  NotifyWhileGrabbed.   Valid  for  Enter,
              Leave, FocusIn, and FocusOut  events.   Corresponds
              to the %m substitution for binding scripts.

       -override boolean
              Boolean  must be a boolean value;  it specifies the
              override_redirect field for the event.   Valid  for
              Map,  Reparent,  and Configure events.  Corresponds
              to the %o substitution for binding scripts.

       -place where
              Where specifies the place field for the event;   it
              must  be either PlaceOnTop or PlaceOnBottom.  Valid
              for Circulate events.  Corresponds to the  %p  sub-
              stitution for binding scripts.

       -root window
              Window  must  be  either  a  window path name or an
              integer window identifier;  it specifies  the  root
              field  for  the  event.  Valid for KeyPress, KeyRe-
              lease, ButtonPress,  ButtonRelease,  Enter,  Leave,
              and Motion events.  Corresponds to the %R substitu-
              tion for binding scripts.

       -rootx coord
              Coord must be a screen distance;  it specifies  the
              x_root  field  for  the event.  Valid for KeyPress,
              KeyRelease,  ButtonPress,   ButtonRelease,   Enter,
              Leave,  and  Motion  events.  Corresponds to the %X
              substitution for binding scripts.

       -rooty coord
              Coord must be a screen distance;  it  specifies  th
              y_root  field  for  the event.  Valid for KeyPress,
              KeyRelease,  ButtonPress,   ButtonRelease,   Enter,
              Leave,  and  Motion  events.  Corresponds to the %Y
              substitution for binding scripts.

       -sendevent boolean
              Boolean must be a boolean value;  it specifies  the
              send_event  field  for  the  event.   Valid for all
              events.  Corresponds to  the  %E  substitution  for
              binding scripts.

       -serial number
              Number must be an integer;  it specifies the serial
              field for the event.  Valid for all events.  Corre-
              sponds  to the %# substitution for binding scripts.

       -state state
              State specifies the state field for the event.  For
              KeyPress,  KeyRelease,  ButtonPress, ButtonRelease,
              Enter, Leave, and Motion events it must be an inte-
              ger value.  For Visibility events it must be one of
              VisibilityUnobscured,  VisibilityPartiallyObscured,
              or  VisibilityFullyObscured.  This option overrides
              any modifiers such as Meta or Control specified  in
              the base event.  Corresponds to the %s substitution
              for binding scripts.

       -subwindow window
              Window specifies the subwindow field for the event,
              either  as  a  path  name  for a Tk widget or as an
              integer window  identifier.   Valid  for  KeyPress,
              KeyRelease,   ButtonPress,   ButtonRelease,  Enter,
              Leave, and Motion events.  Similar to %S  substitu-
              tion for binding scripts.

       -time integer
              Integer must be an integer value;  it specifies the
              time field for  the  event.   Valid  for  KeyPress,
              KeyRelease,   ButtonPress,   ButtonRelease,  Enter,
              Leave, Motion, and Property events.  Corresponds to
              the %t substitution for binding scripts.

       -warp boolean
              boolean  must  be  a  boolean  value;  it specifies
              whether the screen  pointer  should  be  warped  as
              well.  Valid for KeyPress, KeyRelease, ButtonPress,
              ButtonRelease, and Motion events.  The pointer will
              only warp to a window if it is mapped.

       -width size
              Size  must  be a screen distance;  it specifies the
              width field for the  event.   Valid  for  Configure
              events.   Corresponds  to  the  %w substitution for
              binding scripts.

       -when when
              When determines when the event will  be  processed;
              it must have one of the following values:

              now       Process the event immediately, before the
                        command returns.  This  also  happens  if
                        the -when option is omitted.

              tail      Place  the  event  on  Tcl's  event queue
                        behind any events already queued for this
                        application.

              head      Place  the  event  at  the front of Tcl's
                        event queue, so that it will  be  handled
                        before any other events already queued.

              mark      Place  the  event  at  the front of Tcl's
                        event queue but behind any  other  events
                        already  queued  with  -when  mark.  This
                        option is useful when generating a series
                        of  events  that  should  be processed in
                        order but at the front of the queue.
       -x coord
              Coord must be a screen distance;  it specifies  the
              x  field for the event.  Valid for KeyPress, KeyRe-
              lease, ButtonPress, ButtonRelease,  Motion,  Enter,
              Leave,  Expose,  Configure,  Gravity,  and Reparent
              events.  Corresponds to the the %x substitution for
              binding scripts.  If Window is empty the coordinate
              is relative to the screen, and this  option  corre-
              sponds  to the %X substitution for binding scripts.

       -y coord
              Coord must be a screen distance;  it specifies  the
              y  field for the event.  Valid for KeyPress, KeyRe-
              lease, ButtonPress, ButtonRelease,  Motion,  Enter,
              Leave,  Expose,  Configure,  Gravity,  and Reparent
              events.  Corresponds to the the %y substitution for
              binding scripts.  If Window is empty the coordinate
              is relative to the screen, and this  option  corre-
              sponds  to the %Y substitution for binding scripts.

       Any options that are  not  specified  when  generating  an
       event  are  filled  with  the  value 0, except for serial,
       which is filled with the next X event serial number.


VIRTUAL EVENT EXAMPLES
       In order for a  virtual  event  binding  to  trigger,  two
       things  must  happen.   First,  the  virtual event must be
       defined with the event add  command.   Second,  a  binding
       must  be  created for the virtual event with the bind com-
       mand.  Consider the following virtual event definitions:
              event add <<Paste>> <Control-y>
              event add <<Paste>> <Button-2>
              event add <<Save>> <Control-X><Control-S>
              event add <<Save>> <Shift-F12>
       In the bind command, a virtual event can be bound like any
       other builtin event type as follows:
              bind Entry <<Paste>> {%W insert [selection get]}
       The  double angle brackets are used to specify that a vir-
       tual event is being bound.  If the user types Control-y or
       presses  button 2, or if a <<Paste>> virtual event is syn-
       thesized with event generate, then the  <<Paste>>  binding
       will be invoked.

       If a virtual binding has the exact same sequence as a sep-
       arate physical binding, then  the  physical  binding  will
       take precedence.  Consider the following example:
              event add <<Paste>> <Control-y> <Meta-Control-y>
              bind Entry <Control-y> {puts Control-y}
              bind Entry <<Paste>> {puts Paste}
       When the user types Control-y the <Control-y> binding will
       be invoked, because a physical event  is  considered  more
       specific  than  a  virtual  event,  all other things being
       equal.  However, when the user  types  Meta-Control-y  the
       <<Paste>>  binding will be invoked, because the Meta modi-
       fier in the physical pattern associated with  the  virtual
       binding is more specific than the <Control-y> sequence for
       the physical event.

       Bindings on a virtual event may be created before the vir-
       tual  event exists.  Indeed, the virtual event never actu-
       ally needs to be defined, for instance, on platforms where
       the specific virtual event would meaningless or ungenerat-
       able.

       When a definition of a virtual event changes at run  time,
       all  windows  will  respond immediately to the new defini-
       tion.  Starting from the preceding example, if the follow-
       ing code is executed:
              bind <Entry> <Control-y> {}
              event add <<Paste>> <Key-F6>
       the  behavior  will  change  such in two ways.  First, the
       shadowed <<Paste>> binding will emerge.  Typing  Control-y
       will no longer invoke the <Control-y> binding, but instead
       invoke the virtual event <<Paste>>.  Second, pressing  the
       F6 key will now also invoke the <<Paste>> binding.


SEE ALSO
       bind


KEYWORDS
       event, binding, define, handle, virtual event
