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

FreeBSD Manual Pages

  
 
  

home | help
event(n)		     Tk	Built-In Commands		      event(n)

______________________________________________________________________________

NAME
       event  -	Miscellaneous event facilities:	define virtual events and gen-
       erate events

SYNOPSIS
       event option ?arg arg ...?
______________________________________________________________________________

DESCRIPTION
       The event command provides several facilities for dealing  with	window
       system events, such as defining virtual events and synthesizing events.
       The command has several different forms,	determined by the first	 argu-
       ment.  The following forms are currently	supported:

       event add <<virtual>> sequence ?sequence	...?
	      Associates the virtual event virtual with	the physical event se-
	      quence(s)	given by the sequence arguments, so that  the  virtual
	      event  will  trigger  whenever  any one of the sequences occurs.
	      Virtual may be any string	value and sequence may have any	of the
	      values  allowed  for  the	sequence argument to the bind command.
	      If virtual is already defined, the new physical event  sequences
	      add to the existing sequences for	the event.

       event delete <<virtual>>	?sequence sequence ...?
	      Deletes  each  of	 the  sequences	from those associated with the
	      virtual event given by virtual.  Virtual may be any string value
	      and sequence may have any	of the values allowed for the sequence
	      argument to the bind command.  Any sequences not currently asso-
	      ciated  with  virtual  are  ignored.  If no sequence argument is
	      provided,	all physical event sequences are removed for  virtual,
	      so that the virtual event	will not trigger anymore.

       event generate window event ?option value option	value ...?
	      Generates	 a  window  event  and arranges	for it to be processed
	      just as if it had	come from the window system.  Window gives the
	      path  name  of the window	for which the event will be generated;
	      it may also be an	identifier (such as returned by	winfo  id)  as
	      long  as	it  is for a window in the current application.	 Event
	      provides a basic description of the event, such  as  <Shift-But-
	      ton-2>  or  <<Paste>>.   If  Window is empty the whole screen is
	      meant, and coordinates are relative to the  screen.   Event  may
	      have  any	 of the	forms allowed for the sequence argument	of the
	      bind command except that it must consist of a single event  pat-
	      tern, not	a sequence.  Option-value 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 -when option	is not
	      specified, the event is processed	immediately:  all of the  han-
	      dlers for	the event will complete	before the event generate com-
	      mand returns.  If	the -when option is specified then  it	deter-
	      mines  when the event is processed.  Certain events, such	as key
	      events, require that the window has focus	to receive  the	 event
	      properly.

       event info ?<<virtual>>?
	      Returns  information  about  virtual events.  If the <<virtual>>
	      argument is omitted, the return value is a list of all the  vir-
	      tual events that are currently defined.  If <<virtual>> is spec-
	      ified 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	string
	      is returned.

	      Note  that  virtual  events  that	that are not bound to physical
	      event sequences are not returned by event	info.

