Titanium.Contacts.Person
An object that represents a contact record for a person or organization in the system contacts address book.
A person object is created using Titanium.Contacts.createPerson.
The following two kinds of properties exist for this object:
- single value - contains either a
stringornumbertype value, an array ofstringtype values, ornullif unset. - multi-value - contains a dictionary with typical keys of
home,workand/orother. Each key contains either astringtype value, an array ofstringtype values, or a dictionary containing key/value pairs withstringtype values.
Adding and Modifying Properties
Support for adding and modifying properties is currently supported on iOS and Android.
Keys as Address Book UI Labels
Keys act as labels in the address book user interface.
Although there is limited support for custom, arbitrarily-named, keys when used with multi-value properties, there is no support them with single value properties.
On iOS, creating custom keys is not recommended, and will lead to undefined results.
If a label has been created by the user of the device and used with a multi-value property, it will exist as a key with the same name.
See examples in Titanium.Contacts for more information.
These APIs are unavailable on macOS if the app is built on a version of Xcode < 12.
Extends: Titanium.Proxy · Since: 0.8, 0.8, 0.8, 9.2.0 · Platforms: android, iphone, ipad, macos
Properties #
address#
Type: Dictionary
Addresses for the person. Multi-value. Read-only on Android.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
home,work, and/orother. - Values: arrays of dictionary types with seven keys,
CountryCode,Street,City,
,State,CountryandPostalCode, each with astringtype value.
On Android:
'CountryCode' and 'County' are currently not supported.
On iOS:
The CountryCode key value may be one of the recognized two-character ISO 3166-1 country
codes, and determines the format in which the contact is presented by the address book
user interface. See the wikipedia section
ISO 3166-1 alpha-2
for a comprehensive list of codes.
alternateBirthday#
Type: Dictionary
Alternate birthday of the person. Single Dictionary.
The format of the dictionary accepted by this property is as follows:
- Keys:
calendarIdentifier,era,year,month,dayandisLeapMonth. - Values: Use
chinese,hebrewandislamic-civilforcalendarIdentifier.
Usenumbertype forera,year,monthandday. These must be consistent with
correspondingcalendarIdentifier.
Usebooleantype forisLeapMonth.
apiName#
Type: String
The name of the API that this proxy corresponds to.
The value of this property is the fully qualified name of the API. For example, Button
returns Ti.UI.Button.
birthday#
Type: String
Date of birth of the person. Single value.
Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"
bubbleParent#
Type: Boolean
Indicates if the proxy will bubble an event to its parent.
Some proxies (most commonly views) have a relationship to other proxies, often
established by the add() method. For example, for a button added to a window, a
click event on the button would bubble up to the window. Other common parents are
table sections to their rows, table views to their sections, and scrollable views
to their views. Set this property to false to disable the bubbling to the proxy's parent.
date#
Type: Dictionary
Dates associated with the person. Multi-value.
Adding or modifying this property is not currently supported.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
anniversaryand/orother. - Values: array of
stringtype.
Date format is "yyyy-MM-ddTHH:mm:ss.SSS+0000"
email#
Type: Dictionary
Email addresses for the person. Multi-value. Read-only on Android.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
home,work, and/orother. - Values: array of
stringtype.
fullName#
Type: String
Localized full name of the person. Single value. Read-only on Android.
The full name will be printed in the order of.
Prefix,first name, middle name, family name, suffix.
image#
Type: Titanium.Blob
Image for the person. Single value. Read-only for >= iOS 9
Set to null to remove the image.
instantMessage#
Type: Dictionary
Instant messenger information of the person. Multi-value.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
home,workand/orother. - Values: arrays of dictionary types with two keys,
serviceandusername, each with a
stringtype value.
The service key value may be one of AIM, Facebook, GaduGadu, GoogleTalk, ICQ,
Jabber, MSN, QQ, Skype, or Yahoo. These values are key sensitive.
kind#
Type: Number
Determines the type of information the person record contains; either person or organization.
Read-only on Android.
lifecycleContainer#
Type: Titanium.UI.Window, Titanium.UI.TabGroup
The Window or TabGroup whose Activity lifecycle should be triggered on the proxy.
If this property is set to a Window or TabGroup, then the corresponding Activity lifecycle event callbacks
will also be called on the proxy. Proxies that require the activity lifecycle will need this property set
to the appropriate containing Window or TabGroup.
phone#
Type: Dictionary
Phone numbers for the person. Multi-value. Read-only on Android.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
home,work,other,mobile,pager,workFax,homeFax,main,
and/oriPhone. - Values: array of
stringtype.
recordId#
Type: Number
Record identifier of the person. Single value. Deprecated since iOS 9.
For iOS 9 and later, use the Titanium.Contacts.Person.identifier property.
Previously, a contact can be selected without requiring User permission. In such case this
property returns -1.
relatedNames#
Type: Dictionary
Names of people to which the person is related. Multi-value.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
mother,father,parent,brother,sister,child,friend,spouse,
partner,assistant,manager, and/orother. - Values: array of
stringtype.
socialProfile#
Type: Dictionary
Social profile information of the person. Multi-value.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
home,workand/orother. - Values: arrays of dictionary types with two keys,
serviceandusernameeach with a
stringtype value.
The service key value may be one of twitter, sinaweibo, gamecenter, facebook,
myspace, linkedin, or flickr. These values are key sensitive.
url#
Type: Dictionary
URLs of webpages associated with the person. Multi-value.
The format of the dictionary accepted by this property is as follows:
- Keys: any of
homepage,home,work, and/orother. - Values: array of
stringtype.
Methods #
addEventListener #
Adds the specified callback as an event listener for the named event.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to invoke when the event is fired. | No |
applyProperties #
Applies the properties to the proxy.
Properties are supplied as a dictionary. Each key-value pair in the object is applied to the proxy such that
myproxy[key] = value.
| Name | Type | Summary | Optional |
|---|---|---|---|
props | Dictionary | A dictionary of properties to apply. | No |
fireEvent #
Fires a synthesized event to any registered listeners.
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
event | Dictionary | A dictionary of keys and values to add to the Titanium.Event object sent to the listeners. | Yes |
removeEventListener #
Removes the specified callback as an event listener for the named event.
Multiple listeners can be registered for the same event, so the
callback parameter is used to determine which listener to remove.
When adding a listener, you must save a reference to the callback function
in order to remove the listener later:
var listener = function() { Ti.API.info("Event listener called."); }
window.addEventListener('click', listener);
To remove the listener, pass in a reference to the callback function:
window.removeEventListener('click', listener);
| Name | Type | Summary | Optional |
|---|---|---|---|
name | String | Name of the event. | No |
callback | Callback<Titanium.Event> | Callback function to remove. Must be the same function passed to addEventListener. | No |