Most visited

Recently visited

Results for

Added in API level 1
Summary: Constants | Ctors | Methods | Inherited Methods | [Expand All]

RingtoneManager

public class RingtoneManager
extends Object

java.lang.Object
   ↳ 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.

See also:

Summary

Constants
String ACTION_RINGTONE_PICKER

Activity Action: Shows a ringtone picker.

String EXTRA_RINGTONE_DEFAULT_URI

Given to the ringtone picker as a Uri.

String EXTRA_RINGTONE_EXISTING_URI

Given to the ringtone picker as a Uri.

String EXTRA_RINGTONE_INCLUDE_DRM

This constant was deprecated in API level 19. DRM ringtones are no longer supported

String EXTRA_RINGTONE_PICKED_URI

Returned from the ringtone picker as a Uri.

String EXTRA_RINGTONE_SHOW_DEFAULT

Given to the ringtone picker as a boolean.

String EXTRA_RINGTONE_SHOW_SILENT

Given to the ringtone picker as a boolean.

String EXTRA_RINGTONE_TITLE

Given to the ringtone picker as a CharSequence.

String EXTRA_RINGTONE_TYPE

Given to the ringtone picker as an int.

int ID_COLUMN_INDEX

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

int TITLE_COLUMN_INDEX

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

int TYPE_ALARM

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

int TYPE_ALL

All types of sounds.

int TYPE_NOTIFICATION

Type that refers to sounds that are used for notifications.

int TYPE_RINGTONE

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

int URI_COLUMN_INDEX

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

Public constructors
RingtoneManager(Activity activity)

Constructs a RingtoneManager.

RingtoneManager(Context context)

Constructs a RingtoneManager.

Public methods
static Uri getActualDefaultRingtoneUri(Context context, int type)

Gets the current default sound's Uri.

Cursor getCursor()

Returns a Cursor of all the ringtones available.

static int getDefaultType(Uri defaultRingtoneUri)

Returns the type of a default Uri.

static Uri getDefaultUri(int type)

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

boolean getIncludeDrm()

This method was deprecated in API level 19. DRM ringtones are no longer supported

static Ringtone getRingtone(Context context, Uri ringtoneUri)

Returns a Ringtone for a given sound URI.

Ringtone getRingtone(int position)

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

int getRingtonePosition(Uri ringtoneUri)

Gets the position of a Uri within this RingtoneManager.

Uri getRingtoneUri(int position)

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

boolean getStopPreviousRingtone()
static Uri getValidRingtoneUri(Context context)

Returns a valid ringtone URI.

int inferStreamType()

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

static boolean isDefault(Uri ringtoneUri)

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

static void setActualDefaultRingtoneUri(Context context, int type, Uri ringtoneUri)

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

void setIncludeDrm(boolean includeDrm)

This method was deprecated in API level 19. DRM ringtones are no longer supported

void setStopPreviousRingtone(boolean stopPreviousRingtone)

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

void setType(int type)

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

void stopPreviousRingtone()

Stops playing the last Ringtone retrieved from this.

Inherited methods
From class java.lang.Object

Constants

ACTION_RINGTONE_PICKER

Added in API level 1 
String ACTION_RINGTONE_PICKER

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.

Constant Value: "android.intent.action.RINGTONE_PICKER"

EXTRA_RINGTONE_DEFAULT_URI

Added in API level 1 
String EXTRA_RINGTONE_DEFAULT_URI

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 DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or 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.

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

EXTRA_RINGTONE_EXISTING_URI

Added in API level 1 
String EXTRA_RINGTONE_EXISTING_URI

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 DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI to have the "Default" item checked.

See also:

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

EXTRA_RINGTONE_INCLUDE_DRM

Added in API level 1 
String EXTRA_RINGTONE_INCLUDE_DRM

This constant was deprecated in API level 19.
DRM ringtones are no longer supported

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

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

EXTRA_RINGTONE_PICKED_URI

Added in API level 1 
String EXTRA_RINGTONE_PICKED_URI

Returned from the ringtone picker as a Uri.

