Defined in Text.Def Inherits from Object, TextContainer Inherits interface from EditsTarget
An attribute text object is a dynamic text object that has a lot in common with a control: the text contained by the AttributeText object changes as the attribute text monitors a target object. Attribute text objects aren't limited to monitoring. Like controls, they can set the attributes of their targets, too.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
You can use an attribute text object anywhere you would use a text object, but most commonly you'll use it in conjunction with text fields. With text fields, simply point the dataStore field to an attribute text object instead of a text object. You'll do this by editing an object definition file.
Here's an example of a text field that uses an attribute text object for text data, instead of a plain text object:
Instance TextField 3214;
next: (ScrollArrow 8504);
previous: (ContentListView 3365);
superview: (FolderForm 'folder' 3212);
subview: nilObject;
relativeOrigin: <-122.0,-112.0>;
contentSize: <79.0,24.0>;
viewFlags: 0x10019000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: -1;
shadow: nilObject;
sound: nilObject;
border: nilObject;
fieldFlags: 0x03141401;
dataStore: (AttributeText 4505);
baseStyle: iBook12BoldCenter;
End Instance;
Instance AttributeText 4505;
textOwner: nilObject;
text: nilObject;
flags: 32768.w; // Observe using GetTextData
refCount: 0.w;
target: iCurrentCard;
targetAttribute: 1; // get card name
End Instance;
This particular text field is part of the "personal" folder in the file cabinet. It displays the name of the folder, which is the name of the card. When the user types in the field, the name of the card changes appropriately.
Instantiate: often Subclass: rarely Call its methods: rarely
You'll rarely call any methods of class AttributeText. You might use the provided subclass, class AttributeTextPlus, but you probably won't write your own subclasses.
Class AttributeText defines the following methods:
| Method | Description |
|---|---|
| Target | Return the target watched |
| SetTarget | Set the target watched |
| TargetAttribute | Return number of the attribute watched |
| SetTargetAttribute | Set the attribute watched |
| Template | Do nothing; defined by AttributeTextPlus subclass |
| CopyTextFromTarget | Construct a text object from the target and the attribute watched |
| CopyTextIntoTarget | Set the target attribute using the text contained by the attribute text object |
| TextOwner | Return the object that is interested (oh so anthropomorphically) in the target attribute |
| DataStore | Return the text object in the text field |
| SetDataStore | Store new attribute text in the text field |
| Notice | Framework routine that checks the target attribute for changes, also handles a deleted target |
| Opening | Framework routine that does prep work when the attribute text object's text owner is about to go on screen |
| Closing | Framework routine that does clean up work when the attribute text object's text owner goes off screen |
| Freeze | Framework routine that cleans up the text object before tidying it away; called by Closing |
| Thaw | Framework routine that prepares the text object for modification; called by Opening |
Class AttributeText defines the following fields:
| Field | Type | Description |
|---|---|---|
| textOwner | Object | The object interested in the contents of the attribute text object (almost always a textfield) |
| text | Text | Text constructed from the target and its attribute |
| flags | UnsignedShort | Flags that control how the attribute text is filled in |
| refCount | UnsignedShort | For internal use |
| target | Object | The target to be watched |
| targetAttribute | Unsigned | The attribute of interest |
The textOwner field is managed automatically by the text framework. In your object definition files, this field should be nilObject.
The AttributeTextPlus class adds a field named extraText, and overrides Template. It does so to allow you to prepend some extra text to the text produced by the attribute text object. For example, you might be monitoring the number of names in a group list. You could use AttributeTextPlus to produce a text object that contains "MST3K Fan #453" instead of just the number "453."
Here's an example of how you could use an AttributeTextPlus object to customize a field for a user. This example uses a text field to name a personalized newsmagazine:
Instance TextField 'newsmagazine' 5;
next: (TextField 'explanation' 8);
previous: nilObject;
superview: (Form 'News Magazine order' 4);
subview: nilObject;
relativeOrigin: <-99.0,-84.0>;
contentSize: <192.0,50.0>;
viewFlags: 0x70019000;
labelStyle: iBook12;
color: 0xFF000000;
altColor: -1;
shadow: nilObject;
sound: nilObject;
border: nilObject;
fieldFlags: 0x80000000;
dataStore: (AttributeTextPlus 6);
baseStyle: iBook12;
End Instance;
Instance AttributeTextPlus 6;
textOwner: nilObject;
text: nilObject;
flags: 32770.w;
refCount: 0.w;
target: iSystem; // {0}, System
targetAttribute: 1000;
extraText: (Text 7);
End Instance;
Instance Text 7;
text: 'Acme Personal Informer for ';
End Instance;
The FrozenAttributeText class is what an attribute text object becomes when it's encoded for the wireline; that is, when it's sent on a telecard.
The following masks are flags you can use in the flags field to control how the attribute text object creates its text. These flags mainly affect the action of the CopyTextFromTarget method, though some are relevant to other methods.
#define dirty_Mask 0x0001
This flag is for system use only. Please don't set it.
#define useGetTextInfo_Mask 0x0002
Set this flag to call TextInfo on the target to fill in the attribute text object. If you don't set this flag (or the getAttribute flag), the result of a TextData call is used to fill in the attribute text. The CopyTextFromTarget method checks this flag.
#define observing_Mask 0x0004
This flag is for system use only. Please don't set it.
#define useName_Mask 0x0008
This flag does one of two different things, depending on the value of the getAttribute flag:
#define cacheMayBeWrong_Mask 0x0010
This flag is for system use only. Please don't set it.
#define copyAttribute_Mask 0x0020
If this flag is set, the answer returned by the CopyTextFromTarget method is a copy of the target attribute instead of the attribute itself. Similarly, the CopyTextIntoTarget method uses a copy of the new text object, instead of the original object.
There are times when you must use this flag, and times when you shouldn't. Some objects return a copy of their attribute text object instead of the object itself. If your target is an object like this, you shouldn't set this flag. (If you do set it, an assertion will fail. Without the assertion, your code would leak memory.)
If your target object does not return a copy, you need to set this flag. (If you don't, an assertion will fail. Without the assertion, horrible bad things could happen, because the text object might vanish from under your nose.)
#define getAttribute_Mask 0x0040
Set the getAttribute flag to use the current value of the target's attribute to fill in the attribute text object. The value filled in is also affected by the useName and copyAttribute flags.
#define setAttribute_Mask 0x0080
Set this flag when you want to use an attribute text object to set its target's attribute instead of or in addition to monitoring it. If you haven't set this flag but the getAttribute flag is set, the CopyTextIntoTarget method does nothing.
#define zeroValueBlank_Mask 0x0100
Set this flag when you'd like an attribute text object to display nothing if the numeric value of its target's attribute is zero. If you haven't set this flag, the digit "0" is displayed instead.
#define dontSetTarget_Mask 0x0200
Set this flag to prevent the SetTarget method from redirecting the attribute text object to a new target. This flag is useful for attribute text objects that should be fixed, always watching the same target.
#define dontObserveOffscreen_Mask 0x8000
Set this flag to prevent the attribute text object from watching its target while its viewable (the text owner) is off screen. If this flag is set, the Closing method calls DisconnectAttributeText to stop the observation process. You might want to use this flag for some speed improvements.
Version note: The system maintains the observing flag while an attribute text object is watching an object in a scene. If the dontObserveOffScreen flag is clear, the observing bit remains set even after the user has gone to some other scene. If the user then sends or beams the package, this flag is still set on the receiving end. The flag is now in error since the Observe/Notice lists on the receiving device do not contain this attribute text object. Then, AttributeText_Thaw will see the flag and skip the Observe step, which means the text will not be updated appropriately in the future.You can work around this problem by always setting the dontObserveOffScreen flag for attribute text objects in your packages.
#define dontObserveOnscreen_Mask 0x4000
Set this flag to prevent the attribute text object from watching its target while its viewable (the text owner) is on screen. If this flag is set, the Opening method doesn't call Observe, and thus won't start the observation process.
#define dontObserve_Mask 0xC000
This flag is a convenience constant. Setting it is the equivalent of setting both the dontObserveOffscreen and dontObserveOnscreen flags.
operation CopyTextFromTarget(): Text, safe Call: never Override: never
The system calls CopyTextFromTarget when the attribute text's target has changed. It creates new text, reflecting the new status of the target, for the attribute text object to display. This method's behavior is affected by a number of attribute text flags, which are described in the previous section.