


event(n)              STk Built-In Commands              event(n)


NAME
       event  - Miscellaneous event facilities: define virtual events and gen-
       erate events

SYNOPSIS
       event option ?arg arg ...?


DESCRIPTION
       The event procedure provides several facilities for dealing with window
       system events, such as defining virtual events and synthesizing events.
       The procedure has several different  forms,  determined  by  the  first
       argument.  The following forms are currently supported:

       (event 'add "<<virtual>>" sequence ?sequence ...?)
              Associates  the  virtual  event  virtual with the physical event
              sequence(s) given by the sequence arguments, so that the virtual
              event  will  trigger  whenever  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 procedure.
              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 procedure.   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 virtual 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 a window identifier (such as returned  by  (winfo
              'id))  as long as it is for a window in the current application.
              Event provides a basic description of  will  be  generated,  and
              event  provides  a  basic  description  of  the  event,  such as
              "<Shift-Button-2>" or "<<Paste>>".  Event may have  any  of  the
              forms  allowed  for  the sequence argument of the bind procedure
              except that it must consist of a single  event  pattern,  not  a
              sequence.   Option-value pairs may be used to specify additional
              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 processed immediately:  all of the handlers for the
              event will complete before the event generate procedure returns.
              If the :when option is specified then  it  determines  when  the
              event is processed.

       (event 'info)





STk                            4.0                              1





event(n)              STk Built-In Commands              event(n)


       (event 'info "<<virtual>>")
              Returns  information about virtual events.  If the "<<virtual>>"
              argument is omitted, the return value is a list of all the  vir-
              tual  events  that  are  currently 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  list
              is returned.


EVENT FIELDS
       The  following  options are supported for the event generate procedure.
       These correspond to the character names allowed in binding scripts  for
       the bind procedure.

       :above window
              Window specifies the above field for the event, either as a win-
              dow path name or as an integer window 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 Configure 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  num-
              ber 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 substitu-
              tion 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



STk                            4.0                              2





event(n)              STk Built-In Commands              event(n)


              h substitution for binding scripts.

       :keycode number
              Number   must be an integer;  it specifies the keycode field for
              the event.  Valid for KeyPress and  KeyRelease  events.   Corre-
              sponds to the k substitution 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.
              Corresponds to the K substitution for binding scripts.

       :mode notify
              Notify specifies the mode field for the event and must be one of
              NotifyNormal, NotifyGrab, NotifyUngrab,  or  NotifyWhileGrabbed.
              Valid  for  Enter,  Leave, FocusIn, and FocusOut events.  Corre-
              sponds to the m substitution for binding scripts.

       :override boolean
              Boolean must  be  a  boolean  value;   it  specifies  the  over-
              ride_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 substitution 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,  KeyRelease,  ButtonPress,  ButtonRelease, Enter,
              Leave, and Motion events.  Corresponds to the R substitution 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.



STk                            4.0                              3





event(n)              STk Built-In Commands              event(n)


       :serial number
              Number  must  be  an integer;  it specifies the serial field for
              the event.  Valid for all events.  Corresponds to the #  substi-
              tution 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 integer value.  For Visibility events it
              must  be  one  of  VisibilityUnobscured,  VisibilityPartiallyOb-
              scured,  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 substitution  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.  Cor-
              responds to the t substitution for binding scripts.

       :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 procedure
                        returns.  This also happens if  the  :when  option  is
                        omitted.

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

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

              mark      Place the event at the front of STk'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.





STk                            4.0                              4





event(n)              STk Built-In Commands              event(n)


       :x coord
              Coord must be a screen distance;  it specifies the x  field  for
              the event.  Valid for KeyPress, KeyRelease, ButtonPress, Button-
              Release, Motion, Enter, Leave, Expose, Configure,  Gravity,  and
              Reparent  events.   Corresponds  to  the  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, KeyRelease, ButtonPress, Button-
              Release, Motion, Enter, Leave, Expose, Configure,  Gravity,  and
              Reparent  events.   Corresponds  to  the  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  hap-
       pen.   First, the virtual event must be defined with the event add pro-
       cedure.  Second, a binding must be created for the virtual  event  with
       the  bind procedure.  Consider the following virtual event definitions:
       (event 'add "<<Paste>>" "<Control-y>") (event 'add  "<<Paste>>"  "<But-
       ton-2>")  (event 'add "<<Save>>"  "<Control-X><Control-S>") (event 'add
       "<<Save>>"  "<Shift-F12>") In the bind procedure, a virtual  event  can
       be  bound  like  any other builtin event type as follows: (bind "Entry"
       "<<Paste>>" (lambda (|W|)
                                    (|W| 'insert [selection 'get]))) The  dou-
       ble  angle  brackets  are used to specify that a virtual event is being
       bound.  If the user types Control-y  or  presses  button  2,  or  if  a
       <<Paste>>  virtual  event  is synthesized with event generate, then the
       <<Paste>> binding will be invoked.

       If a virtual binding has the exact same sequence as a separate physical
       binding,  then the physical binding will take precedence.  Consider the
       following example: (event 'add  "<<Paste>>"  "<Control-y>"  "<Meta-Con-
       trol-y>")  (bind  "Entry"  "<Control-y>"  (lambda () (display "Control-
       y0))) (bind "Entry" "<<Paste>>"   (lambda () (display  "Paste0)))  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
       modifier 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  virtual  event
       exists.   Indeed, the virtual event never actually needs to be defined,
       for instance, on platforms where the specific virtual event would mean-
       ingless or ungeneratable.

       When  a  definition of a virtual event changes at run time, all windows
       will respond immediately to the  new  definition.   Starting  from  the



STk                            4.0                              5





event(n)              STk Built-In Commands              event(n)


       preceding  example,  if the following 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>  bind-
       ing,  but instead invoke the virtual event <<Paste>>.  Second, pressing
       the F6 key will now also invoke the <<Paste>> binding.


SEE ALSO
       bind















































STk                            4.0                              6