It will be one of:

  • the picked ringtone,
  • a Uri that equals DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI if the default was chosen,
  • null if the "Silent" item was picked.

    See also:

    Constant Value: "android.intent.extra.ringtone.PICKED_URI"

    • EXTRA_RINGTONE_SHOW_DEFAULT

    Added in API level 1 
    String EXTRA_RINGTONE_SHOW_DEFAULT

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

    See also:

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

    EXTRA_RINGTONE_SHOW_SILENT

    Added in API level 1 
    String EXTRA_RINGTONE_SHOW_SILENT

    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.

    See also:

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

    EXTRA_RINGTONE_TITLE

    Added in API level 1 
    String EXTRA_RINGTONE_TITLE

    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.

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

    EXTRA_RINGTONE_TYPE

    Added in API level 1 
    String EXTRA_RINGTONE_TYPE

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

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

    ID_COLUMN_INDEX

    Added in API level 1 
    int ID_COLUMN_INDEX

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

    Constant Value: 0 (0x00000000)

    TITLE_COLUMN_INDEX

    Added in API level 1 
    int TITLE_COLUMN_INDEX

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

    Constant Value: 1 (0x00000001)

    TYPE_ALARM

    Added in API level 1 
    int TYPE_ALARM

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

    Constant Value: 4 (0x00000004)

    TYPE_ALL

    Added in API level 1 
    int TYPE_ALL

    All types of sounds.

    Constant Value: 7 (0x00000007)

    TYPE_NOTIFICATION

    Added in API level 1 
    int TYPE_NOTIFICATION

    Type that refers to sounds that are used for notifications.

    Constant Value: 2 (0x00000002)

    TYPE_RINGTONE

    Added in API level 1 
    int TYPE_RINGTONE

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

    Constant Value: 1 (0x00000001)

    URI_COLUMN_INDEX

    Added in API level 1 
    int URI_COLUMN_INDEX

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

    Constant Value: 2 (0x00000002)

    Public constructors

    RingtoneManager

    Added in API level 1 
    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.

    RingtoneManager

    Added in API level 1 
    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

    getActualDefaultRingtoneUri

    Added in API level 1 
    Uri getActualDefaultRingtoneUri (Context context, 
                int type)

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

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

    See also:

    getCursor

    Added in API level 1 
    Cursor getCursor ()

    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 close() the cursor. The cursor can be deactivate() safely.

    If 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 READ_EXTERNAL_STORAGE permission.

    Returns
    Cursor A Cursor of all the ringtones available.

    See also:

    getDefaultType

    Added in API level 1 
    int getDefaultType (Uri defaultRingtoneUri)

    Returns the type of a default Uri.

    Parameters
    defaultRingtoneUri Uri: The default Uri. For example, DEFAULT_RINGTONE_URI, DEFAULT_NOTIFICATION_URI, or DEFAULT_ALARM_ALERT_URI.
    Returns
    int The type of the defaultRingtoneUri, or -1.

    getDefaultUri

    Added in API level 1 
    Uri getDefaultUri (int type)

    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.
    Returns
    Uri The Uri of the default ringtone for the given type.

    getIncludeDrm

    Added in API level 1 
    boolean getIncludeDrm ()

    This method was deprecated in API level 19.
    DRM ringtones are no longer supported

    Returns whether DRM ringtones will be included.

    Returns
    boolean Whether DRM ringtones will be included.

    See also:

    getRingtone

    Added in API level 1 
    Ringtone getRingtone (Context context, 
                Uri ringtoneUri)

    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 Uri: The Uri of a sound or ringtone.
    Returns
    Ringtone A Ringtone for the given URI, or null.

    getRingtone

    Added in API level 1 
    Ringtone getRingtone (int position)

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

    Parameters
    position int: The position (in the Cursor) of the ringtone.
    Returns
    Ringtone A Ringtone pointing to the ringtone.

    getRingtonePosition

    Added in API level 1 
    int getRingtonePosition (Uri ringtoneUri)

    Gets the position of a Uri within this RingtoneManager.

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

    getRingtoneUri

    Added in API level 1 
    Uri getRingtoneUri (int position)

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

    Parameters
    position int: The position (in the Cursor) of the ringtone.
    Returns
    Uri A Uri pointing to the ringtone.

    getStopPreviousRingtone

    Added in API level 1 
    boolean getStopPreviousRingtone ()

    Returns
    boolean

    See also:

    getValidRingtoneUri

    Added in API level 1 
    Uri getValidRingtoneUri (Context context)

    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 READ_EXTERNAL_STORAGE permission, returns null.

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

    inferStreamType

    Added in API level 3 
    int inferStreamType ()

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

    Returns
    int The stream type.

    isDefault

    Added in API level 1 
    boolean isDefault (Uri ringtoneUri)

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

    Parameters
    ringtoneUri Uri: The ringtone Uri to be checked.
    Returns
    boolean Whether the Uri is a default.

    setActualDefaultRingtoneUri

    Added in API level 1 
    void setActualDefaultRingtoneUri (Context context, 
                int type, 
                Uri ringtoneUri)

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

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

    See also:

    setIncludeDrm

    Added in API level 1 
    void setIncludeDrm (boolean includeDrm)

    This method was deprecated in API level 19.
    DRM ringtones are no longer supported

    Sets whether to include DRM ringtones.

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

    setStopPreviousRingtone

    Added in API level 1 
    void setStopPreviousRingtone (boolean stopPreviousRingtone)

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

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

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

    setType

    Added in API level 1 
    void setType (int type)

    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.

    See also:

    stopPreviousRingtone

    Added in API level 1 
    void stopPreviousRingtone ()

    Stops playing the last Ringtone retrieved from this.