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, 0 insertions, 417 deletions
diff --git a/Master/tlpkg/tlperl/lib/Tk/event.pod b/Master/tlpkg/tlperl/lib/Tk/event.pod
deleted file mode 100644
index 9012a596267..00000000000
--- a/Master/tlpkg/tlperl/lib/Tk/event.pod
+++ /dev/null
@@ -1,417 +0,0 @@
-# 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
-