chapter">
Defined in Stack.Def
A stack is a list of cards that are maintained together in a software package. All the cards in the stack share a single scene. Users can navigate through the stack by moving from one card to another.
Remember that if the documentation and the software (especially the definition files) disagree, always trust the software.
If your package contains cards, it must also include a stack object that describes the collection of cards. The usual way to create the stack is to copy an existing package that includes a stack, then use the Rename Package menu item to begin your new package. You can also construct a stack object in an instance definition file.
The stack's protoCard field defines its prototype card, which serves as a
template for adding new cards to the stack. The stackScene field identifies the scene, if
any, in which the stack is installed.
The stackFlags field defines a number of properties that affect the adding and display of cards. When a new card is added to the stack, the insertOrder property specifies where the new card should be added: before or after the current card, or at the beginning or end of the stack.
Another property flag, containsNewItems, tells whether any new cards have been added to the stack since the last time it was displayed on the screen.
Instantiate: sometimes Subclass: rarely Call its methods: sometimes
You probably won't ever have to make a stack object programmatically, but you'll need a stack if your package contains a collection of cards. As mentioned earlier, you'll probably make your stack by simply copying one from an existing package, then modifying its fields if necessary.
You might want to allow users to add their own cards to your stacks. To do this, you can use the StackScene_CreateNewCard method as part of a button script.
Class StackOfCards includes methods you might want to call for getting and changing information about the stack's contents and the way it displays them.
Class StackOfCards has the following methods that you might Call:
| Method | Description |
|---|---|
| Appearance and behavior | |
| StackScene | Get scene in which stack is installed, if any |
| SetStackScene | Set scene in which stack is installed |
| CanWrap | Does last card wrap back to first? |
| SetCanWrap | Set whether last card wraps back to first |
| Inserting | |
| ProtoCard | Get prototype for new cards inserted in stack |
| GetInsertOrder | Find out where newly created cards will be inserted |
| SetInsertOrder | Set where newly created cards will be inserted |
| ContainsNewItems | Have new cards been added since stack was last displayed? |
| SetContainsNewItems | Set whether new cards have been added since stack was last displayed |
| Debugging and testing | |
| Validate | Test stack for validity |
Class StackOfCards defines the following fields:
| Field | Type | Description |
|---|---|---|
| Inherited from AbstractList: | ||
| length | Unsigned | Number of cards in stack |
| Inherited from FixedList: | ||
| Stride | Unsigned | Size of each card in bytes |
| Defined by Stack: | ||
| protoCard | Card | Prototype for new cards inserted in stack |
| stackFlags | Unsigned | Various flags and properties (see below) |
| stackScene | Object | Scene in which stack is installed, if any |
The stackFlags field contains the following flags and properties:
| Property | Bits | Description |
|---|---|---|
| insertOrder | 01 | Controls where newly created cards will be inserted |
| containsNewItems | 30 | Tells whether new cards have been added since stack was last displayed |
| canWrap | 31 | Controls whether last card wraps back to first |
The following constants are defined for accessing the contents of the stackFlags field:
| Constant | Value |
|---|---|
| insertNewCardHere | 0 |
| insertNewCardAfterMe | 1 |
| insertNewCardAtStart | 2 |
| insertNewCardAtEnd | 2 |
| containsNewItemsBit | 30 |
| wrapFlagBit | 31 |
This section describes the methods of class StackOfCards that you're likely to call or override.
attribute StackScene: Object, safe, common // operation StackScene: Object, safe, common Call: sometimes Override: rarely
Call StackScene to get the scene (if any) in which a stack is installed. If the stack is not installed in a scene, the result is nilObject.
attribute StackScene: Object, safe, common // operation SetStackScene (newScene: Object), safe, common Call: rarely Override: rarely
Call SetStackScene to set the scene in which a stack is installed. The scene is normally defined in the instance definition file and not changed thereafter, so you'll probably never need to call this method.
attribute CanWrap: Boolean; safe; common // operation CanWrap: Boolean; safe; common Call: sometimes Override: rarely
Call CanWrap to find out whether a stack's navigation arrows allow the user to wrap around from one end of the stack to the other. If CanWrap is true, touching the next-card arrow when the last card is showing movea to the first card, and touching the previous-card arrow when the first card is showing moves to the last card. If CanWrap is false, the next- and previous-card arrows do not appear when the last or first card is showing, respectively.
attribute CanWrap: Boolean; safe; common // operation SetCanWrap (newWrapFlag: Boolean); safe; common Call: rarely Override: rarely
Call SetCanWrap to specify whether a stack's navigation arrows allow the user to wrap around from one end of the stack to the other. See CanWrap for more information.
attribute ProtoCard: Card, readOnly // operation ProtoCard(): Card Call: rarely Override: rarely
Call ProtoCard to get the prototype card a stack uses for adding new cards.
operation GetInsertOrder(): UnsignedShort Call: sometimes Override: rarely
Call GetInsertOrder to find out where a stack will place newly added cards. There are four possible values for the insertion order:
| Value | Meaning |
|---|---|
| 0 | Before current card |
| 1 | After current card |
| 2 | At beginning of stack |
| 3 | At end of stack |
operation SetInsertOrder (newOrder: UnsignedShort) Call: sometimes Override: rarely
Call SetInsertOrder to specify where a stack should place newly added cards. See the description of GetInsertOrder for the values of the newOrder parameter.
operation ContainsNewItems(): Boolean Call: sometimes Override: rarely
Call ContainsNewItems to find out whether any new cards have been added to a stack since it was last displayed.
operation SetContainsNewItems (newItemsFlag: Boolean) Call: sometimes Override: rarely
Call SetContainsNewItems to specify whether any new cards have been added to a stack since it was last displayed.
overrides Validate Call: rarely Override: sometimes
StackOfCards_Validate checks for the following conditions and takes the following actions if it discovers any of them:
| Condition | Action if true |
|---|---|
The stack field of the stack's |
Prints debug message: | scene is not the stack | [stack] points to [scene], but not the other way
|
| The stack contains an element that | Prints debug message: | is not a member of class Card |
[stack] contains non-card element: [element]
|
The stack field of one of the |
Prints debug message: | stack's cards is not the stack | [stack] contains [card], but card references [other
stack] |
In addition to checking these conditions, StackOfCards_Validate also calls its inherited implementation to check the validity of the stack's structure at the superclass level.
You should override Validate if you want objects of your class to perform any additional validity checking. See Object_Validate for more information.