Tk

 view release on metacpan or  search on metacpan

pod/Text.pod  view on Meta::CPAN

=item Class:	B<Width>

=item Switch:	B<-width>

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

=item Name:	B<wrap>

=item Class:	B<Wrap>

=item Switch:	B<-wrap>

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 B<none> or B<char> or B<word>.
A wrap mode of B<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 B<char> mode a screen line break may occur after any character;
in B<word> mode a line break will only be made at word boundaries.

=back

=head1 DESCRIPTION

The B<Text> method creates a new window (given by the
$text argument) and makes it into a text widget.
Additional
options, described above, may be specified on the command line
or in the option database
to configure aspects of the text such as its default background color
and relief.  The B<text> command returns the
path name of the new window.

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.
Tags allow different portions of the text
to be displayed with different fonts and colors.
In addition, L<perlE<sol>Tk callbacks|Tk::callbacks> can be associated with tags so
that scripts are invoked when particular actions such as keystrokes
and mouse button presses occur in particular ranges of the text.
See L<"TAGS"> below for more details.

The second form of annotation consists of marks, which are floating
markers in the text.
Marks are used to keep track of various interesting positions in the
text as it is edited.
See L<"MARKS"> below for more details.

The third form of annotation allows arbitrary windows to be
embedded in a text widget.
See L<"EMBEDDED WINDOWS"> below for more details.

The fourth form of annotation allows Tk images to be embedded in a text
widget.
See L<"EMBEDDED IMAGES"> below for more details.

The Perl/Tk B<Text> widget does not support undo/redo, use the B<TextUndo>
widget instead.

=head1 INDICES

Many of the methods for texts take one or more indices
as arguments.
An index is a string 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 I<base> gives a starting point and the I<modifier>s
adjust the index from the starting point (e.g. move forward or
backward one character).  Every index must contain a I<base>,
but the I<modifier>s are optional.

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

=over 4

=item I<line>B<.>I<char>

Indicates I<char>'th character on line I<line>.
Lines are numbered from 1 for consistency with other UNIX programs
that use this numbering scheme.
Within a line, characters are numbered from 0.
If I<char> is B<end> then it refers to the newline character
that ends the line.

=item B<@>I<x>B<,>I<y>

Indicates the character that covers the pixel whose x and y coordinates
within the text's window are I<x> and I<y>.

=item B<end>

Indicates the end of the text (the character just after the last
newline).

=item I<mark>

Indicates the character just after the mark whose name is I<mark>.

=item I<tag>B<.first>

Indicates the first character in the text that has been tagged with
I<tag>.
This form generates an error if no characters are currently tagged
with I<tag>.

=item I<tag>B<.last>

Indicates the character just after the last one in the text that has
been tagged with I<tag>.
This form generates an error if no characters are currently tagged
with I<tag>.

pod/Text.pod  view on Meta::CPAN

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
<perl/Tk callback|Tk::callbacks> 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 B<tagBind> widget
method below.

The third use for tags is in managing the selection.
See L<"THE SELECTION"> below.

=head1 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 may be manipulated with the ``I<$text>-E<gt>B<mark>'' text widget
method, and their current locations may be determined by using the
mark name as an index in methods.

Each mark also has a I<gravity>, which is either B<left> or
B<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 B<right>.

The name space for marks is different from that for tags:  the
same name may be used for both a mark and a tag, but they will refer
to different things.

Two marks have special significance.
First, the mark B<insert> is associated with the insertion cursor,
as described under L<"THE INSERTION CURSOR"> below.
Second, the mark B<current> 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:  B<current> 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).
Neither of these special marks may be deleted.

=head1 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 (subject to the
usual rules for geometry management, which require the text window
to be the parent of the embedded window or a descendant of its
parent).
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.

When an embedded window is added to a text widget with the
B<widgetCreate> method, several configuration
options may be associated with it.
These options may be  modified later with the B<widgetConfigure>
method.
The following options are currently supported:

=over 4

