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

FreeBSD Manual Pages


home | help
busy(n)			     BLT Built-In Commands		       busy(n)


       busy - Make Tk widgets busy, temporarily	blocking user interactions.

       busy hold window	?option	value?...

       busy release window ?window?...

       busy configure window ?option value?...

       busy forget window ?window?...

       busy isbusy ?pattern?

       busy names ?pattern?

       busy status window

       The busy	command	provides a simple means	to block keyboard, button, and
       pointer events from Tk widgets, while overriding	 the  widget's	cursor
       with a configurable busy	cursor.

       There  are many times in	applications where you want to temporarily re-
       strict what actions the user can	take.	For  example,  an  application
       could  have  a "run" button that	when pressed causes some processing to
       occur.  But while the application  is  busy  processing,	 you  probably
       don't  want  the	 the  user to be able to click the "run" button	again.
       You may also want restrict the user from	other tasks such as clicking a
       "print" button.

       The  busy  command  lets	you make Tk widgets busy. This means that user
       interactions such as button clicks, moving the  mouse,  typing  at  the
       keyboard, etc. are ignored by the widget.  You can set a	special	cursor
       (like a watch) that overrides the  widget's  normal  cursor,  providing
       feedback	that the application (widget) is temporarily busy.

       When  a widget is made busy, the	widget and all of its descendents will
       ignore events.  It's easy to make an entire panel of widgets busy.  You
       can simply make the toplevel widget (such as ".") busy.	This is	easier
       and far much more efficient than	recursively traversing the widget  hi-
       erarchy,	disabling each widget and re-configuring its cursor.

       Often,  the busy	command	can be used instead of Tk's grab command.  Un-
       like grab which restricts all user interactions to one widget, with the
       busy  command  you can have more	than one widget	active (for example, a
       "cancel"	dialog and a "help" button).

       You can make several widgets busy by simply making its ancestor	widget
       busy using the hold operation.

	      frame .top
	      button .top.button; canvas .top.canvas
	      pack .top.button .top.canvas
	      pack .top
		. . .
	      busy hold	.top

       All  the	 widgets within	.top (including	.top) are now busy.  Using up-
       date insures that busy command will take	effect before any  other  user
       events can occur.

       When  the  application is no longer busy	processing, you	can allow user
       interactions again by the release operation.

	 busy release .top

       The busy	window has a configurable cursor.  You	can  change  the  busy
       cursor using the	configure operation.

	 busy configure	.top -cursor "watch"

       Finally,	 when you no longer need to the	busy window, invoke the	forget
       operation to free any resources it allocated.

	 busy forget .top

       Destroying the widget will also clean up	any resources allocated	by the
       busy command.

       The following operations	are available for the busy command:

       busy hold window	?option	value?...
	      Makes  the  widget  window (and its descendants in the Tk	window
	      hierarchy) busy.	Window must be a valid path name of a Tk  wid-
	      get.   The  busy	window	is mapped the next time	idle tasks are
	      processed, and the widget	and its	descendants  will  be  blocked
	      from  user interactions. All events in the widget	window and its
	      descendants are ignored.	Normally update	should be called imme-
	      diately afterward	to insure that the hold	operation is in	effect
	      before the application starts its	processing. The	following con-
	      figuration options are valid:

	      -cursor cursorName
		     Specifies	the  cursor to be displayed when the widget is
		     made busy.	 CursorName can	be in  any  form  accepted  by
		     Tk_GetCursor.  The	default	cursor is watch.

       busy configure window ?option value?...
	      Queries  or  modifies the	busy command configuration options for
	      window. Window must be the path name of a	widget previously made
	      busy by the hold operation.  If no options are specified,	a list
	      describing all of	the available options for window (see  Tk_Con-
	      figureInfo  for  information  on the format of this list)	is re-
	      turned.  If option is specified with no value, then the  command
	      returns  a  list describing the one named	option (this list will
	      be identical to the corresponding	sublist	of the value  returned
	      if  no  option is	specified).  If	one or more option-value pairs
	      are specified, then the command modifies the  given  widget  op-
	      tion(s) to have the given	value(s); in this case the command re-
	      turns the	empty string.  Option may have any of the  values  ac-
	      cepted by	the hold operation.

	      Please  note that	the option database is referenced through win-
	      dow.  For	example, if the	widget .frame is to be made busy,  the
	      busy cursor can be specified for it by either option command:

		option add *frame.busyCursor gumby
		option add *Frame.BusyCursor gumby

       busy forget window ?window?...
	      Releases resources allocated by the busy command for window, in-
	      cluding the busy window.	User events  will  again  be  received
	      again by window.	Resources are also released when window	is de-
	      stroyed. Window must be the name of a widget  specified  in  the
	      hold operation, otherwise	an error is reported.

       busy isbusy ?pattern?
	      Returns  the  pathnames  of all widgets that are currently busy.
	      If a pattern is given, the path names of busy  widgets  matching
	      pattern are returned.

       busy names ?pattern?
	      Returns  the  pathnames of all widgets that have previously been
	      made busy	(i.e. a	busy window is allocated and  associated  with
	      the  widget).  It	makes no difference if the window is currently
	      busy or not.  If a pattern is given, the path names of busy wid-
	      gets matching pattern are	returned.

       busy release window ?window?...
	      Restores	user  interactions  to	the widget window again.  This
	      differs from the forget operation	in that	the busy window	is not
	      destroyed,  but  simply  unmapped.  Window must be the name of a
	      widget specified in a hold operation, otherwise an error is  re-

       busy status window
	      Returns  the status of a widget window previously	made busy.  An
	      error is reported	if window was never made busy, or  the	forget
	      operation	 was invoked (i.e. does	not currently have a busy win-
	      dow associated with it).	If window is presently can not receive
	      user interactions, 1 is returned,	otherwise 0.

       The  event  blocking  feature  is implemented by	creating and mapping a
       transparent window that completely covers the widget.   When  the  busy
       window  is  mapped,  it	invisibly shields the widget and its hierarchy
       from all	events that may	be sent.  Like Tk widgets, busy	 windows  have
       widget  names  in the Tk	window hierarchy.  This	means that you can use
       the bind	command, to handle events in the busy window.

	      busy hold	.frame.canvas
	      bind .frame.canvas_Busy <Enter> {	... }

       Normally	the busy window	is a sibling of	the widget.  The name  of  the
       busy  window is "widget_Busy" where widget is the name of the widget to
       be made busy.  In the previous example, the pathname of the busy	window
       is  ".frame.canvas_Busy"	The exception is when the widget is a toplevel
       widget (such as ".")  where the busy window can't be  made  a  sibling.
       The  busy  window  is  then  a child of the widget named	"widget._Busy"
       where widget is the name	of the toplevel	widget.	 In the	following  ex-
       ample, the pathname of the busy window is "._Busy"

	      busy hold	.
	      bind ._Busy <Enter> { ...	}

       Mapping and unmapping busy windows generates Enter/Leave	events for all
       widgets they cover.  Please note	this if	you are	 tracking  Enter/Leave
       events in widgets.

       When  a	widget	is made	busy, the widget is prevented from gaining the
       keyboard	focus by the busy window. But if the widget already had	focus,
       it  still may received keyboard events.	To prevent this, you must move
       focus to	another	window.

	      busy hold	.frame
	      label .dummy
	      focus .dummy

       The above example moves the focus from .frame immediately after	invok-
       ing  the	 hold so that no keyboard events will be sent to .frame	or any
       of its descendants.

       busy, keyboard events, pointer events, window, cursor

BLT				      2.5			       busy(n)


Want to link to this manual page? Use this URL:

home | help