Pympress package — Pympress developer documentation

# 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.__main__.` `main`(argv=['-b', 'html', '-d', '_build/doctrees', '.', '..'])

`pympress.__main__.` `uncaught_handler`(*exc_info)

`pympress.__main__.` `usage`()

### `pympress.ui` – GUI management

This module contains the whole graphical user interface of pympress, which is made of two separate windows: the Content window, which displays only the current page in full size, and the Presenter window, which displays both the current and the next page, as well as a time counter and a clock.

Both windows are managed by the `UI` class.

class `pympress.ui.` `UI`

  Bases: `pympress.builder.Builder`

  Pympress GUI management.

  `accel_group` = None

    A `Gtk.AccelGroup` to store the shortcuts

  `adjust_frame_position`(*args)

    Select how to align the frame on screen.

  `annotations` = None

    Class `Annotations` managing the display of annotations

  `blanked` = False

    track whether we blank the screen

  `c_da` = None

    `DrawingArea` for the Content window.

  `c_frame` = None

    `AspectFrame` for the Content window.

  `c_win` = None

    Content window, as a `Window` instance.

  `cache` = None

    `SurfaceCache` instance.

  `change_notes_pos`(widget, event=None, force_change=False)

    Switch the display mode to “Notes mode” or “Normal mode” (without notes).

    Returns

      whether the mode has been toggled.

    Return type

      `bool`

  `chosen_notes_mode` = 4

    Current choice of mode to toggle notes

  `clear_zoom_cache`()

    Callback to clear the cache of zoomed widgets.

  `click_link`(widget, event)

    Check whether a link was clicked and follow it. Handles a click on a slide.

    Parameters

      - widget (`Widget`) – the widget in which the event occured

      - event (`Event`) – the event that occured

    Returns

      whether the event was consumed

    Return type

      `bool`

  `close_file`(*args)

    Remove the current document.

  `close_shortcuts`(*args)

    Destroy the shortcuts window once it is hidden.

  `config` = <pympress.config.Config object>

    `Config` to remember preferences

  `doc` = <pympress.document.EmptyDocument object>

    Current `Document` instance.

  `error_opening_file`(filename)

    Remove the current document.

  `est_time` = None

    `EstimatedTalkTime` to set estimated/remaining talk time

  `get_notes_mode`()

    Simple getter.

    Returns (`PdfPage`):

      Truthy when we split slides in content + notes

  `highlight_button` = None

    `ToolButton` big button for touch screens, go to scribble on screen

  `hover_link`(widget, event)

    Manage events related to hyperlinks, setting the cursor to a pointer if the hovered region is clickable.

    Parameters

      - widget (`Widget`) – the widget in which the event occured

      - event (`Event`) – the event that occured

    Returns

      whether the event was consumed

    Return type

      `bool`

  `laser` = None

    Software-implemented laser pointer, `Pointer`

  `load_icons`()

    Set the icon list for both windows

  `make_cwin`()

    Initializes the content window.

  `make_pwin`()

    Initializes the presenter window.

  `medias` = None

    Class `Media` managing keeping track of and callbacks on media overlays

  `menu_about`(*args)

    Display the “About pympress” dialog.

    Handles clicks on the “about” menu.

  `next_button` = None

    `ToolButton` big button for touch screens, go to next slide

  `notes_mode` = 0

    Whether to use notes mode or not

  `on_configure_da`(widget, event)

    Manage “configure” events for all drawing areas, e.g. resizes.

    We tell the local `SurfaceCache` cache about it, so that it can invalidate its internal cache for the specified widget and pre-render next pages at a correct size.

    Warning: Some not-explicitely sent signals contain wrong values! Just don’t resize in that case, since these always seem to happen after a correct signal that was sent explicitely.

    Parameters

      - widget (`Widget`) – the widget which has been resized

      - event (`Event`) – the GTK event, which contains the new dimensions of the widget

  `on_configure_win`(widget, event)

    Manage “configure” events for both window widgets.

    Parameters

      - widget (`Widget`) – the window which has been moved or resized

      - event (`Event`) – the GTK event, which contains the new dimensions of the widget

  `on_drag_drop`(widget, drag_context, x, y, data, info, time)

    Receive the drag-drops (as text only). If a file is dropped, open it.

    Parameters

      - widget (`Widget`) – The widget on which the dragged item was dropped

      - drag_context (`DragContext`) –

      - x (`float`) –

      - y (`float`) –

      - data (`SelectionData`) – container for the dropped data

      - info (`int`) –

      - time (`int`) –

  `on_draw`(widget, cairo_context)

    Manage draw events for both windows.

    This callback may be called either directly on a page change or as an event handler by GTK. In both cases, it determines which widget needs to be updated, and updates it, using the `SurfaceCache` if possible.

    Parameters

      - widget (`Widget`) – the widget to update

      - cairo_context (`Context`) – the Cairo context (or `None` if called directly)

  `on_navigation`(widget, event)

    Manage key presses for both windows

    Parameters

      - widget (`Widget`) – the widget in which the event occured (ignored)

      - event (`Event`) – the event that occured

    Returns

      whether the event was consumed

    Return type

      `bool`

  `on_page_change`(unpause=True)

    Switch to another page and display it.

    This is a kind of event which is supposed to be called only from the `Document` class.

    Parameters

      unpause (`bool`) – `True` if the page change should unpause the timer, `False` otherwise

  `on_pane_event`(widget, evt)

    Signal handler for gtk.paned events

    This function allows to delay drawing events when resizing, and to speed up redrawing when moving the middle pane is done (which happens at the end of a mouse resize)

    Parameters

      - widget (`Widget`) – the widget in which the event occured (ignored)

      - evt (`Event`) – the event that occured

  `on_scroll`(widget, event)

    Manage scroll events

    Parameters

      - widget (`Widget`) – the widget in which the event occured (ignored)

      - event (`Event`) – the event that occured

    Returns

      whether the event was consumed

    Return type

      `bool`

  `on_window_state_event`(widget, event)

    Track whether the preview window is maximized.

    Parameters

      - widget (`Widget`) – the widget in which the event occured

      - event (`Event`) – the event that occured

    Returns

      whether the event was consumed.

    Return type

      `bool`

  `p_central` = None

    `Box` for the Presenter window.

  `p_da_cur` = None

    `DrawingArea` for the current slide copy in the Presenter window.

  `p_da_next` = None

    `DrawingArea` for the next slide in the Presenter window.

  `p_da_notes` = None

    `DrawingArea` for the current slide in the Presenter window.

  `p_frame_annot` = None

    `Frame` for the annotations in the Presenter window.

  `p_frame_cur` = None

    `AspectFrame` for the current slide copy in the Presenter window.

  `p_frame_next` = None

    `AspectFrame` for the next slide in the Presenter window.

  `p_frame_notes` = None

    `AspectFrame` for the current slide in the Presenter window.

  `p_win` = None

    Presenter window, as a `Window` instance.

  `page_number` = None

    `PageNumber` displaying current and max page numbers and setting current page number

  `page_preview`(widget, *args)

    Switch to another page and display it.

    This is a kind of event which is supposed to be called only from the spin_cur spinner as a callback

    Parameters

      widget (`SpinButton`) – The spinner button widget calling page_preview

  `page_preview_nb` = -1

    number of page currently displayed in Controller window’s miniatures

  `pane_handle_pos` = {}

    Map of `Paned` to the relative position (`float` between 0 and 1) of its handle

  `pick_file`(*args)

    Ask the user which file he means to open.

  `placeable_widgets` = {}

    Dictionary of `Widget` from the presenter window that can be dynamically rearranged

  `pres_annot` = None

    `CheckMenuItem` that shows whether the annotations are toggled

  `pres_blank` = None

    `CheckMenuItem` that shows whether the blank mode is toggled

  `pres_fullscreen` = None

    `CheckMenuItem` that shows whether the c_win is fullscreen

  `pres_notes` = None

    `CheckMenuItem` that shows whether the annotations are toggled

  `prev_button` = None

    `ToolButton` big button for touch screens, go to previous slide

  `recent_document`(recent_menu)

    Callback for the recent document menu.

    Gets the URI and requests the document swap.

    Parameters

      recent_menu (`RecentChooserMenu`) – the recent docs menu

  `redraw_current_slide`()

    Callback to queue a redraw of the current slides (in both winows)

  `redraw_panes`()

    Handler for `Paned`’s resizing signal, used for delayed drawing events of drawing areas inside the panes. This is very useful on windows where resizing gets sluggish if we try to redraw while resizing.

  `redraw_timeout` = 0

    Tracks return values of GLib.timeout_add to cancel gtk.paned’s redraw callbacks

  `reload_document`()

    Reload the current document.

  `resize_panes` = False

    Indicates whether we should delay redraws on some drawing areas to fluidify resizing gtk.paned

  `run`()

    Run the GTK main loop.

  `save_and_quit`(*args)

    Save configuration and exit the main loop.

  `scribbler` = None

    Class `Scribble` managing drawing by the user on top of the current slide.

  `setup_screens`()

    Sets up the position of the windows

  `shortcuts_window` = None

    A `ShortcutsWindow` to show the shortcuts

  `show_annotations` = True

    Whether to display annotations or not

  `show_bigbuttons` = True

    Whether to display big buttons or not

  `show_shortcuts`(*args)

    Display the shortcuts window.

  `show_timing_report`(*args)

    Show the popup with information on timing of the talk.

    Gather current time, document structure, page labels etc. and pass it to timing popup for display.

  `swap_document`(docpath, page=0, reloading=False)

    Replace the currently open document with a new one

    The new document is possibly and EmptyDocument if docpath is None. The state of the ui and cache are updated accordingly.

    Parameters

      - docpath (`str`) – the absolute path to the new document

      - page (`int`) – the page at which to start the presentation

      - reloading (`bool`) – whether we are reloading or detecting stuff from the document

  `swap_layout`(old, new)

    Save the old layout in the prefs, load the new layout

    Parameters

      - old (`str`) – the name of the layout to save, `None` to use plain or notes automatically

      - new (`str`) – the name of the layout to load, `None` to use plain or notes automatically

  `swap_screens`(*args)

    Swap the monitors on which each window is displayed (if there are 2 monitors at least).

  `switch_annotations`(widget, event=None)

    Switch the display to show annotations or to hide them.

    Returns

      whether the mode has been toggled.

    Return type

      `bool`

  `switch_bigbuttons`(*args)

    Toggle the display of big buttons (nice for touch screens)

  `switch_blanked`(widget, event=None)

    Switch the blanked mode of the content screen.

    Returns

      whether the mode has been toggled.

    Return type

      `bool`

  `switch_fullscreen`(widget)

    Switch the Content window to fullscreen (if in normal mode) or to normal mode (if fullscreen).

    Screensaver will be disabled when entering fullscreen mode, and enabled when leaving fullscreen mode.

    Parameters

      widget (`Widget`) – the widget in which the event occured

    Returns

      whether some window’s full screen status got toggled

    Return type

      `bool`

  `switch_mode`(widget, event=None, target_mode=None)

    Switch the display mode to “Notes mode” or “Normal mode” (without notes).

    Returns

      whether the mode has been toggled.

    Return type

      `bool`

  `talk_time` = None

    `TimeCounter` clock tracking talk time (elapsed, and remaining)

  `timing` = None

    `TimingReport` popup to show how much time was spent on which part

  `track_clicks`(widget, event)

    Track mouse press and release events

    Handles clicks on the slides.

    Parameters

      - widget (`Widget`) – the widget that received the click

      - event (`Event`) – the GTK event containing the click position

    Returns

      whether the event was consumed

    Return type

      `bool`

  `track_motions`(widget, event)

    Track mouse motion events

    Handles mouse motions on the “about” menu.

    Parameters

      - widget (`Widget`) – the widget that received the mouse motion

      - event (`Event`) – the GTK event containing the mouse position

    Returns

      whether the event was consumed

    Return type

      `bool`

  `update_frame_position`(widget, user_data)

    Callback to preview the frame alignement, called from the Gtk.SpinButton.

    Parameters

      - widget (`SpinButton`) – The button updating the slide alignement in the drawing area widget

      - user_data (`str`) – The property being set, either the x or y alignement (resp. xalign and yalign).

  `zoom` = None

    Class `Zoom` managing the zoom level of the current slide.

