Module Expr Str Assign NameStore TupleLoad Str Str Str Str Str Str Str Str ImportFrom alias ImportFrom alias alias ImportFrom alias ImportFrom alias FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad NameLoad Str decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad NameLoad Str decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad NameLoad Str decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad NameLoad Str decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad NameLoad Str decorator_list FunctionDef arguments args NameParam defaults body Expr Str Return Call NameLoad NameLoad Str decorator_list ClassDef bases NameLoad body Expr Str FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore Call AttributeLoad NameLoad attr Str If NameLoad body Return Call NameLoad NameLoad If CompareEq NameLoad Str body If NameLoad body Import alias Assign NameStore Call AttributeLoad NameLoad attr Str Return Call AttributeLoad NameLoad attr orelse Import alias Return Call AttributeLoad NameLoad attr orelse If CompareEq NameLoad Str body Import alias Return Call AttributeLoad NameLoad attr ImportFrom alias Expr Call AttributeLoad NameLoad attr Return AttributeLoad AttributeLoad NameLoad attr attr decorator_list NameLoad FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore AttributeLoad NameLoad attr If CompareLt NameLoad Num body Return Num orelse If CompareLt NameLoad Num body Return Num orelse If CompareLt NameLoad Num body Return Num Return Num decorator_list NameLoad FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore Call AttributeLoad NameLoad attr Str If NameLoad body Return Call NameLoad NameLoad If CompareEq NameLoad Str body Import alias Assign NameStore Call AttributeLoad NameLoad attr Str Return AttributeLoad AttributeLoad NameLoad attr attr orelse If CompareEq NameLoad Str body Import alias Return Call AttributeLoad NameLoad attr orelse If CompareEq NameLoad Str body ImportFrom alias Expr Call AttributeLoad NameLoad attr Return BinOpDiv AttributeLoad AttributeLoad NameLoad attr attr Num Return Num decorator_list NameLoad FunctionDef arguments args NameParam defaults body Expr Str Assign NameStore Call AttributeLoad NameLoad attr Str If NameLoad body Return Call NameLoad NameLoad If CompareEq NameLoad Str body ImportFrom alias If NameLoad body Assign NameStore Call NameLoad Str orelse Assign NameStore Call NameLoad Str Assign NameStore Call AttributeLoad Call AttributeLoad AttributeLoad NameLoad attr attr attr Return AttributeLoad NameLoad attr Return Num decorator_list NameLoad decorator_list Assign NameStore Call NameLoad
N/A N/A 
Metrics
=======

.. versionadded:: 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 :attr:`~MetricsBase.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
  :attr:`~MetricsBase.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
  :attr:`~MetricsBase.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 :attr:`~MetricsBase.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

 N/A __all__ N/A Metrics MetricsBase pt inch cm mm dp sp os environ kivy.utils reify platform kivy.properties dpi2px kivy.setupconfig USE_SDL2 pt N/A N/A value N/A N/A N/A Convert from points to pixels
     N/A N/A dpi2px value pt N/A inch N/A N/A value N/A N/A N/A Convert from inches to pixels
     N/A N/A dpi2px value in N/A cm N/A N/A value N/A N/A N/A Convert from centimeters to pixels
     N/A N/A dpi2px value cm N/A mm N/A N/A value N/A N/A N/A Convert from millimeters to pixels
     N/A N/A dpi2px value mm N/A dp N/A N/A value N/A N/A N/A Convert from density-independent pixels to pixels
     N/A N/A dpi2px value dp N/A sp N/A N/A value N/A N/A N/A Convert from scale-independent pixels to pixels
     N/A N/A dpi2px value sp N/A MetricsBase N/A object N/A N/A Class that contains the default attributes for Metrics. Don't use this
    class directly, but use the `Metrics` instance.
     dpi N/A N/A self N/A N/A N/A Return 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).
         N/A custom_dpi N/A N/A environ get KIVY_DPI N/A custom_dpi N/A N/A N/A float custom_dpi N/A N/A platform android N/A N/A USE_SDL2 N/A N/A jnius N/A Hardware N/A N/A jnius autoclass org.renpy.android.Hardware N/A N/A N/A Hardware getDPI N/A N/A android N/A N/A N/A android get_dpi N/A N/A N/A platform ios N/A N/A ios N/A N/A N/A ios get_dpi kivy.base EventLoop N/A N/A N/A EventLoop ensure_window N/A N/A N/A EventLoop window dpi N/A reify dpi_rounded N/A N/A self N/A N/A N/A Return the DPI of the screen, rounded to the nearest of 120, 160,
        240 or 320.
         N/A dpi N/A self dpi N/A N/A dpi 140 N/A N/A 120 N/A N/A N/A dpi 200 N/A N/A 160 N/A N/A N/A dpi 280 N/A N/A 240 N/A 320 N/A reify density N/A N/A self N/A N/A N/A Return the density of the screen. This value is 1 by default
        on desktops but varies on android depending on the screen.
         N/A custom_density N/A N/A environ get KIVY_METRICS_DENSITY N/A custom_density N/A N/A N/A float custom_density N/A N/A platform android N/A N/A jnius N/A Hardware N/A N/A jnius autoclass org.renpy.android.Hardware N/A N/A N/A Hardware metrics scaledDensity N/A N/A N/A platform ios N/A N/A ios N/A N/A N/A ios get_scale N/A N/A N/A platform macosx N/A kivy.base EventLoop N/A N/A N/A EventLoop ensure_window N/A N/A N/A N/A EventLoop window dpi 96.0 N/A 1.0 N/A reify fontscale N/A N/A self N/A N/A N/A Return the fontscale user preference. This value is 1 by default but
        can vary between 0.8 and 1.2.
         N/A custom_fontscale N/A N/A environ get KIVY_METRICS_FONTSCALE N/A custom_fontscale N/A N/A N/A float custom_fontscale N/A N/A platform android N/A jnius autoclass N/A USE_SDL2 N/A N/A PythonActivity N/A autoclass org.kivy.android.PythonActivity N/A N/A PythonActivity N/A autoclass org.renpy.android.PythonActivity N/A config N/A N/A N/A N/A N/A PythonActivity mActivity getResources getConfiguration N/A N/A config fontScale N/A 1.0 N/A reify N/A N/A Metrics N/A MetricsBase