Defined in Card.Def Inherits from Viewable Uses extra
You can organize your package as a series of documents, with each document containing viewable objects, allowing the user to move from one document to the next. Each document is represented by a group of viewables collected on a card object. All the cards in your package taken together are a stack.
Each card is associated with at most one form, an object that specifies viewables that appear on all cards that use that form. (Cards don't have to have forms.) Although the objects appear with all cards that share the form, each individual card might have separate data for the form objects. For example, a text field object that's part of a form will appear on all cards that use that form. However, each card can have its own text that will appear in the text field object.
Each card serves these purposes:
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 and cards is to copy an existing package that includes a stack, then change the object definitions as needed. Using the Magic Cap software itself, you can modify the card by adding and removing objects.
Each card is associated with a form. (That form could be nilObject, thougha card need not have a form.) The form specifies objects that are shared by more than one card. When a card is drawn on the screen, the objects in the card's form are also drawn. Although the form objects are shared across cards, each card has its own data for the shared items. The data for shared form items is kept in the card's extra data.
Each card is also associated with a special kind of scene object called a stack scene. The stack scene is the card's superview when the card is drawn. There's always exactly one stack scene for a stack.
Instantiate: sometimes Subclass: sometimes Call its methods: rarely
If your package consists of several groups of viewables, and you decide to use a stack to represent the entire collection of groups, you'll use cards for each group of viewables. As mentioned earlier, you'll probably make your stack and at least one card by copying an existing package.
You might also 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 Card includes methods for informing the card if its being displayed, working with the card's form, moving and growing the card, handling scribbles, working with envelopes and mail, providing information about the card, working with the card's viewer, and searching and navigating through cards.
Most of class Card's methods are called by other parts of the system. You'll rarely have to call any methods of class Card directly.
Class Card defines the following methods:
| Method | Description |
|---|---|
| Minicards | |
| InstallMiniCard | Put a miniature icon representing this card onto the specified object (often a telecard) |
| MiniCardPrototype | Get the card's prototype mini card; returns iPrototypeMiniCard by default |
| Stacks | |
| MoveToStack | Add the card to the given stack of cards |
| MoveToSorted | Move the card to sorted position in its stack of cards; stack must be of a class that inherits from class SortedList |
| Visiting a card | |
| AboutToHide | Overridden to dismiss the card's form and stabilize the card |
| AboutToShow | Overridden to summon the card's form, fill the form with the card's data, and size the card correctly |
| DefaultScene | Get the scene to use if this card is viewed by itself (and not as part of a stack scene); returns iSingleCardScene |
| GoTo | Go to this card, with no zoom back spot |
| GoToVia | Zoom to this card using the specified spot as the step back spot |
| WasSeen | Check if the card was seen by the user; uses the cardSeen flag |
| SetWasSeen | Sets the card's cardSeen flag to the given value |
| Changing card size | |
| CanMove | Overridden to return false, since cards can't move on the screen while they're displayed |
| ConstrainMove | Pin card top or bottom when scrolling down or up to keep card size reasonable; used by scroll arrows, not by the move tool |
| ConstrainToolTarget | Allow objects to alter touch behavior; called by Tool_GetToolTarget; handles objects that refuse drawing and autodrawable objects; override to add other constraints |
| AdjustSize | Shrink the card to fit its content |
| SetContentSize | Overridden to also set the size of the card's form |
| InstalledReceiver | |
| InstalledFlags | |
| Scrolling and moving within the card | |
| RevealSelection | If there is an active field, try to keep its insertion point above the keyboard |
| PageUp | Overridden to move card up by 3/4 of its visible height |
| PageDown | Overridden to move card down by 3/4 of its visible height |
| ScrollToTop | Overridden to move card until its top is visible |
| ScrollToBottom | Overridden to move card until its bottom is visible, taking the keyboard into account |
| RevealViewable | Position the card to show the given viewable |
| PageUp | Overridden to move card up by 3/4 of its visible height |
| PageDown | Overridden to move card down by 3/4 of its visible height |
| Scribbling | |
| CanDrawIn | Check if this card can be drawn on; asks the user if the card is locked; otherwise returns the value of the noDrawing flag |
| Manipulating the form | |
| ICFContainerClass | |
| SummonForm | |
| DismissForm | |
| BorrowForm | |
| ReturnForm | |
| StoreFormData | |
| ExtractCardData | |
| StoreCardDataFromForm | |
| ExtractCardDataToForm | |
| EachExtraField | |
| ChangedContents | Does nothing; override to do something |
| Manipulating text on a card | |
| MainText | Extract text from all body fields on the card and return it in a new Text object |
| SetMainText | Put the given text into the card's first body field |
| MainField | Get the first body field of this card |
| Interacting with the card's form | |
| ICFContainerClass | Overridden returnsExtensionElement if any form items are not translatable by ICF; otherwise returns inherited |
| SummonForm | Acquire form for long-term use |
| DismissForm | Done using form |
| BorrowForm | Acquire form temporarily -- returns (former) owner |
| ReturnForm | Give borrowed form back to previous owner |
| StoreFormData | Call StoreCardDataFromForm with nilObject as form; convenience routine |
| ExtractCardData | Call ExtractCardDataToForm with nilObject as form; convenience routine |
| StoreCardDataFromForm | Store the data in the given form in the card |
| ExtractCardDataToForm | Extract the data from the current card into the given form |
| BorrowCopyOfForm | Borrow a copy of the card's form |
| ReturnCopyOfForm | Destroy the form copy previously borrowed with BorrowCopyOfForm |
| EachExtraField | Overridden to handle the fields in the extra data !!!!!!!!!!! |
| Drawing on the card | |
| Erase | Overridden to call Erase on the card's form, if it has one, then call inherited |
| DestroySubviews | Overridden to temporarily remove the card's form, call inherited, then re- install the card's form |
| EraseRecent | Overridden to temporarily remove the card's form, call inherited, then re- install the card's form, if the option key is down |
| Draw | Overridden to borrow and return the card's form around a call to the inherited Draw method |
| DrawWithContents | Overridden to borrow and return the card's form around a call to the inherited DrawWithContents method |
| CalcBorderBox | Overridden to borrow and return the card's form; returns the union of the form's border box and the box returned by calling the inherited method |
| CalcInsidePart | Overridden to borrow and return the card's form; calls CalcInsidePart on the form, if there is one; otherwise calls inherited |
| CalcOpaqueBox | Overridden to borrow and return the card's form; calls CalcOpaqueBox on the form, if there is one; otherwise calls inherited |
| ChangedContents | Overridden to ensure that the form remains the rearmost subview of the card |
| Copy | |
| Copying | Overridden to set the copy's stack to nilObject, if the copy is not in the original's stack |
| CanExtendBottom | Overridden to return true. |
| ExtendBottom | Overridden to center the form in the card after calling inherited method, then to scroll to the new card bottom. |
| Supporting ICF | |
| AddToContainer | Overridden to call AddCardDataToDocument and to handle the card's subviews |
| ExtractFromContainer` | Overridden to call ExtractCardDataFromDocument and to handle the card's subviews |
| AddCardDataToDocument | Add the card's data to the ICF document |
| ExtractCardDataFromDocument | Restores data from an ICF document to the card |
| SetFirstSubview | Overridden to avoid having the form as the first subview, since that can cause problems for package cards |
| Notification | |
| Confirmed | Overridden to set the confirmed card flag, then pass the Confirmed call along to the card's subviews |
| Getting and setting textual information | |
| ActivateForTyping | Activate a body field if possible; else call inherited |
| Label | Obsolete; does the same thing as its inherited method |
| TextInfo | Overridden to handle some card-specific cases |
| MainText | Get text from the card's main field, or from the card data if there's no form installed |
| SetMainText | Replace the text of the main field with the given text |
| MainField | Find the first subview of the card that is a body field |
| Text substitution (for stationery) | |
| SubstituteText | Used by class Telecard to do text mapping on previously-hidden card text in stationery; Card_SubstituteText does nothing |
| debugging | |
| Validate | Check the reserved card flags, compares the setting of the canDelete bit with the setting in the subviews, compares the stack's links to the card's links |
| Searching | |
| MatchText | Overridden to check the card's data if the inherited method can't find a match |
| Sending | |
| AttachmentPosition | Overridden to put task proxies in the lower right corner of the card; otherwise calls inherited |
| MakeMiniCardAndHop | Make a new minicard for this card appear in the desk scene, hop into position, and zoom open |
| MailOnTelecard | Install a minicard copy of this card on a telecard for sending |
| SetSentFlag | Set the flag on a card that indicates it was sent in email, or mark a stationery object as not editable |
| WasSent | Check if this card was sent in mail by checking the sentFlag card flag |
| Confirmable | Returns true; override to add criteria for returning true |
| IsConfirmed | Check if the user has pressed the yes or no button in a confirmation form by checking the confirmed card flag |
| IsEnvelope | Check if this card is an envelope for another card by checking the isEnvelope card flag |
| Filing | |
| CanFileIntoFileCabinet | Check if an item can be filed; cards always return true |
| CopyIntoSystem | Overridden to keep card in same stack if it's in a system stack; makes new minicard if necessary; otherwise moves card to receiver from package's install list; |
| FileTo | Overridden to destroy any minicards for this card, then calls FileInContainer |
| FilingChoiceImage | Get the card's icon |
| NeedsInstallEntry | Check if self is in a package and is not an envelope |
| misc. | |
| Init | Overridden to call SetCanContain(self, true) after calling inherited | Method |
| Finalize | Overridden to remove the card from a stack if it's in one, and removes any installed forms from the card |
| DefaultTool | Determine which tool should be active when the card is displayed; checks the autoPencil card flag and the result of CanDrawIn |
| DetachCard | Detach the card from its stack, passing along the card to its stack's stack scene, if possible |
| ArrowState | Determine the card's vertical scrolling state by comparing its content box against its display area, taking the keyboard into account |
| CardIcon | Get an image to use to represent this card |
| CardText | Extract text from the card and all its data items, returning the text in the theText string |
| SetCardText | Overridden to borrow the form or a copy of the form as nececssary, then set the text in the form |
| CanAccept | Overridden to return true if the inherited method returns true and the probe is in the card's content box |
| CanAcceptCoupon | Overridden to return true if the coupon is view coupon with the selector viewCouponShowSubviews |
| CanBringToFront | Overridden to always return false |
| CanChangeContainers | Overridden to always return false |
| CanCopy | Overridden to always return false |
| CanDelete | Overridden to return false if the card is the target of the system's default stationery; otherwise calls inherited |
| SetName | Overridden to dirty the name bar after calling inherited |
| FillOutCard | Set up a new card dynamically before calling AboutToShow; Card_FillOutCard does nothing |
| GarbageCollectSize | Overridden to return the result of GetSize, since the card's extra data might contain objects |
| Render | Overridden to render the card at the standard size, borrowing and returning the card's form as necessary |
Class Card has several methods that are obsolete or will be obsolete in future versions of the software. Don't use these methods. Use their replacements instead. The following methods are obsolete:
| Obsolete method | Replacement |
| OpenCard | Obsolete; use AboutToShow instead |
| CloseCard | Obsolete; use AboutToHide instead |
| GoToNext | Obsolete; use Scene_GoToNext instead |
| GoToPrevious | Obsolete; use Scene_GoToPrevious instead |
| CanAutoGrow | Obsolete; used to check the autoGrowCard bit |
| RevealTop | Obsolete; use ScrollToTop instead |
| RevealBottom | Obsolete; use ScrollToBottom instead |
| CompareCards | Compare cards so they can be sorted in mail stacks; might vanish, so please don't call this method |
Class Card defines the following attributes:
| Attribute | Type | Description |
|---|---|---|
| ContentIcon | Image | The card's icon, used to represent the card in ContentListViews and other places |
| DefaultTool | ChooseableTool | The tool that should be active when the card is displayed; if the autoPencil bit is set and this card can be drawn in, this is the last-used tool |
| DontPurge | Boolean | True if this card shouldn't be purged; corresponds with the dontPurge flag |
| Form | Form | The card's form; interface to the form field |
| IsReadOnly | Boolean | True if this card can't be changed by the user; corresponds with the cardReadOnly flag |
| Locked | Boolean | True if this card's locked bit is set or if the card's scene is locked |
| LShapedBodyField | Boolean | True if this card's body field is L-shaped; example can be seen on postcards |
| MinimumHeight | Micron | The shortest height this card can be; 246 pixels by default |
| SearchInitial | UnsignedByte | First letter of last name, or may be 0 |
| Stack | StackOfCards | The stack this card is part of |
Class Card 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 | 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 |
| Defined by Card | ||
| globalscreenRedrawCount | Unsigned | Used to keep track of the number of times screen has is redrawn while showing this card |
| form | Object | Form drawn with this card |
| stack | Stack | Stack that contains the card |
| cardFlags | Unsigned | Various settings for cards |
Class Card defines a number of flags, which this section describes in detail. Some flags should be set in a card's object definition. Others are set by the system on the fly. Some flags have pre-defined constants for the their masks and bits. Use whichever constant is most convenient for you.
#define reservedBit 31
This flag is reserved for system use. Please don't set it.
#define autoGrowCardBit 30 #define autoGrowCardMask 0x40000000
This flag is reserved for system use. Please don't set it.
#define noEnvelopeBit 29 #define noEnvelopeMask 0x20000000
This flag is used by class Telecard to distinguish postcard-style from letter-style cards. Set it if you are creating your own postcard-style kind of telecard.
#define sentFlagBit 28 #define sentMask 0x10000000
The system uses this flag to distinguish cards that have been mailed from ones that haven't. Stationery uses this flag to indicate that the stationery isn't editable. This flag is used by the SetSentFlag and WasSent methods.
#define isEnvelopeBit 27 #define isEnvelopeMask 0x08000000
Set this flag if your card is an envelope for a telecard. The system uses this flag to distinguish an envelope from other cards. This flag is checked by the IsEnvelope operation.
#define stationeryBit 26 #define stationeryMask 0x04000000
Set this flag if your card is stationery; that is, your card is the target of a stationery object.
#define substituteBit 25 #define substituteMask 0x02000000
Set the substitute flag if the form data of your card contains text that should be mapped before the card is displayed. The method Telecard_SubstituteText checks this flag.
#define suppressCardDataBit 24 #define suppressCardDataMask 0x01000000
Use this flag in conjunction with the substitute flag. Set it when the text from your card's form data shouldn't be displayed until the system has done the mapping.
#define autoAddressBit 23 #define autoAddressMask 0x00800000
Set this flag when your card is the target of stationery, and should be addressed automatically. When this flag is set, the system will address the new card to the current contact when the user taps the associated stationery.
#define cardSeenBit 22 #define cardSeenMask 0x00400000
The system setse this flag when the card has been drawn on the screen. This flag is used by the WasSeen attribute.
#define autoPencilBit 21 #define cardAutoPencilMask 0x00200000
Set this flag if the system should enable a drawing tool when it displays this card. If this flag is set and the noDrawing flag isn't, the system will set the current tool to be the tool used most recently.
#define noAutoKeybdBit 20 #define noAutoKeybdMask 0x00100000
Set this flag if the keyboard shouldn't be automatically activated for typing when your card is displayed.
#define tempTOCEntryBit 19 #define tempTOCEntryMask 0x00080000
The system sets this flag for book pages when a marked page is inserted into an index.
#define rightPageEntryBit 18 #define rightPageEntryMask 0x00040000
Set this flag for book pages that begin on the right side of a card.
#define noDrawingBit 17 #define noDrawingMask 0x00020000
Set this flag if the user can't draw in this card. When it's set, drawing tools will have no effect on the card. The CanDrawIn method checks this flag.
#define dontPurgeBit 16 #define dontPurgeMask 0x00010000
Set this flag for cards that are so important they should not be offered to the user for deletion. The DontPurge attribute uses this flag.
#define cardLockedBit 15 #define cardLockedMask 0x00008000
This flag is used by the Locked attribute. If it's set, the card is locked.
#define confirmedBit 14 #define confirmedMask 0x00004000
The system sets this flag when Confirmed(…,true) is called. The IsConfirmed method checks this flag.
#define shrinkToFitBit 13 #define shrinkToFitMask 0x00002000
Set this flag for cards that should be automatically resized when AdjustSize is called.
#define noFileAfterSendBit 12 #define noFileAfterSendMask 0x00001000
Set this flag for a Telecard if the iMessageSent trigger shouldn't be posted when they're sent. As the name of the flag suggests, you might want to set this flag for telecards that shouldn't be filed when they're sent. Some examples of telecards that set this flag are directory requests and mailbox rule change notices.
#define noSubstituteCardBit 11 #define noSubstituteCardMask 0x00000800
Set this flag for telecards that shouldn't map their text when they are reply messages or cover pages for forwarded messages.
#define cardReadOnlyBit 10 #define cardReadOnlyMask 0x00000400
Set this flag for cards that should never be changed by the user. Setting this flag makes are card truly read-only. Locked cards can be unlocked, but this flag means what it says. You might set this flag for messages that report errors, such as non-delivery report cards. This flag is used by the IsReadOnly attribute.
#define dontAppearInLogMask 0x00000200 #define dontAppearInLogBit 9
Set this flag for Telecards that should not appear in the name card log.
#define searchInitialUsed 0x00000080
Set this flag if bits 0-6 of the card Flags field contain the unicode for this card's search initial. The SearchInitial method returns true if this flag is set.
#define searchInitialMask 0x0000007F
If this searchInitialUsed flag is set, this constant masks the section of the cardFlags field that contains the unicode for this card's search initial.
This section describes the methods of class Card that you're likely to call or override. You'll find that you rarely have to call methods of class Card.
operation InstallMiniCard(cardOrScene: Viewable): MiniCard;
Call: sometimes Override: rarely
Call InstallMiniCard to create a minicard for the current card, using the card's minicard prototype. The prototype is determined by calling MiniCardPrototype. The newly-created minicard is a subview of the viewable specified in the cardOrScene parameter. InstallMiniCard returns the new minicard.
InstallMiniCard handles several special cases for the cardOrScene parameter. If that parameter is the desk scene, InstallMiniCard puts the minicard onto the main desktop. If that parameter is a stack scene, InstallMiniCard puts the minicard onto the current card, if one exists.
operation MoveToStack(newStack: StackOfCards), noFail; Call: sometimes Override: sometimes
Call MoveToStack to move a card out of its current stack (if any) and into the stack specified by the newStack parameter. newStack can be nilObject. MoveToStack makes the card the current card of newStack's stack scene if it had no cards installed before.
attribute Form: Form; // operation Form(): Form // operation SetForm(newForm: Form) Call: sometimes Override: rarely
Call Form to return the form that's used by the card. Form simply returns the value of the card's form field. Use SetForm to change the card's form.
overrides ConstrainToolTarget Call: rarely Override: never
The system calls ConstrainToolTarget whenever the user touches a viewable with a tool. The target viewable gets a chance to change the tool's target by redirecting the touch. Card_ConstrainToolTarget redirects a touch on the card's form to a touch on the card itself.
For more information on ConstrainToolTarget, see the description of Viewable_ConstrainToolTarget.
operation SummonForm(needCardData: Boolean); Call: rarely Override: never
The system calls SummonForm when a card appears on the screen. The form summoned is one the card will be using for a long period of time. The card is the form's rightful user. You are not likely to call SummonForm yourself. You're more likely to use BorrowCopyOfForm instead.
operation DismissForm(hadCardData: Boolean); Call: rarely Override: never
Call DismissForm to tell the system that you're finished using a form acquired with SummonForm.
operation BorrowForm(needCardData: Boolean): Card; Call: rarely Override: never
Call BorrowForm to get a form to use temporarily. You might do so if you're rendering a card for printing or faxing, while the user is perhaps viewing other cards. You may call Borrow Form only from the user actor. If another actor is running, you must use BorrowCopyOfForm instead. The needCardData parameter should be true if you want your card's data stored in the form.
BorrowForm returns the card's previous owner. You must keep track of that owner so you can return the form to it when you call ReturnForm.
operation ReturnForm(formerOwner: Card; hadCardData: Boolean); Call: rarely Override: never
Call ReturnForm to return a form that you've previously acquired with BorrowForm. If you called BorrowForm with needCardData set to true, you must call ReturnForm with the hadCardData parameter true.
operation BorrowCopyOfForm(readCardData: Boolean): Form; Call: sometimes Override: never
Call BorrowCopyOfForm to borrow a copy of a card's form in code that runs on an actor other than the user actor. This method is rather expensive so you should only use it when you need to support concurrent access to a form. The system uses this method, for example, when it's decoding and encoding mail messages. BorrowCopyOfForm returns the copy of the form.
operation ReturnCopyOfForm(copy: Form; writeCardData: Boolean); Call: sometimes Override: never
Call ReturnCopyOfForm when you're finished using a form copy created with BorrowCopyOfForm. The copy parameter is the copy you're returning. ReturnCopyOfForm destroys the form when it's finished.
operation StoreCardDataFromForm(form: Form); Call: rarely Override: never
Call StoreCardDataFromForm to extract data from a form and store it in the current card. The form parameter is the form to extract data from. If the form parameter is nilObject, StoreCardDataFromForm attempts to find the card's form by calling Form. If this form isn't currently attached to the card, StoreCardDataFromForm does nothing.
overrides ChangedContents Call: rarely Override: never
The system calls ChangedContents when the user drags an object into or out of a card. Card_ChangedContents does nothing. Override to do some work when objects move in or out of your card subclass.
operation Confirmable(): Boolean; Call: sometimes Override: sometimes
The system calls Confirmable when assembling buttons on a confirmation form. Card_Confirmable always returns true. Override Confirmable from your subclass to add custom criteria for returning true. Returning false disables the buttons on the confirmation form.
overrides CopyIntoSystem Call: rarely Override: never
CopyIntoSystem keeps the card in the same stack if it's in a system stack. It makes a new minicard if necessary. Otherwise it moves the card to its receiver from the package's install list.
operation CardIcon(sizeSelect: Unsigned): Image; Call: sometimes Override: sometimes
Call CardIcon to get an image to use to represent this card. The size choices are standardSize (used by mini-cards), and smallestSize (used in list views).
| Size name | Value | Description |
|---|---|---|
| standardSize | 1 | Used for MiniCards |
| SIZEUNUSED2 | 2 | Unused |
| smallestSize | 3 | Used in list views |
CardIcon returns iTinyCardImage if sizeSelect is smallestSize. You might override CardIcon if your card type has a specialized small image.
overrides FilingChoiceImage Call: rarely Override: never
FilingChoiceImage is a convenience routine. It returns the result of a call to CardIcon, with the size choice standardSize.
overrides TextInfo Call: often Override: sometimes
Call TextInfo to get a textual description of a card. Card_TextInfo handles several special cases of TextInfo types. Those types are:
| Case handled | Value | Result returned |
| kContentDescription | The card's name, if it has one, otherwise iCardDefaultType | |
| kTypeDescription | The card's name, if it has one, otherwise iCardDefaultType | |
| kKindOfCard | TextToString(cardKindOfCard, info) |
|
| default case | The result of calling inherited |