Added in API level 24

MagnificationController


class MagnificationController
kotlin.Any
   ↳ android.accessibilityservice.AccessibilityService.MagnificationController

Used to control and query the state of display magnification.

Summary

Nested classes
abstract

Listener for changes in the state of magnification.

Public methods
Unit

Adds the specified change listener to the list of magnification change listeners.

Unit

Adds the specified change listener to the list of magnification change listeners.

Float

Returns the unscaled screen-relative X coordinate of the focal center of the magnified region.

Float

Returns the unscaled screen-relative Y coordinate of the focal center of the magnified region.

Region

Returns the region of the screen currently active for magnification if the controlling magnification is MagnificationConfig#MAGNIFICATION_MODE_FULLSCREEN.

MagnificationConfig?

Gets the MagnificationConfig of the controlling magnifier on the display.

Region

Returns the region of the screen currently active for magnification.

Float

Returns the current magnification scale.

Boolean

Removes the specified change listener from the list of magnification change listeners.

Boolean
reset(animate: Boolean)

Resets magnification scale and center to their default (e.g. no magnification) values.

Boolean

Resets magnification scale and center of the controlling magnification to their default (e.g. no magnification) values.

Boolean
setCenter(centerX: Float, centerY: Float, animate: Boolean)

Sets the center of the magnified viewport.

Boolean

Sets the MagnificationConfig.

Boolean
setScale(scale: Float, animate: Boolean)

Sets the magnification scale.

Public methods

addListener

Added in API level 24
fun addListener(listener: AccessibilityService.MagnificationController.OnMagnificationChangedListener): Unit

Adds the specified change listener to the list of magnification change listeners. The callback will occur on the service's main thread.

Parameters
listener AccessibilityService.MagnificationController.OnMagnificationChangedListener: the listener to add, must be non-null

addListener

Added in API level 24
fun addListener(
    listener: AccessibilityService.MagnificationController.OnMagnificationChangedListener,
    handler: Handler?
): Unit

Adds the specified change listener to the list of magnification change listeners. The callback will occur on the specified Handler's thread, or on the service's main thread if the handler is null.

Parameters
listener AccessibilityService.MagnificationController.OnMagnificationChangedListener: the listener to add, must be non-null
handler Handler?: the handler on which the callback should execute, or null to execute on the service's main thread

getCenterX

Added in API level 24
Deprecated in API level 33
fun getCenterX(): Float

Deprecated: Use getMagnificationConfig() instead

Returns the unscaled screen-relative X coordinate of the focal center of the magnified region. This is the point around which zooming occurs and is guaranteed to lie within the magnified region.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will return a default value of 0.0f.

Note: This legacy API gets the center position of full-screen magnification. To get the magnification center of the current controlling magnifier, use getMagnificationConfig instead.

Return
Float the unscaled screen-relative X coordinate of the center of the magnified region

getCenterY

Added in API level 24
Deprecated in API level 33
fun getCenterY(): Float

Deprecated: Use getMagnificationConfig() instead

Returns the unscaled screen-relative Y coordinate of the focal center of the magnified region. This is the point around which zooming occurs and is guaranteed to lie within the magnified region.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will return a default value of 0.0f.

Note: This legacy API gets the center position of full-screen magnification. To get the magnification center of the current controlling magnifier, use getMagnificationConfig instead.

Return
Float the unscaled screen-relative Y coordinate of the center of the magnified region

getCurrentMagnificationRegion

Added in API level 33
fun getCurrentMagnificationRegion(): Region

Returns the region of the screen currently active for magnification if the controlling magnification is MagnificationConfig#MAGNIFICATION_MODE_FULLSCREEN. Returns the region of screen projected on the magnification window if the controlling magnification is MagnificationConfig#MAGNIFICATION_MODE_WINDOW.

If the controlling mode is MagnificationConfig#MAGNIFICATION_MODE_FULLSCREEN, the returned region will be empty if the magnification is not active. And the magnification is active if magnification gestures are enabled or if a service is running that can control magnification.

If the controlling mode is MagnificationConfig#MAGNIFICATION_MODE_WINDOW, the returned region will be empty if the magnification is not activated.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will return an empty region.

Return
Region the magnification region of the currently controlling magnification This value cannot be null.

getMagnificationConfig

Added in API level 33
fun getMagnificationConfig(): MagnificationConfig?

