Windows
Book Contents Previous Chapter Next Chapter
This chapter describes windows, boxes that cover part of the screen and contain other viewables. Before reading this chapter, you should be familiar with Magic Cap viewables and scenes.
Windows provide a way to present a set of viewables containing information about the current scene or user action without having to leave the scene. Some windows are used to convey a simple message, such as a low battery warning or helpful text about how to use features in the current scene, while other windows present a set of choices and actions, such as the window that lets the user set and change rules.
Windows
Magic Cap provides some windows you might use that perform common functions, such as a window for selecting an entry from the name cards file. Other Magic Cap windows, such as the ones used for displaying information about problems, allow you to show your package's text and viewables in the same formats used by the built-in packages. If you create your own windows, you'll probably do so by declaring them in your instance definition file. You probably won't ever create a window at runtime.
You can make windows appear on the screen when appropriate, using your own windows or windows supplied by Magic Cap. Windows appear in front of all other viewables on the screen.
Magic Cap tries to avoid having many windows open on the screen at once, because of the clutter and confusion that results when the small communicator screen is covered by overlapping windows. To help implement this strategy, many windows close other windows before they appear themselves. Most windows close automatically if the user switches scenes.
Information windows appear when the user touches a circled question mark and display helpful information.
Titled windows have a bar across their tops, which makes them appear more prominent and allows them to have a circled question mark and associated information window. Some of these titled windows are designed to appear and disappear when the user touches a gadget, a small viewable associated with the window. These gadget windows point to their gadgets to remind the user how they were opened and how to close them. Content windows can add and remove subviews dynamically and can display their subviews in neat rows and columns.
Each scene can have helpful information displayed in an information window that appears when the user touches the circled question mark on the name bar. Some other objects, such as titled windows, can have information windows also.
When your package must display important or ongoing information to the user, you can show announcements in public address windows. Magic Cap provides a variety of features in these announcements, including the ability to handle situations when more than one announcement must be conveyed to the user at the same time.
Some Magic Cap user actions cause information to be lost, such as emptying the trash. By displaying a confirmation dialog, a window that asks the user to confirm the action, Magic Cap provides a way for packages to double-check with the user before carrying out the requested operation. Advanced users can flip a control panel switch that prevents most of these windows from appearing.
Windows and announcements each have flags that you can use to set up specialized behavior. Magic Cap also defines various indexicals for built-in windows and announcements, and several items in the package root list provide window-related features.
Class Window defines a set of basic features for supporting windows. You probably won't ever create any objects of class Window. Instead, you'll create windows using one of the window subclasses provided by Magic Cap, or by making your own window subclass.
Call Show to open any window and display it on the screen, or Hide to close any window and remove it from the screen. You can also call ShowOrHide, which calls Show if the window is not on the screen or Hide if the window is on the screen.
When you call Show to open the window, Show calls the window's Appear operation to handle the details of making the window appear on the screen, such as closing other windows if appropriate before opening the new one and actually installing the window in the screen view hierarchy. You can override Appear to perform some custom action when your windows are opened on the screen. For example, the command window that appears when the user opens the Magic Lamp overrides Appear to install the scene's own commands before opening the window.
After calling Appear and just before the window is actually added to the screen view chain, Magic Cap calls its AboutToShow operation.
When windows open on the screen, they are not installed as subviews in the scene. Instead, windows are always subviews of the screen itself. This allows windows to "float" above the scene and its viewables, making windows always appear in front of the scene.
When you call Hide to close the window, Hide calls the window's Disappear operation to handle the details of making the window vanish from the screen, such as closing its associated information window and actually removing the window from the screen view hierarchy. You can override Disappear to perform some custom action when your windows are closed on the screen. For example, the window containing the on-screen keyboard overrides Disappear to restore the current tool to its previous setting.
After calling Disappear and just before the window is actually removed from the screen view chain, Magic Cap calls its AboutToHide operation.
When you open or close a window, Magic Cap can provide a zooming effect like the one sometimes used when going to a new scene. Class Window provides the ZoomFromWhere operation to enable zooming for windows. To make windows of your subclass zoom open and closed, override ZoomFromWhere to return the appropriate location for zooming the window.
When the user opens a window, the new window can force other open windows on the screen to close. You can control this features with the canCoexist flag in the windowFlags field. When the new window is about to open, Magic Cap calls CanCoexist to check the window's canCoexist flag. If the new window returns false, Magic Cap then closes any other windows that also have this flag cleared. Most windows set canCoexist to false, indicating that they will be closed when another such window opens.
Windows with their canCoexist flag set do not force other windows closed when they open and are not closed when other windows open. For example, the tools window sets its canCoexist flag so that users can choose a tool even while another window is open. You can set your window's canCoexist flag when you declare it in the instance definition file.
Every window can have one or more dependent windows. When a window closes, all its dependent windows must close. For example, windows that require typed text entry often designate the keyboard window as a dependent. When the user closes the text entry window, the keyboard window closes also. Windows define the HasDependent operation to determine if a particular window is a dependent of another. The dependent window feature is dormant in class Window. The TitledWindow subclass supports dependent windows by overriding HasDependent and declaring a dependents field.
Note that closing a window also closes its information window. However, this feature isn't handled by making the information window a dependent. Instead, the window's Disappear operation explicitly closes the information window before closing itself.
When the user switches to another scene, Magic Cap usually closes any open windows automatically. This is appropriate for most situations, because windows usually present information that is only useful while in the current scene. The user switches scenes to indicate interest in some new area. When the user switches scenes, Magic Cap decides whether to close a window by calling its PersistentWindow operation. If PersistentWindow returns false, Magic Cap closes the window. Otherwise, Magic Cap leaves the window open.
PersistentWindow works by returning the state of the window's persistentWindow flag in the windowFlags field. You can control whether your window stays open across scene changes by setting this flag appropriately in your instance definition file. Usually, you'll leave this flag cleared so that your window will close when the user goes to a new scene.
You can place a viewable inside a window by calling the AcceptMorsel operation. When you call AcceptMorsel, the viewable is added to the window at the window's default position for new subviews.
Magic Cap defines class TitledWindow as a concrete subclass of window. Titled windows have a title bar, a strip across the top of the window that displays the window's name. Most titled windows also have a circled question mark that opens an information window when touched, and a boxed X that closes the window when touched.
Titled window
Every titled window can have a list of dependent windows. When the titled window closes, the dependent windows are closed, too.
Every titled window (and every scene) can display a associated window containing helpful information. If the titled window has an associated information window, Magic Cap draws a circled question mark at the left edge of the window's title bar. The user can touch there to display the information window. See the Information Windows section in this chapter for more information.
Titled windows specify their information windows by listing them in the package root list. For more information on items in the root list, see the Software Packages chapter of this book.
Most titled windows have a close box at the right edge of their title bars. Occasionally, you may want to create a titled window that has no close box. Magic Cap decides whether to put a close box in the window's title bar by checking the window's HasCloseBox attribute. If HasCloseBox returns true, Magic Cap includes a close box in the window's title bar. Otherwise, the title bar has no close box.
HasCloseBox works by inverting the state of the window's noCloseBox flag. You can control whether your titled window has a close box by setting this flag appropriately in your instance definition file: setting the flag indicates that your window should not have a close box, while clearing the flag makes Magic Cap include a close box in the title bar.
Operation TitleBox returns a pair of values that give the height and width of the window's title bar.
When the user touches one of the viewables in Magic Cap's control bar at the bottom of the screen (other than the desk button), a window appears that is associated with the touched viewable. For example, touching the trash at the lower-right corner of the screen opens the trash window. These viewables are called gadgets, and the windows connected to them are called gadget windows.
Gadget window on screen
The gadget is the target of the window, and the window is the target of the gadget. You can get or set the window's target by using its Target attribute. If the user touches a gadget when its window is already open, the window closes.
You can use any viewable, not just a gadget, as the target of a gadget window. For example, the datebook uses a gadget window to let the user select the location for a meeting. When the user touches the where button, a gadget window opens showing a list of meeting locations. The where button is the target of the window. Because buttons have no target, the where button has a Magic Script that calls ShowOrHide on the gadget window.
When a gadget's window is open, Magic Cap draws a cartoon tail called a spout pointing from the window to the gadget that spawned it. If the window is too close to the gadget, or the gadget isn't on the screen, Magic Cap doesn't draw the spout.
Some gadget windows have contents that never change, or only change indirectly in response to events such as scene changes. For example, the first two rows of the commands window never change, and Magic Cap changes the bottom row by filling in rules and commands for the current scene.
Other gadget windows are more dynamic and have contents that can be changed directly by the user adding and removing viewables. Magic Cap defines class ContainerWindow for these windows. For example, the tote bag's window is a container window. The user controls the contents of the tote bag directly by sliding viewables in and out of the tote bag or its window. The datebook's Choose an appointment type window, another container window, allows the user to add new kinds of appointments.
Container window on the screen
When the user drops a viewable into a container window, the newly added viewable is placed in the window along a grid supplied by the window. You can specify the size of each position in the grid and the location where the grid begins in the window's gridSize and gridOffset fields, respectively. You can also avoid using the grid entirely by setting the ignoreGrid flag in the windowFlags field.
Any object in Magic Cap can have an information window associated with it. Information windows, implemented by class InfoWindow, provide text, images, and other objects that explain the features of their associated object.
Information windows for a scene and for a titled window
Objects that have an information window must provide a way for users to display that window. Although in principle every object can have an information window, in practice only viewable objects with a title bar, such as scenes and titled windows, have information windows.
If the scene or titled window has an associated information window, Magic Cap draws a circled question mark at the left edge of the window's title bar. The user can touch there to display the information window.
To create an information window for your titled window or scene, you'll declare in your instance definition file the objects to appear inside the information window. You'll use the package root list to set up the association between the information window and its scene or titled window.
For system objects, Magic Cap implements the relationship between objects and their information windows by creating two parallel object lists, iDefinedObjects and iObjectDefinitions. For package objects, Magic Cap maintains a similar pair of object lists that you declare in your instance definition file. See the Window Information in the Package Root List section in this chapter for more information.
You probably won't ever create an information window at runtime, nor are you likely to call any operations of class InfoWindow.
Magic Cap uses public address windows to provide important announcements to users. Public address windows display warnings about hardware problems such as low battery levels, reminders for datebook tasks, status of ongoing operations such as mail collection, and other similar purposes. You can use public address windows to display important or unexpected information to the user. Public address windows are implemented by objects of class PublicAddress, a subclass of InfoWindow.
Public address windows
Every public address window has an announcement, a object containing text to be displayed in the public address window, a sound to be played when the window appears, and other information. When you display announcements in public address windows, you'll probably declare objects of class Announcement in your instance definition files, then call operations of that class to display the announcements in system-defined public address windows. You probably won't call operations of class PublicAddress.
In addition to the announcement, public address windows can display any other viewable objects. These viewables are simply subviews of the window.
Some announcements are designed to vanish as soon as the user touches their public address window's close box, while others can be closed and reopened when needed. Announcements that can be closed and reopened are used for ongoing information such as the status of a telephone call or a mail session.
Announcements that are active but closed are represented by tiny images called announcement stamps. These stamps are drawn inside a small viewable container on the name bar called the carousel. Magic Cap draws an announcement stamp in the carousel for each active, hidden announcement. If there are two or more hidden announcements, Magic Cap draws the announcement stamps in the carousel in turn, displaying each one for a few moments before replacing it with the next.
When the user touches the carousel, the hidden announcement is displayed in its public address window. If more than one announcement is hidden when the user touches the carousel, Magic Cap displays a window titled Announcements that contains a list showing the stamps and names of all hidden announcements. The user can then touch any item in the list to see the public address window with the corresponding announcement.
List of announcements in the carousel
Public address windows that display ongoing information and can be hidden have spouts pointing to the carousel, reminding the user to touch the carousel to hide the window.
When an announcement is about to be displayed, Magic Cap installs the announcement in its public address window, then displays the window with its announcement. This allows more than one simultaneous announcement to share the same public address window. Magic Cap chooses the public address window that is appropriate for the announcement, as described in this chapter's Using Public Address Windows and Announcements section.
Magic Cap always displays only one public address window at a time, except that it can display one status announcement along with one non-status announcement at the same time. Other simultaneous public address announcements are represented by their announcement stamps in the carousel.
When you want to use announcements in public address windows, you'll usually do so by declaring an announcement object in your instance definition file, then calling operations on the announcement. To display an announcement just as it is declared in your instance definition file, call Announce.
Every announcement refers to a text object that is displayed when the announcement appears. You can get and set the announcement's text object by using its Info attribute. Similarly, you can get and set the stamp that represents the announcement in the carousel by using its Stamp attribute. Magic Cap uses the PublicAddress attribute to set the public address window used to display the announcement. You can use the PublicAddress attribute to get the announcement's window.
To change the text displayed by an announcement, call ReplaceTextData. You can perform other actions on the announcement's text by using the standard text operations defined by class TextContainer, from which announcements inherit. Most announcements go away when the user closes them. If you want to remove an announcement from the screen directly, call Retract.
You can use the DestroyOnRetract attribute to determine whether the announcement object should be destroyed automatically when it is removed. This is useful for announcements that are only used once, such as temporary copies of announcements.
Announcements provide attributes that let you get and set several common announcement flags. If the DisplayOnce attribute is false, the announcement will place its stamp in the carousel when the user closes its window.
When you display a very important announcement, you can use the Urgent attribute to ensure that the announcement is displayed immediately rather than placed in the carousel if another announcement is being displayed. In this case, the existing announcement is placed in the carousel. In addition, urgent announcements stay open when the user moves to another scene, while non-urgent announcements close automatically when the scene changes.
You can use the HasCloseBox attribute to get and set whether the announcement's public address window has a close box. If your announcement shows the progress of some action that can't be interrupted, you may want to set this attribute to false.
You can call AnnounceQuietly on the rare occasions when you want to place the announcement's stamp in the carousel without displaying the announcement first.
Magic Cap provides several common public address windows that you can refer to with indexicals, including one for general warnings (iSystemWarnings), one for general announcements (iSystemAnnouncements), one for modal progress announcements (iStatusAnnouncements), and others. You will probably use these supplied public address windows rather than creating your own. If you do make your own, you'll probably declare them in your instance definition file rather than creating them at runtime.
Some of the standard public address windows supplied by Magic Cap already include subviews, such as the blinking exclamation point and progress graph in the iStatusAnnouncements window.
The first subview of every public address window must be a text field used to hold the text of the announcement when the window is displayed. If you create your own announcements, be sure to follow this rule.
When the user is about to perform some destructive, lengthy, or irreversible action, such as throwing away a card or personalizing the communicator, your package can ask the user to verify the action by presenting a small window with buttons that confirm or cancel the action. These windows are called confirmation dialogs and are represented by objects of class ConfirmationDialog.
Confirmation dialogs
You probably won't ever make your own confirmation dialogs, either by declaring them in instance definition files or by creating them at runtime. Instead, you'll probably use the standard confirmation dialog supplied by Magic Cap, customizing it by passing parameters to the operations that use it.
Every confirmation dialog contains two buttons. The user can touch one of the buttons to proceed with the proposed action. This button is called the yes button, although it may actually have a label other than yes. Touching the other button cancels the proposed action. This is the no button. The confirmation dialog refers to a target object and operation. If the user touches the yes button, the operation is performed on the target object. If the user touches the no button, no operation is performed on the target, and the confirmation dialog closes.
Confirmation dialogs contain text informing the user of the proposed action and an image that suggests the proposed action. You can also specify a sound to be played if the user touches the yes button to confirm the proposed action.
You can use a confirmation dialog for a proposed action by calling PerformWithConfirmation. When you call PerformWithConfirmation, you specify the confirmation dialog, the text and image to show in the window, the sound to be played if the user touches the yes button, and the target object and proposed operation.
Magic Cap provides a standard confirmation dialog containing yes and no buttons and a jagged border. You can refer to this window with indexical iConfirmationWindow when you call PerformWithConfirmation. The text and image you specify will be drawn inside the confirmation dialog when you call.
If the user touches the yes button supplied by iConfirmationWindow, Magic Cap calls the confirmation dialog's Confirm operation, which closes the confirmation dialog and then calls the specified operation on the target object. If the user touches the no button, Magic Cap simply hides the confirmation dialog. You can provide your own confirmation dialog for the rare cases in which you want to have buttons that call other operations.
When you call PerformWithConfirmation, Magic Cap checks the current confirmation mode, which the user sets with the more warnings switch in the General control panel. If more warnings is on, PerformWithConfirmation displays the confirmation dialog. If more warnings is off, PerformWithConfirmation simply performs the proposed operation without displaying the confirmation dialog.
PerformWithConfirmation also checks the state of the option key when it is called. If the option key is down when PerformWithConfirmation is called, it simply performs the operation on the target object without displaying the confirmation dialog, regardless of the confirmation mode.
When you call PeformWithConfirmation, you can set a parameter that forces the confirmation dialog to appear, ignoring the setting of more warnings and the state of the option key. You should force the user to confirm an action under the following circumstances:
If you want to customize the appearance and behavior of the confirmation dialog, you can call PerformWithConfirmationFancy. Fancy confirmation lets you customize standard confirmation dialogs in two ways:
Fancy confirmation lets you specify different labels for the yes and no buttons while still using the standard confirmation dialog, iConfirmationWindow. No matter what labels you specify, the buttons still have the same roles: the yes button performs the proposed operation, and the no button simply closes the confirmation dialog.
When you use standard confirmation by calling PerformWithConfirmation, your confirmation dialog's proposed operation must be one that takes no parameters. If you use fancy confirmation, the proposed operation can be one that takes exactly one parameter, which must be 32 bits long. When you call PerformWithConfirmationFancy, you can specify the parameter to be passed to the operation.
You can delete the current card by calling DeleteCurrentCardWithConfirmation, which calls PerformWithConfirmation with a confirmation dialog that asks the user to confirm throwing away the current card.
Every confirmation dialog is associated with a proposed operation. You can get the number of the proposed operation from the confirmation dialog's Number attribute.
As described in the Viewables and Touching chapter, viewables can act as tools, which gives viewables the ultimate ability to control what happens when the user touches the viewable. Windows sometimes take advantage of this feature. For example, information windows act as tools when touched, using this ability to close themselves when the user touches anywhere inside them. For more information, see the Viewables as Tools section of the Viewables and Touching chapter of this book.
You probably won't ever create any objects of class Window, although it is a concrete class. Instead, you'll probably create objects of window subclasses, such as TitledWindow, ContainerWindow, and others. No matter which window classes you use, you're likely to declare the windows in your instance definition file rather than creating the windows at runtime.
When you declare windows in your instance definition files, set the next, previous, and superview fields to nilObject. Magic Cap will set them appropriately when the window appears on the screen. The subview field should refer to a view list contained by the window or to nilObject.
When the window opens, Magic Cap uses the window's relativeOrigin field to place it in its superview, which is the screen. Titled windows use their labelStyle field to provide the style for their title, and the titleHeight field indicates the vertical size of the title bar. Most titled windows use a label style of iBook12Bold and a title height of 28 pixels. You can use a title height of 0 if you want your window to be drawn without a title bar. When declaring a titled window, the dependents field refers to an object list containing windows that will be closed when the window itself closes.
Gadget windows have a balloonDot field that is used when drawing the cartoon tail that points from the window to the gadget. You should set this field to <0.0,0.0> in your window definitions. Magic Cap will set it appropriately when the window is drawn. The target field refers to the window's target, the object that the user can touch to open and close the window. If the target is a gadget, the gadget's target field should refer to the gadget window.
When you declare a container window, the gridSize field specifies the dimensions of one slot in the grid. The first item in the window is placed at the location specified in the gridOffset field, and additional items are added across, filling the row, then down to the next row. If your container window includes scroll arrows, you should refer to them in the topArrow and bottomArrow fields. They should also be installed as subviews of the window.
Class Window defines various flags you can use to customize the appearance and behavior of its members. You'll use these flags primarily when you declare windows in instance definition files. A few of the flags are commonly tested at runtime and are available via operations, while others must be examined directly in the window object's windowFlags field. Most flags are tested only by Magic Cap itself to provide various system features. You can set them when you declare windows in your instance definition file, but you probably won't test them yourself.
Window flags indicate whether your window should allow other windows to remain open alongside it (the canCoexist flag), whether your window should stay open when the user changes scenes (persistentWindow), and other settings. For complete information on window flags, see the Window chapter of Magic Cap Class and Method Reference and the Utilities.h file.
Class Announcement defines several flags that you can use to customize the appearance and behavior of announcements in public address windows. You'll use these flags primarily when you declare announcements in instance definition files. Some of the flags are commonly set or tested at runtime and are accessible via attributes, while others must be examined directly in the announcement object's flags field. Most flags used by packages are available via attributes. You'll rarely test or set announcement flags directly at runtime.
Announcement flags control various features, including whether the announcement should vanish when closed or join the carousel of announcements (the announcementDisplayOnce flag), whether your announcement is displayed immediately (announcementUrgent), whether the announcement's window has a close box (announcementNoCloseBox), whether the announcement object will be destroyed automatically when retracted (announcementDestroyOnRetract), and other settings. For complete information on announcement flags, see the Announcement chapter of Magic Cap Class and Method Reference and the Utilities.h file.
Magic Cap provides indexicals that contain useful windows. Indexical iWindowList contains many of Magic Cap's built-in windows, such as the list of people and companies that appears when the user addresses a message (iPeoplePicker), the window that displays the tote bag's contents (iToteBagWindow), the desk accessory window that springs from the drawer on the right side of the desk (iDeskAccessoryWindow), and many others. You can call the ShowOrHide operation with an indexical from iWindowList to make the window appear or vanish.
Magic Cap provides indexicals for many standard system announcements. You're not likely to use these unless you want an announcement that is identical to one used by Magic Cap. Announcement indexicals are available in iAnnouncementList.
Several status announcements are available as indexicals, including those displayed when sending messages (iSendProgress), checking for new messages (iCollectProgress), actually receiving messages (iReceiveProgress), and sending a fax (iFaxProgress).
You can determine which announcement is being displayed by reading indexical iCurrentAnnouncement. The current status announcement is available in iCurrentStatusAnnouncement.
See the Indexicals.h file for more information about indexicals.
Magic Cap provides the people picker window to allow users to choose a name from the name card file without having to leave the current scene. For example, when the user creates and addresses a new telecard, Magic Cap shows the people picker to let the user choose the telecard's recipients.
For more information on using the people picker, see Using the People Picker Window in this book's Name Cards chapter.
The package root list includes some windows and items related to windows. Item 9 in the package root list (iPackageObjectsWithHelp) is an object list of scenes and titled windows that have information windows associated with them. Item 10 (iPackageHelpOnObjects) is an object list of items to be placed in the information windows for the objects in item 9.
For complete information on items in the root list, see the Software Packages chapter of this book.
Magic Cap defines many subclasses of Window in addition to those already discussed. You might use a few of these in your packages. Objects of class AttributeWindow are used for entering information according to a series of editing steps, as when entering the name for a new name card.
For more information, see these topics in Magic Cap Class and Method Reference:
class Window
operations and attributes:
AcceptMorsel Appear CanCoexist Disappear HasDependent Hide PersistentWindow Show ShowOrHide ZoomFromWhere
fields:
next previous relativeOrigin subview superview windowFlags
flags:
canCoexist ignoreGrid noCloseBox persistentWindow
class TitledWindow
operations and attributes:
HasCloseBox TitleBox
fields:
dependents labelStyle titleHeight
class GadgetWindow
operations and attributes:
Target
fields:
balloonDot target
class ContainerWindow
fields:
bottomArrow gridOffset gridSize topArrow
class InfoWindow
class PublicAddress
class Announcement
operations and attributes:
Announce AnnounceQuietly DestroyOnRetract DisplayOnce HasCloseBox Info ReplaceTextData Retract Stamp Urgent
fields:
flags
flags:
announcementDestroyOnRetract announcementDisplayOnce announcementNoCloseBox announcementUrgent
class ConfirmationDialog
operations and attributes:
Confirm DeleteCurrentCardWithConfirmation Number PerformWithConfirmation PerformWithConfirmationFancy
class PeopleListTarget
operations and attributes:
SetEntity
indexicals:
iAnnouncementList iCollectProgress iConfirmationWindow iCurrentAnnouncement iCurrentStatusAnnouncement iDefinedObjects iDeskAccessoryWindow iFaxProgress iObjectDefinitions iPackageHelpOnObjects iPackageObjectsWithHelp iPeoplePicker iReceiveProgress iSendProgress iStatusAnnouncements iSystemAnnouncements iSystemWarnings iToteBagWindow iWindowList
Book Contents Previous Chapter Next Chapter