Pd Community Site

From Pd 0.43 on, Tcl/Tk plugins can be used to add optional functionality to the GUI. Using a GUI plugin, it is possible to change both the looks and the behavior of Pd's user interface.

Installing

GUI Plugins go into one of Pd's standard paths which depend on your Platform.

Naming

Every file that uses the xyz-plugin.tcl naming scheme and resides in the object search path of Pd is executed upon startup. More exactly, it is the pdtk_pd_startup function in pd-gui.tcl that calls the execution of startup plugins, in the following order:

    # [...]
    ::pdwindow::create_window
    ::pd_menus::configure_for_pdwindow
    load_startup_plugins                # The magic happens here
    open_filestoopen
    set ::done_init 1                   # End of pdtk_pd_startup

Format

There are no requirements concerning the format or structure of startup plugins. As an example, here are some recommended elements:

# META NAME My nifty plugin
# META DESCRIPTION Does all kinds of magic that may not be necessary for everyone
# META AUTHOR <John the Developer> johndev@mail.com

package require Tcl 8.5         # The minimum version of TCL that allows the plugin to run
package require Ttk             # If Tk or Ttk is needed
package require pdwindow 0.1    # Any elements of the Pd GUI that are required
                                # + require everything and all your script needs.
                                #   If a requirement is missing,
                                #   Pd will load, but the script will not.

Overwriting functions

To overwrite an existing TCL function, do this:

rename the_function the_function_old   # This is not so important

proc the_function {params} {           # We are just redefining the function
      # here goes your new logic
}

# Alternatively, you can try to execute a find&replace
# style patcher function on the function:
proc the_function {params} [my_patcher_func [info body the_function]]

Pd resources to use in startup plugins

There are parts of the pd-gui code that is intended to be an API for writing plugins, you can see some of that documented in the GUIPluginsAPI page. For a more complete look, check out existing plugins and the Pd sources.

Beware! There is no complete and final API for plugins. As Pd changes, your plugin might become unusable (so you'll have to keep it updated).

There are, however, some variables in pd-gui.tcl intended for plugins:

# These constants will hold the actual version numbers
set PD_MAJOR_VERSION 0
set PD_MINOR_VERSION 0
set PD_BUGFIX_VERSION 0
set PD_TEST_VERSION ""
set TCL_MAJOR_VERSION 0
set TCL_MINOR_VERSION 0
set TCL_BUGFIX_VERSION 0

# Useful variables
# root path to lib of Pd's files, see s_main.c for more info
set sys_libdir {}
# root path where the pd-gui.tcl GUI script is located
set sys_guidir {}
# user-specified search path for objects, help, fonts, etc.
set sys_searchpath {}
# hard-coded search path for objects, help, plugins, etc.
set sys_staticpath {}
# list of command line flags set at startup
set startup_flags {}
# list of libraries loaded on startup
set startup_libraries {}

# Variables for holding the menubar to allow for configuration by plugins
set ::pdwindow_menubar ".menubar"
set ::patch_menubar   ".menubar"

To post messages to the console, use:

::pdwindow::verbose 1 "Hello, World!"
::pdwindow::error "Houston, we have a problem!"
::pdwindow::fatal "See you on the other side."
::pdwindow::post  "This message will self destruct in five seconds."
::pdwindow::debug "Second phase initiated"

The use a string (anywhere in your plugin) which has been translated to language versions (as described in HowToTranslatePd), use the '_' function. For example:

toplevel .myplugwindow
wm title .myplugwindow [_ "My Plugin Window Title in Languages"]

Canvas Widget

Items present on a canvas (text fonts, message boxes, objects boxes, etc) are items present on a canvas widget. For example in the case of text:

tk -> text widget = powerful multiline text display, lots of control over text/font settings, can embed images and other tk widgets tk -> canvas -> text item = limited text display inside a prexisting canvas, limited control over text/font, no embedding

Information on altering items present on a canvas widget can be found here: http://www.tcl.tk/man/tcl8.5/TkCmd/canvas.htm Note: These options are not specific to Pd. They are tk settings.

An example of changing fonts on a canvas is illustrated here:

$tkcanvas itemconfigure text -fill red -font {Helvetica 16}  ;# points
$tkcanvas itemconfigure text -fill red -font {Helvetica -16}  ;# negative is pixels