This is not necessarily the current version of this TIP.This is not necessarily the current version of this TIP.
| TIP: | 321 |
| Title: | Add a tk::busy Command |
| Version: | $Revision: 1.3 $ |
| Author: | Jos Decoster <jos dot decoster at gmail dot com> |
| State: | Draft |
| Type: | Project |
| Tcl-Version: | 8.6 |
| Vote: | In progress |
| Created: | Thursday, 26 June 2008 |
| Keywords: | Tk, BLT, busy |
The blt::busy commands can be used to make Tk widget busy, with all user interaction blocked and the cursor can be changed to e.g. a clock. This TIP proposes to add this useful feature to Tk.
BLT has a lot of very useful commands: bgexec, busy, vector, graph widget, barchart widget, ... But getting BLT to work with the latest releases of Tcl and Tk becomes more and more difficult. Some of the problems I experienced are:
internal Tk structures are mirrored
interaction with xft fails, so Tk has to be build without xft support
the build process is different from the one used in Tcl and Tk
Discussions on CLT and #tcl indicated that extracting functionality from BLT and add it to Tcl and Tk might be a good way to make the blt commands available for every Tcl programmer.
This TIP proposes a way to add the blt::busy command to Tk, based on the code as found in BLT2.4z and the code as found in busy.kit. While adding the code to Tk, it was rewritten to use the Tcl_Obj interface and the new option interface.
The name of this new Tk command as currently implemented is tk::busy. Adding it as an option to the grab command might cause confusion as the tk::busy command has the opposite functionality of the grab command. It blocks all user interaction rather than redirecting it to one widget. Another alternative is adding it to the ensemble of tk commands (tk appname, tk scaling, tk inactive, ...).
The tk::busy command is an ensemble with a special feature that any unrecognized subcommand that starts with a period is treated as an invokation of the hold subcommand upon the widget with that name.
tk::busy window ?option value?
tk::busy hold window ?option value?
Makes the window (and its descendants in the Tk window hierarchy) appear busy by ignoring all events sent to the window and its descendants. Window must be a valid path name of a Tk widget. A transparent window is put in front of the specified window. This transparent window is mapped the next time idle tasks are processed, and the specified window and its descendants will be blocked from user interactions. Normally update should be called immediately afterward to insure that the hold operation is in effect before the 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.
tk::busy forget window
Releases resources allocated by the tk::busy command for window, including the transparent window. User events will again be received by the specified window. Resources are also released when the specified window is destroyed. Window must be the name of a widget previously specified in a hold operation, otherwise an error is reported.
tk::busy release window
Restores user interactions to the window again. This differs from the forget operation in that the transparent window is not destroyed, but simply unmapped. Window must be the name of a window previously specified in a hold operation, otherwise an error is reported.
tk::busy isbusy ?pattern?
Returns the pathnames of all windows that are currently made busy. If a pattern is given, only the path names of busy windows matching pattern are returned.
tk::busy names ?pattern?
Returns the pathnames of all windows that have previously been made busy (i.e. a busy window is allocated and associated with the window). It makes no difference if the window is currently busy or not. If a pattern is given, only the path names of windows matching pattern are returned.
tk::busy status window
Returns the busy status of a window. If window presently can not receive user interactions, 1 is returned, otherwise 0.
tk::busy configure window ?option? ?value ...?
Queries or modifies the tk::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_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. Options 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 specified for it by either option command:
option add *frame.busyCursor gumby
option add *Frame.BusyCursor gumby
tk::busy cget window option
Queries the tk::busy command configuration options for window. Window must be the path name of a widget previously made busy by the hold operation. The command returns the present value of the specified option. Option may have any of the values accepted by the hold operation.
See SourceForge patch #1997907 [1].
Because the command as proposed above has the same interface and behavior as the blt::busy command, replacing blt::busy with tk::busy is all that's needed to switch to the Tk version of the busy command.
The busy command is available as starkit from http://tcl.tk/starkits/busy.kit
The tk::busy forget and tk::busy release commands could be replaced by one single command with the forget functionality. The confusing difference between a window which is busy, a window which was busy but still has the associated transparent window allocated and a window which was but no longer has its associated transparent window but could removed by simplifying the command. Because often the same window is made busy again and again, using release in stead of forget might be faster. But when making an application busy, it's because it'll have to wait for another operation and/or process to finish which will typically take a much longer time than the time needed to (re)create the transparent window. Simplified command:
tk::busy window ?option value?
tk::busy hold window ?option value?
Same as above
tk::busy forget window
Same as above and replaces the tk::busy release command.
tk::busy current ?pattern?
Returns a list of pathnames of all windows currently made busy. If a pattern is given, only the path names of busy windows matching pattern are returned. This commands replaces the isbusy and names commands.
tk::busy status window
Same as above
tk::busy configure window ?option? ?value ...?
Same as above
tk::busy cget window option
Same as above
This simplified command is no longer one-by-one compatible with the BLT command. But typical use (hold and forget/release) will not suffer a lot. Aliases or a namespace ensemble could be used to make transition easier.
This document has been placed in the public domain.
This is not necessarily the current version of this TIP.