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:

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.

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.

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:

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:

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:

Marks are objects that support the following methods:

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:

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:

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:

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:

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

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

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

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

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

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

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

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

exportselection

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

selectbackground

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

selectborderwidth

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

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

setgrid

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

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

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

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

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

spacing1

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

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

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

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

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

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

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.


Donatien Grolaux
Version 1.3.0 (20040413)