Tk Source Code

View Ticket
Login
2026-09-25
08:31 • Closed ticket [44eff211]: bind scripts: documentation on return codes. plus 4 other changes artifact: 86c19a7c user: serhiy.storchaka
2017-09-16
08:24 • Closed ticket [d0c55bd7]: tkBind.c : incorrect documentation for continue/break/ok plus 5 other changes artifact: 88a25439 user: fvogel
08:23
Fix [d0c55bd78a]: inaccurate documentation for continue/break/ok in binding scripts. Thanks to Brad Lanam. check-in: 921f10ca user: fvogel tags: trunk
08:22
Fix [d0c55bd78a]: inaccurate documentation for continue/break/ok in binding scripts. Thanks to Brad Lanam. check-in: c0dbd605 user: fvogel tags: core-8-6-branch
2017-09-03
10:12 • Ticket [d0c55bd7] tkBind.c : incorrect documentation for continue/break/ok status still Open with 5 other changes artifact: 0c839c20 user: fvogel
10:09
Fix [d0c55bd78a]: inaccurate documentation for continue/break/ok in binding scripts. Thanks to Brad Lanam. closed check-in: e69ed726 user: fvogel tags: bug-d0c55bd78a
2017-09-01
14:28 • Ticket [d0c55bd7] tkBind.c : incorrect documentation for continue/break/ok status still Open with 3 other changes artifact: 9b460d42 user: bll
12:15 • Ticket [d0c55bd7]: 3 changes artifact: bfbe0c52 user: bll
2017-08-31
19:36 • Ticket [d0c55bd7]: 3 changes artifact: 5e3f7af3 user: fvogel
2017-08-30
15:48 • Ticket [d0c55bd7]: 4 changes artifact: 10120ad0 user: bll
2017-08-29
13:18 • Ticket [d0c55bd7]: 3 changes artifact: 8eabcd4d user: bll
09:02 • Ticket [d0c55bd7]: 3 changes artifact: 79307d04 user: gcramer
04:34 • Ticket [d0c55bd7]: 3 changes artifact: 85bc7140 user: bll
03:52 • New ticket [d0c55bd7]. artifact: b2c4fef4 user: bll

Ticket UUID: d0c55bd78a70d246a02d12d3696687f8dd4418d2
Title: tkBind.c : incorrect documentation for continue/break/ok
Type: Bug Version: 8.6.7
Submitter: bll Created on: 2017-08-29 03:52:09
Subsystem: 01. Bindings Assigned To: fvogel
Priority: 5 Medium Severity: Minor
Status: Closed Last Modified: 2017-09-16 08:24:36
Resolution: Fixed Closed By: fvogel
    Closed on: 2017-09-16 08:24:36
Description:
a) 

At approximately line 930 in generic/tkBind.c, there is:

 memcpy(newStr+length1+1, script, length2+1);
where length2 is:
 length2 = strlen(script);

This will overrun the length of 'script'.
Possibly change it to:

        memcpy(newStr+length1+1, script, length2);
        newStr[length1+1+length2] = '\n';

b) 

In Tk_BindEvent, the code is confused.

There is a while loop (p < end), but p is a single script, not a series of individual scripts, and the code to handle TCL_CONTINUE and TCL_BREAK does not work as advertised.  Setting p += len + 1 simply terminates the while condition.

e.g. If there are two bindings, p would be a single string consisting of:

::mybind1\n
::mybind2\n

The while loop seems to be pointless, and of course the return code processing will not work.

c)

Because the binding script is run as a single unit, and not a series of individual scripts, the return code from the first binding, if not TCL_OK, will stop the entire binding script.

If the first binding has "return -code continue" as the documentation specifies, the binding evaluation will NOT continue on to the next binding.

The first binding must have "return -code ok" in order to continue with the next binding (or simply have a normal procedure exit as usual, which will have a TCL_OK return code).

This is easily fixed by changing the documentation (my recommendation).
User Comments: fvogel added on 2017-09-16 08:24:36:
Merged to core-8-6-branch and trunk.

fvogel added on 2017-09-03 10:12:22:

Understood, thanks.

I have committed a modified version of your documentation change proposal in branch bug-d0c55bd78a.


bll added on 2017-09-01 14:28:28:
Note that (from the test suite):
    bind .t.f <Button-2> {lappend x b1; continue; lappend x b2}
is the only place a 'continue' can be placed.
A 'continue' cannot be put into a proc that is called from a binding script.

So 'binding script's precise definition is only the script in the 
bind command line, not any other script called by the bind command.  
This is not entirely clear in the documentation.

Original text from manual page:

"The continue and break commands may be used inside a binding script to control the processing of matching scripts. If continue is invoked, then the current binding script is terminated but Tk will continue processing binding scripts associated with other tag's. If the break command is invoked within a binding script, then that script terminates and no other scripts will be invoked for the event. "

New text:

