MPVolumeView Class Reference

Inherits from
Conforms to
Framework
/System/Library/Frameworks/MediaPlayer.framework
Availability
Available in iOS 2.0 and later.
Declared in
MPVolumeView.h

Overview

Use a volume view to present the user with a slider control for setting the system audio output volume, and a button for choosing the audio output route. When first displayed, the slider’s position reflects the current system audio output volume. As the user drags the slider, the changes update the volume. If the user presses the device volume buttons while sound is playing, the slider moves to reflect the new volume.

If there is an Apple TV or other AirPlay-enabled device in range, the route button allows the user to choose it. If there is only one audio output route available, the route button is not displayed.

Use this class by embedding an instance of it in your view hierarchy. The following code snippet assumes you have placed an instance of the UIView class on a view using Interface Builder, sizing and positioning it as desired to contain the volume view. Point to the UIView instance with an outlet variable—named, in the case of this example, mpVolumeViewParentView. You would typically place code like that shown in Listing 1 in your viewDidLoad method.

Listing 1  Adding a volume view to your view hierarchy

mpVolumeViewParentView.backgroundColor = [UIColor clearColor];
MPVolumeView *myVolumeView =
    [[MPVolumeView alloc] initWithFrame: mpVolumeViewParentView.bounds];
[mpVolumeViewParentView addSubview: myVolumeView];
[myVolumeView release];

When an audio output route that does not support volume control, such as A2DP, is active, the volume slider is replaced with the route name.

To instead display a volume slider as an alert, use the functions described in Media Player Functions Reference.

Customizing the Volume Slider’s Appearance

The volume slider is a UISlider object. Sliders are always displayed as horizontal bars and an indicator, or thumb, notes the current value of the slider and can be moved by the user to change the setting.

Slider controls draw the volume slider track using two distinct images, which are customizable. The region between the thumb and the end of the track associated with the slider’s minimum value is drawn using the minimum volume slider image. The region between the thumb and the end of the track associated with the slider’s maximum value is drawn using the maximum volume slider image. Assigning different images to each state lets you customize the appearance of the slider when it is enabled, disabled, highlighted, and so on.

You can also customize the volume thumb image for the slider.

Tasks

Resizing Subviews

Managing Visibility of Controls

Customizing the Volume Slider

Customizing the Route Button

Properties

showsRouteButton

Determines whether or not the route button is visible in the volume view.

@property(nonatomic) BOOL showsRouteButton
Discussion

The route button is visible by default when there is more than one audio output route available. To hide the route button, set this property’s value to NO.

Availability
  • Available in iOS 4.2 and later.
Declared In
MPVolumeView.h

showsVolumeSlider

Determines whether or not the volume slider is visible in the volume view.

@property(nonatomic) BOOL showsVolumeSlider
Discussion

The volume slider is visible by default. To hide the volume slider, set this property’s value to NO.

Availability
  • Available in iOS 4.2 and later.
Declared In
MPVolumeView.h

Instance Methods

maximumVolumeSliderImageForState:

Returns the maximum volume image associated with the specified control state.

- (UIImage *)maximumVolumeSliderImageForState:(UIControlState)state
Parameters
state

The control state whose maximum volume image you want. You should specify only one control state value for this parameter.

Return Value

The maximum volume image associated with the specified state, or nil if an appropriate image could not be retrieved. This method might return nil if you specify multiple control states in the state parameter.

Discussion

For a description of slider and thumb images, see “Customizing the Volume Slider’s Appearance.”

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

minimumVolumeSliderImageForState:

Returns the minimum volume image associated with the specified control state.

- (UIImage *)minimumVolumeSliderImageForState:(UIControlState)state
Parameters
state

The control state whose minimum volume image you want. You should specify only one control state value for this parameter.

Return Value

The maximum volume image associated with the specified state, or nil if an appropriate image could not be retrieved. This method might return nil if you specify multiple control states in the state parameter.

Discussion

For a description of slider and thumb images, see “Customizing the Volume Slider’s Appearance.”

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

routeButtonImageForState:

Returns the button image associated with the specified control state.

- (UIImage *)routeButtonImageForState:(UIControlState)state
Parameters
state

The control state whose thumb image you want. You should specify only one control state value for this parameter.

Return Value

The button image associated with the specified state, or nil if an appropriate image could not be retrieved. This method might return nil if you specify multiple control states in the state parameter.

Discussion

