Book Contents Previous Chapter Next Chapter
This chapter describes how you can use Magic Cap to handle text in your packages. Before reading this chapter, you should be familiar with viewables and scenes.
This section describes the various ways that Magic Cap packages work with text, especially representing text as objects. This section also discusses different uses for text in your packages.
Magic Cap packages use text to represent messages on the screen for users, input typed or otherwise entered by users, information received from remote services, and many other purposes. Magic Cap provides various ways to represent text in packages. In general, you should use text objects to represent text in your packages. These are objects of classes that inherit from mixin class HasText. Magic Cap uses Unicode to encode characters represented by text objects.
Class HasText includes features for text storage and access, such as creating text objects, manipulating the text, and replacing and appending the text. Most packages that operate on text objects use some of these features. Magic Cap defines many text-handling operations in class HasText. You can create your own text-containing objects by inheriting from class HasText, and you can work with existing text objects by calling operations of this class.
Magic Cap defines a text range as a subset of the text in a text object. A text range is defined by a typing point, which is the empty space between two characters, and a count indicating the number of characters in the range. Many text operations take a text range as a parameter.
In addition to keeping text in text objects, you can also use other data structures to represent text, such as strings or literals. There are several reasons why text objects are generally the best way to represent text in your packages. Text objects provide the following advantages:
Some Magic Cap operations require parameters that represent text as values of type Str255, Pascal-style strings that are data structures consisting of a length byte followed by 8-bit values representing characters. You should only use Str255 values when they are required by Magic Cap operations. If you use Str255 values, they can't contain Unicode characters, will be incompatible with future versions of Magic Cap, and can't take advantage of the text-manipulating features of strings. In future versions of Magic Cap, these parameters will be changed from Str255 data structures to text objects.
In addition to the basic storage and access operations, class HasText also provides operations for drawing the text of text objects on the screen, and for measuring the width in microns of text drawn on the screen. For more information about text objects, see the section Features of Text Objects below.
Most text in Magic Cap packages is represented by text objects or by data structures of type Str255, as discussed in the previous section. In addition to these representations, Magic Cap occasionally uses other data structures to represent text.
Magic Cap defines type Character as a 16-bit data structure designed to hold one Unicode character, and type CharactersPointer as a pointer to this structure, as follows:
typedef ushort Character; typedef Character *CharactersPointer;
You can use type Character to represent a single Unicode character, or create an array of Character to store multiple Unicode characters. If you use this technique for representing text, your text will be able to include international characters, but will not be able to contain other features of text objects, such as font or style information. You should use a text object to represent text that is entered and edited by the user. If the text will not require font or style information or other advanced features of text objects, you can use an array of Character to represent text that is entered and edited by the user.
You can use a standard C null-terminated literal to represent text. You can use this representation for text that is specified and hard-coded by your package and isn't subject to modification by the user. In general, you should avoid C literals for other uses because of their limitations, such as the fact that they are composed of 8-bit characters. Also, in all cases, C literals must be translated when your package is localized, which requires a change to your C source, not just your instance definition file.
Magic Cap provides support for an expanded encoding of 8-bit characters called Magic 8-bit characters. This encoding defines eight non-ASCII characters by assigning values in the unused range from 0x80 through 0x87, as follows:
character Magic 8-bit value Unicode value
- em dash 0x80 0x2014
` opening curly single quote 0x81 0x2018
' closing curly single quote 0x82 0x2019
" opening curly double quote 0x83 0x201C
" closing curly double quote 0x84 0x201D
+ dagger 0x85 0x2020
* bullet 0x86 0x2022
(TM) trademark symbol 0x87 0x2122
Magic Cap supports Magic 8-bit characters by automatically converting them to and from Unicode representations when appropriate. In general, you can use Magic 8-bit characters in any 8-bit text representation, such as a Str255 character. Any Magic Cap operation that takes a parameter of type Str255 will accept Magic 8-bit characters in the string.
When Magic Cap converts 8-bit characters to Unicode, characters in the range 0x00 to 0x7F are converted to their standard Unicode values, characters from 0x80 to 0x87 are converted to Magic 8-bit values, and all other characters are converted to the question mark character. Magic Cap converts characters when necessary. For example, if you paste text from the Macintosh clipboard into the Magic Cap Simulator, the text is converted from Magic 8-bit to Unicode for use inside Magic Cap.
VERSION NOTE: The Magic 8-bit characters listed in the table above are defined for Magic Cap 1.0. Future versions of Magic Cap may define additional characters in the unused range 0x88 to 0xFF.
Magic Cap converts Unicode characters to 8-bit characters by calling the intrinsic Text_ConvertToMagic8Bit, and 8-bit characters are converted to Unicode characters by calling the intrinsic Text_ConvertFromMagic8Bit. Although these intrinsics are usually called automatically by Magic Cap when necessary, you can call them if you want to convert characters between the two representations.
This section describes the features of text objects that you can use when you create your own text or when you operate on system text objects. Unless otherwise noted, all the operations and attributes described in this section are defined by class HasText.
Magic Cap defines a set of fundamental operations for text objects. These operations provide low-level support for performing various text functions.
Several operations allow you to manage the style of a text object. You can call MarkTextRange to set the style to be used for a range of text or for the entire object. When you call MarkTextRange, you pass a text style object to use for the text. Call TextRangeMark to get a text style object that contains the style used by the first character in a desired range of text. TextRangeMark also reports whether the entire range has the same style.
Call ReplaceTextData to modify the text in a text object. When you call ReplaceTextData, you indicate the range of text to modify, the new characters to add, the number of characters, and their style.
You can use ReplaceTextData to insert, delete, or replace text. To insert text, pass a typing point, which is an empty space between two existing characters, as the range to modify when you call ReplaceTextData. To delete text, pass the range to be deleted and pass zero as the number or characters to be inserted. To replace text, pass the range to be replaced and the new characters, their count, and text style.
You can call CompareText to compare the text of two text objects. CompareText returns a value that indicates whether the text is the same, or if not, which one should be ordered first. CompareText ignores any text styles associated with the text objects.
Call TextLength to determine how many characters are in the object's text.
This section describes operations that perform some action on the entire text object, not just a range of text within the whole object.
You can call ReplaceText to replace all the text in a text object with text from another object that inherits from HasText. Call ReplaceTextWithCharacters to replace all the text in the object with characters you provide, or you can call ReplaceTextWithCharacter to set the object's text to a single character that you pass as a parameter. Call ReplaceTextWithLiteral to set the object's text to a C literal that you pass as a parameter.
NOTE: When you call ReplaceTextWithLiteral, Magic Cap does not translate any Magic 8-bit characters in the literal.
Call DeleteText to delete all the text in the object without destroying the object.
You can call CopyTextNear if you want to create a new text object containing the same text as the given object. CopyTextNear creates the new object by calling NewNear. Call CopyTextTransient to create a transient text object containing the same text as the given object. CopyTextTransient creates the new object by calling NewTransient. See the section Creating Objects at Runtime in this book's Object Runtime chapter for more information about NewNear and NewTransient.
Magic Cap uses text ranges to represent subsets of the text in a text object. You can get a text range that includes all the text in an object by calling EntireTextRange. If you want to perform some action on the whole text object, you can then pass the resulting text range as a parameter to other operations that require a text range.
You can determine if any text in the object has a text style by calling IsStyledText.
This section describes operations that perform actions on a text range within the given text object.
You can call CopyTextRangeNear if you want to create a new text object containing the same text as the given text range in the object. CopyTextRangeNear creates the new object by calling NewNear. Call CopyTextRangeTransient to create a transient text object containing the same text as the given text range in the object. CopyTextRangeTransient creates the new object by calling NewTransient.
Call CopyTextRangeToBuffer to copy text from the given text range of the object to a buffer of characters. You must ensure that the buffer contains two bytes for every character to be copied from the text range.
If you want to change the text in a text range, you can call ReplaceTextRange to replace the text in the given range with all the text of another text object, which you also pass as a parameter. You can call ReplaceCharacterAt if you want to replace a single character in a text object with another character you specify as a parameter.
You can call DeleteTextRange to delete the given text range from the object's text. Call DeleteCharacterAt to delete a single character you specify from the object.
You can call CharacterAt to get the character at a given position in the object's text.
This section describes operations you can call to perform actions on a typing point within the text object. A typing point is represented by the empty space between two characters. Some of the operations in this section take an explicit typing point as a parameter, while others assume the end of the text as the typing point.
You can call InsertText to insert text into the object from another text object. Call InsertCharacters to insert characters you provide into the object at any point, or call InsertCharacter to insert a single character into the object. Call InsertLiteral to insert a C literal that you pass as a parameter into the object's text.
Magic Cap provides a set of operations that add characters to the end of an object's text. You can call AppendText to add the contents of another text object onto the end of the object's text. Call AppendCharacters to add characters you provide onto the end of the text, or call AppendCharacter to add a single character to the end of the text. Call AppendLiteral to add a C literal that you pass as a parameter onto the object's text.
This section describes operations that perform actions on lines of text produced on the screen by text objects. These operations define a line as a sequence of characters ending in a newline character, which does not take into account any text that is wrapped for formatting reasons.
You can call Lines to determine how many lines are in the text. Given the number of any line in text, you can call LineToTextRange to return the text range that includes the characters in the given line. The numbering is one-based. That is, the first line is numbered 1, not 0.
You can call CopyLine to create a new text object with text that consists of the given line from the current text object. Call ReplaceLine to replace a specified line of text in the object with other text.
Call FindMatchingLine to search the object for the given text. If the given text matches a line in the object, FindMatchingLine returns the number of the line that matched. For more information about searching for text, see this chapter's Searching for Text section.
This section describes operations that allow you to search text objects for particular contents.
You can call FindText to search a range in the text object for characters you specify. If the characters are found, FindText returns true and passes back a range that specifies their location. You can search the entire object by passing nil for the range to be searched.
You can call FindCharacter to search a range in the text object for a single character you specify. If the character is found, FindCharacter returns true and passes a range that specifies its location. You can search the entire object by passing nil for the range to be searched.
You can call FindMatchingLine to search the object for a line that matches the given text. For more information about FindMatchingLine, see this chapter's Text Lines section.
VERSION NOTE: Magic Cap defines the SearchTextRangeForData operation for future expansion of text searching features. SearchTextRangeForData always returns false in Magic Cap 1.0.
This section describes operations provided by Magic Cap for drawing text on the screen and for measuring the size of the text.
You can call TextToTotalWidth to calculate the width in microns of a given range of text. You can measure the entire text by passing nil for the range to be measured.
Call TextToWidths to measure the width of every character of a given range of text. You can measure all the characters in the text by passing nil for the range to be measured.
Magic Cap calls TextDraw to draw a range of text using the given canvas, clipping path, and location. You will rarely call TextDraw from your packages, as Magic Cap generally calls it when necessary. Call TextToOffsets to compute the offset position in microns for the text.
Every object can have a text value called its object name. Every class specifies how its objects handle their names. Some viewable classes display their objects' names to users. For example, the text on a button is the button's object name. Magic Cap provides a pair of operations that allow you to use the object's name as text.
You can call AppendObjectName to add an object's name to the end of another text object. Call InsertObjectName to insert an object's name at a specified location in the text of a text object.
For more information about object names, see this book's Object Runtime chapter.
Although most of the features of class HasText operate at a fairly low level, Magic Cap also defines a few high-level operations you can use to process text objects, as described in this section.
You can call StripLeadingWhiteSpace to automatically delete any white-space characters from the start of the text. Call StripTrailingWhiteSpace to automatically remove any white-space characters at the end of the text. Magic Cap defines white-space characters as those with Unicode values of 0x0020 or less (these are control characters) as well as the space character itself.
If you have a number represented as a text object, you can call TextToInteger to convert the text to its integer value. The text must represent a value in the range of a signed integer. TextToInteger interprets numeric characters and an optional leading plus or minus. TextToInteger returns a boolean value indicating whether the conversion was performed successfully.
You can call BreakAtCapitals if you want to convert from C-style operation names to conventional English phrases. BreakAtCapitals takes text that includes multiple words joined together with no spaces and with upper-case characters at the start of each word. BreakAtCapitals converts the upper-cause characters to lower case and adds a space to denote the start of each word. For example, the text "ReplaceTextWithCharacter" would be converted to "replace text with character". Magic Cap uses this operation when displaying operation names in the Magic Script editor.
You can call EnglishPluralNounHack to make any noun plural. EnglishPluralNounHack checks the ending of the given text. If the text ends with an s or x, it adds es to the end of the word. If the text ends with a consonant followed by y, it replaces the y with ies. Otherwise, it simply adds an s to the end.
Note that EnglishPluralNounHack produces incorrect results in many cases, including all non-standard plurals. For example, man becomes mans. If you use EnglishPluralNounHack, you should be sure it works correctly for all input possibilities in your package.
As described in the section Text Objects in this chapter, you should use text objects wherever possible and avoid strings except where their limitations are acceptable. For those cases in which you must use strings, Magic Cap defines a set of operations for working with strings, including converting them to and from text, manipulating strings, and other utilities. This section describes those string utilities.
You can call TextRangeToString to copy a range in a text object to a string. You can pass nil for the range if you want to copy the entire text, or you can simply call TextToString. The string created by TextRangeToString or TextToString can contain Magic 8-bit characters.
Call ReplaceTextWithString if you want to replace the object's text with the contents of a string. The string you pass to ReplaceTextWithString can contain Magic 8-bit characters.
You can call AppendStringToText if you want to add the contents of a string to the end of the object's text. The string you pass to AppendStringToText can contain Magic 8-bit characters.
Call InsertStringInText if you want to insert the contents of a string in the object's text. Pass the string you want to insert and the typing point where the string should be inserted. The string you pass to InsertStringInText can contain Magic 8-bit characters.
Magic Cap provides the Line and StringAt operations to copy a line of text into a string. Line copies a line given its number, while StringAt copies from a specified position to the end of the line.
Call Line to copy a specified line of text to a string. Pass the number of the desired line when you call this operation. The string created by Line can contain Magic 8-bit characters.
Call StringAt to copy a line of text to a string. Specify the starting position of the text to copy. StringAt will copy from that position to the next new-line character or the end of the text. The string created by StringAt can contain Magic 8-bit characters.
You can call SetLine to replace a line of text with characters from a string. Pass the number of the line along with the string when you call SetLine. The string you pass can contain Magic 8-bit characters. Call InsertLine to insert a new line in the text using the characters in the string. Pass the line which should follow the newly inserted line, along with the string to be inserted, when you call InsertLine. The string you pass can contain Magic 8-bit characters.
Magic Cap provides FindString as a utility you can use to search text for a given string. If the string is found in the text, FindString returns true and passes back a range that specifies its location. You can search the entire object by passing nil for the range to be searched.
You can call MatchText to compare a string to the object's text. If the string and the text match, MatchText returns true. MatchText only compares the first 255 characters of the text.
For more information, see the following topics in Magic Cap Class and Method Reference:
class HasText
operations and attributes:
AppendCharacter AppendCharacters AppendLiteral AppendObjectName AppendStringToText AppendText BreakAtCapitals CharacterAt CompareText CopyLine CopyTextNear CopyTextRangeNear CopyTextRangeToBuffer CopyTextRangeTransient CopyTextTransient DeleteCharacterAt DeleteText DeleteTextRange EnglishPluralNounHack EntireTextRange FindCharacter FindMatchingLine FindMatchingLine FindString FindText InsertCharacter InsertCharacters InsertLine InsertLiteral InsertObjectName InsertStringInText InsertText Line Lines LineToTextRange MarkTextRange MatchText ReplaceCharacterAt ReplaceLine ReplaceText ReplaceTextData ReplaceTextRange ReplaceTextWithCharacter ReplaceTextWithCharacters ReplaceTextWithLiteral ReplaceTextWithString SetLine StringAt StripLeadingWhiteSpace StripTrailingWhiteSpace TextDraw TextLength TextRangeMark TextRangeToString TextToInteger TextToOffsets TextToString TextToTotalWidth
TextToWidths
Book Contents Previous Chapter Next Chapter