Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
bind(3)		      User Contributed Perl Documentation	       bind(3)

NAME
       Tk::bind	- Arrange for X	events to invoke callbacks

SYNOPSIS
       Retrieve	bindings:

       A A A A $widget->bind

       A A A A $widget->bind(tag)

       A A A A $widget->bind(sequence)

       A A A A $widget->bind(tag,sequence)

       Associate and destroy bindings:

       A A A A $widget->bind(sequence,callback)

       A A A A $widget->bind(tag,sequence,callback)

DESCRIPTION
       The bind	method associates callbacks with X events.  If callback	is
       specified, bind will arrange for	callback to be evaluated whenever the
       event(s)	given by sequence occur	in the window(s) identified by $widget
       or tag.	If callback is an empty	string then the	current	binding	for
       sequence	is destroyed, leaving sequence unbound.	 In all	of the cases
       where a callback	argument is provided, bind returns an empty string.

       If sequence is specified	without	a callback, then the callback
       currently bound to sequence is returned,	or undef is returned if	there
       is no binding for sequence.  If neither sequence	nor callback is
       specified, then the return value	is a list whose	elements are all the
       sequences for which there exist bindings	for tag.

       If no tag is specified then the bind refers to $widget.	If tag is
       specified then it is typically a	class name and the bind	refers to all
       instances of the	class on the MainWindow	associated with	$widget. (It
       is possible for tag to be another "widget object" but this practice is
       deprecated.) Perl's ref($object)	can be used to get the class name of
       any object.  Each window	has an associated list of tags,	and a binding
       applies to a particular window if its tag is among those	specified for
       the window.  Although the bindtags method may be	used to	assign an
       arbitrary set of	binding	tags to	a window, the default binding tags
       provide the following behavior:

       If a tag	is the name of an internal window the binding applies to that
       window.

       If the tag is the name of a toplevel window the binding applies to the
       toplevel	window and all its internal windows.

       If the tag is the name of a class of widgets, such as Tk::Button, the
       binding applies to all widgets in that class;

       If tag has the value all, the binding applies to	all windows descended
       from the	MainWindow of the application.

