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 ContactPickerUIpublic sealed class ContactPickerUIPublic NotInheritable Class ContactPickerUIpublic sealed class ContactPickerUI
Attributes
Windows 10 requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

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

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";
                }
            }

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<string> DesiredFields { get; }public IVectorView<string> DesiredFields { get; }Public ReadOnly Property DesiredFields As IVectorView<string>public IVectorView<string> DesiredFields { get; }
Value

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

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

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 IVector<ContactFieldType> DesiredFieldsWithContactFieldType { get; }Public ReadOnly Property DesiredFieldsWithContactFieldType As IVector<ContactFieldType>public IVector<ContactFieldType> DesiredFieldsWithContactFieldType { get; }
Value

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

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

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 ContactSelectionModepublic ContactSelectionMode SelectionMode { get; }
Value
ContactSelectionMode ContactSelectionMode ContactSelectionMode ContactSelectionMode

Specifies the selection mode that you want to use.

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

Methods

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

Note

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

Adds a Contact.

public AddContactResult AddContact(String id, Contact contact)public AddContactResult AddContact(String id, Contact contact)Public Function AddContact(id As String, contact As Contact) As AddContactResultpublic AddContactResult AddContact(String id, Contact contact)
Parameters
id
System.String System.String System.String System.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.

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

Remarks

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;
    }
}

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

Adds a Contact.

Note

The Id property must be set when you call AddContact(Contact). If 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 AddContactResultpublic AddContactResult AddContact(Contact 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.

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

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

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

Note

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

public bool ContainsContact(String id)public bool ContainsContact(String id)Public Function ContainsContact(id As String) As boolpublic bool ContainsContact(String id)
Parameters
id
System.String System.String System.String System.String

The ID of the contact.

Returns
bool bool bool bool

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

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

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

Removes a contact.

Note

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

public void RemoveContact(String id)public void RemoveContact(String id)Public Function RemoveContact(id As String) As voidpublic void RemoveContact(String id)
Parameters
id
System.String System.String System.String System.String

The ID of the contact to remove.

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

Events

ContactRemoved ContactRemoved ContactRemoved ContactRemoved

Occurs when the user deselects or removes the contact.

public event TypedEventHandler ContactRemovedpublic event TypedEventHandler ContactRemovedPublic Event ContactRemovedpublic event TypedEventHandler ContactRemoved
Attributes
Additional features and requirements
Device family
Windows 10 (introduced v10.0.10240.0)
API contract
Windows.Foundation.UniversalApiContract (introduced v1)

Remarks

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.

}