Inherits from Object, TextContainer
Announcements present the user with important information. They're presented in public address windows which appear in front of the current scene. Use announcements to explain errors or give feedback on the progress of long tasks.
Class Announcement has two useful subclasses: TargetedAnnouncement and StatusAnnouncement. Class StatusAnnouncement provides you with a convenient way of displaying the progress of long tasks. Class TargetedAnnouncement allows announcements to monitor target objects.
Every announcement is displayed by a public address window. See the chapter on class PublicAddress for information on creating public addresses.
In real life, announcements are made over public address systems. In the world of Magic Cap, announcements are displayed in public address windows.
Since announcements usually display important information, they're displayed in windows that cover up other items on the screen. Most announcements disappear when the user closes or taps on them. Other announcements display information about work in progress, and remain until the work is completed. You can hide these announcements by tapping on their public address windows.
Public address windows often spout from a particular spot in the name bar. This spot is called the carousel. The carousel displays an announcement stamp that cycles through the images of the various pending announcements.
If you've hidden an announcement, you can tap the announcement's stamp in the name bar to redisplay it. If the system is making more than one announcement at a time, tapping the stamp will display the list of announcements. The following figure shows the list view that displays all the items in the carousel.
To display any announcement in the carousel, just tap its entry in the list view.
Instantiate: often Subclass: rarely Call its methods: always
To create an announcement object, you need these pieces:
The two public addresses you're likely to use most often are iSystemWarnings and iSystemAnnouncements. The system defines a few others. For a complete list and some sample illustrations, see the chapter on class PublicAddress.
You will call the methods of class Announcement often, to make and retract announcements. To make an announcement, call the Announce method or its variation, AnnounceQuietly. To take an announcement back, call Retract. You might not need to call Retract for every announcement you make. Most announcements are displayed only once, and are retracted automatically when the user dismisses them.
Class Announcement defines the following methods:
| Method | Description |
|---|---|
| Abort | Do something when the user taps the stop button |
| Announce | Display the announcement |
| AnnounceQuietly | Install in carousel, but don't present the announcement window |
| OnScreen | Return true if the announcement is on the screen |
| Present | Display an already-announced announcement |
| Retract | Remove a displayed announcement |
| RetractWithoutHiding | Retract an announcement without automatically hiding the window that's displayed |
Class Announcement defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| Info | Object | Text of the announcement; corresponds to info field |
| Stamp | Viewable | The stamp to install in the name bar; corresponds to stamp field |
| PublicAddress | Object | Which public address to use for the announcement; corresponds to publicaddress field |
| DestroyOnRetract | Boolean | True if the announcement should be destroyed when retracted |
| DisplayOnce | Boolean | True if the announcement should be displayed only once |
| KeepFrontmost | Boolean | True if the announcement should be displayed in front of all other windows (even the calibration window) |
| Urgent | Boolean | True if the announcement is urgent |
| NoTopic | Boolean | True if the announcement has no topic |
| HasCloseBox | Boolean | True if the announcement has a close box |
Each of these attributes has getter and setter methods. Each of the Boolean attributes corresponds to an announcement flag. See the section on flags for detailed descriptions.
Class Announcement defines the following fields:
| Field | Type | Description |
|---|---|---|
| Defined by Announcement | ||
| global bootlist | DataList | List of announcements retracted or announced at boot |
| Flags | Flags | Announcement flags |
| info | HasText | Text of the announcement |
| stamp | Viewable | The small stamp displayed in the name bar |
| sound | Sound | Sound played when the announcement is made |
| publicAddress | Object | The public address to use for the announcement |
The stamp field should contain an announcement stamp. Make sure the announcement stamp points back to the public address the announcement is using. If it doesn't, the announcement might not display properly. (If you want to use an announcement stamp for several similar announcements, make sure you correctly set its announcement and publicAddress fields before each use.)
To use the default announcement stamp, iPrototypeAnnouncementStamp, put nilObject into the stamp field.
Here's the instance definition for the announcement shown at the beginning of this chapter:
Instance Announcement 284;
flags: 0x00000083;
info: (Text 704);
stamp: (AnnouncementStamp 'Backup is low' 7856);
sound: nilObject;
publicAddress: iSystemWarnings;
End Instance;
Instance Text 704;
info: 'The backup battery is almost dead. ' \
'The battery must be replaced for the ' \
'communicator to maintain information. ' \
'Leave the main battery in place until ' \
'you've replaced the backup ' \
'or you will lose information.';
End Instance;
Instance AnnouncementStamp 'Backup is low' 7856;
next: nilObject;
previous: nilObject;
superview: nilObject;
subview: nilObject;
relativeOrigin: <0.0,0.0>;
contentSize: <0.0,0.0>;
viewFlags: 0x10081000;
labelStyle: iSign8;
color: -1;
altColor: 0xFF000000;
shadow: nilObject;
sound: nilObject;
image: {6,26};
announcement: (Announcement 284);
publicAddress: iSystemWarnings;
End Instance;
This announcement is an error, it's urgent, and it is displayed once. It uses the standard system warnings public address and installs a custom stamp in the name bar.
#define announcementDisplayOnceBit0 #define announcementDisplayOnceMask0x00000001
Set this flag if your announcement need only be displayed once. Announcements that aren't displayed just once stay in the carousel until they're retracted. The user can't make these announcements go away by closing them.
This flag is used by the DisplayOnce attribute getter and setter.
#define announcementUrgentBit1 #define announcementUrgentMask0x00000002
Set this flag if your announcement is urgent. Urgent announcements are displayed immediately; announcements that aren't urgent join the carousel behind any more important announcements. Urgent announcements also stay on the screen when the user changes scenes. (Normal announcements are hidden when the scene changes.) Announcements are urgent if they might require the user to take immediate action. For example, most announcements about battery power should be urgent.
This flag is used by the Urgent attribute getter and setter.
#define announcementNoTopicBit2 #define announcementNoTopicMask0x00000004
This flag is used by the NoTopic attribute getter and setter, but not, it seems, by any other methods. Since it has no effect, you probably shouldn't bother using it.
#define announcementNoStampBit3 #define announcementNoStampMask0x00000008
The system sets this flag for announcements that don't have a custom stamp to display in the name bar. The system instead uses iPrototypeAnnouncementStamp. That stamp looks like this:
You shouldn't set this flag yourself.
#define announcementDestroyOnRetractBit4 #define announcementDestroyOnRetractMask0x00000010
Set this flag if your announcement object should be destroyed when it's retracted. This flag is used by the DestroyOnRetract attribute getter and setter. You could use this flag to copy an existing announcement that's almost what you want, change your copy in some way, then have the copy automatically destroyed when it's retracted.
#define announcementMapTextBit5 #define announcementMapTextMask0x00000020
Set this flag if your announcement has text that should be mapped before it's displayed.
Here's an example of an announcement that maps its info text:
Instance Announcement 40;
flags: 0x00000020;
info: (Text 41);
stamp: (AnnouncementStamp 42);
sound: nilObject;
publicAddress: iSystemAnnouncements;
End Instance;
Instance Text 43;
info: 'Copying package /current context/.';
End Instance;
When the system displays this announcement, it replaces the string "/current context/" with the name of the current context.
For more information on text mappings, see class MapText.
#define announcementNoCloseBoxBit6 #define announcementNoCloseBoxMask0x00000040
Set this flag if your announcement should not have a close box. You should only set this flag if you need to inform your user that Magic Cap is currently engaged in some uninterruptible task. Some system tasks that are uninterruptible are restoring from a backup and setting the current user.
For example, any announcement that uses the public address iStatusAnnouncements won't have a close box. The iStatusAnnouncements window places an animation of a blinking exclamation mark in the place where a close box would be.
This flag is used by the HasCloseBox attribute getter and setter. The attribute has the opposite value of the flag.
#define announcementIsErrorBit7 #define announcementIsErrorMask0x00000080
Set this flag if your announcement describes an error condition. If your announcement is an error and has no name of its own, the system names it "error." Otherwise, the system names it "info."
#define announcementPresentedBit8 #define announcementPresentedMask0x00000100
The system sets this flag when an announcement is displayed to the user. This flag is set by the Present method, and cleared when the announcement is retracted. You shouldn't set it yourself.
#define announcementMustBeFrontmostBit9 #define announcementMustBeFrontmostMask0x00000200
Set this flag if your announcement should always be displayed in front of other viewable objects. This flag is used by the KeepFrontMost attribute getter and setter. You should set this flag only for those rare announcements that are so important they must appear over the calibration screen.
operation Announce(), noFail, safe, common Call: often Override: rarely
Call Announce to make an announcement; that is, to display an announcement in a public address window.
Here's an example from Viewable_DroppedFromWindow, showing how you might display an announcement telling the user that a card is locked:
if (card == nilObject || !Locked(card)) return; Announce(iCardIsLocked); HopToTrash(self);
operation AnnounceQuietly(), noFail Call: sometimes Override: rarely
Call AnnounceQuietly to install an announcement in the carousel without presenting its window to the user.
operation Present(), noFail Call: rarely Override: rarely
Call Present to display an already-made announcement. This method is used by the underpinnings of class Announcement, and you probably won't use it often (if at all).
operation Retract(), noFail, safe Call: often Override: rarely
Call Retract to take back an announcement, removing it from the carousel and hiding its window.
operation RetractWithoutHiding(), noFail, safe Call: rarely Override: rarely
Call RetractWithoutHiding to take back an announcement and remove it from the carousel, without hiding its window. The announcement disappears when the user taps its close box. The underpinnings of class Announcement use this method, but you probably won't need to use it yourself.
operation ReplaceTextData(), noFail, safe Call: sometimes Override: rarely
Call ReplaceTextData to change the text of an announcement.
ReplaceTextData does two things. First, it calls its inherited method, thus changing the text stored by the announcement object. Then it passes along the replace text call to the announcement's public address, if the announcement is the current announcement. It does so by calling ReplaceText on the public address. PublicAddress_ReplaceText won't replace the text in the window of an announcement that's made but not currently displayed. If you need to do this, override the ReplaceText method. Or you could retract the announcement, update its text, then announce again. See PublicAddress_ReplaceText for more information on how to override if that's the solution you choose.
operation Abort(), noFail Call: rarely Override: sometimes
The system calls Abort when the user taps a stop button. Some subclasses of class Announcements are displayed by public address windows with stop buttons.
Announcement_Abort retracts the announcement. Specialized subclasses of Announcement might override Abort to interrupt tasks in progress. See class StatusAnnouncement for an example.