# hwtk::text

Create and manipulate text widgets.

## Format

hwtk::text - pathName ?option value? …

## Description

Displays one or more lines of text and allows that text to be edited.

## Standard Options

-clientdata
Database name: clientData
Database class: ClientData
Acts as a data storage for a widgets. User can store any data and this will not have any effect on widget property.
-height
Database name: height
Database class: Height
If specified, the widget’s requested height in pixels.
-relief
Database name: relief
Database class: Relief
Specifies the 3D effect desired for the widget. Acceptable values are raised, sunken, flat, ridge, solid, and 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.
-state
Database name: state
Database class: State
May be set to normal or disabled to control the disabled state bit.
-width
Database name: width
Database class: Width
Specifies the width of a widget.

## Widget Specific Options

-wrap
Database name: wrap
Database class: Wrap
Determines how text wrapping behaves. May be char, none, or word. If word, text will be forced to wrap at the end of a word. If char, text will wrap after any character it needs to. If none, it will not wrap at all.

## Widget Commands

pathName cget option
Returns the current value of the configuration option given by option.
pathName configure ?option? ?value option value …?
Query or modify the configuration options of the widget. If one or more option-value pairs are specified, then the command modifies the given widget option(s) to have the given value(s); in this case the command returns an empty string. If option is specified with no value, then the command returns a list describing the named option: the elements of the list are the option name, database name, database class, default value, and current value. If no option is specified, returns a list describing all of the available options for pathName.
pathName delete ?arg arg …?
Delete a range of characters from the text.
pathName edit ?arg arg …?
Controls the undo mechanism and the modified flag.
pathName edit modified ?boolean?
If boolean is not specified, returns the modified flag of the widget. The insert, delete, edit undo and edit redo commands or the user can set or clear the modified flag. If boolean is specified, sets the modified flag of the widget to boolean.
pathName edit redo
When the -undo option is true, reapplies the last undone edits provided no other edits were done since then. Generates an error when the redo stack is empty. Does nothing when -undo option is false.
pathName edit reset
Clears the undo and redo stacks.
pathName edit separator
Inserts a separator (boundary) on the undo stack. Does nothing when the -undo value is false.
pathName edit undo
Reverts the last edit action when the -undo option is true. An edit action is defined as all the insert and delete commands that are recorded on the undo stack in between two separators. Generates an error when the undo stack is empty. Does nothing when the -undo option is false.
pathName get ?arg arg …?
Returns a range of characters from the text.
pathName identify element x y
Returns the name of the element under the point given by x and y, or an empty string if the point does not lie within any element. x and y are pixel coordinates relative to the widget. Some widgets accept other identify subcommands.
pathName insert ?arg arg …?
Inserts all of the chars arguments just before the character at index.
pathName instate statespec ?script?
Test the widget’s state. If script is not specified, returns 1 if the widget state matches statespec and 0 otherwise. If script is specified, equivalent to
if{[pathNameinstatestateSpec]}script
pathName search ?arg arg …?
Searches the text in pathName starting at index for a range of characters that matches pattern. If a match is found, the index of the first character in the match is returned as result; otherwise an empty string is returned. 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 index. This is the default.
-backwards
The search will proceed backward through the text, finding the matching range closest to index whose first character is before index.
-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.
-nocase
Ignore case differences between the pattern and the text.
-count varName
The argument following -count gives the name of a variable; if a match is found, the number of index positions between beginning and end of the matching range will be stored in the variable. If there are no embedded images or windows in the matching range (and there are no elided characters if -elide is not given), this is equivalent to the number of characters matched. In either case, the range matchIdx to matchIdx + $count chars will return the entire matched text. -elide Find elided (hidden) text as well. By default only displayed text is searched. - - This switch has no effect except to terminate the list of switches: the next argument will be treated as pattern even if it starts with -. pathName see ?arg arg …? Adjusts the view in the window so that the character given by index is completely visible. pathName state ?stateSpec? Modify or inquire widget state. If stateSpec is present, sets the widget state: for each flag in stateSpec, sets the corresponding flag or clears it if prefixed by an exclamation point. Returns a new state spec indicating which flags were changed: setchanges[pathNamestatespec] pathNamestate$changes
will restore pathName to the original state. If stateSpec is not specified, returns a list of the currently-enabled state flags.
pathName tag ?arg arg …?
This command is used to manipulate tags. The exact behavior of the command depends on the option argument that follows the tag argument. The following forms of the command are currently supported:
pathName tag add tagName index1 ?index2 index1 index2 …?
Associate the tag tagName with all of the characters starting with index1 and ending just before index2 (the character at index2 isn’t tagged). A single command may contain any number of index1-index2 pairs. If the last index2 is omitted then the single character at index1 is tagged. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then the command has no effect.
pathName tag bind tagName ?sequence? ?script?
This command associates script with the tag given by tagName. Whenever the event sequence given by sequence occurs for a character that has been tagged with tagName, the script will be invoked.
pathName tag cget tagName option
This command returns the current value of the option named option associated with the tag given by tagName. Option may have any of the values accepted by the tag configure widget command.
pathName tag configure tagName ?option? ?value? ?option value …?
This command is similar to the configure widget command except that it modifies options associated with the tag given by tagName instead of modifying options for the overall text widget.
pathName tag delete tagName ?tagName …?
Deletes all tag information for each of the tagName arguments. The command removes the tags from all characters in the file and also deletes any other information associated with the tags, such as bindings and display information. The command returns an empty string.
pathName tag lower tagName ?belowThis?
Changes the priority of tag tagName so that it is just lower in priority than the tag whose name is belowThis. If belowThis is omitted, then tagName’s priority is changed to make it lowest priority of all tags.
pathName tag names ?index?
Returns a list whose elements are the names of all the tags that are active at the character position given by index. If index is omitted, then the return value will describe all of the tags that exist for the text (this includes all tags that have been named in a pathName tag widget command but haven’t been deleted by a pathName tag delete widget command, even if no characters are currently marked with the tag). The list will be sorted in order from lowest priority to highest priority.
pathName tag nextrange tagName index1 ?index2?
This command searches the text for a range of characters tagged with tagName where the first character of the range is no earlier than the character at index1 and no later than the character just before index2 (a range starting at index2 will not be considered). If several matching ranges exist, the first one is chosen. The command’s return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If index2 is not given then it defaults to the end of the text.
pathName tag prevrange tagName index1 ?index2?
This command searches the text for a range of characters tagged with tagName where the first character of the range is before the character at index1 and no earlier than the character at index2 (a range starting at index2 will be considered). If several matching ranges exist, the one closest to index1 is chosen. The command’s return value is a list containing two elements, which are the index of the first character of the range and the index of the character just after the last one in the range. If no matching range is found then the return value is an empty string. If index2 is not given then it defaults to the beginning of the text.
pathName tag raise tagName ?aboveThis?
Changes the priority of tag tagName so that it is just higher in priority than the tag whose name is aboveThis. If aboveThis is omitted, then tagName’s priority is changed to make it highest priority of all tags.
pathName tag ranges tagName
Returns a list describing all of the ranges of text that have been tagged with tagName. The first two elements of the list describe the first tagged range in the text, the next two elements describe the second range, and so on. The first element of each pair contains the index of the first character of the range, and the second element of the pair contains the index of the character just after the last one in the range. If there are no characters tagged with tag then an empty string is returned.
pathName tag remove tagName index1 ?index2 index1 index2 …?
Remove the tag tagName from all of the characters starting at index1 and ending just before index2 (the character at index2 isn’t affected). A single command may contain any number of index1-index2 pairs. If the last index2 is omitted then the single character at index1 is tagged. If there are no characters in the specified range (e.g. index1 is past the end of the file or index2 is less than or equal to index1) then the command has no effect. This command returns an empty string.

## Example

::hwtk::dialog .d -title "::hwtk::text"
set t [hwtk::text [.d recess].t]
pack \$t

.d post