A binding script is the script defined in the bind command line.  Within this binding script, the continue and break commands may be used. If continue is invoked, then the current binding script, including all other + appended 
scripts, is terminated but Tk will continue processing binding scripts associated with other tag's. If the break command is invoked within a 
binding script, then that script terminates and no other scripts will 
be invoked for the event."

Within a script called from the binding script, a return -code ok may be 
used to continue processing (including + appended scripts) or may use
return -code break may be used to stop processing all other bind scripts.

bll added on 2017-09-01 12:15:02:
Test program...

Notes: The screens where I use keyboard bindings are more complex than this, and I want the "bind <toplevel-window>" action where the bind is propagated to all child windows so that I can pick up the keypress.

#!/usr/bin/tclsh
#
# Instructions:
#   With current return set to 'ok':
#     Alternate selecting tab AAA and tab BBB
#     Type Control-s
# -> note that the key handler works for both tabs.
#   Set the return to 'continue':
#     Alternate selecting tab AAA and tab BBB
#     Type Control-s
# -> note that the key handler does not work for tab BBB

package require Tk

variable vars

proc setContinue { } {
  variable vars

  set vars(ret) continue
}

proc setOk { } {
  variable vars

  set vars(ret) ok
}

proc keyHandler { mw w } {
  variable vars

  set cont [winfo containing {*}[winfo pointerxy $mw]]
  if { ! [winfo exists $cont] } {
    return -code ok
  }
  if { [string match $mw* $cont] } {
    $w insert end "$vars(counter) control-s\n"
    incr vars(counter)
    return -code break
  }
  return -code $vars(ret)
}

proc main { } {
  variable vars

  set vars(ret) ok
  set vars(counter) 1

  ttk::notebook .nb
  pack .nb -in . -expand true -fill both
  ttk::button .bc -text {Use Continue} -command ::setContinue
  ttk::button .bok -text {Use OK} -command ::setOk
  ttk::label .l1 -text {Current return: }
  ttk::label .l2 -textvariable ::vars(ret)
  pack .bc .bok .l1 .l2 -in . -side left

  ttk::frame .a
  text .aa -height 5 -width 15
  pack .aa -in .a -expand true -fill both

  .nb add .a -text AAA -sticky news

  ttk::frame .b
  text .bb -height 5 -width 15
  pack .bb -in .b -expand true -fill both

  .nb add .b -text BBB -sticky news

  # bind to the top level so that all sub-windows also have the bind set
  bind . <Control-s> +[list ::keyHandler .a .aa]
  bind . <Control-s> +[list ::keyHandler .b .bb]
}
main

fvogel added on 2017-08-31 19:36:08:
Could you suggest changes you think should be included in the documentation? At best you would submit an updated man page, could you do that?

bll added on 2017-08-30 15:48:15:
Changed title.

bll added on 2017-08-29 13:18:18:
My apologies.
I got frustrated with this, as the documentation is really poor in this area.
And I don't work with continuing binds often enough to remember how it works.

I think you are correct.

I don't know in what situation the scripts get concatenated with a null byte.
Using:
  bind <Control-s> . +::mybindA
  bind <Control-s> . +::mybindB
Creates a single script separated by newlines.

Fortunately for bind-script writers TCL_OK acts just like TCL_CONTINUE as far as I can tell.

If the bind script actually had to return TCL_CONTINUE, it would be a problem, for as in the example above, ::mybindA would need to return TCL_OK, and ::mybindB would need to return TCL_CONTINUE, as it is the last of that set of scripts and is terminated by a null byte.  There's no way for the bind-script writer to tell if their script is the last of the set.

So the documentation is very poor and not really correct, because TCL_CONTINUE is not going to do what the user thinks it does if there is another binding active within the same set.

gcramer added on 2017-08-29 09:02:47:

About (a) and (b):

>   memcpy(newStr+length1+1, script, length2+1);
> where length2 is:
>   length2 = strlen(script);
>
> This will overrun the length of 'script'.

I cannot see that this is overrunning 'script', because:
  length2 = strlen(script);
depends on the trailing zero byte which belongs to 'script', so the byte length of 'script' is at least 'length2+1'.

> There is a while loop (p < end), but p is a single script, not a series of individual scripts, and the code to handle TCL_CONTINUE and TCL_BREAK does not work as advertised. Setting p += len + 1 simply terminates the while condition.

Yes, this construction only works if the individual scripts are concatenated with a zero byte; if \n is used as a separator, then this algorithm cannot work. Have a look at lines 1439-1444:

    /*
     * A "" is added to the scripts string to separate the various
     * scripts that should be invoked.
     */
 
   Tcl_DStringAppend(&scripts, "", 1);

This means that the single scripts are zero byte separated. Note that Tcl_DStringLength() does not depend on a trailing zero byte, unlike the counterpart strlen().


bll added on 2017-08-29 04:34:38:
I don't think that suggestion in (a) will work.

I would just like to see the documentation fixed.  The whole continue/break business is very confusing (it may work within the bind statement).  And there's no documentation on what code to return from a bound procedure.