### `pympress.document` – document handling

This module contains several classes that are used for managing documents (only PDF documents are supported at the moment, but other formats may be added in the future).

An important point is that this module is completely independant from the GUI: there should not be any GUI-related code here, except for page rendering (and only rendering itself: the preparation of the target surface must be done elsewhere).

class `pympress.document.` `Document`(builder, pop_doc, path, page=0)

  Bases: `object`

  This is the main document handling class.

  Note

  The internal page numbering scheme is the same as in Poppler: it starts at 0.

  Parameters

    - builder (`pympress.builder.Builder`) – A builder to load callbacks

    - pop_doc (`Document`) – Instance of the Poppler document that this class will wrap

    - path (`str`) – Absolute path to the PDF file to open

    - page (`int`) – page number to which the file should be opened

  `cleanup_media_files`()

    Removes all files that were extracted from the pdf into the filesystem

  static `create`(builder, path, page=0)

    Initializes a Document by passing it a `Document`

    Parameters

      - builder (`pympress.builder.Builder`) – A builder to load callbacks

      - path (`str`) – Absolute path to the PDF file to open

      - page (`int`) – page number to which the file should be opened

    Returns

      The initialized document

    Return type

      `Document`

  `cur_page` = -1

    Number of the current page

  `current_page`()

    Get the current page.

    Returns

      the current page

    Return type

      `Page`

  `doc` = None

    Current PDF document (`Document` instance)

  `get_full_path`(filename)

    Returns full path, extrapolated from a path relative to this document or to the current directory.

    Parameters

      filename (`str`) – Name of the file or relative path to it

    Returns

      the full path to the file or None if it doesn’t exist

    Return type

      `str`

  `get_structure`(index_iter=None)

    Gets the structure of the document from its index.

    Recursive, pass the iterator.

    Parameters

      index_iter (`IndexIter` or `None`) – the iterator for the child index to explore.

    Returns

      A list of tuples (depth, page number, title)

    Return type

      `list`

  `get_uri`()
    Returns

      the URI to the file currently opened.

    Return type

      `str`

  `goto`(number)

    Switch to another page.

    Parameters

      number (`int`) – number of the destination page

  `goto_end`(*args)

    Switch to the last page.

  `goto_home`(*args)

    Switch to the first page.

  `goto_next`(*args)

    Switch to the next page.

  `goto_prev`(*args)

    Switch to the previous page.

  `guess_notes`()

    Get our best guess for the document mode.

    Returns

      the notes mode

    Return type

      `PdfPage`

  `has_labels`()

    Return whether this document has useful labels.

    Returns

      False iff there are no labels or they are just the page numbers

    Return type

      `bool`

  `hist_next`(*args)

    Switch to the page we viewed next

  `hist_pos` = -1

    Our position in the history

  `hist_prev`(*args)

    Switch to the page we viewed before

  `history` = []

    History of pages we have visited

  `label_after`(page)

    Switch to the next page with different label. If we’re within a set of pages with the same label we want to go to the last one.

  `label_before`(page)

    Switch to the previous page with different label If we’re within a set of pages with the same label we want to go before the first one.

  `label_next`(*args)

    Switch to the next page with different label

  `label_prev`(*args)

    Switch to the previous page with different label

  `lookup_label`(label, prefix_unique=True)

    Find a page from its label

    Parameters

      - label (`str`) – the label we are searching for

      - prefix_unique (`bool`) – whether a prefix match should be unique, e.g. when the user is still typing

    Returns

      the page

    Return type

      `int`

  `nb_pages` = -1

    Number of pages in the document

  `next_page`()

    Get the next page.

    Returns

      the next page, or `None` if this is the last page

    Return type

      `Page`

  `notes` = 0

    `PdfPage` representing our best guess for the notes position in this document

  `page`(number)

    Get the specified page.

    Parameters

      number (`int`) – number of the page to return

    Returns

      the wanted page, or `None` if it does not exist

    Return type

      `Page`

  `page_change`()

    callback, to be connected to `on_page_change()`

  `page_labels` = []

    `dict` of all the page labels

  `pages_cache` = {}

    Pages cache (`dict` of `Page`). This makes navigation in the document faster by avoiding calls to Poppler when loading a page that has already been loaded.

  `pages_number`()

    Get the number of pages in the document.

    Returns

      the number of pages in the document

    Return type

      `int`

  `path` = None

    Path to pdf

  static `path_to_uri`(path)
  `play_media`()

    callback, to be connected to `play()`

  `remove_on_exit`(filename)

    Remember a temporary file to delete later

    Parameters

      filename (`str`) – The path to the file to delete

  `start_editing_page_number`()

    callback, to be connected to `start_editing()`

  `temp_files` = {}

    Files that are temporary and need to be removed

class `pympress.document.` `EmptyDocument`

  Bases: `pympress.document.Document`

  A dummy document, placeholder for when no document is open.

  `page`(number)

    Retreive a page from the document.

    Parameters

      number (`int`) – page number to be retreived

    Returns

      -1 returns the empty page so we can display something.

    Return type

      `EmptyPage` or `None`

class `pympress.document.` `EmptyPage`

  Bases: `pympress.document.Page`

  A dummy page, placeholder for when there are no valid pages around.

  This page is a non-notes page with an aspect ratio of 1.3 and nothing else inside. Also, it has no “rendering” capability, and is made harmless by overriding its render function.

  `can_render`()

    Informs that rendering is not necessary (avoids checking the type)

    Returns

      `False`, no rendering

    Return type

      `bool`

  `render_cairo`(cr, ww, wh, dtype=<PdfPage.FULL: 1>)

    Overriding this purely for safety: make sure we do not accidentally try to render

    Parameters

      - cr (`CairoContext`) – target surface

      - ww (`int`) – target width in pixels

      - wh (`int`) – target height in pixels

      - dtype (`PdfPage`) – the type of document that should be rendered

