Some PyGUI classes have one or more action properties. An action
property specifies an action to perform in response to something done by
the user, e.g. clicking a button.
The value of an action property can take any of the following forms:
- A function (or other callable object)
- A tuple (function, arg, ...)
- A message name specifying a message to be sent up the message
- A tuple (message, arg, ...)
Invoking actions programmatically
As a general principle, action properties are only triggered in response
to actions performed by the user, not actions performed by the program. For
example, the action property of a CheckBox is triggered when the
user clicks on the check box, but not when the on property of the
check box is assigned to by program code. This makes it easier to set up
actions which keep different controls in sync with each other without inadvertently
creating infinite loops.
If you do want an action performed in response to program code, you will
need to trigger it explicitly. Corresponding to each action property xxx_action
there is a method called do_xxx_action which invokes the action.
For example, here is how you can change the on property of a check
box and trigger the action as though the user had clicked on the control:
my_checkbox.on = True
Overriding actions in subclasses
If you subclass a component and want the subclass to provide an action for
one of the superclass's action properties, there are a couple of ways you
can go about it. One is to simply pass a bound method of the subclass as
the initial value of the action property when calling the superclass's __init__
method. This is not the best way, however, since it uses up the action slot
and precludes the possibility of users of your class using it to further
customise the component's behaviour. Worse, if the user doesn't realise the
action slot is already in use and plugs in an action of his own, it will
supplant your subclass's action, which is probably not what you want.
A better way is to override the do_action method for the action.
This ensures that users of your class can't inadvertently wipe out your action,
and leaves the action property open for further customisation, which you
can allow by calling the superclass's do_action method from yours.
...do something special here,
give user's action a go