FullContact

AcceptEdit Acclimatize AddAddress AddDefaultAddresses AddMember AddNewAddress AddToDisplayView AddressCount AddressImage AddressIndex AddressInfoByTypeNear AddressInfoNear AlternateKey BeginEdit CanSendTo CategorizeByImage

ChangedAddress Clear CompareByName Confirm CopyAddresses CopyIntoSystem Copying CountByType CreateMailLabel DefaultInstallLocation DisambiguateDisplayName EachAddress Eliminate FileTo Finalize FindAddressByAttribute

FindFullContactByName FullContact GoTo HasCorrespondent HasPagerLabel Init InitialExtraSize InstalledReceiver LetterIndex MakeFullContactFromSimpleContactNear MakeSimpleContactNear MakeSimpleContactWithAddressNear MakeSimpleContactWithNoAddressNear MergeAddressesAndViewables NamePart

NextStepList PhoneCount PreferredDeliveryChoice RememberDeliveryChoice RemoveAddress RemoveAddressInfo RemoveDefaultAddresses RemoveFromDisplayView RemoveMember SearchByCorrespondent SetNamePart SpecifiedLabelMatches Stabilize UpdateContactFields Validate

Attributes

AllNameParts CanDelete CanDelete CanFileIntoFileCabinet CanGoTo Category Category Count DisambiguatingInteger DisplayName DisplayNameForSortedList

DisplayView Empty Entity Entity FilingChoiceImage GivenName GoToAfterFiling IdentifyingName Image IsCompany MemberList

Name Name NativeGivenName NativeSurname NeedsInstallEntry Nickname RomanGivenName RomanName RomanSurname SalutationName

SelectedMemberIndex SenderName SenderOrRecipientName SortName SortNameGivenName SortNameSurname Subject Surname TypeDescription UserEdited

Fields

instance FullContact tag;
          flags: 0;
    attachments: nilObject;
end instance;

