Metrics¶
New in version 1.5.0.
A screen is defined by its actual physical size, density, resolution. These factors are essential for creating UI with correct size everywhere.
In Kivy, all our graphics pipeline is working with pixels. But using pixels as a measurement unit is wrong, because the size will changes according to the screen.
Dimensions¶
As you design your UI for different screen sizes, you’ll need new measurement unit to work with.
Units: |
|
---|
Examples¶
An example of creating a label with a sp font_size, and set a manual height with a 10dp margin:
#:kivy 1.5.0
<MyWidget>:
Label:
text: 'Hello world'
font_size: '15sp'
size_hint_y: None
height: self.texture_size[1] + dp(10)
Manual control of metrics¶
The metrics cannot be changed in runtime. Once a value has been converted to pixels, you don’t have the original value anymore. It’s not like you’ll change the DPI or density in runtime.
We provide new environment variables to control the metrics:
- KIVY_METRICS_DENSITY: if set, this value will be used for Metrics.density instead of the system one. On android, the value varies between 0.75, 1, 1.5. 2.
- KIVY_METRICS_FONTSCALE: if set, this value will be used for Metrics.fontscale instead of the system one. On android, the value varies between 0.8-1.2.
- KIVY_DPI: if set, this value will be used for Metrics.dpi. Please note that settings the DPI will not impact dp/sp notation, because thoses are based on the density.
For example, if you want to simulate an high-density screen (like HTC One X):
KIVY_DPI=320 KIVY_METRICS_DENSITY=2 python main.py --size 1280x720
Or a medium-density (like Motorola Droid 2):
KIVY_DPI=240 KIVY_METRICS_DENSITY=1.5 python main.py --size 854x480
You can also simulate an alternative user preference for fontscale, like:
KIVY_METRICS_FONTSCALE=1.2 python main.py
- kivy.metrics.metrics = <kivy.metrics.Metrics object at 0x1f712d0>¶
default instance of Metrics, used everywhere in the code
- class kivy.metrics.Metrics¶
Bases: object
Class that contain the default attribute for metrics. Don’t use the class directly, but use the metrics instance.
- density()¶
Return the density of the screen. This value is 1 by default on desktop, and varies on android depending the screen.
- dpi()¶
Return the DPI of the screen. Depending of the platform, the DPI can be taken from the Window provider (Desktop mainly), or from platform-specific module (like android/ios).
- dpi_rounded()¶
Return the dpi of the screen, rounded to the nearest of 120, 160, 240, 320.
- fontscale()¶
Return the fontscale user preference. This value is 1 by default, and can varies between 0.8-1.2.
- kivy.metrics.pt(value)¶
Convert from points to pixels
- kivy.metrics.inch(value)¶
Convert from inches to pixels
- kivy.metrics.cm(value)¶
Convert from centimeters to pixels
- kivy.metrics.mm(value)¶
Convert from millimeters to pixels
- kivy.metrics.dp(value)¶
Convert from density-independent pixels to pixels
- kivy.metrics.sp(value)¶
Convert from scale-independent pixels to pixels