<section ID="chapter.widgets.text">
  <TITLE>Text widget</TITLE>

<subsection> <TITLE>Description</TITLE>

<P>
A text widget displays one or more lines of text and allows that text to be edited. Text widgets support four different kinds of annotations on the text, called tags, marks, embedded windows or embedded images. These annotations are described below.
<P>
<EM>Indices</EM>
</P>
<P>
Many of the widget commands for texts take one or more indices as arguments. An index is a succession of things used to indicate a particular place within a text, such as a place to insert characters or one endpoint of a range of characters to delete. Indices have the syntax 

<<<base modifier modifier modifier ...>>>

Where <<base>> gives a starting point and the <<modifiers>> adjust the index from the starting point (e.g. move forward or backward one character). Every index must contain a base, but the modifiers are optional. 
</P>
<P>
The <<base>> for an index must have one of the following forms: 

<LIST>

<ITEM> <<coord(X Y)>> : Indicates <<X>>'th character on line <<Y>>. Lines and chars both begins at 1. If <<X>> is then atom <<end>> then it refers to the newline character that ends the line. 

<ITEM> <<pixel(X Y)>> : Indicates the character that covers the pixel whose x and y coordinates within the text's window are <<X>> and <<Y>>. 

<ITEM> <<Mark>> : Where <<Mark>> was previously obtained by the <<newMark()>> method and set by the <<set()>> method of the mark. Indicates where the mark is set.

<ITEM> <<Tag.first>> : Where <<Tag>> was previously obtained by the <<newTag()>> method. Indicates the first character in the text that has been tagged with <<Tag>>. This form generates an error if no characters are currently tagged with <<Tag>>.

<ITEM> <<Tag.last>> : Where <<Tag>> was previously obtained by the <<newTag()>> method. Indicates the character just after the last one in the text that has been tagged with <<Tag>>. This form generates an error if no characters are currently tagged with <<Tag>>. 

<ITEM> <<Window>> : Where <<Window>> was previously obtained by the <<newWindow()>> method. Indicates the position of the embedded window.

<ITEM> <<Image>> : Where <<Image>> was previously obtained by the <<newImage()>> method. Indicates the position of the embedded image.

</LIST>

If <<modifiers>> follow the base index, each one of them must have one of the forms listed below. Keywords such as <<chars>> and <<wordend>> may be abbreviated as long as the abbreviation is unambiguous. 

<LIST>

<ITEM> <<chars(N)>> : Adjust the index by <<N>> characters, moving to later or earlier lines in the text if necessary. If there are fewer than <<N>> characters in the text after or before the current index, then set the index to the last or first character in the text.

<ITEM> <<liness(N)>> : Adjust the index by <<N>> lines, moving to later or earlier lines in the text if necessary. If there are fewer than <<N>> lines in the text after or before the current index, then set the index to the last or first character in the text.

<ITEM> <<linestart>> :  Adjust the index to refer to the first character on the line. 

<ITEM> <<lineend>> : Adjust the index to refer to the last character on the line (the newline). 

<ITEM> <<wordstart>> : Adjust the index to refer to the first character of the word containing the current index. A word consists of any number of adjacent characters that are letters, digits, or underscores, or a single character that is not one of these. 

<ITEM> <<wordend>> : Adjust the index to refer to the character just after the last one of the word containing the current index. If the current index refers to the last character of the text then it is not modified. 

