diff options
Diffstat (limited to 'tk/doc/text.n')
| -rw-r--r-- | tk/doc/text.n | 192 |
1 files changed, 166 insertions, 26 deletions
diff --git a/tk/doc/text.n b/tk/doc/text.n index 5a0892d76fc..5cf8d9603c8 100644 --- a/tk/doc/text.n +++ b/tk/doc/text.n @@ -8,26 +8,45 @@ '\" RCS: @(#) $Id$ '\" .so man.macros -.TH text n 4.0 Tk "Tk Built-In Commands" +.TH text n 8.4 Tk "Tk Built-In Commands" .BS '\" Note: do not modify the .SH NAME line immediately below! .SH NAME -text \- Create and manipulate text widgets +text, tk_textCopy, tk_textCut, tk_textPaste \- Create and manipulate text widgets .SH SYNOPSIS +.nf \fBtext\fR \fIpathName \fR?\fIoptions\fR? +.VS 8.4 +\fBtk_textCopy\fR \fIpathName\fR +\fBtk_textCut\fR \fIpathName\fR +\fBtk_textPaste\fR \fIpathName\fR +.VE 8.4 .SO -\-background \-highlightbackground \-insertontime \-selectborderwidth -\-borderwidth \-highlightcolor \-insertwidth \-selectforeground -\-cursor \-highlightthickness \-padx \-setgrid -\-exportselection \-insertbackground \-pady \-takefocus -\-font \-insertborderwidth \-relief \-xscrollcommand -\-foreground \-insertofftime \-selectbackground \-yscrollcommand +\-background \-highlightthickness \-relief +\-borderwidth \-insertbackground \-selectbackground +\-cursor \-insertborderwidth \-selectborderwidth +\-exportselection \-insertofftime \-selectforeground +\-font \-insertontime \-setgrid +\-foreground \-insertwidth \-takefocus +\-highlightbackground \-padx \-xscrollcommand +\-highlightcolor \-pady \-yscrollcommand .SE .SH "WIDGET-SPECIFIC OPTIONS" +.OP \-autoseparators autoSeparators AutoSeparators +.VS 8.4 +Specifies a boolean that says whether separators are automatically +inserted in the undo stack. Only meaningful when the \fB\-undo\fR +option is true. +.VE 8.4 .OP \-height height Height Specifies the desired height for the window, in units of characters in the font given by the \fB\-font\fR option. Must be at least one. +.OP \-maxundo maxUndo MaxUndo +.VS 8.4 +Specifies the maximum number of compound undo actions on the undo +stack. A zero or a negative value imply an unlimited undo stack. +.VE 8.4 .OP \-spacing1 spacing1 Spacing1 Requests additional space above each text line in the widget, using any of the standard forms for screen distances. @@ -81,6 +100,11 @@ options in tags. If no \fB\-tabs\fR option is specified, or if it is specified as an empty list, then Tk uses default tabs spaced every eight (average size) characters. +.OP \-undo undo Undo +.VS 8.4 +Specifies a boolean that says whether the undo mechanism is active or +not. +.VE 8.4 .OP \-width width Width Specifies the desired width for the window in units of characters in the font given by the \fB\-font\fR option. @@ -113,10 +137,8 @@ path name of the new window. .PP A text widget displays one or more lines of text and allows that text to be edited. -.VS Text widgets support four different kinds of annotations on the text, called tags, marks, embedded windows or embedded images. -.VE Tags allow different portions of the text to be displayed with different fonts and colors. In addition, Tcl commands can be associated with tags so @@ -134,11 +156,14 @@ The third form of annotation allows arbitrary windows to be embedded in a text widget. See EMBEDDED WINDOWS below for more details. .PP -.VS The fourth form of annotation allows Tk images to be embedded in a text widget. See EMBEDDED IMAGES below for more details. -.VE +.PP +.VS 8.4 +The text widget also has a built-in undo/redo mechanism. +See UNDO MECHANISM below for more details. +.VE 8.4 .SH INDICES .PP @@ -195,13 +220,11 @@ Indicates the position of the embedded window whose name is This form generates an error if there is no embedded window by the given name. .TP 12 -.VS \fIimageName\fR Indicates the position of the embedded image whose name is \fIimageName\fR. This form generates an error if there is no embedded image by the given name. -.VE .PP If the \fIbase\fP could match more than one of the above forms, such as a \fImark\fP and \fIimageName\fP both having the same value, then @@ -339,7 +362,7 @@ as an empty string, then a solid fill will be used. .TP \fB\-font \fIfontName\fR \fIFontName\fR is the name of a font to use for drawing characters. -It may have any of the forms accepted by \fBTk_GetFontStruct\fR. +It may have any of the forms accepted by \fBTk_GetFont\fR. .TP \fB\-foreground \fIcolor\fR \fIColor\fR specifies the color to use when drawing text and other @@ -524,7 +547,7 @@ 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. -.SH EMBEDDED WINDOWS +.SH "EMBEDDED WINDOWS" .PP The third form of annotation in text widgets is an embedded window. Each embedded window annotation causes a window to be displayed @@ -594,8 +617,7 @@ stretched. \fB\-window \fIpathName\fR Specifies the name of a window to display in the annotation. -.VS -.SH EMBEDDED IMAGES +.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 @@ -662,9 +684,8 @@ It may have any of the usual forms defined for a screen distance. \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 +.SH "THE SELECTION" .PP Selection support is implemented via tags. If the \fBexportSelection\fR option for the text widget is true @@ -680,6 +701,9 @@ characters with the \fBsel\fR tag. 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. +.IP [4] +Whenever the \fBsel\fR tag range changes a virtual event +\fB<<Selection>>\fR is generated. .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'' @@ -690,7 +714,7 @@ the text widget are tied to the \fB\-background\fR, tag: changes in either will automatically be reflected in the other. -.SH THE INSERTION CURSOR +.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 @@ -700,6 +724,47 @@ 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 "THE MODIFIED FLAG" +The text widget can keep track of changes to the content of the widget +by means of the modified flag. Inserting or deleting text will set +this flag. The flag can be queried, set and cleared programatically +as well. Whenever the flag changes state a \fB<<Modified>>\fR virtual +event is generated. See the \fBedit modified\fR widget command for +more details. + +.SH "THE UNDO MECHANISM" +.PP +.VS 8.4 +The text widget has an unlimited undo and redo mechanism (when the +\fB-undo\fR widget option is true) which records every insert and +delete action on a stack. +.PP +Boundaries (called "separators") are inserted between edit actions. +The purpose of these separators is to group inserts and deletes into +one compound edit action. When undoing a change everything between +two separators will be undone. The undone changes are then moved to +the redo stack, so that an undone edit can be redone again. The redo +stack is cleared whenever new edit actions are recorded on the undo +stack. The undo and redo stacks can be cleared to keep their depth +under control. +.PP +Separators are inserted automatically when the \fB-autoseparators\fR +widget option is true. You can insert separators programatically as +well. If a separator is already present at the top of the undo stack +no other will be inserted. That means that two separators on the undo +stack are always separated by at least one insert or delete action. +.PP +The undo mechanism is also linked to the modified flag. This means +that undoing or redoing changes can take a modified text widget back +to the unmodified state or vice versa. The modified flag will be set +automatically to the appropriate state. This automatic coupling +does not work when the modified flag has been set by the user, until +the flag has been reset again. +.PP +See below for the \fBedit\fR widget command that controls the undo +mechanism. +.VE 8.4 + .SH "WIDGET COMMAND" .PP The \fBtext\fR command creates a new Tcl command whose @@ -770,8 +835,15 @@ 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? +.PP +.VS 8.4 +When debugging is turned on, the drawing routines of the text widget +set the global variables \fBtk_textRedraw\fR and \fBtk_textRelayout\fR +to the lists of indices that are redrawn. The values of these variables +are tested by Tk's test suite. +.VE 8.4 +.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 @@ -784,6 +856,16 @@ If \fIindex2\fR isn't specified then the single character at 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. +.VS 8.4 +If more indices are given, multiple ranges of text will be deleted. +All indices are first checked for validity before any deletions are made. +They are sorted and the text is removed from the last range to the +first range to deleted text does not cause a undesired index shifting +side-effects. If multiple ranges with the same start index are given, +then the longest range is used. If overlapping ranges are given, then +they will be merged into spans that do not cause deletion of text +outside the given ranges due to text shifted during deletion. +.VE 8.4 .TP \fIpathName \fBdlineinfo \fIindex\fR Returns a list with five elements describing the area occupied @@ -861,7 +943,43 @@ 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? +\fIpathName \fBedit \fIoption \fR?\fIarg arg ...\fR? +.VS 8.4 +This command controls the undo mechanism and the modified flag. The +exact behavior of the command depends on the \fIoption\fR argument +that follows the \fBedit\fR argument. The following forms of the +command are currently supported: +.RS +.TP +\fIpathName \fBedit modified ?\fIboolean\fR? +If \fIboolean\fR 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 \fIboolean\fR is +specified, sets the modified flag of the widget to \fIboolean\fR. +.TP +\fIpathName \fBedit redo\fR +When the \fB-undo\fR 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 the \fB-undo\fR option is +false. +.TP +\fIpathName \fBedit reset\fR +Clears the undo and redo stacks. +.TP +\fIpathName \fBedit separator\fR +Inserts a separator (boundary) on the undo stack. Does nothing when +the \fB-undo\fR option is false. +.TP +\fIpathName \fBedit undo\fR +Undoes the last edit action when the \fB-undo\fR 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 \fB-undo\fR +option is false. +.RE +.VE 8.4 +.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 @@ -874,6 +992,11 @@ 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. +.VS 8.4 +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 \fBget\fR. +.VE 8.4 .TP \fIpathName \fBimage \fIoption \fR?\fIarg arg ...\fR? This command is used to manipulate embedded images. @@ -1552,15 +1675,24 @@ Control-\e clears any selection in the widget. .IP [20] The F16 key (labelled Copy on many Sun workstations) or Meta-w copies the selection in the widget to the clipboard, if there is a selection. +.VS 8.4 +This action is carried out by the command \fBtk_textCopy\fR. +.VE 8.4 .IP [21] The F20 key (labelled Cut on many Sun workstations) or Control-w copies the selection in the widget to the clipboard and deletes the selection. +.VS 8.4 +This action is carried out by the command \fBtk_textCut\fR. +.VE 8.4 If there is no selection in the widget then these keys have no effect. .IP [22] The F18 key (labelled Paste on many Sun workstations) or Control-y inserts the contents of the clipboard at the position of the insertion cursor. +.VS 8.4 +This action is carried out by the command \fBtk_textPaste\fR. +.VE 8.4 .IP [23] The Delete key deletes the selection, if there is one in the widget. If there is no selection, it deletes the character to the right of @@ -1589,6 +1721,15 @@ Control-x deletes whatever is selected in the text widget. .IP [31] Control-t reverses the order of the two characters to the right of the insertion cursor. +.IP [32] +.VS 8.4 +Control-z (and Control-underscore on UNIX when \fBtk_strictMotif\fR is +true) undoes the last edit action if the \fB-undo\fR option is true. +Does nothing otherwise. +.IP [33] +Control-Z (or Control-y on Windows) reapplies the last undone edit +action if the \fB-undo\fR option is true. Does nothing otherwise. +.VE 8.4 .PP If the widget is disabled using the \fB\-state\fR option, then its view can still be adjusted and text can still be selected, @@ -1632,5 +1773,4 @@ The display line with the insert cursor is redrawn each time the cursor blinks, which causes a steady stream of graphics traffic. Set the \fBinsertOffTime\fP attribute to 0 avoid this. .SH KEYWORDS -text, widget - +text, widget, tkvars |