summaryrefslogtreecommitdiff
path: root/Master/tlpkg/tlperl/lib/Tk/event.pod
diff options
context:
space:
mode:
Diffstat (limited to 'Master/tlpkg/tlperl/lib/Tk/event.pod')
-rw-r--r--Master/tlpkg/tlperl/lib/Tk/event.pod417
1 files changed, 417 insertions, 0 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/event.pod b/Master/tlpkg/tlperl/lib/Tk/event.pod
new file mode 100644
index 00000000000..9012a596267
--- /dev/null
+++ b/Master/tlpkg/tlperl/lib/Tk/event.pod
@@ -0,0 +1,417 @@
+# 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.
+#
+#
+
+=head1 NAME
+
+Tk::event - Miscellaneous event facilities: define virtual events and generate events
+
+=for category Binding Events and Callbacks
+
+=head1 SYNOPSIS
+
+I<$widget>-E<gt>B<event>I<Action>(?I<arg, arg, ...>?);
+
+=head1 DESCRIPTION
+
+The B<event>I<Action> methods provides several facilities for dealing with
+window system events, such as defining virtual events and synthesizing
+events. Virtual events are shared by all widgets of the same
+B<MainWindow>. Different L<MainWindow|Tk::MainWindow>s can have different
+virtual event.
+
+The following methods are currently supported:
+
+=over 4
+
+=item I<$widget>-E<gt>B<eventAdd>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>I<, sequence >?,I<sequence, ...>?)
+
+Associates the virtual event I<virtual> with the physical
+event sequence(s) given by the I<sequence> arguments, so that
+the virtual event will trigger whenever any one of the I<sequence>s
+occurs.
+I<Virtual> may be any string value and I<sequence> may have
+any of the values allowed for the I<sequence> argument to the
+L<bind|Tk::bind> method.
+If I<virtual> is already defined, the new physical event sequences
+add to the existing sequences for the event.
+
+=item I<$widget>-E<gt>B<eventDelete>(B<'E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'> ?,I<sequence,> I<sequence, ...>?)
+
+Deletes each of the I<sequence>s from those associated with
+the virtual event given by I<virtual>.
+I<Virtual> may be any string value and I<sequence> may have
+any of the values allowed for the I<sequence> argument to the
+L<bind|Tk::bind> method.
+Any I<sequence>s not currently associated with I<virtual>
+are ignored.
+If no I<sequence> argument is provided, all physical event sequences
+are removed for I<virtual>, so that the virtual event will not
+trigger anymore.
+
+=item I<$widget>-E<gt>B<eventGenerate>(I<event> ?,I<option =E<gt> value, option =E<gt> value, ...>?)
+
+Generates a window event and arranges for it to be processed just as if
+it had come from the window system.
+I<$window> is a reference to the window for which the event
+will be generated.
+I<Event> provides a basic description of
+the event, such as B<E<lt>Shift-Button-2E<gt>> or B<E<lt>E<lt>PasteE<gt>E<gt>>.
+If I<Window> is empty the whole screen is meant, and coordinates
+are relative to the screen.
+I<Event> may have any of the forms allowed for the I<sequence>
+argument of the L<bind|Tk::bind> method except that it must consist
+of a single event pattern, not a sequence.
+I<Option-value> pairs may be used to specify additional
+attributes of the event, such as the x and y mouse position;
+see L<"EVENT FIELDS"> below. If the B<-when> option is not specified, the
+event is processed immediately: all of the handlers for the event
+will complete before the B<eventGenerate> method returns.
+If the B<-when> option is specified then it determines when the
+event is processed.
+
+=item I<$widget>-E<gt>B<eventInfo>(?'B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>'>?)
+
+Returns information about virtual events.
+If the B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> argument is omitted, the return value
+is a list of all the virtual events that are currently defined.
+If B<E<lt>E<lt>>I<virtual>B<E<gt>E<gt>> 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 B<undef> is returned.
+
+=back
+
+=head1 EVENT FIELDS
+
+The following options are supported for the B<eventGenerate>
+method. These correspond to the ``%'' expansions
+allowed in binding callback for the L<bind|Tk::bind> method.
+
+=over 4
+
+=item B<-above> => I<window>
+
+I<Window> specifies the I<above> field for the event,
+either as a window path name or as an integer window id.
+Valid for B<Configure> events.
+Corresponds to the L<%a|Tk::bind/'a'> substitution for binding scripts.
+
+=item B<-borderwidth> => I<size>
+
+I<Size> must be a screen distance; it specifies the
+I<border_width> field for the event.
+Valid for B<Configure> events.
+Corresponds to the L<%B|Tk::bind/'B'> substitution for binding scripts.
+
+=item B<-button> => I<number>
+
+I<Number> must be an integer; it specifies the I<detail> field
+for a B<ButtonPress> or B<ButtonRelease> event, overriding
+any button number provided in the base I<event> argument.
+Corresponds to the L<%b|Tk::bind/'b'> substitution for binding scripts.
+
+=item B<-count> => I<number>
+
+I<Number> must be an integer; it specifies the I<count> field
+for the event. Valid for B<Expose> events.
+Corresponds to the L<%c|Tk::bind/'c'> substitution for binding scripts.
+
+=item B<-delta> =E<gt> I<number>
+
+B<number> must be an integer; it specifies the B<delta> field for the
+B<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. Typically these values are
+multiples of 120. For example, 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 corresponds to the %D substitution for binding scripts.
+
+=item B<-detail> => I<detail>
+
+I<Detail> specifies the I<detail> field for the event
+and must be one of the following:
+
+=over 8
+
+ NotifyAncestor NotifyNonlinearVirtual
+ NotifyDetailNone NotifyPointer
+ NotifyInferior NotifyPointerRoot
+ NotifyNonlinear NotifyVirtual
+
+=back
+
+Valid for B<Enter>, B<Leave>, B<FocusIn> and
+B<FocusOut> events.
+Corresponds to the L<%d|Tk::bind/'d'> substitution for binding scripts.
+
+=item B<-focus>I< boolean>
+
+I<Boolean> must be a boolean value; it specifies the I<focus>
+field for the event.
+Valid for B<Enter> and B<Leave> events.
+Corresponds to the L<%f|Tk::bind/'f'> substitution for binding scripts.
+
+=item B<-height>I< size>
+
+I<Size> must be a screen distance; it specifies the I<height>
+field for the event. Valid for B<Configure> events.
+Corresponds to the L<%h|Tk::bind/'h'> substitution for binding scripts.
+
+=item B<-keycode>I< number>
+
+I<Number> must be an integer; it specifies the I<keycode>
+field for the event.
+Valid for B<KeyPress> and B<KeyRelease> events.
+Corresponds to the L<%k|Tk::bind/'k'> substitution for binding scripts.
+
+=item B<-keysym>I< name>
+
+I<Name> must be the name of a valid keysym, such as B<g>,
+B<space>, or B<Return>; its corresponding
+keycode value is used as the I<keycode> field for event, overriding
+any detail specified in the base I<event> argument.
+Valid for B<KeyPress> and B<KeyRelease> events.
+Corresponds to the L<%K|Tk::bind/'K'> substitution for binding scripts.
+
+=item B<-mode>I< notify>
+
+I<Notify> specifies the I<mode> field for the event and must be
+one of B<NotifyNormal>, B<NotifyGrab>, B<NotifyUngrab>, or
+B<NotifyWhileGrabbed>.
+Valid for B<Enter>, B<Leave>, B<FocusIn>, and
+B<FocusOut> events.
+Corresponds to the L<%m|Tk::bind/'m'> substitution for binding scripts.
+
+=item B<-override>I< boolean>
+
+I<Boolean> must be a boolean value; it specifies the
+I<override_redirect> field for the event.
+Valid for B<Map>, B<Reparent>, and B<Configure> events.
+Corresponds to the L<%o|Tk::bind/'o'> substitution for binding scripts.
+
+=item B<-place>I< where>
+
+I<Where> specifies the I<place> field for the event; it must be
+either B<PlaceOnTop> or B<PlaceOnBottom>.
+Valid for B<Circulate> events.
+Corresponds to the L<%p|Tk::bind/'p'> substitution for binding scripts.
+
+=item B<-root>I< window>
+
+I<Window> must be either a window path name or an integer window
+identifier; it specifies the I<root> field for the event.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion>
+events.
+Corresponds to the L<%R|Tk::bind/'R'> substitution for binding scripts.
+
+=item B<-rootx>I< coord>
+
+I<Coord> must be a screen distance; it specifies the I<x_root>
+field for the event.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion>
+events. Corresponds to the L<%X|Tk::bind/'X'> substitution for binding scripts.
+
+=item B<-rooty>I< coord>
+
+I<Coord> must be a screen distance; it specifies the I<y_root>
+field for the event.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion>
+events.
+Corresponds to the L<%Y|Tk::bind/'Y'> substitution for binding scripts.
+
+=item B<-sendevent>I< boolean>
+
+B<Boolean> must be a boolean value; it specifies the I<send_event>
+field for the event. Valid for all events. Corresponds to the
+L<%E|Tk::bind/'E'> substitution for binding scripts.
+
+=item B<-serial>I< number>
+
+I<Number> must be an integer; it specifies the I<serial> field
+for the event. Valid for all events.
+Corresponds to the L<%#|Tk::bind/'#'> substitution for binding scripts.
+
+=item B<-state>I< state>
+
+I<State> specifies the I<state> field for the event.
+For B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events
+it must be an integer value.
+For B<Visibility> events it must be one of B<VisibilityUnobscured>,
+B<VisibilityPartiallyObscured>, or B<VisibilityFullyObscured>.
+This option overrides any modifiers such as B<Meta> or B<Control>
+specified in the base I<event>.
+Corresponds to the L<%s|Tk::bind/'s'> substitution for binding scripts.
+
+=item B<-subwindow>I< window>
+
+I<Window> specifies the I<subwindow> field for the event, either
+as a path name for a Tk widget or as an integer window identifier.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Enter>, B<Leave>, and B<Motion> events.
+Similar to L<%S|Tk::bind/'S'> substitution for binding scripts.
+
+=item B<-time>I< integer>
+
+I<Integer> must be an integer value; it specifies the I<time> field
+for the event.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Enter>, B<Leave>, B<Motion>,
+and B<Property> events.
+Corresponds to the L<%t|Tk::bind/'t'> substitution for binding scripts.
+
+
+=item B<-warp>I< boolean>
+
+I<boolean> must be a boolean value; it specifies whether
+the screen pointer should be warped as well.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, and B<Motion> events.
+
+=item B<-width>I< size>
+
+I<Size> must be a screen distance; it specifies the I<width> field
+for the event.
+Valid for B<Configure> events.
+Corresponds to the L<%w|Tk::bind/'w'> substitution for binding scripts.
+
+=item B<-when>I< when>
+
+I<When> determines when the event will be processed; it must have one
+of the following values:
+
+=over 8
+
+=item B<now>
+
+Process the event immediately, before the command returns.
+This also happens if the B<-when> option is omitted.
+
+=item B<tail>
+
+Place the event on perl/Tk's event queue behind any events already
+queued for this application.
+
+=item B<head>
+
+Place the event at the front of perl/Tk's event queue, so that it
+will be handled before any other events already queued.
+
+=item B<mark>
+
+Place the event at the front of perl/Tk's event queue but behind any
+other events already queued with B<-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.
+
+=back
+
+=item B<-x>I< coord>
+
+I<Coord> must be a screen distance; it specifies the I<x> field
+for the event.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>,
+B<Expose>, B<Configure>, B<Gravity>, and B<Reparent>
+events.
+Corresponds to the the L<%x|Tk::bind/'x'> substitution for binding scripts.
+If I<Window> is empty the coordinate is relative to the
+screen, and this option corresponds to the L<%X|Tk::bind/'X'> substitution
+for binding scripts.
+
+=item B<-y>I< coord>
+
+I<Coord> must be a screen distance; it specifies the I<y>
+field for the event.
+Valid for B<KeyPress>, B<KeyRelease>, B<ButtonPress>,
+B<ButtonRelease>, B<Motion>, B<Enter>, B<Leave>,
+B<Expose>, B<Configure>, B<Gravity>, and B<Reparent>
+events.
+Corresponds to the the L<%y|Tk::bind/'y'> substitution for binding scripts.
+If I<Window> is empty the coordinate is relative to the
+screen, and this option corresponds to the L<%Y|Tk::bind/'Y'> substitution
+for binding scripts.
+
+Any options that are not specified when generating an event are filled
+with the value 0, except for I<serial>, which is filled with the
+next X event serial number.
+
+=back
+
+=head1 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
+B<eventAdd> method. Second, a binding must be created for
+the virtual event with the B<bind> method.
+Consider the following virtual event definitions:
+
+ $widget->eventAdd('<<Paste>>' => '<Control-y>');
+ $widget->eventAdd('<<Paste>>' => '<Button-2>');
+ $widget->eventAdd('<<Save>>' => '<Control-X><Control-S>');
+ $widget->eventAdd('<<Save>>' => '<Shift-F12>');
+
+In the B<bind> method, a virtual event can be bound like any other
+builtin event type as follows:
+
+ $entry->bind('Tk::Entry', '<<Paste>>' => sub {
+ $entry->Insert($entry->selectionGet) });
+
+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<E<lt>E<lt>PasteE<gt>E<gt>> virtual event is synthesized with B<eventGenerate>,
+then the B<E<lt>E<lt>PasteE<gt>E<gt>> 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:
+
+ $mw->eventAdd('<<Paste>>' => '<Control-y>','<Meta-Control-y>');
+ $mw->bind('Tk::Entry', '<Control-y>' => sub{print 'Control-y'});
+ $mw->bind('Tk::Entry', '<<Paste>>' => sub{print 'Paste'});
+
+When the user types Control-y the B<E<lt>Control-yE<gt>> 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<E<lt>E<lt>PasteE<gt>E<gt>> binding will be invoked, because the
+B<Meta> modifier in the physical pattern associated with the
+virtual binding is more specific than the B<E<lt>Control-y>E<gt> 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 meaningless 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 preceding example, if the following code is executed:
+
+ $entry->bind(ref($entry), '<Control-y>' => undef);
+ $entry->eventAdd('<<Paste>>' => '<Key-F6>');
+
+the behavior will change such in two ways. First, the shadowed
+B<E<lt>E<lt>PasteE<gt>E<gt>> binding will emerge.
+Typing Control-y will no longer invoke the B<E<lt>Control-yE<gt>> binding,
+but instead invoke the virtual event B<E<lt>E<lt>PasteE<gt>E<gt>>. Second,
+pressing the F6 key will now also invoke the B<E<lt>E<lt>PasteE<gt>E<gt>> binding.
+
+=head1 SEE ALSO
+
+L<Tk::bind|Tk::bind>
+L<Tk::callbacks|Tk::callbacks>
+
+=head1 KEYWORDS
+
+event, binding, define, handle, virtual event
+
+=cut
+