Provided by: tklib_0.8~20230222-1_all 
NAME
ntextWordBreak - ntext Word Boundary Detection for the Text Widget
SYNOPSIS
package require Tcl 8.5
package require Tk 8.5
package require ntext ?1.0?
_________________________________________________________________________________________________
DESCRIPTION
The ntext package provides a binding tag named Ntext for use by text widgets in place of
the default Text binding tag.
Navigation and selection in a text widget require the detection of words and their
boundaries. The word boundary detection facilities provided by Tcl/Tk through the Text
binding tag are limited because they define only one class of "word" characters and one
class of "non-word" characters. The Ntext binding tag uses more general rules for word
boundary detection, that define two classes of "word" characters and one class of "non-
word" characters.
CONFIGURATION OPTIONS
The behaviour of Ntext may be configured application-wide by setting the values of a
number of namespace variables. One of these is relevant to word boundary detection:
::ntext::classicWordBreak
• 0 - (default value) selects Ntext behaviour, i.e. platform-independent, two classes
of word characters and one class of non-word characters.
• 1 - selects classic Text behaviour, i.e. platform-dependent, one class of word
characters and one class of non-word characters
• After changing this value, Ntext 's regexp matching patterns should be
recalculated. See FUNCTIONS for details and advanced configuration options.
ADVANCED USE
VARIABLES (ADVANCED USE)
::ntext::tcl_match_wordBreakAfter
::ntext::tcl_match_wordBreakBefore
::ntext::tcl_match_endOfWord
::ntext::tcl_match_startOfNextWord
::ntext::tcl_match_startOfPreviousWord
These variables hold the regexp patterns that are used by Ntext to search for word
boundaries. If they are changed, subsequent searches are immediately altered. In many
situations, it it unnecessary to alter the values of these variables directly: instead
call one of the functions ::ntext::initializeMatchPatterns, ::ntext::createMatchPatterns.
In the Text binding tag one can change the search rules by changing the values of the
global variables tcl_wordchars and tcl_nonwordchars. The equivalent operation in the
Ntext binding tag is to call ::ntext::createMatchPatterns with appropriate arguments.
FUNCTIONS (ADVANCED USE)
If a simple regexp search should prove insufficient, the following functions (analogous to
the Tcl/Tk core's tcl_wordBreakAfter etc) may be replaced by the developer:
ntext::new_wordBreakAfter
ntext::new_wordBreakBefore
ntext::new_endOfWord
ntext::new_startOfNextWord
ntext::new_startOfPreviousWord
FUNCTIONS
Each function calculates the five regexp search patterns that define the word boundary
searches. These values are stored in the namespace variables listed above.
::ntext::initializeMatchPatterns
• This function is called when Ntext is first used, and needs to be called again only
if the script changes the value of either ::ntext::classicWordBreak or
::tcl_platform(platform). The function is called with no arguments. It is useful
when the desired search patterns are the default patterns for either the Ntext or
Text binding tag, and so are implicitly specified by the values of
::ntext::classicWordBreak and ::tcl_platform(platform) alone.
::ntext::createMatchPatterns new_nonwordchars new_word1chars ?new_word2chars?
• This function is useful in a wider range of situations than
::ntext::initializeMatchPatterns. It calculates the regexp search patterns for any
case with one class of "non-word" characters and one or two classes of "word"
characters.
Each argument should be a regexp expression defining a class of characters. An
argument will usually be a bracket expression, but might alternatively be a class-
shorthand escape, or a single character. The third argument may be omitted, or
supplied as the empty string, in which case it is unused.
The first argument is interpreted as the class of non-word characters; the second
argument (and the third, if present) are classes of word characters. The classes
should include all possible characters and will normally be mutually exclusive: it
is often convenient to define one class as the negation of the other two.
WORD BOUNDARY MATCHING
The problem of word boundary selection is a vexed one, because text is used to represent a
universe of different types of information, and there are no simple rules that are useful
for all data types or for all purposes.
Ntext attempts to improve on the facilities available in classic Text by providing
facilities for more complex definitions of words (with three classes of characters instead
of two).
What is a word? Why two classes of word?
When using the modified cursor keys <Control-Left> and <Control-Right> to navigate through
a Ntext widget, the cursor is placed at the start of a word. A word is defined as a
sequence of one or more characters from only one of the two defined "word" classes; it may
be preceded by a character from the other "word" class or from the "non-word" class.
The double-click of mouse button 1 selects a word of text, where in this case a "word" may
be as defined above, or alternatively may be a sequence of one or more characters from the
"non-word" class of characters.
Traditionally Tcl has defined only one word class and one non-word class: on Windows, the
non-word class is whitespace, and so alphanumerics and punctuation belong to the same
class. On other platforms, punctuation is bundled with whitespace as "non-word"
characters. In either case, the navigation and selection of text are unnecessarily
coarse-grained, and sometimes give unhelpful results.
The use of three classes of characters might make selection too fine-grained; but in this
case, holding down the Shift key and double-clicking another word is an excellent way to
select a longer range of text (a useful binding that Tcl/Tk has long provided but which is
missing in other systems).
As well as its defaults, Ntext permits the developer to define their own classes of
characters, or to revert to the classic Text definitions, or to specify their own regexp
matching patterns.
BUGS
This version of ntext is intended to be compatible with all releases of Tk 8.5 and 8.6,
and with the branches core-8-5-branch, core-8-6-branch, and trunk in the source code
repository for Tk. Any incompatibility with any of these versions, for any Tk windowing
system, should be reported as a bug. Please report such in the category ntext of the Tklib
Trackers [http://core.tcl.tk/tklib/reportlist].
EXAMPLE
To use Ntext with Tcl/Tk's usual word-boundary detection rules:
package require ntext
text .t
bindtags .t {.t Ntext . all}
set ::ntext::classicWordBreak 1
::ntext::initializeMatchPatterns
See bindtags for more information.
To define a different set of word-boundary detection rules:
package require ntext
text .t
bindtags .t {.t Ntext . all}
::ntext::createMatchPatterns {[[:space:][:cntrl:]]} {[[:punct:]]} {[^[:punct:][:space:][:cntrl:]]}
See regexp, re_syntax for more information.
SEE ALSO
bindtags, ntext, re_syntax, regexp, text
KEYWORDS
bindtags, re_syntax, regexp, text