www.delorie.com/gnu/docs/gcl/gcl-tk_114.html   search  
 
Buy GNU books!


Untitled Document

[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

A Text Widget's Arguments

The text 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:

 
pathName option ?arg arg ...?

PathName is the name of the command, which is the same as the text widget's path name. Option and the args determine the exact behavior of the command. The following commands are possible for text widgets:

pathName :compare index1 op index2
Compares the indices given by index1 and index2 according to the relational operator given by op, and returns 1 if the relationship is satisfied and 0 if it isn't. Op must be one of the operators <, <=, ==, >=, >, or !=. If op is == then 1 is returned if the two indices refer to the same character, if op is < then 1 is returned if index1 refers to an earlier character in the text than index2, and so on.
pathName :configure ?option? ?value option value ...?
Query or modify the configuration options of the widget. If no option is specified, returns a list describing all of the available options for pathName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no 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 option is specified). 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. Option may have any of the values accepted by the text command.
pathName :debug ?boolean?
If boolean 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 boolean has a false value then the debugging checks will be turned off. In either case the command returns an empty string. If boolean is not specified then the command returns on or off 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.
pathName :delete index1 ?index2?
Delete a range of characters from the text. If both index1 and index2 are specified, then delete all the characters starting with the one given by index1 and stopping just before index2 (i.e. the character at index2 is not deleted). If index2 doesn't specify a position later in the text than index1 then no characters are deleted. If index2 isn't specified then the single character at index1 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.
pathName :get index1 ?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 index1 and ending just before the one whose index is index2 (the character at index2 will not be returned). If index2 is omitted then the single character at index1 is returned. 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 an empty string is returned.
pathName :index index
Returns the position corresponding to index in the form line.char where line is the line number and char is the character number. Index may have any of the forms described under INDICES above.
pathName :insert \fIindex chars
Inserts chars into the text just before the character at index and returns an empty string. It is not possible to insert characters after the last newline of the text.
pathName :mark option ?arg arg ...?
This command is used to manipulate marks. The exact behavior of the command depends on the option argument that follows the mark argument. The following forms of the command are currently supported:
pathName :mark :names
Returns a list whose elements are the names of all the marks that are currently set.
pathName :mark :set markName index
Sets the mark named markName to a position just before the character at index. If markName already exists, it is moved from its old position; if it doesn't exist, a new mark is created. This command returns an empty string.
pathName :mark :unset markName ?markName markName ...?
Remove the mark corresponding to each of the markName arguments. The removed marks will not be usable in indices and will not be returned by future calls to "pathName :mark names". This command returns an empty string.

pathName :scan option args
This command is used to implement scanning on texts. It has two forms, depending on option:
pathName :scan :mark y
Records y and the current view in the text window; used in conjunction with later scan dragto commands. Typically this command is associated with a mouse button press in the widget. It returns an empty string.
pathName :scan :dragto y
This command computes the difference between its y argument and the y argument to the last scan mark command for the widget. It then adjusts the view up or down by 10 times the difference in y-coordinates. This command is typically associated with mouse motion events in the widget, to produce the effect of dragging the text at high speed through the window. The return value is an empty string.

pathName :tag option ?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?
Associate the tag tagName with all of the characters starting with index1 and ending just before index2 (the character at index2 isn't tagged). If 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.
pathName :tag :bind tagName ?sequence? ?command?
This command associates command with the tag given by tagName. Whenever the event sequence given by sequence occurs for a character that has been tagged with tagName, the command will be invoked. This widget command is similar to the bind command except that it operates on characters in a text rather than entire widgets. See the bind manual entry for complete details on the syntax of sequence and the substitutions performed on command before invoking it. If all arguments are specified then a new binding is created, replacing any existing binding for the same sequence and tagName (if the first character of command is "+" then command augments an existing binding rather than replacing it). In this case the return value is an empty string. If command is omitted then the command returns the command associated with tagName and sequence (an error occurs if there is no such binding). If both command and sequence are omitted then the command returns a list of all the sequences for which bindings have been defined for tagName.

The only events for which bindings may be specified are those related to the mouse and keyboard, such as Enter, Leave, ButtonPress, Motion, and KeyPress. Event bindings for a text widget use the current mark described under MARKS above. Enter events trigger for a character when it becomes the current character (i.e. the current mark moves to just in front of that character). Leave events trigger for a character when it ceases to be the current item (i.e. the current mark moves away from that character, or the character is deleted). These events are different than Enter and Leave events for windows. Mouse and keyboard events are directed to the current character.

It is possible for the current character to have multiple tags, and for each of them to have a binding for a particular event sequence. When this occurs, the binding from the highest priority tag is used. If a particular tag doesn't have a binding that matches an event, then the tag is ignored and tags with lower priority will be checked.

If bindings are created for the widget as a whole using the bind command, then those bindings will supplement the tag bindings. This means that a single event can trigger two Tcl scripts, one for a widget-level binding and one for a tag-level binding.

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. If no option is specified, the command returns a list describing all of the available options for tagName (see Tk_ConfigureInfo for information on the format of this list). If option is specified with no 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 option is specified). If one or more option:value pairs are specified, then the command modifies the given option(s) to have the given value(s) in tagName; in this case the command returns an empty string. See TAGS above for details on the options available for tags.
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 :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?
Remove the tag tagName from all of the characters starting at index1 and ending just before index2 (the character at index2 isn't affected). If index2 is omitted then the single character at index1 is untagged. 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.

pathName :yview ?:pickplace? what
This command changes the view in the widget's window so that the line given by what is visible in the window. What may be either an absolute line number, where 0 corresponds to the first line of the file, or an index with any of the forms described under INDICES above. The first form (absolute line number) is used in the commands issued by scrollbars to control the widget's view. If the :pickplace option isn't specified then what will appear at the top of the window. If :pickplace is specified then the widget chooses where what appears in the window:

The :pickplace option is typically used after inserting text to make sure that the insertion cursor is still visible on the screen. This command returns an empty string.


[ < ] [ > ]   [ << ] [ Up ] [ >> ]         [Top] [Contents] [Index] [ ? ]

  webmaster     delorie software   privacy  
  Copyright 2003   by The Free Software Foundation     Updated Jun 2003