</LIST>
</P>
<P>
<EM>TAGS</EM>
</P>
<P>
The first form of annotation in text widgets is a tag. A tag can be associated to any part of the text. There may be any number of tags associated with characters in a text. Each tag may refer to a single character, a range of characters, or several ranges of characters. An individual character may have any number of tags associated with it. 
</P>
<P>
A priority order is defined among tags, and this order is used in implementing some of the tag-related functions described below. When a tag is defined (by associating it with characters or setting its display options or binding commands to it), it is given a priority higher than any existing tag. The priority order of tags may be redefined using the <<raise()>> and <<lower()>> methods.
</P>
<P>
Tags serve several purposes in text widgets. First, they control the way information is displayed on the screen. By default, characters are displayed as determined by the background, font, and foreground options for the text widget. However, display options may be associated with individual tags. If a character has been tagged, then the display options associated with the tag override the default display style. 
If a character has several tags associated with it, and if their display options conflict, then the options of the highest priority tag are used. If a particular display option hasn't been specified for a particular tag, then that option will never be used; the next-highest-priority tag's option will used instead. If no tag specifies a particular display option, then the default style for the widget will be used. 
</P>
<P>
The second purpose for tags is event bindings. You can associate bindings with a tag in much the same way you can associate bindings with a widget class: whenever particular X events occur on characters with the given tag, a given Oz command will be executed. Tag bindings can be used to give behaviors to ranges of characters; among other things, this allows hypertext-like features to be implemented. For details, see the description of the tag bind widget command below. 
</P>
<P>
<EM>MARKS</EM>
</P>
<P>
The second form of annotation in text widgets is a mark. Marks are used for remembering particular places in a text. They are something like tags, in that they have names and they refer to places in the file, but a mark isn't associated with particular characters. Instead, a mark is associated with the gap between two characters. Only a single position may be associated with a mark at any given time. If the characters around a mark are deleted the mark will still remain; it will just have new neighbor characters. In contrast, if the characters containing a tag are deleted then the tag will no longer have an association with
characters in the file. Marks can be used as index in widget commands.
</P>
<P>
<EM>EMBEDDED WINDOWS</EM>
</P>
<P>
The third form of annotation in text widgets is an embedded window. Each embedded window annotation causes a window to be displayed at a particular point in the text. There may be any number of embedded windows in a text widget, and any widget may be used as an embedded window. The embedded window's position on the screen will be updated as the text is modified or scrolled, and it will be mapped and unmapped as it moves into and out of the visible area of the text widget. Each embedded window occupies one character's worth of index space in the text widget, and it may be referred to either by the name of its embedded window or by its position in the widget's index space. If the range of text containing the embedded window is deleted then the window is destroyed. However return values in the widgets of these windows are bound only when the toplevel window is destroyed.
</P>
<P>
<EM>EMBEDDED IMAGES</EM>
</P>
<P>
The final form of annotation in text widgets is an embedded image. Each embedded image annotation causes an image to be displayed at a particular point in the text. There may be any number of embedded images in a text widget, and a particular image may be embedded in multiple places in the same text widget. The embedded image's position on the screen will be updated as the text is modified or scrolled. Each embedded image occupies one character's worth of index space in the text widget, and it may be referred to either by its position in the widget's index space, or the name it is assigned when the image is inserted into the text widget widh image create. If the range of text containing the embedded image is deleted then that copy of the image is removed from the screen. 
</P>
<subsection> <TITLE>Parameters</TITLE>
<P>
<LIST>
<ITEM> <<1:VS>> : Specifies the text displayed inside the widget (same as text). This parameter can be only used with the <<set()>> and <<get()>> methods.

&param_init_text;

<ITEM> <<return:V>> : When the window is closed, <<V>> is bound to the contents of the entry. <<V>> must be a free variable.

&param_background;
&param_borderwidth;
&param_cursor;
&param_exportselection;
&param_font;
&param_foreground;
&param_highlightbackground;
&param_highlightcolor;
&param_highlightthickness;
&param_insertbackground;
&param_insertborderwidth;
&param_insertofftime;
&param_insertontime;
&param_insertwidth;
&param_ipadx;
&param_ipady;
&param_relief;
&param_selectbackground;
&param_selectborderwidth;
&param_selectforeground;
&param_setgrid;
&param_takefocus;

<ITEM> <<height:I>> : Specifies the desired height for the window, in units of characters in the font given by the <<font>> option. Must be at least one. <<I>> must be an integer.

<ITEM> <<spacing1:P>> : Specifies how much additional space should be left above each text line. If a line wraps, this option only applies to the first line on the display. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<spacing2:P>> : For lines that wrap, this option specifies how much additional space to leave between the display lines for a single text line. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).
   
<ITEM> <<spacing3:P>> : Specifies how much additional space should be left below each text line. If a line wraps, this option only applies to the last line on the display.  <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<state:A>> : Specifies one of two states for the button: <<normal>> or <<disabled>>. If the text is disabled then characters may not be inserted or deleted and no insertion cursor will be displayed, even if the input focus is in the widget. <<A>> must be one of these two atoms : <<normal>> or <<disabled>>.