EVENT PATTERNS
       The sequence argument specifies a sequence of one or more event
       patterns, with optional white space between the patterns.  Each event
       pat may take one	of three forms.	 In the	simplest case it is a single
       printing	ASCII character, such as a or [.  The character	may not	be a
       space character or the character	<.  This form of pattern matches a
       KeyPress	event for the particular character.  The second	form of
       pattern is longer but more general.  It has the following syntax:

       A A A A '<modifier-modifier-type-detail>'

       The entire event	pattern	is surrounded by angle brackets, and normally
       needs to	be quoted, as angle brackets are special to perl.  Inside the
       angle brackets are zero or more modifiers, an event type, and an	extra
       piece of	information (detail) identifying a particular button or
       keysym.	Any of the fields may be omitted, as long as at	least one of
       type and	detail is present.  The	fields must be separated by white
       space or	dashes.

       The third form of pattern is used to specify a user-defined, named
       virtual event; see Tk::event for	details.  It has the following syntax:

       A A A A '<<name>>'

       The entire virtual event	pattern	is surrounded by double	angle
       brackets.  Inside the angle brackets is the user-defined	name of	the
       virtual event.  Modifiers, such as Shift	or Control, may	not be
       combined	with a virtual event to	modify it.  Bindings on	a virtual
       event may be created before the virtual event is	defined, and if	the
       definition of a virtual event changes dynamically, all windows bound to
       that virtual event will respond immediately to the new definition.

MODIFIERS
       Modifiers consist of any	of the following values:

	Control	       Mod2, M2
	Shift	       Mod3, M3
	Lock	       Mod4, M4
	Button1, B1    Mod5, M5
	Button2, B2    Meta, M
	Button3, B3    Alt
	Button4, B4    Double
	Button5, B5    Triple
	Mod1,	 M1    Quadruple

       Where more than one value is listed, separated by commas, the values
       are equivalent.	Most of	the modifiers have the obvious X meanings.
       For example, Button1 requires that button 1 be depressed	when the event
       occurs.	For a binding to match a given event, the modifiers in the
       event must include all of those specified in the	event pattern.	An
       event may also contain additional modifiers not specified in the
       binding.	 For example, if button	1 is pressed while the shift and
       control keys are	down, the pattern <Control-Button-1> will match	the
       event, but <Mod1-Button-1> will not.  If	no modifiers are specified,
       then any	combination of modifiers may be	present	in the event.

       Meta and	M refer	to whichever of	the M1 through M5 modifiers is
       associated with the meta	key(s) on the keyboard (keysyms	Meta_R and
       Meta_L).	 If there are no meta keys, or if they are not associated with
       any modifiers, then Meta	and M will not match any events.  Similarly,
       the Alt modifier	refers to whichever modifier is	associated with	the
       alt key(s) on the keyboard (keysyms Alt_L and Alt_R).

       The Double, Triple and Quadruple	modifiers are a	convenience for
       specifying double mouse clicks and other	repeated events. They cause a
       particular event	pattern	to be repeated 2, 3 or 4 times,	and also place
       a time and space	requirement on the sequence: for a sequence of events
       to match	a Double, Triple or Quadruple pattern, all of the events must
       occur close together in time and	without	substantial mouse motion in
       between.	 For example, <Double-Button-1>	is equivalent to
       <Button-1><Button-1> with the extra time	and space requirement.

EVENT TYPES
       The type	field may be any of the	standard X event types,	with a few
       extra abbreviations.  Below is a	list of	all the	valid types; where two
       names appear together, they are synonyms.

	   Activate	       Destroy		  Map
	   ButtonPress,	Button Enter		  MapRequest
	   ButtonRelease       Expose		  Motion
	   Circulate	       FocusIn		  MouseWheel
	   CirculateRequest    FocusOut		  Property
	   Colormap	       Gravity		  Reparent
	   Configure	       KeyPress, Key	  ResizeRequest
	   ConfigureRequest    KeyRelease	  Unmap
	   Create	       Leave		  Visibility
	   Deactivate

       Most of the above events	have the same fields and behaviors  as	events
       in  the X Windowing system.  You	can find more detailed descriptions of
       these events in any X window programming	book.  A couple	of the	events
       are  extensions to the X	event system to	support	features unique	to the
       Macintosh and Windows platforms.	 We provide a little  more  detail  on
       these events here.  These include:

	   Activate
	   Deactivate

       These two events	are sent to every sub-window of	a toplevel when	they
       change state.  In addition to the focus Window, the Macintosh platform
       and Windows platforms have a notion of an active	window (which often
       has but is not required to have the focus).  On the Macintosh, widgets
       in the active window have a different appearance	than widgets in
       deactive	windows.  The Activate event is	sent to	all the	sub-windows in
       a toplevel when it changes from being deactive to active.  Likewise,
       the Deactive event is sent when the window's state changes from active
       to deactive.  There are no use- ful percent substitutions you would
       make when binding to these events.

	   MouseWheel

       Some mice on the	Windows	platform support a mouse wheel	which  is used
       for  scrolling  documents  without using	the scrollbars.	 By rolling
       the wheel, the system will generate MouseWheel events that the
       application  can	use to scroll.	Like Key events	the event is always
       routed to the window that currently  has	 focus.	 When  the event is
       received	you can	use the	%D substitution	to get the delta field for the
       event which is a	integer	value of  motion  that	the mouse  wheel  has
       moved.  The smallest value for which the	system will report is defined
       by the OS.  On Windows  95  &  98  machines this	value is at least 120
       before it is reported.  However,	higher resolution devices may be
       available in the	future.	  The  sign  of	the  value  determines	which
       direction your widget should scroll.  Positive values should scroll up
       and negative values should scroll down.

       The last	part of	a long event specification is detail.  In the case of
       a ButtonPress or	ButtonRelease event, it	is the number of a button
       (1-5).  If a button number is given, then only an event on that
       particular button will match;  if no button number is given, then an
       event on	any button will	match.	Note:  giving a	specific button	number
       is different than specifying a button modifier; in the first case, it
       refers to a button being	pressed	or released, while in the second it
       refers to some other button that	is already depressed when the matching
       event occurs.  If a button number is given then type may	be omitted:
       if will default to ButtonPress.	For example, the specifier <1> is
       equivalent to <ButtonPress-1>.

       If the event type is KeyPress or	KeyRelease, then detail	may be
       specified in the	form of	an X keysym.  Keysyms are textual
       specifications for particular keys on the keyboard; they	include	all
       the alphanumeric	ASCII characters (e.g. ``a'' is	the keysym for the
       ASCII character ``a''), plus descriptions for non-alphanumeric
       characters (``comma'' is	the keysym for the comma character), plus
       descriptions for	all the	non-ASCII keys on the keyboard (``Shift_L'' is
       the keysm for the left shift key, and ``F1'' is the keysym for the F1
       function	key, if	it exists).  The complete list of keysyms is not
       presented here;	it is available	in other X documentation and may vary
       from system to system.  If necessary, you can use the 'K' notation
       described below to print	out the	keysym name for	a particular key.  If
       a keysym	detail is given, then the type field may be omitted;  it will
       default to KeyPress.  For example, <Control-comma> is equivalent	to
       <Control-KeyPress-comma>.

BINDING	CALLBACKS AND SUBSTITUTIONS
       The callback argument to	bind is	a perl/Tk callback.  which will	be
       executed	whenever the given event sequence occurs.  (See	Tk::callbacks
       for description of the possible forms.)	Callback will be associated
       with the	same MainWindow	that is	associated with	the $widget that was
       used to invoke the bind method, and it will run as though called	from
       MainLoop.  If callback contains any Ev(%) calls,	then each "nested"
       Ev(%) "callback"	will be	evaluated when the event occurs	to form
       arguments to be passed to the main callback.  The replacement depends
       on the character	%, as defined in the list below.  Unless otherwise
       indicated, the replacement string is the	numeric	(decimal) value	of the
       given field from	the current event. Perl/Tk has enhanced	this mechanism
       slightly	compared to the	comparable Tcl/Tk mechanism. The enhancements
       are not yet all reflected in the	list below.  Some of the substitutions
       are only	valid for certain types	of events;  if they are	used for other
       types of	events the value substituted is	undefined (not the same	as
       undef!).

       '#' The number of the last client request processed by the server (the
	   serial field	from the event).  Valid	for all	event types.

       'a' The above field from	the event, formatted as	a hexadecimal number.
	   Valid only for Configure events.

       'b' The number of the button that was pressed or	released.  Valid only
	   for ButtonPress and ButtonRelease events.

       'c' The count field from	the event.  Valid only for Expose events.

       'd' The detail field from the event.  The 'd' is	replaced by a string
	   identifying the detail.  For	Enter, Leave, FocusIn, and FocusOut
	   events, the string will be one of the following:

	    NotifyAncestor	    NotifyNonlinearVirtual
	    NotifyDetailNone	    NotifyPointer
	    NotifyInferior	    NotifyPointerRoot
	    NotifyNonlinear	    NotifyVirtual

	   For ConfigureRequest	events,	the string will	be one of:

	    Above		    Opposite
	    Below		    None
	    BottomIf		    TopIf

	   For events other than these,	the substituted	string is undefined.
	   (Note that this is not the same as Detail part of sequence use to
	   specify the event.)

       'f' The focus field from	the event (0 or	1).  Valid only	for Enter and
	   Leave events.

       'h' The height field from the event.  Valid only	for Configure,
	   ConfigureRequest, Create, Expose, and ResizeRequest events.

       'i' The window field from the  event,  represented  as  a  hexadecimal
	   integer.

       'k' The keycode field from the event.  Valid only for KeyPress and
	   KeyRelease events.

       'm' The mode field from the event.  The substituted string is one of
	   NotifyNormal, NotifyGrab, NotifyUngrab, or NotifyWhileGrabbed.
	   Valid only for Enter, FocusIn, FocusOut, and	Leave events.

       'o' The override_redirect field from the	event.	Valid only for Map,
	   Reparent, and Configure events.

       'p' The place field from	the event, substituted as one of the strings
	   PlaceOnTop or PlaceOnBottom.	 Valid only for	Circulate and
	   CirculateRequest events.

       's' The state field from	the event.  For	ButtonPress, ButtonRelease,
	   Enter, KeyPress, KeyRelease,	Leave, and Motion events, a decimal
	   string is substituted.  For Visibility, one of the strings
	   VisibilityUnobscured, VisibilityPartiallyObscured, and
	   VisibilityFullyObscured is substituted.

       't' The time field from the event.  Valid only for events that contain
	   a time field.

       'w' The width field from	the event.  Valid only for Configure,
	   ConfigueRequest, Create, Expose, and	ResizeREquest events.

       'x' The x field from the	event.	Valid only for events containing an x
	   field.

       'y' The y field from the	event.	Valid only for events containing a y
	   field.

       '@' The string "@x,y" where x and y are as above.  Valid	only for
	   events containing x and y fields.  This format is used my methods
	   of Tk::Text and similar widgets.

       'A' Substitutes the UNICODE character corresponding to the event, or
	   the empty string if the event doesn't correspond to a UNICODE
	   character (e.g. the shift key was pressed).	XmbLookupString	does
	   all the work	of translating from the	event to a UNICODE character.
	   Valid only for KeyPress and KeyRelease events.

       'B' The border_width field from the event.  Valid only for Configure,
	   ConfigureRequest and	Create events.

       'D' This	reports	the delta value	of a  MouseWheel  event.   The	delta
	   value  represents  the  rotation  units  the	 mouse wheel has been
	   moved.  On Windows 95 & 98 systems  the  smallest  value  for  the
	   delta is 120.  Future systems may support higher resolution values
	   for the delta.  The sign of the value represents the	direction the
	   mouse wheel was scrolled.

       'E' The send_event field	from the event.	 Valid for all event types.

       'K' The keysym corresponding to the event, substituted as a textual
	   string.  Valid only for KeyPress and	KeyRelease events.

       'N' The keysym corresponding to the event, substituted as a decimal
	   number.  Valid only for KeyPress and	KeyRelease events.

       'R' The root window identifier from the event.  Valid only for events
	   containing a	root field.

       'S' The subwindow window	identifier from	the event, as an object	if it
	   is one otherwise as a hexadecimal number.  Valid only for events
	   containing a	subwindow field.

       'T' The type field from the event.  Valid for all event types.

       'W' The window to which the event was reported (the $widget field from
	   the event) -	as an perl/Tk object.  Valid for all event types.

       'X' The x_root field from the event.  If	a virtual-root window manager
	   is being used then the substituted value is the corresponding
	   x-coordinate	in the virtual root.  Valid only for ButtonPress,
	   ButtonRelease, KeyPress, KeyRelease,	and Motion events.

       'Y' The y_root field from the event.  If	a virtual-root window manager
	   is being used then the substituted value is the corresponding
	   y-coordinate	in the virtual root.  Valid only for ButtonPress,
	   ButtonRelease, KeyPress, KeyRelease,	and Motion events.

MULTIPLE MATCHES
       It is possible for several bindings to match a given X event.  If the
       bindings	are associated with different tag's, then each of the bindings
       will be executed, in order.  By default,	a class	binding	will be
       executed	first, followed	by a binding for the widget, a binding for its
       toplevel, and an	all binding.  The bindtags method may be used to
       change this order for a particular window or to associate additional
       binding tags with the window.

       return and Tk->break may	be used	inside a callback to control the
       processing of matching callbacks.  If return is invoked,	then the
       current callback	is terminated but Tk will continue processing
       callbacks associated with other tag's.  If Tk->break is invoked within
       a callback, then	that callback terminates and no	other callbacks	will
       be invoked for the event.  (Tk->break is	implemented via	perl's die
       with a special value which is "caught" by the perl/Tk "glue" code.)

       If more than one	binding	matches	a particular event and they have the
       same tag, then the most specific	binding	is chosen and its callback is
       evaluated.  The following tests are applied, in order, to determine
       which of	several	matching sequences is more specific: (a) an event
       pattern that specifies a	specific button	or key is more specific	than
       one that	doesn't; (b) a longer sequence (in terms of number of events
       matched)	is more	specific than a	shorter	sequence; (c) if the modifiers
       specified in one	pattern	are a subset of	the modifiers in another
       pattern,	then the pattern with more modifiers is	more specific.	(d) a
       virtual event whose physical pattern matches the	sequence is less
       specific	than the same physical pattern that is not associated with a
       virtual event.  (e) given a sequence that matches two or	more virtual
       events, one of the virtual events will be chosen, but the order is
       undefined.

       If the matching sequences contain more than one event, then tests
       (c)-(e) are applied in order from the most recent event to the least
       recent event in the sequences.  If these	tests fail to determine	a
       winner, then the	most recently registered sequence is the winner.

       If there	are two	(or more) virtual events that are both triggered by
       the same	sequence, and both of those virtual events are bound to	the
       same window tag,	then only one of the virtual events will be triggered,
       and it will be picked at	random:

	$widget->eventAdd('<<Paste>>' => '<Control-y>');
	$widget->eventAdd('<<Paste>>' => '<Button-2>');
	$widget->eventAdd <<Scroll>>' => '<Button-2>');
	$widget->bind('Tk::Entry','<<Paste>>',sub { print 'Paste'});
	$widget->bind('Tk::Entry','<<Scroll>>',	sub {print 'Scroll'});

       If the user types Control-y, the	<<Paste>> binding will be invoked, but
       if the user presses button 2 then one of	either the <<Paste>> or	the
       <<Scroll>> bindings will	be invoked, but	exactly	which one gets invoked
       is undefined.

       If an X event does not match any	of the existing	bindings, then the
       event is	ignored.  An unbound event is not considered to	be an error.

