HasText |
|
|
Content DisplayName Info Lines SearchName TextLength |
Define Class HasText;
mixes in with Object;
inherits interface from FormElement;
// bottlenecks (lowest-level text calls, new types of text must implement all of these)
attribute TextLength: Unsigned, readOnly, noGetter;
// call to get the number of characters in the text object
// must override when defining a new type of text
operation EachTextRunInRange(rangeToIterate: TextRange; defaultStyle: TextStyle; function: EachTextRunFunction; parameters: Pointer): Object, noFail, noMethod;
// call to iterate over all text within a range, calling an EachTextRunFunction for runs
// pass nil for rangeToIterate to iterate over the entire text object
// if range goes beyond
// defaultStyle is passed through for any ranges that do not have a style marked within the text
// must override when defining a new type of text
operation EachStyle(defaultStyle: TextStyle; function: EachStyleFunction; parameters: Pointer): Object, noFail, noMethod;
// call to iterate over all styles used in the text object, calling an EachStyleFunction for each style
// defaultStyle is passed through if any text in the text object is not marked with a style
// function is called only once per style, except that defaultStyle may be repeated one more time
// must override when defining a new type of text
operation ReplaceTextData(rangeToReplace: TextRange; data: ReadOnlyCharactersPointer; count: Unsigned; style: TextStyle), noMethod;
// call to change a text object; allows deleting, adding, replacing
// pass nil for rangeToReplace to replace the entire text
// data parameter points to count characters (2 bytes each)
// must override when defining a new type of text
operation TextRangeMark(rangeToCheck: TextRange; var rangeMarkedHomogeneously: TextRange): TextStyle, noMethod;
// call to find out the text style of a range of text
// returns the style of the first character as return value
// returns the largest range starting from the beginning of rangeToCheck that has the same style in rangeMarkedHomogeneously
// pass nil for rangeToCheck to check mark of the entire text
// pass nil for rangeMarkedHomogeneously if not interested in how much has the same style
// must override when defining a new type of text
operation MarkTextRange(rangeToMark: TextRange; style: TextStyle), noFail, noMethod;
// call to change the style of a range of text without changing the characters
// pass nil for rangeToMark to mark the entire text
// must override when defining a new type of text
// routines that operate on an entire text object
operation DeleteText(), noFail;
// call to delete all the text in the object, but does not destroy the object itself
// calls ReplaceTextData(nil, nil, 0, iMarkSameAsContextConstant)
// rarely override
operation ReplaceText(textToInsert: HasText), noFail;
// call to replace all the text in the object with a copy of the text in textToInsert
// textToInsert is not destroyed
// works by making multiple ReplaceTextData calls
// rarely override
operation ReplaceTextWithCharacters(characters: ReadOnlyCharactersPointer; count: Unsigned);
// call to replace all the text in the object with the specified characters
// calls ReplaceTextData(nil, characters, count, iMarkSameAsContextConstant)
// rarely override
operation ReplaceTextWithCharacter(character: Character);
// call to replace all the text in the object with a single character
// calls ReplaceTextData(nil, &character, 1, iMarkSameAsContextConstant)
// rarely override
operation ReplaceTextWithLiteral(literal: Literal);
// call to replace all the text in the object with a C-style null-terminated ASCII string
// all characters are mapped directly (no Magic 8-bit translation is done)
// calls ReplaceTextData
// rarely override
operation CopyTextNear(nearThis: Object): Text, noFail;
// creates a new object of class Text containing all the text from this object
// calls NewNear, then EachTextRunInRange and using ReplaceTextData to append to the new text object
// rarely override
// may return nilObject instead of an empty text object
operation CopyText(): Text, noFail;
// creates a new ephemeral object of class Text containing all the text from this object
// calls NewText, then EachTextRunInRange and using ReplaceTextData to append to the new text object
// rarely override
// may return nilObject instead of an empty text object
operation CopyPlainText(): Text, noFail;
// creates a new ephemeral object of class Text containing all the text from this object, but no style information
// rarely override
// may return nilObject instead of an empty text object
operation CopyPlainTextIfStyled(): Text, noFail;
// returns self if self has no styles, else returns CopyPlainText(self)
// rarely override
operation EachTextRun(function: EachTextRunFunction; parameters: Pointer): Object, noFail;
// call to iterate through on entire text object
// like EachTextRunInRange(nil, nilObject, function, parameters) except some subclasses supply an appropriate default style
// rarely override
operation EntireTextRange(var range: TextRange);
// call to compute a range that contains the entire text
// calls TextLength to figure out the size of the range
// rarely override
operation IsStyledText(): Boolean, noFail;
// returns true iff any run in the text has a non-nil style
// rarely override
operation HasCharacters(): Boolean, noFail;
// returns true iff the object contains at least one character
// equivalent to TextLength() != 0
// override to provide more efficient implementation
operation MarkAllUnmarkedText(style: TextStyle), noFail;
// call to change the style of all ranges of text that are not already marked;
// rarely override
// routines that operate on a point in a text object
operation AppendText(textToAppend: HasText);
// call to append a copy of all the text in textToAppend onto the end of the text object
// textToAppend is not destroyed
// works by making multiple ReplaceTextData calls
// rarely override
operation AppendTextRange(textToAppend: HasText; rangeToAppend: TextRange);
// call to append a copy of the text in <rangeToAppend> from <textToAppend> onto the end of self
// textToAppend is not destroyed
// works by making multiple ReplaceTextData calls
// faster than calling AppendText after calling CopyTextRange
// rarely override
operation AppendCharacters(characters: ReadOnlyCharactersPointer; count: Unsigned);
// call to append the specified characters to the end of the text
// calls ReplaceTextData
// rarely override
operation AppendCharacter(character: Character);
// call to append the specified character to the end of the text
// calls ReplaceTextData
// rarely override
operation AppendLiteral(literal: Literal);
// call to append a C-style null-terminated ASCII string to the end of the text
// all characters are mapped directly (no Magic 8-bit translation is done)
// calls ReplaceTextData
// rarely override
operation InsertText(insertPoint: Unsigned; textToInsert: HasText);
// call to insert textToInsert in the text
// insertPoint 0 means before first character, 1 means after first character, etc.
// works by making multiple ReplaceTextData calls
// rarely override
operation InsertCharacters(insertPoint: Unsigned; characters: ReadOnlyCharactersPointer; count: Unsigned);
// call to insert the specified characters in the text
// insertPoint 0 means before first character, 1 means after first character, etc.
// calls ReplaceTextData
// rarely override
operation InsertCharacter(insertPoint: Unsigned; character: Character);
// call to insert the specified character in the text
// insertPoint 0 means before first character, 1 means after first character, etc.
// calls ReplaceTextData
// rarely override
operation InsertLiteral(insertPoint: Unsigned; literal: Literal);
// call to insert a C-style null-terminated ASCII string in the text
// insertPoint 0 means before first character, 1 means after first character, etc.
// all characters are mapped directly (no Magic 8-bit translation is done)
// calls ReplaceTextData
// rarely override
// routines that operate on a sub-range of a text object
operation DeleteTextRange(rangeToDelete: TextRange), noFail;
// call to delete a range of text
// calls ReplaceTextData(rangeToDelete, nil, 0, iMarkSameAsContextConstant)
// rarely override
operation DeleteCharacterAfter(beforeCharacter: Unsigned), noFail;
// call to delete a single character
// offset is 0-based
// calls ReplaceTextData
// rarely override
operation CopyTextRangeNear(rangeToCopy: TextRange; nearThis: Object): Text, noFail;
// call to create a new text object containing a copy of part of this text object
// calls NewNear, then EachTextRunInRange and using ReplaceTextData to append to the new text object
// rarely override
// may return nilObject instead of an empty text object
operation CopyTextRange(rangeToCopy: TextRange): Text, noFail;
// call to create a new ephemeral text object containing a copy of part of this text object
// calls NewText, then EachTextRunInRange and using ReplaceTextData to append to the new text object
// rarely override
// may return nilObject instead of an empty text object
operation CopyTextRangeToBuffer(var rangeToCopy: TextRange; characters: CharactersPointer), intrinsic;
// call to copy the characters from part of a text range into a character buffer
// the buffer needs to have 2 bytes for each character in the range to be copied
// nil is not allowed for the rangeToCopy parameter, because the range is required to specify the buffer size
// returns actual number of characters copied in rangeToCopy.length
operation CopyTextToLiteral(buffer: LiteralBufferPointer; bufferSize: Unsigned): Boolean, intrinsic;
// call to copy ASCII characters from the text into a literal buffer
// returns true if the buffer is big enough and all the characters are ASCII
// non-ASCII charactere are replaced with ?
// the buffer always gets a null-terminated literal
operation CharacterAfter(beforeCharacter: Unsigned): Character, noFail;
// call to get the character at a particular offset within the text
// offset is 0-based
// 0 is returned if position passed is at or beyond the end of the text
// rarely override
operation ReplaceTextRange(rangeToReplace: TextRange; textToInsert: HasText);
// call to replace a range of text with text from another object
// calls EachTextRun and using ReplaceTextData to replace the text object
// rarely override
operation ReplaceCharacterAfter(beforeCharacter: Unsigned; character: Character);
// call to replace a single character within a text object
// offset is 0-based
// rarely override
operation TruncateText(maximumCharacters: Unsigned), noFail;
// truncate to at most maximumCharacters characters.
// may truncate to something shorter if it would otherwise have to separate a combining mark from its base character
// names
operation AppendObjectName(namedObject: Object);
// call to append the name of an object to the end of the text
// rarely override
operation InsertObjectName(insertPoint: Unsigned; namedObject: Object);
// call to insert the name of an object in the text
// rarely override
// support for dynamic text (for example, AttributeText)
operation Thaw(), noFail;
// useful hook for sub-classes that implement dynamic text
// called before making changes
// present here in HasText to standardize all types of dynamic text
// rarely call
// sometimes override when defining a new class of dynamic text
operation Freeze(): Object, noFail;
// useful hook for sub-classes that implement dynamic text
// called when done making changes
// present here in HasText to standardize all types of dynamic text
// rarely call
// sometimes override when defining a new class of dynamic text
// comparison
intrinsic CompareTextCharacters(a: HasText; b: HasText): SignedShort;
// call to compare the characters in two text objects, ignoring the style of the text
// returns -1 if self < compareWith, 0 if self = compareWith, 1 if self > compareWith
// uses default sort order and is sensitive to case, diacritics and everything else
intrinsic IsTextIdentical(a: HasText; b: HasText): Boolean;
// call to find out if two objects have the same text, ignoring the style of the text
intrinsic IsTextSimilar(a: HasText; b: HasText): Boolean;
// call to find out if two objects have similar text, ignoring the style of the text.
// Similar means: no primary differences (text length, 'A' vs. 'B'), but possibly
// less relevant differences such as differences in case.
// Uses default sort order.
operation MakeComparable(): Text, intrinsic;
// call to convert text to a comparable form suitable for comparison, eliminating
// secondary features such as case, diacritics, or ignorable characters
// strips style information and both leading and trailing white space
// result is identical for the following two blocks:
// { StripLeadingWhitespace(a); StripTrailingWhitespace(a); StripLeadingWhitespace(b); StripTrailingWhitespace(b); result = IsTextSimilar(a, b); }
// { result = IsTextIdentical(MakeComparable(a), MakeComparable(b)); }
operation TextMatchesLiteral(literal: Literal; identical: Boolean): Boolean, intrinsic;
// compares a text object to a C literal, ignoring case if "identical" is false
intrinsic FindIdenticalText(listToSearch: HasIndexing; textToMatch: HasText): Unsigned;
// call to search a list of text objects, returning the index of the first
// object whose text is identical to that in textToMatch.Returns 0 if there
// is no match.Uses IsTextIdentical to perform the comparison.
intrinsic FindSimilarText(listToSearch: HasIndexing; textToMatch: HasText): Unsigned;
// call to search a list of text objects, returning the index of the first
// object whose text is similar to that in textToMatch.Returns 0 if there
// is no match.Uses IsTextSimilar to perform the comparison.
operation TextCore(): HasText, noFail;
// call to return the core of the text, used for comparison
// sometimes override to return the object that actually holds the text
// lines
attribute Lines: Unsigned, readOnly;
// call to compute how many lines are in the text
// a line is any sequence of characters, ending in a new-line character
// if there are any characters after the last new-line, these characters count as an additional line
// rarely override
operation LineToTextRange(whichLine: Unsigned; appendNewLinesIfNeeded: Boolean; var result: TextRange);
// given a line number, compute the text range which includes all characters from that line, not including the new-line
// a line number of 0 is illegal
// if the line number is greater than the number of lines in the text, an empty range at the end of the text will be returned
// in this case, if appendNewLinesIfNeeded is true, new-line characters will be appended to make sure the line specified exists
// rarely override
operation CopyLine(whichLine: Unsigned): Text, noFail;
// call to extract a line of text as a new ephemeral text object
// calls LineToTextRange and CopyText
// rarely override
// may return nilObject instead of an empty text object
operation ReplaceLine(whichLine: Unsigned; lineText: HasText);
// call to replace a line of text with some text
// will add new-line characters if necessary
// calls LineToTextRange and ReplaceTextRange
// rarely override
operation AppendLine(lineText: HasText);
// call to add a new line of text to a text object with multiple lines
// will add new-line characters if necessary
// calls TextLength, CharacterAfter, AppendCharacter, and AppendText
// rarely override
operation InsertLine(beforeLine: Unsigned; lineText: HasText);
// call to add a new line of text to a text object with multiple lines
// will add new-line characters if necessary
// calls LineToTextRange, InsertCharacter, and InsertText
// rarely override
operation DeleteLine(whichLine: Unsigned);
// call to delete a line from a text object
// will delete a new-line character if successful
// calls LineToTextRange, CharacterAfter, and DeleteTextRange
// rarely override
operation FindIdenticalLine(searchFor: HasText): Unsigned, noFail;
// call to find a line that matches the characters in searchFor
// returns 0 if no matching line is found
// a matching line matches searchFor (not including the new-line if any) as defined by IsTextIdentical
// uses LineToTextRange to define where lines begin/end
// this routine is case sensitive
// rarely override
operation FindSimilarLine(searchFor: HasText): Unsigned, noFail;
// same as FindIdenticalLine, but case insensitive
// text sections
// text sections are runs of characters divided by separators
// (lines are sections divided by newLine characters)
// the operations below are just like their "Line" counterparts, but with an
// additional parameter to indicate a separator character to use
operation TextSections(separator: Character): Unsigned;
operation TextSectionToTextRange(whichSection: Unsigned; appendSeparatorsIfNeeded: Boolean; separator: Character; var result: TextRange);
operation CopyTextSection(whichSection: Unsigned; separator: Character): Text, noFail;
operation ReplaceTextSection(whichSection: Unsigned; separator: Character; sectionText: HasText);
operation AppendTextSection(separator: Character; sectionText: HasText);
operation InsertTextSection(beforeSection: Unsigned; separator: Character; sectionText: HasText);
operation DeleteTextSection(whichSection: Unsigned; separator: Character);
operation FindIdenticalTextSection(searchFor: HasText; separator: Character): Unsigned, noFail;
operation FindSimilarTextSection(searchFor: HasText; separator: Character): Unsigned, noFail;
// finding
operation FindText(searchText: HasText; searchRange: TextRange; flags: Unsigned; var answerRange: TextRange): Boolean, intrinsic;
// call to find the characters from searchText within searchRange
// use flags defined in Utilities.h
// returns true if characters are found
// returns range of found characters in answerRange
// pass nil for searchRange to search entire text
// pass nil for answerRange if not interested in where the text was found
operation ContainsText(searchText: HasText): Boolean, intrinsic;
// call to find out whether searchIn contains text similar to searchText
// based on FindText using kFindSimilarText flag
// returns true if characters are found
operation FindCharacter(searchCharacter: Character; searchRange: TextRange; var answerRange: TextRange): Boolean, noFail;
// call to find a character within searchRange
// definition of a match is the exact character code matching
// returns true if character is found
// returns range of found character in answerRange
// pass nil for searchRange to search entire text
// pass nil for answerRange if not interested in where the character was found
// rarely override
// drawing and measuring
operation TextDraw(rangeToDraw: TextRange; defaultStyle: TextStyle; location: Dot), noFail;
// call to draw a range of text
// pass nil for rangeToDraw to draw entire text
// calls EachTextRunInRange(rangeToDraw, defaultStyle, ...) and FillText() and FontTotalWidth(ActualFont())
// rarely override
operation TextToOffsets(measureRange: TextRange; defaultStyle: TextStyle; firstPosition: Micron; positionTable: MicronPointer), noFail;
// call to compute the offset for each character for a range of text
// pass nil for measureRange to measure entire text
// calls EachTextRunInRange(measureRange, defaultStyle, ...) and FontOffsets(ActualFont())
// rarely override
operation TextToTotalWidth(rangeToMeasure: TextRange; defaultStyle: TextStyle): Micron, noFail;
// call to get the total width of a range of text
// pass nil for measureRange to measure entire text
// calls EachTextRunInRange(measureRange, defaultStyle, ...) and FontTotalWidth(ActualFont())
// rarely override
operation TextToWidths(measureRange: TextRange; defaultStyle: TextStyle; widthTable: MicronPointer; hintTable: UnsignedBytePointer), noFail;
// call to compute widths and hints for each character in a range of text
// pass nil for measureRange to measure entire text
// calls EachTextRunInRange(measureRange, defaultStyle, ...) and FontWidths(ActualFont())
// rarely override
// high-level text operations
operation StripLeadingWhitespace(), noFail;
// call to remove any white-space characters at the start of the text
// calls CharacterIsWhitespace for definition of white space
// rarely override
operation StripTrailingWhitespace(), noFail;
// call to remove any white-space characters at the end of the text
// calls CharacterIsWhitespace for definition of white space
// rarely override
operation MakeUppercase(initialOnly: Boolean): Text, intrinsic;
// call to convert text to uppercase form
// if initialOnly, converts only the initial character(s)
// don't use to make comparisons case-insensitive; use MakeComparable for that
operation DigitsOnly(): HasText, noFail;
// returns an ephemeral text object that contains only the digit characters from self
operation RemoveTextUpToCharacter(character: Character), noFail;
// removes the text before character (if there is any)
operation RemoveTextUpToAndIncludingCharacter(character: Character), noFail;
// removes the text (if there is any) before character and the character
operation HasNonRomanCharacters(): Boolean, intrinsic;
// whether the text object has characters outside the range of Roman characters that are supported on any Magic Cap system
operation AccumulateTextCRC(var crc: Unsigned), noFail;
// add this text to a CRC -- does not include the styles
operation ComputeTextCRC(): Unsigned, intrinsic;
// compute a CRC of the text -- does not include the styles
// a whiff of a higher-level text editing concept
operation CorrectText(newText: HasText);
// Same as ReplaceText, with the implicit concept that the old text was
// wrong and the new text is a logical replacement.
// overrides
overrides Info;
overrides SearchName;
overrides IsFormElement;
overrides DisplayName;
// hooks for dynamic text
operation Opening(whatIsOpening: Object), noFail;
operation Closing(whatIsClosing: Object), noFail;
attribute Content: Object;
end class;