# Pympress package

This page contains the inline documentation, generated from the code using sphinx.

The code is documented in the source using the Google style for docstrings. Sphinx has gathered a set of examples which serves as a better crash course than the full style reference.

Retructured text (rst) can be used inside the comments and docstrings.

## Modules

### `pympress.util` – various utility functions

class pympress.util.Monitor(obj, id_=None, num=None)

  Bases: `ScreenArea`

  A specialised `ScreenArea` representing a monitor, with an descriptive string and a monitor number

  static lookup_monitors(display, *windows)

    Get the info on the monitors

    Parameters:

      - display (`Display`) – the current screen

      - *windows (`tuple` of `Window`) – windows for wich to look up the monitor position

    Returns:

      The monitors for each window, followed by the best monitors for presenter and content

    Return type:

      `tuple` of `Monitor`

  monitor_number = -1

    An `int` that identifies the monitor in `Display`

  name = ''

    A `str` to represent a user-friendly name for the monitor

exception pympress.util.NoMonitorPositions

  Bases: `Exception`

  The Exception we raise when there is no way of figuring out the monitor position of windows

class pympress.util.ScreenArea(obj)

  Bases: `object`

  Convenience class to represent monitors or windows in terms of the area (position and size) they use on screen

  This is similar to `Monitor`, but necessary as we want to handle “mirrored” monitors as if they were a single monitor, and only use “extended” monitors as target for content window position and/or fullscreening.

  contains(other)

    Check whether this area contains `other`

    Parameters:

      other (`ScreenArea`) – The screen area to compare with

    Returns:

      `True` iff the area is contained

    Return type:

      `bool`

  equal(other)

    Check whether 2 areas cover the exact same space

    Parameters:

      other (`ScreenArea`) – The screen area to compare with

    Returns:

      `True` iff the areas are identical

    Return type:

      `bool`

  intersection(other)

    Compute the intersection of 2 screen areas

    Parameters:

      other (`ScreenArea`) – The screen area to compare with

    Returns:

      An area representing the intersection, or `None` if there is no intersection

    Return type:

      `ScreenArea` or `None`

  intersects(other)

    Check whether this area intersects `other`

    Parameters:

      other (`ScreenArea`) – The screen area to compare with

    Returns:

      `True` iff the areas have an intersection

    Return type:

      `bool`

  least_intersection(candidates)

    Find the rectangle that intersects least with `rect` in `candidates`

    Parameters:

      candidates (iterable of `ScreenArea`s) – The monitor areas to check for intersection

    Returns:

      The best candidate screen area, i.e. that has the smallest intersection

    Return type:

      `ScreenArea`

  most_intersection(candidates)

    Find the rectangle that intersects most with `rect` in `candidates`

    Parameters:

      candidates (iterable of `ScreenArea`s) – The monitor areas to check for intersection

    Returns:

      The best candidate screen area, i.e. that has the largest intersection

    Return type:

      `ScreenArea`

pympress.util.close_opened_resources()

  Close all importlib context managers for resources that we needed over the program lifetime.

pympress.util.fileopen(f)

  Call the right function to open files, based on the platform.

  Parameters:

    f (path-like) – path to the file to open

pympress.util.get_default_config()

  Returns the path to the configuration file containing the defaults.

  Returns:

    The path to the portable configuration file.

  Return type:

    `Path`

pympress.util.get_icon_path(name)

  Get the path for an image from pympress’ resources

  Parameters:

    name (`str`) – The name of the icon to load

  Returns:

    The path to the icon to load

  Return type:

    `str`

pympress.util.get_log_path()

  Returns the appropriate path to the log file in the user app dirs.

  Returns:

    path to the log file.

  Return type:

    `Path`

pympress.util.get_portable_config()

  Returns the path to the configuration file for a portable install (i.e. in the install root).

  May return None if the install root is not a real directory (e.g. in a zip file).

  Returns:

    The path to the portable configuration file.

  Return type:

    `Path` or `None`

pympress.util.get_pympress_meta()

  Get metadata (version, etc) from pympress’ __init__.py or git describe.

  Returns:

    metadata properties (version, contributors) mapped to their values

  Return type:

    `dict`

pympress.util.get_translation(domain)

  Returns a gettext translation object.

  This re-implements gettext’s translation() and find() to allow using a python 3.9 Traversable as localedir

  Returns:

    A gettext translation object with the strings for the domain loaded

  Return type:

    `NullTranslations`

pympress.util.get_ui_resource_file(name, ext='.glade')

  Load an UI definition file from pympress’ resources

  Parameters:

    - name (`str`) – The name of the UI to load

    - ext (`str`) – The extension of the file

  Returns:

    The full path to the glade file

  Return type:

    `str`

pympress.util.get_user_config()

  Returns the path to the configuration file in the user config directory

  Returns:

    path to the user configuration file.

  Return type:

    `Path`

pympress.util.hard_set_screensaver(disabled)

  Enable or disable the screensaver.

  Parameters:

    disabled (`bool`) – if `True`, indicates that the screensaver must be disabled; otherwise it will be enabled

pympress.util.introspect_flag_value(flags_class, nick, fallback)

  Get the value of a flag from its class, given a value’s name (or nick)

  Introspection technique (in particular __flags_values__ dict) inspired from pygtkcompat. This is needed because there is no typelib for libgstplayback.

  Parameters:

    - flags_class (a `type` inheriting from `GFlags`) – the flags class to introspect

    - nick (`str`) – a name or nick of the flag value that should be returned

    - fallback (`int`) – the documented flag value, if lookup fails

pympress.util.list_icons()

  List the icons from pympress’ resources.

  Returns:

    The paths to the icons in the pixmaps directory

  Return type:

    `list` of `str`

pympress.util.load_style_provider(style_provider)

  Load the css and in a style provider

  Parameters:

    style_provider (`CssProvider`) – The style provider in which to load CSS

  Returns:

    The style provider with CSS loaded

  Return type:

    `CssProvider`