EVENT FIELDS
       The following options are supported for	the  event  generate  command.
       These  correspond  to the "%" expansions	allowed	in binding scripts for
       the bind	command.

       -above window
	      Window specifies the above field for the event, either as	a win-
	      dow  path	 name or as an integer window id.  Valid for Configure
	      events.  Corresponds to the %a substitution for binding scripts.

       -borderwidth size
	      Size must	be a screen distance;  it specifies  the  border_width
	      field  for  the event.  Valid for	Configure events.  Corresponds
	      to the %B	substitution for binding scripts.

       -button number
	      Number must be an	integer;  it specifies the detail field	for  a
	      ButtonPress  or ButtonRelease event, overriding any button  num-
	      ber provided in the base event argument.	Corresponds to the  %b
	      substitution for binding scripts.

       -count number
	      Number must be an	integer;  it specifies the count field for the
	      event.  Valid for	Expose events.	Corresponds to the %c  substi-
	      tution for binding scripts.				       |

       -data string							       |
	      String  may  be  any value; it specifies the user_data field for |
	      the event.  Only valid for virtual events.  Corresponds  to  the |
	      %d substitution for virtual events in binding scripts.

       -delta number
	      Number must be an	integer;  it specifies the delta field for the
	      MouseWheel event.	 The delta refers to the direction and	magni-
	      tude  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 de-
	      fine different behaviors for mouse  wheel	 motion.   This	 field
	      corresponds to the %D substitution for binding scripts.

       -detail detail
	      Detail  specifies	the detail field for the event and must	be one
	      of the following:

		     NotifyAncestor	     NotifyNonlinearVirtual
		     NotifyDetailNone	     NotifyPointer
		     NotifyInferior	     NotifyPointerRoot
		     NotifyNonlinear	     NotifyVirtual

	      Valid for	Enter, Leave, FocusIn  and  FocusOut  events.	Corre-
	      sponds to	the %d substitution for	binding	scripts.

       -focus boolean
	      Boolean  must  be	a boolean value;  it specifies the focus field
	      for the event.  Valid for	Enter and Leave	 events.   Corresponds
	      to the %f	substitution for binding scripts.

       -height size
	      Size  must  be a screen distance;	 it specifies the height field
	      for the event.  Valid for	Configure events.  Corresponds to  the
	      %h substitution for binding scripts.

       -keycode	number
	      Number   must be an integer;  it specifies the keycode field for
	      the event.  Valid	for KeyPress and  KeyRelease  events.	Corre-
	      sponds to	the %k substitution for	binding	scripts.

       -keysym name
	      Name  must  be  the name of a valid keysym, such as g, space, or
	      Return;  its corresponding keycode value is used as the  keycode
	      field  for  event,  overriding  any detail specified in the base
	      event argument.  Valid for KeyPress and KeyRelease events.  Cor-
	      responds to the %K substitution for binding scripts.

       -mode notify
	      Notify specifies the mode	field for the event and	must be	one of
	      NotifyNormal, NotifyGrab,	NotifyUngrab,  or  NotifyWhileGrabbed.
	      Valid  for  Enter,  Leave, FocusIn, and FocusOut events.	Corre-
	      sponds to	the %m substitution for	binding	scripts.

       -override boolean
	      Boolean must be a	boolean	value;	it specifies the  override_re-
	      direct  field  for the event.  Valid for Map, Reparent, and Con-
	      figure events.  Corresponds to the %o substitution  for  binding
	      scripts.

       -place where
	      Where  specifies	the place field	for the	event;	it must	be ei-
	      ther PlaceOnTop or PlaceOnBottom.	 Valid for  Circulate  events.
	      Corresponds to the %p substitution for binding scripts.

       -root window
	      Window  must  be	either a window	path name or an	integer	window
	      identifier;  it specifies	the root field for the	event.	 Valid
	      for  KeyPress,  KeyRelease,  ButtonPress,	 ButtonRelease,	Enter,
	      Leave, and Motion	events.	 Corresponds to	 the  %R  substitution
	      for binding scripts.

       -rootx coord
	      Coord  must be a screen distance;	 it specifies the x_root field
	      for the event.  Valid  for  KeyPress,  KeyRelease,  ButtonPress,
	      ButtonRelease,  Enter, Leave, and	Motion events.	Corresponds to
	      the %X substitution for binding scripts.

       -rooty coord
	      Coord must be a screen distance;	it specifies the y_root	 field
	      for  the	event.	 Valid	for KeyPress, KeyRelease, ButtonPress,
	      ButtonRelease, Enter, Leave, and Motion events.  Corresponds  to
	      the %Y substitution for binding scripts.

       -sendevent boolean
	      Boolean  must  be	 a boolean value;  it specifies	the send_event
	      field for	the event.  Valid for all events.  Corresponds to  the
	      %E substitution for binding scripts.

       -serial number
	      Number  must  be	an integer;  it	specifies the serial field for
	      the event.  Valid	for all	events.	 Corresponds to	the %# substi-
	      tution for binding scripts.

       -state state
	      State  specifies	the  state field for the event.	 For KeyPress,
	      KeyRelease, ButtonPress, ButtonRelease, Enter, Leave, and	Motion
	      events  it  must	be an integer value.  For Visibility events it
	      must  be	one  of	 VisibilityUnobscured,	VisibilityPartiallyOb-
	      scured,  or  VisibilityFullyObscured.  This option overrides any
	      modifiers	such as	Meta or	Control	specified in the  base	event.
	      Corresponds to the %s substitution for binding scripts.

       -subwindow window
	      Window  specifies	the subwindow field for	the event, either as a
	      path name	for a Tk widget	or as an  integer  window  identifier.
	      Valid  for KeyPress, KeyRelease, ButtonPress, ButtonRelease, En-
	      ter, Leave, and Motion events.  Similar to %S  substitution  for
	      binding scripts.

       -time integer
	      Integer  must  be	an integer value;  it specifies	the time field
	      for the event.  Valid  for  KeyPress,  KeyRelease,  ButtonPress,
	      ButtonRelease,  Enter, Leave, Motion, and	Property events.  Cor-
	      responds to the %t substitution for binding scripts.

       -warp boolean
	      boolean must be a	 boolean  value;   it  specifies  whether  the
	      screen  pointer  should  be warped as well.  Valid for KeyPress,
	      KeyRelease, ButtonPress, ButtonRelease, and Motion events.   The
	      pointer will only	warp to	a window if it is mapped.

       -width size
	      Size  must  be  a	screen distance;  it specifies the width field
	      for the event.  Valid for	Configure events.  Corresponds to  the
	      %w substitution for binding scripts.

       -when when
	      When  determines when the	event will be processed;  it must have
	      one of the following values:

	      now	Process	the event immediately, before the command  re-
			turns.	This also happens if the -when option is omit-
			ted.

	      tail	Place the event	on Tcl's event queue behind any	events
			already	queued for this	application.

	      head	Place  the event at the	front of Tcl's event queue, so
			that it	will be	handled	before any  other  events  al-
			ready queued.

	      mark	Place  the event at the	front of Tcl's event queue but
			behind any other  events  already  queued  with	 -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.

       -x coord
	      Coord  must  be a	screen distance;  it specifies the x field for
	      the event.  Valid	for KeyPress, KeyRelease, ButtonPress, Button-
	      Release,	Motion,	 Enter,	Leave, Expose, Configure, Gravity, and
	      Reparent events.	Corresponds to the %x substitution for binding
	      scripts.	 If  Window is empty the coordinate is relative	to the
	      screen, and this option corresponds to the %X  substitution  for
	      binding scripts.

       -y coord
	      Coord  must  be a	screen distance;  it specifies the y field for
	      the event.  Valid	for KeyPress, KeyRelease, ButtonPress, Button-
	      Release,	Motion,	 Enter,	Leave, Expose, Configure, Gravity, and
	      Reparent events.	Corresponds to the %y substitution for binding
	      scripts.	 If  Window is empty the coordinate is relative	to the
	      screen, and this option corresponds to the %Y  substitution  for
	      binding scripts.

       Any  options that are not specified when	generating an event are	filled
       with the	value 0, except	for serial, which is filled with  the  next  X
       event serial number.

