340 lines
14 KiB
Plaintext
340 lines
14 KiB
Plaintext
'\"
|
|
'\" Copyright (c) 1996 Sun Microsystems, Inc.
|
|
'\"
|
|
'\" See the file "license.terms" for information on usage and redistribution
|
|
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
|
|
'\"
|
|
'\" SCCS: @(#) event.n 1.4 96/10/03 18:39:43
|
|
'\"
|
|
.so STk-man.macros
|
|
.TH event n 4.0 STk "STk Built-In Commands"
|
|
.BS
|
|
'\" Note: do not modify the .SH NAME line immediately below!
|
|
.SH NAME
|
|
event \- Miscellaneous event facilities: define virtual events and generate events
|
|
.SH SYNOPSIS
|
|
\fBevent\fI option \fR?\fIarg arg ...\fR?
|
|
.BE
|
|
|
|
.SH DESCRIPTION
|
|
.PP
|
|
The \fBevent\fR 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:
|
|
.TP
|
|
(\fBevent 'add "<<\fIvirtual\fB>>"\fI sequence \fR?\fIsequence ...\fR?)
|
|
Associates the virtual event \fIvirtual\fR with the physical
|
|
event sequence(s) given by the \fIsequence\fR arguments, so that
|
|
the virtual event will trigger whenever any one of the \fIsequence\fRs
|
|
occurs.
|
|
\fIVirtual\fR may be any string value and \fIsequence\fR may have
|
|
any of the values allowed for the \fIsequence\fR argument to the
|
|
\fBbind\fR procedure.
|
|
If \fIvirtual\fR is already defined, the new physical event sequences
|
|
add to the existing sequences for the event.
|
|
.TP
|
|
(\fBevent 'delete "<<\fIvirtual\fB>>" \fR?\fIsequence\fR \fIsequence ...\fR?)
|
|
Deletes each of the \fIsequence\fRs from those associated with
|
|
the virtual event given by \fIvirtual\fR.
|
|
\fIVirtual\fR may be any string value and \fIsequence\fR may have
|
|
any of the values allowed for the \fIsequence\fR argument to the
|
|
\fBbind\fR procedure.
|
|
Any \fIsequence\fRs not currently associated with \fIvirtual\fR
|
|
are ignored.
|
|
If no \fIsequence\fR argument is provided, all physical event sequences
|
|
are removed for \fIvirtual\fR, so that the virtual event will not
|
|
trigger anymore.
|
|
.TP
|
|
(\fBevent 'generate \fIwindow event \fR?\fIoption value option value ...\fR?)
|
|
Generates a window event and arranges for it to be processed just as if
|
|
it had come from the window system.
|
|
\fIWindow\fR gives the path name of the window for which the event
|
|
.VS
|
|
will be generated; it may also be a window identifier (such as returned by
|
|
(\fBwinfo 'id\fR)) as long as it is for a window in the current application.
|
|
.VE
|
|
\fIEvent\fR provides a basic description of
|
|
will be generated, and \fIevent\fR provides a basic description of
|
|
the event, such as "\fB<Shift-Button-2>\fR" or "\fB<<Paste>>\fR".
|
|
\fIEvent\fR may have any of the forms allowed for the \fIsequence\fR
|
|
argument of the \fBbind\fR procedure except that it must consist
|
|
of a single event pattern, not a sequence.
|
|
\fIOption-value\fR 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 \fB:when\fR option is not specified, the
|
|
event is processed immediately: all of the handlers for the event
|
|
will complete before the \fBevent generate\fR procedure returns.
|
|
If the \fB:when\fR option is specified then it determines when the
|
|
event is processed.
|
|
.TP
|
|
(\fBevent 'info)
|
|
.TP
|
|
(\fBevent 'info \fR"<<\fIvirtual\fB>>"\fR)
|
|
Returns information about virtual events.
|
|
If the "\fB<<\fIvirtual\fB>>\fR" argument is omitted, the return value
|
|
is a list of all the virtual events that are currently defined.
|
|
If "\fB<<\fIvirtual\fB>>\fR" 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.
|
|
|
|
.SH "EVENT FIELDS"
|
|
.PP
|
|
The following options are supported for the \fBevent generate\fR
|
|
procedure. These correspond to the character names
|
|
allowed in binding scripts for the \fBbind\fR procedure.
|
|
.TP
|
|
\fB:above\fI window\fR
|
|
\fIWindow\fR specifies the \fIabove\fR field for the event,
|
|
either as a window path name or as an integer window id.
|
|
Valid for \fBConfigure\fR events.
|
|
Corresponds to the \fBa\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:borderwidth\fI size\fR
|
|
\fISize\fR must be a screen distance; it specifies the
|
|
\fIborder_width\fR field for the event.
|
|
Valid for \fBConfigure\fR events.
|
|
Corresponds to the \fBB\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:button\fI number\fR
|
|
\fINumber\fR must be an integer; it specifies the \fIdetail\fR field
|
|
for a \fBButtonPress\fR or \fBButtonRelease\fR event, overriding
|
|
any button number provided in the base \fIevent\fR argument.
|
|
Corresponds to the \fBb\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:count\fI number\fR
|
|
\fINumber\fR must be an integer; it specifies the \fIcount\fR field
|
|
for the event. Valid for \fBExpose\fR events.
|
|
Corresponds to the \fBc\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:detail\fI detail\fR
|
|
\fIDetail\fR specifies the \fIdetail\fR field for the event
|
|
and must be one of the following:
|
|
.RS
|
|
.DS
|
|
.ta 6c
|
|
\fBNotifyAncestor NotifyNonlinearVirtual
|
|
NotifyDetailNone NotifyPointer
|
|
NotifyInferior NotifyPointerRoot
|
|
NotifyNonlinear NotifyVirtual\fR
|
|
.DE
|
|
Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR and
|
|
\fBFocusOut\fR events.
|
|
Corresponds to the \fBd\fR substitution for binding scripts.
|
|
.RE
|
|
.TP
|
|
\fB:focus\fI boolean\fR
|
|
\fIBoolean\fR must be a boolean value; it specifies the \fIfocus\fR
|
|
field for the event.
|
|
Valid for \fBEnter\fR and \fBLeave\fR events.
|
|
Corresponds to the \fBf\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:height\fI size\fR
|
|
\fISize\fR must be a screen distance; it specifies the \fIheight\fR
|
|
field for the event. Valid for \fBConfigure\fR events.
|
|
Corresponds to the \fBh\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:keycode\fI number\fR
|
|
\fINumber\fR must be an integer; it specifies the \fIkeycode\fR
|
|
field for the event.
|
|
Valid for \fBKeyPress\fR and \fBKeyRelease\fR events.
|
|
Corresponds to the \fBk\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:keysym\fI name\fR
|
|
\fIName\fR must be the name of a valid keysym, such as "\fBg\fR",
|
|
"\fBspace\fR", or "\fBReturn\fR"; its corresponding
|
|
keycode value is used as the \fIkeycode\fR field for event, overriding
|
|
any detail specified in the base \fIevent\fR argument.
|
|
Valid for \fBKeyPress\fR and \fBKeyRelease\fR events.
|
|
Corresponds to the \fBK\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:mode\fI notify\fR
|
|
\fINotify\fR specifies the \fImode\fR field for the event and must be
|
|
one of \fBNotifyNormal\fR, \fBNotifyGrab\fR, \fBNotifyUngrab\fR, or
|
|
\fBNotifyWhileGrabbed\fR.
|
|
Valid for \fBEnter\fR, \fBLeave\fR, \fBFocusIn\fR, and
|
|
\fBFocusOut\fR events.
|
|
Corresponds to the \fBm\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:override\fI boolean\fR
|
|
\fIBoolean\fR must be a boolean value; it specifies the
|
|
\fIoverride_redirect\fR field for the event.
|
|
Valid for \fBMap\fR, \fBReparent\fR, and \fBConfigure\fR events.
|
|
Corresponds to the \fBo\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:place\fI where\fR
|
|
\fIWhere\fR specifies the \fIplace\fR field for the event; it must be
|
|
either \fBPlaceOnTop\fR or \fBPlaceOnBottom\fR.
|
|
Valid for \fBCirculate\fR events.
|
|
Corresponds to the \fBp\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:root\fI window\fR
|
|
\fIWindow\fR must be either a window path name or an integer window
|
|
identifier; it specifies the \fIroot\fR field for the event.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR
|
|
events.
|
|
Corresponds to the \fBR\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:rootx\fI coord\fR
|
|
\fICoord\fR must be a screen distance; it specifies the \fIx_root\fR
|
|
field for the event.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR
|
|
events. Corresponds to the \fBX\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:rooty\fI coord\fR
|
|
\fICoord\fR must be a screen distance; it specifies th \fIy_root\fR
|
|
field for the event.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR
|
|
events.
|
|
Corresponds to the \fBY\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:sendevent\fI boolean\fR
|
|
\fBBoolean\fR must be a boolean value; it specifies the \fIsend_event\fR
|
|
field for the event. Valid for all events. Corresponds to the
|
|
\fBE\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:serial\fI number\fR
|
|
\fINumber\fR must be an integer; it specifies the \fIserial\fR field
|
|
for the event. Valid for all events.
|
|
Corresponds to the \fB#\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:state\fI state\fR
|
|
\fIState\fR specifies the \fIstate\fR field for the event.
|
|
For \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events
|
|
it must be an integer value.
|
|
For \fBVisibility\fR events it must be one of \fBVisibilityUnobscured\fR,
|
|
\fBVisibilityPartiallyObscured\fR, or \fBVisibilityFullyObscured\fR.
|
|
This option overrides any modifiers such as \fBMeta\fR or \fBControl\fR
|
|
specified in the base \fIevent\fR.
|
|
Corresponds to the \fBs\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:subwindow\fI window\fR
|
|
\fIWindow\fR specifies the \fIsubwindow\fR field for the event, either
|
|
as a path name for a Tk widget or as an integer window identifier.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, and \fBMotion\fR events.
|
|
Similar to \fBS\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:time\fI integer\fR
|
|
\fIInteger\fR must be an integer value; it specifies the \fItime\fR field
|
|
for the event.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBEnter\fR, \fBLeave\fR, \fBMotion\fR,
|
|
and \fBProperty\fR events.
|
|
Corresponds to the \fBt\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:width\fI size\fR
|
|
\fISize\fR must be a screen distance; it specifies the \fIwidth\fR field
|
|
for the event.
|
|
Valid for \fBConfigure\fR events.
|
|
Corresponds to the \fBw\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:when\fI when\fR
|
|
\fIWhen\fR determines when the event will be processed; it must have one
|
|
of the following values:
|
|
.RS
|
|
.IP \fBnow\fR 10
|
|
Process the event immediately, before the procedure returns.
|
|
This also happens if the \fB:when\fR option is omitted.
|
|
.IP \fBtail\fR 10
|
|
Place the event on STk's event queue behind any events already
|
|
queued for this application.
|
|
.IP \fBhead\fR 10
|
|
Place the event at the front of STk's event queue, so that it
|
|
will be handled before any other events already queued.
|
|
.IP \fBmark\fR 10
|
|
Place the event at the front of STk's event queue but behind any
|
|
other events already queued with \fB:when mark\fR.
|
|
This option is useful when generating a series of events that should
|
|
be processed in order but at the front of the queue.
|
|
.RE
|
|
.TP
|
|
\fB:x\fI coord\fR
|
|
\fICoord\fR must be a screen distance; it specifies the \fIx\fR field
|
|
for the event.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR,
|
|
\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR
|
|
events.
|
|
Corresponds to the the \fBx\fR substitution for binding scripts.
|
|
.TP
|
|
\fB:y\fI coord\fR
|
|
\fICoord\fR must be a screen distance; it specifies the \fIy\fR
|
|
field for the event.
|
|
Valid for \fBKeyPress\fR, \fBKeyRelease\fR, \fBButtonPress\fR,
|
|
\fBButtonRelease\fR, \fBMotion\fR, \fBEnter\fR, \fBLeave\fR,
|
|
\fBExpose\fR, \fBConfigure\fR, \fBGravity\fR, and \fBReparent\fR
|
|
events.
|
|
Corresponds to the the \fBy\fR substitution for binding scripts.
|
|
.PP
|
|
Any options that are not specified when generating an event are filled
|
|
with the value 0, except for \fIserial\fR, which is filled with the
|
|
next X event serial number.
|
|
|
|
.SH "VIRTUAL EVENT EXAMPLES"
|
|
.PP
|
|
In order for a virtual event binding to trigger, two things must
|
|
happen. First, the virtual event must be defined with the
|
|
\fBevent add\fR procedure. Second, a binding must be created for
|
|
the virtual event with the \fBbind\fR procedure.
|
|
Consider the following virtual event definitions:
|
|
.CS
|
|
(event 'add "<<Paste>>" "<Control-y>")
|
|
(event 'add "<<Paste>>" "<Button-2>")
|
|
(event 'add "<<Save>>" "<Control-X><Control-S>")
|
|
(event 'add "<<Save>>" "<Shift-F12>")
|
|
.CE
|
|
In the \fBbind\fR procedure, a virtual event can be bound like any other
|
|
builtin event type as follows:
|
|
.CS
|
|
(bind "Entry" "<<Paste>>" (lambda (|W|)
|
|
(|W| 'insert [selection 'get])))
|
|
.CE
|
|
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 \fB<<Paste>>\fR virtual event is synthesized with \fBevent generate\fR,
|
|
then the \fB<<Paste>>\fR binding will be invoked.
|
|
.PP
|
|
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:
|
|
.CS
|
|
(event 'add "<<Paste>>" "<Control-y>" "<Meta-Control-y>")
|
|
(bind "Entry" "<Control-y>" (lambda () (display "Control-y\n")))
|
|
(bind "Entry" "<<Paste>>" (lambda () (display "Paste\n")))
|
|
.CE
|
|
When the user types Control-y the \fB<Control-y>\fR 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
|
|
\fB<<Paste>>\fR binding will be invoked, because the
|
|
\fBMeta\fR modifier in the physical pattern associated with the
|
|
virtual binding is more specific than the \fB<Control-y\fR> sequence for
|
|
the physical event.
|
|
.PP
|
|
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.
|
|
.PP
|
|
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:
|
|
.CS
|
|
(bind "<Entry>" "<Control-y>" "")
|
|
(event 'add "<<Paste>>" "<Key-F6>")
|
|
.CE
|
|
the behavior will change such in two ways. First, the shadowed
|
|
\fB<<Paste>>\fR binding will emerge.
|
|
Typing Control-y will no longer invoke the \fB<Control-y>\fR binding,
|
|
but instead invoke the virtual event \fB<<Paste>>\fR. Second,
|
|
pressing the F6 key will now also invoke the \fB<<Paste>>\fR binding.
|
|
|
|
.SH "SEE ALSO"
|
|
bind
|