class `pympress.document.` `Link`(x1, y1, x2, y2, action)

  Bases: `object`

  This class encapsulates one hyperlink of the document.

  Parameters

    - x1 (`float`) – first x coordinate of the link rectangle

    - y1 (`float`) – first y coordinate of the link rectangle

    - x2 (`float`) – second x coordinate of the link rectangle

    - y2 (`float`) – second y coordinate of the link rectangle

    - action (`function`) – action to perform when the link is clicked

  static `build_closure`(fun, *args, **kwargs)

    Return a lambda that calls fun(*args, **kwargs), with the current value of args and kwargs. By creating the lambda in a new scope, we bind the arguments, thus creating a closure and remember the arguments.

    Parameters

      - fun (`function`) – The function to be called

      - args (`tuple`) – non-keyworded variable-length argument list to pass to fun()

      - kwargs (`dict`) – keyworded variable-length argument dict to pass to fun()

  `follow`(**kwargs)

    `function`, action to be perform to follow this link

  `is_over`(x, y)

    Tell if the input coordinates are on the link rectangle.

    Parameters

      - x (`float`) – input x coordinate

      - y (`float`) – input y coordinate

    Returns

      `True` if the input coordinates are within the link rectangle, `False` otherwise

    Return type

      `bool`

  `x1` = None

    `float`, first x coordinate of the link rectangle

  `x2` = None

    `float`, second x coordinate of the link rectangle

  `y1` = None

    `float`, first y coordinate of the link rectangle

  `y2` = None

    `float`, second y coordinate of the link rectangle

class `pympress.document.` `Page`(page, number, parent)

  Bases: `object`

  Class representing a single page.

  It provides several methods used by the GUI for preparing windows for displaying pages, managing hyperlinks, etc.

  Parameters

    - doc (`Page`) – the poppler object around the page

    - number (`int`) – number of the page to fetch in the document

    - parent (`Document`) – the parent Document class

  `annotations` = []

    All text annotations

  `can_render`()

    Informs that rendering is necessary (avoids checking the type)

    Returns

      `True`, do rendering

    Return type

      `bool`

  `get_annot_action`(link_type, action, rect)

    Get the function to be called when the link is followed.

    Parameters

      - link_type (`ActionType`) – The link type

      - action (`Action`) – The action to be performed when the link is clicked

      - rect (`Rectangle`) – The region of the page where the link is

    Returns

      The function to be called to follow the link

    Return type

      `function`

  `get_annotations`()

    Get the list of text annotations on this page.

    Returns

      annotations on this page

    Return type

      `list` of `str`

  `get_aspect_ratio`(dtype=<PdfPage.FULL: 1>)

    Get the page aspect ratio.

    Parameters

      dtype (`PdfPage`) – the type of document to consider

    Returns

      page aspect ratio

    Return type

      `float`

  `get_link_action`(link_type, action)

    Get the function to be called when the link is followed.

    Parameters

      - link_type (`ActionType`) – The type of action to be performed

      - action (`Action`) – The atcion to be performed

    Returns

      The function to be called to follow the link

    Return type

      `function`

  `get_link_at`(x, y, dtype=<PdfPage.FULL: 1>)

    Get the `Link` corresponding to the given position, or `None` if there is no link at this position.

    Parameters

      - x (`float`) – horizontal coordinate

      - y (`float`) – vertical coordinate

      - dtype (`PdfPage`) – the type of document to consider

    Returns

      the link at the given coordinates if one exists, `None` otherwise

    Return type

      `Link`

  `get_media`()

    Get the list of medias this page might want to play.

    Returns

      medias in this page

    Return type

      `list`

  `get_size`(dtype=<PdfPage.FULL: 1>)

    Get the page size.

    Parameters

      dtype (`PdfPage`) – the type of document to consider

    Returns

      page size

    Return type

      `(float, float)`

  `label`()

    Get the page label.

  `links` = []

    All the links in the page, as a `list` of `Link` instances

  `medias` = []

    All the media in the page, as a `list` of tuples of (area, filename)

  `number`()

    Get the page number.

  `page` = None

    Page handled by this class (instance of `Page`)

  `page_label` = None

    `str` representing the page label

  `page_nb` = -1

    `int`, number of the current page (starting from 0)

  `parent` = None

    Instance of `Document` that contains this page.

  `ph` = 0.0

    `float`, page height

  `pw` = 0.0

    `float`, page width

  `render_cairo`(cr, ww, wh, dtype=<PdfPage.FULL: 1>)

    Render the page on a Cairo surface.

    Parameters

      - cr (`CairoContext`) – target surface

      - ww (`int`) – target width in pixels

      - wh (`int`) – target height in pixels

      - dtype (`PdfPage`) – the type of document that should be rendered

class `pympress.document.` `PdfPage`

  Bases: `enum.IntEnum`

  Represents the part of a PDF page that we want to draw.

  `BOTTOM` = 2

    Bottom half of PDF page

  `FULL` = 1

    Full PDF page (without notes)

  `LEFT` = 5

    Left half of PDF page

  `NONE` = 0

    No notes on PDF page, only falsy value

  `RIGHT` = 4

    Right half of PDF page

  `TOP` = 3

    Top half of PDF page

  `complement`()

    Return the enum value for the other part of the page.

  `from_screen`(x, y, x2=None, y2=None)

    Transform visible part of the page coordinates to full page coordinates.

    Pass 2 floats to transform coordinates, 4 to transform margins, i.e. the second pair of coordinates is taken from the opposite corner.

    Parameters

      - x1 (`float`) – x coordinate on the screen, on a scale 0..1

      - y1 (`float`) – y coordinate on the screen, on a scale 0..1

      - x2 (`float`) – second x coordinate on the screen, from the other side, on a scale 0..1

      - y2 (`float`) – second y coordinate on the screen, from the other side, on a scale 0..1

  `scale`()

    Return the enum value that does only scaling not shifting

  `to_screen`(x, y, x2=None, y2=None)

    Transform full page coordinates to visible part coordinates.

    Pass 2 floats to transform coordinates, 4 to transform margins, i.e. the second pair of coordinates is taken from the opposite corner.

    Parameters

      - x1 (`float`) – x coordinate on the page, on a scale 0..1

      - y1 (`float`) – y coordinate on the page, on a scale 0..1

      - x2 (`float`) – second x coordinate on the page, from the other side, on a scale 0..1

      - y2 (`float`) – second y coordinate on the page, from the other side, on a scale 0..1

`pympress.document.` `get_extension`(mime_type)

  Returns a valid filename extension (recognized by python) for a given mime type.

  Parameters

    mimetype (`str`) – The mime type for which to find an extension

  Returns

    A file extension used for the given mimetype

  Return type

    `str`

### `pympress.ui_builder` – abstract GUI management

This module contains the tools to load the graphical user interface of pympress, building the widgets/objects from XML (glade) files, applying translation “manually” to avoid dealing with all the mess of C/GNU gettext’s bad portability.

class `pympress.builder.` `Builder`

  Bases: `gi.overrides.Gtk.Builder`

  GUI builder, inherits from `Builder` to read XML descriptions of GUIs and load them.

  `connect_signals`(base_target)

    Override default signal connector so we can map signals to the methods of (any depth of) object that are properties of self

    Parameters

      base_target (`Builder`) – The target object, that has functions to be connected to signals loaded in this builder.

  static `find_callback_handler`(target, handler_name)

    Returns the handler from its name, searching in target. Parse handler names and split on ‘.’ to use recursion.

    Parameters

      - target (`object`) – An object that has a method called `handler_name`

      - handler_name (`str`) – The name of the function to be connected to a signal

    Returns

      A function bound to an object or, if the object may change, a lambda calling Builder.signal_resolver to get said function bound to an object

    Return type

      `function`

  `get_callback_handler`(handler_name)

    Convenience non-static wrapper function for `find_callback_handler()` to search in the builder object. The `handler_name` function must be a method of this builder (realistically, a method of an inherited UI class’ instance).

    Parameters

      handler_name (`str`) – The name of the function to be connected to a signal

    Returns

      A function bound to an object or, if the object may change, a lambda calling Builder.signal_resolver to get said function bound to an object

    Return type

      `function`

  `list_attributes`(target)

    List the None-valued attributes of target.

    Parameters

      target (`dict`) – An object with None-valued attributes

  `load_ui`(resource_name)

    Loads the UI defined in the file named resource_name using the builder.

    Parameters

      resource_name (`str`) – the name of the glade file (basename without extension), identifying which resource to load.

  `load_widgets`(target)

    Fill in target with the missing elements introspectively. This means that all attributes of target that are None at this time must exist under the same name in the builder.

    Parameters

      target (`dict`) – An object with None-valued attributes that have the same name as built widgets, loaded from the glade file.

  `pending_pane_resizes` = {}

    `dict` mapping `Paned` names to the handler ids of their size-allocate signal

  `replace_layout`(layout, top_widget, leaf_widgets, pane_resize_handler=None)

    Remix the layout below top_widget with the layout configuration given in ‘layout’ (assumed to be valid!).

    Parameters

      - layout (`dict`) – the json-parsed config string, thus a hierarchy of lists/dicts, with strings as leaves

      - top_widget (`Container`) – The top-level widget under which we build the hierachyy

      - leaf_widgets (`dict`) – the map of valid leaf identifiers (strings) to the corresponding `Widget`

      - pane_resize_handler (function) – callback function to be called when the panes are resized

    Returns

      The mapping of the used `Paned` widgets to their relative handle position (float between 0 and 1)

    Return type

      `dict`

  `resize_paned`(paned, rect, relpos)

    Resize `paned` to have its handle at `relpos`, then disconnect this signal handler. Called from the `Gtk.Widget.signals.size_allocate()` signal.

    Parameters

      - paned (`Paned`) – Panel whose size has just been allocated, and whose handle needs initial placement.

      - rect (`Rectangle`) – The rectangle specifying the size that has just been allocated to `paned`

      - relpos (`float`) – A number between `0.` and `1.` that specifies the handle position

    Returns

      `True`

  `signal_connector`(builder, object, signal_name, handler_name, connect_object, flags, *user_data)

    Callback for signal connection. Implements the `BuilderConnectFunc` function interface.

    Parameters

      - builder (`Builder`) – The builder, unused

      - object (`Object`) – The object (usually a wiget) that has a signal to be connected

      - signal_name (`str`) – The name of the signal

      - handler_name (`str`) – The name of the function to be connected to the signal

      - connect_object (`Object`) – unused

      - flags (`ConnectFlags`) – unused

      - user_data (`tuple`) – supplementary positional arguments to be passed to the handler

  static `signal_resolver`(target, attr_list)

    Dynamically resolves a signal that is target.a.b.c() when attr_list is [‘a’, ‘b’, ‘c’].

    This allows to specify multi-level signals in the XML files, instead of targeting everything at the main UI object.

    Also, resolving signals dynamically means the object properties of the top-level object can be replaced, and the signal will still connect to something meaningful. The downside is that this connection is done at runtime, thus probably less efficient and might fail to find the target if any attribute along the way has an unexpected value.

    Parameters

      attr_list (`list`) – a list of attribute names, designating objects except the last one designating a function

    Returns

      The function to which we want to connect

    Return type

      function