PREDEFINED VIRTUAL EVENTS
       Tk  defines  the	following virtual events for the purposes of notifica-
       tion:

       <<AltUnderlined>>
	      This is sent to widget to	notify it that the letter it  has  un-
	      derlined	(as  an	accelerator indicator) with the	-underline op-
	      tion has been pressed in combination with	the Alt	key. The usual
	      response to this is to either focus into the widget (or some re-
	      lated widget) or to invoke the widget.

       <<Invoke>>
	      This can be sent to some widgets (e.g. button, listbox, menu) as
	      an alternative to	<space>.

       <<ListboxSelect>>
	      This  is	sent  to a listbox when	the set	of selected item(s) in
	      the listbox is updated.

       <<MenuSelect>>
	      This is sent to a	menu when the currently	selected item  in  the
	      menu changes. It is intended for use with	context-sensitive help
	      systems.

       <<Modified>>
	      This is sent to a	text widget when the contents  of  the	widget
	      are changed.

       <<Selection>>
	      This  is	sent to	a text widget when the selection in the	widget
	      is changed.

       <<ThemeChanged>>
	      This is sent to a	text widget when the ttk (Tile)	theme changed.

       <<TraverseIn>>
	      This is sent to a	widget when the	focus enters  the  widget  be-
	      cause of a user-driven "tab to widget" action.

       <<TraverseOut>>
	      This  is	sent  to a widget when the focus leaves	the widget be-
	      cause of a user-driven "tab to widget" action.

       Tk defines the following	virtual	events for the	purposes  of  unifying
       bindings	 across	multiple platforms. Users expect them to behave	in the
       following way:

       <<Clear>>
	      Delete the currently selected widget contents.

       <<Copy>>
	      Copy the currently selected widget contents to the clipboard.

       <<Cut>>
	      Move the currently selected widget contents to the clipboard.

       <<Paste>>
	      Replace the currently selected widget contents with the contents
	      of the clipboard.

       <<PasteSelection>>
	      Insert  the  contents  of	 the  selection	at the mouse location.
	      (This event has meaningful %x and	%y substitutions).

       <<PrevWindow>>
	      Traverse to the previous window.

       <<Redo>>
	      Redo one undone action.

       <<Undo>>
	      Undo the last action.

