Provided by: blt-dev_2.4z-7ubuntu2_amd64 bug

NAME

       htext - Create and manipulate hypertext widgets

SYNOPSIS

       htext pathName ?option value?...
_________________________________________________________________

DESCRIPTION

       The  htext command creates a new window (given by the pathName argument) and makes it into
       a htext widget.  Additional options, described above, may be specified on the command line
       or  in  the option database to configure aspects of the widget such as its color and font.
       At the time this command is invoked, there must not exist a  window  named  pathName,  but
       pathName's parent must exist.  The htext command returns its pathName.

       The  htext widget is hybrid of a non-editable text widget and a geometry manager (e.g. the
       packer).  It displays text (optionally read from file) in a window.  Text can be  scrolled
       either  horizontally or vertically using the htext window as a viewport.  In addition, Tcl
       commands can be embedded into the text which are evaluated as the text  is  parsed.   Text
       between  special  double  characters (percent signs "%%") is immediately passed to the Tcl
       interpreter for evaluation.

       Furthermore, any widget or widget hierarchy can be packed in-line and made  to  appear  on
       the  current  line  of  the text.  Widgets are packed using the htext append command.  All
       widgets must be children of the htext window and must already exist before packing.   Once
       a  widget  has  been  packed  it  cannot be moved to a different position within the text.
       Widgets can be resized but they will remain at the same position within the text.

       Before a file or text string is parsed by the  htext  widget,  all  the  widget's  current
       children  are destroyed.  You can reload files or text without worrying about unmapping or
       destroying each child window beforehand.

       Setting the either the -filename or -text configuration option will adjust  the  value  of
       the  other.   If both options are set, the file takes precedence.  When a new file is read
       using the -filename option, the value of the -text option is reset to  the  empty  string.
       Likewise,  when  the  -text option is set, the string representing the -filename option is
       cleared.

FILE FORMAT

       The format of htext text file is typically ASCII text.  Text enclosed  by  special  double
       characters  (by  default, percent signs '%%') is interpreted and executed as Tcl commands.
       The special character  may be specified by the  -specialchar  option.   In  the  following
       example  of  a htext file,  a button widget is appended to the text between  the words "a"
       and "which".  The pathName of the htext widget is ".ht".

              This will be displayed as normal text.
              But this will become a %%
                button .ht.button -text "button" -fg red
                .ht append .ht.button
              %% which can invoke a Tcl command.

INDICES

       Some of the widget operations (selection, gotoline, search, etc.) take one or more indices
       as  arguments.   An index is a string used to indicate a particular place within the text,
       such as the first and last characters in a range to be selected.

       An index must have one of the following forms:

       line.char   Indicates char'th character on line  line.   Both  lines  and  characters  are
                   number  from  0,  so  "0.0"  is  the first beginning of the text.  Char may be
                   undesignated.  In this case a character position of 0 is assumed.

       @x,y        Indicates the character that covers the pixel whose x and y coordinates within
                   the text's window are x and y.

       end         Indicates the end of the text.

       anchor      Indicates  the anchor point for the selection, which is set with the selection
                   operation.

       sel.first   Indicates the first character in the selection.  It is an error  to  use  this
                   form if the selection isn't in the entry window.

       sel.last    Indicates  the  character  just after the last one in the selection.  It is an │
                   error to use this form if the selection isn't in the entry window.

VARIABLES

       The following global Tcl variables are maintained when an htext file is parsed.

       htext(widget)
              is the pathname of the htext widget.

       htext(file)
              is the name of the file the htext widget is currently parsing.   It  is  the  empty
              string when the -text option is used.

       htext(line)
              is the current line number in the text.

       This  information  might  be  used to construct hyper links between different files and/or
       lines.

SYNTAX

       The htext command creates a new Tcl command whose name is pathName.  This command  may  be
       used  to  invoke  various  operations  on  the widget.  It has the following general form:
       pathName oper ?args?  Oper and args determine the exact behavior of the command.

