326 lines
16 KiB
HTML
326 lines
16 KiB
HTML
<HTML><HEAD><TITLE>STk Built-In Commands - event manual page</TITLE></HEAD>
|
||
<BR>
|
||
<BODY bgcolor = #c3c3ff>
|
||
<H2><IMG ALIGN=BOTTOM SRC="./Img/ManPageBlue.gif"> event</H2>
|
||
<I>Miscellaneous event facilities: define virtual events and generate events</I><P><IMG ALIGN=TOP SRC="./Img/line-red.gif">
|
||
<H3><A NAME="M2">SYNOPSIS</A></H3>
|
||
<B>event</B><I> option </I>?<I>arg arg ...</I>?<BR>
|
||
<H3><A NAME="M3">DESCRIPTION</A></H3>
|
||
The <B>event</B> 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:
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M4">(<B>event 'add {"<<</B><I>virtual</I><B>>>"</B><I>} sequence </I>?<I>sequence ...</I>?)</A><DD>
|
||
Associates the virtual event <I>virtual</I> with the physical
|
||
event sequence(s) given by the <I>sequence</I> arguments, so that
|
||
the virtual event will trigger whenever any one of the <I>sequence</I>s
|
||
occurs.
|
||
<I>Virtual</I> may be any string value and <I>sequence</I> may have
|
||
any of the values allowed for the <I>sequence</I> argument to the
|
||
<B><A HREF="./bind.n.html">bind</A></B> procedure.
|
||
If <I>virtual</I> is already defined, the new physical event sequences
|
||
add to the existing sequences for the event.
|
||
<P>
|
||
<DT><A NAME="M5">(<B>event 'delete {"<<</B><I>virtual</I><B>>>"} </B>?<I>sequence</I> <I>sequence ...</I>?)</A><DD>
|
||
Deletes each of the <I>sequence</I>s from those associated with
|
||
the virtual event given by <I>virtual</I>.
|
||
<I>Virtual</I> may be any string value and <I>sequence</I> may have
|
||
any of the values allowed for the <I>sequence</I> argument to the
|
||
<B><A HREF="./bind.n.html">bind</A></B> procedure.
|
||
Any <I>sequence</I>s not currently associated with <I>virtual</I>
|
||
are ignored.
|
||
If no <I>sequence</I> argument is provided, all physical event sequences
|
||
are removed for <I>virtual</I>, so that the virtual event will not
|
||
trigger anymore.
|
||
<P>
|
||
<DT><A NAME="M6">(<B>event 'generate </B><I>window event </I>?<I>option value option value ...</I>?)</A><DD>
|
||
Generates a window event and arranges for it to be processed just as if
|
||
it had come from the window system.
|
||
<I>Window</I> 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
|
||
(<B>winfo 'id</B>)) as long as it is for a window in the current application.
|
||
<I>Event</I> provides a basic description of
|
||
will be generated, and <I>event</I> provides a basic description of
|
||
the event, such as "<B><Shift-Button-2></B>" or "<B><<Paste>></B>".
|
||
<I>Event</I> may have any of the forms allowed for the <I>sequence</I>
|
||
argument of the <B><A HREF="./bind.n.html">bind</A></B> procedure except that it must consist
|
||
of a single event pattern, not a sequence.
|
||
<I>Option-value</I> 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 <B>:when</B> option is not specified, the
|
||
event is processed immediately: all of the handlers for the event
|
||
will complete before the <B>event generate</B> procedure returns.
|
||
If the <B>:when</B> option is specified then it determines when the
|
||
event is processed.
|
||
<P>
|
||
<DT><A NAME="M7">{( Bevent} 'info)</A><DD>
|
||
<DT><A NAME="M8">(<B>event 'info {</B>"<<<I>virtual</I><B>>>"</B>)}</A><DD>
|
||
Returns information about virtual events.
|
||
If the "<B><<</B><I>virtual</I><B>>></B>" argument is omitted, the return value
|
||
is a list of all the virtual events that are currently defined.
|
||
If "<B><<</B><I>virtual</I><B>>></B>" 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.
|
||
|
||
<P>
|
||
</DL>
|
||
<H3><A NAME="M9">EVENT FIELDS</A></H3>
|
||
The following options are supported for the <B>event generate</B>
|
||
procedure. These correspond to the character names
|
||
allowed in binding scripts for the <B><A HREF="./bind.n.html">bind</A></B> procedure.
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M10"><B>:above</B><I> window</I></A><DD>
|
||
<I>Window</I> specifies the <I>above</I> field for the event,
|
||
either as a window path name or as an integer window id.
|
||
Valid for <B>Configure</B> events.
|
||
Corresponds to the <B>a</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M11"><B>:borderwidth</B><I> size</I></A><DD>
|
||
<I>Size</I> must be a screen distance; it specifies the
|
||
<I>border_width</I> field for the event.
|
||
Valid for <B>Configure</B> events.
|
||
Corresponds to the <B>B</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M12"><B>:button</B><I> number</I></A><DD>
|
||
<I>Number</I> must be an integer; it specifies the <I>detail</I> field
|
||
for a <B>ButtonPress</B> or <B>ButtonRelease</B> event, overriding
|
||
any button number provided in the base <I>event</I> argument.
|
||
Corresponds to the <B>b</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M13"><B>:count</B><I> number</I></A><DD>
|
||
<I>Number</I> must be an integer; it specifies the <I>count</I> field
|
||
for the event. Valid for <B>Expose</B> events.
|
||
Corresponds to the <B>c</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M14"><B>:detail</B><I> detail</I></A><DD>
|
||
<I>Detail</I> specifies the <I>detail</I> field for the event
|
||
and must be one of the following:
|
||
<P>
|
||
<UL>
|
||
<PRE><B>NotifyAncestor NotifyNonlinearVirtual
|
||
NotifyDetailNone NotifyPointer
|
||
NotifyInferior NotifyPointerRoot
|
||
NotifyNonlinear NotifyVirtual</B></PRE>
|
||
Valid for <B>Enter</B>, <B>Leave</B>, <B>FocusIn</B> and
|
||
<B>FocusOut</B> events.
|
||
Corresponds to the <B>d</B> substitution for binding scripts.
|
||
</UL>
|
||
<DT><A NAME="M15"><B>:focus</B><I> boolean</I></A><DD>
|
||
<I>Boolean</I> must be a boolean value; it specifies the <I>focus</I>
|
||
field for the event.
|
||
Valid for <B>Enter</B> and <B>Leave</B> events.
|
||
Corresponds to the <B>f</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M16"><B>:height</B><I> size</I></A><DD>
|
||
<I>Size</I> must be a screen distance; it specifies the <I>height</I>
|
||
field for the event. Valid for <B>Configure</B> events.
|
||
Corresponds to the <B>h</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M17"><B>:keycode</B><I> number</I></A><DD>
|
||
<I>Number</I> must be an integer; it specifies the <I>keycode</I>
|
||
field for the event.
|
||
Valid for <B>KeyPress</B> and <B>KeyRelease</B> events.
|
||
Corresponds to the <B>k</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M18"><B>:keysym</B><I> name</I></A><DD>
|
||
<I>Name</I> must be the name of a valid keysym, such as "<B>g</B>",
|
||
"<B>space</B>", or "<B>Return</B>"; its corresponding
|
||
keycode value is used as the <I>keycode</I> field for event, overriding
|
||
any detail specified in the base <I>event</I> argument.
|
||
Valid for <B>KeyPress</B> and <B>KeyRelease</B> events.
|
||
Corresponds to the <B>K</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M19"><B>:mode</B><I> notify</I></A><DD>
|
||
<I>Notify</I> specifies the <I>mode</I> field for the event and must be
|
||
one of <B>NotifyNormal</B>, <B>NotifyGrab</B>, <B>NotifyUngrab</B>, or
|
||
<B>NotifyWhileGrabbed</B>.
|
||
Valid for <B>Enter</B>, <B>Leave</B>, <B>FocusIn</B>, and
|
||
<B>FocusOut</B> events.
|
||
Corresponds to the <B>m</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M20"><B>:override</B><I> boolean</I></A><DD>
|
||
<I>Boolean</I> must be a boolean value; it specifies the
|
||
<I>override_redirect</I> field for the event.
|
||
Valid for <B>Map</B>, <B>Reparent</B>, and <B>Configure</B> events.
|
||
Corresponds to the <B>o</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M21"><B>:place</B><I> where</I></A><DD>
|
||
<I>Where</I> specifies the <I>place</I> field for the event; it must be
|
||
either <B>PlaceOnTop</B> or <B>PlaceOnBottom</B>.
|
||
Valid for <B>Circulate</B> events.
|
||
Corresponds to the <B>p</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M22"><B>:root</B><I> window</I></A><DD>
|
||
<I>Window</I> must be either a window path name or an integer window
|
||
identifier; it specifies the <I>root</I> field for the event.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Enter</B>, <B>Leave</B>, and <B>Motion</B>
|
||
events.
|
||
Corresponds to the <B>R</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M23"><B>:rootx</B><I> coord</I></A><DD>
|
||
<I>Coord</I> must be a screen distance; it specifies the <I>x_root</I>
|
||
field for the event.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Enter</B>, <B>Leave</B>, and <B>Motion</B>
|
||
events. Corresponds to the <B>X</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M24"><B>:rooty</B><I> coord</I></A><DD>
|
||
<I>Coord</I> must be a screen distance; it specifies th <I>y_root</I>
|
||
field for the event.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Enter</B>, <B>Leave</B>, and <B>Motion</B>
|
||
events.
|
||
Corresponds to the <B>Y</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M25"><B>:sendevent</B><I> boolean</I></A><DD>
|
||
<B>Boolean</B> must be a boolean value; it specifies the <I>send_event</I>
|
||
field for the event. Valid for all events. Corresponds to the
|
||
<B>E</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M26"><B>:serial</B><I> number</I></A><DD>
|
||
<I>Number</I> must be an integer; it specifies the <I>serial</I> field
|
||
for the event. Valid for all events.
|
||
Corresponds to the <B>#</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M27"><B>:state</B><I> state</I></A><DD>
|
||
<I>State</I> specifies the <I>state</I> field for the event.
|
||
For <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Enter</B>, <B>Leave</B>, and <B>Motion</B> events
|
||
it must be an integer value.
|
||
For <B>Visibility</B> events it must be one of <B>VisibilityUnobscured</B>,
|
||
<B>VisibilityPartiallyObscured</B>, or <B>VisibilityFullyObscured</B>.
|
||
This option overrides any modifiers such as <B>Meta</B> or <B>Control</B>
|
||
specified in the base <I>event</I>.
|
||
Corresponds to the <B>s</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M28"><B>:subwindow</B><I> window</I></A><DD>
|
||
<I>Window</I> specifies the <I>subwindow</I> field for the event, either
|
||
as a path name for a Tk widget or as an integer window identifier.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Enter</B>, <B>Leave</B>, and <B>Motion</B> events.
|
||
Similar to <B>S</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M29"><B>:time</B><I> integer</I></A><DD>
|
||
<I>Integer</I> must be an integer value; it specifies the <I>time</I> field
|
||
for the event.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Enter</B>, <B>Leave</B>, <B>Motion</B>,
|
||
and <B>Property</B> events.
|
||
Corresponds to the <B>t</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M30"><B>:width</B><I> size</I></A><DD>
|
||
<I>Size</I> must be a screen distance; it specifies the <I>width</I> field
|
||
for the event.
|
||
Valid for <B>Configure</B> events.
|
||
Corresponds to the <B>w</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M31"><B>:when</B><I> when</I></A><DD>
|
||
<I>When</I> determines when the event will be processed; it must have one
|
||
of the following values:
|
||
<P>
|
||
<P>
|
||
<DL>
|
||
<DT><A NAME="M32">{ Bnow R}</A><DD>
|
||
Process the event immediately, before the procedure returns.
|
||
This also happens if the <B>:when</B> option is omitted.
|
||
<P>
|
||
<DT><A NAME="M33">{ Btail R}</A><DD>
|
||
Place the event on STk's event queue behind any events already
|
||
queued for this application.
|
||
<P>
|
||
<DT><A NAME="M34">{ Bhead R}</A><DD>
|
||
Place the event at the front of STk's event queue, so that it
|
||
will be handled before any other events already queued.
|
||
<P>
|
||
<DT><A NAME="M35">{ Bmark R}</A><DD>
|
||
Place the event at the front of STk's event queue but behind any
|
||
other events already queued with <B>:when mark</B>.
|
||
This option is useful when generating a series of events that should
|
||
be processed in order but at the front of the queue.
|
||
<P>
|
||
</DL>
|
||
<DT><A NAME="M36"><B>:x</B><I> coord</I></A><DD>
|
||
<I>Coord</I> must be a screen distance; it specifies the <I>x</I> field
|
||
for the event.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Motion</B>, <B>Enter</B>, <B>Leave</B>,
|
||
<B>Expose</B>, <B>Configure</B>, <B>Gravity</B>, and <B>Reparent</B>
|
||
events.
|
||
Corresponds to the the <B>x</B> substitution for binding scripts.
|
||
<P>
|
||
<DT><A NAME="M37"><B>:y</B><I> coord</I></A><DD>
|
||
<I>Coord</I> must be a screen distance; it specifies the <I>y</I>
|
||
field for the event.
|
||
Valid for <B>KeyPress</B>, <B>KeyRelease</B>, <B>ButtonPress</B>,
|
||
<B>ButtonRelease</B>, <B>Motion</B>, <B>Enter</B>, <B>Leave</B>,
|
||
<B>Expose</B>, <B>Configure</B>, <B>Gravity</B>, and <B>Reparent</B>
|
||
events.
|
||
Corresponds to the the <B>y</B> substitution for binding scripts.
|
||
<P>
|
||
</DL>
|
||
<P>
|
||
Any options that are not specified when generating an event are filled
|
||
with the value 0, except for <I>serial</I>, which is filled with the
|
||
next X event serial number.
|
||
|
||
<H3><A NAME="M38">VIRTUAL EVENT EXAMPLES</A></H3>
|
||
In order for a virtual event binding to trigger, two things must
|
||
happen. First, the virtual event must be defined with the
|
||
<B>event add</B> procedure. Second, a binding must be created for
|
||
the virtual event with the <B><A HREF="./bind.n.html">bind</A></B> procedure.
|
||
Consider the following virtual event definitions:
|
||
<PRE>(event 'add "<<Paste>>" "<Control-y>")
|
||
(event 'add "<<Paste>>" "<Button-2>")
|
||
(event 'add "<<Save>>" "<Control-X><Control-S>")
|
||
(event 'add "<<Save>>" "<Shift-F12>")</PRE>
|
||
In the <B><A HREF="./bind.n.html">bind</A></B> procedure, a virtual event can be bound like any other
|
||
builtin event type as follows:
|
||
<PRE>(bind "Entry" "<<Paste>>" (lambda (|W|)
|
||
(|W| 'insert [selection 'get])))</PRE>
|
||
The double 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 <B><<Paste>></B> virtual event is synthesized with <B>event generate</B>,
|
||
then the <B><<Paste>></B> binding will be invoked.
|
||
<P>
|
||
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:
|
||
<PRE>(event 'add "<<Paste>>" "<Control-y>" "<Meta-Control-y>")
|
||
(bind "Entry" "<Control-y>" (lambda () (display "Control-y\n")))
|
||
(bind "Entry" "<<Paste>>" (lambda () (display "Paste\n")))</PRE>
|
||
When the user types Control-y the <B><Control-y></B> 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
|
||
<B><<Paste>></B> binding will be invoked, because the
|
||
<B>Meta</B> modifier in the physical pattern associated with the
|
||
virtual binding is more specific than the <B><Control-y</B>> sequence for
|
||
the physical event.
|
||
<P>
|
||
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 meaningless or
|
||
ungeneratable.
|
||
<P>
|
||
When a definition of a virtual event changes at run time, all windows
|
||
will respond immediately to the new definition.
|
||
Starting from the preceding example, if the following code is executed:
|
||
<PRE>(bind "<Entry>" "<Control-y>" "")
|
||
(event 'add "<<Paste>>" "<Key-F6>")</PRE>
|
||
the behavior will change such in two ways. First, the shadowed
|
||
<B><<Paste>></B> binding will emerge.
|
||
Typing Control-y will no longer invoke the <B><Control-y></B> binding,
|
||
but instead invoke the virtual event <B><<Paste>></B>. Second,
|
||
pressing the F6 key will now also invoke the <B><<Paste>></B> binding.
|
||
|
||
<H3><A NAME="M39">SEE ALSO</A></H3>
|
||
<B><A HREF="./bind.n.html">bind</A></B>
|
||
<P><IMG ALIGN=TOP SRC="./Img/line-red.gif"><P>
|
||
<A HREF=./STk-hlp.html><IMG ALIGN=BOTTOM SRC="./Img/RefBookBlue.gif"> Back to the <B>STk</B> main page</A>
|
||
</BODY></HTML>
|