Inherits from Viewable, BackgroundWithBorder
Magic Cap relies on a "drag and drop" interface technique, in which items on the screen are directly manipulated by users as if they were actual physical objects. Coupons provide a way for intangible attributes and qualities to be seen and applied to objects. Users can use coupons to apply colors, rotate objects, change text styles, and do many other tasks.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Class Coupon is a direct descendent of class Viewable. In addition, Coupon mixes in class BackgroundWithBorder, which gives coupons their distinctive dotted border.
Coupon defines several fields for its objects. Coupons act as tangible representatives for other objects, such as colors or shape types, and each coupon has a reference to the object it represents. Class Coupon also defines two fields that allow its objects to provide more detail about what should happen when the coupon is applied to a viewable object.
Many different kinds of coupon objects are provided in the Magic Hat.
Instantiate: never Subclass: sometimes Call its methods: rarely
The Coupon class is abstract; you'll never create or work with any objects of type Coupon. You might create your own subclass of coupon if you can't find the kind of coupon you need in the Magic Hat.
You'll rarely call any methods of class Coupon. Usually you'll just use coupons from the Magic Hat as you put your packages together. Because coupons perform some action and then vanish, you'll rarely include any coupons in your packages. You might put your own custom coupons in the Magic Hat, though, so your users can tear off copies to their hearts' content.
When you do call methods of class Coupon, you can get and change the coupon's image, its text, or the intangible object it's associated with.
The Coupon class defines the following methods:
| Method | Description |
|---|---|
| Accepted | Play the swallow sound when an object accepts the coupon |
| Amount | Get the coupon's "amount" value |
| SetAmount | Set the coupon's "amount" value |
| AutoMove | Return true, since coupons can be moved without the move tool |
| Border | Return the indexical for the dashed-line coupon border |
| CalcContentBox | Return a content box sized correctly for various kinds of coupon |
| CanAcceptCoupon | Overridden to allow all coupons to accept view coupons, and style coupons | to accept color coupons |
| CanApply | Return true if the coupon can be applied to the given viewable |
| CanDrawIn | Return kdontdrawhere, since you can't draw in coupons |
| CanStretch | Return false for text coupons, the inherited method for everything else |
| CouponImage | Return the image associated with the coupon, for subclasses that use | images |
| CouponObject | Get the coupon's associated object or attribute |
| SetCouponObject | Set the coupon's associated object or attribute |
| CouponText | Put the coupon's name into a string |
| DisplaySize | Return the display size of the coupon plus its object |
| Draw | Just call drawcoupon |
| DrawCoupon | Draw the coupon |
| Mode | Get the mode from the selector field |
| SetMode | Set the mode in the selector field |
| Pressed | If the coupon was dragged, drop the coupon |
| SetPartColor | Change the color of the coupon object, if the coupon is a color coupon |
| Tap | Drop the coupon using the given touch input |
| TextStyle | Return the default coupon text style, ibook12 |
Whenever you create a subclass of the Coupon class, you should override the following methods:
| Method | Description |
|---|---|
| ApplyCoupon | To perform the action indicated by the coupon |
In addition, you might override these other methods under the following circumstances:
| Method | When to override |
|---|---|
| CouponImage | If you want an image to be drawn on the coupon |
| Draw | If the coupon has a nonstandard appearance |
The Coupon class 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 |
| Defined by Coupon | ||
| couponObject | Object | Object or attribute associated with coupon |
| selector | Unsigned | Provides detail on coupon's action |
| amount | Unsigned | Provides value for coupon's action |
operation DrawCoupon(canvas: Object; clip: Object): Object Call: rarely Override: rarely
DrawCoupon is a utility routine that draws the generic parts of a coupon, a rectangle with a dashed-line border. DrawCoupon calls GetCouponText to determine if the coupon has any text; if it does, the text is drawn on the coupon. If the coupon has no text, DrawCoupon returns the coupon's coupon object, obtained by calling GetCouponObject, as the function result. You can use this return value in your Draw method to draw the coupon object in other ways, if you wish.
If your coupon subclass overrides Draw to provide a custom appearance, you should call DrawCoupon from your overridden Draw method to draw the generic part of the coupon.
operation SetAmount(newAmount: Unsigned) Call: sometimes Override: rarely
Call SetAmount to set the coupon's amount to the given value. The coupon's value is used by some coupons to determine what happens when the user drops the coupon on another object. For example, the ViewCoupon class uses the coupon's amount to determine whether the coupon should turn a setting on or off.
operation SetCouponObject(newObject: Object) Call: sometimes Override: rarely
Call SetCouponObject to set the coupon's associated object to the given object.
operation ApplyCoupon(theTarget: Object; where: Dot) Call: rarely Override: always
The system calls ApplyCoupon when the user drops a coupon into a viewable object. ApplyCoupon should perform the action represented by the coupon. Coupon_ApplyCoupon does nothing, since this action depends on exactly what kind the coupon is.
You should override ApplyCoupon when you create a subclass of Coupon. In your overriding method, you should perform the action that the coupon represents. The theTarget parameter is the object that is accepting the coupon. The where parameter gives the coordinates where the user dropped the coupon, although many coupon subclasses don't use this parameter in their ApplyCoupon methods.
Here's how the BorderCoupon subclass overrides ApplyCoupon:
Method void
BorderCoupon_ApplyCoupon(ObjectID self, ObjectID target, const
Dot *where)
{
#pragma unused (where)
SetBorder(target, MoveNear(CouponObject(self), target));
}
And here's how color coupons do it:
partCode = InsidePart(target, where);
if ((partCode == partContent || partCode == partImage)
&& OptionKey())
partCode = partAltContent;
SetPartColor(target, RGB(CouponObject(self)), partCode);
operation CouponImage(): Object Call: rarely Override: sometimes
The system calls CouponImage when it draws the generic part of a coupon (in the DrawCoupon method). If CouponImage returns a non-Nil result, the system draws the returned image at the left edge of the coupon. If CouponImage returns nilObject, the system draws no image on the coupon. Coupon_CouponImage simply returns nilObject.
You should override CouponImage if you want your coupon subclass to draw an image on the left edge of its coupons. In your overriding method, you should simply return the desired image as the function result. For example, the SoundCoupon class overrides CouponImage to return the musical note image that's drawn on every sound coupon.
overrides Draw Call: rarely Override: sometimes
When the system has to draw a coupon on the screen, it calls the coupon's Draw method. Coupon_Draw simply calls DrawCoupon, which draws the coupon's rectangle, its dashed-line border, and its text, if any.
You should override Draw if you want coupons of your subclass to have an appearance other than the generic: a rectangle with a dashed-line border, optional text, and an optional image at the left edge of the coupon. Your overriding method should draw the coupon as you wish. You should not call the inherited Draw from your overriding method; instead, call DrawCoupon to draw the generic parts of the coupon.