### `pympress.surfacecache` – pages prerendering and caching

This modules contains stuff needed for caching pages and prerendering them. This is done by the `SurfaceCache` class, using several `dict` of `ImageSurface` for storing rendered pages.

The problem is, neither Gtk+ nor Poppler are particularly threadsafe. Hence the prerendering isn’t really done in parallel in another thread, but scheduled on the main thread at idle times using GLib.idle_add().

class `pympress.surfacecache.` `OrderedDict`

  Bases: `collections.OrderedDict`

  OrderedDict for python2 compatibility, adding move_to_end().

  `move_to_end`(key)

    Move an existing element to the end (or beginning if last is false).

    Raise KeyError if the element does not exist.

class `pympress.surfacecache.` `SurfaceCache`(doc, max_pages)

  Bases: `object`

  Pages caching and prerendering made (almost) easy.

  Parameters

    - doc (`Document`) – the current document

    - max_pages (`int`) – The maximum page number.

  `active_widgets` = {}

    Set of active widgets

  `add_widget`(widget, wtype, prerender_enabled=True, zoomed=False)

    Add a widget to the list of widgets that have to be managed (for caching and prerendering).

    This creates new entries for `widget_name` in the needed internal data structures, and creates a new thread for prerendering pages for this widget.

    Parameters

      - widget (`Widget`) – The widget for which we need to cache

      - wtype (`int`) – type of document handled by the widget (see `surface_type`)

      - prerender_enabled (`bool`) – whether this widget is initially in the list of widgets to prerender

  `clear_cache`(widget_name)

    Remove all cached values for a given widget. Useful for zoomed views.

    Parameters

      widget_name (`str`) – name of the widget that is resized

  `disable_prerender`(widget_name)

    Remove a widget from the ones to be prerendered.

    Parameters

      widget_name (`str`) – string used to identify a widget

  `doc` = None

    The current `Document`.

  `doc_lock` = None

    `Lock` used to manage conccurent accesses to `doc`.

  `enable_prerender`(widget_name)

    Add a widget to the ones to be prerendered.

    Parameters

      widget_name (`str`) – string used to identify a widget

  `get`(widget_name, page_nb)

    Fetch a cached, prerendered page for the specified widget.

    Parameters

      - widget_name (`str`) – name of the concerned widget

      - page_nb (`int`) – number of the page to fetch in the cache

    Returns

      the cached page if available, or `None` otherwise

    Return type

      `ImageSurface`

  `get_widget_type`(widget_name)

    Get the document type of a widget.

    Parameters

      widget_name (`str`) – string used to identify a widget

    Returns

      type of document handled by the widget (see `surface_type`)

    Return type

      `int`

  `locks` = {}

    Dictionary of `Lock` used for managing conccurent accesses to `surface_cache` and `surface_size`

  `max_pages` = 200

    maximum number fo pages we keep in cache

  `prerender`(page_nb)

    Queue a page for prerendering.

    The specified page will be prerendered for all the registered widgets.

    Parameters

      page_nb (`int`) – number of the page to be prerendered

  `renderer`(widget_name, page_nb)

    Rendering thread.

    This function is meant to be run in the prerendering thread. It runs infinitely (until the program ends) and does the following steps:

    - check if the job’s result is not already available in the cache

    - render it in a new `ImageSurface` if necessary

    - store it in the cache if it was not added there since the beginning of the process and the widget configuration is still valid

    Parameters

      - widget_name (`str`) – name of the concerned widget

      - page_nb (`int`) – number of the page to store in the cache

  `resize_widget`(widget_name, width, height)

    Change the size of a registered widget, thus invalidating all the cached pages.

    Parameters

      - widget_name (`str`) – name of the widget that is resized

      - width (`int`) – new width of the widget

      - height (`int`) – new height of the widget

  `set`(widget_name, page_nb, val)

    Store a rendered page in the cache.

    Parameters

      - widget_name (`str`) – name of the concerned widget

      - page_nb (`int`) – number of the page to store in the cache

      - val (`ImageSurface`) – content to store in the cache

  `set_widget_type`(widget_name, wtype)

    Set the document type of a widget.

    Parameters

      - widget_name (`str`) – string used to identify a widget

      - wtype (`int`) – type of document handled by the widget (see `surface_type`)

  `surface_cache` = {}

    The actual cache. It is a `dict` of `Cache`: its keys are widget names and its values are `dict` whose keys are page numbers and values are instances of `ImageSurface`. In each `Cache` keys are ordered by Least Recently Used (get or set), when the size is beyond `max_pages`, pages are popped from the start of the cache.

  `surface_factory` = {}

    `dict` containing functions that return a `Surface` given a `Context`, width `int` and height `int` see `create_similar()`

  `surface_size` = {}

    Size of the different managed widgets, as a `dict` of tuples

  `surface_type` = {}

    its keys are widget names and its values are document types from ui.

    Type

      Type of document handled by each widget. It is a `dict`

  `swap_document`(new_doc)

    Replaces the current document for which to cache slides with a new one.

    This function also clears the cached pages, since they now belong to an outdated document.

    Parameters

      new_doc (`Document`) – the new document

### `pympress.scribble` – Manage user drawings on the current slide