<ITEM> <<tabs:L>> : Specifies a set of tab stops for the window. The option's value consists of a record name <<q>> and whose fields are a list of screen distances giving the positions of the tab stops. Each position may optionally be followed in the next list element by one of the atoms <<left>>, <<right>>, <<center>>, or <<numeric>>, which specifies how to justify text relative to the tab stop. <<left>> is the default; it causes the text following the tab character to be positioned with its left edge at the tab position. <<right>> means that the right edge of the text following the tab character is positioned at the tab position, and <<center>> means that the text is centered at the tab position. <<numeric>> means that the decimal point in the text is positioned at the tab position; if there is no decimal point then the least significant digit of the number is positioned just to the left of the tab position; if there is no number in the text then the text is right-justified at the tab position. For example, <<tabs:q(2#c left 4#c 6#c center)>> creates three tab stops at two-centimeter intervals; the first two use left justification and the third uses center justification. If the list of tab stops does not have enough elements to cover all of the tabs in a text line, then new tab stops are extrapolated using the spacing and alignment from the last tab stop in the list. The value of the tabs option may be overridden by <<tabs>> options in tags. If no <<tabs>> option is specified, or if it is specified as <<nil>>, then default tabs spaced every eight (average size) characters are used. 

<ITEM> <<width:I>> : Specifies the desired width for the window in units of characters in the font given by the <<font>> option. If the font doesn't have a uniform width then the width of the character ``0'' is used in translating from character units to screen units.

<ITEM> <<wrap:A>> : Specifies how to handle lines in the text that are too long to be displayed in a single line of the text's window. The value must be on of the following atoms : <<none>> or <<char>> or <<word>>. A wrap mode of <<none>> means that each line of text appears as exactly one line on the screen; extra characters that don't fit on the screen are not displayed. In the other modes each line of text will be broken up into several screen lines if necessary to keep all the characters visible. In <<char>> mode a screen line break may occur after any character; in <<word>> mode a line break will only be made at word boundaries. 

<ITEM> <<action:C>> : Specifies an action to execute juste after the user modified the text. <<C>> can take several different forms (see <ptr to="basics.events">).

&param_lrscrollbar;
&param_tdscrollbar;
&param_scrollwidth;

&param_glue;
&param_padx;
&param_pady;
&param_feature;
&param_handle;
&param_tooltips;


</LIST>

</P>

<subsection> <TITLE>Interface</TITLE>

<P>
The object you get by an handle on the widget implements the following methods :

<LIST>

&interface_set;
&interface_get;
&interface_bind;
&interface_getFocus;
&interface_setGrab;
&interface_releaseGrab;
&interface_getGrabStatus;
&interface_raise;
&interface_lower;
&interface_winfo;

<ITEM> <<bbox(I V)>> : Binds <<V>> to a list of four elements describing the screen area of the character given by <<I>>. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the character, and the last two elements give the width and height of the area. If the character is only partially visible on the screen, then the return value reflects just the visible part. If the character is not visible on the screen then the return value is an empty list. <<I>> must be an indices as described above.

<ITEM> <<compare(I1 S I2 V)>> : Binds <<V>> to a boolean that is the result of the comparison of the indices given by <<I1>> and <<I2>> according to the relational operator given by the string <<S>>. <<S>> must be one of the strings :  <<"<">>, <<"<=">>, <<"==">>, <<">=">>, <<">">>, or <<"!=">>. If <<S>> is <<"==">> then <<true>> is returned if the two indices refer to the same character, if <<S>> is <<"<">> then <<true>> is returned if <<I1>> refers to an earlier character in the text than <<I2>>, and so on. 

<ITEM> <<delete(I1 ?I2)>> : Delete a range of characters from the text. If both <<I1>> and <<I2>> are specified, then delete all the characters starting with the one given by <<I1>> and stopping just before <<I2>> (i.e. the character at <<I2>> is not deleted). If <<I2>> doesn't specify a position later in the text than <<I1>> then no characters are deleted. If <<I2>> isn't specified then the single character at <<I1>> is deleted. It is not allowable to delete characters in a way that would leave the text without a newline as the last character.

<ITEM> <<dlineinfo(I V)>> : Binds <<V>> to a list with five elements describing the area occupied by the display line containing <<I>>. The first two elements of the list give the x and y coordinates of the upper-left corner of the area occupied by the line, the third and fourth elements give the width and height of the area, and the fifth element gives the position of the baseline for the line, measured down from the top of the area. All of this information is measured in pixels. If the current wrap mode is <<none>> and the line extends beyond the boundaries of the window, the area returned reflects the entire area of the line, including the portions that are out of the window. If the line is shorter than the full width of the window then the area returned reflects just the portion of the line that is occupied by characters and embedded windows. If the display line containing <<I>> is not visible on the screen then the return value is an empty list. 

