7.25 Text widget

local 
   R E
   Desc=text(tdscrollbar:true 
             lrscrollbar:true 
             init:"Hello world" 
             handle:E
             return:R)
in 
   {{QTk.build td(Desc)} show}
   {Delay 2000}
   {E set("Hi guys")}  % changes the displayed text
   {Delay 2000}
   {E insert('end' "\nNew text")} % inserts new text
   {Wait R}
   {Show {VirtualString.toAtom R}}
end

7.25.1 Description

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.

Indices

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.

The base for an index must have one of the following forms:

• coord(L C) : Indicates C'th character on line L. Lines and chars both begins at 1. If C is then atom end then it refers to the newline character that ends the line.

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

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

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

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

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

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

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.

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

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

• linestart : Adjust the index to refer to the first character on the line.

• lineend : Adjust the index to refer to the last character on the line (the newline).

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

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

TAGS

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.

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.

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.

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.

MARKS

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.

EMBEDDED WINDOWS

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.

EMBEDDED IMAGES

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.

7.25.2 Parameter List

Specific Parameters

1 action actionh height return spacing1 spacing2 spacing3 state tabs width wrap

Non Specific Parameters

background borderwidth cursor exportselection feature font foreground glue handle highlightbackground highlightcolor highlightthickness init insertbackground insertborderwidth insertofftime insertontime insertwidth ipadx ipady look lrscrollbar onCreation padx pady relief scrollwidth selectbackground selectborderwidth selectforeground setgrid takefocus tdscrollbar tooltips

7.25.3 Method List

'raise'

'raise'(1:W): If the W argument is omitted then the command raises the widget so that it is above all of its siblings in the stacking order (it will not be obscured by any siblings and will obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the 'raise' command will insert this widget into the stacking order just above W; this could end up either raising or lowering the widget.

bbox

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.

bind

bind(event:E action:A args:LA append:AP): Specifies an action LA to execute when the event E is triggered.

• Actions can be specified either as a procedure, a pair Port#Message or a pair Object#Method (see Section 4.3.3).

• Events are strings (see Section 8.11.1).

• The list of arguments LA specifies supplementary information to pass to the action, like the key code of a keypress, or the mouse coordinates of a mouse button click (see Section 8.11.2). If LA if not specified, nil is assumed.

• The boolean append parameter specifies if the binding overrides the previous binding for this event, or adds a supplementary action. If not specified, false is assumed.

compare

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.

delete

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.

dlineinfo

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.

dump

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:

• "-all": Return information about all elements: text, marks, tags, and windows. This is the default.

• "-mark": Include information about marks in the dump results.

• "-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.

• "-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.

• "-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.

get

get(parameter1:Variable1 ... parameterX:VariableX): Obtains the value of one or more parameters. parameterX must be a valid parameter for the widget. VariableX must be free variables that will receive the current value of the parameters.

getFocus

getFocus(force:B): if B is false (or by default): if the application currently has the input focus on the widget's display, this command resets the input focus for the widget's display to the widget. If the application doesn't currently have the input focus on the widget's display, the widget will be remembered as the focus for its top-level; the next time the focus arrives at the top-level, it will be redirected it to the widget. If B is true: sets the focus of the widget's display to the widget, even if the application doesn't currently have the input focus for the display. This command should be used sparingly, if at all. In normal usage, an application should not claim the focus for itself; instead, it should wait for the window manager to give it the focus. B must be a boolean.

getGrabStatus

getGrabStatus(1:V): Binds V to the atom none if there is no grab on the widget, to the atom local if there is a local grab and to global if there is a global grab. V must be a free variable.

getText

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.

index

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.

insert

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.

lower

lower(1:W): If the W argument is omitted then the command lowers the widget so that it is below all of its siblings in the stacking order (it will be obscured by any siblings and will not obscure any siblings that overlap it). If W is specified then it must be a handle to another widget that is either a sibling of this widget or the descendant of a sibling of this widget. In this case the lower command will insert this widget into the stacking order just below W; this could end up either raising or lowering the widget.

newImage

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:

• 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).

• image:I: Specifies an image to display in the annotation. I must be a valid image (see Section 8.4).

• 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 Section 8.6).

• 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 Section 8.6).

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

newMark

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

• newMark(V): Binds V to a general purpose mark annotation.

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

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

Marks are objects that support the following methods:

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

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

• unset: Removes the mark. The removed marks will not be usable in indices.

newTag

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:

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

• 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 Section 8.3).

