* added some docco for [update] changes.

- obviates [vwait] and provides a new way into event loop

doc/update.n

@@ -12,14 +12,14 @@
 .SH NAME
 update \- Process pending events and idle callbacks
 .SH SYNOPSIS
-\fBupdate\fR ?\fBidletasks\fR?
+\fBupdate\fR ?\fIoption ...\fR?
 .BE
 .SH DESCRIPTION
 .PP
 This command is used to bring the application
 .QW "up to date"
 by entering the event loop repeatedly until all pending events
-(including idle callbacks) have been processed.
+(including idle callbacks, if specified) have been processed.
 .PP
 If the \fBidletasks\fR keyword is specified as an argument to the
 command, then no new events or errors are processed;  only idle
@@ -27,6 +27,16 @@ callbacks are invoked.
 This causes operations that are normally deferred, such as display
 updates and window layout calculations, to be performed immediately.
 .PP
+Options accepted are
+	\fBidletasks\fR - process any pending window events or idle events, do not wait
+	\fBwindow\fR - process window events
+	\fBfile\fR - process file events
+	\fBtimer\fR - process timer events
+	\fBonlyidle\fR - process only idle events
+	\fBall\fR - process all events
+	\fBwait\fR - wait until at least one event has been processed
+	\fBnowait\fR - return immediately if no events are pending.
+.PP
 The \fBupdate idletasks\fR command is useful in scripts where
 changes have been made to the application's state and you want those
 changes to appear on the display immediately, rather than waiting
@@ -60,6 +70,6 @@ while {!$done} {
 }
 .CE
 .SH "SEE ALSO"
-after(n), interp(n)
+after(n), interp(n), Tcl_DoOneEvent(3)
 .SH KEYWORDS
 asynchronous I/O, event, flush, handler, idle, update

generic/tclEvent.c

@@ -1497,26 +1497,49 @@ Tcl_UpdateObjCmd(
 {
     int optionIndex;
     int flags = 0;		/* Initialized to avoid compiler warning. */
-    static const char *const updateOptions[] = {"idletasks", NULL};
-    enum updateOptions {OPT_IDLETASKS};
+    int index;
+    static const char *const updateOptions[] = {"idletasks", "window", "file", "timer", "onlyidle", "all", "wait", "nowait", NULL};
+    enum updateOptions {OPT_IDLETASKS, OPT_WINDOW, OPT_FILE, OPT_TIMER, OPT_ONLYIDLE, OPT_ALL, OPT_WAIT, OPT_NOWAIT};
 
     if (objc == 1) {
 	flags = TCL_ALL_EVENTS|TCL_DONT_WAIT;
-    } else if (objc == 2) {
-	if (Tcl_GetIndexFromObj(interp, objv[1], updateOptions,
-		"option", 0, &optionIndex) != TCL_OK) {
-	    return TCL_ERROR;
-	}
-	switch ((enum updateOptions) optionIndex) {
-	case OPT_IDLETASKS:
-	    flags = TCL_WINDOW_EVENTS|TCL_IDLE_EVENTS|TCL_DONT_WAIT;
-	    break;
-	default:
-	    Tcl_Panic("Tcl_UpdateObjCmd: bad option index to UpdateOptions");
-	}
     } else {
-	Tcl_WrongNumArgs(interp, 1, objv, "?idletasks?");
-	return TCL_ERROR;
+	flags = 0;
+	for (index = 1; index < objc; index++) {
+	    if (Tcl_GetIndexFromObj(interp, objv[index], updateOptions,
+				    "option", 0, &optionIndex) != TCL_OK) {
+		return TCL_ERROR;
+	    }
+
+	    switch ((enum updateOptions) optionIndex) {
+	    case OPT_IDLETASKS:
+		flags = TCL_WINDOW_EVENTS|TCL_IDLE_EVENTS|TCL_DONT_WAIT;
+		break;
+	    case OPT_WINDOW:
+		flags |= TCL_WINDOW_EVENTS;	// Process window system events.
+		break;
+	    case OPT_FILE:
+		flags |= TCL_FILE_EVENTS; 	// Process file events.
+		break;
+	    case OPT_TIMER:
+		flags |= TCL_TIMER_EVENTS;	// Process timer events.
+		break;
+	    case OPT_ONLYIDLE:
+		flags |= TCL_IDLE_EVENTS;	// Process idle callbacks.
+		break;
+	    case OPT_ALL:
+		flags |= TCL_ALL_EVENTS;	// Process all kinds of events
+		break;
+	    case OPT_WAIT:
+		flags &= ~TCL_DONT_WAIT;	// Sleep until an event occurs
+		break;
+	    case OPT_NOWAIT:
+		flags |= TCL_DONT_WAIT;	// Do not sleep:  process only events that are ready at the time of the call.
+		break;
+	    default:
+		Tcl_Panic("Tcl_UpdateObjCmd: bad option index to UpdateOptions");
+	    }
+	}
     }
 
     while (Tcl_DoOneEvent(flags) != 0) {

tests/event.test

@@ -614,10 +614,10 @@ test event-11.8 {Bug 16828b3744} -setup {
 
 test event-12.1 {Tcl_UpdateCmd procedure} -returnCodes error -body {
     update a b
-} -result {wrong # args: should be "update ?idletasks?"}
+} -result {bad option "b": must be idletasks, window, file, timer, onlyidle, all, wait, or nowait}
 test event-12.2 {Tcl_UpdateCmd procedure} -returnCodes error -body {
     update bogus
-} -result {bad option "bogus": must be idletasks}
+} -result {bad option "bogus": must be idletasks, window, file, timer, onlyidle, all, wait, or nowait}
 test event-12.3 {Tcl_UpdateCmd procedure} -setup {
     foreach i [after info] {
 	after cancel $i