May 8, 1995
Inherits from TitledWindow Inherits from BalloonSpout Defined in Window.Def
Gadget windows are windows with targets. They have balloon spouts that sprout from their targets. Usually that target is a gadget. Gadget windows typically appear when the user taps on the window's target gadget. The illustration at the beginning of this chapter shows a gadget windowa window containing two locksspouting from its gadget, the drawer in the small table.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Instantiate: often Subclass: often Call its methods: rarely
Gadget windows, deep in their heart of hearts, are windows that spout from something. That something is usually a gadget, which deep in its dark heart is nothing more than an object that displays a window when it's tapped. You'll use gadget windows whenever you use gadgets. See the chapter on class Gadget for details on gadgets.
Sometimes you'll use gadget windows without gadgets. For example, class AttributeWindow isn't associated with a gadget. Neither is class TextSelectionWindow, which spouts from a chunk of selected text and not from a gadget.
Magic Cap has a variety of subclasses of class GadgetWindow, each designed for a specific use. Some notable gadget windows subclasses are classes AttributeWindow, ListWindow, ContainerWindow, and InfoWindow. You will often create subclasses of your own when you want your gadget window to behave in a special way or contain special objects.
Here's an example of a simple subclass, class BackUpWindow:
Define Class BackupWindow;
inherits from GadgetWindow;
field prototypeName: HasText;
// default backupName
field backupName: HasText;
// name user has entered for package to create
// for backup
field backupChoices: ChoiceBox;
// choices for list of ContainerDevices available
// to store the backup or restore
field backupListView: ListView;
// pop-up list of packages that can be restored
field containerDevice: ContainerDevice, getter;
// currently selected ContainerDevices from
// backupChoices
field storageBox: StorageBox;
// storageBox to restore from
operation DoFullBackup(), safe, common;
// perform FullBackup using our containerDevice
// and backupName fields
operation DoFullRestore(), safe, common;
// ask user if he really wants to Restore
operation ConfirmedFullRestore(), safe, common;
// perform FullRestore using our containerDevice
// and storageBox fields
overrides AboutToShow,AboutToHide,Notice;
attribute ContainerDevice: ContainerDevice, safe;
End Class;
You'll notice that this subclass has very little in common with other kinds of gadget windows. It adds many new fields and operations to do its specialized job. It overrides AboutToShow and AboutToHide to manage observing a list of possible destinations for filing objects, iFileDestinationList. In all other ways, it just inherits its behavior from class GadgetWindow, without changing it.
Here's a back up window in its native habitat:
Notice that the back up window displays the two distinguishing characteristics of the gadget window: it spouts from something (the magic lamp) and it has a title bar.
Class GadgetWindow defines the following methods:
| Method | Description |
|---|---|
| SetUpTargetWindow | Set the target of this gadget window and set the target of all controls inside this window |
| Underpinnings | |
| Appear | Overridden to position the window if the autoPosition flag in windowFlags is set, and to call TargetChanged on target if it's a gadget |
| Disappear | Overridden to call TargetChanged on target if it's a gadget |
| CanAccept | Overridden to reject its own target |
| BalloonDot | Overridden to get the spout point from its target |
| ZoomFromWhere | Overridden to use the balloon dot as the spout origin |
| ChangedContents | Overridden to call TargetChanged on the window's target, if the target is a gadget |
| MakeValid | Overridden to add self to iMakeActive list |
| MakeActive | Overridden to call TargetChanged on the window's target, if the target is a gadget |
Class GadgetWindow 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 | Flags | 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 HasBorder | ||
| border | Border | Framed border drawn around object |
| inherited from Window | ||
| windowFlags | Flags | Stores various boolean attributes of the window |
| inherited from TitledWindow | ||
| titleColor | Unsigned | RGB value used to fill in the window's title box |
| titleHeight | Micron | Height of the title box |
| dependents | ObjectList | List of windows used by HasDependent |
| inherited from BalloonSpout | ||
| balloonDot | Dot | The spot the balloon spouts from (ignored by gadget windows) |
| defined by GadgetWindow | ||
| target | Object | Used by the Target attribute |
Here's the object definition for the gadget window shown at the beginning of this chapter:
Instance GadgetWindow 'Drawer' 3247;
next: nilObject;
previous: nilObject;
superview: nilObject;
subview: nilObject;
relativeOrigin: <-25.5,-50.5>;
contentSize: <299.0,102.0>;
viewFlags: 0x50105000;
labelStyle: iBook12Bold;
color: 0xFF000000;
altColor: 0xFFFFFFFF;
shadow: nilObject;
sound: nilObject;
border: iBorderBlack2;
windowFlags: 0x00004000;
titleColor: 0xFF333333;
titleHeight: <28.0>;
dependents: nilObject;
balloonDot: <0.0,0.0>;
target: (Gadget 3246);
End Instance;
Fill in the balloon dot field with <0.0,0.0>. Gadget windows spout from their targets and don't use their balloon dot fields.
The target field should point to the object the gadget window spouts from. This object will probably be the viewable the user taps to make the gadget window appear, though sometimes it makes more sense for the gadget to spout from a related viewable. For example, the back up window shown earlier in this chapter spouts from the magic lamp, even though the user taps a back up button inside a different window to make it appear. The back up button is inside the command window, a gadget window that spouts from the magic lamp. Only rarely should there be more than one window at a time on the Magic Cap screen, and it would be confusing to have one window spouting from inside another window. So the back up window spouts from the magic lamp, thus avoiding clutter and confusion.
Class GadgetWindow defines just one attribute:
| Attribute | Type | Description |
|---|---|---|
| Target | Object | The viewable (usually a gadget) that the window points to |
operation SetUpTargetWindow(viewTarget: Viewable; attributeTarget: Object); Call: rarely Override: rarely
Call SetUpTargetWindow to point the gadget window and any controls it contains to a particular target. The viewTarget parameter is the new target for the gadget window. The attributeTarget parameter is the new target for any controls inside the gadget window . Often these two parameters will be the same.
The system uses this method only when setting up the window that controls recording sound stamps and the window that controls song stamps. Gadget windows that spout from a fixed target can ignore this method. You'll use this method only if you're calculating on the fly the viewable your gadget window spouts from.