VIRTUAL	EVENT EXAMPLES
       In order	for a virtual event binding to trigger,	two things  must  hap-
       pen.   First, the virtual event must be defined with the	event add com-
       mand.  Second, a	binding	must be	created	for the	virtual	event with the
       bind command.  Consider the following virtual event definitions:
	      event add	<<Paste>> <Control-y>
	      event add	<<Paste>> <Button-2>
	      event add	<<Save>> <Control-X><Control-S>
	      event add	<<Save>> <Shift-F12>
       In  the	bind  command,	a  virtual  event  can be bound	like any other
       builtin event type as follows:
	      bind Entry <<Paste>> {%W insert [selection get]}
       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
       <<Paste>> virtual event is synthesized with event  generate,  then  the
       <<Paste>> 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:
	      event add	<<Paste>> <Control-y> <Meta-Control-y>
	      bind Entry <Control-y> {puts Control-y}
	      bind Entry <<Paste>> {puts Paste}
       When  the user types Control-y the <Control-y> 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 <<Paste>> binding will be invoked, because the  Meta
       modifier	in the physical	pattern	associated with	the virtual binding is
       more specific than the <Control-y> sequence for the physical event.

       Bindings	on a virtual event may be created before the virtual event ex-
       ists.   Indeed,	the  virtual event never actually needs	to be defined,
       for instance, on	platforms where	the specific virtual  event  would  be
       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 pre-
       ceding example, if the following	code is	executed:
	      bind <Entry> <Control-y> {}
	      event add	<<Paste>> <Key-F6>
       the  behavior  will  change  such  in  two  ways.   First, the shadowed
       <<Paste>> binding will emerge.  Typing Control-y	will no	longer	invoke
       the   <Control-y>   binding,  but  instead  invoke  the	virtual	 event
       <<Paste>>.  Second, pressing the	 F6  key  will	now  also  invoke  the
       <<Paste>> binding.

SEE ALSO
       bind(n)

KEYWORDS
       event, binding, define, handle, virtual event

Tk				      8.3			      event(n)

NAME | SYNOPSIS | DESCRIPTION | EVENT FIELDS | PREDEFINED VIRTUAL EVENTS | VIRTUAL EVENT EXAMPLES | SEE ALSO | KEYWORDS

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

home | help