The purpose of this API is to display a contacts dialog and\nallow a user to select a contact
\n\n\n//\n// show contact picker\n//\n\n//\n// if array of details is specified, the detail view will be shown\n// when the contact is selected. this will also trigger e.key, and e.index in the success callback\n//\nTitanium.Contacts.showContactPicker({\n\n success:function(event)\n {\n // e.contact\n // e.key\n // e.index\n\n },\n cancel:function()\n {\n // user canceled\n },\n details:[array of constants]\n);\n\n//\n// Supported Contact property names \n//\nfirstName\nlastName\nmiddleName\nprefix\nsuffix\nnickname\nfirstNamePhonetic\nlastNamePhonetic\nmiddleNamePhonetic\norganization\njobTitle\ndepartment\nbirthday\nnote\ncreationDate\nmodificationDate\nimageData\nphoneNumber\naddress\nemail\n\n//\n// get all contacts\n//\nvar contacts = Titanium.Contacts.getAllContacts()\nvar c = contacts[0];\nvar birthday = c.birthday\n\n// remove contact\nTitanium.Contacts.removeContact(c);\n\n// modify contact\nc.firstName = 'Fred';\nTitanium.Contacts.saveContact(c);\n\n\n//\n// create new contact\n//\nvar c = Titanium.Contacts.createContact({\n firstName:'Fred',\n lastName:'Smith'\n\n})\n\nTitanium.Contacts.addContact(c);\n\n//\n// create new contact using multi-value fields like email, phone and address\n//\nvar c = Titanium.Contacts.createContact({\n email:[{label:'home', value:'foo@foo.com'}],\n phone:[{label:'home', value:'3032223333'}],\n address:[{label:'home', value:[{city:'Foo', state:'GA', zip:'40344', street1:'value', street2:'value'}]\n})\nWe'll probably want to add functionality later on for being able\nto pick not only a person, but other UI features:
\nPick a person and a property (IE, phone number out of several),\ncomplete with a filter of what to show.
\n(See \nhttp://developer.apple.com/IPhone/library/documentation/AddressBook...:\n)
View a person that's been chosen from the database, filter of\nwhat to show, allow editing of it, etc. The callback should return\na boolean on whether to act on user input. (IE, if the user touched\nthe phone number, to launch the phone)
\n(See \nhttp://developer.apple.com/IPhone/library/documentation/AddressBook...\n)
Present an 'add a person' dialog, with prepopulated properties,\nand let them add it to the address book.
\n(See \nhttp://developer.apple.com/IPhone/library/documentation/AddressBook...\n)
Present an 'unknown person' (IE, could be new person, could be\nold person and the data needs merging) which has the new person\ndynamicness as well as the ability to launch actions like view a\nperson.
\n(See \nhttp://developer.apple.com/IPhone/library/documentation/AddressBook...\n)
Notes to self:
\nMore flies in the ointment. While the properties are integers on\nthe native side, accessing images are done with a completely\ndifferent function. Fetching this all for getAllContacts is\nprohibitive. The image blobs alone would take too much memory all\nat one time.
\nNot only that, but it's unlikely that Android will have the same\nvalues. So perhaps we should use string values and do the mapping\nnative-side.
\nSo the data sent to the callback must be an array of\nlazy-loading objects with the following properties:
\n_REFID:,
\n_CACHE:{dict of fetched values},
\n_DELTA:{dict of js-set values},
\ngetFoo:function(){
\nif(this.DELTA.foo)return this.DELTA.foo;
\nif(this.CACHE.foo===undefined)this.CACHE.foo =\nTi.TIDO('contacts','getContactProperty',[this.REFID,'foo']);
\nreturn this._CACHE.foo;
\n},
\nsetFoo:function(newFoo){this._DELTA.foo=newFoo;}
\nappropriate setters and getters for every foo. I'm thinking\nmaking an object class for this. The win here also is that there\nneed not be any native-side caching contacts, and when saving a\ncontact, only the delta need be sent back.
\nActually, this pattern may be very useful in other objects.
this is mostly implemented and tested for iphone.
\nhowever, it crashes when you pass @ symbol to email\nproperty when creating a contact.
Ready for testing.
add read only properties w/ getters.
\ndisplayLabel (map to display value in \"pick list\" style, e.g.\nCompany if no person name)
\ndisplayName (constructed from Person Name Attributes Prefix, First,\nMiddle, Last Suffix)
\ndisplayAddress (Address String a concatenation of the pieces)
\ndisplayPhoneticName (same as displayName using phonetic values,\ndoes not include prefix and suffix)
Ready for testing.