text.n

linux系统下的音频通信

.VS
.SH EMBEDDED IMAGES
.PP
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 \fBimage create\fP.
If the range of text containing the embedded image is deleted then
that copy of the image is removed from the screen.
.PP
When an embedded image is added to a text widget with the \fBimage
create\fR widget command, 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 \fB-name\fP option
(described below).  If the \fB-name\fP option is not provided, the
\fB-image\fP name is used instead.  If the \fIimageName\fP is already
in use in the text widget, then \fB#\fInn\fR is added to the end of the
\fIimageName\fP, where \fInn\fP is an arbitrary integer.  This insures
the \fIimageName\fP is unique.
Once this name is assigned to this instance of the image, it does not 
change, even though the \fB-image\fP or \fB-name\fP values can be changed
with \fBimage configure\fP.
.PP
When an embedded image is added to a text widget with the
\fBimage create\fR widget command, several configuration
options may be associated with it.
These options may be modified later with the \fBimage configure\fR
widget command.
The following options are currently supported:
.TP
\fB\-align \fIwhere\fR
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.
\fIWhere\fR must have one of the values \fBtop\fR (align the top of the image
with the top of the line), \fBcenter\fR (center the image
within the range of the line), \fBbottom\fR (align the bottom of the
image with the bottom of the line's area),
or \fBbaseline\fR (align the bottom of the image with the baseline
of the line).
.TP
\fB\-image \fIimage\fR
Specifies the name of the Tk image to display in the annotation.
If \fIimage\fP is not a valid Tk image, then an error is returned.
.TP
\fB\-name \fIImageName\fR
Specifies the name by which this image instance may be referenced in
the text widget. If \fIImageName\fP is not supplied, then the
name of the Tk image is used instead.
If the \fIimageName\fP is already in use, \fI#nn\fP is appended to
the end of the name as described above.
.TP
\fB\-padx \fIpixels\fR
\fIPixels\fR specifies the amount of extra space to leave on
each side of the embedded image.
It may have any of the usual forms defined for a screen distance.
.TP
\fB\-pady \fIpixels\fR
\fIPixels\fR specifies the amount of extra space to leave on
the top and on the bottom of the embedded image.
It may have any of the usual forms defined for a screen distance.
.VE

.SH THE SELECTION
.PP
Selection support is implemented via tags.
If the \fBexportSelection\fR option for the text widget is true
then the \fBsel\fR tag will be associated with the selection:
.IP [1]
Whenever characters are tagged with \fBsel\fR the text widget
will claim ownership of the selection.
.IP [2]
Attempts to retrieve the
selection will be serviced by the text widget, returning all the
characters with the \fBsel\fR tag.
.IP [3]
If the selection is claimed away by another application or by another
window within this application, then the \fBsel\fR tag will be removed
from all characters in the text.
.PP
The \fBsel\fR tag is automatically defined when a text widget is
created, and it may not be deleted with the ``\fIpathName \fBtag delete\fR''
widget command.  Furthermore, the \fBselectBackground\fR,
\fBselectBorderWidth\fR, and \fBselectForeground\fR options for
the text widget are tied to the \fB\-background\fR,
\fB\-borderwidth\fR, and \fB\-foreground\fR options for the \fBsel\fR
tag:  changes in either will automatically be reflected in the
other.

.SH THE INSERTION CURSOR
.PP
The mark named \fBinsert\fR has special significance in text widgets.
It is defined automatically when a text widget is created and it
may not be unset with the ``\fIpathName \fBmark unset\fR'' widget
command.
The \fBinsert\fR mark represents the position of the insertion
cursor, and the insertion cursor will automatically be drawn at
this point whenever the text widget has the input focus.

.SH "WIDGET COMMAND"
.PP
The \fBtext\fR command creates a new Tcl command whose
name is the same as the path name of the text's window.  This
command may be used to invoke various
operations on the widget.  It has the following general form:
.CS
\fIpathName option \fR?\fIarg arg ...\fR?
.CE
\fIPathName\fR is the name of the command, which is the same as
the text widget's path name.  \fIOption\fR and the \fIarg\fRs
determine the exact behavior of the command.  The following
commands are possible for text widgets:
.TP
\fIpathName \fBbbox \fIindex\fR
Returns a list of four elements describing the screen area
of the character given by \fIindex\fR.
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.
.TP
\fIpathName \fBcget\fR \fIoption\fR
Returns the current value of the configuration option given
by \fIoption\fR.
\fIOption\fR may have any of the values accepted by the \fBtext\fR
command.
.TP
\fIpathName \fBcompare\fR \fIindex1 op index2\fR
Compares the indices given by \fIindex1\fR and \fIindex2\fR according
to the relational operator given by \fIop\fR, and returns 1 if
the relationship is satisfied and 0 if it isn't.
\fIOp\fR must be one of the operators <, <=, ==, >=, >, or !=.
If \fIop\fR is == then 1 is returned if the two indices refer to
the same character, if \fIop\fR is < then 1 is returned if \fIindex1\fR
refers to an earlier character in the text than \fIindex2\fR, and
so on.
.TP
\fIpathName \fBconfigure\fR ?\fIoption\fR? \fI?value option value ...\fR?
Query or modify the configuration options of the widget.
If no \fIoption\fR is specified, returns a list describing all of
the available options for \fIpathName\fR (see \fBTk_ConfigureInfo\fR for
information on the format of this list).  If \fIoption\fR is specified
with no \fIvalue\fR, 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 \fIoption\fR is specified).  If
one or more \fIoption\-value\fR 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.
\fIOption\fR may have any of the values accepted by the \fBtext\fR
command.
.TP
\fIpathName \fBdebug \fR?\fIboolean\fR?
If \fIboolean\fR is specified, then it must have one of the true or
false values accepted by Tcl_GetBoolean.
If the value is a true one then internal consistency checks will be
turned on in the B-tree code associated with text widgets.
If \fIboolean\fR has a false value then the debugging checks will
be turned off.
In either case the command returns an empty string.
If \fIboolean\fR is not specified then the command returns \fBon\fR
or \fBoff\fR to indicate whether or not debugging is turned on.
There is a single debugging switch shared by all text widgets:  turning
debugging on or off in any widget turns it on or off for all widgets.
For widgets with large amounts of text, the consistency checks may
cause a noticeable slow-down.
.TP
\fIpathName \fBdelete \fIindex1 \fR?\fIindex2\fR?
Delete a range of characters from the text.
If both \fIindex1\fR and \fIindex2\fR are specified, then delete
all the characters starting with the one given by \fIindex1\fR
and stopping just before \fIindex2\fR (i.e. the character at
\fIindex2\fR is not deleted).
If \fIindex2\fR doesn't specify a position later in the text
than \fIindex1\fR then no characters are deleted.
If \fIindex2\fR isn't specified then the single character at
\fIindex1\fR is deleted.
It is not allowable to delete characters in a way that would leave
the text without a newline as the last character.
The command returns an empty string.
.TP
\fIpathName \fBdlineinfo \fIindex\fR
Returns a list with five elements describing the area occupied
by the display line containing \fIindex\fR.
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 \fBnone\fR 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 \fIindex\fR is not visible on
the screen then the return value is an empty list.
.TP
\fIpathName \fBdump \fR?\fIswitches\fR? \fIindex1 \fR?\fIindex2\fR?
Return the contents of the text widget from \fIindex1\fR up to,
but not including \fIindex2\fR,
including the text and
information about marks, tags, and embedded windows.
If \fIindex2\fR is not specified, then it defaults to
one character past \fIindex1\fR.  The information is returned
in the following format:
.LP
.RS
\fIkey1 value1 index1 key2 value2 index2\fR ...
.LP
The possible \fIkey\fP values are \fBtext\fP, \fBmark\fP,
\fBtagon\fP, \fBtagoff\fP, and \fBwindow\fP.  The corresponding
\fIvalue\fP is the text, mark name, tag name, or window name.
The \fIindex\fP 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 (or abbreviations thereof)
may be specified to control the dump:
.TP
\fB\-all\fR
Return information about all elements: text, marks, tags, and windows.
This is the default.
.TP
\fB\-command \fIcommand\fR
Instead of returning the information as the result of the dump operation,
invoke the \fIcommand\fR on each element of the text widget within the range.
The command has three arguments appended to it before it is evaluated:
the \fIkey\fP, \fIvalue\fP, and \fIindex\fP.
.TP
\fB\-mark\fR
Include information about marks in the dump results.
.TP
\fB\-tag\fR
Include information about tag transitions in the dump results. Tag information is
returned as \fBtagon\fP and \fBtagoff\fP elements that indicate the
begin and end of each range of each tag, respectively.
.TP
\fB\-text\fR
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 \fIindex2\fR.
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.
.TP
\fB\-window\fR
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.  (It must have a create script.)
In this case an empty string is returned, and you must query the
window by its index position to get more information.
.RE
.TP
\fIpathName \fBget \fIindex1 \fR?\fIindex2\fR?
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 \fIindex1\fR and ending just before
the one whose index is \fIindex2\fR (the character at \fIindex2\fR
will not be returned).
If \fIindex2\fR is omitted then the single character at \fIindex1\fR
is returned.
If there are no characters in the specified range (e.g. \fIindex1\fR
is past the end of the file or \fIindex2\fR is less than or equal
to \fIindex1\fR) then an empty string is returned.
If the specified range contains embedded windows, no information
about them is included in the returned string.
.TP
\fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR?
This command is used to manipulate embedded images.
The behavior of the command depends on the \fIoption\fR argument
that follows the \fBtag\fR argument.
The following forms of the command are currently supported:
.RS
.TP
\fIpathName \fBimage cget\fR \fIindex option\fR
Returns the value of a configuration option for an embedded image.
\fIIndex\fR identifies the embedded image, and \fIoption\fR
specifies a particular configuration option, which must be one of
the ones listed in the section EMBEDDED IMAGES.
.TP
\fIpathName \fBimage configure \fIindex\fR ?\fIoption value ...\fR?
Query or modify the configuration options for an embedded image.
If no \fIoption\fR is specified, returns a list describing all of