Defined in Gadget.Def Inherits from Stamp, StarburstHilite, HasDestination
Gadgets display windows when you touch them. Buttons call functions. And icons take you to new destinations.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
To use an icon, tap it. The icon highlights, and a new scene zooms open. This is what icons do most often. For examples, look at the icons on the desk: the notebook icon, the clock icon, and the phone icon. Each of these icons move the user to a new scene.
On rare occasions, icons send taps to other objects. For example, the message icon on the desk (the icon that looks like stationery) doesn't move the user to another scene itself. Instead, it sends a tap to the default stationery.
Instantiate: sometimes Subclass: often Call its methods: sometimes
You will often create custom subclasses of class Icon, most commonly because you need to override methods like Action or Tap. See the methods descriptions for some hints about when you might need to override.
Here's an example of an icon you've probably seen many times:
Instance NotebookIcon 'Notebook' 507;
next: (DrawerGadget 'Stationery' 3084);
previous: (MessageIcon 'Message' 3079);
superview: (Scene 'Desk' 18);
subview: nilObject;
relativeOrigin: <99.0,7.5>;
contentSize: <75.0,40.0>;
viewFlags: 0x50081000;
labelStyle: iBook12;
color: -1;
altColor: 0xFF000000;
shadow: nilObject;
sound: iTouchSound;
image: (Image 'Notebook' 843);
destination: (NotebookScene 'Notebook' 516);
nativeContainer: (Scene 'Desk' 18);
nativePosition: <99.0,7.5>;
End Instance;
This icon appears on the desk. It uses the notebook image, and its destination is the notebook. Your users probably refer to this icon as "the notebook", so closely is this icon linked to its destination in their minds. Keep this close linkage in mind when designing the appearance of your icons: the image you choose is the image that defines the destination to your users.
The notebook icon is a subclass of class Icon instead of an instance, because the notebook icon overrides the Swallow method. See the description of Swallow below for some hints about when you might need to override Swallow for your custom icon classes.
Class Icon defines the following methods:
| Method | Description |
|---|---|
| AutoMove | Returns true if the icon can be dragged |
| NativeContainer | Returns the icon's native scene or container |
| SetNativeContainer | Sets the icon's native scene or container |
| PutAway | Returns the icon to its native container and position |
| Touch | Highlights the icon when it's touched |
| Action | Zooms to the icon's destination |
You might override these methods under the following circumstances:
| Method | When to override |
|---|---|
| Action | If you need to do more than just zoom to the icon's destination |
| Tap | If you need to do some checking before allowing the user to zoom away |
| Draw | If your icon needs to display more than just its image |
| Swallow | If you need special processing to swallow certain kinds of morsels |
Class Icon 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 |
| Defined by Icon: | ||
| nativeContainer | Viewable | The icon's default superview |
| nativePosition | Dot | The icon's default position (relative to the origin of the native container) |
You should set the native container of your icon to the most appropriate system place. For example, if your icon belongs in the desk accessory drawer, set the field to iDeskAccessoryWindow. Or if your icon belongs in the desk scene, set the field to iDesk.
You shouldn't set the icon's native position yourself. In your object definition file, set that field to <0.0,0.0>. The system assigns your icon a unique position when it's installed, which it stores in the icon's relative origin field. You can save that position by overriding AboutToShow for your subclass. Here's an example of how you might do so:
Method void
MyIcon_AboutToShow(ObjectID self)
{
Dot relOrigin;
/* get the relative origin */
RelativeOrigin(self, &relOrigin);
/* put it into the nativePosition field */
SetFieldOf(self, MyIcon_nativePosition, relOrigin);
}
overrides Action() Call: rarely Override: sometimes
The system calls Action from the Tap method, whenever the user taps the icon. By default, the Action method calls ZoomToDestination. (ZoomToDestination is a method inherited from the HasDestination mixin.)
Override Action if your subclass of Icon needs to do something more than just zooming off into the sunset scene (or any other scene). For example, class ArchiveIcon overrides the Action method to test for the presence of a lock on the archive, and to play a sound. Class MessageIcon overrides Action to send a tap to the default stationery indexical, and doesn't zoom anywhere at all!
Stamp_Draw overrides Draw() Call: rarely Override: sometimes
Override Draw if your subclass of Icon needs to draw itself in an unusual way. Class Icon doesn't override Draw itself, but you might need to when you subclass. Here are some examples of how existing subclasses of Icon override this method:
Class MessageIcon overrides Draw because it draws the default stationery instead of a canned image. If the default stationery changes, the message icon should also change. So MessageIcon_Draw checks the indexical iDefaultStationery before drawing.
Class DatebookIcon also overrides Draw, to display the year in addition to the image of a date book.
Icon_PutAway overrides PutAway() Call: rarely Override: sometimes
Call PutAway to return an icon to its default place in the system. The PutAway method returns the icon to its native container and position if the icon has moved. If the icon's native container is on screen, the icon performs a graceful fancy hop to its native position.
Icon_Swallow overrides Swallow(morsel: Object; where: Dot; realSwallow: Boolean): Boolean Call: rarely Override: sometimes
Override Swallow if your icon is linked to a destination that needs to process some morsels as it swallows them, or if morsels fed to an icon should be fed to the icon's destination instead.
Often by dropping an morsel onto an icon, users mean to drop the morsel into its destination. (It's that close mental association between the icon and its destination again.) If this is true for your particular kind of icon, you will want to override Swallow. For example, the notebook icon's override of Swallow sends most morsels off to the notebook itself to be swallowed, unless the option key is down. If the option key is down, the icon tries to swallow the morsel itself.
Here's a code fragment that shows how you might do this:
ObjectID destination = Destination(self);
/* if the option key is down, try feeding the morsel
to the icon itself */
if (OptionKey())
return InheritedSwallow(self, morsel, where,
realSwallow);
/* otherwise, pass the Swallow call along to the icon's
destination */
return Swallow(destination, morsel, where, realSwallow);
Class DatebookIcon overrides Swallow for a slightly different reason. The date book icon handles TaskProxy morsels by adding them to the task list. In this case, the icon itself does the processing, and the icon's destination doesn't need to.
Class ContainerIcon overrides Swallow for yet another reason. This kind of icon adjusts its image if necessary, for that "bulging" full container look.
Stamp_Tap overrides Tap() Call: rarely Override: sometimes
Override Tap to do any special processing required before the system calls the icon's Action method. Some destinations aren't useful until the user has performed some setup action first, such as filling out a name card or signing up for a service. Icons that zoom to these destinations should override Tap to check that the user has met any necessary preconditions. If you override, make sure you remember to call the InheritedTap method from your new method.