Craig VotavaDonal K. FellowsJeff Hobbs$Revision: 1.8 $

The Tk Text widget provides text tags, which are a very powerful thing. However, the current implementation does not provide an efficient way for a Tk Text widget programmer to extract (get) all of the actual text that has a given text tag. This TIP proposes to enhance the Tk Text widget to provide this functionality.

While writing applications using the Tk Text widget, I find myself wanting to extract all of the text that has a given text tag. Although this is possible with the existing functionality of the Tk Text widget, it can become extremely inefficient, depending on your application. Consider the example where we load a text widget with say, the contents of a scene from a play, and we tag all of the spoken passages with the name of the character that utters them. How can we provide an efficient way to allow an end user to print out all the spoken text for a single given character? My initial impulse was to design something like this (please excuse the use of Perl-Tk syntax, that's what I'm most comfortable with): ICAgJHR4dC0+dGFnR2V0KCR0YWcpOw== The problem with this design is what should this return? A string? An list? If a list, should it be a list of each tagged character? A list of strings containing all contiguous characters? In addition, Steve Lidie points out that the corresponding tagDelete() command would also have to be modified to mimic this change as well. This line of thought got icky pretty fast. My second impulse was to try to induce this functionality with as much existing stuff as possible. The tagRanges command returns a list of index pairs for all contiguous characters with a given tag. The thought here was to combine that command with the get command to get all the text with a given tag: ICAgJHR4dC0+Z2V0KCAkdHh0LT50YWdSYW5nZXMoJHRhZykgKTs= This design seems to fit in well with much of the existing functionality of the text widget. The main problem here is that the existing get command only allows for either one or two arguments, and returns a single string. For this design to be implemented, the get interface would need to be enhanced. This is the design I chose to implement as a reference (prototype) implementation. I believe that the functionality should be provided in the Tk Text widget, and believe that this prototype solution could be turned into a production solution. However those decisions I happily leave up to the Tk developers who are more knowledgeable about the Tk Text implementation than myself. An additional concern here involves the corresponding text delete command. Should the delete command also be modified in a similar way so that it has this same functionality too? It seems like it should.

This specification will only describe how the reference implementation was produced. If it is decided that an alternate design is needed for the final production solution, this specification can be scrapped. The goal of this design is to enhance the Tk Text get command from accepting only one or two arguments, to accepting any number of 1 (+NULL) or 2 arguments sets. The Tcl-Tk manual page description would change from this: ICAgJHQgZ2V0IGkxID9pMj8= to something like this: ICAgJHQgZ2V0IGkxID9pMj8gPyhpMyA/aTQ/IC4uLik/ By providing this enhancement, we give the programmer with the ability to efficiently get all of the text that is tagged with a given tag. The programmer would do this by using a compound statement utilizing the existing tag ranges command along with the enhanced get command, as follows (the examples are using the Perl-Tk syntax): ICAgJHR4dC0+Z2V0KCAkdHh0LT50YWdSYW5nZXMoJHRhZykgKTs= In addition, the enhancement will preserve compatibility with all of the existing Tk get commands currently in use. Currently, the get command simply returns a single string containing all of the characters specified by the first and (optionally) the second argument(s). The enhanced get command will preserve this existing functionality: ICAgbXkgJGNociA9ICR0ZXh0LT5nZXQoJzEuMCcpOw== This command functions exactly the same as the original get command. It will return a string containing the first character from the first line. ICAgbXkgJHN0ciA9ICR0ZXh0LT5nZXQoJzEuMCcsICcxLjAgbGluZWVuZCcpOw== This command functions exactly the same as the original get command. It will return a string containing all of the characters on the first line. However, if the programmer provides more than one or two argument(s), the enhanced get command will return a list of strings, just as if the original get command was called multiple times and the results were loaded into a programmer-defined list: ICAgbXkgQGxpbmVzID0gJHRleHQtPmdldCgnMS4wJywgJzEuMCBsaW5lZW5kJywgJzIuMCcpOw== This command returns a list whose first element ($lines[0]) is a string containing all of the characters from the first line, and the second element ($lines[1]) is a string containing just the first character of the second line. ICAgbXkgQGxpbmVzID0gJHRleHQtPmdldCgnMS4wJywgJycsICcyLjAnLCAnMi4wIGxpbmVlbmQnKTs= This command returns a list whose first element ($lines[0]) is a string containing just the first character from the first line, and the second element ($lines[1]) is a string containing all of the characters on the second line. ICAgbXkgQGxpbmVzID0gJHRleHQtPmdldCgnMS4wJywgJzEuMCBsaW5lZW5kJywgJzIuMCcsICcyLjAgbGluZWVuZCcpOw== This command returns a list whose first element ($lines[0]) is a string containing the all of the characters from the first line, and the second element ($lines[1]) is a string containing all of the characters from the second line. All of this paves the way for the programmer to use the compound command: ICAgbXkgQGxpbmVzID0gJHR4dC0+Z2V0KCAkdHh0LT50YWdSYW5nZXMoJHRhZykgKTs= This command returns a list whose elements are strings of all the contiguous characters tagged with a given tag.

