Name cards
Book Contents Previous Chapter Next Chapter
This chapter describes name cards, a subclass of cards whose objects keep track of people and companies that the user communicates with. Before reading this chapter, you should be familiar with viewables, scenes, and cards.
When the user refers to a person or company using any of Magic Cap's communication features, such as by sending mail or by scheduling a meeting, Magic Cap uses a name card to hold the information for the person or company. Name cards are kept in the name card file, a stack of cards that the user can see by touching the name card icon on the desk. The name card file is also called the name cards stack. The people and companies listed in the name cards stack are called correspondents.
Name cards
When the user touches the icon on the desk that looks like a collection of name cards, Magic Cap goes to the name cards scene and shows the name card for the current contact, the last correspondent referred to by the user. All the name cards pictured above are shown in the name cards scene, the usual setting for name cards.
Your software packages will probably include at least one name card - yours. Including your name card provides the user with information about the package's author and a way to send feedback or ask questions. If your package ever asks the user to choose a correspondent, as when addressing a telecard, you'll probably use the people picker, a built-in window that displays all the names in the name card stack.
This chapter includes general information on how name cards work. You may find this information useful for creating various kinds of communicating packages and for debugging.
For more information on writing communicating packages, see this book's Electronic Mail chapter.
When a name card appears on the screen, it includes information about the correspondent, such as the correspondent's name, e-mail and postal addresses, voice and data phone numbers, and any other miscellaneous viewables, such as stamps or shapes. Although all these elements are drawn on the screen with the name card, the data for most of them is provided by an object of class AddressCard that the name card refers to in its addressCard field. The only elements that aren't part of the address card are the stamps and other miscellaneous viewables on the name card, which are stored as subviews of the name card itself.
Magic Cap users can create four kinds of name cards: person name cards, company name cards, group name cards, and communication service provider name cards.
Name cards are rarely found anywhere other than in the name cards stack (iNameCardsStack). Name cards in the name cards stack are displayed in the name cards scene (iNameCardsScene). When a name card is not in the name cards stack, it is displayed in the single name card scene (iSingleNameCardScene), as shown in the following figure:
Name card in single name card scene
In the single name card scene, the user can touch the buttons at the right to add the card to the name cards stack or to put it in the trash. There are two ways for the user to make name cards that are outside the name cards stack: by mailing a name card, which makes a copy and puts the copy on a telecard, and by discarding a name card, which puts it in the trash. In addition, Magic Cap will add name cards silently if the user has the Automatically collect name cards from incoming messages rule turned on.
Name cards can enter the name cards stack in various ways:
When a name card in the name cards stack appears on the screen, it gathers information from its address card and displays that information on the screen along with its own subviews.
Every name card refers to an address card, an object of class AddressCard that gives the name card its identity and all its contact information, such as addresses and telephone numbers. Despite the name of their class, address cards are not members of class Card. In fact, address cards are not viewable objects at all. Instead, they contain information that a name card uses to present information about a correspondent.
VERSION NOTE: In addition to providing the fundamental identity and contact information for correspondents, address cards have information that is useful mainly for AT&T PersonaLink and other Magicmail- and Telescript-based communication services. This draft of Magic Cap Concepts provides minimal information about using Telescript from Magic Cap, and creating Telescript services requires an additional product, the Telescript Developer Kit, which is available through a special license.
The correspondent's name is available in its MagicName attribute, which returns an object of class MagicmailName. Despite the references to Magicmail in the attribute and class names, this attribute provides the name of the correspondent for all uses, not just for Magicmail services. You can get the correspondent's name as a text string by calling its GetName operation.
You can use the address card's Addresses attribute to get and set the correspondent's addresses and phone numbers. The Addresses attribute returns an object list that refers to all the correspondent's address labels.
For more information on getting and setting the correspondent's name and addresses, see the Names, Addresses, and Phone Numbers section below.
You can call Category on the address card to determine what kind of correspondent it represents, as follows:
/* AddressCard Category constants */ #define categoryUnspecified 0 /* unknown kind */ #define categoryPerson 1 #define categoryCompany 2 #define categoryDistributionList 3 /* reserved - future use */ #define categoryProvider 4 #define categoryGroup 5
Address cards provide a number of features that support sending and receiving mail. This section discusses the mail features of address cards that are available to all communication services and to Magic Cap packages in general.
When the user sends a telecard to the correspondent, the address card records the address label that was used. The next time the user addresses a telecard to that correspondent, Magic Cap uses the same address label (although the user can change it). You can get and set the most recently used address label by using the address card's LastLabel attribute.
You can verify that the user is able to contact a particular communication service by calling MakeReadyToCommunicate on the address card. This operation ensures the following: the current location and its dialing prefix are set, the current user has been set and has an assigned name, an encoded name used for authentication with a service, and the user is registered with the given service. If any of these conditions is false, Magic Cap shows a window that prompts the user for the necessary information, as shown in the following figure. The windows are shown in turn if more than one is needed.
Windows shown by MakeReadyToCommunicate
If all the necessary information isn't available and the user doesn't enter the missing items, MakeReadyToCommunicate returns false.
The address card's AssignedName attribute returns its telename, used by Telescript services to determine identity. You can call IsPeer on the address card to determine if two address cards have the same assigned name and so refer to the same correspondent. For a broader comparison, you can call IsSameCorrespondent, which compares two address cards using several criteria, including magic name, which is the correspondent's name expressed as a text object and a list of sort keys, and the assigned name, if any. You can also call IsSameNamedCorrespondent, which requires that the address cards being compared have the same magic name before performing any further comparison.
This section describes the operations provided by address cards for working with their name and address information. You can call GetName and SetName to get and set the correspondent's name using text strings. You can also get and set the correspondent's name with text objects by using the NameText attribute. You can use the Addresses attribute to get and set the correspondent's list of address labels.
Address cards include attributes for getting and setting various parts of the correspondent's name independently. Use the FirstAndMiddleName and LastName attributes to get and set those parts of the correspondent's name using text objects.
You can call Empty to see if the address card has any addresses. Empty returns true if the address card has no address labels, or if it has address labels that are all empty.
You can call DisplayedPostalAndEmailLabelCount on the address card to get the number of postal labels and e-mail labels on the name card. To get a particular postal or e-mail label from this set, call DisplayedPostalOrEmailLabel.
The last phone label entered or used on the address card becomes its current phone label. You can use address card attributes to get and set information about the current phone label. Use the Telephone attribute to get or set the label's telephone number and the Telenumber attribute to access the label's telenumber object.
Every phone label has a telenumber that gives its telephone number, country, and extension, and every telenumber has a locale, an object that provides more information about the country where the telenumber is located, such as its dial-out and dial-in codes. You can call Country on the address card to get the country of the first phone label on the card, or you can call Locale on the address card to get the locale of the first phone label.
You can call GoTo on an address card to go to the name cards scene and display the name card that refers to the given address card.
Magic Cap provides several operations for creating, destroying, and working directly with name cards. If you want to allow the user to create name cards, you'll probably use the people picker rather than creating them from your code. If you want more control or want to perform a more specific task than letting the user create a name card, you can use the operations described in this section.
You can create a new, blank name card and allow the user to enter its name by calling EditNewCard on the name cards scene. You can edit the name on the current name card by calling EditName on the name cards scene.
If you have an address card and you want to make a name card for it, you can call MakeNameCard to create the new name card. If you have an address card, you can create the new name card and install it in the name cards stack by calling InsertNameCard, which calls MakeNameCard for you. To add an existing name card to the name cards stack, use MoveToStack as in the following example:
MoveToStack(nameCard, iNameCardsStack);
Magic Cap maintains built-in lists of name cards of people, companies, services, and groups. When the user creates a new name card, Magic Cap calls Categorize on the address card to add it to the appropriate list.
You can delete a name card and the address card it rode in on by calling DestroyAndForget. If the name card is on screen, it zooms down to a minicard, and the minicard hops to the trash. The address card might be shared with another name card. If so, the address card won't be destroyed.
You'll probably include a name card for your company or yourself in your package. Including your name card provides a way for users to contact you for support or other information about your package. When you create your name card, you'll also create an address card and other related information, including a telename and its two octet strings. For complete information on how to specify your telename, see the Citation chapter in Magic Cap Class and Method Reference.
When the user touches the name cards icon on the desk, Magic Cap goes to the name cards scene and shows the current card in the name cards stack. The name cards stack contains two different kinds of cards: name cards and index cards. Index cards provide a list of all the cards that are filed under two consecutive letters, as shown in the following figure:
Index card
All the name cards share the same form, and all index cards share another form. The name cards form has several subviews, including a panel for addresses, another panel for phone numbers, and a group list view for showing members if the card is a group card. When a name card in the name cards scene is about to appear on the screen, Magic Cap makes the panels targets of the address card, which causes the panels to draw address and phone number information from the labels on the address card.
When a name card in the name cards scene is about to appear on the screen, Magic Cap calls the name card's AboutToShow operation, which eventually calls NameCardForm_AttachToCard to set up the card for display. AttachToCard calls AddressCardChanged, which makes the panels targets of the address card. When the panels are drawn, they get the address and phone number information from the labels on their target address card.
Given an address card, you can find a name card that refers to that address card by calling FindMatchingNameCard on the name cards scene. You can find a particular name card by calling various methods of class NameCardsStack, including FindAddressCard, FindAssignedName, and FindByAuthority.
Every name card refers to an address card, which contains most of the information about the correspondent represented by the name card. In addition, every name card displays an image in its upper-left corner. When a name card is on screen, the name card form supplies panels for its addresses and phone numbers, or a group list view for its members if it is a group card.
You can get and change the name card's address card by using the AddressCard attribute. You can also get and set the image on the name card by using the Image attribute. If the image is changed to one that is larger or smaller than the image it replaces, Magic Cap automatically repositions the phone panel to accommodate the new image.
You can get the name card form's address panel by calling its AddressPanel operation. There is no corresponding operation to get the phone panel. If you need to get the phone panel, you can get the form, then search the form's subviews for a member of class PhonePanel.
If you want the user to work with the name cards in the name cards stack while staying in your package's scene, you can use the people picker window to provide a list of all the entries in the name cards stack. To use the people picker, your package must have an object that inherits from class PeopleListTarget to act as the target of the people picker. After you set the people picker's target to your object, simply show the people picker. When the user selects an entry and touches accept, Magic Cap calls the target's SetEntity operation, passing the chosen entry as the parameter.
Given the code in the following example, your package can call LetUserChooseEntity to show the people picker. When the user touches accept, Magic Cap will call the target's SetEntity operation.
The following example demonstrates how to use the people picker:
Private void
LetUserChooseEntity(void)
{
SetTarget(iPeoplePicker, targetObject); /* set up */
/* targetObject is an object of class TargetClass */
/* (see following method) */
Show(iPeoplePicker); /* show the people picker and */
/* it works independently */
}
Method void
TargetClass_SetEntity(ObjectID self, ObjectID newEntity)
{
/* Magic Cap calls here when user touches _accept_ */
/* in people picker. */
/* This method is defined by the class of the people */
/* picker's target. This class must inherit from */
/* PeopleListTarget. */
/* newEntity is an address card that corresponds to */
/* the user's choice. You can use it however you like. */
/* For example, the following example is a simplified */
/* version of how group address cards use SetEntity to */
/* add new group members: */
/* First, check to see if user has tried to add group */
/* to itself. This isn't allowed; honk if so */
if (IsSameNamedCorrespondent(self, newEntity)) Honk();
else
{
/* Now see if user has tried to add someone who is */
/* already in the group. If so, just ignore it. */
if (HasCorrespondent(self, newEntity)) return;
/* Finally, if user has picked a good one, add it to */
/* the group. */
AddMember(self, newEntity);
}
Each name card refers to an address card that contains most of the information about the name card's correspondent. Name cards for people and companies get their contact information from objects of class AddressCard. Group name cards refer to objects of class GroupAddressCard, while name cards for communication service providers refer to objects of class ProviderAddressCard. When the user creates a new name card, the appropriate kind of address card is also created and is connected to the name card.
You can use the group address card's MemberList attribute to get and set the list of members of the group. The list is an alphabetical list that refers to the address cards of group members.
You can call AddMember or RemoveMember on the group address card to change the group by adding or removing address cards. You can call HasCorrespondent on the group address card to determine if the group includes a particular address card.
Class GroupAddressCard inherits from class PeopleListTarget, which allows group address cards to be the target of the people picker. This capability lets the user add names to the group by choosing them from the people picker. The preceding section has an example of how GroupAddressCard uses the people picker.
To determine if the current user of the communicator (not necessarily the correspondent of the current name card) is registered with a communication service, call the provider address card's IsDeviceOwnerRegistered operation.
You can use the Service attribute of provider address cards to get and set the electronic mail service that the address card refers to. You can call CollectMail on the provider address card to connect to the service and collect mail.
For more information, see the following topics in Magic Cap Class and Method Reference:
class AddressCard
operations and attributes:
AddressCount Addresses AssignedName Categorize Category Country DisplayedPostalAndEmailLabelCount DisplayedPostalOrEmailLabel Empty FirstAndMiddleName GetName GoTo IsPeer IsSameCorrespondent IsSameNamedCorrespondent LastLabel LastName Locale MagicName MakeReadyToCommunicate NameText PhoneCount PhoneDescription PhoneLabel SetName Telenumber Telephone
class GroupAddressCard
operations and attributes:
AddMember HasCorrespondent MemberList RemoveMember
class NameCard
operations and attributes:
DestroyAndForget Image InsertNameCard MakeNameCard MoveToStack
fields:
addressCard
class NameCardsScene
operations and attributes:
EditName EditNewCard FindMatchingNameCard
class NameCardsStack
operations and attributes:
FindAddressCard FindAssignedName FindByAuthority
class NameCardForm
operations and attributes:
AddressPanel
class ProviderAddressCard
operations and attributes:
CollectMail IsDeviceOwnerRegistered Service
indexicals:
iNameCardsScene iNameCardsStack
Book Contents Previous Chapter Next Chapter