ContactPickerUI ContactPickerUI ContactPickerUI ContactPickerUI Class

Definition

Allows you to call the contact picker UI so you can select one or more contacts.

public : sealed class ContactPickerUI : IContactPickerUI, IContactPickerUI2
public sealed class ContactPickerUI : IContactPickerUI, IContactPickerUI2
Public NotInheritable Class ContactPickerUI Implements IContactPickerUI, IContactPickerUI2
// This class does not provide a public constructor.
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem

Examples

This example code prepares the page to use ContactPickerUI:


var contactPickerUI;

    var page = WinJS.UI.Pages.define("/html/contactPickerScenario.html", {
        processed: function (element, uri) {
            // During an initial activation this event is called before the system splash screen is torn down.
            sampleContacts.forEach(createContactUI);
        },

        ready: function (element, options) {
            // During an initial activation this event is called after the system splash screen is torn down.
            // Do any initialization work that is not related to getting the initial UI setup.
            contactPickerUI = options.contactPickerUI;
            contactPickerUI.addEventListener("contactremoved", onContactRemoved, false);
        },

        unload: function () {
            contactPickerUI.removeEventListener("contactremoved", onContactRemoved, false);
        }
});
        ContactPickerUI contactPickerUI = MainPagePicker.Current.contactPickerUI;
        CoreDispatcher dispatcher = Window.Current.Dispatcher;

        public ContactPickerPage()
        {
            this.InitializeComponent();
            ContactList.ItemsSource = contactSet;
            ContactList.SelectionChanged += ContactList_SelectionChanged;
        }

        protected override void OnNavigatedTo(NavigationEventArgs e)
        {
            contactPickerUI.ContactRemoved += contactPickerUI_ContactRemoved;
        }

        protected override void OnNavigatedFrom(NavigationEventArgs e)
        {
            contactPickerUI.ContactRemoved -= contactPickerUI_ContactRemoved;
        }

        async void contactPickerUI_ContactRemoved(ContactPickerUI sender, ContactRemovedEventArgs args)
        {
            // The event handler may be invoked on a background thread, so use the Dispatcher to run the UI-related code on the UI thread.
            string removedId = args.Id;
            await dispatcher.RunAsync(CoreDispatcherPriority.Normal, () =>
            {
                foreach (SampleContact contact in ContactList.SelectedItems)
                {
                    if (contact.Id == removedId)
                    {
                        ContactList.SelectedItems.Remove(contact);
                        OutputText.Text += "\n" + contact.DisplayName + " was removed from the basket";
                        break;
                    }
                }
            });
        }

This example code shows how to add a contact to the basket with the AddContact(Contact) method.


// Add the contact to the basket
var statusMessage = document.getElementById("statusMessage");
     switch (contactPickerUI.addContact(contact)) {
     case Windows.ApplicationModel.Contacts.Provider.AddContactResult.added:
         // Notify user that the contact was added to the basket
         statusMessage.innerText = contact.displayName + " was added to the basket";
         break;
     case Windows.ApplicationModel.Contacts.Provider.AddContactResult.alreadyAdded:
         // Notify the user that the contact is already in the basket
         statusMessage.innerText = contact.displayName + " is already in the basket";
         break;
     case Windows.ApplicationModel.Contacts.Provider.AddContactResult.unavailable:
     default:
         // Notify the user that the basket is not currently available
         statusMessage.innerText = contact.displayName + " could not be added to the basket";
         break;
}
            switch (contactPickerUI.AddContact(contact))
            {
                case AddContactResult.Added:
                    // Notify the user that the contact was added
                    OutputText.Text = contact.DisplayName + " was added to the basket";
                    break;
                case AddContactResult.AlreadyAdded:
                    // Notify the user that the contact is already added
                    OutputText.Text = contact.DisplayName + " is already in the basket";
                    break;
                case AddContactResult.Unavailable:
                default:
                    // Notify the user that the basket is unavailable
                    OutputText.Text = contact.DisplayName + " could not be added to the basket";
                    break;
            }

This example code shows how to remove a contact from the basket and respond to its removal.

function removeContactFromBasket(sampleContact) {
    // Programmatically remove the contact from the basket
    if (contactPickerUI.containsContact(sampleContact.id)) {
        contactPickerUI.removeContact(sampleContact.id);
        document.getElementById("statusMessage").innerText = sampleContact.displayName + " was removed from the basket";
    }
}
            foreach (SampleContact removed in e.RemovedItems)
            {
                if (contactPickerUI.ContainsContact(removed.Id))
                {
                    contactPickerUI.RemoveContact(removed.Id);
                    OutputText.Text = removed.DisplayName + " was removed from the basket";
                }
            }

Remarks

To see an example of how to use this class, check out our code sample.

Properties

DesiredFields DesiredFields DesiredFields DesiredFields

Note

DesiredFields may be altered or unavailable for releases after Windows 8.1. Instead, use DesiredFieldsWithContactFieldType.

Specifies the fields that you want returned after the user selects one or more contacts.

public : IVectorView<Platform::String> DesiredFields { get; }
public IReadOnlyList<string> DesiredFields { get; }
Public ReadOnly Property DesiredFields As IReadOnlyList<string>
var iReadOnlyList = contactPickerUI.desiredFields;
Value
IVectorView<Platform::String> IReadOnlyList<string> IReadOnlyList<string> IReadOnlyList<string>

A collection of fields that you want returned. You can specify which fields you want through the KnownContactField class.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem

Remarks

To see an example of how to use this property, check out our code sample.

DesiredFieldsWithContactFieldType DesiredFieldsWithContactFieldType DesiredFieldsWithContactFieldType DesiredFieldsWithContactFieldType

Gets the fields with contact field type that you want returned after the user selects one or more contacts.