The following Perl-Tk code illustrates how the enhanced get command could be used with the existing tag ranges command to efficiently extract all of the text that is tagged with a given tag. ICAgIyEgL3Vzci9sb2NhbC9iaW4vcGVybCAtdw==ICAgICAgcmVxdWlyZSA1LjAwNTs=ICAgICAgdXNlIHN0cmljdDs=ICAgdXNlIEVuZ2xpc2g7ICAgICAgdXNlIFRrOw==ICAgICAgIyBDcmVhdGUgbWFpbiB3aW5kb3cgd2l0aCBidXR0b24gYW5kIHRleHQgd2lkZ2V0IGluIGl0Li4uICAgbXkgJHRvcCA9IE1haW5XaW5kb3ctPm5ldzs=ICAgbXkgJGJ0biA9ICR0b3AtPkJ1dHRvbigtdGV4dD0+J3ByaW50IG9kZCBsaW5lcycpLT5wYWNrOw==ICAgbXkgJHR4dCA9ICR0b3AtPlNjcm9sbGVkKCdUZXh0JywgLXJlbGllZj0+J3N1bmtlbicsIC1ib3JkZXJ3aWR0aD0+JzInLA==CS1zZXRncmlkPT4ndHJ1ZScsIC1oZWlnaHQ9PiczMCcsIC1zY3JvbGxiYXJzPT4nZScpOw==ICAgJHR4dC0+cGFjaygtZXhwYW5kPT4neWVzJywgLWZpbGw9Pidib3RoJyk7ICAgJGJ0bi0+Y29uZmlndXJlKC1jb21tYW5kPT5zdWJ7JkdldFRleHQoJHR4dCl9ICk7ICAgICAgIyBQb3B1bGF0ZSB0ZXh0IHdpZGdldCB3aXRoIGxpbmVzIHRhZ2dlZCBvZGQgYW5kIGV2ZW4uLi4=ICAgbXkgJGxubzs=ICAgbXkgJG9kZGV2ZW47ICAgZm9yZWFjaCAkbG5vICgxLi4yMCkgew==CWlmKCRsbm8gJSAyKSB7ICRvZGRldmVuID0gIm9kZCIgfSBlbHNlIHsgJG9kZGV2ZW4gPSAiZXZlbiIgfTs=CSRsbm8gPSAiTGluZSAkbG5vICgkb2RkZXZlbilcbiI7CSR0eHQtPmluc2VydCAoJ2VuZCcsICRsbm8sICRvZGRldmVuKTs=ICAgfQ==ICAgICAgIyBEbyB0aGUgbWFpbiBwcm9jZXNzaW5nIGxvb3AuLi4=ICAgTWFpbkxvb3AoKTs=ICAgICAgc3ViIEdldFRleHQgew==CW15ICR0eHRvYmogPSBzaGlmdDs=CSR0eHRvYmotPnRhZygnY29uZmlndXJlJywgJ29kZCcsIC1iYWNrZ3JvdW5kPT4nbGlnaHRibHVlJyk7CSR0eHRvYmotPnRhZygnY29uZmlndXJlJywgJ2V2ZW4nLCAtYmFja2dyb3VuZD0+J2xpZ2h0Z3JlZW4nKTs=CSMgVGhpcyBpcyB0aGUgZ29hbCBvZiBhbGwgdGhlIHdvcmsuLi4=CW15IEBsaW5lcyA9ICR0eHRvYmotPmdldCgkdHh0b2JqLT50YWdSYW5nZXMoJ29kZCcpKTs=CXByaW50IFNUREVSUiBqb2luKCIiLCBAbGluZXMpOw==ICAgfQ==

The patch for this reference implementation has been posted to the ptk mailing list. An archived version is available at: I have written and run a single benchmark test (in Perl-Tk) to compare this reference implementation against a traditional method of extracting all text with a specific tag. The results of this specific benchmark test (tagging odd lines odd and even lines even in a text window with 2000 entries), run on my computer are as follows: UmVmZXJlbmNlIEltcGxlbWVudGF0aW9uICAgMC4xMDUgQ1BVIFNlY29uZHMgKGF2ZXJhZ2Ugb3ZlciAxMCBydW5zKQ==VHJhZGl0aW9uYWwgTWV0aG9kICAgICAgICAgMC40NDMgQ1BVIFNlY29uZHMgKGF2ZXJhZ2Ugb3ZlciAxMCBydW5zKQ== I believe that both the CPU the efficiency, and the coding efficiency that this reference implementation provides, merit the change to the Tk Widget. In addition to the get enhancement, the symmetrical changes would be make to the delete subcommand. The patch has received little testing so far, so any testing is encouraged.

Tcl has less of a need for this than Perl because it has a striding [foreach] allowing the list of indices returned by the [$t tag ranges] subcommand to be traversed in a straight-forward fashion, but this sort of functionality is still useful. The motivating examples above become (in order): ICAgc2V0IGxpbmVzIFskdCBnZXQgMS4wICIxLjAgbGluZWVuZCIgMi4wXQ==ICAgc2V0IGxpbmVzIFskdCBnZXQgMS4wIHt9IDIuMCAiMi4wIGxpbmVlbmQiXQ==ICAgc2V0IGxpbmVzIFskdCBnZXQgMS4wICIxLjAgbGluZWVuZCIgMi4wICIyLjAgbGluZWVuZCJdICAgc2V0IGxpbmVzIFtldmFsICR0IGdldCBbJHQgdGFnIHJhbmdlc11d

This document has been placed in the public domain.