NAME

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


SYNOPSIS

       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
_________________________________________________________________


DESCRIPTION

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


INTRODUCTION

       There  are  many  times  in applications where you want to
       temporarily restrict 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 hierarchy, disabling each widget and re-configuring
       its cursor.

       Often,  the  busy command can be used instead of Tk's grab

       tions  to  one  widget, with the busy command you can have
       more than one widget active (for example, a "cancel"  dia­
       log and a "help" button).


EXAMPLE

       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
              update

       All the widgets within .top (including .top) are now busy.
       Using  update  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 allo­
       cated.

            busy forget .top

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


OPERATIONS

       The  following  operations are available for the busy com­
       mand:

       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  widget.   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  immediately afterward to insure

              application  starts  its  processing. The following
              configuration 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 opera­
              tion.  If no options are specified, a list describ­
              ing  all  of  the available options for window (see
              Tk_ConfigureInfo for information on the  format  of
              this  list)  is  returned.   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 option(s) to have
              the  given  value(s);  in  this  case  the  command
              returns  the  empty string.  Option may have any of
              the values accepted by the hold operation.

              Please note that the option database is  referenced
              through  window.  For example, if the widget .frame
              is to be made busy, the busy cursor can  be  speci­
              fied 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, including the busy window.  User events
              will  again be received again by window.  Resources
              are also released when window is destroyed.  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  cur­
              rently 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 pre­
              viously been made busy (i.e. a busy window is allo­
              cated and associated with the widget).  It makes no

              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 reported.

       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 window
              associated with it).  If window  is  presently  can
              not  receive user interactions, 1 is returned, oth­
              erwise 0.


BINDINGS

       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.can­
       vas_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 example, the pathname
       of the busy window is "._Busy"

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


ENTER/LEAVE EVENTS

       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
              update

       The above example moves the focus from .frame  immediately
       after invoking the hold so that no keyboard events will be
       sent to


KEYWORDS

       busy, keyboard events, pointer events, window, cursor


Man(1) output converted with man2html