MULTI-EVENT SEQUENCES AND IGNORED EVENTS
       When a sequence specified in a bind method contains more	than one event
       pattern,	then its callback is executed whenever the recent events
       (leading	up to and including the	current	event) match the given
       sequence.  This means, for example, that	if button 1 is clicked
       repeatedly the sequence <Double-ButtonPress-1> will match each button
       press but the first.  If	extraneous events that would prevent a match
       occur in	the middle of an event sequence	then the extraneous events are
       ignored unless they are KeyPress	or ButtonPress events.	For example,
       <Double-ButtonPress-1> will match a sequence of presses of button 1,
       even though there will be ButtonRelease events (and possibly Motion
       events) between the ButtonPress events.	Furthermore, a KeyPress	event
       may be preceded by any number of	other KeyPress events for modifier
       keys without the	modifier keys preventing a match.  For example,	the
       event sequence aB will match a press of the a key, a release of the a
       key, a press of the Shift key, and a press of the b key:	 the press of
       Shift is	ignored	because	it is a	modifier key.  Finally,	if several
       Motion events occur in a	row, only the last one is used for purposes of
       matching	binding	sequences.

ERRORS
       If an error occurs in executing the callback for	a binding then the
       Tk::Error mechanism is used to report the error.	 The Tk::Error
       mechanism will be executed at same call level, and associated with the
       same MainWindow as as the callback was invoked.

CAVEATS
       Note that for the Canvas	widget,	the call to bind has to	be fully
       qualified. This is because there	is already a bind method for the
       Canvas widget, which binds individual canvas tags.

       A A A A $canvas->Tk::bind

SEE ALSO
       Tk::Error Tk::callbacks Tk::bindtags

KEYWORDS
       Event, binding

perl v5.32.1			  2013-11-15			       bind(3)

NAME | SYNOPSIS | DESCRIPTION | EVENT PATTERNS | MODIFIERS | EVENT TYPES | BINDING CALLBACKS AND SUBSTITUTIONS | MULTIPLE MATCHES | MULTI-EVENT SEQUENCES AND IGNORED EVENTS | ERRORS | CAVEATS | SEE ALSO | KEYWORDS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Tk::bind&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help