• 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 Section 8.6).

• 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 Section 8.3).

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

• 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 Section 8.6).

• 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 Section 8.6).

• 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 Section 8.6).

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

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

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

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

newWindow

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:

• 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).

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

• 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 Section 8.6).

• 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 Section 8.6).

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

releaseGrab

releaseGrab: Releases the grab on the widget if there is one, otherwise does nothing.

scan

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

• 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 Section 8.6).

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

search

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:

• "-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.

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

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

• "-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).

• "-nocase": Ignore case differences between the pattern and the text.

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.

see

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.

set

set(parameter1:value1 ... parameterX:valueX): Changes the value of one or more parameters. parameterX must be a valid parameter for the widget. valueX must be a valid value for the parameter.

setGrab

setGrab(global:B): Sets a grab on the widget. If B is true then the grab is global, otherwise it is local (B false by default). If a grab was already in effect for this application then it is automatically released. If there is already a grab on the widget and it has the same global/local form as the requested grab, then the command does nothing. Local grab affects only the grabbing application: events will be reported to other applications as if the grab had never occurred. A global grab locks out all applications on the screen, so that only the given subtree of the grabbing application will be sensitive to pointer events (mouse button presses, mouse button releases, pointer motions, window entries, and window exits). During global grabs the window manager will not receive pointer events either. Warning: whe a grab is set, it is define for the whole Oz process so that it will prevent the user to do input to other windows as well. Moreover a grab is still effective even if the window that contains the grabbed widgets is hidden. B must be a boolean.

winfo

winfo(parameter1:value1 ... parameterX:valueX): This commands works like the get method, but for window-related information. For more details, see Section 8.9.

7.25.4 Detailed Parameters List

1:VS: Specifies the text displayed inside the widget (same as text). This parameter can be only used with the set() and get() methods.

action:C: Specifies an action to execute right after the user modified the text. C can take several different forms (see Section 4.3.1).

actionh:C: Similar to the action parameter where then handle of the widget is given as a parameter to the action to be executed. This parameter overrides the action parameter when present.

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.

background:C: or bg:C: Specifies the normal background color to use when displaying the widget. C must be a valid color (see Section 8.2).

borderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around the outside of the widget (if such a border is being drawn; the relief option typically determines this). The value may also be used when drawing 3-D effects in the interior of the widget. P must be a valid screen distance (see Section 8.6).

cursor:A: Specifies the mouse cursor to be used for the widget. A must be a valid cursor (see Section 8.7)

exportselection:B: Specifies whether or not a selection in the widget should also be the X selection. If the selection is exported, then selecting in the widget deselects the current X selection, selecting outside the widget deselects any widget selection, and the widget will respond to selection retrieval requests when it has a selection. The default is usually for widgets to export selections. B must be a boolean.

feature:A: Specifies a feature name for the container object to reference the object controlling this widget. For more details, see Section 4.2. A must be an atom.

font:F: Specifies the font to use when drawing text inside the widget. This parameter can't be get at runtime, however it can be set. F must be a valid font (see Section 8.8)

foreground:C: or fg:C: Specifies the normal foreground color to use when displaying the widget. C must be a valid color (see Section 8.2)

glue:A: Specifies how a widget must fit in its own available place. A must be an atom that is any combination of n, s, w and e. If a direction is specified, the corresponding border is glued to its neighbor or border of the frame if there is no neighbor. If a direction is not specified, the corresponding border if such that the widget takes just the width or height it needs to draw itself. If none of opposite directions is specified, the widget is centered. For more details, see Section 4.1.

handle:V: Specifies a variable to reference the object controlling this widget. This variable is bound when the window is built. For more details, see Section 4.2. V must be a free variable.

highlightbackground:C: Specifies the color to display in the traversal highlight region when the widget does not have the input focus. C must be a valid color (see Section 8.2)

highlightcolor:C: Specifies the color to use for the traversal highlight rectangle that is drawn around the widget when it has the input focus. C must be a valid color (see Section 8.2)

highlightthickness:P: Specifies a non-negative value indicating the width of the highlight rectangle to draw around the outside of the widget when it has the input focus. If the value is zero, no focus highlight is drawn around the widget. P must be a valid screen distance (see Section 8.6).

init:VS: The initial text displayed inside the widget. This parameter is valid at creation time only. VS must be a virtual string. This parameter is only valid at creation time.

