May 8, 1995 Inherits from Box Inherits from Tool
Windows float on top of scenes. They usually don't fill the screen. They're temporary, some vanishing when their informational job is done and some vanishing when the user dismisses them. Since they cover up part of the screen, they are often moveable. Magic Cap has many kinds of windows. Some have title bars, some have borders, and some have balloon spouts. You'll probably use several of the various window kinds in your packages.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
Here are some of the window classes you're likely to use often:
| Window class | Description |
|---|---|
| ConfirmationDialog | A window with a framework for letting you ask users yes/no questions |
| ContainerWindow | A window that aligns its contents to a grid |
| AttributeWindow | A window that displays attribute steps |
| GadgetWindow | A window that spouts from another viewable, usually a an object of class Gadget. |
| InfoWindow | A window that displays help for an object or a scene. |
| ListWindow | A window that is tailored to display lists |
| TitledWindow | A window with a bar on top that displays its name |
This isn't a complete list of window classes, since Magic Cap defines nearly 50 subclasses of class Window. Some of those are tailored for very specific purposes, but others are general enough to be useful for you.
Instantiate: never Subclass: sometimes Call its methods: sometimes
You'll never use an object of class Window. Instead, you'll often use objects of Window's many subclasses. Class Window does define a large set of flags which you can use to control the behavior of many windows, and it also overrides many methods that give windows their basic character.
Class Window defines the following methods:
| Method | Description |
|---|---|
| AcceptMorsel | Make morsel a subview of self, and put it in default position |
| DropACopy | Drop a copy of source viewable onto card (or scene if none) |
| Showing and hiding | |
| PersistentWindow | Called by system to determine whether self should remain shown when scene changes |
| Show | Show window if it's hidden, zooming up if necessary |
| Hide | Hide window if it's shown |
| ShowOrHide | Show if hidden or hide if shown |
| Appear | Called by Show to make the window visible on the screen |
| Clear | Clear the window; does nothing to standard windows |
| Disappear | Called by Hide to remove the window from the screen |
| ZoomFromWhere | Check if window should zoom open and closed in Show and Hide, and check where to zoom from and to |
| CanCoexist | Check if this window can co-exist on the screen with other open windows |
| HasDependent | Check whether candidate should be closed when self is closed, and whether opening candidate should keep self open |
| Coexisting with the keyboard | |
| CheckCoveringKeyboard | Call before and after doing something that changes window bounds |
| SetBorder, SetContentSize, | Overridden to call CheckCoveringKeyboard | SetRelativeOrigin, | SetVisible, AboutToShow, | BringToFront, SendToBack, | Unlink |
| Underpinnings | |
| AllowedToLeaveScene | Overridden to return true |
| AutoMove | Overridden to return true |
| CanAcceptCoupon | Overridden to reject "no border" coupons |
| CanChangeContainers | Overridden to return false |
| CanShowLabel | Overridden to return false so the tinker window won't let the user change the label position |
| ConstrainToolTarget | if closeBeforeTouch or closeAfterTouch flag is set, makes self the tool with some exceptions |
| TouchTarget | if closeBeforeTouch or closeAfterTouch flag is set, closes window before or after calling Touch on target |
| DontCopyToPackage | Overridden to return true |
| ShouldBufferBehind | Overridden to return true |
| Searchable | Overridden to return value of searchableWindow flag |
| Validating | |
| MakeValid | Ensure that superview is nilObject, or screen if self is in screen's subview chain |
You might override these methods of class Window in the described circumstances:
| Method | When to override |
|---|---|
| PersistentWindow | If you need to dynamically determine when to stay on-screen |
| Appear | If you need to do something before the window is shown |
| Disappear | If you need to do something each time a window is closed |
| ZoomFromWhere | If you want to enable zooming and set where the window should zoom from |
| CanCoexist | If your subclass can always coexist or can never coexist |
| HasDependent | If your subclass of windows can have dependents |
| KeepFrontmost | If windows of your subclass should always stay in front, and should ignore the flag |
Class Window 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 |
| defined by Window | ||
| windowFlags | Flags | Stores various boolean attributes of the window |
Class Window defines the following attribute:
| Attribute | Type | Description |
|---|---|---|
| KeepFrontmost | Boolean | Called by system to determine whether this window | should appear and remain in front of all windows | that return false |
Class Window has handy names for the bits you can set in its windowFlags field. This section lists and describes all the window flags.
#define canCoexistBit 0 #define canCoexistMask 0x00000001
Set this flag if your window can coexist on the screen with other windows that set this flag. For example, the system keyboard, which inherits from class Window, sets this flag. The keyboard is often on the screen with other windows. The tool window sets this flag, to allow users to leave it open as a kind of floating palette.
#define persistentWindowBit 1 #define persistentWindowMask 0x00000002
Set this flag if your window shouldn't disappear when the user changes scenes. Reserve this flag for only the most important windows, or you risk annoying your users.
#define dontAutoExtendBit 2 #define dontAutoExtendMask 0x00000004
Set this flag in your InfoWindow objects if they shouldn't extend their bottoms to fit their content.
#define ignoreGridBit 4 #define ignoreGridMask 0x00000010
Set this flag for your ContainerWindow object if it shouldn't enforce a grid on its subviews. See class ContainerWindow for details.
#define closeAfterTouchBit 5 #define closeAfterTouchMask 0x00000020
Set the closeAfterTouch flag if your window should be closed after the user touches it. The touch will be passed to a subview of the window, and then the window will be closed. There are exceptions to this rule, which are explored in detail later in this chapter in the description of the ConstrainToolTarget method.
#define closeBeforeTouchBit 6 #define closeBeforeTouchMask 0x00000040
Set the closeBeforeTouch flag if your window should be closed as the user touches it and before the touch is passed to a subview of the window. There are exceptions to this rule, which are explored in detail later in this chapter in the description of the ConstrainToolTarget method.
#define autoPositionBit 7 #define autoPositionMask 0x00000080
Set this flag if your window should be positioned before it appears. Classes GadgetWindow, ListWindow, and TextStyleWindow are the subclasses that respect this flag. Class TextStyleWindow, for example, uses this flag to check if the style window should position itself where it won't cover up the text the user wants to style.
This flag will have no effect for other subclasses. If you're creating a custom subclass that should respect this flag, you'll probably want to override Appear to check the flag and do any required repositioning.
#define noCloseBoxBit 8 #define noCloseBoxMask 0x00000100
Set this flag if your window shouldn't have a close box. If it's set, the HasCloseBox method returns false and the Draw method won't draw a close box.
#define downArrowVisibleBit 9 #define downArrowVisibleMask 0x00000200
The system uses this flag to cache the state of the down arrow for objects of class ContainerWindow. Don't set this flag yourself.
#define upArrowVisibleBit 10 #define upArrowVisibleMask 0x00000400
The system uses this flag to cache the state of the up arrow for objects of class ContainerWindow. Don't set this flag yourself.
#define rightArrowVisibleBit 11 #define rightArrowVisibleMask 0x00000800
The system uses this flag to cache the state of the right arrow for objects of class ContainerWindow. Don't set this flag yourself.
#define leftArrowVisibleBit 12 #define leftArrowVisibleMask 0x00001000
The system uses this flag to cache the state of the left arrow for objects of class ContainerWindow. Don't set this flag yourself.
#define autoMoveContentsBit 13 #define autoMoveContentsMask 0x00002000
Set this flag for windows that let users move their contents without using the move tool. For example, the tote bag window, the trash window, and the stationery window all set this flag. The TouchTarget and ConstrainToolTarget methods check this flag. When this flag is set, TouchTarget passes along presses to the target by calling MovePress on it. See the description of TouchTarget for more details.
#define searchableWindowBit 14 #define searchableWindowMask 0x00004000
Set this flag if searches should check the contents of your window. The Searchable method checks this flag and returns true if it's set. See the description of Viewable_Searchable for more information.
#define autoCopyWindowBit 31 #define autoCopyWindowMask 0x80000000
Set this flag if you want a copy of your window to be displayed instead of the original. Show checks this flag and, if it's set, makes a copy of the window before displaying the window. The copy is in the same cluster as the original object. Hide destroys the copy when the window is closed.
The method ConfirmationDialog_PerformWithConfirmation uses this flag to make a copy of the confirmation window if the original is already in use.
operation AcceptMorsel(morsel: Viewable); Call: rarely Override: rarely
The system calls AcceptMorsel when a user has successfully dropped an object into the window.
AcceptMorsel unlinks the morsel from its previous superview then determines the morsel's new position inside the window. It determines the morsel's position by calling FindContainerPosition, a method class Window inherits from class Viewable. It then sets the morsel's new superview to be the window. AcceptMorsel finishes by calling MovedContents to give certain kinds of windows a chance to reposition the morsel. (Some subclasses, like class ContainerWindow, align their contents to a grid.)
operation DropACopy(source: Viewable; touchInput: TouchInput); Call: rarely Override: rarely
Call DropACopy to drop a copy of the viewable in the source parameter onto the current card or scene. Windows like the magic hat and the tinker window call this method to make copies of their contents when the user taps. You'll call this method if your subclass of class Window contains objects the user copies.
operation PersistentWindow(): Boolean; Call: rarely Override: sometimes
The system calls Persistent Window to check if the window should stay on the screen when the scene changes. PersistentWindow returns the setting stored in the flag persistentWindow.
You might override PersistentWindow if you needed to determine dynamically whether a window should stay on the screen.
operation Show(), safe, common, noFail; Call: sometimes Override: rarely
Call Show to show a window if it's hidden, zooming the window open if necessary. You'll override Show only rarely. Show calls Appear, which you should override instead.
operation Hide(), safe, common, noFail; Call: sometimes Override: rarely
Call Hide to hide a window if it's shown. You'll override Hide only rarely. Hide calls Disappear, which you should override instead.
operation Appear(); Call: rarely Override: sometimes
Call Appear to show a window by adding it to the screen's view list.
Appear will call Disappear on other open windows if this window can't coexist with them. Appear makes this decision by checking the window's canCoexist flag.
Override Appear if you need to do other work each time your window appears. You could override AboutToShow instead of Appear.
operation CanCoexist(): Boolean; Call: rarely Override: sometimes
The system calls CanCoexist to check if this window can be visible at the same time other windows are visible. Windows that return false won't be shown at the same time.
CanCoexist checks the canCoexist flag and returns true if it's set. Override CanCoexist to ignore the flag if you know that windows of your subclass always answer yes or no.
operation Clear(), noFail, safe; Call: sometimes Override: sometimes
Override and call Clear if your window subclass can clear itself in some way. Window_Clear does nothing. For example, class TrashWindow overrides Clear to empty the trash; the button in the title bar of the trash window calls Clear on the trash window.
operation Disappear(); Call: sometimes Override: sometimes
Call Disappear to hide a window by removing it from the view list. Disappear also flushes any pending touches on the window.
You might override Disappear to do other work each time your window disappears, though you could also override AboutToHide instead.
operation HasDependent(candidate: Window): Boolean; Call: sometimes Override: rarely
The system calls HasDependent to check if the window in the candidate parameter is a dependent of this window. If it is, the candidate window should be closed when this window is closed, and it should stay open when this window is opened.
Window_HasDependent returns false because basic windows don't have dependents. If your new window type has dependent windows, override HasDependent to check.
attribute KeepFrontmost: Boolean, readOnly; Call: sometimes Override: rarely
The system calls KeepFrontmost to check whether this window should appear and remain in front of all windows that return false. Window_KeepFrontmost returns false. You might override to return true or to check a flag if your window class should always be in front of other windows.
operation ShowOrHide(), safe, common, noFail; Call: often Override: rarely
Call ShowOrHide to show a hidden window and hide a visible window.
operation ZoomFromWhere(VAR zoomFrom: Box): Boolean; Call: rarely Override: sometimes
The system calls ZoomFromWhere from Show and Hide to check if the window should zoom open and closed, and if it does, where it should zoom from and to. Window_ZoomFromWhere returns false.
Override ZoomFromWhere to enable zooming and set where your window should zoom from and to.
overrides ConstrainToolTarget; Call: sometimes Override: rarely
Unfortunately, to be written. Here's a brief comment: if closeBeforeTouch or closeAfterTouch flag is set, ConstrainToolTarget makes self the tool with some exceptions.