OPERATIONS

       The following operations are available for htext widgets:

       pathName append window ?option value?...
              Embeds the widget window into the htext widget.  Window  is  the  pathname  of  the
              widget to be embedded which must be a child of pathName.  Window will be positioned
              in the htext widget at the current location of the text. If option and value  pairs
              are  present,  they  configure various aspects how window appears in pathName.  The
              following options are available.

              -anchor anchorPos
                     Specifies how window will be arranged if there is any  extra  space  in  the
                     cavity surrounding the window.  For example, if anchorPos is center then the
                     window is centered in the cavity; if anchorPos is w then the window will  be
                     drawn  such  it  touches  the  leftmost  edge  of the cavity. The default is
                     center.

              -fill style
                     Specifies how the window should be stretched to occupy the  extra  space  in
                     the  cavity  surrounding it (if any exists).  Style is none, x, y, both.  If
                     style is x, the width of window is expanded to fill the cavity.  If style is
                     y, the height is expanded.  The default is none.

              -height pixels
                     Sets  the  height  of the cavity surrounding window.  If pixels is zero, the
                     height of the cavity will be the same as the requested height of window.  If
                     pixels  is  less than the requested height of window, window will be reduced
                     to fit the cavity.  The default is 0.

              -ipadx pad
                     Sets the amount of internal padding to be added to the  width  window.   Pad
                     can be a list of one or two numbers.  If pad has two elements, the left side
                     of window is extended by the first value and the right side  by  the  second
                     value.   If  pad is just one value, both the left and right sides are padded
                     by evenly by the value.  The default is 0.

              -ipady pad
                     Sets an amount of internal padding to be added to the height of window.  Pad
                     can  be  a  list of one or two numbers.  If pad has two elements, the top of
                     window is padded by the first value and the bottom by the second value.   If
                     pad  is  just  one  number, both the top and bottom are padded evenly by the
                     value.  The default is 0.

              -justify justify
                     Justifies window vertically within the cavity containing it in  relation  to
                     the  line of text. Justify is top, bottom, or  center.  If justify is center
                     the widget is centered along the baseline of the line of text.  The  default
                     is center.

              -padx pad
                     Sets  the  padding on the left and right sides of window.  Pad can be a list
                     of one or two numbers.  If pad has two elements, the left side of window  is
                     padded  by  the  first value and the right side by the second value.  If pad
                     has just one value, both the left and right sides are padded evenly  by  the
                     value.  The default is 0.

              -pady pad
                     Sets  the  padding  above and below window.  Pad can be a list of one or two
                     numbers.  If pad has two elements, the area above window is  padded  by  the
                     first  value  and  the  area  below by the second value.  If pad is just one
                     number, both the top and bottom are padded by the value.  The default is 0.

              -relheight value
                     Specifies the height of the cavity containing window relative to the  height
                     of pathName.  Value is real number indicating the ratio of the height of the
                     cavity to the height of pathName.  As the height  of  pathName  changes,  so
                     will  the  height  of  window.   If  value is 0.0 or less, the height of the
                     cavity is the requested height window.  The default is 0.0.

              -relwidth value
                     Specifies the width of the cavity containing window relative to the width of
                     pathName.   Value  is  real  number indicating the ratio of the width of the
                     cavity to the width of IpathName.  As the height  of  pathName  changes,  so
                     will the height of window.  If value is 0.0 or less, the width of the cavity
                     is the requested width of window.   The default is 0.0.

              -width value
                     Species the width of the cavity containing the child window.  Value must  be
                     in  a  form  accepted  by  Tk_GetPixels.  If value is greater than zero, the
                     cavity is resized to that width.  If the requested window width  is  greater
                     than  the  cavity's width, the window will be reduced to fit the cavity.  By
                     default, the cavity is requested width of the child window.

       pathName configure ?window? ?option? ?value option value ...?
              Queries or modifies the configuration options of the text  widget  or  one  of  its
              embedded  widgets.   If  no  window argument is present, the htext widget itself is
              configured.  Otherwise window is the pathname of a widget already embedded into the
              htext widget.  Then this command configure the options for the embedded widget.

       If  option  isn't  specified, a list describing all of the current options for pathName or
       window is returned.  If option is specified, but not value, then  a  list  describing  the
       option  option is returned.  If one or more option and value pairs are specified, then for
       each pair, the htext or embedded window option option is set to value.

       The following options are valid for the htext widget.

              -background color
                     Sets the background of the htext widget to color.  This default is white.

              -cursor cursor
                     Specifies the cursor for the htext widget.  The default cursor is pencil.

              -filename fileName
                     Specifies a htext file to be displayed in the window.  If the value  is  the
                     empty string, the -text option is used instead.  See the section FILE FORMAT
                     for a description of the htext file format.

              -font fontName
                     Sets the font of the text in the htext widget to fontName.  The  default  is
                     *-Helvetica-Bold-R-Normal-*-12-120-*.

              -foreground color
                     Sets  the foreground of the htext widget to color.  This is the color of the
                     text.  This default is black.

              -height pixels
                     Specifies the height of the htext widget window.

              -linespacing pixels
                     Specifies the spacing between each line of text.  The value  must  be  in  a
                     form accepted by Tk_GetPixels. The default value is 1 pixel.

              -specialchar number
                     Specifies  the  ASCII  value of the special double character delimiters.  In
                     htext files, the text between these special characters  is  evaluated  as  a
                     block  of  Tcl commands. The default special character is the 0x25  (percent
                     sign).

              -text text
                     Specifies the text to be displayed in the htext widget.   Text  can  be  any
                     valid string of characters. See FILE FORMAT for a description.

              -xscrollcommand string
                     Specifies  the  prefix  for  a  command  used to communicate with horizontal
                     scrollbars.  When the view in the htext widget's window changes (or whenever
                     anything else occurs that could change the display in a scrollbar, such as a
                     change in the total size of the widget's contents), the widget invoke string
                     concatenated  by  two  numbers.  Each of the numbers is a fraction between 0
                     and 1, which indicates a position in the document.  If this  option  is  not
                     specified, then no command will be executed.

              -yscrollcommand string
                     Specifies  the  prefix  for  a  command  used  to  communicate with vertical
                     scrollbars.  When the view in the htext widget's window changes (or whenever
                     anything else occurs that could change the display in a scrollbar, such as a
                     change in the total size of the widget's contents), the widget invoke string
                     concatenated  by  two  numbers.  Each of the numbers is a fraction between 0
                     and 1, which indicates a position in the document.  If this  option  is  not
                     specified, then no command will be executed.

              -width pixels
                     Specifies  the  desired width of the viewport window.  If the pixels is less
                     than one, the window will grow to accommodate the widest line of text.

              -xscrollunits pixels
                     Specifies the horizontal scrolling distance. The default is 10 pixels.

              -yscrollunits pixels
                     Specifies the vertical scrolling distance. The default is 10 pixels.

       pathName gotoline ?index?
              Sets the top line of the text to index. Index must  be  a  valid  text  index  (the
              character  offset is ignored).  If an index isn't provided, the current line number
              is returned.

       pathName scan mark position
              Records position and the current view in the text window;  used in conjunction with
              later  scan dragto commands.  Position must be in the form "@x,y, where x and y are
              window coordinates.  Typically this command is associated with a mouse button press
              in the widget.  It returns an empty string.

       pathName scan dragto position
              Computes  the  difference  between position and the position registered in the last
              scan mark command for the widget.  The view is then adjusted up or down by 10 times
              the difference in coordinates.  This command is can be associated with mouse motion
              events to produce the effect of dragging the text at high speed through the window.
              Position  must  be  in  the  form  "@x,y, where x and y are window coordinates. The
              command returns an empty string.

       pathName search pattern ?from? ?to?
              Returns the number of the next line matching pattern.  Pattern is  a  string  which
              obeys  the  matching  rules  of Tcl_StringMatch.  From and to are text line numbers
              (inclusive) which bound the search.  If no match for pattern can be  found,  -1  is
              returned.

       pathName xview ?position?
              Moves the viewport horizontally to the new text x-coordinate position.  Position is
              the offset from the left side of the text to the current position and must be in  a
              form  accepted  by  Tk_GetPixels.  If  position  is  not  present, the current text
              position is returned.

       pathName yview ?position?
              Moves the viewport vertically to the new text y-coordinate position.   Position  is
              the  offset  from the top of the text to the current position and must be in a form
              accepted by Tk_GetPixels. If position is not present, the current text position  is
              returned.

BUGS

       Text with embedded tabs can be obscured by child windows when scrolled horizontally.

KEYWORDS

       hypertext, widget