RingtoneManager

open class RingtoneManager
kotlin.Any
   ↳ android.media.RingtoneManager

RingtoneManager provides access to ringtones, notification, and other types of sounds. It manages querying the different media providers and combines the results into a single cursor. It also provides a Ringtone for each ringtone. We generically call these sounds ringtones, however the #TYPE_RINGTONE refers to the type of sounds that are suitable for the phone ringer.

To show a ringtone picker to the user, use the #ACTION_RINGTONE_PICKER intent to launch the picker as a subactivity.

Summary

Constants
static String

Activity Action: Shows a ringtone picker.

static String

Given to the ringtone picker as a Uri.

static String

Given to the ringtone picker as a Uri.

static String

Given to the ringtone picker as a boolean.

static String

Returned from the ringtone picker as a Uri.

static String

Given to the ringtone picker as a boolean.

static String

Given to the ringtone picker as a boolean.

static String

Given to the ringtone picker as a CharSequence.

static String

Given to the ringtone picker as an int.

static Int

The column index (in the cursor returned by #getCursor() for the row ID.

static Int

The column index (in the cursor returned by #getCursor() for the title.

static Int

Type that refers to sounds that are used for the alarm.

static Int

All types of sounds.

static Int

Type that refers to sounds that are used for notifications.

static Int

Type that refers to sounds that are used for the phone ringer.

static Int

The column index (in the cursor returned by #getCursor() for the media provider's URI.

Public constructors
<init>(activity: Activity!)

Constructs a RingtoneManager.

<init>(context: Context!)

Constructs a RingtoneManager.

Public methods
open Int

Infers the volume stream type based on what type of ringtones this manager is returning.

open Ringtone!
getRingtone(position: Int)

Gets a Ringtone for the ringtone at the given position in the Cursor.

open Unit
setType(type: Int)

Sets which type(s) of ringtones will be listed by this.

open Boolean

Returns whether DRM ringtones will be included.

open Unit
setStopPreviousRingtone(stopPreviousRingtone: Boolean)

Whether retrieving another Ringtone will stop playing the previously retrieved Ringtone.

open Cursor!

Returns a Cursor of all the ringtones available.

open Unit

Stops playing the last Ringtone retrieved from this.

open Uri!
getRingtoneUri(position: Int)

Gets a Uri for the ringtone at the given position in the Cursor.

open Int
getRingtonePosition(ringtoneUri: Uri!)

Gets the position of a Uri within this RingtoneManager.

open Boolean

open Unit
setIncludeDrm(includeDrm: Boolean)

Sets whether to include DRM ringtones.

open static Uri!

Returns a valid ringtone URI.

open static Ringtone!
getRingtone(context: Context!, ringtoneUri: Uri!)

Returns a Ringtone for a given sound URI.

open static Uri!

Gets the current default sound's Uri.

open static Unit
setActualDefaultRingtoneUri(context: Context!, type: Int, ringtoneUri: Uri!)

Sets the Uri of the default sound for a given sound type.

open static Boolean
isDefault(ringtoneUri: Uri!)

Returns whether the given Uri is one of the default ringtones.

open static Int
getDefaultType(defaultRingtoneUri: Uri!)

Returns the type of a default Uri.

open static Uri!

Returns the Uri for the default ringtone of a particular type.

Constants

ACTION_RINGTONE_PICKER

static val ACTION_RINGTONE_PICKER: String

Activity Action: Shows a ringtone picker.

Input: #EXTRA_RINGTONE_EXISTING_URI, #EXTRA_RINGTONE_SHOW_DEFAULT, #EXTRA_RINGTONE_SHOW_SILENT, #EXTRA_RINGTONE_TYPE, #EXTRA_RINGTONE_DEFAULT_URI, #EXTRA_RINGTONE_TITLE,

Output: #EXTRA_RINGTONE_PICKED_URI.

Value: "android.intent.action.RINGTONE_PICKER"

EXTRA_RINGTONE_DEFAULT_URI

static val EXTRA_RINGTONE_DEFAULT_URI: String

Given to the ringtone picker as a Uri. The Uri of the ringtone to play when the user attempts to preview the "Default" ringtone. This can be one of System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#DEFAULT_ALARM_ALERT_URI to have the "Default" point to the current sound for the given default sound type. If you are showing a ringtone picker for some other type of sound, you are free to provide any Uri here.

Value: "android.intent.extra.ringtone.DEFAULT_URI"

EXTRA_RINGTONE_EXISTING_URI

static val EXTRA_RINGTONE_EXISTING_URI: String

Given to the ringtone picker as a Uri. The Uri of the current ringtone, which will be used to show a checkmark next to the item for this Uri. If showing an item for "Default" (@see #EXTRA_RINGTONE_SHOW_DEFAULT), this can also be one of System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#DEFAULT_ALARM_ALERT_URI to have the "Default" item checked.

Value: "android.intent.extra.ringtone.EXISTING_URI"

EXTRA_RINGTONE_INCLUDE_DRM

static val EXTRA_RINGTONE_INCLUDE_DRM: String

Given to the ringtone picker as a boolean. Whether to include DRM ringtones.

Value: "android.intent.extra.ringtone.INCLUDE_DRM"

EXTRA_RINGTONE_PICKED_URI

static val EXTRA_RINGTONE_PICKED_URI: String

Returned from the ringtone picker as a Uri.

It will be one of:

  • the picked ringtone,
  • a Uri that equals System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#DEFAULT_ALARM_ALERT_URI if the default was chosen,
  • null if the "Silent" item was picked.
  • Value: "android.intent.extra.ringtone.PICKED_URI"

    EXTRA_RINGTONE_SHOW_DEFAULT

    static val EXTRA_RINGTONE_SHOW_DEFAULT: String

    Given to the ringtone picker as a boolean. Whether to show an item for "Default".

    Value: "android.intent.extra.ringtone.SHOW_DEFAULT"

    EXTRA_RINGTONE_SHOW_SILENT

    static val EXTRA_RINGTONE_SHOW_SILENT: String

    Given to the ringtone picker as a boolean. Whether to show an item for "Silent". If the "Silent" item is picked, #EXTRA_RINGTONE_PICKED_URI will be null.

    Value: "android.intent.extra.ringtone.SHOW_SILENT"

    EXTRA_RINGTONE_TITLE

    static val EXTRA_RINGTONE_TITLE: String

    Given to the ringtone picker as a CharSequence. The title to show for the ringtone picker. This has a default value that is suitable in most cases.

    Value: "android.intent.extra.ringtone.TITLE"

    EXTRA_RINGTONE_TYPE

    static val EXTRA_RINGTONE_TYPE: String

    Given to the ringtone picker as an int. Specifies which ringtone type(s) should be shown in the picker. One or more of #TYPE_RINGTONE, #TYPE_NOTIFICATION, #TYPE_ALARM, or #TYPE_ALL (bitwise-ored together).

    Value: "android.intent.extra.ringtone.TYPE"

    ID_COLUMN_INDEX

    static val ID_COLUMN_INDEX: Int

    The column index (in the cursor returned by #getCursor() for the row ID.

    Value: 0

    TITLE_COLUMN_INDEX

    static val TITLE_COLUMN_INDEX: Int

    The column index (in the cursor returned by #getCursor() for the title.

    Value: 1

    TYPE_ALARM

    static val TYPE_ALARM: Int

    Type that refers to sounds that are used for the alarm.

    Value: 4

    TYPE_ALL

    static val TYPE_ALL: Int

    All types of sounds.

    Value: 7

    TYPE_NOTIFICATION

    static val TYPE_NOTIFICATION: Int

    Type that refers to sounds that are used for notifications.

    Value: 2

    TYPE_RINGTONE

    static val TYPE_RINGTONE: Int

    Type that refers to sounds that are used for the phone ringer.

    Value: 1

    URI_COLUMN_INDEX

    static val URI_COLUMN_INDEX: Int

    The column index (in the cursor returned by #getCursor() for the media provider's URI.

    Value: 2

    Public constructors

    <init>

    RingtoneManager(activity: Activity!)

    Constructs a RingtoneManager. This constructor is recommended as its constructed instance manages cursor(s).

    Parameters
    activity Activity!: The activity used to get a managed cursor.

    <init>

    RingtoneManager(context: Context!)

    Constructs a RingtoneManager. The instance constructed by this constructor will not manage the cursor(s), so the client should handle this itself.

    Parameters
    context Context!: The context to used to get a cursor.

    Public methods

    inferStreamType

    added in API level 3
    open fun inferStreamType(): Int

    Infers the volume stream type based on what type of ringtones this manager is returning.
    Requires API level 3 (Android 1.5, Cupcake)

    Return
    Int: The stream type.

    getRingtone

    open fun getRingtone(position: Int): Ringtone!

    Gets a Ringtone for the ringtone at the given position in the Cursor.

    Parameters
    position Int: The position (in the Cursor) of the ringtone.
    Return
    Ringtone!: A Ringtone pointing to the ringtone.

    setType

    open fun setType(type: Int): Unit

    Sets which type(s) of ringtones will be listed by this.

    Parameters
    type Int: The type(s), one or more of #TYPE_RINGTONE, #TYPE_NOTIFICATION, #TYPE_ALARM, #TYPE_ALL.

    getIncludeDrm

    open fun getIncludeDrm(): Boolean

    Returns whether DRM ringtones will be included.

    Return
    Boolean: Whether DRM ringtones will be included.

    setStopPreviousRingtone

    open fun setStopPreviousRingtone(stopPreviousRingtone: Boolean): Unit

    Whether retrieving another Ringtone will stop playing the previously retrieved Ringtone.

    If this is false, make sure to Ringtone#stop() any previous ringtones to free resources.

    Parameters
    stopPreviousRingtone Boolean: If true, the previously retrieved Ringtone will be stopped.

    getCursor

    open fun getCursor(): Cursor!

    Returns a Cursor of all the ringtones available. The returned cursor will be the same cursor returned each time this method is called, so do not Cursor#close() the cursor. The cursor can be Cursor#deactivate() safely.

    If RingtoneManager#RingtoneManager(Activity) was not used, the caller should manage the returned cursor through its activity's life cycle to prevent leaking the cursor.

    Note that the list of ringtones available will differ depending on whether the caller has the android.Manifest.permission#READ_EXTERNAL_STORAGE permission.

    Return
    Cursor!: A Cursor of all the ringtones available.

    stopPreviousRingtone

    open fun stopPreviousRingtone(): Unit

    Stops playing the last Ringtone retrieved from this.

    getRingtoneUri

    open fun getRingtoneUri(position: Int): Uri!

    Gets a Uri for the ringtone at the given position in the Cursor.

    Parameters
    position Int: The position (in the Cursor) of the ringtone.
    Return
    Uri!: A Uri pointing to the ringtone.

    getRingtonePosition

    open fun getRingtonePosition(ringtoneUri: Uri!): Int

    Gets the position of a Uri within this RingtoneManager.

    Parameters
    ringtoneUri Uri!: The Uri to retreive the position of.
    Return
    Int: The position of the Uri, or -1 if it cannot be found.

    getStopPreviousRingtone

    open fun getStopPreviousRingtone(): Boolean

    setIncludeDrm

    open fun setIncludeDrm(includeDrm: Boolean): Unit

    Sets whether to include DRM ringtones.

    Parameters
    includeDrm Boolean: Whether to include DRM ringtones. Obsolete - no longer has any effect

    getValidRingtoneUri

    open static fun getValidRingtoneUri(context: Context!): Uri!

    Returns a valid ringtone URI. No guarantees on which it returns. If it cannot find one, returns null. If it can only find one on external storage and the caller doesn't have the android.Manifest.permission#READ_EXTERNAL_STORAGE permission, returns null.

    Parameters
    context Context!: The context to use for querying.
    Return
    Uri!: A ringtone URI, or null if one cannot be found.

    getRingtone

    open static fun getRingtone(context: Context!, ringtoneUri: Uri!): Ringtone!

    Returns a Ringtone for a given sound URI.

    If the given URI cannot be opened for any reason, this method will attempt to fallback on another sound. If it cannot find any, it will return null.

    Parameters
    context Context!: A context used to query.
    ringtoneUri Context!: The Uri of a sound or ringtone.
    Return
    Ringtone!: A Ringtone for the given URI, or null.

    getActualDefaultRingtoneUri

    open static fun getActualDefaultRingtoneUri(context: Context!, type: Int): Uri!

    Gets the current default sound's Uri. This will give the actual sound Uri, instead of using this, most clients can use System#DEFAULT_RINGTONE_URI.

    Parameters
    context Context!: A context used for querying.
    type Context!: The type whose default sound should be returned. One of #TYPE_RINGTONE, #TYPE_NOTIFICATION, or #TYPE_ALARM.
    Return
    Uri!: A Uri pointing to the default sound for the sound type.

    setActualDefaultRingtoneUri

    open static fun setActualDefaultRingtoneUri(context: Context!, type: Int, ringtoneUri: Uri!): Unit

    Sets the Uri of the default sound for a given sound type.

    Parameters
    context Context!: A context used for querying.
    type Context!: The type whose default sound should be set. One of #TYPE_RINGTONE, #TYPE_NOTIFICATION, or #TYPE_ALARM.
    ringtoneUri Context!: A Uri pointing to the default sound to set.

    isDefault

    open static fun isDefault(ringtoneUri: Uri!): Boolean

    Returns whether the given Uri is one of the default ringtones.

    Parameters
    ringtoneUri Uri!: The ringtone Uri to be checked.
    Return
    Boolean: Whether the Uri is a default.

    getDefaultType

    open static fun getDefaultType(defaultRingtoneUri: Uri!): Int

    Returns the type of a default Uri.

    Parameters
    defaultRingtoneUri Uri!: The default Uri. For example, System#DEFAULT_RINGTONE_URI, System#DEFAULT_NOTIFICATION_URI, or System#DEFAULT_ALARM_ALERT_URI.
    Return
    Int: The type of the defaultRingtoneUri, or -1.

    getDefaultUri

    open static fun getDefaultUri(type: Int): Uri!

    Returns the Uri for the default ringtone of a particular type. Rather than returning the actual ringtone's sound Uri, this will return the symbolic Uri which will resolved to the actual sound when played.

    Parameters
    type Int: The ringtone type whose default should be returned.
    Return
    Uri!: The Uri of the default ringtone for the given type.