Gets the MagnificationConfig of the controlling magnifier on the display.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will return null.

Return
MagnificationConfig? the magnification config that the service controls

getMagnificationRegion

Added in API level 24
Deprecated in API level 33
fun getMagnificationRegion(): Region

Deprecated: Use getCurrentMagnificationRegion() instead

Returns the region of the screen currently active for magnification. Changes to magnification scale and center only affect this portion of the screen. The rest of the screen, for example input methods, cannot be magnified. This region is relative to the unscaled screen and is independent of the scale and center point.

The returned region will be empty if magnification is not active. Magnification is active if magnification gestures are enabled or if a service is running that can control magnification.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will return an empty region.

Note: This legacy API gets the magnification region of full-screen magnification. To get the magnification region of the current controlling magnifier, use getCurrentMagnificationRegion() instead.

Return
Region the region of the screen currently active for magnification, or an empty region if magnification is not active. This value cannot be null.

getScale

Added in API level 24
Deprecated in API level 33
fun getScale(): Float

Deprecated: Use getMagnificationConfig() instead

Returns the current magnification scale.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will return a default value of 1.0f.

Note: This legacy API gets the scale of full-screen magnification. To get the scale of the current controlling magnifier, use getMagnificationConfig instead.

Return
Float the current magnification scale

removeListener

Added in API level 24
fun removeListener(listener: AccessibilityService.MagnificationController.OnMagnificationChangedListener): Boolean

Removes the specified change listener from the list of magnification change listeners.

Parameters
listener AccessibilityService.MagnificationController.OnMagnificationChangedListener: the listener to remove, must be non-null
Return
Boolean true if the listener was removed, false otherwise

reset

Added in API level 24
fun reset(animate: Boolean): Boolean

Resets magnification scale and center to their default (e.g. no magnification) values.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will have no effect and return false.

Note: This legacy API reset full-screen magnification. To reset the current controlling magnifier, use resetCurrentMagnification(boolean) ()} instead.

Parameters
animate Boolean: true to animate from the current scale and center or false to reset the scale and center immediately
Return
Boolean true on success, false on failure

resetCurrentMagnification

Added in API level 33
fun resetCurrentMagnification(animate: Boolean): Boolean

Resets magnification scale and center of the controlling magnification to their default (e.g. no magnification) values.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will have no effect and return false.

Parameters
animate Boolean: true to animate from the current scale and center or false to reset the scale and center immediately
Return
Boolean true on success, false on failure

setCenter

Added in API level 24
Deprecated in API level 33
fun setCenter(
    centerX: Float,
    centerY: Float,
    animate: Boolean
): Boolean

Deprecated: Use setMagnificationConfig(android.accessibilityservice.MagnificationConfig,boolean) instead

Sets the center of the magnified viewport.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will have no effect and return false.

Note: This legacy API sets the center of full-screen magnification. To set the center of the specified magnifier, use setMagnificationConfig instead.

Parameters
centerX Float: the unscaled screen-relative X coordinate on which to center the viewport
centerY Float: the unscaled screen-relative Y coordinate on which to center the viewport
animate Boolean: true to animate from the current viewport center or false to set the center immediately
Return
Boolean true on success, false on failure

setMagnificationConfig

Added in API level 33
fun setMagnificationConfig(
    config: MagnificationConfig,
    animate: Boolean
): Boolean

Sets the MagnificationConfig. The service controls the magnification by setting the config.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will have no effect and return false.

Parameters
config MagnificationConfig: the magnification config This value cannot be null.
animate Boolean: true to animate from the current spec or false to set the spec immediately
Return
Boolean true on success, false on failure

setScale

Added in API level 24
Deprecated in API level 33
fun setScale(
    scale: Float,
    animate: Boolean
): Boolean

Deprecated: Use setMagnificationConfig(android.accessibilityservice.MagnificationConfig,boolean) instead

Sets the magnification scale.

Note: If the service is not yet connected (e.g. AccessibilityService#onServiceConnected() has not yet been called) or the service has been disconnected, this method will have no effect and return false.

Note: This legacy API sets the scale of full-screen magnification. To set the scale of the specified magnifier, use setMagnificationConfig instead.

Parameters
scale Float: the magnification scale to set, must be >= 1 and <= 8
animate Boolean: true to animate from the current scale or false to set the scale immediately
Return
Boolean true on success, false on failure