2. GNOME-Mud's Python plugin interface

2.1. Basic usage

When GNOME-Mud launches, it scans the $HOME/.gnome-mud directory for Python scripts, ie. files ending with the .py suffix, and loads each script found in turn. Each script should import the GnomeMud module, which provides all the API functions necessary for writing useful scripts.

2.2. GnomeMud module

The GnomeMud module provides access to the GNOME-Mud scripting API. Normally, a script would register_input_handler() and register_output_handler() as needed to register callback functions, possibly adding some widgets using add_user_widget() if using PyGTK, and then have no further use of this module.

Adds a GTK+ widget, created by PyGTK, to the GNOME-Mud application window. The parameters are passed more or less directly to gtk_box_pack_start(), and the meaning of expand, fill and padding is to be found in the GTK+ documentation.

You would commonly use this function to build status displays or action buttons.

Note

The widget parameter must refer to a genuine PyGTK widget. The function will only check to ensure it is passed a Python object, and then blithely go on to assume it is the correct type of Python object. The effect of passing a different kind of object to the function is undefined, although GTK+ can generally be trusted to spot the error. However, Python will be completely unaware of the incident and assume everything proceeded in a correct manner.

This function is only available if GNOME-Mud has been compiled with PyGTK support.

Returns a Connection object for the currently active connection, meaning the connection tab being currently displayed in the GNOME-Mud application window. This is useful for printing some descriptive text during script initialisation, or displaying some especially urgent text to the user from a callback function.

Registers a callback function for input received from a MUD connection. The callback function is passed two parameters: a Connection object referring to the connection on which the input was received, and a string containing the actual input. The return value of the function may be a string, which is then further processed by GNOME-Mud as if it were the actual data received from the connection, or any other type of Python object, in which case GNOME-Mud is passed the original string. Thus, you are able to modify the data received on a socket before GNOME-Mud at large sees it, allowing you to gag input or perform text substitutions.

Registers a callback function for data being sent to a MUD connection. This works similarly to the callback functions for register_input_handler() above, but applies to text entered by the user, or caused by triggers or key bindings. It does not apply to data sent by Python scripts using the send() method provided by the Connection class.

This function simply returns the GNOME-Mud version that is running, as a string.

2.2.1. Connection class

Connection is an interface class for a GNOME-Mud connection, meaning a socket connection to a MUD and its corresponding text display. It is normally used for sending data to the socket through the send() method and printing to the display using the write() method.