insertbackground:C: Specifies the color to use as background in the area covered by the insertion cursor. This color will normally override either the normal background for the widget (or the selection background if the insertion cursor happens to fall in the selection). C must be a valid color (see Section 8.2).

insertborderwidth:P: Specifies a non-negative value indicating the width of the 3-D border to draw around the insertion cursor. P must be a valid screen distance (see Section 8.6).

insertofftime:I: Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain "off" in each blink cycle. If this option is zero then the cursor doesn't blink: it is on all the time. I must be a positive integer value.

insertontime:I: Specifies a non-negative integer value indicating the number of milliseconds the insertion cursor should remain "on" in each blink cycle. I must be a positive integer value.

insertwidth:P: Specifies a value indicating the total width of the insertion cursor. If a border has been specified for the insertion cursor (using the insertborderwidth option), the border will be drawn inside the width specified by the insertwidth option. P must be a valid screen distance (see Section 8.6).

ipadx:P: Specifies a non-negative value indicating how much extra space to request for the widget in the X-direction. When computing how large a window needs to be, the widget will add this amount to the width it would normally need (as determined by the width of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space to the left and/or right of what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. P must be a valid screen distance (see Section 8.6)

ipady:P: Specifies a non-negative value indicating how much extra space to request for the widget in the Y-direction. When computing how large a window needs to be, the widget will add this amount to the height it would normally need (as determined by the height of the things displayed in the widget); if the geometry manager can satisfy this request, the widget will end up with extra internal space above and/or below what it displays inside. Most widgets only use this option for padding text: if they are displaying a bitmap or image, then they usually ignore padding options. P must be a valid screen distance (see Section 8.6)

look:L: Specifies a look to use for the widget. A look specifies default values for the parameters of widgets. This parameter can be specified at creation time only. Moreover changing a look will not change the appearance of widgets that are already displayed with that look. See Section 5.1 for more details.

lrscrollbar:B: Determines whether the widget has got a horizontal bar below. This option can be specified at creation time only. B must be a boolean.

onCreation:P: When a widget is created, for example by QTk.build, this parameter specifies an action to execute right after the widget has been created, but before returning from the build instruction. It is usefull if one needs the handle of the widget to initialize it in ways not permitted by its description record (for example binding the Enter or Leave mouse events).

padx:P: Specifies how much horizontal external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

pady:P: Specifies how much vertical external padding to leave on each side of the widget. This space is added outside the widget border. P must be a valid screen distance (see Section 8.6)

relief:A: Specifies the 3-D effect desired for the widget. Must be one of these atoms: raised, sunken, flat, ridge, solid or groove. The value indicates how the interior of the widget should appear relative to its exterior; for example, raised means the interior of the widget should appear to protrude from the screen, relative to the exterior of the widget.

scrollwidth:P: Specifies the width of the vertical and horizontal scrollbars. P must be a valid screen distance (see Section 8.6)

selectbackground:C: Specifies the background color to use when displaying selected items. C must be a valid color (see Section 8.2).

selectborderwidth:P: pecifies a non-negative value indicating the width of the 3-D border to draw around selected items. P must be a valid screen distance (see Section 8.6).

selectforeground:C: Specifies the foreground color to use when displaying selected items. C must be a valid color (see Section 8.2).

setgrid:B: Determines whether this widget controls the resizing grid for its top-level window. This option is typically used in text widgets, where the information in the widget has a natural size (the size of a character) and it makes sense for the window's dimensions to be integral numbers of these units. These natural window sizes form a grid. If the setgrid option is set to true then the widget will communicate with the window manager so that when the user interactively resizes the top-level window that contains the widget, the dimensions of the window will be displayed to the user in grid units and the window size will be constrained to integral numbers of grid units. B must be a boolean.

takefocus:B: Determines whether the window accepts the focus during keyboard traversal (e.g., Tab and Shift-Tab). Before setting the focus to a window, the traversal mechanims consult the value of the takeFocus option. A value of false means that the widget should be skipped entirely during keyboard traversal. true means that the widget should receive the input focus as long as it is viewable (it and all of its ancestors are mapped). B must be a boolean.

tdscrollbar:B: Determines whether the widget has got a vertical bar at the right. This option can be specified at creation time only. B must be a boolean.

tooltips:VS: Specifies a tooltip for the widget. A tooltip is a small message that appears when the mouse cursor if left still over the widget for a while. If VS is set to nil, no tooltip will appear at all. VS must be a virtual string.

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

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 Section 8.6).

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 Section 8.6).

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 Section 8.6).

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.

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.

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.

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.