21.11. The Text Widget
Create a Text widget with the
Text method:
$parentwidget->Text ( options)
The standard configuration options that apply to
Text are: -background,
-bg,
-bor-derwidth,
-bd, -cursor,
-exportselection, -font,
-foreground, -fg,
-height,
-high-lightbackground,
-highlightcolor,
-highlightthickness,
-insertbackground,
-in-sertborderwidth,
-insertofftime, -insertontime,
-insertwidth, -padx,
-pady,
-re-lief,
-selectbackground,
-selectborderwidth,
-selectforeground, -state,
-takefo-cus,
-width, -xscrollcommand, and
-yscrollcommand.
Other options are:
- -setgrid => boolean
-
Turns
on gridding for the Text widget. Default is 0
(off).
- -spacing1 => amount
-
Defines the amount of space left on the
top of a line of text that starts on its own line. Default is
0.
- -spacing2 => amount
-
Defines the amount of space left on the top of a line of text after
it has been automatically wrapped by the Text widget. Default is
0.
- -spacing3 => amount
-
Defines the amount of space left after a line of text that has been
ended by \n. Default is 0.
- -tabs => list
-
Specifies a list of tab stops to use in
the text widget. Default is undefined (no tab stops).
- -wrap => mode
-
Sets the mode for determining automatic
line wrapping. Values are none (no wrapping),
char (wrap at any character), or
word (wrap at a word boundary). Default is
char.
21.11.1. Text Indexes and Modifiers
In a Text widget, several indexes are defined to identify positions
in the text. These are used by the methods that retrieve and
manipulate text.
- n.m
-
Numbers representing character
m on line n
- @x,y
-
The character closest to the x,y coordinate
- end
-
The end of the text
- insert
-
The character after the insert cursor
- current
-
The position closest to the mouse cursor
- mark
-
Other marks defined for the widget (see discussion of text marks
later in this section)
- sel.first
-
The
first selected character
- sel.last
-
The character just after the last selected character
- tag.first
-
The first character in the widget of the specified tag type
- tag.last
-
The character just after the last character of the specified tag type
- widget
-
The location of an embedded widget
There are also several modifiers to use with text indexes. They are:
- - n lines
- + n lines
-
n lines before or after the index
- - n chars
- + n chars
-
n characters before or after the index
- linestart
-
The first character on the line
- lineend
-
The last character on the line (often a newline)
- wordstart
-
The first character in the word
- wordend
-
The character after the last character in the word
21.11.2. Text Methods
In addition to configure and
cget, the following methods are defined for the
Text widget:
- bbox
-
Returns the location and dimensions of
the bounding box surrounding the character at the specified index.
The returned list contains four numbers representing (respectively)
the x coordinate of the upper-left corner, the y coordinate of the
upper-left corner, the width of the text in pixels, and the height of
the text in pixels.
- compare
-
Performs a comparison on two indexes.
For example:
if ($text->compare('insert', '==', 'end') {
# we're at the end of the text
}
The valid operators are <,
<=, ==,
>=, and !=.
- debug
-
Given a Boolean, turns debugging on or
off.
- delete
-
Deletes text from the text widget. To
delete everything:
$text->delete(0, 'end');
- dlineinfo
-
Returns the location and dimensions of
the bounding box surrounding the line at the specified index. The
returned list contains five numbers representing (respectively) the x
coordinate of the upper-left corner, the y coordinate of the
upper-left corner, the width of the text in pixels, the height of the
text in pixels, and the baseline position of the line.
- get
-
Returns the text located in the given
index range.
- index
-
Given a named index, returns its
numeric equivalent in the format
line.char.
- insert
-
Inserts text into the widget at the
specified location. The second argument is the text to insert, and
the third argument is either a single tag or a list reference
containing the names of multiple tags to apply to the text.
Subsequent arguments alternate between text and tags. For example:
$text->insert('end', 'You want to do ', 'normal',
'what?!', ['bold','red']);
- search
-
Returns the index containing a
particular string in the Text widget. For example, to search
backwards for a case-insensitive hostname starting from the end of
the text:
$hostindex = $text->search(-nocase, -backwards, $hostname, 'end');
The search method takes several switches to modify
the search, each starting with -. The first argument that does not
start with - is taken to be the search string. The switches are:
- -forwards
-
Searches forwards starting at the specified index.
- -backwards
-
Searches backwards starting at the specified index.
- -exact
-
Matches the string exactly (default).
- -regexp
-
Treat the pattern as a regular expression.
- -nocase
-
Ignores case.
- -count => $variable
-
Stores the number of matches into the specified variable.
- --
-
Interprets the next argument as the pattern. (Useful when the pattern
starts with a -.)
- see
-
Scrolls the text so that the portion of
the text containing the specified index is visible.
- window
-
Embeds widgets within the Text widget.
The first argument can be any of: create,
names, cget, and
configure.
- create
-
Inserts an embedded widget at a specified index. Each widget occupies
one character in the Text widget. The widget must have already been
created as a child of the Text widget. For example:
$button = $text->Label(-text => "How ya doing?");
$text->window('create','end', -window => $button);
Here, the -window option is used to identify the
widget to embed. The list of options to window
('create') is:
- -align
-
Determines the positioning within the line of text. Values are
baseline, bottom,
top, or center (default).
- -padx
-
Adds padding in the x direction.
- -pady
-
Adds padding in the y direction.
- -window
-
Identifies the widget to embed.
- names
-
Returns a list of widget types embedded into the Text widget.
- cget
-
Returns information on the widget at the specified index:
$text->window('cget',0);
- configure
-
Configures widget at the specified index:
$text->window('configure',0,-background => "green");
- xview
-
Manipulates the text in view. With no
arguments, returns a list of two numbers between 0 and 1, defining
the portion of the text that is currently hidden on the left and
right sides, respectively. With arguments, the function of
xview changes:
- index
-
If the first argument is an index, that position becomes the leftmost
position in view.
- moveto
-
Moves the specified fraction of the text to the left of the visible
portion.
- scroll
-
Scrolls the text left or right by the specified number of units
(characters, in this context) or pages. Used primarily as a callback
to a scrollbar; pressing on an arrow would move by units
(characters), and pressing on the trough would move by pages. The
number is either 1 or -1, to
move forwards or backwards, respectively.
- yview
-
Manipulates the text in view. With no
arguments, returns a list of two numbers between 0 and 1, defining
the portion of the text that is currently hidden on the top and
bottom, respectively. With arguments, the function of
yview changes:
- index
-
If the first argument is an index, that position becomes the topmost
position in view.
- moveto
-
Moves the specified fraction of the text to the top of the visible
portion.
- scroll
-
Scrolls the text up or down by the specified number of units (lines,
in this context) or pages. Used primarily as a callback to a
scrollbar; pressing on an arrow would move by units (lines), and
pressing on the trough would move by pages. The number is either
1 or -1, to move forwards or
backwards, respectively.
21.11.3. Tags
You
can associate a distinct set of format properties to a portion of the
text using tags. A tag is defined with the
tagConfigure method, and text is associated with a
tag via an option to the insert or
tagAdd method. For example:
$text->Text->pack;
$text->tagConfigure('bold', -font =>
'-*-Courier-Medium-B-Normal-*-120-*-*-*-*-*-*');
$text->insert('end', "Normal text\n");
$text->insert('end', "Bold text\n", 'bold');
There are several methods defined for manipulating text tags:
- tagAdd
-
Adds a tag to the text within the
specified index range. For example, to assign the
bold tag defined above to the current selection:
$text->tagAdd('bold','sel.first','sel.last');
You can supply multiple ranges as arguments to
tagAdd.
- tagBind
-
Executes a callback when a specified
event happens on the tagged text. For example:
$text->tagBind('goto_end', "<Button-1>", sub {shift->see('end');} );
- tagConfigure
-
Creates or changes settings for a text
tag. For example:
$text->tagConfigure('link', -foreground => 'red');
Options for configuring text tags are:
- -background => color
-
The color to use behind the text.
- -bgstipple => bitmap
-
A pattern to draw behind the text.
- -borderwidth => amount
-
The width of the edge drawn around the text.
- -fgstipple => bitmap
-
A pattern used to draw the text.
- -font => fontname
-
The font used for the text.
- -foreground => color
-
The color of the text.
- -justify => position
-
The justification of the text (any of left,
right, and center). The default
is left.
- -lmargin1 => amount
-
The indentation for the first line of a paragraph.
- -lmargin2 => amount
-
The indentation for subsequent lines of a paragraph (for hanging
indents).
- -offset => amount
-
The amount the text is raised or lowered from the baseline (for
subscripts and superscripts).
- -overstrike => boolean
-
Draws the text with a line through it.
- -relief => type
-
The types of edges drawn around the text. Values for
type can be flat,
groove, raised,
ridge, and sunken. Default is
flat.
- -rmargin => amount
-
The right margin.
- -spacing1 => amount
-
The amount of space left on the top of a line of text that starts on
its own line.
- -spacing2 => amount
-
The amount of space left on the top of a line of text after it has
been automatically wrapped by the Text widget.
- -spacing3 => amount
-
The amount of space left after a line of text ended by
\n.
- -tabs => list
-
A list of tab stops to use in the Text widget.
- -underline => boolean
-
Whether to underline the text.
- -wrap => mode
-
Sets the mode for determining automatic line wrapping. Values are
none (no wrapping), char (wrap
at any character), or word (wrap at a word
boundary).
- tagCget
-
Returns configuration settings for a
tag.
- tagDelete
-
Deletes the specified tag(s).
- tagRemove
-
Removes the tags from the text in the
specified index range. (The tag itself remains defined, but is no
longer applied to that text.)
- tagRaise
-
Increases priority for a specified tag.
With only one argument, the tag takes highest priority over all
others; with a second argument of another tag, the
tag's priority is just higher than the second tag.
For example:
$text->tagRaise('bold','italic');
- tagLower
-
Decreases priority for a specified tag.
With only one argument, the tag takes lowest priority to all others;
with a second argument of another tag, the tag's
priority is just lower than the second tag. For example:
$text->tagLower('italic','bold');
- tagNames
-
Returns the names of all tags applying
to the specified index. With no index specified, returns all tags
defined for the Text widget, regardless of whether they have been
applied. For example:
@defined_tags = $text->tagNames;
- tagRanges
-
Returns a list of index ranges to which
the specified tag is defined. The returned list contains pairs of
starting and ending indexes for the ranges. For example:
@bold_indexes = $text->tagRanges('bold');
- tagNextrange
-
Given a tag
name and an index, returns the next index range to which the
specified tag is defined. For example:
@next_bold = $text->tagRanges('bold', 'insert');
21.11.4. Marks
A
mark is a particular position between characters
in a Text widget. Once you create a mark, you can use it as an index.
The gravity of the mark affects to which side the text is inserted.
Right gravity is the default, in which case the
text is inserted to the right of the mark.
The two marks that are automatically set are
insert and current. The
insert mark refers to the position of the insert
cursor. The current mark is the position closest
to the mouse cursor.
The following methods are defined for marking:
- markGravity
-
Sets the gravity of a mark. For example:
$text->markGravity('insert', 'left');
- markNames
-
Returns a list of all marks defined for
the Text widget.
- markSet
-
Creates a mark at a specified index:
$text->markSet('saved', 'insert');
- markUnset
-
Deletes mark(s) from the Text widget:
$text->markUnset('saved');
Note that you cannot delete the insert or
current marks.
 |  |  |
| 21.10. The Listbox Widget |  | 21.12. The Canvas Widget |
Copyright © 2002 O'Reilly & Associates. All rights reserved.