ContactPickerUI ContactPickerUI ContactPickerUI ContactPickerUI Class

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

Syntax

Declaration

public sealed class ContactPickerUIpublic sealed class ContactPickerUIPublic NotInheritable Class ContactPickerUI

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(Windows.ApplicationModel.Contacts.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 summary

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.

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

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

Methods summary

Note

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

Adds a Contact.

Adds a Contact.

Note

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

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

Note

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

Removes a contact.

Note

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

Events summary

Occurs when the user deselects or removes the contact.

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>

    Property Value

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

    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>

    Property Value

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

  • 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

    Property Value

Methods

  • AddContact(System.String,Windows.ApplicationModel.Contacts.Contact)
    AddContact(System.String,Windows.ApplicationModel.Contacts.Contact)
    AddContact(System.String,Windows.ApplicationModel.Contacts.Contact)
    AddContact(System.String,Windows.ApplicationModel.Contacts.Contact)
    Note

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

    Adds a Contact.

    public AddContactResult AddContact(System.String id,Windows.ApplicationModel.Contacts.Contact contact)public AddContactResult AddContact(System.String id,Windows.ApplicationModel.Contacts.Contact contact)Public Function AddContact(id As System.String,contact As Windows.ApplicationModel.Contacts.Contact) As AddContactResult

    Parameters

    • id
      System.String
      System.String
      System.String
      System.String

      The ID for the contact.

    • contact

      An object that contains the contact's information.

    Returns

    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(Windows.ApplicationModel.Contacts.Contact)
    AddContact(Windows.ApplicationModel.Contacts.Contact)
    AddContact(Windows.ApplicationModel.Contacts.Contact)
    AddContact(Windows.ApplicationModel.Contacts.Contact)

    Adds a Contact.

    Note

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

    public AddContactResult AddContact(Windows.ApplicationModel.Contacts.Contact contact)public AddContactResult AddContact(Windows.ApplicationModel.Contacts.Contact contact)Public Function AddContact(contact As Windows.ApplicationModel.Contacts.Contact) As AddContactResult

    Parameters

    Returns

  • ContainsContact(System.String)
    ContainsContact(System.String)
    ContainsContact(System.String)
    ContainsContact(System.String)

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

    Note

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

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

    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.

  • RemoveContact(System.String)
    RemoveContact(System.String)
    RemoveContact(System.String)
    RemoveContact(System.String)

    Removes a contact.

    Note

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

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

    Parameters

    • id
      System.String
      System.String
      System.String
      System.String

      The ID of the contact to remove.

Events

  • ContactRemoved
    ContactRemoved
    ContactRemoved
    ContactRemoved

    Occurs when the user deselects or removes the contact.

    public event TypedEventHandler ContactRemovedpublic event TypedEventHandler ContactRemovedPublic Event ContactRemoved

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

Device family

Windows 10 (introduced v10.0.10240.0)

API contract

Windows.Foundation.UniversalApiContract (introduced v1)

Attributes

Windows.Foundation.Metadata.ContractVersionAttribute

Details

Assembly

Windows.ApplicationModel.Contacts.Provider.dll