May 8, 1995 Inherits from Proxy
Content proxies are stand-ins for objects that can be mailed, beamed, printed, or filed. They are objects that represent larger items or collection of items. The illustration at the beginning of this chapter shows a viewable container for a content proxy for a name card, created when a user tapped the mail button in the magic lamp.
Instantiate: rarely Subclass: sometimes Call its methods: often
You'll probably create content proxies programmatically instead of predefining them in an object definition file. You'll most commonly create them by calling Scene_NewContentProxy. The chapter on class Scene describes that method briefly, but this chapter goes into detail and gives lots of examples showing how you're likely to use it.
Here's the declaration for Scene_NewContentProxy:
operation NewContentProxy(descriptionText: Object;
count: Unsigned; target: Object; image: Object;
conveyFlags: Flags): Object;
NewContentProxy begins by creating a copy of iPrototypeContentProxy. Here's the object definition for iPrototypeContentProxy:
Instance ContentProxy 891;
next: nilObject;
previous: nilObject;
superview: nilObject;
subview: nilObject;
relativeOrigin: <-219.0,-139.0>;
contentSize: <43.0,42.0>;
viewFlags: 0x10181200;
labelStyle: iSign10;
color: -1;
altColor: 0xFF000000;
shadow: nilObject;
sound: nilObject;
image: iMiniCardImage;
target: nilObject;
proxyFlags: 0xC0000000;
conveyFlags: 0;
End Instance;
The prototype proxy has both the isAlias and keepNameAsIs proxy flags set. Its image is the default mini card image, which depicts a small telecard.
NewContentProxy sets the proxy's target to be the object in the target parameter. It sets the proxy's image to be the image in the image parameter. (If the image isn't shared, NewContentProxy uses a copy of the image. Otherwise, it points to the same image object.) NewContentProxy also sets the proxy's conveyFlags field to the value in the conveyFlags parameter.
The count parameter is the number of items this proxy represents. You must provide a count, or NewContentProxy will return nilObject instead of a proxy object.
The descriptionText parameter is the label text that appears underneath the proxy. Usually this is a brief name for the proxy. If you don't provide a text description, NewContentProxy will construct a name for the proxy. If you don't provide a description, NewContentProxy uses the name of the target object for the proxy label. If the target object is an object list with only one entry, the proxy's label is the name of that entry. If the target object doesn't have a name, NewContentProxy uses the target's text info, with the index kTypeDescription.
If it's making a proxy that represents more than two items, NewContentProxy will try to map the description text using the mapping iContentDescriptionMapping. Here's the object definition for that mapping:
Instance TextMapping 7113; // iContentDescriptionMapping
keyText: (Text 7114);
valueText: (Text 7115);
End Instance;
Instance Text 7114;
text: 'count\npages\nname\nkind of card\nother name';
End Instance;
The system defines several indexicals for description texts that you might use with NewContentProxy. Here are the indexicals:
| Indexical | Description text |
| iContentDescriptionScene | 'screen' |
| iContentDescriptionCard | 'card\nboth cards\nall /count/ cards' |
| iContentDescriptionItem | 'item\nboth items\nall /count/ items' |
| iContentDescriptionIndex | 'index' |
| iContentDescriptionFolder | 'folder' |
| iContentDescriptionBackup | 'backup of system' |
You'll usually find the mappable text in iContentDescriptionCard and iContentDescriptionIndex suits most of your needs. You might want to customize your proxy's descriptions by passing other mappable text to NewContentProxy. NewContentProxy assumes that if count is greater than 2, the description text is set up like the text in those two indexicals. If you're likely to use a count of 3 or more when you call NewContentProxy, send it text like this:
'chess board\nboth chess boards\nall /count/ chess boards'
Here's how you could use these text descriptions to create a proxy for 3 name cards. The name cards are in an object list called cardList. Here's how you would call NewContentProxy:
proxy = NewContentProxy(myScene, iContentDescriptionCard, 3,
cardList, iFolderImage, 0);
The content proxy would appear as a folder with the name "all 3 cards," like this:
If you're subclassing Scene to override MakeContentProxyChoices, you might also want to override NewContentProxy. In the most common situation, you'll override to copy a prototype proxy item.
If you're making a content proxy in a very controlled situation, you can write a very simple override for NewContentProxy. The example in the description of Scene_MakeContentProxyChoices was of a scene which needed proxies for widget objects. Here's how class WidgetScene might override NewContentProxy:
Method ObjectID
WidgetScene_NewContentProxy(ObjectID self,
ObjectID descriptionText, Unsigned count,
ObjectID target, ObjectID image, Flags conveyFlags)
{
ObjectID contentProxy;
Str255 name;
/* start with a copy of our prototype proxy for widgets,
which we've cleverly made into a package indexical */
contentProxy = CopyNear(iPrototypeWidgetContentProxy,
self);
/* give the proxy the same name as the widget */
GetName(target, name);
SetName(contentProxy, name);
/* point the proxy at the widget */
SetTarget(contentProxy, target);
/* set up the proxy the way we're told */
SetImage(contentProxy, image);
SetFieldOf(contentProxy, ContentProxy_conveyFlags,
conveyFlags);
/* return our finished proxy */
return contentProxy;
}
The prototype widget proxy should be a content proxy object with its fields and flags set up the way most widget proxies should be set up. For example, you could simplify this override of NewContentProxy by setting up the prototype to use a small widget image, and skip the SetImage call.
Class ContentProxy defines the following methods:
| Method | Description |
|---|---|
| Copying | Overridden to check the conveyTransient flag and if it'set, copy the proxy's | target and point the proxy at the copy |
| CreateContainer | Get a single viewable to contain whatever object it is we need a proxy for |
| Finalize | Overridden to destroy the proxy's target if the conveyTransient flag is set |
| MailOnTelecard | Overridden to create a telecard to use to mail this proxy |
| Render | Print or fax the target of this proxy |
Class ContentProxy defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from SingleLinkable: | ||
| next | Object | Next item in view list |
| Inherited from Linkable: | ||
| previous | Object | Previous item in view list |
| Inherited from Viewable: | ||
| superview | Viewable | Container for this object |
| subview | Viewable | Object contained by this object |
| relativeOrigin | Dot | Origin relative to superview |
| contentSize | Dot | Size of content rectangle |
| viewFlags | Unsigned | Property settings |
| labelStyle | TextStyle | Text style of object's label |
| color | Color | Color of object's content |
| shadow | Shadow | Shadow drawn with object |
| sound | Sound | Sound associated with object |
| Inherited from Stamp: | ||
| image | Image | Image used to draw stamp |
| Inherited from Proxy: | ||
| target | Object | The object for which this proxy is a stand-in; used by the | Target attribute |
| proxyFlags | Unsigned | Flags that control various aspects of the proxy object |
| Defined by ContentProxy | ||
| conveyFlags | Flags | Various flags indicating special handling of items |
Class ContentProxy defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| Stationery | Stationery | iThe stationery to be used for sending this content |
| UsageType, SetUsageType | UnsignedShort | The intended use of this content |
Class ContentProxy has three named flags you can set in the conveyFlags field. This section describes the flags.
#define conveyTransientMask 0x10000000
Set this flag if your proxy's target is transient. If this flag is set, the system will destroy the proxy's target object when it destroys the proxy object.
You'd set this flag if you're creating an object whose sole purpose is to display a content proxy choice to the user. For example, if you created an object list to contain three name cards that the user could mail, you'd probably want the object list to be deleted when its contents have been mailed. You'd set this flag for that object list.
#define conveyBorderMask 0x00008000
Set this flag if you want Render to draw a border around viewable when faxing or printing.
#define contentProxyUsageMask 0x0000000F
This flag stores the intended usage type of this contentProxy. Here are the usage types handled by most kinds of scenes:
| Usage Type | Value | Description |
|---|---|---|
| contentFile | 1 | Items that can be filed in data packages or in the file cabinet |
| contentPrint | 2 | Items that can be printed |
| contentMail | 3 | Items that can be sent on telecards |
| contentFax | 4 | Items that can be faxed |
| contentBeam | 5 | Items that can be beamed |
attribute Stationery: Stationery // operation Stationery: Stationery // operation SetStationery(newStationery: Stationery); Call: rarely Override: sometimes
Call Stationery to get the stationery that should be used to mail this content proxy. ContentProxy_Stationery just returns iDefaultStationery and SetStationery does nothing. You might override this attribute's getter or setter if you've created a custom kind of content proxy which sometimes should be sent on a particular kind of stationery.
attribute UsageType: UnsignedShort // operation UsageType: UnsignedShort; // operation SetUsageType(newType: UnsignedShort); Call: rarely Override: rarely
Call UsageType to get the intended usage type of this proxy, which is stored in the contentProxyUsage flag. The usage type attribute is set by the method NewContentProxy after it's created, when NewContentProxy sets up the new proxy's flags.
operation CreateContainer(): Viewable; Call: rarely Override: rarely
The system calls CreateContainer to get a viewable to use to send or beam this content proxy. For example, ContentProxy_MailOnTelecard calls CreateContainer to make a viewable for the proxy, then puts the new container on a telecard for mailing.
If the proxy's target is a card, CreateContainer returns copy of target in system persistent cluster;
If the proxy's target is a stack subclass, CreateContainer returns folder in system persistent cluster whose list is an object of class StackOfCards that contains copies of all the cards in the target.
If the proxy's target is a non-stack object list, CreateContainer returns a folder in the system persistent cluster whose list is a copy of the proxy's target.
If the proxy's target is a storage box, CreateContainer returns the result of a CreateContainer call on the storage box.
operation Render(printJob: Object); Call: rarely Override: rarely
The system calls Render on a proxy when the user has chosen to fax or print it.
Render first prints the cover page for the fax or print job, if any. If the conveyBorder is set, Render creates a 2-pixel border on the print job. If the proxy's target is an object list, Render calls RenderIntoPage on each item in the list. Otherwise, it just calls RenderIntoPage on the target.
You might override Render to set up the print job differently, or to distinguish faxing and printing cases by checking the UsageType, SetUsageType of the proxy.
overrides MailOnTelecard; Call: rarely Override: rarely
To be written. Here are the Def file comments for this method:
If the system is not yet personalized, MailOnTelecard reminds
the user to personalize first. Otherwise, it creates a mini card
on the desk from self's stationery that points to object created
by CreateContainer(self), and zooms it up for the user to finish
or send. Override this method to create a message to send that
represents self's content some other way if content cannot be
represented by a Card subclass.