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:
pt

Points - 1/72 of an inch based on the physical size of the screen. Prefer to use sp instead of pt.

mm

Millimeters - Based on the physical size of the screen

cm

Centimeters - Based on the physical size of the screen

in

Inches - Based on the physical size of the screen

dp

Density-independent Pixels - An abstract unit that is based on the physical density of the screen. With a Metrics.density of 1, 1dp is equal to 1px. When running on a higher density screen, the number of pixels used to draw 1dp is scaled up by the factor of appropriate screen’s dpi, and the inverse for lower dpi. The ratio dp-to-pixes will change with the screen density, but not necessarily in direct proportions. Using dp unit is a simple solution to making the view dimensions in your layout resize properly for different screen densities. In others words, it provides consistency for the real-world size of your UI across different devices.

sp

Scale-independent Pixels - This is like the dp unit, but it is also scaled by the user’s font size preference. It is recommended to use this unit when specifying font sizes, so they will be adjusted for both the screen density and the user’s preference.

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