Version

Quick search

Table Of Contents

Metrics

New in version 1.5.0.

A screen is defined by its physical size, density and resolution. These factors are essential for creating UI’s with correct size everywhere.

In Kivy, all the graphics pipelines work with pixels. But using pixels as a measurement unit is problematic because sizes change according to the screen.

Dimensions

If you want to design your UI for different screen sizes, you will want better measurement units to work with. Kivy provides some more scalable alternatives.

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 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 a factor appropriate to the screen’s dpi, and the inverse for a lower dpi. The ratio of dp-to-pixels will change with the screen density, but not necessarily in direct proportion. Using the 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. We recommend you use this unit when specifying font sizes, so the font size will be adjusted to both the screen density and the user’s preference.

Examples

Here is an example of creating a label with a sp font_size and setting the height manually 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 at runtime. Once a value has been converted to pixels, you can’t retrieve the original value anymore. This stems from the fact that the DPI and density of a device cannot be changed at runtime.

We provide some environment variables to control metrics:

  • KIVY_METRICS_DENSITY: if set, this value will be used for density instead of the systems one. On android, the value varies between 0.75, 1, 1.5 and 2.

  • KIVY_METRICS_FONTSCALE: if set, this value will be used for fontscale instead of the systems one. On android, the value varies between 0.8 and 1.2.

  • KIVY_DPI: if set, this value will be used for dpi. Please note that setting the DPI will not impact the dp/sp notation because these are based on the screen density.

For example, if you want to simulate a high-density screen (like the 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 as follows:

KIVY_METRICS_FONTSCALE=1.2 python main.py
kivy.metrics.Metrics: MetricsBase = <kivy.metrics.MetricsBase object>

The metrics object storing the window scaling factors.

New in version 1.7.0.

Changed in version 2.1.0: Metrics is now a Context registered variable (like e.g. Clock).

class kivy.metrics.MetricsBase(**kwargs)[source]

Bases: kivy.event.EventDispatcher

Class that contains the default attributes for Metrics. Don’t use this class directly, but use the Metrics instance.

cm: float

The scaling factor that converts from centimeters to pixels.

cm is a AliasProperty containing the factor. E.g in KV: width: self.texture_size[0] + 10 * Metrics.cm will update width when cm changes from a screen configuration change.

density: float

The density of the screen.

This value is 1 by default on desktops but varies on android depending on the screen.

density is a AliasProperty and can be set to change the value. But, the density is reloaded and reset if we got it from the Window and the Window density changed.

dp: float

The scaling factor that converts from density-independent pixels to pixels.

dp is a AliasProperty containing the factor. E.g in KV: width: self.texture_size[0] + 10 * Metrics.dp will update width when dp changes from a screen configuration change.

dpi: float

The DPI of the screen.

Depending on the platform, the DPI can be taken from the Window provider (Desktop mainly) or from a platform-specific module (like android/ios).

dpi is a AliasProperty and can be set to change the value. But, the density is reloaded and reset if we got it from the Window and the Window dpi changed.

dpi_rounded: int

Return the dpi of the screen, rounded to the nearest of 120, 160, 240 or 320.

dpi_rounded is a AliasProperty and updates when dpi changes.

fontscale: float

The fontscale user preference.

This value is 1 by default but can vary between 0.8 and 1.2.

fontscale is a AliasProperty and can be set to change the value.

inch: float

The scaling factor that converts from inches to pixels.

inch is a AliasProperty containing the factor. E.g in KV: width: self.texture_size[0] + 10 * Metrics.inch will update width when inch changes from a screen configuration change.

mm: float

The scaling factor that converts from millimeters to pixels.

mm is a AliasProperty containing the factor. E.g in KV: width: self.texture_size[0] + 10 * Metrics.mm will update width when mm changes from a screen configuration change.

pt: float

The scaling factor that converts from points to pixels.

pt is a AliasProperty containing the factor. E.g in KV: width: self.texture_size[0] + 10 * Metrics.pt will update width when pt changes from a screen configuration change.

reset_dpi(*args)[source]

Resets the dpi (and possibly density) to the platform values, overwriting any manually set values.

reset_metrics()[source]

Resets the dpi/density/fontscale to the platform values, overwriting any manually set values.

sp: float

The scaling factor that converts from scale-independent pixels to pixels.

sp is a AliasProperty containing the factor. E.g in KV: width: self.texture_size[0] + 10 * Metrics.sp will update width when sp changes from a screen configuration change.

kivy.metrics.cm(value) → float[source]

Convert from centimeters to pixels

kivy.metrics.dp(value) → float[source]

Convert from density-independent pixels to pixels

kivy.metrics.dpi2px(value, unicode ext) → float

Converts the value according to the ext.

kivy.metrics.inch(value) → float[source]

Convert from inches to pixels

kivy.metrics.mm(value) → float[source]

Convert from millimeters to pixels

kivy.metrics.pt(value) → float[source]

Convert from points to pixels

kivy.metrics.sp(value) → float[source]

Convert from scale-independent pixels to pixels

« Low level Metrics Multistroke gesture recognizer »