<ITEM> <<dump(Opt I1 ?I2 V)>> : This method is kept for backyard compatibility with the underlying Tcl/Tk layer, so it should normally never be called. Binds <<V>> to the contents of the text widget from <<I1>> up to, but not including <<I2>>, including the text and information about marks, tags, and embedded windows. If <<I2>> is not specified, then it defaults to one character past <<I1>>. The information is returned in the following format: <<

     key1 value1 index1 key2 value2 index2 ... 

>> The possible key values are <<text>>, <<mark>>, <<tagon>>, <<tagoff>>, and <<window>>. The corresponding value is the text, tcl/tk mark name, tcl/tk tag name, or tcl/tk window name. The <<index>> information is the index of the start of the text, the mark, the tag transition, or the window. One or more of the following switches may be specified to control the dump: 
<LIST>
<ITEM> <<"-all">> : Return information about all elements: text, marks, tags, and windows. This is the default. 

<ITEM> <<"-mark">> : Include information about marks in the dump results. 

<ITEM> <<"-tag">> :  Include information about tag transitions in the dump results. Tag information is returned as tagon and tagoff elements that indicate the begin and end of each range of each tag, respectively. 

<ITEM> <<"-text">> : Include information about text in the dump results. The value is the text up to the next element or the end of range indicated by <<I2>>. A text element does not span newlines. A multi-line block of text that contains no marks or tag transitions will still be dumped as a set of text seqments that each end with a newline. The newline is part of the value. 

<ITEM> <<"-window">> : Include information about embedded windows in the dump results. The value of a window is its Tk pathname, unless the window has not been created yet. In this case an empty string is returned, and you must query the window by its index position to get more information. 
</LIST>

<ITEM> <<getText(I1 ?I2 V)>> : Binds <<V>> to a range of the text. The return value will be all the characters in the text starting with the one whose index is <<I1>> and ending just before the one whose index is <<I2>> (the character at <<I2>> will not be returned). If <<I2>> is omitted then the single character at <<I1>> is returned. If there are no characters in the specified range (e.g. <<I1>> is past the end of the file or <<I2>> is less than or equal to <<I1>>) then an empty string is returned. If the specified range contains embedded windows, no information about them is included in the returned string. 

<ITEM> <<newImage(I param1:value1 ... paramX:valueX V)>> : This command creates a new image annotation, which will appear in the text at the position given by <<I>>. <<V>> is bound to an object allowing to control the image. The parameters are :

<LIST>

