Class: CrowsNest

CrowsNest is a class which provides the "safe" full screen area that can be used without being cut off by the shape of the display or browser UI elements. including whether or not a virtual keyboard is open.

Constructors

Constructor

new CrowsNest(onDebug?: (...args: []) => void): CrowsNest;

Creates a new CrowsNest instance

Parameters

Parameter	Type	Description
onDebug?	(...args: []) => void	A callback function which is called when a debug message is emitted

Returns

CrowsNest

Accessors

keyboard

Get Signature

get keyboard(): KeyboardState;

Determines if the virtual keyboard is open or closed

Returns

KeyboardState

---

observable

Get Signature

get observable(): Surface;

The area which is safe to put content into without risking it being cut off by the shape of a non‑rectangular display or the virtual keyboard

Returns

Surface

---

apis

Get Signature

get static apis(): {
  Document: boolean;
  ResizeObserver: boolean;
  Screen: boolean;
  VirtualKeyboard: boolean;
  VisualViewport: boolean;
  Window: boolean;
  WindowControlsOverlay: boolean;
};

Returns a boolean indicating if an API which is used by CrowsNest is available in the current environment.

Returns

{
  Document: boolean;
  ResizeObserver: boolean;
  Screen: boolean;
  VirtualKeyboard: boolean;
  VisualViewport: boolean;
  Window: boolean;
  WindowControlsOverlay: boolean;
}

Name	Type	Description
Document	boolean	If the Document API is available in the current environment
ResizeObserver	boolean	If the ResizeObserver API is available in the current environment
Screen	boolean	If the Screen API is available in the current environment
VirtualKeyboard	boolean	If the VirtualKeyboard API is available in the current environment
VisualViewport	boolean	If the VisualViewport API is available in the current environment
Window	boolean	If the Window API is available in the current environment
WindowControlsOverlay	boolean	If the WindowControlsOverlay API is available in the current environment

Methods

bindHtmlElement()

bindHtmlElement(elem: HTMLElement): void;

Bind Crows Nest to an HTML element. This will make the element resize and move with the observable safe area.

Parameters

Parameter	Type	Description
elem	HTMLElement	The HTML element to bind to the observable safe area

Returns

void

---

bindVueRef()

bindVueRef(ref: Ref<Surface>): void;

Bind Crows Nest to a Vue ref. This will update the ref with the observable safe area.

Parameters

Parameter	Type	Description
ref	Ref<Surface>	The Vue ref to bind to the observable safe area

Returns

void

---

destroy()

destroy(): void;

Removes all elements and event listeners created by CrowsNest

Returns

void

---

off()

off<K>(event: K, callback?: CrowsNestEvents[K]): this;

Removes the specified listener from the listener array for the event named eventName.

off() will remove, at most, one instance of a listener from the listener array. If any single listener has been added multiple times to the listener array for the specified eventName, then off() must be called multiple times to remove each instance.

Once an event is emitted, all listeners attached to it at the time of emitting are called in order. This implies that any off() calls after emitting and before the last listener finishes execution will not remove them fromemit() in progress. Subsequent events behave as expected.

Because listeners are managed using an internal array, calling this will change the position indices of any listener registered after the listener being removed. This will not impact the order in which listeners are called.

When a single function has been added as a handler multiple times for a single event, off() will remove the most recently added instance.

Returns a reference to the CrowsNest, so that calls can be chained.

Type Parameters

Type Parameter
K extends string | number

Parameters

Parameter	Type
event	K
callback?	CrowsNestEvents[K]

Returns

this

---

on()

on<K>(
   event: K,
   callback: CrowsNestEvents[K],
   ctx?: any): this;

Adds the listener function to the end of the listeners array for the event named event. No checks are made to see if the listener has already been added. Multiple calls passing the same combination of event and listener will result in the listener being added, and called, multiple times.

Returns a reference to the CrowsNest, so that calls can be chained.

Event listeners are invoked in the order they are added.

Type Parameters

Type Parameter
K extends keyof CrowsNestEvents

Parameters

Parameter	Type	Description
event	K	The name of the event.
callback	CrowsNestEvents[K]	The callback function
ctx?	any	-

Returns

this

---

once()

once<K>(
   event: K,
   callback: CrowsNestEvents[K],
   ctx?: any): this;

Adds a one-time listener function for the event named event. The next time event is triggered, this listener is removed and then invoked.

Returns a reference to the CrowsNest, so that calls can be chained.

Event listeners are invoked in the order they are added.

Type Parameters

Type Parameter
K extends keyof CrowsNestEvents

Parameters

Parameter	Type	Description
event	K	The name of the event.
callback	CrowsNestEvents[K]	The callback function
ctx?	any	-

Returns

this

---

unbindHtmlElement()

unbindHtmlElement(elem: HTMLElement): void;

Unbind Crows Nest from an HTML element. This will stop the element from resizing and moving with the observable safe area.

Parameters

Parameter	Type	Description
elem	HTMLElement	The HTML element to unbind from the observable safe area

Returns

void

---

unbindVueRef()

unbindVueRef(ref: Ref<Surface>): void;

Unbind Crows Nest from a Vue ref. This will stop the ref from updating with the observable safe area.

Parameters

Parameter	Type	Description
ref	Ref<Surface>	The Vue ref to unbind from the observable safe area

Returns

void