ntextWordBreak(ntext Word Boundary Detection for the Text WidntextWordBreak(n)



______________________________________________________________________________

NAME
       ntextWordBreak - ntext Word Boundary Detection for the Text Widget

SYNOPSIS
       package require Tcl  8.5

       package require Tk  8.5

       package require ntext  ?0.81?

_________________________________________________________________

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

       o      0 - (default value) selects Ntext behaviour, i.e. platform-
              independent, two classes of word characters and one class of
              non-word characters.

       o      1 - selects classic Text behaviour, i.e. platform-dependent, one
              class of word characters and one class of non-word characters

       o      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

       o      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?

       o      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.

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.

BUGS, IDEAS, FEEDBACK
       This document, and the package it describes, will undoubtedly contain
       bugs and other problems.  Please report such in the category ntext of
       the Tklib Trackers [http://core.tcl.tk/tklib/reportlist].  Please also
       report any ideas for enhancements you may have for either package
       and/or documentation.

SEE ALSO
       bindtags, ntext, re_syntax, regexp, text

KEYWORDS
       bindtags, re_syntax, regexp, text



tklib                                0.81                    ntextWordBreak(n)
