puzzlepiece.action module

class puzzlepiece.action.Action(function, parent, shortcut=None, visible=True)[source]

Bases: QObject

An action is a function that a Piece object can call.

It will be given a button in the GUI (if visible is True), and can be executed from code in other Pieces or elsewhere as if it was a method:

puzzle['piece_name'].actions['action_name']()

Any arguments provided when calling an action will be passed to the registered function.

To register an action, use the define() decorator as shown below. The action will return the values your function returns.

Parameters:

function – The function to call when the action is executed.
parent – The Piece this action belongs to.
shortcut – A keyboard shortcut for this action, works only when the Piece is visible.
visible – Bool flag, whether a button for the action is generated in the GUI.

called: A Qt signal emitted when the action is executed.

shortcut: Keyboard shortcut associated with the param.

property visible: Bool flag, indicates whether this action is visible as a button in the GUI.

make_child_action()[source]

Create and return a child action that calls the same callable.

See puzzlepiece.piece.Popup.add_child_actions() for a quick way of adding child actions to a popup.

puzzlepiece.action.define(piece, name, shortcut=None, visible=True)[source]

A decorator generator for registering a Action in a Piece’s define_actions() method with a given function.

To register an action for a function, do this:

@puzzlepiece.action.define(self, 'action_name')
def action():
    print(f"Hello world from {self}!")

It’s also allowed to provide “self” as the first argument of the action method for added clarity, but since self exists locally within define_actions() this is technically not required:

@puzzlepiece.action.define(self, 'action_name')
def action(self):
    print(f"Hello world from {self}!")

The method you’re decorating can take arguments, but all should in general be optional, as invoking the actio with a GUI button will not provide arguments to it:

@puzzlepiece.action.define(self, 'Say Hello')
def say_hello(name="test user"):
    print(f"Hello {name}}!")

This can be invoked as:

puzzle["piece_name"].actions["Say Hello"]()
puzzle["piece_name"].actions["Say Hello"]("another user")
puzzle["piece_name"].actions["Say Hello"](name="another user")

Parameters:

piece – The Piece this param should be registered with. Usually self, as this method should be called from within puzzlepiece.piece.Piece.define_actions()
name – a unique (per Piece) name for the action
shortcut – The keyboard shortcut for this action. See https://doc.qt.io/qt-6/qt.html#Key-enum for possible values. Example: QtCore.Qt.Key.Key_F1
visible – bool flag, determined if a GUI button will be shown for this param.