Customize using plugins

The pibooth application is built on the top of pluggy that gives users the ability to extend or modify its behavior thanks to plugins.

Several plugins maintained by the community are available. They add extra features to pibooth. Have a look to the plugins on PyPI.

You can also easily develop your own plugin, and declare it in the [GENERAL][plugins] key of the configuration.

What is a plugin?

A plugin is a set of functions (called hooks) defined in a python module and participating to the pibooth execution when they are invoked.

The list of available hooks are defined on this chapter. A plugin implements a subset of those functions.

There are 2 families of hooks implemented in pibooth:

• Pibooth state-independent hooks

• State dependant hooks (see below)

Influencing states

The pibooth application is built on the principle of states. Each state is defined by a specific screen and possible actions available to the user.

The following states are defined:

• wait : wait for starting a new capture sequence

• choose : selection of the number of captures

• chosen : confirm the number of captures

• preview : show preview and countdown

• capture : take a capture

• processing : build the final picture

• print : show preview and ask for printing

• finish : thank before going back to wait state

• failsafe : oops message when an exception occurs

There are four hooks defined for each state.

• state_<name>_enter

  Invoked one time when the state is activating.

• state_<name>_do

  Invoked in a loop until the state is switching to an other one.

• state_<name>_validate

  Invoked in a loop, returns the name of the next state if all conditions are met (else return None).

• state_<name>_exit

  Invoked one time when the state is exiting.

Code skeleton

A plugin is generally a Python module called pibooth_[...].py. For a better configuration management, it should have the constant __version__ set to the plugin version:

__version__ = "1.0.0"

The pibooth_configure hook permits to define some new configuration options. At this step of the starting process, only the pre-loaded configuration is available (application is not created yet).

@pibooth.hookimpl
def pibooth_configure(cfg):
    cfg.add_option('CONTROLS', 'startup_led_pin', 29,
                   "Physical GPIO OUT pin to light a LED at pibooth startup")

The new objects, which should persist between states, can be created and attached to the application instance in the pibooth_startup hook:

@pibooth.hookimpl
def pibooth_startup(cfg, app):
    app.led_startup = LED("BOARD" + cfg.get('CONTROLS', 'startup_led_pin'))

Access to internal variables

cfg

class PiConfigParser(filename, plugin_manager, load=True)

Class to parse and store the configuration values. The following attributes are available for use in plugins:

Attr filename:

absolute path to the laoded config file

join_path(*names)

Return the directory path of the configuration file and join it the given names.

Parameters:

names (str) – names to join to the directory path

add_option(section, option, default, description, menu_name=None, menu_choices=None)

Add a new option to the configuration and defines its default value.

Parameters:

• section (str) – section in which the option is declared

• option (str) – option name

• default (any) – default value of the option

• description (str) – description to put in the configuration

• menu_name (str) – option label on graphical menu (hidden if None)

• menu_choices (any) – option possible choices on graphical menu

get(section, option, **kwargs)

Get a value from config. Return the default value if the section or option is not defined.

Parameters:

• section (str) – config section name

• option (str) – option name

Returns:

value

Return type:

str

set(section, option, value=None)

Set a value to config. Create the section if it is not defined.

Parameters:

• section (str) – config section name

• option (str) – option name

• value (str) – value to set

gettyped(section, option)

Get a value from config and try to convert it in a native Python type (using the ast module).

Parameters:

• section (str) – config section name

• option (str) – option name

getpath(section, option)

Get a path from config, evaluate the absolute path from configuration file path.

Parameters:

• section (str) – config section name

• option (str) – option name

gettuple(section, option, types, extend=0)

Get a list of values from config. The values type shall be in the list of authorized types. This method permits to get severals values from the same configuration option.

If the option contains one value (with acceptable type), a tuple with one element is created and returned.

Parameters:

• section (str) – config section name

• option (str) – option name

• types (list) – list of authorized types

• extend (int) – extend the tuple with the last value until length is reached

getint(section, option, *, raw=False, vars=None, fallback=<object object>, **kwargs)

getfloat(section, option, *, raw=False, vars=None, fallback=<object object>, **kwargs)

getboolean(section, option, *, raw=False, vars=None, fallback=<object object>, **kwargs)

app

class PiApplication(config, plugin_manager)

Main class representing the pibooth software. The following attributes are available for use in plugins:

Attr capture_nbr:

number of capture to be done in the current sequence

Attr capture_date:

date (%Y-%m-%d-%H-%M-%S) of the first capture of the current sequence

Attr capture_choices:

possible choices of captures numbers.

Attr previous_picture:

picture generated during last sequence

Attr previous_animated:

infinite list of picture to display during animation

Attr previous_picture_file:

file name of the picture generated during last sequence

Attr count:

holder for counter values

Attr camera:

camera used

Attr buttons:

access to hardware buttons capture and printer

Attr leds:

access to hardware LED capture and printer

Attr leds:

gpiozero.LEDBoard

Attr printer:

printer used

property picture_filename

Return the final picture file name.

find_quit_event(events)

Return the first found event if found in the list.

find_settings_event(events)

Return the first found event if found in the list.

find_fullscreen_event(events)

Return the first found event if found in the list.

find_resize_event(events)

Return the first found event if found in the list.

find_capture_event(events)

Return the first found event if found in the list.

find_print_event(events)

Return the first found event if found in the list.

find_print_status_event(events)

Return the first found event if found in the list.

find_choice_event(events)

Return the first found event if found in the list.

win

class PiWindow(title, size=(800, 480), color=(0, 0, 0), text_color=(255, 255, 255), arrow_location='bottom', arrow_offset=0, debug=False)

Class to handle the window. The following attributes are available for use in plugins:

Attr surface:

surface on which sprites are displayed

Attr is_fullscreen:

set to True if the window is display in full screen

Attr display_size:

tuple (width, height) represneting the size of the screen

get_rect(absolute=False)

Return a Rect object (as defined in pygame) for this window.

Parameters:

absolute (bool) – absolute position considering the window centered on screen

get_image()

Return the currently displayed foreground image.

resize(size)

Resize the window keeping aspect ratio.

update()

Repaint the window with currently displayed images.

show_oops()

Show failure view in case of exception.

show_intro(pil_image=None, with_print=True)

Show introduction view.

show_choice(choices, selected=None)

Show the choice view.

show_image(pil_image=None, pos='center')

Show PIL image as it (no resize).

show_work_in_progress()

Show wait view.

show_print(pil_image=None)

Show print view (image resized on the left).

show_finished(pil_image=None)

Show finished view (image resized fullscreen).

flash(count)

Flash the window content.

set_capture_number(current_nbr, total_nbr)

Set the current number of captures taken.

set_print_number(current_nbr=None, failure=None)

Set the current number of tasks in the printer queue.

toggle_fullscreen()

Set window to full screen or initial size.

drop_cache()

Drop all cached background and foreground to force refreshing the view.