@hiloenergie/capacitor-plugin-native-gestures-area

Gestures Area

@hiloenergie/capacitor-plugin-native-gestures-area

A plugin to expose the native gestures area insets from the native iOS/Android device to your web project.

Maintainers

This is a fork of @capacitor-community/safe-area modified to return the native gestures area. Note that the modifications impact only Android as iOS Insets already covers the native gestures areas

Maintainer	GitHub	Social
Kevin Pacheco	PolymorphiK	@k_pacheco10

Installation

Soon(TM)

Configuration

For Android, register plugin in your main activity.

import com.getcapacitor.community.gesturesarea.GesturesAreaPlugin;

public class MainActivity extends BridgeActivity {
  @Override
  public void onCreate(Bundle savedInstanceState) {
	super.onCreate(savedInstanceState);
  
	this.init(savedInstanceState, new ArrayList<Class<? extends Plugin>>() {{
	  add(GesturesAreaPlugin.class);
	}});
  }
}

Here is a bonus tip, to get full screen mode use this in your main activity. Requires Android 28+

@Override
public void onResume() {
super.onResume();

// Requires API 28+
this.getWindow().getAttributes().layoutInDisplayCutoutMode = WindowManager.LayoutParams.LAYOUT_IN_DISPLAY_CUTOUT_MODE_SHORT_EDGES;

View decorView = this.getWindow().getDecorView();

decorView.setSystemUiVisibility(
		View.SYSTEM_UI_FLAG_IMMERSIVE_STICKY
				// Set the content to appear under the system bars so that the
				// content doesn't resize when the system bars hide and show.
				| View.SYSTEM_UI_FLAG_LAYOUT_STABLE
				| View.SYSTEM_UI_FLAG_LAYOUT_HIDE_NAVIGATION
				| View.SYSTEM_UI_FLAG_LAYOUT_FULLSCREEN
				// Hide the nav bar and status bar
				| View.SYSTEM_UI_FLAG_HIDE_NAVIGATION
				| View.SYSTEM_UI_FLAG_FULLSCREEN);
}

To change the Android build version, change the minSdkVersion to at least 28 in the variables.gradle file.
For more information please see Android's immersive, and short edges documentation.

Usage

Register the plugin via the entry file of your project.

// Register Capacitor Plugin...
import '@capacitor-community/gestures-area';

It is strongly recomended that you use the GesturesAreaController as it makes it super easy to use the plugin :)

import { GesturesAreaController } from '@capacitor-community/gestures-area';

// Initialize the controller.
GesturesAreaController.load();

// Gets the insets object
// Shape
/*
 {
     top: number,
     bottom: number,
     right: number,
     left: number,
 }
 */
GesturesAreaController.getInsets();

// Use this to listen for changes in the insets.
// i.e. when the device is rotated
GesturesAreaController.addListener((insets) => {
    
});

// Use this to force the plugin to invoke the event
// Example, after you add a listener perhaps you invoke refresh
// to get the most up-to-date inset values.
GesturesAreaController.refresh();

// Uninitialize the controller when you don't need it anymore.
GesturesAreaController.unload();

Once the GesturesAreaController has been loaded, it will inject CSS variables for you to use in your style sheets.

/* styling for every case Web, iOS, and/or Android */
.myContainer {
	paddingTop: max(1.5rem, val(--gestures-area-inset-top)); 
	paddingLeft: max(1.5rem, val(--gestures-area-inset-left));
	paddingRight: max(1.5rem, val(--gestures-area-inset-right));
	paddingBottom: val(--gestures-area-inset-bottom);
}

/* If you need Android specific stying */
.myContainerForAndroidOnly {
	paddingTop: max(1.5rem, val(--android-gestures-area-inset-top)); 
	paddingLeft: max(1.5rem, val(--android-gestures-area-inset-left));
	paddingRight: max(1.5rem, val(--android-gestures-area-inset-right));
	paddingBottom: val(--android-gestures-area-inset-bottom);
}

/* If you need iOS specific styling */
.myContainerForIOSOnly {
	paddingTop: max(1.5rem, val(--ios-gestures-area-inset-top)); 
	paddingLeft: max(1.5rem, val(--ios-gestures-area-inset-left));
	paddingRight: max(1.5rem, val(--ios-gestures-area-inset-right));
	paddingBottom: val(--ios-gestures-area-inset-bottom);
}

This can also be used with the styles attribute in something like React.js for example.

// This div will grow to cover the area of the cutout
// this would be at the very top.
<div
	style={{
		height: "var(--gestures-area-inset-top)",
		backgroundColor: "#12005e"
	}}>
</div>

React - GesturesAreaInsetsProvider

Here is a component that can be used by React.js developers. This handles everything for you via the GesturesAreaController. There is a hook you can use as well called useGesturesAreaInsetsState which will return a JSON object with top, bottom, right, and left number properties.

import * as React from 'react';
import { GesturesAreaController } from '@capacitor-community/gestures-area';

const StateContext = React.createContext();

export const useGesturesAreaInsetsState = () => {
	const context = React.useContext(StateContext);

	if(context === undefined)
		throw new Error("Cannot use 'useGesturesAreaInsetsState' outside of a GesturesAreaInsetsProvider!");
	
	return context;
}

const GesturesAreaInsetsProvider = ({children}) => {
	const [state, setState] = React.useState({
		top: 0,
		bottom: 0,
		right: 0,
		left: 0
	});

	React.useState(() => {
		GesturesAreaController.addListener((insets) => {
			setState(insets);
		});

		GesturesAreaController.load();

		return () => {
			GesturesAreaController.removeAllListeners();
			GesturesAreaController.unload();
		}
	}, []);

	return (
		<StateContext.Provider value={state}>
			{children}
		</StateContext.Provider>
	)
};

export default GesturesAreaInsetsProvider;

You can then use this provider ideally in the index file of your project.

ReactDOM.render(
	<React.StrictMode>
		<GesturesAreaInsetsProvider>
			<App />
		</GesturesAreaInsetsProvider>
	</React.StrictMode>,
	document.getElementById('root')
);