Use this method to retrieve the corresponding button image for a specific state.

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

routeButtonRectForBounds:

Returns the drawing rectangle for the route button.

- (CGRect)routeButtonRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the route button.

Discussion

Use this method to retrieve the bounding rectangle for the route button.

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

setMaximumVolumeSliderImage:forState:

Assigns a maximum volume slider image to the specified control states.

- (void)setMaximumVolumeSliderImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The maximum volume slider image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

The orientation of the track image must match the orientation of the slider control. To facilitate the stretching of the image to fill the space between the thumb and end point, track images are usually defined in three regions. A stretchable region sits between two end cap regions. The end caps define the portions of the image that remain as is and are not stretched. The stretchable region is a 1-point wide area between the end caps that can be replicated to make the image appear longer.

To define the end cap sizes for a slider, assign an appropriate value to the image’s capInsets property. For more information about how this value defines the regions of the slider, see the UIImage Class Reference.

For a description of slider and thumb images, see “Customizing the Volume Slider’s Appearance.”

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

setMinimumVolumeSliderImage:forState:

Assigns a minimum volume slider image to the specified control states.

- (void)setMinimumVolumeSliderImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The minimum volume slider image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

The orientation of the track image must match the orientation of the slider control. To facilitate the stretching of the image to fill the space between the thumb and end point, track images are usually defined in three regions. A stretchable region sits between two end cap regions. The end caps define the portions of the image that remain as is and are not stretched. The stretchable region is a 1-point wide area between the end caps that can be replicated to make the image appear longer.

To define the end cap sizes for a slider, assign an appropriate value to the image’s capInsets property. For more information about how this value defines the regions of the slider, see the UIImage Class Reference.

For a description of slider and thumb images, see “Customizing the Volume Slider’s Appearance.”

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

setRouteButtonImage:forState:

Assigns a button image to the specified control states.

- (void)setRouteButtonImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

Use this to customize the appearance of the route button when it is enabled, disabled, highlighted, and so on.

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

setVolumeThumbImage:forState:

Assigns a thumb image to the specified control states.

- (void)setVolumeThumbImage:(UIImage *)image forState:(UIControlState)state
Parameters
image

The thumb image to associate with the specified states.

state

The control state with which to associate the image.

Discussion

For a description of slider and thumb images, see “Customizing the Volume Slider’s Appearance.”

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

sizeThatFits:

Calculates and returns a size that best fits the receiver’s subviews.

- (CGSize)sizeThatFits:(CGSize)size
Parameters
size

The preferred size of the receiver.

Return Value

A new size that fits the receiver’s subviews.

Discussion

This method overrides the like-named method from the UIView class. It returns the preferred size the volume view needs to display the contained slider. You should not need to override this method.

Availability
  • Available in iOS 2.0 and later.
Declared In
MPVolumeView.h

volumeSliderRectForBounds:

Returns the drawing rectangle for the slider’s track.

- (CGRect)volumeSliderRectForBounds:(CGRect)bounds
Parameters
bounds

The bounding rectangle of the receiver.

Return Value

The computed drawing rectangle for the volume slider track. This rectangle corresponds to the entire length of the track between the minimum and maximum value images.

Discussion

The returned rectangle is used to scale the track and thumb images during drawing.

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

volumeThumbImageForState:

Returns the thumb image associated with the specified control state.

- (UIImage *)volumeThumbImageForState:(UIControlState)state
Parameters
state

The control state whose thumb image you want. You should specify only one control state value for this parameter.

Return Value

The thumb image associated with the specified state, or nil if an appropriate image could not be retrieved. This method might return nil if you specify multiple control states in the state parameter.

Discussion

For a description of slider and thumb images, see “Customizing the Volume Slider’s Appearance.”

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h

volumeThumbRectForBounds:volumeSliderRect:value:

Returns the drawing rectangle for the volume slider’s thumb image.

- (CGRect)volumeThumbRectForBounds:(CGRect)bounds volumeSliderRect:(CGRect)rect value:(float)value
Parameters
bounds

The bounding rectangle of the receiver.

rect

The drawing rectangle for the receiver’s track, as returned by the volumeSliderRectForBounds: method.

value

The current value of the volume slider.

Return Value

The computed drawing rectangle for the thumb image.

Discussion

The rectangle you return should reflect the size of your thumb image and its current position on the slider’s track.

Availability
  • Available in iOS 6.0 and later.
Declared In
MPVolumeView.h