Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/IslamKhSh/Xdimen
Easily support android multiple screen sizes
https://github.com/IslamKhSh/Xdimen
android dimensions multiple-screen ui-design
Last synced: 9 days ago
JSON representation
Easily support android multiple screen sizes
- Host: GitHub
- URL: https://github.com/IslamKhSh/Xdimen
- Owner: IslamKhSh
- License: apache-2.0
- Created: 2022-03-26T23:58:10.000Z (over 2 years ago)
- Default Branch: master
- Last Pushed: 2024-03-02T00:57:52.000Z (9 months ago)
- Last Synced: 2024-08-02T19:38:48.153Z (4 months ago)
- Topics: android, dimensions, multiple-screen, ui-design
- Language: Kotlin
- Homepage:
- Size: 3.35 MB
- Stars: 50
- Watchers: 4
- Forks: 13
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
- awesome-list - IslamKhSh/Xdimen - Easily support android multiple screen sizes (Kotlin)
README
# Xdimen
[](https://plugins.gradle.org/plugin/io.github.islamkhsh.xdimen) []( https://android-arsenal.com/details/1/8408 )
Support multiple screen sizes easily by scaling your dimensions.
## How does Xdimen work?
When you have a UI design with a specific dimension, and you need to support different mobiles or tablets in portrait or
landscape. This case **Xdimen** can help you to generate scalable dimesions for common devices' screen sizes.
Xdimen generates an alternative res directory for every common screen width (configurable) and scales your design
dimensions.
> Xml resources are generated with help of [kotlin xml builder](https://github.com/redundent/kotlin-xml-builder)
Find more about Xdimen [here](https://medium.com/@islam.khaled50/android-support-multiple-screen-sizes-by-scaling-dimensions-5fd9bd80821)
## Usage
### Add to project
Xdimen must be applied in an android project.
Groovy
````groovy
plugins {
id 'io.github.islamkhsh.xdimen' version "$latest_version"
// agp plugin
}
````
Kotlin
````kotlin
plugins {
id("io.github.islamkhsh.xdimen") version "$latest_version"
// agp plugin
}
````
### Configure Xdimen
All properties are optional, only `designWidth` is required. Properties are discussed in more detail in below section.
Groovy
````groovy
xdimen {
deleteOldXdimen = true
designWidth = 411 // required
designDpi = mdpi()
targetDevicesWidth = [360, 375, 411]
dimensRange {
minDimen = -10
maxDimen = 600
step = 0.5d
}
fontsRange {
minDimen = 10
maxDimen = 60
step = 1.0d
}
}
````
Kotlin
````kotlin
xdimen {
deleteOldXdimen.set(true)
designWidth.set(411) // required
designDpi.set(mdpi())
targetDevicesWidth.set(phonePortrait)
dimensRange {
minDimen.set(-10)
maxDimen.set(500)
step.set(0.5)
}
fontsRange {
minDimen.set(10)
maxDimen.set(60)
step.set(1.0)
}
}
````
### Use scaled dimens
After generate xdimen resources (see next section) you can use the dimens
```xml
```
## Tasks
To execute a task, make sure you execute it on an android project using one of these ways
- `$ gradle :prjectName:taskName`.
- From gradle tool window under `android` group.
- From `Run AnyThing` window.
### `generateXdimen`
Generates alternative resources for every device width in `targetDevicesWidth` set and for every created resource
qualifier it scales the dimensions to fit with this width. It uses configured properties to calculate a scaling factor,
get the range of dimensions to generate and the list of screen widths' to target.
### `deleteXdimen`
Delete the previous generated xdimen resources unless you renamed the res file or dir. It will be executed
before `generateXdimen` if you set `deleteOldXdimen` property by true.
## Configuration properties
deleteOldXdimen
By setting it when you execute `generateXdimen` task `deleteXdimen` will be executed first to delete all previous
generated xdimen resources and their dirs if the directory contains only `xdimen.xml` file.
> If you renamed the `xdimen.xml` file or its directory for any reason, this file won't be deleted.
> Default value: **true**.
designWidth
The value of screen width of your design in `dp` unit. It will be used with `designDpi` to calculate the
relativeDesignWidth (width relative to main density `mdpi`) and then calculate a scaling factor for every screen width
in `targetDevicesWidth`.
> If your design is in `px` set its width in this property and set `designDpi` to be `mdpi` as in mdpi 1px = 1dp.
> No default value because it's required and must be configured.
designDpi
The design screen density (dot per inch) [see more](https://developer.android.com/training/multiscreen/screendensities). This will be used with `designWidth` to calculate the relativeDesignWidth.
> Default value is: **mdpi**
> Predefined densities: for every density in [common densities](https://developer.android.com/training/multiscreen/screendensities#TaskProvideAltBmp) there's a method with its name ( `ldpi()`, `mdpi()`, `hdpi()`, ... etc), Also there's a method to set custom density `dpi(value)`.
targetDevicesWidth
The width of screens of devices which you target. For every width in this list, an alternative resource will be generated
with scaled dimensions.
ex: if the list is [350, 400] then
```
...
-> values/xdimen.xml # Devices with screen-width less than 350dp.
-> values-w350dp/xdimen.xml # 350dp <= screen-width < 400dp
-> values-w400dp/xdimen.xml # screen-width >= 400dp
...
```
> You can use a predefined set as it's, adds or removes from it, or provide your own set.
> Default value is: **[designWidth]** set of designWidth provided value.
> > Predefined sets for common devices:
> - `phonePortrait`: common phones in portrait orientation.
> - `phoneLandscape`: common phones in landscape orientation.
> - `tabletPortrait`: common tablets in portrait orientation.
> - `tabletLandscape`: common tablets in landscape orientation.
> ####
> - `devicesInPortrait`: common phones and tablets in portrait.
> - `devicesInLandscape`: common phones and tablets in landscape.
>
> You can combine multiple devices list, but I recommend not to target both portrait and landscape unless you provide a custom layout for landscape or using [Pane Layout](https://developer.android.com/guide/topics/ui/layout/twopane).
>
> These lists were collected from many sources: [Wikipedia](https://en.wikipedia.org/wiki/Comparison_of_high-definition_smartphone_displays#720p_by_1280_(HD_ready)),
[ScreenSize](https://screensiz.es/), [Pixensity](https://pixensity.com/list/) and others.
dimensRange
The range of dimensions you want to be generated and scaled.
- `minDimen`: the minimum dimen to be generated.
- `maxDimen`: the maximum dimen to be generated.
- `step`: the step between two generated dimen.
> Default value: **minDimen=-10**, **maxDimen=600**, **step=1.00**.
fontsRange
The same of `dimensRange` but for fonts dimensions range.
> Default value: **minDimen=6**, **maxDimen=48**, **step=1.00**.
## Screenshots
