Stay organized with collections
Save and categorize content based on your preferences.
PinnedPositions
class PinnedPositions
Contact-specific information about whether or not a contact has been pinned by the user at a particular position within the system contact application's user interface.
This pinning information can be used by individual applications to customize how they order particular pinned contacts. For example, a Dialer application could use pinned information to order user-pinned contacts in a top row of favorites.
It is possible for two or more contacts to occupy the same pinned position (due to aggregation and sync), so this pinning information should be used on a best-effort basis to order contacts in-application rather than an absolute guide on where a contact should be positioned. Contacts returned by the ContactsProvider will not be ordered based on this information, so it is up to the client application to reorder these contacts within their own UI adhering to (or ignoring as appropriate) information stored in the pinned column.
By default, unpinned contacts will have a pinned position of PinnedPositions.UNPINNED. Client-provided pinned positions can be positive integers that are greater than 1.
Summary
| Constants |
| static Int |
Value of pinned position for a contact that a user has indicated should be considered of the lowest priority.
|
| static Int |
Default value for the pinned position of an unpinned contact.
|
| Public methods |
| static Unit |
Pins a contact at a provided position, or unpins a contact.
|
| static Unit |
Undemotes a formerly demoted contact.
|
Constants
DEMOTED
static val DEMOTED: Int
Value of pinned position for a contact that a user has indicated should be considered of the lowest priority. It is up to the client application to determine how to present such a contact - for example all the way at the bottom of a contact list, or simply just hidden from view.
Value: -1
UNPINNED
static val UNPINNED: Int
Default value for the pinned position of an unpinned contact.
Value: 0
Public constructors
PinnedPositions
PinnedPositions()
Public methods
pin
static fun pin(
contentResolver: ContentResolver!,
contactId: Long,
pinnedPosition: Int
): Unit
Pins a contact at a provided position, or unpins a contact.
undemote
static fun undemote(
contentResolver: ContentResolver!,
contactId: Long
): Unit
Undemotes a formerly demoted contact. If the contact was not previously demoted, nothing will be done.
| Parameters |
contentResolver |
ContentResolver!: to perform the undemote operation on. |
contactId |
Long: the id of the contact to undemote. |
Content and code samples on this page are subject to the licenses described in the Content License. Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
Last updated 2025-02-10 UTC.
[null,null,["Last updated 2025-02-10 UTC."],[],[],null,["# ContactsContract.PinnedPositions\n\nAdded in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels)\n\nPinnedPositions\n===============\n\n*** ** * ** ***\n\nKotlin \\|[Java](/reference/android/provider/ContactsContract.PinnedPositions \"View this page in Java\") \n\n```\nclass PinnedPositions\n```\n\n|---|--------------------------------------------------------|\n| [kotlin.Any](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-any/index.html) ||\n| ↳ | [android.provider.ContactsContract.PinnedPositions](#) |\n\nContact-specific information about whether or not a contact has been pinned by the user at a particular position within the system contact application's user interface.\n\nThis pinning information can be used by individual applications to customize how they order particular pinned contacts. For example, a Dialer application could use pinned information to order user-pinned contacts in a top row of favorites.\n\nIt is possible for two or more contacts to occupy the same pinned position (due to aggregation and sync), so this pinning information should be used on a best-effort basis to order contacts in-application rather than an absolute guide on where a contact should be positioned. Contacts returned by the ContactsProvider will not be ordered based on this information, so it is up to the client application to reorder these contacts within their own UI adhering to (or ignoring as appropriate) information stored in the pinned column.\n\nBy default, unpinned contacts will have a pinned position of [PinnedPositions.UNPINNED](#UNPINNED:kotlin.Int). Client-provided pinned positions can be positive integers that are greater than 1.\n\nSummary\n-------\n\n| Constants ||\n|-----------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------|\n| static [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html) | [DEMOTED](#DEMOTED:kotlin.Int) Value of pinned position for a contact that a user has indicated should be considered of the lowest priority. |\n| static [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html) | [UNPINNED](#UNPINNED:kotlin.Int) Default value for the pinned position of an unpinned contact. |\n\n| Public constructors ||\n|--------------------------------------------------|---|\n| [PinnedPositions](#PinnedPositions())`()` \u003cbr /\u003e |\n\n| Public methods ||\n|-------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| static [Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html) | [pin](#pin(android.content.ContentResolver,%20kotlin.Long,%20kotlin.Int))`(`contentResolver:` `[ContentResolver](../content/ContentResolver.html#)!`, `contactId:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`, `pinnedPosition:` `[Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html)`)` Pins a contact at a provided position, or unpins a contact. |\n| static [Unit](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-unit/index.html) | [undemote](#undemote(android.content.ContentResolver,%20kotlin.Long))`(`contentResolver:` `[ContentResolver](../content/ContentResolver.html#)!`, `contactId:` `[Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html)`)` Undemotes a formerly demoted contact. |\n\nConstants\n---------\n\n### DEMOTED\n\nAdded in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nstatic val DEMOTED: Int\n```\n\nValue of pinned position for a contact that a user has indicated should be considered of the lowest priority. It is up to the client application to determine how to present such a contact - for example all the way at the bottom of a contact list, or simply just hidden from view. \n\n Value: -1\n\n### UNPINNED\n\nAdded in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nstatic val UNPINNED: Int\n```\n\nDefault value for the pinned position of an unpinned contact. \n\n Value: 0\n\nPublic constructors\n-------------------\n\n### PinnedPositions\n\n```\nPinnedPositions()\n```\n\nPublic methods\n--------------\n\n### pin\n\nAdded in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nstatic fun pin(\n contentResolver: ContentResolver!, \n contactId: Long, \n pinnedPosition: Int\n): Unit\n```\n\nPins a contact at a provided position, or unpins a contact.\n\n| Parameters ||\n|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| `contentResolver` | [ContentResolver](../content/ContentResolver.html#)!: to perform the pinning operation on. |\n| `pinnedPosition` | [Int](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-int/index.html): the position to pin the contact at. To unpin a contact, use [PinnedPositions.UNPINNED](#UNPINNED:kotlin.Int). |\n\n### undemote\n\nAdded in [API level 21](https://developer.android.com/guide/topics/manifest/uses-sdk-element.html#ApiLevels) \n\n```\nstatic fun undemote(\n contentResolver: ContentResolver!, \n contactId: Long\n): Unit\n```\n\nUndemotes a formerly demoted contact. If the contact was not previously demoted, nothing will be done.\n\n| Parameters ||\n|-------------------|------------------------------------------------------------------------------------------------------------------|\n| `contentResolver` | [ContentResolver](../content/ContentResolver.html#)!: to perform the undemote operation on. |\n| `contactId` | [Long](https://kotlinlang.org/api/latest/jvm/stdlib/kotlin/-long/index.html): the id of the contact to undemote. |"]]
