LocationButtonSession

public interface LocationButtonSession
implements 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

int TEXT_TYPE_NEAR_MY_PRECISE_LOCATION

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

int TEXT_TYPE_NEAR_YOUR_PRECISE_LOCATION

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

int TEXT_TYPE_NONE

The button displays no text.

int TEXT_TYPE_PRECISE_LOCATION

The button displays the text as "Precise location".

int TEXT_TYPE_SHARE_PRECISE_LOCATION

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

int TEXT_TYPE_USE_PRECISE_LOCATION

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

Public methods

abstract void changeConfiguration(Configuration newConfig)

Notifies the remote service of a configuration change.

abstract void close()

Closes the session and releases all associated resources.

abstract SurfaceControlViewHost.SurfacePackage getSurfacePackage()

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

abstract void resize(int width, int height)

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

abstract void setBackgroundColor(int color)

Sets the background color of the location button.

abstract void setCornerRadius(float cornerRadius)

Sets the corner radius for the location button.

abstract void setIconTint(int color)

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

abstract void setPadding(int left, int top, int right, int bottom)

Sets the padding for the location button within its container.

abstract void setPressedCornerRadius(float cornerRadius)

Sets the corner radius for the location button pressed state.

abstract void setStrokeColor(int color)

Sets the color of location button stroke/outline.

abstract void setStrokeWidth(int width)

Sets the width of location button stroke/outline.

abstract void setTextColor(int color)

Sets the color of location button text.

abstract void setTextType(int textType)

Sets the text to be displayed on the button.

Inherited methods

Constants

TEXT_TYPE_NEAR_MY_PRECISE_LOCATION

Added in API level 37 
public static final int TEXT_TYPE_NEAR_MY_PRECISE_LOCATION

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

Constant Value: 4 (0x00000004)

TEXT_TYPE_NEAR_YOUR_PRECISE_LOCATION

Added in API level 37 
public static final int TEXT_TYPE_NEAR_YOUR_PRECISE_LOCATION

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

Constant Value: 5 (0x00000005)

TEXT_TYPE_NONE

Added in API level 37 
public static final int TEXT_TYPE_NONE

The button displays no text.

Constant Value: 0 (0x00000000)

TEXT_TYPE_PRECISE_LOCATION

Added in API level 37 
public static final int TEXT_TYPE_PRECISE_LOCATION

The button displays the text as "Precise location".

Constant Value: 1 (0x00000001)

TEXT_TYPE_SHARE_PRECISE_LOCATION

Added in API level 37 
public static final int TEXT_TYPE_SHARE_PRECISE_LOCATION

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

Constant Value: 3 (0x00000003)

TEXT_TYPE_USE_PRECISE_LOCATION

Added in API level 37 
public static final int TEXT_TYPE_USE_PRECISE_LOCATION

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

Constant Value: 2 (0x00000002)

Public methods

changeConfiguration

Added in API level 37 
public abstract void changeConfiguration (Configuration newConfig)

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 
public abstract void close ()

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.

getSurfacePackage

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

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

The client can attach surface package to a 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.

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

resize

Added in API level 37 
public abstract void resize (int width, 
                int height)

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 
public abstract void setBackgroundColor (int color)

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 ERROR(ColorInt/android.annotation.ColorInt ColorInt).

setCornerRadius

Added in API level 37 
public abstract void setCornerRadius (float cornerRadius)

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 
public abstract void setIconTint (int color)

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 ERROR(ColorInt/android.annotation.ColorInt ColorInt).

setPadding

Added in API level 37 
public abstract void setPadding (int left, 
                int top, 
                int right, 
                int bottom)

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 
public abstract void setPressedCornerRadius (float cornerRadius)

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 
public abstract void setStrokeColor (int color)

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 ERROR(ColorInt/android.annotation.ColorInt ColorInt).

setStrokeWidth

Added in API level 37 
public abstract void setStrokeWidth (int width)

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 
public abstract void setTextColor (int color)

Sets the color of location button text.

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

Parameters
color int: The desired text color, as a ERROR(ColorInt/android.annotation.ColorInt ColorInt).

setTextType

Added in API level 37 
public abstract void setTextType (int textType)

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: