Defined in Scene.Def Inherits from Scene
Stack scenes are viewable objects that act as the containers for cards in a stack. Every stack has exactly one stack scene. You'll rarely have to work directly with stack scenes; most of their work takes place automatically as you build and manipulate stacks.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
If your package consists of a stack of cards, you'll use an object of class StackScene as the container for all the cards in the stack.
If your package has a stack, it will have exactly one stack scene. The easiest and best way to create the stack scene is simply to copy an existing package, then use MagicDeveloper's Clone Package menu item to start fresh with a new name.
As the user moves from one card in the stack to the next, the old card is removed from the stack scene and the new card is installed. The stack scene is always the container for the current card; the other cards aren't installed in the stack scene and aren't in the view list at all.
Every stack scene has a stack field that refers to the stack object associated with the stack scene. Stack scenes also keep track of the stack's current card in their cardNum field.
Instantiate: sometimes Subclass: rarely Call its methods: sometimes
You probably won't ever have to make a stack scene object programmatically, but every stack of cards you create needs one. As mentioned earlier, you'll probably make your stack scene simply by copying one from an existing package's object definition file, then modifying its fields if necessary.
Class StackScene defines a few methods you might call that perform actions with the stack scene's associated stack and cards, such as navigating through the stack and finding out which card is currently being displayed.
Class StackScene has the following methods you might call:
| Method | Description |
|---|---|
| CurrentCard | Returns card currently being displayed |
| GoToCardNum | Goes to specified card |
| GoRelative | Set current card to next, previous, first, or last card in stack, depending on flags |
| SetCurrentCard | Sets current card and adds card to stack if necessary |
| Adding and removing cards | |
| CreateNewCard | Adds a new card and goes to it |
| DeleteCard | Removes card from stack and destroys it |
| DetachCard | Remove current card from stack and scene; shows next card | (previous card if this was last) |
| MoveToStack | Remove card from this stack, adds it to other stack, and makes it current card if in a scene |
| DeleteCurrentCardWithConfirmation | Delete the current card after asking the user to confirm |
Class StackScene defines the following framework methods, which you're not likely to call:
| Method | Description |
|---|---|
| Stacks and cards | |
| HasCards | Return true |
| OpenScene | Set current card indexical |
| CloseScene | Set current card indexical |
| DefaultTool | Ask the card for its default tool |
| InstalledReceiver | Overridden to return the stack |
| MakeContentProxyChoices | |
| Title bar | |
| PlaceName | Return current card type for title bar scene name |
| CaptionInfo | Construct the string "# of #" for the title bar |
| Adding and removing cards | |
| Swallow | Optionally expand and add swallowed minicards |
| Guts | |
| InstallCurrentCard | Put current card into view hierarchy |
| RemoveCurrentCard | Remove current card from view hierarchy |
| SetName | Set name of stack as well |
| Copy | Clone scenes with card removed |
| Finalize | Destroy scenes with card removed |
| TypeKeys | Arrows do next card and previous card; sends characters to card directly |
The StackScene class defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| CardNumber | Unsigned | Index in stack of current card |
| Stack | StackOfCards | The stack associated with this stack scene |
| ShowNameBarInfo | Boolean | Enables arrows if can go to next or previous card and returns "cardnum of total" for curstring |
The StackScene class defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from SingleLinkable: | ||
| next | Object | Next item in view list |
| Inherited from Linkable: | ||
| previous | Object | Previous item in view list |
| Inherited from Viewable: | ||
| superview | Viewable | Container for this object |
| subview | Viewable | Object contained by this object |
| relativeOrigin | Dot | Origin relative to superview |
| contentSize | Dot | Size of content rectangle |
| viewFlags | Unsigned | Various 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 |
| Defined by HasBorder: | ||
| border | Border | Border drawn around object |
| Defined by Scene: | ||
| sceneFlags | Unsigned | Various scene settings |
| stepBackScene | Scene | Scene to step back to (at right of name bar) |
| stepBackSpot | Viewable | Place to zoom to on step back |
| image | Image | Image for scene's snapshots |
| additions | SceneAdditions | First in list of scene-specific commands |
| screen | Buffer | Cached bits to draw scene |
| Defined by StackScene: | ||
| stack | Stack | Stack associated with scene |
| cardNum | Unsigned | Index of current card |
attribute Stack: StackOfCards, safe // operation Stack(): Stack call: sometimes Override: rarely
Call Stack to return the stack that's associated with this stack scene.
overrides CurrentCard call: sometimes Override: rarely
Call CurrentCard to return the card that's currently being displayed by the stack. CurrentCard calls CardNumber to determine the current card number, then calls Linkable_GetAt to return the card.
operation SetCurrentCard(card: Object) call: sometimes Override: rarely
Call SetCurrentCard to make the given card the current card. If the card isn't already in the stack, SetCurrentCard adds it to the stack, and the card is added according to the stack's insert order. If the newly-added card has an envelope, the envelope is added to the stack.
See StackOfCards_GetInsertOrder for more information.
attribute CardNumber: Unsigned, readOnly // operation CardNum(): Unsigned call: sometimes Override: rarely
Call CardNum to return the number of the card that's currently being displayed. The card number is an index into the cards associated with the stack scene.
operation GoToCardNum(cardNum: Unsigned) call: sometimes Override: rarely
Call GoToCardNum to display the card specified by the given number as the current card.
operation CreateNewCard(): Card, safe; common call: sometimes Override: rarely
Call CreateNewCard to make a new card, add it to the stack, and make it the current card, which shows it on the screen. The new card is a copy of the stack's prototype card as specified by calling Stack_ProtoCard. The new card is added to the stack at the position specified by the stack's insert order, which is determined by calling Stack_GetInsertOrder. After it's created, the new card becomes the stack's current card.
operation DeleteCard(), safe, common call: sometimes Override: rarely
Call DeleteCard to remove the current card from the stack and destroy it. DeleteCard checks calls Card_CanDelete to see if the card's can delete flag is set. If Card_CanDelete returns true, the card isn't deleted and DeleteCard plays the error sound. Otherwise, the card is deleted and DeleteCard plays the trash sound.