| /* |
| * Copyright 2018 The Android Open Source Project |
| * |
| * Licensed under the Apache License, Version 2.0 (the "License"); |
| * you may not use this file except in compliance with the License. |
| * You may obtain a copy of the License at |
| * |
| * http://www.apache.org/licenses/LICENSE-2.0 |
| * |
| * Unless required by applicable law or agreed to in writing, software |
| * distributed under the License is distributed on an "AS IS" BASIS, |
| * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| * See the License for the specific language governing permissions and |
| * limitations under the License. |
| */ |
| |
| package androidx.core.app; |
| |
| import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP_PREFIX; |
| |
| import android.os.Bundle; |
| import android.os.PersistableBundle; |
| |
| import androidx.annotation.NonNull; |
| import androidx.annotation.Nullable; |
| import androidx.annotation.RequiresApi; |
| import androidx.annotation.RestrictTo; |
| import androidx.core.graphics.drawable.IconCompat; |
| |
| /** |
| * Provides an immutable reference to an entity that appears repeatedly on different surfaces of the |
| * platform. For example, this could represent the sender of a message. |
| */ |
| public class Person { |
| private static final String NAME_KEY = "name"; |
| private static final String ICON_KEY = "icon"; |
| private static final String URI_KEY = "uri"; |
| private static final String KEY_KEY = "key"; |
| private static final String IS_BOT_KEY = "isBot"; |
| private static final String IS_IMPORTANT_KEY = "isImportant"; |
| |
| /** |
| * Extracts and returns the {@link Person} written to the {@code bundle}. A bundle can be |
| * created from a {@link Person} using {@link #toBundle()}. |
| */ |
| @NonNull |
| public static Person fromBundle(@NonNull Bundle bundle) { |
| Bundle iconBundle = bundle.getBundle(ICON_KEY); |
| return new Builder() |
| .setName(bundle.getCharSequence(NAME_KEY)) |
| .setIcon(iconBundle != null ? IconCompat.createFromBundle(iconBundle) : null) |
| .setUri(bundle.getString(URI_KEY)) |
| .setKey(bundle.getString(KEY_KEY)) |
| .setBot(bundle.getBoolean(IS_BOT_KEY)) |
| .setImportant(bundle.getBoolean(IS_IMPORTANT_KEY)) |
| .build(); |
| } |
| |
| /** |
| * Extracts and returns the {@link Person} written to the {@code bundle}. A persistable bundle |
| * can be created from a {@link Person} using {@link #toPersistableBundle()}. The Icon of the |
| * Person will not be extracted from the PersistableBundle. |
| * |
| * @hide |
| */ |
| @RestrictTo(LIBRARY_GROUP_PREFIX) |
| @NonNull |
| @RequiresApi(22) |
| public static Person fromPersistableBundle(@NonNull PersistableBundle bundle) { |
| return new Builder() |
| .setName(bundle.getString(NAME_KEY)) |
| .setUri(bundle.getString(URI_KEY)) |
| .setKey(bundle.getString(KEY_KEY)) |
| .setBot(bundle.getBoolean(IS_BOT_KEY)) |
| .setImportant(bundle.getBoolean(IS_IMPORTANT_KEY)) |
| .build(); |
| } |
| |
| /** |
| * Converts an Android framework {@link android.app.Person} to a compat {@link Person}. |
| * |
| * @hide |
| */ |
| @RestrictTo(LIBRARY_GROUP_PREFIX) |
| @RequiresApi(28) |
| @NonNull |
| public static Person fromAndroidPerson(@NonNull android.app.Person person) { |
| return new Builder() |
| .setName(person.getName()) |
| .setIcon( |
| (person.getIcon() != null) |
| ? IconCompat.createFromIcon(person.getIcon()) |
| : null) |
| .setUri(person.getUri()) |
| .setKey(person.getKey()) |
| .setBot(person.isBot()) |
| .setImportant(person.isImportant()) |
| .build(); |
| } |
| |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| @Nullable CharSequence mName; |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| @Nullable IconCompat mIcon; |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| @Nullable String mUri; |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| @Nullable String mKey; |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| boolean mIsBot; |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| boolean mIsImportant; |
| |
| @SuppressWarnings("WeakerAccess") /* synthetic access */ |
| Person(Builder builder) { |
| mName = builder.mName; |
| mIcon = builder.mIcon; |
| mUri = builder.mUri; |
| mKey = builder.mKey; |
| mIsBot = builder.mIsBot; |
| mIsImportant = builder.mIsImportant; |
| } |
| |
| /** |
| * Writes and returns a new {@link Bundle} that represents this {@link Person}. This bundle can |
| * be converted back by using {@link #fromBundle(Bundle)}. |
| */ |
| @NonNull |
| public Bundle toBundle() { |
| Bundle result = new Bundle(); |
| result.putCharSequence(NAME_KEY, mName); |
| result.putBundle(ICON_KEY, mIcon != null ? mIcon.toBundle() : null); |
| result.putString(URI_KEY, mUri); |
| result.putString(KEY_KEY, mKey); |
| result.putBoolean(IS_BOT_KEY, mIsBot); |
| result.putBoolean(IS_IMPORTANT_KEY, mIsImportant); |
| return result; |
| } |
| |
| /** |
| * Writes and returns a new {@link PersistableBundle} that represents this {@link Person}. This |
| * bundle can be converted back by using {@link #fromPersistableBundle(PersistableBundle)}. The |
| * Icon of the Person will not be included in the resulting PersistableBundle. |
| * |
| * @hide |
| */ |
| @RestrictTo(LIBRARY_GROUP_PREFIX) |
| @NonNull |
| @RequiresApi(22) |
| public PersistableBundle toPersistableBundle() { |
| PersistableBundle result = new PersistableBundle(); |
| result.putString(NAME_KEY, mName != null ? mName.toString() : null); |
| result.putString(URI_KEY, mUri); |
| result.putString(KEY_KEY, mKey); |
| result.putBoolean(IS_BOT_KEY, mIsBot); |
| result.putBoolean(IS_IMPORTANT_KEY, mIsImportant); |
| return result; |
| } |
| |
| /** Creates and returns a new {@link Builder} initialized with this Person's data. */ |
| @NonNull |
| public Builder toBuilder() { |
| return new Builder(this); |
| } |
| |
| /** |
| * Converts this compat {@link Person} to the base Android framework {@link android.app.Person}. |
| * |
| * @hide |
| */ |
| @RestrictTo(LIBRARY_GROUP_PREFIX) |
| @NonNull |
| @RequiresApi(28) |
| public android.app.Person toAndroidPerson() { |
| return new android.app.Person.Builder() |
| .setName(getName()) |
| .setIcon((getIcon() != null) ? getIcon().toIcon() : null) |
| .setUri(getUri()) |
| .setKey(getKey()) |
| .setBot(isBot()) |
| .setImportant(isImportant()) |
| .build(); |
| } |
| |
| /** |
| * Returns the name for this {@link Person} or {@code null} if no name was provided. This could |
| * be a full name, nickname, username, etc. |
| */ |
| @Nullable |
| public CharSequence getName() { |
| return mName; |
| } |
| |
| /** Returns the icon for this {@link Person} or {@code null} if no icon was provided. */ |
| @Nullable |
| public IconCompat getIcon() { |
| return mIcon; |
| } |
| |
| /** |
| * Returns the raw URI for this {@link Person} or {@code null} if no URI was provided. A URI can |
| * be any of the following: |
| * <ul> |
| * <li>The {@code String} representation of a |
| * {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}</li> |
| * <li>A {@code mailto:} schema*</li> |
| * <li>A {@code tel:} schema*</li> |
| * </ul> |
| * |
| * <p>*Note for these schemas, the path portion of the URI must exist in the contacts |
| * database in their appropriate column, otherwise the reference should be discarded. |
| */ |
| @Nullable |
| public String getUri() { |
| return mUri; |
| } |
| |
| /** |
| * Returns the key for this {@link Person} or {@code null} if no key was provided. This is |
| * provided as a unique identifier between other {@link Person}s. |
| */ |
| @Nullable |
| public String getKey() { |
| return mKey; |
| } |
| |
| /** |
| * Returns whether or not this {@link Person} is a machine rather than a human. Used primarily |
| * to identify automated tooling. |
| */ |
| public boolean isBot() { |
| return mIsBot; |
| } |
| |
| /** |
| * Returns whether or not this {@link Person} is important to the user of this device with |
| * regards to how frequently they interact. |
| */ |
| public boolean isImportant() { |
| return mIsImportant; |
| } |
| |
| /** Builder for the immutable {@link Person} class. */ |
| public static class Builder { |
| @Nullable CharSequence mName; |
| @Nullable IconCompat mIcon; |
| @Nullable String mUri; |
| @Nullable String mKey; |
| boolean mIsBot; |
| boolean mIsImportant; |
| |
| /** Creates a new, empty {@link Builder}. */ |
| public Builder() { } |
| |
| Builder(Person person) { |
| mName = person.mName; |
| mIcon = person.mIcon; |
| mUri = person.mUri; |
| mKey = person.mKey; |
| mIsBot = person.mIsBot; |
| mIsImportant = person.mIsImportant; |
| } |
| |
| /** |
| * Give this {@link Person} a name to use for display. This can be, for example, a full |
| * name, nickname, username, etc. |
| */ |
| @NonNull |
| public Builder setName(@Nullable CharSequence name) { |
| mName = name; |
| return this; |
| } |
| |
| /** |
| * Set an icon for this {@link Person}. |
| * |
| * <p>The system will prefer this icon over any images that are resolved from |
| * {@link #setUri(String)}. |
| */ |
| @NonNull |
| public Builder setIcon(@Nullable IconCompat icon) { |
| mIcon = icon; |
| return this; |
| } |
| |
| /** |
| * Set a URI for this {@link Person} which can be any of the following: |
| * <ul> |
| * <li>The {@code String} representation of a |
| * {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}</li> |
| * <li>A {@code mailto:} schema*</li> |
| * <li>A {@code tel:} schema*</li> |
| * </ul> |
| * |
| * <p>*Note for these schemas, the path portion of the URI must exist in the contacts |
| * database in their appropriate column, otherwise the reference will be discarded. |
| */ |
| @NonNull |
| public Builder setUri(@Nullable String uri) { |
| mUri = uri; |
| return this; |
| } |
| |
| /** |
| * Set a unique identifier for this {@link Person}. This is especially useful if the |
| * {@link #setName(CharSequence)} value isn't unique. This value is preferred for |
| * identification, but if it's not provided, the person's name will be used in its place. |
| */ |
| @NonNull |
| public Builder setKey(@Nullable String key) { |
| mKey = key; |
| return this; |
| } |
| |
| /** |
| * Sets whether or not this {@link Person} represents a machine rather than a human. This is |
| * used primarily for testing and automated tooling. |
| */ |
| @NonNull |
| public Builder setBot(boolean bot) { |
| mIsBot = bot; |
| return this; |
| } |
| |
| /** |
| * Sets whether this is an important person. Use this method to denote users who frequently |
| * interact with the user of this device when {@link #setUri(String)} isn't provided with |
| * {@link android.provider.ContactsContract.Contacts#CONTENT_LOOKUP_URI}, and instead with |
| * the {@code mailto:} or {@code tel:} schemas. |
| */ |
| @NonNull |
| public Builder setImportant(boolean important) { |
| mIsImportant = important; |
| return this; |
| } |
| |
| /** Creates and returns the {@link Person} this builder represents. */ |
| @NonNull |
| public Person build() { |
| return new Person(this); |
| } |
| } |
| } |