class `pympress.scribble.` `Scribbler`(config, builder, notes_mode)

  Bases: `pympress.builder.Builder`

  `clear_scribble`(*args)

    Callback for the scribble clear button, to remove all scribbles

  `disable_scribbling`()

    Disable the scribbling mode.

    Returns

      whether it was possible to disable (thus if it was not disabled already)

    Return type

      `bool`

  `draw_scribble`(widget, cairo_context)

    Perform the drawings by user.

    Parameters

      - widget (`DrawingArea`) – The widget where to draw the scribbles.

      - cairo_context (`Context`) – The canvas on which to render the drawings

  `enable_scribbling`()

    Enable the scribbling mode.

    Returns

      whether it was possible to enable (thus if it was not enabled already)

    Return type

      `bool`

  `get_slide_point`()

    callback, to be connected to `get_slide_point()`

  `nav_scribble`(name, ctrl_pressed, command=None)

    Handles an key press event: undo or disable scribbling.

    Parameters

      - name (`str`) – The name of the key pressed

      - ctrl_pressed (`bool`) – whether the ctrl modifier key was pressed

      - command (`str`) – the name of the command in case this function is called by on_navigation

    Returns

      whether the event was consumed

    Return type

      `bool`

  `off_render` = None

    A `OffscreenWindow` where we render the scribbling interface when it’s not shown

  `on_configure_da`(widget, event)

    Transfer configure resize to the cache.

    Parameters

      - widget (`Widget`) – the widget which has been resized

      - event (`Event`) – the GTK event, which contains the new dimensions of the widget

  `on_draw`()

    callback, to be connected to `on_draw()`

  `p_central` = None

    `Box` in the Presenter window, where we insert scribbling.

  `pop_scribble`(*args)

    Callback for the scribble undo button, to undo the last scribble

  `pres_highlight` = None

    `CheckMenuItem` that shows whether the scribbling is toggled

  `redraw_current_slide`()

    callback, to be connected to `redraw_current_slide()`

  `resize_cache`()

    callback, to be connected to `resize_widget()`

  `scribble_c_eb` = None

    `EventBox` for the scribbling in the Content window, captures freehand drawing

  `scribble_color` = Gdk.RGBA(red=1.000000, green=1.000000, blue=1.000000, alpha=1.000000)

    `RGBA` current color of the scribbling tool

  `scribble_drawing` = False

    Whether the current mouse movements are drawing strokes or should be ignored

  `scribble_list` = []

    `list` of scribbles to be drawn, as tuples of color `RGBA`, width `int`, and a `list` of points.

  `scribble_overlay` = None

    `HBox` that is replaces normal panes when scribbling is toggled, contains buttons and scribble drawing area

  `scribble_p_da` = None

    `DrawingArea` for the scribbles in the Presenter window. Actually redraws the slide.

  `scribble_p_eb` = None

    `EventBox` for the scribbling in the Presenter window, captures freehand drawing

  `scribble_p_frame` = None

    `AspectFrame` for the slide in the Presenter’s highlight mode

  `scribble_width` = 1

    `int` current stroke width of the scribbling tool

  `scribbling_mode` = False

    Whether we are displaying the interface to scribble on screen and the overlays containing said scribbles

  `start_zooming`()

    callback, to be connected to `start_zooming()`

  `stop_zooming`()

    callback, to be connected to `stop_zooming()`

  `swap_layout`()

    callback, to be connected to `swap_layout()`

  `switch_scribbling`(widget, event=None)

    Starts the mode where one can read on top of the screen

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event` or None) – the GTK event., None when called through a menu item

    Returns

      whether the event was consumed

    Return type

      `bool`

  `toggle_scribble`(widget, event)

    Start/stop drawing scribbles.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `track_clicks`()

    callback, to be connected to `track_clicks()`

  `track_motions`()

    callback, to be connected to `track_motions()`

  `track_scribble`(widget, event)

    Draw the scribble following the mouse’s moves.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `update_color`(widget)

    Callback for the color chooser button, to set scribbling color

    Parameters

      widget (`ColorButton`) – the clicked button to trigger this event, if any

  `update_width`(widget, event, value)

    Callback for the width chooser slider, to set scribbling width

    Parameters

      - widget (`Scale`) – The slider control used to select the scribble width

      - event (`Event`) – the GTK event triggering this update.

      - value (`int`) – the width of the scribbles to be drawn

  `zoom_stop_button` = None

    `Button` that is clicked to stop zooming, unsensitive when there is no zooming

### `pympress.pointer` – Manage when and where to draw a software-emulated laser pointer on screen

`pympress.pointer.` `POINTER_HIDE` = 0

  Pointer enabled but hidden, will be drawn on ctrl + click

`pympress.pointer.` `POINTER_OFF` = -1

  Pointer disabled, will not be drawn

`pympress.pointer.` `POINTER_SHOW` = 1

  Draw the pointer on the current slide

class `pympress.pointer.` `Pointer`(config, builder)

  Bases: `object`

  `change_pointer`(widget)

    Callback for a radio item selection as pointer color

    Parameters

      widget (`RadioMenuItem`) – the selected radio item in the pointer type selection menu

  `config` = None

    A reference to the UI’s `Config`, to update the pointer preference

  `load_pointer`(name)

    Perform the change of pointer using its name

    Parameters

      name (`str`) – Name of the pointer to load

  `pointer` = <GdkPixbuf.Pixbuf object at 0x7f90906a7240 (GdkPixbuf at 0x55dcb1168700)>

    `Pixbuf` to read XML descriptions of GUIs and load them.

  `pointer_pos` = (0.5, 0.5)

    `(float, float)` of position relative to slide, where the pointer should appear

  `redraw_current_slide`()

    callback, to be connected to `redraw_current_slide()`

  `render_pointer`(cairo_context, ww, wh)

    Draw the laser pointer on screen

    Parameters

      - cairo_context (`Context`) – The canvas on which to render the pointer

      - ww (`int`) – The widget width

      - wh (`int`) – The widget height

  `show_pointer` = -1

    `bool` indicating whether we should show the pointer

  `toggle_pointer`(widget, event)

    Track events defining when the laser is pointing.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `track_pointer`(widget, event)

    Move the laser pointer at the mouse location.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

### `pympress.editable_label` – A label that can be swapped out for an editable entry

class `pympress.editable_label.` `EditableLabel`

  Bases: `object`

  `cancel`()
  `editing` = False

    `bool` tracking whether we are currently editing the label.

  `event_box` = None

    `EventBox` around the label, used to sense clicks

  `more_actions`(event, name)
  `on_keypress`(widget, event, name=None, command=None)

    Manage key presses for the editable label.

    If we are editing the label, intercept some key presses (to validate or cancel editing or other specific behaviour), otherwise pass the key presses on to the button for normal behaviour.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

      - name (`str`) – the name of the key stroke

      - command (`str`) – the name of the command in case this function is called by on_navigation

    Returns

      whether the event was consumed

    Return type

      `bool`

  `on_label_event`(widget, event=None, name=None)

    Manage events on the current slide label/entry.

    This function triggers replacing the label with an entry when clicked or otherwise toggled.

    Parameters

      - widget (`Widget`) – the widget in which the event occured

      - event (`Event` or None) – the event that occured, None if tf we called from a menu item

      - name (`str`) – name of the key in the casae of a key press

    Returns

      whether the event was consumed

    Return type

      `bool`

  `restore_label`()

    Make sure that the editable label is not in entry mode. If it is an entry, then replace it with the label.

  `start_editing`()

    Start the editing of the label if it is disabled.

  `stop_editing`()

    Disable the editing of the label if it was enabled.

  `swap_label_for_entry`()

    Perform the actual work of starting the editing.

  `validate`()

class `pympress.editable_label.` `EstimatedTalkTime`(builder, ett=0)

  Bases: `pympress.editable_label.EditableLabel`

  `delayed_callback_connection`(builder)

    Connect callbacks later than at init, due to circular dependencies. Call this when the page_number module is initialized, but before needing the callback.

    Parameters

      builder (builder.Builder) – The builder from which to load widgets.

  `eb_ett` = None

    `EventBox` associated with the estimated talk time.

  `entry_ett` = <Gtk.Entry object at 0x7f90906bbf78 (GtkEntry at 0x55dcb10343a0)>

    `Entry` used to set the estimated talk time.

  `est_time` = 0

    Estimated talk time, `int` in seconds.

  `label_ett` = None

    Estimated talk time `Label` for the talk.

  `label_time` = None

    Elapsed time `Label`.

  `more_actions`(event, name)

    Pass on keystrokes to `do_key_press_event()`

  `restore_label`()

    Make sure that the current page number is displayed in a label and not in an entry. If it is an entry, then replace it with the label.

  `set_time`(time)

    Set the talk time.

    Parameters

      time (`int`) – the estimated time for the talk, in seconds.

  `stop_editing_page_number`()

    callback, to be connected to `stop_editing()`

  `swap_label_for_entry`(*args)

    Perform the actual work of starting the editing.

  `validate`()

    Update estimated talk time from the input/

class `pympress.editable_label.` `PageNumber`(builder, page_num_scroll)

  Bases: `pympress.editable_label.EditableLabel`

  `cancel`()

    Make the UI re-display the pages from before editing the current page.

  `changed_page_label`(*args)

    Get the page number from the spinner and go to that page

  `eb_cur` = None

    `EventBox` associated with the slide counter label in the Presenter window.

  `edit_label` = None

    `Entry` used to switch to another slide by typing its label.

  `enable_labels`(enable)

    Allow to use or ignore labels.

    Parameters

      enable (`bool`) – Whether to enable labels

  `find_label`()

    callback, to be connected to `lookup_label()`

  `goto_page`()

    callback, to be connected to `goto()`

  `hb_cur` = None

    `HBox` containing the slide counter label in the Presenter window.

  `invert_scroll` = True

    `bool` whether to scroll with the pages (True) or with the page numbers (False)

  `label_after`()

    callback, to be connected to `label_before()`

  `label_before`()

    callback, to be connected to `label_after()`

  `label_cur` = None

    Slide counter `Label` for the current slide.

  `label_last` = None

    Slide counter `Label` for the last slide.

  `label_sep` = None

    `Label` separating `spin_cur` and `edit_label`

  `max_page_number` = 1

    `int` holding the maximum page number in the document

  `more_actions`(event, name)

    Implement directions (left/right/home/end) keystrokes, otherwise pass on to `do_key_press_event()`

  `on_scroll`(widget, event)

    Scroll event. Pass it on to the spin button if we’re currently editing the page number.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `page_change`()

    callback, to be connected to `on_page_change()`

  `page_labels` = True

    `bool` holding whether we display or ignore page labels

  `restore_label`()

    Make sure that the current page number is displayed in a label and not in an entry. If it is an entry, then replace it with the label.

  `set_last`(num_pages)

    Set the max number of pages, both on display and as the range of values for the spinner.

    Parameters

      num_pages (`int`) – The maximum page number

  `spin_cur` = None

    `SpinButton` used to switch to another slide by typing its number.

  `stop_editing_est_time`()

    callback, to be connected to `stop_editing()`

  `swap_label_for_entry`(hint=None)

    Perform the actual work of starting the editing.

  `update_jump_label`(label)

    Update the displayed page label.

    Parameters

      label (`str`) – The current page label

  `update_page_numbers`(cur_nb, label)

    Update the displayed page numbers.

    Parameters

      cur_nb (`int`) – The current page number, in documentation numbering (range [0..max - 1])

  `validate`()

    Get the page number from the spinner and go to that page

### `pympress.talk_time` – Manages the clock of elapsed talk time

class `pympress.talk_time.` `TimeCounter`(builder, ett)

  Bases: `object`

  `delta` = 0

    Time elapsed since the beginning of the presentation, `int` in seconds.

  `ett` = None

    `EstimatedTalkTime` that handles changing the ett

  `label_clock` = None

    Clock `Label`.

  `label_colorer` = None

    `TimeLabelColorer` that handles setting the colors of `label_time`

  `label_time` = None

    Elapsed time `Label`.

  `pause`()

    Pause the timer if it is not paused, otherwise do nothing.

    Returns

      whether the clock’s pause was toggled.

    Return type

      `bool`

  `paused` = True

    Timer paused status, `bool`.

  `pres_pause` = None

    `CheckMenuItem` that shows whether the time is toggled

  `reset_timer`(*args)

    Reset the timer.

  `start_time` = 0

    Time at which the counter was started, `int` in seconds as returned by `time()`.

  `switch_pause`(widget, event=None)

    Switch the timer between paused mode and running (normal) mode.

    Returns

      whether the clock’s pause was toggled.

    Return type

      `bool`

  `unpause`()

    Unpause the timer if it is paused, otherwise do nothing.

    Returns

      whether the clock’s pause was toggled.

    Return type

      `bool`

  `update_time`()

    Update the timer and clock labels.

    Returns

      `True` (to prevent the timer from stopping)

    Return type

      `bool`

class `pympress.talk_time.` `TimeLabelColorer`(label_time)

  Bases: `object`

  Manage the colors of a label with a set of colors between which to fade, based on how much time remains (<0 has run out of time). Times are given in seconds. In between timestamps the color will interpolated linearly, outside of the intervals the closest color will be used.

  Parameters

    label_time (`Gtk.Label`) – the label where the talk time is displayed

  `color_map` = []

    `list` of tuples (`int`, `RGBA`), which are the desired colors at the corresponding timestamps. Sorted on the timestamps.

  `color_override` = None

    `CssProvider` affecting the style context of the labels

  `default_color`()

    Forces to reset the default colors on the label.

  `label_color_default` = None

    `RGBA` The default color of the info labels

  `label_time` = None

    The `Gtk.Label` whose colors need updating

  `load_color_from_css`(style_context, class_name=None)

    Add class class_name to the time label and return its color.

    Parameters

      - label_time (`Gtk.Label`) – the label where the talk time is displayed

      - style_context (`StyleContext`) – the CSS context managing the color of the label

      - class_name (`str` or `None`) – The name of the class, if any

    Returns

      The color of the label with class “class_name”

    Return type

      `RGBA`

  `update_time_color`(remaining)

    Update the color of the time label based on how much time is remaining.

    Parameters

      remaining (`int`) – Remaining time until estimated talk time is reached, in seconds.

### `pympress.config` – Configuration

class `pympress.config.` `Config`

  Bases: `configparser.ConfigParser`, `object`

  Manage configuration :Get the configuration from its file and store its back.

  `get_layout`(layout_name)

    Getter for the `layout_name` layout.

  `getlist`(*args)

    Parse a config value and return the list by splitting the value on commas.

    i.e. bar = foo,qux returns the list [‘foo’, ‘qux’]

    Returns

      a config value split into a list.

    Return type

      `list`

  `layout` = {'highlight': {'children': ['highlight', {'resizeable': True, 'children': ['next', 'annotations'], 'proportions': [0.55, 0.44999999999999996], 'orientation': 'vertical'}], 'orientation': 'horizontal', 'proportions': [0.6697916666666667, 0.3302083333333333], 'resizeable': True}, 'notes': {'children': ['notes', {'resizeable': False, 'children': ['current', 'next'], 'orientation': 'vertical'}], 'orientation': 'horizontal', 'proportions': [0.6, 0.4], 'resizeable': True}, 'plain': {'children': ['current', {'resizeable': True, 'children': ['next', 'annotations'], 'proportions': [0.55, 0.44999999999999996], 'orientation': 'vertical'}], 'orientation': 'horizontal', 'proportions': [0.6697916666666667, 0.3302083333333333], 'resizeable': True}}

    `dict`-tree of presenter layouts for various modes

  `load_window_layouts`()

    Parse and validate layouts loaded from config, with fallbacks if needed.

  static `path_to_config`(search_legacy_locations=False)

    Return the path to the currently used configuration file.

    Parameters

      search_legacy_locations (`bool`) – whether to look in previously used locations

  `placeable_widgets` = {'annotations': 'p_frame_annot', 'current': 'p_frame_cur', 'highlight': 'scribble_overlay', 'next': 'p_frame_next', 'notes': 'p_frame_notes'}

    `dict` of strings that are the valid representations of widgets from the presenter window that can be dynamically rearranged, mapping to their names

  `save_config`()

    Save the configuration to its file.

  `shortcuts` = {(accelerator_key=32, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'next', (accelerator_key=32, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'next_label', (accelerator_key=97, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'annotations', (accelerator_key=98, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'blank_screen', (accelerator_key=102, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'fullscreen_content', (accelerator_key=102, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'fullscreen_presenter', (accelerator_key=103, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'goto_page', (accelerator_key=104, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'highlight', (accelerator_key=106, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'jumpto_label', (accelerator_key=108, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'fullscreen_content', (accelerator_key=110, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'notes_mode', (accelerator_key=111, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'open_file', (accelerator_key=112, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'pause_timer', (accelerator_key=113, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'quit', (accelerator_key=114, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'reset_timer', (accelerator_key=115, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'swap_screens', (accelerator_key=116, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'talk_time', (accelerator_key=117, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'unzoom', (accelerator_key=119, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'close_file', (accelerator_key=122, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'zoom', (accelerator_key=122, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'undo_scribble', (accelerator_key=65288, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'hist_back', (accelerator_key=65288, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'hist_forward', (accelerator_key=65293, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'validate', (accelerator_key=65293, accelerator_mods=<flags GDK_META_MASK of type Gdk.ModifierType>): 'fullscreen_content', (accelerator_key=65299, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'pause_timer', (accelerator_key=65307, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'cancel', (accelerator_key=65360, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'first', (accelerator_key=65361, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'prev', (accelerator_key=65361, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'prev_label', (accelerator_key=65362, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'prev', (accelerator_key=65362, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'prev_label', (accelerator_key=65363, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'next', (accelerator_key=65363, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'next_label', (accelerator_key=65364, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'next', (accelerator_key=65364, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'next_label', (accelerator_key=65365, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'prev', (accelerator_key=65365, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'prev_label', (accelerator_key=65366, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'next', (accelerator_key=65366, accelerator_mods=<flags GDK_CONTROL_MASK of type Gdk.ModifierType>): 'next_label', (accelerator_key=65367, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'last', (accelerator_key=65421, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'validate', (accelerator_key=65474, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'fullscreen_content', (accelerator_key=65480, accelerator_mods=<flags 0 of type Gdk.ModifierType>): 'fullscreen_content'}

    Map of (keyval, Gdk.ModifierType) to string, which representing the shortcuts for each command

  static `toggle_portable_config`(*args)

    Create or remove a configuration file for portable installs.

    The portable install file will be used by default, and deleting it causes the config to fall back to the user profile location.

    No need to populate the new config file, this will be done on pympress exit.

  `toggle_start`(check_item)

    Generic function to toggle some boolean startup configuration.

    Parameters

      check_item (`:CheckMenuItem`) – the check button triggering the call

  `update_layout`(layout_name, widget, pane_handle_pos)

    Setter for the notes layout.

    Parameters

      - layout_name (`str`) – the name of the layout to update

      - widget (`Widget`) – the widget that will contain the layout.

      - pane_handle_pos (`dict`) – Map of `Paned` to the relative position (float between 0 and 1) of its handle

  static `using_portable_config`()

    Checks which configuration file location is in use

    Returns

      `True` iff we are using the portable (i.e. in install dir) location

    Return type

      `bool`

  `validate_layout`(layout, expected_widgets, optional_widgets={})

    Validate layout: check whether the layout of widgets built from the config string is valid.

    Parameters

      - layout (`dict`) – the json-parsed config string

      - expected_widgets (`set`) – strings with the names of widgets that have to be used in this layout

      - optional_widgets (`set`) – strings with the names of widgets that may or may not be used in this layout

    Layout must have all self.placeable_widgets (leaves of the tree, as `str`) and only allowed properties on the nodes of the tree (as `dict`).

    Contraints on the only allowed properties of the nodes are: - resizeable: `bool` (optional, defaults to no), - orientation: `str`, either “vertical” or “horizontal” (mandatory) - children: `list` of size >= 2, containing `str`s or `dict`s (mandatory) - proportions: `list` of `float` with sum = 1, length == len(children), representing the relative sizes of all the resizeable items (if and only if resizeable).

  `widget_layout_to_tree`(widget, pane_handle_pos)

    Build a tree representing a widget hierarchy, leaves are strings and nodes are `dict`. Recursive function. See validate_layout() for more info on the tree structure.

    Parameters

      - widget (`Widget`) – the widget where to start

      - pane_handle_pos (`dict`) – Map of `Paned` to the relative position (float between 0 and 1) of its handle

    Returns

      A tree of dicts reprensenting the widget hierarchy

    Return type

      `dict`

`pympress.config.` `layout_from_json`(layout_string)

  Load the layout from config, with all strings cast to type `str` (even on python2 where they default to `unicode`) Raises ValueError until python 3.4, json.decoder.JSONDecodeError afterwards, on invalid input.

  Parameters

    layout_string (`str`) – A JSON string to be loaded.

`pympress.config.` `recursive_unicode_to_str`(obj)

### `pympress.extras` – Manages the display of fancy extras such as annotations, videos and cursors

class `pympress.extras.` `Annotations`(builder)

  Bases: `object`

  `add_annotations`(annotations)

    Insert text annotations into the tree view that displays them.

    Parameters

      annotations (`list`) – A list of strings, that are the annotations to be displayed

  `annotation_renderer` = None

    `CellRendererText` Text renderer for the annotations

  `on_configure_annot`(widget, event)

    Adjust wrap width in annotations when they are resized.

    Parameters

      - widget (`Widget`) – the widget which was resized.

      - event (`Event`) – the GTK event.

  `on_scroll`(widget, event)

    Try scrolling the annotations window.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `scrollable_treelist` = None

    The containing widget for the annotations

  `scrolled_window` = None

    Making the annotations list scroll if it’s too long

class `pympress.extras.` `Cursor`

  Bases: `object`

  classmethod `set_cursor`(widget, cursor_name='parent')

    Set the cursor named cursor_name’

    Parameters

      - widget (`Widget`) – The widget triggering the cursor change, used to retrieve a Gdk.Window

      - cursor_name (`str`) – Name of the cursor to be set

class `pympress.extras.` `FileWatcher`

  Bases: `object`

  A class with only static methods that wraps object watchdogs, to trigger callbacks when a file changes.

  classmethod `call`(callback, *args, **kwargs)

    Call the callback

    Parameters

      callback (`function`) – callback to call with all the further arguments

  classmethod `enqueue`(callback, *args, **kwargs)

    Do not call callback directly, instead delay as to avoid repeated calls in short periods of time.

    Parameters

      callback (`function`) – callback to call with all the further arguments

  `monitor` = <watchdog.events.FileSystemEventHandler object>

    A `FileSystemEventHandler` to get notified when the file changes

  `observer` = <InotifyObserver(Thread-1, initial daemon)>

    A `Observer` to watch when the file changes

  classmethod `start_daemon`()

    Start the watchdog observer thread

  classmethod `stop_daemon`(wait=False)

    Stop the watchdog observer thread.

    Parameters

      wait (`bool`) – whether to wait for the thread to have joined before returning

  classmethod `stop_watching`()

    Remove all files that are being watched

  `timeout` = 0
  classmethod `watch_file`(path, callback, *args, **kwargs)

    Watches a new file with a new callback. Removes any precedent watched files.

    Parameters

      - path (`str`) – full path to the file to watch

      - callback (`function`) – callback to call with all the further arguments when the file changes

class `pympress.extras.` `Media`(builder, conf)

  Bases: `object`

  `adjust_margins_for_mode`(page_type)

    Adjust the relative margins of child widgets for notes mode update.

    Parameters

      page_type (`PdfPage`) – The part of the page to display

  classmethod `backend_version`()

    Returns which backend is used.

    Returns

      The name and version of the backend(s).

    Return type

      `str`

  `c_overlay` = None

    `Overlay` for the Content window.

  classmethod `get_factory`(mime_type)

    Returns a class of type `_backend`

  `hide`(media_id, button=None)

    Stops playing a media and hides the player. Used as a callback.

    Parameters

      media_id (`int`) – A unique idientifier of the media to start playing

  `hide_all`()

    Stops all playing medias and hides the players. Used before exit.

  `p_overlay` = None

    `Overlay` for the Presenter window.

  `play`(media_id, button=None)

    Starts playing a media. Used as a callback.

    Parameters

      media_id (`int`) – A unique idientifier of the media to start playing

  `play_pause`(media_id, *args)

    Toggles playing and pausing a media. Used as a callback.

    Parameters

      media_id (`int`) – A unique idientifier of the media to start playing

  `purge_media_overlays`()

    Remove current media overlays.

  `remove_media_overlays`()

    Remove current media overlays.

  `replace_media_overlays`(current_page, page_type)

    Remove current media overlays, add new ones if page contains media.

    Parameters

      - current_page (`Page`) – The page for which to prepare medias

      - page_type (`PdfPage`) – The part of the page to consider

  `resize`(which=None)

    Resize all media overlays that are a child of an overlay

  `set_time`(media_id, t, *args)

    Set the player of a given media at time t. Used as a callback.

    Parameters

      - media_id (`int`) – A unique idientifier of the media to start playing

      - t (`float`) – the timestamp, in s

class `pympress.extras.` `TimingReport`(parent)

  Bases: `pympress.builder.Builder`

  `page_time` = []

    `list` of time at which each page was reached

  `reset`(reset_time)

    A timer reset. Clear the history as soon as we start changing pages again.

  `reset_time` = -1

    `int` the time at which the clock was reset

  `show`(current_time, doc_structure, page_labels)

    Show the popup with the timing infortmation

    Parameters

      - current_time (`int`) – the number of seconds elapsed since the beginning of the presentation

      - doc_structure (`dict`) – the structure of the document

      - page_labels (`list`) – the page labels for each of the pages

  `time_report_dialog` = None

    A `Dialog` to contain the timing to show.

  `timing_treeview` = None

    The `TreeView` containing the timing data to display in the dialog.

  `transition`(page, time)

    Record a transition time between slides

    Parameters

      - page (`int`) – the page number of the current slide

      - time (`int`) – the number of seconds elapsed since the beginning of the presentation

class `pympress.extras.` `Zoom`(builder)

  Bases: `object`

  `clear_cache`()

    callback, to be connected to `clear_cache()`

  `delayed_callback_connection`(scribble_builder)

    Connect callbacks later than at init, due to circular dependencies. Call this when the page_number module is initialized, but before needing the callback.

    Parameters

      builder (builder.Builder) – The builder from which to load widgets for scribble

  `draw_zoom_target`(widget, cairo_context)

    Perform the drawings by user.

    Parameters

      - widget (`DrawingArea`) – The widget where to draw the scribbles.

      - cairo_context (`Context`) – The canvas on which to render the drawings

  `get_matrix`(ww, wh)

    Returns the `Matrix` used to perform the zoom for the widget of size ww x wh.

    Parameters

      - ww (`float`) – widget width

      - wh (`float`) – widget height

    Returns

      the zoom transformation matrix

    Return type

      `Matrix`

  `get_slide_point`(widget, event)

    Gets the point on the slide on a scale (0..1, 0..1), from its position in the widget.

  `menu_zoom_out` = None

    `MenuItem` that is clicked to stop zooming

  `nav_zoom`(name, ctrl_pressed, command=None)

    Handles an key press event: stop trying to select an area to zoom.

    Parameters

      - name (`str`) – The name of the key pressed

      - ctrl_pressed (`bool`) – whether the ctrl modifier key was pressed

      - command (`str`) – the name of the command in case this function is called by on_navigation

    Returns

      whether the event was consumed

    Return type

      `bool`

  `p_central` = None

    `Box` in the Presenter window, used to reliably set cursors.

  `redraw_current_slide`()

    callback, to be connected to `redraw_current_slide()`

  `scale` = 1.0
  `set_scribble_zoomout_sensitive`()

    a callback for the `set_sensitive()` function of the zoom-out button in the scribble interface

  `shift` = (0, 0)
  `start_zooming`(*args)

    Setup for the user to select the zooming area.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `stop_zooming`(*args)

    Cancel the zooming, if it was enabled.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `toggle_zoom_target`(widget, event)

    Start/stop drawing the zoom’s target rectangle.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `track_zoom_target`(widget, event)

    Draw the zoom’s target rectangle.

    Parameters

      - widget (`Widget`) – the widget which has received the event.

      - event (`Event`) – the GTK event.

    Returns

      whether the event was consumed

    Return type

      `bool`

  `zoom_points` = None
  `zoom_selecting` = False

    Whether we are displaying the interface to scribble on screen and the overlays containing said scribbles

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

`pympress.util.` `fileopen`(f)

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

  Parameters

    f (`str`) – 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

    str

`pympress.util.` `get_icon_path`(name)

  Load an image from pympress’ resources in a Gdk Pixbuf.

  Parameters

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

  Returns

    The loaded icon

  Return type

    `Pixbuf`

`pympress.util.` `get_locale_dir`()

  Returns the path to the locale directory

  Returns

    The path to the locale directory

  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

    `str`

`pympress.util.` `get_portable_config`()

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

  Returns

    The path to the portable configuration file.

  Return type

    str

`pympress.util.` `get_pympress_meta`()

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

`pympress.util.` `get_ui_resource_file`(name)

  Load an UI definition file from pympress’ resources.

  Parameters

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

  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

    `str`

`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`

`pympress.util.` `set_screensaver`(must_disable, window)

  Enable or disable the screensaver.

  Parameters

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

    - window (`Window`) – The window on the screen where the screensaver is to be suspended.

### `pympress.media_overlays.base` – widget to play videos with a backend like VLC

class `pympress.media_overlays.base.` `VideoOverlay`(container, show_controls, relative_margins, page_type, callback_getter)

  Bases: `pympress.builder.Builder`

  Simple Video widget.

  Parameters

    - container (`Overlay`) – The container with the slide, at the top of which we add the movie area

    - show_controls (`bool`) – whether to display controls on the video player

    - page_type (`PdfPage`) – the part of the page to display

    - relative_margins (`Rectangle`) – the margins defining the position of the video in the frame.

  `autoplay` = False

    `bool` that tracks whether we should play automatically

  `do_hide`()

    Remove widget from overlays. Needs to be callded via GLib.idle_add

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_play`()

    Start playing the media file. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_play_pause`()

    Toggle pause mode of the media. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_set_time`(t)

    Set the player at time t. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Parameters

      t (`float`) – the timestamp, in s

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_stop`()

    Stops playing in the backend player.

  `dragging_paused` = False

    `bool` that tracks whether the playback was paused when the user started dragging the position

  `dragging_position` = False

    `bool` that tracks whether the user is dragging the position

  `format_millis`(sc, prog)

    Callback to format the current timestamp (in milliseconds) as minutes:seconds

    Parameters

      - sc (`Scale`) – The scale whose position we are formatting

      - prog (`float`) – The position of the `Scale`, i.e. the number of seconds elapsed

  `handle_embed`(mapped_widget)

    Handler to embed the video player in the correct window, connected to the `map` signal

  `hide` = None

    callback, to be connected to `hide()`, curryfied with the correct media_id

  `is_playing`()

    Returns whether the media is currently playing (and not paused).

    Returns

      `True` iff the media is playing.

    Return type

      `bool`

  `is_shown`()

    Returns whether the media overlay is currently added to the overlays, or hidden.

    Returns

      `True` iff the overlay is currently displayed.

    Return type

      `bool`

  `maxval` = 1

    `float` holding the max time in s

  `media_overlay` = None

    `VBox` that contains all the elements to be overlayed.

  `movie_zone` = None

    `DrawingArea` where the media is rendered.

  `parent` = None

    `Overlay` that is the parent of the VideoOverlay widget.

  `play` = None

    callback, to be connected to `play()`, curryfied with the correct media_id

  `play_pause` = None

    callback, to be connected to `play_pause()`, curryfied with the correct media_id

  `progress` = None

    `Scale` that is the progress bar in the controls toolbar - if we have one.

  `progress_moved`(rng, sc, val)

    Callback to update the position of the video when the user moved the progress bar.

    Parameters

      - rng (`Range`) – The range corresponding to the scale whose position we are formatting

      - sc (`Scale`) – The scale whose position we are updating

      - val (`float`) – The position of the `Scale`, which is the number of seconds elapsed in the video

  `relative_margins` = None

    `tuple` containing the left/top/right/bottom space around the drawing area in the visible slide

  `relative_page_margins` = None

    `tuple` containing the left/top/right/bottom space around the drawing area in the PDF page

  `resize`()

    Adjust the position and size of the media overlay.

  `set_file`(filepath)

    Sets the media file to be played by the widget.

    Parameters

      filepath (`str`) – The path to the media file path

  `set_time` = None

    callback, to be connected to `set_time()`, curryfied with the correct media_id

  `show`()

    Bring the widget to the top of the overlays if necessary.

  `time_format` = '{:01}:{:02}'

    ss / m:ss when the max time is known

    Type

      Format of the video time, defaults to m

    Type

      ss, changed to m

  `toolbar` = None

    A `HBox` containing a toolbar with buttons and `progress` the progress bar

  `update_margins_for_page`(page_type)
    Parameters

      page_type (`PdfPage`) – the part of the page to display

  `update_progress`(time)

    Update the toolbar slider to the current time.

    Parameters

      time (`float`) – The time in this video in s

  `update_range`(max_time)

    Update the toolbar slider size.

    Parameters

      max_time (`float`) – The maximum time in this video in s

`pympress.media_overlays.base.` `get_window_handle`(window)

  Uses ctypes to call gdk_win32_window_get_handle which is not available in python gobject introspection porting (yet ?) Solution from http://stackoverflow.com/a/27236258/1387346

  Parameters

    window (`Window`) – The window for which we want to get the handle

  Returns

    The handle to the win32 window

### `pympress.media_overlays.gif` – widget to play gif images as videos

class `pympress.media_overlays.gif_backend.` `GifOverlay`(container, show_controls, relative_margins, page_type, callback_getter)

  Bases: `pympress.media_overlays.base.VideoOverlay`

  A simple overlay mimicking the functionality of showing videos, but showing gifs instead.

  `advance_gif`()

    Advance the gif, queue redrawing if the frame changed, and schedule the next frame.

  `anim` = None

    A `PixbufAnimation` containing all the frames and their timing for the displayed gif

  `base_size` = None

    A `tuple` of (`int`, `int`) indicating the size of the bounding box of the gif

  `do_play`()

    Start playing the media file. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_play_pause`()

    Toggle pause mode of the media. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_set_time`(t)

    Set the player at time t. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Parameters

      t (`int`) – the timestamp, in ms

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_stop`()

    Stops playing in the backend player.

  `draw`(widget, ctx)

    Simple resized drawing: get the pixbuf, set the transform, draw the image.

  `is_playing`()

    Returns whether the media is currently playing (and not paused).

    Returns

      `True` iff the media is playing.

    Return type

      `bool`

  `iter` = None

    A `PixbufAnimationIter` which will provide the timely access to the frames in `anim`

  `mute`(*args)
  `set_file`(filepath)

    Sets the media file to be played by the widget.

    Parameters

      filepath (`str`) – The path to the media file path

  `set_transform`(*args)

    Compute the transform to scale (not stretch nor crop) the gif

  classmethod `setup_backend`()
  `transform` = None

    The `Matrix` defining the zoom & shift to scale the gif

