Personal tools
You are here: Home documentation GUI Plugins GUI Plugins
Views

Edit history

Edit: -1 of 1
Time: 2013-01-25 15:16:36
Note: /pd/pd/docs/guiplugins/GUIPlugins/edit

changed:
-
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 [http://puredata.info/docs/faq/how-do-i-install-externals-and-help-files 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 [http://puredata.info/dev/HowToTranslatePd !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
}}}




Powered by IEM Powered by Plone Section 508 WCAG Valid XHTML Valid CSS Usable in any browser