This document describes the public API available to library consumers.
The namespace of this plugin is window.totalpave.Inset. It will become available after the deviceready event. Throughout this document, I'll refer to the totalpave.Inset object as Inset.
This library is authored in TypeScript and provides TypeScript typings, however consuming this package as typescript is experimental. If you use bundlers, you may get duplicate runtimes. Changes to how the library is consumed may change without warning.
This section describes the interfaces that will be encountered when using this API.
IInsets is an interface that describes an Inset dataset. It has the following structure:
interface IInsets {
top: number;
left: number;
right: number;
bottom: number;
}A type that describes the callback signature to addListener/removeListener. It contains the following signature:
type IInsetCallbackFunc = (inset: IInsets) => void;A type that describes the configuration object used when creating new Inset provider instances. All fields are optional.
Structure:
interface IInsetConfiguration {
mask?: number;
includeRoundedCorners?: boolean;
}If mask is not set, the default will be DISPLAY_CUTOUT | SYSTEM_BARS.
If includeRoundedCorners is not set, the default will be true.
An enumeration of mask values. These correlate to WindowInsetsCompat.Type though the values may not match, they are mapped during runtime.
Currently the following mask values are supported:
- CAPTION_BAR
- DISPLAY_CUTOUT
- IME
- MANDATORY_SYSTEM_GESTURES
- NAVIGATION_BARS
- STATUS_BARS
- SYSTEM_BARS
- SYSTEM_GESTURES
- TAPPABLE_ELEMENT
If the android SDK introduces any newer ones, feel free to open a PR.
Inset is a class that provides the APIs to retrieve and to listen for inset changes. It serves as a provider object and wil hold the configuration state as well as a collection of inset listeners. It is valid to have more than one Inset object alive in your application, with different configurations though it will be recommended to keep the instance count low for performance reasons.
Direct access to the Inset constructor is forbidden but an instance can be created via the static create method. If the Inset provider instance is no
longer used, it should be freed via Insets.free(inset) which will clean up
references to objects and allow them to be garbage collected, both in the webview
and in the Java/Native runtime. Additionally if your application holds any references to listener functions, they should also be cleaned up.
Note that the configuration parameters cannot be modified on an inset provider instance.
Creates a new Inset provider object with the given configuration. If the configuration object is missing, default values are used as indicated in IInsetConfiguration.
The returned Inset instance can be used to attach listeners on for inset
update notifications. When the provider is no longer needed, it should be freed by calling free().
Creating Inset objects will trigger a layout request, triggering an update on
all inset providers.
static create(config?: IInsetConfiguration): Promise<Inset>;Frees an inset provider, cleaning up references to allow objects to be garbage collected. Once freed, it will be unhooked from the global listener system and that inset provider instance will no longer receive inset updates.
It's the applications responsibility to clean up any retained IInsetCallbackFunc
listener functions.
static free(inset: Inset): Promise<void>;Alternatively, the inset can be freed by calling the instance member free.
free(): Promise<void>;Attaches a new handler which will be invoked when the view layout/inset information changes. The reference of callback must be retained by the user for the removeListener call.
When the callback is invoked, it will receive an IInset object as an argument.
addListener(callback: IInsetCallbackFunc): void;Removes an attached handler from the listener pool.
This will be a no-op if the callback is not in the listener pool.
removeListener(callback: IInsetCallbackFunc): void;Returns the last known IInset object.
getInset(): IInset;