ScreenEasy 💎 ScreenEz

🔥 An Android library that provides quick access to screen attributes like: screenSize, cutout, status/navbar, safeArea, ... without worrying about headache, deprecated stuffs.

 

what we want	reality

Table of Contents 📝

1. Install
2. Usage
3. Contribution guide
4. WIP Note 🚧
5. License

 

I. Install

Ensure your app’s minimum SDK version is 21+ and `mavenCentral()` included

1. Ensure your app’s minimum SDK version is 21+. This is declared in the module-level `build.gradle` file

android {
    defaultConfig {
        ...
        minSdk 21
    }

2. Ensure the mavenCentral() repository is declared in the project-level build.gradle or setting.gradle file:

   build.gradle (project-level)

       allprojects {
           repositories {
               mavenCentral()
               ...
           }
           ...
       }

   Alternative (In case "allprojects" not found). go to settings.gradle

   pluginManagement {
       repositories {
           ...
           mavenCentral()
       }
   }
   dependencyResolutionManagement {
       ...
       repositories {
           ...
           mavenCentral()
       }
   }

Declare the dependencies in the module-level build.gradle file 🍀

    dependencies {
        implementation "io.github.torrydo:screen-easy:<LATEST_VERSION>"
    }

II. Usage

1, Firstly, init ScreenEz.with(context) anywhere in your project

Optional: call ScreenEz.refresh() when configuration change (orientation/rotation change...)

If you are developing a library that use ScreenEasy internally, please create an instance of ScreenEasy() instead. You can find the reason here

Sample

// consider using this approach instead if you are developing a library/submodule
val screenEasy = ScreenEasy()
screenEasy.with(context)

2, That's it, no more step needed, enjoy! 💖

Java

API	Return	Description
with(context)	None	Call this function one time before any other function to setup properly. Calling multiple times is okay, but unnecessary
refresh()	None	Refresh attributes, call when configuration change, rotation, ...
getNavBarPadding()	ScreenPadding	Represent screen padding of system bar for navigation
getStatusBarPadding()	ScreenPadding	Represent screen padding of status bar.
getCutoutPadding()	ScreenPadding	Represent screen padding of cutout for the notch, or smth similar
getFullWidth()	Int	Width of the screen in pixel
getFullHeight()	Int	Height of the screen in pixel
getFullSize()	Size	Size of the screen in pixel
isButtonsNavigation()	Boolean	True if buttons navigation is being used
isGestureNavigation()	Boolean	True if gesture navigation is being used
getSafeArea()	ScreenArea	The area of the screen that is not obscured by the navigation bar, status bar, or other system UI elements.
getSafeScreenPadding()	ScreenPadding	Returns the safe screen padding
getSafePaddingLeft()	Int	Padding for LEFT edge to avoid overlap with system UI
getSafePaddingRight()	Int	Padding for RIGHT edge to avoid overlap with system UI
getSafePaddingTop()	Int	Padding for TOP edge to avoid overlap with system UI
getSafePaddingBottom()	Int	Padding for BOTTOM edge to avoid overlap with system UI
getSafeWidth()	Int	The width of the screen after subtracting the system bar on the left and right sides
getSafeHeight()	Int	The height of the screen after subtracting the system bar on the top and bottom sides
getSafeSize()	Size	The Size(width, height) of the screen after subtracting the system bar on all sides
getStatusBarHeight()	Int	status bar height (pixel unit)
getNavBarHeight()	Int	navigation bar height (both gesture and buttons in pixel unit)
isPortrait()	Boolean	True if screen is in portrait mode
getScreenRotation()	ScreenRotation	the rotation of the screen. (portrait, landscape, reversed...)

Kotlin

API	Return	Description
with(context)	None	Call this function one time before any other function to setup properly. Calling multiple times is okay, but unnecessary
refresh()	None	Refresh attributes, call when configuration change, rotation, ...
navBarPadding	ScreenPadding	Represent screen padding of system bar for navigation
statusBarPadding	ScreenPadding	Represent screen padding of status bar.
cutoutPadding	ScreenPadding	Represent screen padding of cutout for the notch, or smth similar
fullWidth	Int	Width of the screen in pixel
fullHeight	Int	Height of the screen in pixel
fullSize	Size	Size of the screen in pixel
safeArea	ScreenArea	The area of the screen that is not obscured by the navigation bar, status bar, or other system UI elements.
safeScreenPadding	ScreenPadding	Returns the safe screen padding
safePaddingLeft	Int	Padding for LEFT edge to avoid overlap with system UI
safePaddingRight	Int	Padding for RIGHT edge to avoid overlap with system UI
safePaddingTop	Int	Padding for TOP edge to avoid overlap with system UI
safePaddingBottom	Int	Padding for BOTTOM edge to avoid overlap with system UI
safeWidth	Int	The width of the screen after subtracting the system bar on the left and right sides
safeHeight	Int	The height of the screen after subtracting the system bar on the top and bottom sides
safeSize	Size	The Size of the screen after subtracting the system bar on all sides
statusBarHeight	Int	status bar height (pixel unit)
navBarHeight	Int	navigation bar height (both gesture and buttons in pixel unit)
screenRotation	ScreenRotation	the rotation of the screen. (portrait, landscape, reversed...)
isPortrait()	Boolean	true if screen is in portrait mode, false otherwise
isButtonsNavigation()	Boolean	true if buttons navigation is being used
isGestureNavigation()	Boolean	true if gesture navigation is being used

III, Contribution Guide 👏

Contributions are welcome! 🙌

• If you come across a bug or have an idea for a new feature, please let us know by creating an Issue 🐞🐛💡
• If you've already fixed a bug or implemented a feature, feel free to submit a Pull request 🚀
• Having questions, ideas, or feedback? Don't worry, I gotchu. Simply open a Discussion 🔊
• Find this project useful? Don't forget to show some love by giving a star ⭐

Thank you! 💖

IV, Work in Progress 🚧

This library is still under heavy development. There is still a lot of code cleanup to do, so expect breaking API changes over time.

Please refer to the following page to check out the change-log: Releases

Everything's gonna be ok! 🍀

V, License

    Copyright 2023 TorryDo

    Licensed under the Apache License, Version 2.0 (the "License");
    you may not use this file except in compliance with the License.
    You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing, software
    distributed under the License is distributed on an "AS IS" BASIS,
    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    See the License for the specific language governing permissions and
    limitations under the License.