Define Class FullContact;
    inherits from Object;
    inherits from Contact;
    inherits from PeopleListTarget;
    inherits from EditAttributeClient, CanBeFiled, HasAddress, HasCount;
    inherits from HasContent;
    
    uses extra;

    field flags: Unsigned;
    field attachments: ObjectList;
    
    // localizable name accessors
    // localization typically affects character set (native vs. roman) and name order (surname first or given name first)
    // for non-persons, the attributes have the following equivalences:
    //      GivenName = Surname = Name
    //      RomanGivenName = RomanSurname = RomanName
    //      SortNameGivenName = SortNameSurname = SortName

    overrides Name, SetName;
        // Name provides full name
        // SetName replaces complete name information with name parts extracted from new name
    overrides DisplayName;
        // full name, possibly with disambiguating integer
    overrides DisplayNameForSortedList;
        // full name, possibly with disambiguating integer, format adjusted for sorted list if necessary
    overrides SortName;
        // version to be used for sorting, may not look like Name at all
    overrides GivenName;
    overrides Surname;
    attribute NativeGivenName: Text;
    attribute NativeSurname: Text;
    attribute RomanGivenName: Text;
    attribute RomanSurname: Text;
    attribute RomanName: Text, readOnly;
        // romanized versions of GivenName, Surname, Name, different only if GivenName/Surname/Name use non-Roman characters
    attribute SortNameGivenName: Text;
    attribute SortNameSurname: Text;
        // accessors for editing sort name
    overrides IdentifyingName;
    overrides SalutationName;
        // name used when addressing a message
    attribute Nickname: Text;
        // returns nickname if available, given name otherwise; sets nickname

    // name-related auxiliary information

    operation LetterIndex(): UnsignedShort;
        // returns a number between 1 and a locale-dependent limit (typically in the 20s),
        // depends on the first character(s) in the SortName
        // determines in which sublist of an ContactsMasterList this entity goes
    attribute DisambiguatingInteger: Unsigned;
        // lets the user distinguish between two otherwise identical names
    operation DisambiguateDisplayName();
    
    // low level interface called by name formatters
    
    operation NamePart(selector: Unsigned): Text;
    operation SetNamePart(selector: Unsigned; newName: Text);
    attribute AllNameParts: Text;
        //returns a newLine delimited text object where each line corresponds to a name part.  It
        //is used to get and set the entire name
    
    // general attributes
    
    overrides Category;
    overrides SetCategory;
    attribute IsCompany: Boolean;
        // getter returns whether the contact represents a company
        // setter switches between company and person, adjusting name and image information
    overrides Empty;
        // true if there's no address information attached
    overrides Entity, SetEntity;
    attribute Image: Image;
    attribute UserEdited: Boolean;
        // returns true if the user has ever directly modified the contact
        
    // creation

    overrides Init, InitialExtraSize;   
    intrinsic MakeFullContactFromSimpleContactNear(contact: SimpleContact; nearThis: Object): FullContact;
        // given a simple contact, creates a full contact near nearThis and adds an addressInfo with the address that is stored in the simple contact

    // comparison

    intrinsic CompareByName(first: FullContact; second: FullContact): SignedShort;
        // call to compare two contacts by their sort names
    
    // accessing addresses
    
    operation AddressInfoNear(nearThis: Object; whichAddress: Signed): AddressInfo;
        // returns an addressInfo object containing the information in address label specified by whichAddress
    operation AddressInfoByTypeNear(nearThis: Object; whichAddress: Signed; desiredType: Unsigned): AddressInfo;
        // the same as above, except filtered by the desired addressType
    operation AddressImage(whichAddress: Signed): Image;
        // return image associated with address selected by whichAddress
        // this is usually not called, since you usually get the image from the AddressInfo
    operation ChangedAddress(addressInfo: AddressInfo): Boolean;
        // used to check the changes made to an AddressInfo back into the Entity object

    operation EachAddress(doToAddress: EachFunction; nearThis: Object; desiredType: Unsigned; parameters: Pointer): Object;
        // calls <doToAddress> once for each address of the desired type held by the contact
        // if <desiredType> is zero, iterates over all addresses
        // the first parameter passed to <doToAddress> is an AddressInfo created near <nearThis>
        // <doToAddress> is responsible for destroying these AddressInfos as necessary
    overrides CopyAddresses;
        // returns a transient list containing an addressInfo object corresponding to each address held by the contact
        
    // adding and removing addresses    
    
    operation AddNewAddress(newAddressType: Unsigned): Signed;
    operation RemoveAddress(whichAddress: Signed);
    operation RemoveAddressInfo(addressInfo: AddressInfo);
    operation AddAddress(addressToAdd: AddressInfo);
    operation AddDefaultAddresses();    
    operation AddressIndex(address: AddressInfo): Signed;
    operation Clear(), noFail;
    overrides Count;
    operation CountByType(desiredType: Unsigned): Signed;
    operation CreateMailLabel();
    operation RemoveDefaultAddresses();

    operation AddressCount(): Unsigned;
    operation HasPagerLabel(): Boolean;
    overrides PhoneCount;
    overrides Stabilize;
    
    // viewables displayed with this entity

    attribute DisplayView: ObjectList;
    operation AddToDisplayView(addMe: Viewable), noFail;
    operation RemoveFromDisplayView(removeMe: Viewable), noFail;
    
    // mail

    operation CanSendTo(): Boolean, noFail;
        // called by the system to find out if this contact can be sent via
        // a mail service
    overrides PreferredDeliveryChoice;
    overrides RememberDeliveryChoice;

    // EditAttribute client for verifying input, etc
    
    overrides AcceptEdit, BeginEdit, NextStepList;
        
    // relationship with SimpleContact
        // all three of these calls:
        //   set the name of the simple contact object to the display name of the full contact
        //   set the category of the simple contact to the category of its address
        //   set the sort name of the simple contact to the sort name of the full contact
    
    overrides MakeSimpleContactNear;
        // creates a simple contact from one of the addresses
    overrides MakeSimpleContactWithNoAddressNear;
        // creates a simple contact with no address
    operation MakeSimpleContactWithAddressNear(nearThis: Object; whichAddress: Signed): SimpleContact, noFail;
        // creates a simple contact with the selected address

    overrides FullContact;
        // returns self
    
    // support for appearing in list views
    
    overrides SenderName, SenderOrRecipientName;
    overrides Subject, TypeDescription;
    
    // group support

    operation AddMember(newMember: FullContact);
    operation CategorizeByImage(image: Image; addFlag: Boolean), noFail;
    operation HasCorrespondent(correspondent: FullContact): Boolean;
    attribute MemberList: Object, readOnly;
    operation RemoveMember(formerMember: FullContact);
    attribute SelectedMemberIndex: Unsigned;
    
    // filing support
    
    overrides CanFileIntoFileCabinet;
    overrides CopyIntoSystem;
    overrides DefaultInstallLocation;
    overrides FileTo;
    overrides FilingChoiceImage;
    overrides InstalledReceiver;
    attribute NeedsInstallEntry: Boolean;
    overrides GoToAfterFiling;

    // searching
    
    operation FindAddressByAttribute(opNum: OperationNumber; addressType: Unsigned; textToFind: HasText; mainNumber: Unsigned): AddressInfo;
    operation SpecifiedLabelMatches(addressType: Unsigned; index: Unsigned; searchCriteria: Object): Boolean;
        // returns whether <index>th label of type <addressType> matches <searchCriteria>
        // text is matched against both description of label and content
        // image is matched against image of label
        // override rarely
    intrinsic FindFullContactByName(list: HasIterator; name: HasText): FullContact;
        // returns first object in <list> with name that matches <name>
        // returns nilObject if <name> has no characters
    intrinsic SearchByCorrespondent(list: HasIndexing; searchFor: FullContact): Unsigned;
        // call to search for a full contact matching this one in this list
        // comparing using IsSameCorrespondent
        // UI oriented stuff
    
    overrides CanGoTo, GoTo;
        // use GoToContact in iNameCardsScene
        
    // housekeeping
    
    overrides CanDelete, SetCanDelete;
        // returns false for current user's card, and for some service providers    
    overrides Confirm;
    overrides Copying;
        // to copy the display viewables onto the name card if it's a copy of the name
        // card currently being displayed in the name cards scene
    overrides Eliminate;
    overrides Finalize;
        // clears single-pair contact cache if self was the full contact
    operation AlternateKey(): Unsigned;
        // called by the system to compute a key based on the contact for security purposes
    operation UpdateContactFields(newContact: FullContact);
        // replace fields with fields from passed in contact
    operation MergeAddressesAndViewables(newContact: FullContact);
        // adds any addresses or display viewables in newContact that aren't
        // already in self
    
    overrides Acclimatize;
        // recomputes name checksum which may differ in different sort environments
    
#ifdef VALIDATE
    overrides Validate;
#endif
end class;