public : IVector<ContactFieldType> DesiredFieldsWithContactFieldType { get; }
public IList<ContactFieldType> DesiredFieldsWithContactFieldType { get; }
Public ReadOnly Property DesiredFieldsWithContactFieldType As IList<ContactFieldType>
var iList = contactPickerUI.desiredFieldsWithContactFieldType;
Value
IVector<ContactFieldType> IList<ContactFieldType> IList<ContactFieldType> IList<ContactFieldType>

A collection of fields of contact field type that you want returned. The ContactFieldType values specify which fields you want.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem

SelectionMode SelectionMode SelectionMode SelectionMode

Determines the selection mode for the contact picker. The most common options are PickSingleContactAsync or PickMultipleContactsAsync.

public : ContactSelectionMode SelectionMode { get; }
public ContactSelectionMode SelectionMode { get; }
Public ReadOnly Property SelectionMode As ContactSelectionMode
var contactSelectionMode = contactPickerUI.selectionMode;
Value
ContactSelectionMode ContactSelectionMode ContactSelectionMode ContactSelectionMode

Specifies the selection mode that you want to use.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem

Methods

AddContact(String, Contact) AddContact(String, Contact) AddContact(String, Contact) AddContact(String, Contact)

Note

AddContact may be altered or unavailable for releases after Windows 8.1. Instead, use AddContact without the ID.

Adds a Contact.

public : AddContactResult AddContact(Platform::String id, Contact contact)
public AddContactResult AddContact(String id, Contact contact)
Public Function AddContact(id As String, contact As Contact) As AddContactResult
var addContactResult = contactPickerUI.addContact(id, contact);
Parameters
id
Platform::String String String String

The ID for the contact.

contact
Contact Contact Contact Contact

An object that contains the contact's information.

Returns

An AddContactResult -typed value that indicates whether the contact was added successfully.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem

Examples

This example code adds a contact to the contact picker.

function addContact (sampleContact) {
// Generate the Contact object to be added
var contact = createContactForBasket(sampleContact);

// Add the Contact object to the basket
var statusMessage = document.getElementById("statusMessage");
     switch (contactPickerUI.addContact(contact)) {
     case Windows.ApplicationModel.Contacts.Provider.AddContactResult.added:
         // Notify user that the contact was added to the basket
         statusMessage.innerText = contact.displayName + " was added to the basket";
         break;
     case Windows.ApplicationModel.Contacts.Provider.AddContactResult.alreadyAdded:
         // Notify the user that the contact is already in the basket
         statusMessage.innerText = contact.displayName + " is already in the basket";
         break;
     case Windows.ApplicationModel.Contacts.Provider.AddContactResult.unavailable:
     default:
         // Notify the user that the basket is not currently available
         statusMessage.innerText = contact.displayName + " could not be added to the basket";
         break;
    }
}
See Also

AddContact(Contact) AddContact(Contact) AddContact(Contact) AddContact(Contact)

Adds a Contact.

Note

The Contact.Id property must be set when you call AddContact. If Contact.Id isn't set, your app will fail.

public : AddContactResult AddContact(Contact contact)
public AddContactResult AddContact(Contact contact)
Public Function AddContact(contact As Contact) As AddContactResult
var addContactResult = contactPickerUI.addContact(contact);
Parameters
contact
Contact Contact Contact Contact

An object that contains the contact's information.

Returns

An AddContactResult -typed value that indicates whether the contact was added successfully.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem
See Also

ContainsContact(String) ContainsContact(String) ContainsContact(String) ContainsContact(String)

Checks to see whether the contact was already selected by the user.

Note

The Contact.Id property must be set when you call ContainsContact. If Contact.Id isn't set, your app won't be able to find the contact.

public : Platform::Boolean ContainsContact(Platform::String id)
public bool ContainsContact(String id)
Public Function ContainsContact(id As String) As bool
var bool = contactPickerUI.containsContact(id);
Parameters
id
Platform::String String String String

The ID of the contact.

Returns
Platform::Boolean bool bool bool

True if the contact has already been selected; otherwise, false.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem
See Also

RemoveContact(String) RemoveContact(String) RemoveContact(String) RemoveContact(String)

Removes a contact.

Note

The Contact.Id property must be set when you call RemoveContact. If Contact.Id isn't set, your app won't be able to remove the contact.

public : void RemoveContact(Platform::String id)
public void RemoveContact(String id)
Public Function RemoveContact(id As String) As void
contactPickerUI.removeContact(id);
Parameters
id
Platform::String String String String

The ID of the contact to remove.

Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem
See Also

Events

ContactRemoved ContactRemoved ContactRemoved ContactRemoved

Occurs when the user deselects or removes the contact.

public : event TypedEventHandler ContactRemoved<ContactPickerUI,  ContactRemovedEventArgs>
public event TypedEventHandler ContactRemoved<ContactPickerUI,  ContactRemovedEventArgs>
Public Event TypedEventHandler ContactRemoved( Of ( Of ContactPickerUI ), ( Of  ContactRemovedEventArgs ))
function onContactRemoved(eventArgs){/* Your code */}


contactPickerUI.addEventListener("contactRemoved", onContactRemoved);
contactPickerUI.removeEventListener("contactRemoved", onContactRemoved);
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)
Capabilities
contactsSystem

Examples


var contactPickerUI = null;  

function activatedHandler(ev) {  
    if (ev.detail[0].kind == Windows.ApplicationModel.Activation.ActivationKind.contactPicker) {  
        contactPickerUI = ev.detail[0].contactPickerUI;  
        contactPickerUI.addEventListener("contactremoved", onContactRemoved);  
    }  
}

function onContactRemoved(e) {
    var contactId = e.id;

    // TODO: Respond to removal of this contact.

}