### `pympress.media_overlays.gst` – widget to play videos using Gstreamer’s GstPlayer

class `pympress.media_overlays.gst_backend.` `GstOverlay`(*args, **kwargs)

  Bases: `pympress.media_overlays.base.VideoOverlay`

  Simple Gstramer widget.

  Its player can be controlled through the ‘player’ attribute, which is a `Player` instance.

  `do_play`()

    Start playing the media file.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_play_pause`()

    Toggle pause mode of the media. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_set_time`(t)

    Set the player at time t. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Parameters

      t (`float`) – the timestamp, in s

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_stop`()

    Stops playing in the backend player.

  `is_playing`()

    Returns whether the media is currently playing (and not paused).

    Returns

      `True` iff the media is playing.

    Return type

      `bool`

  `mute`(value)

    Mutes the player.

    Parameters

      value (`bool`) – `True` iff this player should be muted

  `player` = None

    A `PlayerVideoOverlayVideoRenderer` to be display the videos

  `player_state` = <enum GST_PLAYER_STATE_STOPPED of type GstPlayer.PlayerState>
  `set_file`(filepath)

    Sets the media file to be played by the widget.

    Parameters

      filepath (`str`) – The path to the media file path

  classmethod `setup_backend`(gst_opts=[])

    Prepare/check the Gst backend

    Returns

      the version of Gst used by the backend

    Return type

      `str`

  `track_state`(player, state)

    Update the current state of the player for easy reference

    Parameters

      - player (`Player`) – The player for which the position changed

      - duration (`PlayerState`) – The player’s new state

### `pympress.media_overlays.vlc` – widget to play videos using VLC

class `pympress.media_overlays.vlc_backend.` `VlcOverlay`(*args, **kwargs)

  Bases: `pympress.media_overlays.base.VideoOverlay`

  Simple VLC widget.

  Its player can be controlled through the ‘player’ attribute, which is a `MediaPlayer` instance.

  `do_play`()

    Start playing the media file. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_play_pause`()

    Toggle pause mode of the media. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_set_time`(t)

    Set the player at time t. Should run on the main thread to ensure we avoid vlc plugins’ reentrency problems.

    Parameters

      t (`float`) – the timestamp, in s

    Returns

      `True` iff this function should be run again (`idle_add()` convention)

    Return type

      `bool`

  `do_stop`()

    Stops playing in the backend player.

  `handle_embed`(mapped_widget)

    Handler to embed the VLC player in the correct window, connected to the `map` signal

  `is_playing`()

    Returns whether the media is currently playing (and not paused).

    Returns

      `True` iff the media is playing.

    Return type

      `bool`

  `mute`(value)

    Mutes the player.

    Parameters

      value (`bool`) – `True` iff this player should be muted

  `set_file`(filepath)

    Sets the media file to be played by the widget.

    Parameters

      filepath (`str`) – The path to the media file path

  classmethod `setup_backend`(vlc_opts=['--no-video-title-show'])

    Prepare/check the VLC backend

    Parameters

      vlc_opts (`list`) – the arguments for starting vlc

    Returns

      the version of VLC used by the backend

    Return type

      `str`