Added in API level 37

LocationButtonSession

interface LocationButtonSession : AutoCloseable
android.app.permissionui.LocationButtonSession

This interface defines location button session, and allows apps to change/customize the appearance of the button.

A location button's UI is rendered by a trusted system process to ensure its integrity and prevent tap jacking. An instance of this interface is returned via LocationButtonClient.onSessionOpened after a session is requested through LocationButtonProvider.openSession.

Once a session is opened, the client can get the button's UI by calling getSurfacePackage() and embedding it in its view hierarchy. The client is responsible for notifying the session of any UI changes, such as size or configuration updates.

When the session is no longer needed, the client must call close() to release all associated system resources.

Summary

Constants
static Int

The button displays the text as "Near my precise location".
static Int

The button displays the text as "Near your precise location".
static Int

The button displays no text.
static Int

The button displays the text as "Precise location".
static Int

The button displays the text as "Share precise location".
static Int

The button displays the text as "Use precise location".
Public methods
abstract Unit

Notifies the remote service of a configuration change.
abstract Unit

Closes the session and releases all associated resources.
abstract SurfaceControlViewHost.SurfacePackage

Returns the SurfaceControlViewHost.SurfacePackage containing the view for the location button.
abstract Unit
resize(width: Int, height: Int)

Notifies the remote service that the button's container view has been resized.
abstract Unit

Sets the background color of the location button.
abstract Unit
setCornerRadius(cornerRadius: Float)

Sets the corner radius for the location button.
abstract Unit
setIconTint(color: Int)

Sets the tint color of the icon within the location button.
abstract Unit
setPadding(left: Int, top: Int, right: Int, bottom: Int)

Sets the padding for the location button within its container.
abstract Unit

Sets the corner radius for the location button pressed state.
abstract Unit

Sets the color of location button stroke/outline.
abstract Unit

Sets the width of location button stroke/outline.
abstract Unit
setTextColor(color: Int)

Sets the color of location button text.
abstract Unit
setTextType(textType: Int)

Sets the text to be displayed on the button.

Constants

TEXT_TYPE_NEAR_MY_PRECISE_LOCATION

Added in API level 37
static val TEXT_TYPE_NEAR_MY_PRECISE_LOCATION: Int

The button displays the text as "Near my precise location".

Value: 4

TEXT_TYPE_NEAR_YOUR_PRECISE_LOCATION

Added in API level 37
static val TEXT_TYPE_NEAR_YOUR_PRECISE_LOCATION: Int

The button displays the text as "Near your precise location".

Value: 5

TEXT_TYPE_NONE

Added in API level 37
static val TEXT_TYPE_NONE: Int

The button displays no text.

Value: 0

TEXT_TYPE_PRECISE_LOCATION

Added in API level 37
static val TEXT_TYPE_PRECISE_LOCATION: Int

The button displays the text as "Precise location".

Value: 1

TEXT_TYPE_SHARE_PRECISE_LOCATION

Added in API level 37
static val TEXT_TYPE_SHARE_PRECISE_LOCATION: Int

The button displays the text as "Share precise location".

Value: 3

TEXT_TYPE_USE_PRECISE_LOCATION

Added in API level 37
static val TEXT_TYPE_USE_PRECISE_LOCATION: Int

The button displays the text as "Use precise location".

Value: 2

Public methods

changeConfiguration

Added in API level 37
abstract fun changeConfiguration(newConfig: Configuration): Unit

Notifies the remote service of a configuration change.

This should be called when the application's configuration changes, for example, due to a device rotation or a theme change (e.g., light to dark mode).

Parameters
newConfig Configuration: The new configuration.
This value cannot be null.

close

Added in API level 37
abstract fun close(): Unit

Closes the session and releases all associated resources.

This releases the underlying surface and the connection to the remote service. Once closed, the location button UI is removed, and the session is no longer usable.

Exceptions
java.lang.Exception if this resource cannot be closed

getSurfacePackage

Added in API level 37
abstract fun getSurfacePackage(): SurfaceControlViewHost.SurfacePackage

Returns the SurfaceControlViewHost.SurfacePackage containing the view for the location button.

The client can attach surface package to a android.view.SurfaceView in its view hierarchy to display the button. This allows the button's UI to be rendered by a trusted system process while being seamlessly integrated into the application's layout.

Return
SurfaceControlViewHost.SurfacePackage The surface package for the location button.
This value cannot be null.

resize

Added in API level 37
abstract fun resize(
    width: Int, 
    height: Int
): Unit

Notifies the remote service that the button's container view has been resized.

The remote service will re-layout the button to fit within the new dimensions.

See LocationButtonRequest.Builder.Builder(int,int,Configuration) for width and height input constraints.

Parameters
width Int: The new width of the button's container, in pixels.
height Int: The new height of the button's container, in pixels.

setBackgroundColor

Added in API level 37
abstract fun setBackgroundColor(color: Int): Unit

Sets the background color of the location button.

See LocationButtonRequest.Builder.setBackgroundColor(int) for input constraints.

Parameters
color Int: The desired background color, as a ColorInt.

setCornerRadius

Added in API level 37
abstract fun setCornerRadius(cornerRadius: Float): Unit

Sets the corner radius for the location button.

See LocationButtonRequest.Builder.setCornerRadius(float) for input constraints.

Parameters
cornerRadius Float: The corner radius in pixels.

setIconTint

Added in API level 37
abstract fun setIconTint(color: Int): Unit

Sets the tint color of the icon within the location button.

See LocationButtonRequest.Builder.setIconTint(int) for input constraints.

Parameters
color Int: The desired icon tint color, as a ColorInt.

setPadding

Added in API level 37
abstract fun setPadding(
    left: Int, 
    top: Int, 
    right: Int, 
    bottom: Int
): Unit

Sets the padding for the location button within its container.

See the padding setters (e.g., LocationButtonRequest.Builder.setPaddingLeft(int)) for input constraints.

Parameters
left Int: The left padding in pixels.
top Int: The top padding in pixels.
right Int: The right padding in pixels.
bottom Int: The bottom padding in pixels.

setPressedCornerRadius

Added in API level 37
abstract fun setPressedCornerRadius(cornerRadius: Float): Unit

Sets the corner radius for the location button pressed state.

See LocationButtonRequest.Builder.setPressedCornerRadius(float) for input constraints.

Parameters
cornerRadius Float: The corner radius in pixels.

setStrokeColor

Added in API level 37
abstract fun setStrokeColor(color: Int): Unit

Sets the color of location button stroke/outline.

See LocationButtonRequest.Builder.setStrokeColor(int) for input constraints.

Parameters
color Int: The desired outline color, as a ColorInt.

setStrokeWidth

Added in API level 37
abstract fun setStrokeWidth(width: Int): Unit

Sets the width of location button stroke/outline.

See LocationButtonRequest.Builder.setStrokeWidth(int) for input constraints.

Parameters
width Int: The desired stroke width.

setTextColor

Added in API level 37
abstract fun setTextColor(color: Int): Unit

Sets the color of location button text.

See LocationButtonRequest.Builder.setTextColor(int) for input constraints.

Parameters
color Int: The desired text color, as a ColorInt.

setTextType

Added in API level 37
abstract fun setTextType(textType: Int): Unit

Sets the text to be displayed on the button.

See LocationButtonRequest.Builder.setTextType(int) for input constraints.

Parameters
textType Int: The text type for the button text.
Value is one of the following: