Defined in Scene.Def
Inherits from Panel
A scene is a viewable object that contains all the other viewables in the space between the name bar and the control bar. If your software package displays its viewables, it will probably contain at least one scene.
The illustration at the beginning of this chapter shows the Magic Cap library scene. The library scene contains viewable objects like the shelf and several books. All these viewable objects are direct or indirect subviews of the scene.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
The machinations of class Scene are inextricably linked with those of class StackScene. You will find the chapter on class StackScene to be most helpful. Class SceneAdditions is also important to scenes.
Instantiate: often Subclass: often Call its methods: sometimes
You should specify scenes in your object definition file, using an existing scene definition as a guide. You probably won't ever have to make a scene programmatically.
You'll often subclass Scene to customize various scene behaviors. Here are some reasons you might subclass Scene:
A Scene's bounding box is the entire screen minus the name bar and the control bar. The Scene is always the ultimate superview of all other viewables on the screen. The only exceptions are viewable objects inside a window: the window is their superview.
Scenes display information about themselves in the name bar, though the name bar is not part of any scene. The name bar for the library scene looks like this:
The left end of the name bar shows the name of the current scene, Library. The right end of the name bar shows the name of the step back scene for the library, Hallway.
Each scene has a step back scene. When the user taps the step back scene name in the name bar, Magic Cap "steps back" to, or opens, that scene. The step back scene is usually the scene that the user was viewing before she opened the current scene. However, some scenes always have a specific step back scene. For example, the downtown scene always has the hallway as its step back scene.
Most scenes have step back spots. When Magic Cap steps back to a scene, it draws a zooming-closed effect around the step back spot. The effect is of the scene receding into that spot, or folding up into that spot. Usually, the step back spot is the place Magic Cap zoomed to when it originally went to the scene. For example, when you tap the name cards icon on the desk, Magic Cap draws a zooming-open effect centered on the name cards icon and goes to the name cards scene.When you step back from the name cards, Magic Cap reverses its steps: it goes to the desk and draws a zooming-closed effect centered on the name cards icon. So the location of the name cards icon is the step back spot for the name cards scene.
Some scenes don't have step back spots because there is no appropriate location to zoom to. For example, the downtown scene's step back scene is the hallway, but there's really no one spot in the hallway to step back to. So the downtown scene has no step back spot.
Class Scene 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 | The container for this viewable |
| subview | Viewable | The first viewable contained inside this viewable |
| relativeOrigin | Dot | Origin relative to superview |
| contentSize | Dot | Size of content rectangle |
| viewFlags | Unsigned | Property settings |
| labelStyle | TextStyle | Text style of viewable's label |
| color | Unsigned | Color of viewable's content |
| altColor | Unsigned | Alternative color |
| shadow | Shadow | The shadow of this viewable (not used for scenes) |
| sound | Playable | The sound associated with this viewable |
| border | Border | The border for this viewable |
| Defined by Scene: | ||
| sceneFlags | Unsigned | The flags that specify certain properties for the scene |
| stepBackScene | Scene | The step back scene |
| stepBackSpot | Viewable | The step back spot |
| image | UnsharedImage | The image used to draw this scene's snapshot |
| additions | SceneAdditions | Scene specific commands, rules, stamps, and tools |
| screen | Buffer | Cached bits used to redraw the scene |
To create a new scene, copy a scene from an existing package and then modify its fields to the values you need.
When you specify a scene in your instance definition file, you should set its next, previous, and superview fields to nil, and its subview field to the rearmost (first) viewable it contains.
For the default Magic Cap screen size of 480.0 by 320.0 pixels, you should set your scene's origin to <0.0, -8.0>, which places it directly below the name bar. Set your scene's content size to <480.0, 256.0>, which fills all the space between the name bar and the control bar.
Scenes have several flags you might set. The section on Scene Flags describes the available flags.
Here's the instance definition for a popular scene, the desk:
Instance Scene 'Desk' 18;
next: nilObject;
previous: nilObject;
superview: nilObject;
subview: (ArchiveIcon 'File cabinet' 733);
relativeOrigin: <0.0,-8.0>;
contentSize: <480.0,256.0>;
viewFlags: 0x11005800;
labelStyle: iBook12;
color: 0xFF333333;
altColor: 0xFF000000;
shadow: nilObject;
sound: nilObject;
border: nilObject;
sceneFlags: 0x88100005;
stepBackScene: (Scene 'Hallway' 88);
stepBackSpot: nilObject;
image: nilObject;
additions: (SceneAdditions 19);
screen: nilObject;
End Instance;
Instance SceneAdditions 19; // additions for Desk scene
commands: (ObjectList 9222);
rules: nilObject;
tools: nilObject;
stamps: nilObject;
stampBankNames: nilObject;
stampBankContents: nilObject;
End Instance;
Instance ObjectList 9222;
length: 2;
entry: nilObject;
entry: (Button 'clean up' 9223);
End Instance;
The first subview of the desk scene is the icon for the filing cabinet. The step back scene for the desk is the hallway, and there is no step back spot.
The desk scene sets the place flag. It uses the sceneVisited flag to mark the desk as visited. In addition, it sets the canDrawIn flag.
The desk scene has a scene additions object. This object specifies the additional commands, rules, tools, stamps, stamper banks, and stamper drawers that this scene adds. The items are available only when this scene is the current scene. For example, the desk scene has a custom command in its scene additions. When the user taps the magic lamp in the desk scene, that command appears as a button in the lamp's gadget window. The "clean up" button won't appear if the user taps the magic lamp in the hallway instead of the desk. For more details, please see the chapter on class SceneAdditions.
Class Scene defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| Image | Image | The image field |
| Visited | Boolean | The sceneVisited flag |
| Form | Object | The form used by this scene's cards |
| Stack | StackOfCards | The stack of cards associated with this scene |
| StepBackScene | Scene | Interface to the scene's step back scene |
| StepBackSpot | Viewable | Interface to the scene's step back spot |
| Additions | SceneAdditions | Interface to the scene additions field |
| Commands | ObjectList | The custom commands for this scene, from the scene additions |
| Rules | ObjectList | The custom rules for this scene, from the scene additions |
| Tools | ObjectList | The custom tools for this scene, from the scene additions |
| Stamps | Viewable | Stamps in this scene's local drawer, from the scene additions |
| StampBankNames | Object | Drawer names for this scene's custom stamp bank, from the scene additions |
| StampBankContents | Object | Drawer contents for this scene's custom stamp bank, from the scene additions |
| DefaultTool | ChooseableTool | The default tool for this scene |
| Locked | Boolean | Interface to the sceneLocked flag |
| OptionFlags | Unsigned | Interface to the sceneFlags field |
Class Scene defines the following methods:
| Method | Description |
|---|---|
| Navigating among scenes | |
| AddToHistory | Add this scene to the top of the history list of recently-visited places |
| GoTo | Go to the specified scene |
| GoToVia | Go to the specified scene and set the step back spot |
| Operating on the current scene | |
| OpenScene | Open the specified scene, restore the scene's screen from the last time it was opened, and set up any scene additions |
| CloseScene | Close the specified scene, save the scene's screen, and remove any scene additions |
| ShutdownScene | Perform any actions necessary when the power is being shut down |
| Purging | Perform any actions necessary when the scene is being removed from the cache |
| SetCurrentSceneIndexicals | Set the iCurrentScene, iCurrentSceneStack, and iCurrentSceneList indexicals |
| Navigating in scenes with cards | |
| HasCards | Check if the scene has cards |
| CurrentCard | The card visible now |
| GoRelative | Move forward or backward inside your scene's abstract space |
| GoToNext | Move one unit forward in your scene's abstract space |
| GoToPrevious | Move one unit backward in your scene's abstract space |
| OneCardOnly | Check if this scene only accepts one card at a time. |
| Place and Nested Scene Operations | |
| StepBack | Go to the scene specified in the current scene's stepBack field |
| IsPlace | Check the place flag to see if this scene has a fixed step back spot |
| IsCorridor | Check the corridor flag to see if this scene is a scrolling scene like the hallway and downtown |
| IsStoreroom | Check the storeroom flag to see if this scene is a storeroom |
| RefreshImage | Update the bits in the image field |
| Searching | |
| SearchFor | Search for the given text, viewable object, or image in the current scene |
| Searchable | Check if the scene object can be searched |
| FindNext | Search forward for the next occurrence of the given text, viewable object, or image in the current scene |
| FindPrevious | Search backward for the next occurrence of the given text, viewable object, or image in the current scene |
| Putting information in the title bar | |
| PlaceName | Get the name of the scene |
| CaptionInfo | Get the scene's caption |
| MemoryImage | Get the image to put in the namebar to show where this card lives if it lives in a package or on a PC card |
| TouchedMemoryImage | Ask the user if she wants to copy an item into main memory |
| MemoryImageInfo | Get information about a memory image |
| Making proxies for sending | |
| MakeContentProxyChoices | Create a list of proxies for the items contained by this scene |
| NewContentProxy | Create a new content proxy for a specific item |
| MakeFileContentList | Get a list of items in this scene that can be filed |
| MakePrintContentList | Get a list of items in this scene that can be printed |
| MakeMailContentList | Get a list of items in this scene that can be mailed |
| MakeFaxContentList | Get a list of items in this scene that can be faxed |
| MakeBeamContentList | Get a list of items in this scene that can be beamed |
| Drawing the scene | |
| Draw | Overridden to raw a gray line underneath the title bar and call inherited |
| SetHilited | Overridden to do nothing because scenes don't highlight |
| NeedsDirtyOffscreen | Check if this Scene has a screen field that is not nil, and thus might need redrawing |
| DirtyOffscreen | Invalidate the offscreen image contained in the screen field |
| Scene underpinnings | |
| CanAccept | Overridden to return false for items placed outside the scene's content box |
| CanAcceptCoupon | Overridden to accept color coupons only |
| CanDrawIn | Check if the canDraw flag is set for the scene. |
| Miscellaneous Operations | |
| DisplayArea | Return the box representing the Scene's content area. |
| InstallAdditions | Install the scene-specific items for the scene from the scene additions object |
| RemoveAdditions | Remove the scene additions |
| MiniCardOrigin | Set the origin that minicards hop from to be the stationary drawer on the main desk. |
| MakeValid | Initialize the scene by destroying the contents of the Scene's screen field, | if any. |
| PutAway | Clean up all associated items for the scene, such as windows, before the scene is removed. |
| TypeKeys | Overridden to corridor scenes to scroll when the right and left arrow keys are tapped |
| UseSpecialDrawer | Check if the scene uses a special drawer |
| Finalize | Overridden to remove the scene from the system history list; calls inherited |
Whenever you create a subclass of class Scene, you are likely to override the following methods:
| Method | When to override |
|---|---|
| HasCards | If your scene subclass contains cards |
| CurrentCard | If your scene subclass contains card, to return the current card |
| GoRelative | If you want to implement moving forward and backward through your scene |
| PlaceName | If you want to customize your scene's name |
| CaptionInfo | If you want to customize your scene's caption |
| CanAccept | If your scene can accept certain kinds of objects dropped onto it |
| CanAcceptCoupon | If your scene can accept certain kinds of coupons |
| SetHilited | If your scene highlights |
| MiniCardOrigin | If minicards should hop from some specific spot in your scene |
#define placeMask 0x80000000
Set this flag if your scene is a place. Places are scenes with fixed step back scenes. If your scene isn't a place, then its step back scene can vary. For example, the downtown scene is a place. Its step back scene is always the hallway. The IsPlace method checks this flag, and returns true if it's set.
#define corridorMask 0x40000000
Set this flag if your scene is a corridor. The IsCorridor method checks this flag, and returns true if it's set.
#define frozenMask 0x20000000
Set this flag if your scene shouldn't redraw itself. You'll probably set this flag programmatically, leave it set for a short time while doing some work, then unset it. For example, you might set it while faxing your scene and unset it when you've finished.
#define useCardNameMask 0x10000000
This flag isn't checked by any of class Scene's methods, but is used by StackScene_PlaceName, to determine how to name the displayed scene. If the useCardName flag is set, PlaceName tries to use the name of the current card as the place name.
#define sceneVisitedMask 0x08000000 #define sceneVisitedBit 27
This flag is checked and set by Visited and SetVisited respectively. It's true if the scene has been visited by the user. This flag is set automatically by the system the first time a Scene is visited.
#define storeroomMask 0x04000000 #define storeroomBit 26
Set this flag if your scene is a store room. It's checked by the IsStoreroom method. The system uses this flag for the store room; you probably won't use it yourself.
#define blankTitleMask 0x02000000
The StackScene_CaptionInfo and StackScene_ShowNameBarInfo methods check this flag. If it's set, CaptionInfo hides the left and right arrows and displays no caption in the stack scene associated with the scene. ShowNameBarInfo returns false if this flag is set.
#define messageViewerMask 0x01000000
Set this flag to mark your scene as a message viewer scene. Message viewer scenes use the minicard stack to step back to.
#define suppressGrayLineMask 0x00800000
Set this flag if you don't want a gray line at the bottom of the title bar. The Scene_Draw method checks this flag.
#define stepBackWhenEmptyMask 0x00400000
Set this flag if the system should step back from the current scene when its contents are deleted. This flag is typically set for scenes that have only one card. For example, the message creation scene sets this flag. If the user deletes or sends the last of the messages she was working on, the system steps back to the desk scene.
#define skipSearchingMask 0x00200000 #define skipSearchingBit 21
Set this flag if the search agent shouldn't bother to search your scene. The Searchable method returns false if this bit is set.
#define canDrawInMask 0x00100000
Set this flag if you want your users to be able to draw in your scene."Drawing" includes scribbling, stamping, adding new fields, and adding other fun objects to a scene. CanDrawIn checks this flag.
#define autoPencilMask 0x00080000
Set this flag if the last pencil tool chosen by the user should be active when your scene is opened. The message creation scene is an example of a scene that sets this flag.
#define sceneDrawerMask 0x00040000
Set this flag to make drawer banks in the Magic Hat display with their last drawer open by default, instead of their first. You might set this flag if your scene installs stamps in the local drawer, and those stamps are the ones people will use most often in your scene.
#define singleCardScene 0x00020000
Set this flag if the stack scene associated with your scene should contain only one card at a time.
#define ephemeralMask 0x00010000
Set this flag if users shouldn't be able to step back to your scene after leaving it. For example, if your Scene was a game, and at the end of the game the user walked through a one way door behind which lurked a tiger, you would set the ephemeral flag for your Scene so they could not return to it by stepping back. The notebook index scene sets this flag to avoid making a loop in the step-back list, where the notebook steps back to the notebook index which steps back to the notebook, and so on.
#define dontAddToHistoryMask 0x00008000
Set this flag if your scene shouldn't be added to the scene history list after the user visits it. (The scene history list is the convenient list of recent destinations that appears when users option-tap on the pointing hand in the right of the name bar.) The AddToHistory method checks this flag, and if it's set, doesn't add the scene to the history list. The system won't take snapshots of scenes with this flag set.
This flag is useful if your scene requires a specific kind of set-up before the user visits it. For example, the package scene needs to have a package installed in it.
#define suppressDateTimeMask 0x00004000 #define suppressDateTimeBit 14
Set this flag if you want to suppress the display of the date and time in the name bar in your scene.
#define sceneDrawerBankMask 0x00002000
Set this flag to display a special drawer bank when the user opens the Magic Hat while in your scene. The UseSpecialDrawer method checks this flag.
#define sceneLockedMask 0x00001000
Set this flag to lock the scene. The Locked method checks and the SetLocked method sets this flag.
#define expandMiniCardsMask 0x00000800
Set this flag if your scene should expand and add minicards dropped into the associated stack scene.
#define sceneToolsMask 0x00000400
Set this flag if you want the tool window to open to the last page instead of the first page as its default for the Scene. You might use this flag if your scene has a custom page of tools that are more commonly used in your scene than the standard tools.
This section describes in detail the methods of class Scene. The methods appear in alphabetical order.
operation AddToHistory(), safe; Call: never Override: never
Call AddToHistory to add the current scene to the history list. If the sceneFlags field has the dontAddToHistory flag set, then this operation does nothing. If the dontAddToHistory flag is clear, then this operation adds the name of this object into the first slot in the system's history list.
overrides CanAccept; Call: rarely Override: sometimes
The system calls CanAccept to check if the Scene will accept the given morsel. Scene_CanAccept returns false for items outside the scene's content box. This prevents unmovable objects from permanently covering other viewables on the screen. Otherwise, CanAccept calls its inherited method, Panel_CanAccept, which returns true to accept everything.
Override CanAccept if your custom scene should reject certain kinds of objects.
overrides CanAcceptCoupon; Call: rarely Override: sometimes
The system calls CanAcceptCoupon to test whether the scene can accept a coupon that the user has dragged on top of the scene. Basic scenes accept only color coupons dropped inside the scene's content box. They reject other coupons.
You should override CanAcceptCoupon if you want your scenes to use different rules for accepting coupons. See Viewable_CanAcceptCoupon for more information.
overrides CanDrawIn; Call: rarely Override: rarely
Call CanDrawIn to check if this scene allows drawing. Scene_CanDrawIn checks the canDrawIn flag and returns kDrawHere if it's set. Otherwise, it returns kAskSuperviewifCanDraw. See the description of Viewable_CanDrawIn for more information.
operation CaptionInfo(abbreviate: Boolean;
VAR captionStr: String; VAR showLeftArrow: Boolean;
VAR showRightArrow: Boolean; VAR minimumWidth:
Micron): Boolean;
Call: rarely
Override: sometimes
The system calls CaptionInfo when it draws the title bar. The caption is the text that appears in the middle of the name bar, in between the name of the current scene and the name of the stepback scene. Often the caption is just the date and time, but some scenes provide custom captions. For example, the name cards stack scene has a caption that tells the user she's looking at name card i of n. Class DatebookScene overrides this method to return the name of current day, week, month, or year, depending upon what the user is currently viewing.
CaptionInfo returns true if this scene has a caption and false if it doesn't. The showLeftArrow parameter is true if a left arrow should appear in the name bar, to allow the user to move back one step in scene space. The showRightArrow parameter is true if the name bar should display a right arrow. The captionStr parameter contains the scene's caption as constructed by CaptionInfo. The minimumWidth parameter is the minimum width of the caption expressed in Microns.
Basic scenes don't have custom captions, so Scene_CaptionInfo returns false. It also sets the captionStr to be empty, the showLeftArrow and showRightArrow parameters to false, and the minimumWidth parameter to 0.
Override CaptionInfo if your scene has a custom caption.
operation CloseScene(), noFail; Call: rarely Override: rarely
The system calls CloseScene to pack up a scene before moving to a different one.
CloseScene removes the scene from the view hierarchy and saves its screen into the screen field for later restoration. CloseScene then calls RemoveAdditions to remove scene-specific objects from the stamper and other places.
You're not likely to call CloseScene, because the handy methods GoTo and GoToVia call it for you.
operation CurrentCard(): Object, safe, common, noFail; Call: sometimes Override: sometimes
Call CurrentCard to get the current card of the Scene, if any. CurrentCard always returns nilObject for class Scene, since the base scene class doesn't have cards.
You should override CurrentCard if your subclass has a concept of a current card. For example, class StackScene overrides to return the current card from the stack of cards.
operation DisplayArea(VAR displayArea: Box; accountForKeyboard: Boolean); Call: sometimes Override: rarely
Call DisplayArea to get a box enclosing the scene's current display area. Pass true in the accountForKeyboard parameter if you want DisplayArea to keep track of the keyboard. DisplayArea returns the scene's valid display area in the displayArea parameter. Usually that will be just the scene's content box. If the keyboard is visible, DisplayArea removes the area the keyboard covers from the content box by the simple expedient of making the bottom of the box be the top of the keyboard's bounds box.
overrides Draw; Call: sometimes Override: sometimes
The system calls Draw to draw the scene and its contents. Scene_Draw calls its inherited Draw method. If the suppressGrayLine flag isn't set, it then draws a gray line underneath the title bar.
overrides Finalize; Call: sometimes Override: rarely
The system calls this method to perform any cleanup before the object is disposed of. Scene_Finalize removes the scene from the history list in iHistoryList and then calls its inherited Finalize method.
operation FindNext(), safe, common; Call: rarely Override: rarely
Call FindNext to search forward in the scene for the next occurrence of whatever the current seach agent is looking for. Scene_FindNext just passes along the FindNext call to the current search agent, iCurrentSearchAgent.
operation FindPrevious(), safe, common; Call: rarely Override: rarely
Call FindPrevious to search backward in the scene for the previous occurrence of whatever the current seach agent is looking for. Scene_FindPrevious just passes along the FindPrevious call to the current search agent, iCurrentSearchAgent.
operation GoRelative(nextFlag: Boolean; allTheWayFlag: Boolean); Call: rarely Override: sometimes
The system calls GoRelative when the user touches an arrow in the name bar to move forward or backward in the scene's abstract space. Most scenes in Magic Cap that have a concept of forward and backward are stacks of cards. Your subclass, however, might have its own concept of multiple locations.
You'll call GoRelative rarely, since you're more likely to use the methods GoToNext and GoToPrevious.
Scene_GoRelative does nothing, since the basic scene class has only one location in its abstract space. Override GoRelative if your scene class has a more than one there there. (Scenes always have at least one there there. It would be confusing indeed if scenes, like Gertrude Stein's Oakland, had no there there at all.) For example, if your subclass has a stack of cards, you would override GoRelative to move forward or backward through the cards. Class StackScene does just that to go to a specific card in its stack. Class DatebookScene also overrides GoRelative to move to the next and previous tasks for a particular day.
GoRelative should move forward one unit in scene space if the nextFlag parameter is true. Otherwise, GoRelative should move one backward one unit. GoRelative should move all the way to the start or the end of its space if the allTheWayFlag parameter is true.
operation GoTo(), safe, common, noFail; Call: sometimes Override: rarely
Call GoTo to switch from the current scene to the scene in the self parameter. GoTo closes all windows as a side effect.
operation GoToNext(), safe, common; Call: sometimes Override: rarely
The system calls GoToNext when the user touches the right arrow in the name bar of a stack scene. GoToNext calls GoRelative with the nextFlag parameter true. It passes false in the allTheWayFlag parameter.
operation GoToPrevious(), safe, common; Call: sometimes Override: rarely
The system calls GoToNext when the user touches the left arrow in the name bar of a stack scene. GoToNext calls GoRelative with the nextFlag parameter false. It passes false in the allTheWayFlag parameter.
operation GoToVia(zoomBackSpot: Viewable), safe, common, noFail; Call: sometimes Override: rarely
Call GoToVia to step into a scene and remember a step back spot. GoToVia sets the new scene's step back spot to be the spot in the zoomBackSpot parameter.
operation HasCards(): Boolean; Call: sometimes Override: sometimes
The system calls HasCards to determine if the scene is associated with a set of cards. Scene_HasCards returns false.
If your scene subclass has a set of cards, override this method to return true (or to check, if the cards are optional). For example, class StackScene overrides HasCards to return true, since stack scenes always contain at least one card.
operation InstallAdditions(); Call: rarely Override: rarely
The system calls InstallAdditions whenever a new scene is opened. InstallAdditions installs any custom tools, rules, commands, or stamps in the scene's scene additions object. See the chapter on class SceneAdditions for more information on scene additions.
operation IsCorridor(): Boolean; Call: sometimes Override: never
Call IsCorridor to check if this scene is a corridor. IsCorridor returns true if the corridor flag is set.
operation IsPlace(): Boolean; Call: sometimes Override: never
Call IsPlace to check if this scene is a place. IsPlace returns true if the place flag is set. Places are scenes with fixed step back spots.
operation IsStoreroom(): Boolean; Call: sometimes Override: never
Call IsStoreroom to check if the current scene is the storeroom. IsStoreroom returns true if the storeroom flag is set.
operation MakeBeamContentList(): ObjectList; Call: rarely Override: rarely
The system calls this operation to get the list of items that the Scene can beam.
operation MakeContentProxyChoices(usageType: Unsigned; list: Object), safe, common; Call: rarely Override: sometimes
The system calls MakeContentProxyChoices to assemble a list of items from the scene that match the given usage type. MakeContentProxyChoices adds the matching items to the list parameter.
The system defines several usage types. The predefined types are:
| Usage Type | Value | Description |
|---|---|---|
| contentFile | 1 | Items that can be filed in data packages or in the file cabinet |
| contentPrint | 2 | Items that can be printed |
| contentMail | 3 | Items that can be sent on telecards |
| contentFax | 4 | Items that can be faxed |
| contentBeam | 5 | Items that can be beamed |
The methods MakeBeamContentList, MakeFaxContentList, MakeFileContentList, MakeMailContentList, and MakePrintContentList call MakeContentProxyChoices with the corresponding usage type.
Class Scene knows how to create proxy lists for printing and faxing. It creates a proxy containing an image of itself which can be printed or faxed. It doesn't handle any of the other usage types. It also doesn't create content proxies for any printable or faxable items inside the scene. You should override MakeContentProxyChoices if your scenes contain items you want to make available for sending by any of the methods listed in the usage types.
Here's an example of how you might override MakeContentProxyChoices. Our mythical scene subclass, class WidgetScene, usually contains one object of the equally mythical class Widget. Widgets can be mailed, beamed, and filed. They're shy, though, so they can't be printed or faxed. Class WidgetScene overrides MakeContentProxyChoices this way:
Method void
WidgetScene_MakeContentProxyChoices(ObjectID self,
ulong usageType, ObjectID list)
{
ContentProxy newProxy;
Widget widget;
/* Our scene class defines an attribute for its widget.
* Make sure your subclass has a convenient way to get
* at its sendable items.
*/
widget = Widget(scene);
switch(usageType)
{
/* We can mail, beam, and file widgets. */
case contentMail:
case contentBeam:
case contentFile:
/* Make a new proxy that has our widget as its
* its target. We've cleverly defined a package
* indexical for our widget's proxy image.
*/
newProxy = NewContentProxy(self, nilObject, 1,
widget, iWidgetSmallImage, 0);
/* Add the new content proxy to the end of the
* proxy list.
*/
AddLast(list, newProxy);
break;
/* Can't fax or print widgets, so do nothing for
the other cases. */
default:
break;
}
/* Call inherited to let superclasses add their choices.*/
InheritedMakeContentProxyChoices(self, usageType, list);
}
The method NewContentProxy does all the hard work. The descriptions of NewContentProxy later in this chapter and in the chapter on class ContentProxy go into detail about what that method does.
Sometimes you might not want to call the inherited method to let superclasses add their choices. At other times you might want to dispatch directly to a class further up in the hierarchy, skipping one or more superclasses.
See the chapters on class ContentProxy and class Proxy for more information on proxies.
operation MakeFileContentList(): ObjectList; Call: rarely Override: rarely
The system calls MakeFileContentList to construct a list of items from the current scene that can be filed.
operation MakeFaxContentList(): ObjectList; Call: rarely Override: rarely
The system calls this operation to get the list of items that the Scene can fax.
operation MakeMailContentList(): ObjectList; Call: rarely Override: rarely
The system calls MakeMailContentList to construct a list of items from the current scene that can be mailed.
operation MakePrintContentList(): ObjectList; Call: rarely Override: rarely
The system calls MakePrintContentList to construct a list of items from the current scene that can be printed.
overrides MakeValid; Call: sometimes Override: rarely
The system calls MakeValid at boot time when clean up needs to occur. Scene_MakeValid destroys the contents of the scene's screen field, if any, and then sets the screen field to nilObject.
operation MemoryImage(): Image; Call: rarely Override: rarely
The system calls MemoryImage when it's drawing the name bar, to get the image that represents where the current card is stored. MemoryImage assumes that the scene has cards and that there is a current card. The memory image is a small image that represents a category of memory container, such as a package or a PC card. The user can tap on the memory image to move the card from one container to another. MemoryImage returns iNameBarPackage if the card is in a package, and iNameBarMemoryCard if the card is on a PC card.
operation MemoryImageInfo(containee: Object; VAR showImage: Boolean; VAR messageIsForPackage: Boolean; VAR useMinicard: Boolean; VAR nearThis: Object); Call: rarely Override: rarely
The system calls MemoryImageInfo while deciding which image to return from MemoryImage. You will never need to call or override this method, so this document spares you the horror of its internal machinations.
operation MiniCardOrigin(hopFrom: Dot); Call: rarely Override: sometimes
Call MiniCardOrigin to get the position that new mini cards should hop from. In basic scenes, mini cards hop as if they came from the stationery drawer in the desk. So MiniCardOrigin returns the origin of iStationeryDrawer in the hopFrom parameter. Override MiniCardOrigin if your scene has a custom spot for mini cards to hop from and you'll be calling Stationery_CreateMessage from your scene.
operation NewContentProxy(descriptionText: Object; count: Unsigned; target: Object; image: Object; conveyFlags: Flags): Object; Call: sometimes Override: sometimes
Call NewContentProxy to create a new content proxy for the object specified by the target parameter. The system calls NewContentProxy from MakeContentProxyChoices when it's creating a list of proxy items that match its criteria. You will probably override and call NewContentProxy if you override MakeContentProxyChoices.
This method is described in great detail in the chapter on class ContentProxy.
operation OpenScene(); Call: rarely Override: rarely
The system calls OpenScene to set up and display a scene.
OpenScene installs the specified scene into the view hierarchy. It then checks the screen field and restores the contents of the screen from the last time (if any) the scene was installed. OpenScene then calls InstallAdditions to install any scene-specific objects into the stamper and other places.
You're not likely to call OpenScene. You're more likely to call the methods GoTo and GoToVia., which both call OpenScene for you.
operation OneCardOnly(): Boolean; Call: rarely Override: rarely
Call OneCardOnly to check if a scene accepts only one card at a time. OneCardOnly checks the singleCardScene flag and returns true if it's set.
operation PlaceName(VAR name: String; abbreviate: Boolean); Call: rarely Override: sometimes
The system calls PlaceName when it needs to obtain the name of the current place. The current place name is shown in the left edge of the name bar. Scene_PlaceName returns the name of the scene. Override PlaceName if you need to return a more specific place name. For example, class StackScene overrides PlaceName to return the name of the current card if a certain flag is set.
operation RefreshImage(); Call: rarely Override: rarely
The system calls RefreshImage to update the small image of the scene that's stored in its image field.
operation RemoveAdditions(); Call: rarely Override: rarely
The system calls RemoveAdditions whenever a scene is closed. RemoveAdditions removes any custom tools, rules, commands, or stamps that were installed by InstallAdditions. See the chapter on class SceneAdditions for more information on scene additions.
overrides Searchable; Call: rarely Override: rarely
Call Searchable to check if this scene should be searched. Searchable returns true if the skipSearching flag is not set. See the description of Viewable_Searchable for more information.
operation SearchFor(searchFor: Object; searchFlags: Flags): Object, noFail; Call: rarely Override: sometimes
Class Scene overrides SearchFor to search the name of the scene and its contents. You might override SearchFor if your scene has more than one place to search. For detailed information about how to override, see the description of SearchFor in the chapter on class Viewable.
overrides SetHilited; Call: sometimes Override: sometimes
Class Scene overrides SetHilited to do nothing. Basic scenes don't highlight, so you'll need to override SetHilited if your scene does. See the description of Viewable_SetHilited for more information.
operation ShutdownScene(); Call: rarely Override: rarely
The system calls ShutdownScene right before it shuts down. This operation is an empty method, but you might want to override it to perform any necessary actions before power off occurs, such as saving any important state information for the current scene.
operation StepBack(), safe, common; Call: sometimes Override: rarely
Call StepBack to move from the current scene to the scene pointed to by its stepBackScene field. The system calls step back when the user taps on the name of the step back scene in the name bar. The system also calls StepBack in stack scenes when the user has deleted the card she's looking at. You might call StepBack any time when the user must leave your scene and return to the last place she visited.
StepBack closes any open windows associated with the current Scene, sets the current tool to the touch tool, and hides the search dog if he's visible. If the scene it's leaving is a mini card, StepBack calls the method that uses the mini card stack to do the bookkeeping of setting the step back scene and spot of the new scene. Otherwise, it sets the new step backs itself.
attribute StepBackScene: Scene, safe; // operation StepBackScene(): Scene; // operation SetStepBackScene(newScene: Scene); Call: sometimes Override: rarely
The setter for this attribute sets the stepBackSpot field to nilObject when it sets the stepBackScene field. When getting the contents of the stepBackScene field, this attribute simply returns the contents of the stepBackScene field.
operation TouchedMemoryImage(); Call: rarely Override: rarely
The system calls TouchedMemoryImage when the user taps on the memory image in the name bar. TouchedMemoryImage asks the user if she wants to move the current card from one memory location to another. See the description of the method MemoryImage for more information.
overrides TypeKeys; Call: rarely Override: sometimes
Class Scene overrides TypeKeys to scroll corridors when the user types the right and left arrow keys. Scene_TypeKeys calls PageLeft or PageRight when appropriate. TypeKeys just calls its inherited method if the scene isn't a corridor. See Viewable_TypeKeys for more information.
operation UseSpecialDrawer(bankFlag: Boolean): Boolean; Call: rarely Override: rarely
The system calls UseSpecialDrawer to check if this scene has a special stamp drawer that should open by default when the users taps the stamper. UseSpecialDrawer is called twice from Drawers_SetToDefault, once to check if this scene uses a special drawer bank, and a second time to check if it uses a special drawer. The bankFlag parameter is true when the system is checking for a special bank.
UseSpecialDrawer returns true to the special bank query if the scene's sceneDrawerBank flag is set. It returns true to the special drawer query if the scene's sceneDrawer flag is set and the scene has custom stamps. The special drawer is usually the local drawer in the main stamper bank.