=item B<-align> =E<gt> I<where>

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.
I<Where> must have one of the values B<top> (align the top of the window
with the top of the line), B<center> (center the window
within the range of the line), B<bottom> (align the bottom of the
window with the bottom of the line's area),
or B<baseline> (align the bottom of the window with the baseline
of the line).

=item B<-create> =E<gt> I<callback>

Specifies a L<callback|Tk::callbacks> that may be evaluated to create the window
for the annotation.
If no B<-window> option has been specified for the annotation
this I<callback> will be evaluated when the annotation is about to
be displayed on the screen.
I<Callback> must create a window for the annotation and return
the name of that window as its result.
If the annotation's window should ever be deleted, I<callback>
will be evaluated again the next time the annotation is displayed.

=item B<-padx> =E<gt> I<pixels>

I<Pixels> specifies the amount of extra space to leave on
each side of the embedded window.
It may have any of the usual forms defined for a screen distance
(see B<Tk_GetPixels>).

=item B<-pady> =E<gt> I<pixels>

I<Pixels> specifies the amount of extra space to leave on
the top and on the bottom of the embedded window.
It may have any of the usual forms defined for a screen distance
(see B<Tk_GetPixels>).

=item B<-stretch> =E<gt> I<boolean>

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 B<-pady> option has been specified as well, then the
requested padding will be retained even if the window is
stretched.

=item B<-window> =E<gt> I<$widget>

Specifies the name of a window to display in the annotation.

=back

=head1 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 with B<imageCreate>.
If the range of text containing the embedded image is deleted then
that copy of the image is removed from the screen.

When an embedded image is added to a text widget with the B<image>
create method, a name unique to this instance of the image
is returned.  This name may then be used to refer to this image
instance.  The name is taken to be the value of the B<-name> option
(described below).  If the B<-name> option is not provided, the
B<-image> name is used instead.  If the I<imageName> is already
in use in the text widget, then B<#>I<nn> is added to the end of the
I<imageName>, where I<nn> is an arbitrary integer.  This insures
the I<imageName> is unique.
Once this name is assigned to this instance of the image, it does not
change, even though the B<-image> or B<-name> values can be changed
with B<image configure>.

When an embedded image is added to a text widget with the
B<imageCreate> method, several configuration
options may be associated with it.
These options may be modified later with the B<image configure>
method.
The following options are currently supported:

=over 4

=item B<-align> =E<gt> I<where>

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.
I<Where> must have one of the values B<top> (align the top of the image
with the top of the line), B<center> (center the image
within the range of the line), B<bottom> (align the bottom of the
image with the bottom of the line's area),
or B<baseline> (align the bottom of the image with the baseline
of the line).

=item B<-image> =E<gt> I<image>

Specifies the name of the Tk image to display in the annotation.
If I<image> is not a valid Tk image, then an error is returned.

=item B<-name> =E<gt> I<ImageName>

Specifies the name by which this image instance may be referenced in
the text widget. If I<ImageName> is not supplied, then the
name of the Tk image is used instead.
If the I<imageName> is already in use, I<#nn> is appended to

pod/Text.pod  view on Meta::CPAN

Gets the currently selected text and removes all selections. It then
finds the next exact, case-sensitive string that matches in a forward
direction and selects the text and makes the new selection visible.

=item I<$text>-E<gt>B<FindSelectionPrevious>

Gets the currently selected text and removes all selections. It then
finds the next exact, case-sensitive string that matches in a reverse
direction and selects the text and makes the new selection visible.

=item I<$text>-E<gt>B<get>(I<index1, >?I<index2>?)

Return a range of characters from the text.  The return value will be
all the characters in the text starting with the one whose index is
I<index1> and ending just before the one whose index is I<index2> (the
character at I<index2> will not be returned).  If I<index2> is omitted
then the single character at I<index1> is returned.  If there are no
characters in the specified range (e.g. I<index1> is past the end of
the file or I<index2> is less than or equal to I<index1>) then an
empty string is returned.  If the specified range contains embedded
windows, no information about them is included in the returned string.
If multiple index pairs are given, multiple ranges of text will be
returned in a list.  Invalid ranges will not be represented with empty
strings in the list.  The ranges are returned in the order passed to
B<get>.

=item I<$text>-E<gt>B<getSelected>

Return the currently selected text.

=item I<$text>-E<gt>B<GetTextTaggedWith>(I<tag>)

Return the text tagged with the I<tag> parameter.

=item I<$text>-E<gt>B<GotoLineNumber>(I<line_number>)

Set the insert mark to I<line_number> and ensures the line is
visible.

=item I<$text>-E<gt>B<GotoLineNumberPopUp>(I<line_number>)

Displays a popup, pre-filling it with selected numeric text
(if any), or the line number from B<GotoLineNumber> (if any).

=item I<$text>-E<gt>B<image>(I<option>, ?I<arg, arg, ...>?)

=item I<$text>-E<gt>B<image>I<Option>(?I<arg, arg, ...>?)

This method is used to manipulate embedded images.
The behavior of the method depends on the I<option> argument
that follows the B<image> prefix.
The following forms of the methods are currently supported:

=over 8

=item I<$text>-E<gt>B<imageCget>(I<index, option>)

Returns the value of a configuration option for an embedded image.
I<Index> identifies the embedded image, and I<option>
specifies a particular configuration option, which must be one of
the ones listed in L<"EMBEDDED IMAGES">.

=item I<$text>-E<gt>B<imageConfigure>(I<index, >?I<option, value, ...>?)

Query or modify the configuration options for an embedded image.
If no I<option> is specified, returns a list describing all of
the available options for the embedded image at I<index>
(see L<Tk::options> for information on the format of this list).
If I<option> is specified with no I<value>, then the command
returns a list describing the one named option (this list will be
identical to the corresponding sublist of the value returned if no
I<option> is specified).
If one or more I<option-value> pairs are specified, then the command
modifies the given option(s) to have the given value(s);  in
this case the command returns an empty string.
See L<"EMBEDDED IMAGES"> for information on the options that
are supported.

=item I<$text>-E<gt>B<imageCreate>(I<index, >?I<option, value, ...>?)

This command creates a new image annotation, which will appear
in the text at the position given by I<index>.
Any number of I<option-value> pairs may be specified to
configure the annotation.
Returns a unique identifier that may be used as an index to refer to
this image.
See L<"EMBEDDED IMAGES"> for information on the options that
are supported, and a description of the identifier returned.

=item I<$text>-E<gt>B<imageNames>

Returns a list whose elements are the names of all image instances currently
embedded in $text.

=back

=item I<$text>-E<gt>B<index>(I<index>)

Returns the position corresponding to I<index> in the form
I<line.char> where I<line> is the line number and I<char>
is the character number.
I<Index> may have any of the forms described under L<"INDICES"> above.

=item I<$text>-E<gt>B<insert>(I<index, chars, >?I<tagList, chars, tagList, ...>?)

Inserts all of the I<chars> arguments just before the character at
I<index>.
If I<index> 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 I<chars> argument and no I<tagList>, 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 I<tagList> is specified then it consists of a list of
tag names;  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 I<chars>-I<tagList> argument pairs are present,
they produce the same effect as if a separate B<insert> widget
command had been issued for each pair, in order.
The last I<tagList> argument may be omitted.

=item I<$text>-E<gt>B<Insert>(I<string>)

Do NOT confuse this with the lower-case B<insert> method.
Insert I<string> at the point of the insertion cursor. If there is
a selection in the text, and it covers the point of the insertion
cursor, then it deletes the selection before inserting.

=item I<$text>-E<gt>B<InsertKeypress>(I<character>)

Inserts I<character> at the B<insert> mark. If in overstrike mode,
it firsts deletes the character at the B<insert> mark.

=item I<$text>-E<gt>B<InsertSelection>

Inserts the current selection at the B<insert> mark.

=item I<$text>-E<gt>B<insertTab>

Inserts a tab (\t) character at the B<insert> mark.

=item I<$text>-E<gt>B<mark>(I<option, >?I<arg, arg, ...>?)

This command is used to manipulate marks.  The exact behavior of

pod/Text.pod  view on Meta::CPAN

=item I<$text>-E<gt>B<tagRanges>(I<tagName>)

Returns a list describing all of the ranges of text that have been
tagged with I<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 I<tag> then an
empty string is returned.

=item I<$text>-E<gt>B<tagRemove>(I<tagName, index1, >?I<index2, index1, index2, ...>?)

Remove the tag I<tagName> from all of the characters starting
at I<index1> and ending just before
I<index2> (the character at I<index2> isn't affected).
A single command may contain any number of I<index1>-I<index2>
pairs.
If the last I<index2> is omitted then the single character at
I<index1> is tagged.
If there are no characters in the specified range (e.g. I<index1>
is past the end of the file or I<index2> is less than or equal
to I<index1>) then the command has no effect.
This command returns an empty string.

=back

=item I<$text>-E<gt>B<ToggleInsertMode>

Toggles the current overstrike mode.

=item I<$text>-E<gt>B<unselectAll>

Unselects all the text in the widget.

=item I<$text>-E<gt>B<WhatLineNumberPopup>

Creates a popup that displays the current line number of the
insert mark.

=item I<$text>->B<widget>(I<option?, arg, arg, ...>?)

=item I<$text>->B<widget>I<Option>(?I<arg, arg, ...>?)

This method is used to manipulate embedded windows.
The behavior of the method depends on the I<option> argument
that follows the B<window> argument.
The following forms of the method are currently supported:

=over 8

=item I<$text>->B<windowCget>(I<index, option>)

Returns the value of a configuration option for an embedded window.
I<Index> identifies the embedded window, and I<option>
specifies a particular configuration option, which must be one of
the ones listed in L<"EMBEDDED WINDOWS"> above.

=item I<$text>->B<windowConfigure>(I<index>?, I<option, value, ...>?)

Query or modify the configuration options for an embedded window.
If no I<option> is specified, returns a list describing all of
the available options for the embedded window at I<index>
(see L<Tk::options> for information on the format of this list).
If I<option> is specified with no I<value>, then the command
returns a list describing the one named option (this list will be
identical to the corresponding sublist of the value returned if no
I<option> is specified).
If one or more I<option-value> pairs are specified, then the command
modifies the given option(s) to have the given value(s);  in
this case the command returns an empty string.
See L<"EMBEDDED WINDOWS"> above for information on the options that
are supported.

=item I<$text>->B<windowCreate>(I<index>?, I<option, value, ...>?)

This command creates a new window annotation, which will appear
in the text at the position given by I<index>.
Any number of I<option-value> pairs may be specified to
configure the annotation.
See L<"EMBEDDED WINDOWS"> above for information on the options that
are supported.
Returns an empty string.

=item I<$text>->B<windowNames>

Returns a list whose elements are the names of all windows currently
embedded in $text.

=back

=item I<$text>->B<xview>(I<option, args>)

This command is used to query and change the horizontal position of the
text in the widget's window.  It can take any of the following
forms:

=over 8

=item I<$text>->B<xview>

Returns a list containing two elements.
Each element is a real fraction between 0 and 1;  together they describe
the portion of the document's horizontal span that is visible in
the window.
For example, if the first element is .2 and the second element is .6,
20% of the text is off-screen to the left, the middle 40% is visible
in the window, and 40% of the text is off-screen to the right.
The fractions refer only to the lines that are actually visible in the
window:  if the lines in the window are all very short, so that they
are entirely visible, the returned fractions will be 0 and 1,
even if there are other lines in the text that are
much wider than the window.
These are the same values passed to scrollbars via the B<-xscrollcommand>
option.

=item I<$text>-E<gt>B<xviewMoveto>(I<fraction>)

Adjusts the view in the window so that I<fraction> of the horizontal
span of the text is off-screen to the left.
I<Fraction> is a fraction between 0 and 1.

=item I<$text>-E<gt>B<xviewScroll>(I<number, what>)

This command shifts the view in the window left or right according to
I<number> and I<what>.
I<Number> must be an integer.
I<What> must be either B<units> or B<pages> or an abbreviation
of one of these.
If I<what> is B<units>, the view adjusts left or right by
I<number> average-width characters on the display;  if it is
B<pages> then the view adjusts by I<number> screenfuls.
If I<number> is negative then characters farther to the left
become visible;  if it is positive then characters farther to the right
become visible.

=back

=item I<$text>-E<gt>B<yview>(I<?args>?)

This command is used to query and change the vertical position of the