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, IContactPickerUI2public sealed class ContactPickerUI : IContactPickerUI, IContactPickerUI2Public NotInheritable Class ContactPickerUI Implements IContactPickerUI, IContactPickerUI2
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

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>
Value

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

Attributes

Remarks

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

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>
Value

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

Attributes

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
Value
ContactSelectionMode ContactSelectionMode ContactSelectionMode

Specifies the selection mode that you want to use.

Attributes

Methods

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

The ID for the 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

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)

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
Parameters
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

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 bool ContainsContact(String id)public bool ContainsContact(String id)Public Function ContainsContact(id As String) As bool
Parameters
id
System.String System.String System.String

The ID of the contact.

Returns
bool bool bool

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

Attributes
See Also

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(String id)public void RemoveContact(String id)Public Function RemoveContact(id As String) As void
Parameters
id
System.String System.String System.String

The ID of the contact to remove.

Attributes
See Also

Events

ContactRemoved ContactRemoved ContactRemoved

Occurs when the user deselects or removes the contact.

public event TypedEventHandler ContactRemovedpublic event TypedEventHandler ContactRemovedPublic Event ContactRemoved
Attributes

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.

}