<ITEM> <<align:A>> : If the image is not as tall as the line in which it is displayed, this option determines where the image is displayed in the line. <<A>> must be one of the following atoms : <<top>> (align the top of the image with the top of the line), <<center>> (center the image within the range of the line), <<bottom>> (align the bottom of the image with the bottom of the line's area), or <<baseline>> (align the bottom of the image with the baseline of the line). 

<ITEM> <<image:I>> : Specifies an image to display in the annotation. <<I>> must be a valid image (see <ptr to="misc.image">).

<ITEM> <<padx:P>> : Specifies the amount of extra space to leave on each side of the embedded image. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<pady:P>> : Specifies the amount of extra space to leave on the top and on the bottom of the embedded image. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

</LIST>

These parameters can be obtained and changed by the <<get()>> and <<set()>> methods of <<V>>.

<ITEM> <<index(I V)>> : Binds <<V>> to the position corresponding to <<I>> in the form <<coord(Line Char)>> where <<Line>> is the line number and <<Char>> is the character number. 

<ITEM> <<insert(I VS1 ?Tag1 ?VS2 ?Tag2 ...)>> : Inserts all of the <<VSx>> arguments just before the character at position <<I>>. If <<I>> refers to the end of the text (the character after the last newline) then the new text is inserted just before the last newline instead. If there is a single <<VS1>> argument and no <<Tag1>>, then the new text will receive any tags that are present on both the character before and the character after the insertion point; if a tag is present on only one of these characters then it will not be applied to the new text. If <<TagX>> is specified then it consists of either a text tag, or a record of the form <<q(Tag1 ... TagX)>>. The new characters will receive all of the tags in this list and no others, regardless of the tags present around the insertion point. If multiple chars-tagList argument pairs are present, they produce the same effect as if a separate insert widget command had been issued for each pair, in order. The last <<Tag>> argument may be omitted. 

<ITEM> <<newMark(...)>> : This command creates a new mark annotation. It can takes three diferents forms :

<LIST>

<ITEM> <<newMark(V)>> : Binds <<V>> to a general purpose mark annotation.

<ITEM> <<newMark(insert:V)>> : Binds <<V>> to a particular mark linked to the insertion cursor. This mark can't be deleted.

<ITEM> <<newMark(current:V)>> : Binds <<V>> to a particular mark that is associated with the character closest to the mouse and is adjusted automatically to track the mouse position and any changes to the text in the widget (one exception: it is not updated in response to mouse motions if a mouse button is down; the update will be deferred until all mouse buttons have been released). This amrk can't be deleted.

</LIST>

Marks are objects that support the following methods :

<LIST>

<ITEM> <<gravity(A)>> : Each mark has a gravity, which is either left or right. The gravity for a mark specifies what happens to the mark when text is inserted at the point of the mark. If a mark has left gravity, then the mark is treated as if it were attached to the character on its left, so the mark will remain to the left of any text inserted at the mark position. If the mark has right gravity, new text inserted at the mark position will appear to the right of the mark. The gravity for a mark defaults to right. This methods changes the gravity of the mark. <<A>> must be either <<left>> or <<right>>.

<ITEM> <<set(I)>> : Sets the mark to a position just before the character at index <<I>>. If the mark was already set, it is moved from its old position.

<ITEM> <<unset>> : Removes the mark. The removed marks will not be usable in indices.

</LIST>

<ITEM> <<scan(...)>> : This command is used to implement scanning on text widgets. It has two forms, depending on option: 

<LIST>

<ITEM> <<scan(mark X Y)>> : Records X and Y and the entry's current view; used in conjunction with later <<scan(dragto ...)>> commands. Typically this command is associated with a mouse button press in the widget and <<X>> and <<Y>> are the coordinates of the mouse. <<X>> and <<Y>> must be valid distances (see <ptr to="misc.distance">).

<ITEM> <<scan(dragto X Y)>> : This command computes the difference between its <<X>> and <<Y>> arguments (which are typically mouse coordinates) and the <<X>> and <<Y>> arguments to the last <<scan(mark ...)>> command for the widget. It then adjusts the view by 10 times the difference in coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the listbox at high speed through its window.

</LIST>

<ITEM> <<search(?Switches VS I ?S V)>> : Searches the text starting at <<I>> for a range of characters that matches <<VS>>. If a match is found, <<V>> is bound to the index of the first character in the match in the form <<coord(X Y)>>; otherwise <<B>> is bound to <<false>>. One or more of the following switches (or abbreviations thereof) may be specified to control the search:

<LIST>

<ITEM> <<"-forwards">> : The search will proceed forward through the text, finding the first matching range starting at or after the position given by <<I>>. This is the default. 

<ITEM> <<"-backwards">> : The search will proceed backward through the text, finding the matching range closest to <<I>> whose first character is before <<I>>.

<ITEM> <<"-exact">> : Use exact matching: the characters in the matching range must be identical to those in pattern. This is the default. 

<ITEM> <<"-regexp">> : Treat pattern as a regular expression and match it against the text using the rules for regular expressions (see the regexp command for details). 

<ITEM> <<"-nocase">> : Ignore case differences between the pattern and the text. 

</LIST>

The matching range must be entirely within a single line of text. For regular expression matching the newlines are removed from the ends of the lines before matching: use the $ feature in regular expressions to match the end of a line. For exact matching the newlines are retained. If <<S>> is specified, the search stops at that index: for forward searches, no match at or after <<S>> will be considered; for backward searches, no match earlier in the text than <<S>> will be considered. If <<S>> is omitted, the entire text will be searched: when the beginning or end of the text is reached, the search continues at the other end until the starting location is reached again; if <<S>> is specified, no wrap-around will occur.

<ITEM> <<see(I)>> : Adjusts the view in the window so that the character given by <<I>> is completely visible. If <<I>> is already visible then the command does nothing. If <<I>> is a short distance out of view, the command adjusts the view just enough to make <<I>> visible at the edge of the window. If <<I>> is far out of view, then the command centers <<I>> in the window. 

<ITEM> <<newTag(V)>> : Binds <<V>> to a tag annotation. A tag is an object that can be associated to part of the text and that supports the following parameters :

<LIST>
<ITEM> <<background>>, <<font>>, <<foreground>>, <<spacing1>>, <<spacing2>>, <<spacing3>>, <<tabs>> and <<wrap>> : These parameters redefine widget specific parameters for the part of text associated with the tag.

<ITEM> <<bgstipple:B>> : Specifies a bitmap that is used as a stipple pattern for the background. If bitmap hasn't been specified, or if it is specified as <<nil>>, then a solid fill will be used for the background. <<B>> must be a valid bitmap (see <ptr to="misc.bitmap">).

<ITEM> <<borderwidth:P>> : Specifies the width of a 3-D border to draw around the background. This option is used in conjunction with the <<relief>> option to give a 3-D appearance to the background for characters; it is ignored unless the <<background>> option has been set for the tag. <<P>> must be a valid screen distance (see  <ptr to="misc.distance">).

<ITEM> <<fgstipple:B>> : Specifies a bitmap that is used as a stipple pattern when drawing text and other foreground information such as underlines. If bitmap hasn't been specified, or if it is specified as <<nil>>, then a solid fill will be used for the background. <<B>> must be a valid bitmap (see <ptr to="misc.bitmap">).

<ITEM> <<justify:A>> : If the first character of a display line has a tag for which this option has been specified, then justify determines how to justify the line. It must be one of the following atoms : <<left>>, <<right>>, or <<center>>. If a line wraps, then the justification for each line on the display is determined by the first character of that display line. 

<ITEM> <<lmargin1:P>> : If the first character of a text line has a tag for which this option has been specified, then pixels specifies how much the line should be indented from the left edge of the window. If a line of text wraps, this option only applies to the first line on the display; the <<lmargin2>> option controls the indentation for subsequent lines. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<lmargin2:P>> :  If the first character of a display line has a tag for which this option has been specified, and if the display line is not the first for its text line (i.e., the text line has wrapped), then pixels specifies how much the line should be indented from the left edge of the window. This option is only used when wrapping is enabled, and it only applies to the second and later display lines for a text line.  <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<offset:P>> : Specifies an amount by which the text's baseline should be offset vertically from the baseline of the overall line. For example, a positive offset can be used for superscripts and a negative offset can be used for subscripts. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<overstrike:B>> : Specifies whether or not to draw a horizontal rule through the middle of characters.  <<B>> must be a boolean.

<ITEM> <<relief:A>> : Specifies the 3-D effect desired for drawing backgrounds.  Must be one of these atoms : <<raised>>, <<sunken>>, <<flat>>, <<ridge>>, <<solid>> or <<groove>>.  This option is used in conjunction with the <<borderwidth>> option to give a 3-D appearance to the background for characters; it is ignored unless the <<background>> option has been set for the tag. 

<ITEM> <<rmargin:P>> : If the first character of a display line has a tag for which this option has been specified, then pixels specifies how wide a margin to leave between the end of the line and the right edge of the window. This option is only used when wrapping is enabled. If a text line wraps, the right margin for each line on the display is determined by the first character of that display line. 

<ITEM> <<underline:B>> : Specifies whether or not to draw an underline underneath characters. <<B>> must be a boolean value.

</LIST>

<ITEM> <<newWindow(I D param1:value1 ... paramX:valueX V)>> : Builds the window described by the record <<D>>, inserts that window to the position <<I>> of the text and binds <<V>> to an object that can control the window. Several <<paramX:valueX>> configuration options may be associated with the window. The following options are currently supported:

<LIST>

<ITEM> <<align:A>> : If the window is not as tall as the line in which it is displayed, this option determines where the window is displayed in the line. <<A>> must be one of the following atoms : <<top>> (align the top of the image with the top of the line), <<center>> (center the image within the range of the line), <<bottom>> (align the bottom of the image with the bottom of the line's area), or <<baseline>> (align the bottom of the image with the baseline of the line). 

<ITEM> <<stretch:B>> : If the requested height of the embedded window is less than the height of the line in which it is displayed, this option can be used to specify whether the window should be stretched vertically to fill its line. If the <<pady>> option has been specified as well, then the requested padding will be retained even if the window is stretched. 

<ITEM> <<padx:P>> : Specifies the amount of extra space to leave on each side of the embedded image. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

<ITEM> <<pady:P>> : Specifies the amount of extra space to leave on the top and on the bottom of the embedded image. <<P>> must be a valid screen distance (see <ptr to="misc.distance">).

</LIST>

These options can be dynamically changed by the <<set()>> and <<get()>> methods of <<V>>.

</LIST>

</section>
