Defined in Text.Def
Mixes in with Object
Inherits interface from FormElement
The HasText mixin provides its subclasses with a wide and useful variety of methods for inserting, replacing, deleting, and appending text and characters to text objects. It is the foundation for all text-containing and -manipulating classes in Magic Cap. Understand it, and you understand most of the TextContainer and TextField classes
Version note: This chapter is under construction. Please put on your hard hat before reading any further.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
The HasText mixin has two notable subclasses: class Text and class TextContainer. Class Text is the implementation of HasText that you'll use most often.
You will never work directly with objects of class HasText. Instead, you will work with objects of one of its many subclasses: strings, text objects, text fields, digit fields, date fields, or attribute text objects.
Instantiate: never Subclass: always Call its methods: rarely
Most of the methods of HasText are convenience routines, which manipulate text in many handy ways. The convenience routines depend on a few bottlenecks, which aren't implemented in HasText. Classes which mix in HasText implement the bottlenecks, and therefore implement the actual text. The bottlenecks are:
| Method | Brief description |
|---|---|
| Reading text | |
| EachTextRunInRange | Reads text chunks |
| TextRangeMark | Reads text styles |
| TextLength | Returns length of text |
| Writing text | |
| ReplaceTextData | Replaces text with new text |
| MarkTextRange | Writes text style marks |
Version note: The methods description section of this chapter has not yet been written. Because of that lack, the following table is a complete list of methods defined by HasText, with brief notes on what they do. When more complete HasText documentation comes into being, this table will shorten.
Class HasText has the following methods you might call:
| Method | Description |
|---|---|
| Operating on an entire text object | |
| Content | Returns self |
| SetContent | Replaces the current text with the new text |
| DeleteText | Deletes the text without deleting the object |
| ReplaceText | Replaces all text with the new text |
| ReplaceTextWithCharacters | Given some characters, replaces the current text data with the characters |
| ReplaceTextWithCharacter | Given one character, replaces the current text with that character |
| ReplaceTextWithLiteral | Replaces the current text with the contents of the literal |
| CopyText | Creates a text object like the one you called it on but not necessarily identical |
| CopyTextNear | Copies the text into a new object in the same cluster as the old one |
| CopyTextTransient | Copies the text into a new object in transient cluster |
| EachTextRun | Iterates the specified function on each text run in a text object |
| EntireTextRange | Sets range parameter to point to entire text |
| Operating on a point | |
| AppendText | Appends a copy of all the given text to end of current text |
| AppendCharacters | Appends given characters to the end of the current text |
| AppendCharacter | Appends one character to end of current text |
| AppendLiteral | Appends the given literal to end of current text (where a literal is a c-style ascii character run) |
| AppendObjectName | Appends the name of the given object to the end of the current text |
| InsertText | Inserts the given text into the current text at the given insertion point |
| InsertCharacters | Inserts the given characters into the current text at the given insertion point |
| InsertCharacter | Inserts the given single character into the current text at the given insertion point |
| InsertLiteral | Inserts the given literal into the current text at the given insertion point |
| InsertObjectName | Inserts the name of the given object into the text |
| Operating on a sub-range | |
| DeleteTextRange | Deletes the given range of text |
| DeleteCharacterAt | Deletes the specified character |
| CopyTextRange | Returns a text object containing a copy of the given text |
| CopyTextRangeNear | Returns a text object containing a copy of the text range, in the same cluster as the original |
| CopyTextRangeTransient | Returns a text object containing a copy of the text range, in the transient cluster |
| CopyTextRangeToBuffer | Copies the specified text range into the given buffer |
| CharacterAt | Returns the specified character |
| ReplaceTextRange | Replaces the specified range of text with the given text |
| ReplaceCharacterAt | Replaces the character at beforecharacter |
| Comparing | |
| CompareTextRefs | Compares two hastext objects using comparetext |
| Managing lines | |
| Lines | Returns the number of lines of text the text object occupies |
| LineToTextRange | Given line number, returns the text in that line |
| FindMatchingLine | Given a text object in searchfor, looks for a line in self that matches |
| Finding | |
| FindCharacter | Searches for the given character in a text object |
| FindText | Searches for the given text |
| MatchText | Converts the text to a string, and searchs for a matching string |
| Implementing form data | |
| IsFormElement | Returns false |
| Drawing and measuring | |
| TextDraw | Draws the text |
| TextToOffsets | Returns a position table for drawing the text |
| TextToTotalWidth | Given a text range, returns the total width in microns |
| Manipulating strings | |
| TextToString | Converts the text range to a string |
| TextToInteger | Converts the text to a string, and then to an integer |
| StringAt | Copies the text starting at the given point into a string |
| ReplaceTextWithString | Replaces the text object in self with the string in newtext |
| AppendStringToText | Converts the string to text, then appends the resulting text to the end of the current text |
| InsertStringInText | Converts the string to text, then inserts the text into self |
| TextRangeToString | Given a text range, returns a string containing a copy |
| Line | Given a line number, copies that line into a string |
| SetLine | Given a line number and a new string, replaces the line with the new string |
| InsertLine | Inserts the given text into the specified line |
| FindString | Searches the current text for the given string |
| ICF methods | |
| ProduceCardFromContent | Produces a telecard from the text |
Class HasText has the following methods you should override whenever you create your own Subclass:
| Method | Description |
|---|---|
| Bottlenecks required by subclasses | |
| EachTextRunInRange | Similar to the "each" functions; calls the given function on each text run in the given range of text |
| ReplaceTextData | Replaces the specified text with the given new text |
| TextRangeMark | Reads the style marks from a text range |
| MarkTextRange | Adds a style mark to a text range |
| TextLength | Returns the length of the current text object |
| Searching and comparing text | |
| CompareText | Compare two text objects |
| SearchTextRangeForData | Defined to return false |
| Managing dynamic text | |
| Thaw | Does nothing by default; override to do any processing immediately before a text object is modified |
| Freeze | Returns nilobject if the text object is empty, and the object otherwise; override to do any other processing immediately after a text object is modified |
Class HasText defines no fields.
operation EachTextRunInRange(rangeToIterate: TextRange; defaultStyle: TextStyle; function: EachTextRunFunction; VAR parameters: Parameters), noFail, noMethod; call: rarely Override: always
This method is similar to the "Each" functions common to all classes inheriting from HasIterator. EachTextRunInRange calls the given function on each text run in the given range of text.
operation ReplaceTextData(rangeToReplace: TextRange; data: CharactersPointer; count: Unsigned; style: TextStyle), noMethod; call: rarely Override: always
This method replaces the range of text specified by rangeToReplace with the characters in data.
operation TextRangeMark(rangeToCheck: TextRange; VAR rangeMarkedHomogeneously: TextRange): TextStyle, noMethod call: rarely Override: always
This method returns the style mark associated with the specified text range. Marks could be anything you define them to be in your subclasses, but TextField expects them to be text styles.
operation MarkTextRange(rangeToMark: TextRange; style: TextStyle), noMethod call: rarely Override: always
Add a style mark to the specified range of text.
attribute TextLength: Unsigned, readOnly, safe, common, noGetter; // operation TextLength(): Text, safe call: rarely Override: always
If you create a new subclass using the HasText mixin, you should redefine the TextLength attribute, and write a getter for it. The TextLength method should return the length of the current text object.
operation CompareText(compareWith: HasText): SignedShort, noMethod call: sometimes Override: always
This method compares two text objects. The HasText mixin does not define this method, so you should override whenever you subclass. The TextContainer mixin, for example, overrides this method to call CompareTextRefs on the the objects containing the text. (No, there is no evil recursion here. The data store of the text container (that is, the text contained inside it) is what CompareTextRefs calls CompareText on. Confused? Just remember that both the text containers and the text objects they contain descend from HasText.)
intrinsic CompareTextRefs(a: HasText; b: HasText): SignedShort call: rarely Override: rarely
CompareTextRefs compares two HasText objects.
If a and b are identicalthat is, if their object IDs are the sameCompareTextRefs returns 0. If a is nilObject, CompareTextRefs returns -1. If b is nilObject, it returns 1. Otherwise, it returns the result of a CompareText call on the two, with a as self and b as the text to be compared with.
operation Thaw(), noFail call: rarely Override: often
The system calls this method just before a HasText object is modified. If your implementation of text requires any processing to be done on an object before modification (such as unpacking from a compact storage format), override Thaw. As defined by HasText, Thaw does nothing.
operation Freeze(): Object, noFail call: rarely Override: rarely
The system calls this method just after a HasText object has been modified. If your implementation of text requires any cleanup work after text modification (such as packing to a compact storage format), override Freeze.
If the text object has zero length, HasText_Freeze deletes it & returns nilObject. Otherwise Freeze returns the text object.
operation FindCharacter(searchChar: Character; searchRange: TextRange; VAR answerRange: TextRange): Boolean call: rarely Override: rarely
Call FindCharacter if you want to search the object's text for a specified character. FindCharacter looks for searchChar, searching the text specified by searchRange. If searchChar is found, FindCharacter returns true as the function result and answerRange is set to indicate where the character was found (FindCharacter stops after finding one occurrence of searchChar). If searchChar isn't found, FindCharacter returns false, and answerRange is undefined. FindCharacter calls EachTextRunInRange to look for searchChar.
operation FindText(searchText: Text; searchRange: TextRange; VAR answerRange: TextRange):Boolean call: rarely Override: rarely
Call FindText if you want to search the object's text for a specified run of text. FindText looks for the text in searchText, searching the characters specified by searchRange. If searchText is found, FindText returns true as the function result and answerRange is set to indicate where the text was found (FindText stops after finding one occurrence of searchText). If searchText isn't found, FindText returns false, and answerRange is undefined. To perform its action, FindText calls TextToString to copy the object's text to a string, then calls FindString.
operation MatchText(searchString: String):Boolean call: sometimes Override: sometimes
Call MatchText if you want to search for a string (C or Pascal type Str255) in the object's text. MatchText looks for searchString in the object and returns true if a match is found. MatchText calls StringMatch to perform its action.
You should override MatchText if objects of your class define text data that consists of something other than the object's contents. As a general rule, you should override MatchText if you also override GetTextData and SetTextData.
operation TextToString(VAR copy: String) call: sometimes Override: rarely
Call TextToString if you want to copy all the characters in the object to a string variable (C or Pascal type Str255). The characters are copied from the object to copyTo. TextToString ensures that no more than 255 characters are copied. TextToString calls CopyToBytes to perform the copying.
TextToString does its work by calling TextRangeToString.
operation GetLine(whichLine: Unsigned; VAR resultString: String) call: rarely Override: rarely
Call GetLine if you want to copy a line of characters from the object to a string variable (C or Pascal type Str255). The whichLine parameter indicates the line to get, and resultString is set to the characters in that line. The object isn't changed, but any previous value of resultString is lost. The first line in the Text object is number 1.
Line calls LineToTextRange and TextRangeToString to do its work.
operation SetLine(whichLine: Unsigned; newString: String) call: rarely Override: rarely
Call SetLine if you want to replace a line of characters in the object with characters from a string variable (C or Pascal type Str255). The whichLine parameter indicates which line of the object is to be replaced, and newString contains the characters to be copied in. The first line in the Text object is number 1.
SetLine calls LineToTextRange and ReplaceTextData to do its work.
operation FindString(searchString: String; searchRange: TextRange; VAR answerRange: TextRange):Boolean call: rarely Override: rarely
Call FindString if you want to search the object's text for a specified string (C or Pascal type Str255). FindString looks for searchString, searching the text specified by searchRange. If searchString is found, FindString returns true as the function result and answerRange is set to indicate where the string was found (FindString stops after finding one occurrence of searchString). If searchString isn't found, FindString returns false, and answerRange is undefined. FindString calls StringMatch to look for searchString.