Defined in Text.Def Mixes in with Object Inherits from HasText Inherits interface from EditsTarget
The TextContainer mixin class provides the basic capabilities for objects that are designed to hold text, such as text field objects. You'll probably never use any objects of class TextContainer, instead using objects that are instances of its subclasses. Class TextContainer is the second major implementation of the methods in HasText (the first being class Text).
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Class TextContainer descends from class HasText, which supplies many text-handling features to text containers.
Instantiate: rarely Subclass: rarely Call its methods: sometimes
You'll probably never create any objects of class TextContainer in your software. Instead, you'll probably use objects of TextContainer subclasses, such as class TextField.
If you create a subclass of TextContainer, you'll need to define how objects of your class store and access their text by overriding the methods that get and set the text: DataStore and SetDataStore. See the description of class TextField for an example of one way to implement the data store.
When you use a TextContainer object in your software, you can call methods to change its text in many ways, including inserting, deleting or replacing characters in the text.
The TextContainer class doesn't add any additional fields beyond those provided by its superclasses. It does add two attributes, though: DataStore and Target.
The TextContainer class has the following method that you might call:
| Method | Description |
|---|---|
| EachTextRunInRange | Performs some action for a range of text |
| SetTarget | Set the data store (the contained text) to be the object in newtarget |
| MapTextRange | |
| AboutToHide | Called before the text container goes off screen |
| AboutToShow | Called before the text container goes on screen |
The TextContainer class has the following method that you might Override:
| Method | Description |
|---|---|
| DataStore | Override to return the text contained by the text container |
| SetDataStore | Override to set the text contained to new text |
The TextContainer class doesn't define any fields.
The HasText mixin provides TextContainer with many methods for manipulating texts. Class TextField is TextContainer's most common implementation.
When you want to operate on the text in a TextContainer object, you'll find that many routines use the concept of a text point, which is a position between two characters. The text point before the first character is numbered 0, the position between the first and second characters is numbered 1, and so on.
The text classes defines several methods that require you to specify a range of characters in the object. There's a data type for a range of characters, defined as follows:
typedef struct
{ TextPoint start; /* starting point for range */
ulong length; /* number of characters in range */
} TextRange;
overrides EachTextRunInRange call: sometimes Override: sometimes
Call EachTextRunInRange when you want to perform some function on some of the text in the container, such as searching for a particular character. If you call EachTextRunInRange, you must also define the function that is to be called to process the text, then pass a pointer to this routine in the EachTextRunProcPtr parameter. If you want to send any parameters to this routine, pass a pointer to the parameters in params when you call EachTextRunInRange.
When you call EachTextRunInRange, the system divides the specified text range into text runs. Each text run is an adjacent collection of text that has the same style, species, and storage characteristics, as defined by the class that the text belongs to.
EachTextRunInRange keeps calling the iterative function as long as it returns true and there are still text runs in the range that haven't been processed. When the iterative function returns false, EachTextRunInRange stops calling the iterative function and exits. This is useful if you want to stop iterating when your iterative function fulfills some condition, such as successfully completing a search.
The searchRange parameter indicates which range of text to process with this call. The info parameter can contain any object that provides additional information that describes the text in the search range. Typically, this parameter is used to describe the base style information for the text. See MultiText_EachTextRunInRange for more information. The params parameter contains any additional parameters that you want to pass to your iterative routine.
The routine that's called for each text run should be declared like this:
PrivateProc Boolean TheProc (void *data, ulong count, ulong dataClass, ObjectID info, void *params)
Warning! You must use the PrivateProc specifier when you declare your iterative function. If you fail to do so, you'll get no warning from any tools during the build process, but your software will fail in an unpredictable way and you'll feel bad, and you might even have to bother Jim Friedlander.
When the iterative function is called, the data parameter points to the start of the text run, and count tells how many characters are in the text run. The dataClass parameter gives the kind of text (Unicode, ASCII, etc.) that's being processed. The info and params parameters are passed through directly from the EachTextRunInRange call.
attribute DataStore: HasText, noGetter, noSetter; // operation DataStore(): HasText // operation SetDataStore(newText: HasText) call: never Override: always
To be written.