Defined in Gadget.Def Inherits from Stamp, StarburstHilite Inherits interface from Targeted
Gadgets appear as images that represent windows. When the user touches a gadget, the associated window appears on the screen. The window usually contains several other objects for the user to touch, such as icons or buttons. For example, touching the Magic Lamp gadget opens a window that contains a number of buttons that perform commands.
When the user touches a gadget connected to a window that's already open, the window closes.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Gadget is a subclass of Stamp. Each gadget has a target, which is the window that appears when the user taps the gadget. Gadgets also have a set of flags that maintain various settings.
Many gadgets in the Magic Cap software are system objects, such as the Trash, Tote Bag, Magic Hat, and Tools gadgets. Other gadgets, such as index and directory gadgets, are generally useful in many kinds of packages.
Instantiate: sometimes Subclass: sometimes Call its methods: rarely
You might want to instantiate generally useful gadgets, like index or directory gadgets. You can do this by adding the text definition for a gadget and its target to your object definition (Objects.Def) file.
You might create a subclass of Gadget if you want to have gadgets that do something other than simply toggling the appearance of a window.
It's very unlikely that you'll call any methods of class Gadget. Class Gadget defines very few methods, most of which are overrides to implement the basic behavior of gadgets.
Class Gadget has the following method that you might Call:
| Method | Description |
|---|---|
| Target | returns the gadget's target window |
You might override these methods under the following circumstances:
| Method | When to override |
|---|---|
| Press | You want to change the gadget's response when the user presses |
| Action | You want to change the gadget's most basic behavior (displaying a window) |
Class Gadget 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 |
| altColor | Color | Alternative object color |
| shadow | Shadow | Shadow drawn with object |
| sound | Sound | Sound associated with object |
| Inherited from Stamp | ||
| image | Image | Image used to draw gadget |
| Defined by Gadget | ||
| target | Object | Viewable shown/hidden when user taps |
| flags | Unsigned | Various gadget settings |
Class Gadget uses a number of flags to control various gadget behaviors. The flags are listed here in two tables. The first table is a list of system flags, which will probably not be useful to you (but are documented here to satisfy your natural curiosity about them). The system flags are used internally as a sort of light-weight subclassing. For example, you'll probably never use the Magic Hat flag yourself. You might use the pull out flags, though, or the show occupied flag. So the second table is a list of flags that you will find handy in creating your own gadgets.
The system flags defined by class Gadget are:
| Flag | Bit | Meaning if set |
|---|---|---|
| searchFlag | 26 | The gadget is the search gadget |
| acceptToolsFlag | 25 | Used by drawergadget |
| acceptStationeryFlag | 24 | Used by drawergadget |
| magicHatFlag | 22 | The gadget is the magic hat |
| gadgetLockBoxFlag | 20 | Used by storagebox |
The useful-to-you flags defined by class Gadget are:
| Flag | Bit | Meaning if set |
|---|---|---|
| swallowFlag | 31 | The gadget will swallow other objects |
| categorizeFlag | 30 | The gadget has subviews that display various categories of objects |
| pullOutFlag | 28 | Pressing will move contained objects out |
| setEmptyFlag | 27 | Empties the gadget before it swallows a morsel |
| pullOutCopyFlag | 23 | Pressing will make copies of contained objects |
| showOccupiedFlag | 19 | Use alternate image if not empty |
| useStarburstFlag | 18 | Use starburst highlight |
| dontSetTargetFlag | 17 | Don't set target during action |
The gadget flags are set to the bit number that you should check. For example, to check if the pull out flag is set, you would use code similar to this fragment:
if (viewable && (flags & (1 << pullOutFlag))) {
/* handle pulling & dragging */
…
}
attribute Target: Object, readOnly // operation Target(): Object Call: rarely Override: rarely
Call Target to get the gadget's target, which is the window that appears or disappears when the user taps the gadget. Gadget_Target simply returns the value of the gadget's target field.
overrides Touch(touchInput: Object) Call: rarely Override: rarely
Touch highlights the gadget, calls the inherited Touch method, and unhighlights the gadget. You should override Touch if your gadget subclass shouldn't highlight itself when touched.
overrides Press(touchInput: Object) Call: rarely Override: sometimes
The system calls Press when the user presses on an object. If the pull out bit of the gadget's flags field is not set, Gadget_Press simply calls the inherited Press. If the pull out bit is set, Gadget_Press allows the user to drag a subview out of the gadget. If the pull out copy flag is set, Press makes copies of the pressed object.
You should override Press if you want your gadgets to have some other behavior when the user presses on them. You should call the inherited Press method if you want the standard Press behavior to take place either before or after your custom behavior.
overrides Tap Call: rarely Override: rarely
The system calls Tap when the user taps an object. Gadget_Tap is overridden to avoid the inherited Tap's call of PlaySound. Gadget_Action handles sounds. Tap simply calls Action, and does nothing else. You might want to override Tap to allow your gadget to play different sounds when it's in different states. For example, if your gadget can contain other objects, you might want to play the error sound when it's full and can't contain anything more.
overrides Action Call: rarely Override: sometimes
The system calls Action from Tap, in response to a user tap on the gadget. Action does the following:
Override Action if you want your gadgets to have some other behavior when the user taps them. You should call the inherited Action method if you want the standard Action behavior to take place either before or after your custom behavior. For example, you might override Action if you don't want tapping on an active gadget to hide its target.
overrides CanAcceptCoupon(coupon: Object; partCode: long): Boolean Call: rarely Override: sometimes
The system calls CanAcceptCoupon to test if a gadget can accept a coupon . If the swallow flag is set and the user isn't pressing the option key, Gadget_CanAcceptCoupon returns false, because the coupon will be swallowed as if it were any other viewable. (For example, the tote bag and the trash should both be able to contain coupons.) Otherwise, CanAcceptCoupon calls its inherited method.
overrides Swallow(morsel: Object; where: Dot; realSwallow: Boolean): Boolean Call: rarely Override: sometimes
The Swallow method defines the behavior a gadget exhibits when the user drops an object onto it. Swallow handles this situation as follows:
Now the real fun begins. If none of the above conditions apply, Swallow does the following:
You should override Swallow if your subclass of class Gadget needs to do anything different when swallowing an object.
overrides UseStarburst(): Boolean Call: rarely Override: rarely
The UseStarburst method checks the use starburst flag. If it's set, UseStarburst returns true. You probably won't need to override this method. Instead, you'll just set or unset the use starburst flag.
overrides TargetChanged() Call: rarely Override: rarely
The system calls the TargetChanged method when the gadget's target has changed in some way, such as when the user drops an object into it. The default implementation of TargetChanged checks the show occupied flag. If this flag isn't set, TargetChanged returns without doing anything. Otherwise, TargetChanged checks the target: is it empty? TargetChanged sets the gadget's image to the "empty" image if the target is empty, and to the "occupied" image if it contains anything. The "empty" image is determined by calling First on the current image, and the "occupied" image by calling Last.
The Trash gadget is a good example of a subclass of gadget that uses the show occupied flag. Here's the object definition of the trash gadget:
Instance TrashGadget 'Trash' 29;
next: (KeyboardGadget 'Keyboard' 13);
previous: (Gadget 'desk' 104);
superview: (ControlBar 4);
subview: nilObject;
relativeOrigin: <204.0,0.0>;
contentSize: <48.0,25.0>;
viewFlags: 0x10081000;
labelStyle: iSign8;
color: -1;
altColor: 0xFF000000;
shadow: nilObject;
sound: iTouchSound;
image: iTrashImage;
target: (TrashWindow 'Trash' 447);
flags: 0x90280000;
max: 6;
End Instance;
The image, iTrashImage, is the standard trash truck. The next field of that image points to the "full" trash image, the trash truck with a pile of refuse peeking from its top.