htext(n)

💅 htext(n) — Create and manipulate hypertext widgets

from the BLT Built-In Commands collection 💖

✨ NAME ✨

htext — Create and manipulate hypertext widgets

🛠️ SYNOPSIS 🛠️

htext pathName ?option value?...

🌸 DESCRIPTION 🌸

okay so the htext command creates a new window (that's the pathName argument, bestie) and makes it into an htext widget. Additional options, described above (even though they show up later — classic manpage chaos 💀), 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 already be a window named pathName, but pathName's parent must exist. The htext command returns its pathName. slay.

The htext widget is a hybrid of a non-editable text widget and a geometry manager (e.g. the packer, iykyk). It displays text (optionally read from a 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 (by default, percent signs %%) is immediately passed to the Tcl interpreter for evaluation. iconic.

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. no cap.

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. that's the self-care.

Setting the either the -filename or -text configuration option (their words, not mine 💅) 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. periodt.

📄 FILE FORMAT 📄

The format of an 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 an 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 (yes, "number", not "numbered" — we're keeping it 💅), 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.

also there's a stray 2 floating in the original right around sel.last — page-number glitter, not an index, bestie 😭

🧩 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 of 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 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 a 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 of window. The default is 0.0.
• -relwidth value — Specifies the width of the cavity containing window relative to the width of pathName. value is a real number indicating the ratio of the width of the cavity to the width of IpathName (yes, that capital I is in the original — we're keeping the typo, bestie 🫶). 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 (their typo, not mine 💅) 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 the 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 (their grammar 💅) 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 — paints the whole htext widget in color. Default? white, always has been 💭
• -cursor cursor — what your pointer turns into over the widget. Default is pencil — yes really, a pencil, it's giving study era ✏️
• -filename fileName — points at an htext file to show in the window. If you set it to the empty string, the widget falls back to the -text option instead. The whole htext file format lives up in FILE FORMAT, go peek 🫶
• -font fontName — sets the font of the text, duh. Default is *-Helvetica-Bold-R-Normal-*-12-120-* — very 1990s of it ngl
• -foreground color — the color of the text itself. Default is black 🖤
• -height pixels — how tall the htext widget window is.
• -linespacing pixels — the gap between each line of text. Has to be in a form Tk_GetPixels accepts. Default is 1 pixel.
• -specialchar number — the ASCII value of the special double-character delimiters, no cap. Inside htext files, whatever sits between these special characters gets evaluated as a block of Tcl commands 👀 Default special char is 0x25 (the percent sign).
• -text text — the actual text to display in the widget. Can be any valid string of characters, live your truth. See FILE FORMAT for the deets.
• -xscrollcommand string — the prefix for a command that talks to horizontal scrollbars. Whenever the view in the widget's window changes (or literally anything else happens that could change what a scrollbar shows, like the total size of the widget's contents shifting), the widget invokes string concatenated with two numbers. Each number is a fraction between 0 and 1 marking a position in the document. Don't specify this option and no command gets executed at all. periodt.
• -yscrollcommand string — same exact energy but for vertical scrollbars: the prefix of a command invoked as string plus two numbers, each a fraction between 0 and 1 indicating a position in the document, whenever the view changes or something else could change a scrollbar's display (like the widget's contents resizing). No option, no command. 💅
• -width pixels — the desired width of the viewport window. Plot twist: if pixels is less than one, the window just grows to fit the widest line of text 🌱
• -xscrollunits pixels — how far you scroll horizontally. Default 10 pixels.
• -yscrollunits pixels — how far you scroll vertically. Default 10 pixels.

---

🌸 WIDGET COMMANDS 🌸

These are the commands you call on pathName, bestie. Learn them, love them.

pathName gotoline ?index?

Jumps so that index becomes the top line of the text. index has to be a valid text index — heads up, the character offset part is straight up ignored 🙈 If you don't pass an index, you get the current line number back instead.

pathName scan mark position

Records position plus the current view in the text window — it's the setup half of the whole scan dragto situation. position must be in the form @x,y where x and y are window coordinates. Typically you wire this to a mouse button press inside the widget. Returns an empty string, as a treat.

pathName scan dragto position

Does the math: it takes the difference between position and the position saved by the last scan mark on this widget, then adjusts the view up or down by 10 times that coordinate difference. Hook it to mouse motion events and boom — you're dragging text through the window at high speed 🔥 position must be in the form @x,y where x and y are window coordinates. Returns an empty string.

pathName search pattern ?from? ?to?

Gives you the number of the next line that matches pattern. pattern is a string that follows the matching rules of Tcl_StringMatch. from and to are text line numbers (inclusive, both of them) that bound the search. And if nothing matches? You get -1. 😭

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 it must be in a form Tk_GetPixels accepts. Leave position off and you get the current text position back instead.

pathName yview ?position?

Same vibe, vertical axis: moves the viewport down/up to the new text y-coordinate position, which is the offset from the top of the text to the current position and must be in a form Tk_GetPixels accepts. No position? Current text position comes back to you. 🎀

---

💀 BUGS 💀

Fr fr: text with embedded tabs can get obscured by child windows when you scroll it horizontally. Not a vibe, but it's documented, so now you know.

---

🔑 KEYWORDS 🔑

hypertext, widget

---

And that's the whole page, bestie — you officially know htext(n) from BLT 2.5, slay 💖 Go build something iconic with it, ily, bye 🦋✨