The TkTurf plugin API is constantly evolving as overlooked requirements are found. The API may change in such a way that older plugins no longer function, although this shall be avoided as much as possible. It is also possible that certain features may exist but remain undocumented. This file shall be maintained as time allows. The file is laid out in two sections. First, there is a style/procedure guide and introduction to hidden API features and aspects of the API which are not function based. This is followed by an index of functions included in the API for plugins, and the TkTurf program API.

The first thing a TkTurf plugin should do is register itself with the plugin registry. While not strictly needed, this provides a convenient means for users to identify which plugins are installed correctly, and which versions of said plugins they are currently using. This is done by calling the register function, which takes three arguments. register "name" version "description", where the name and description are relevant descriptive strings, and the version number is a floating point number. TkTurf now has a plugin manager plugin which downloads upgraders based on registration information, making this standard registration vital.

TkTurf plugins are executed immediately after all core TkTurf is loaded and immediately before the interface is created. This allows plugins to (in theory) over write any function they need to modify. Since multiple plugins may alter the same function it is recommended that plugins modify any functions in a non-destructive manner. This can be done through use of the info command, specifically, info args, and info body. Code can be appended to the end of the function, which will allow other plugins to also modify the same function. This can also be impossible on certain functions, such as the function for saving preferences, which has a buffer flush at the end of it. More sophisticated methods can be employed for non-destructive function editing in this case, such as use of the regsub command and code known to be in the function. In many (file|window) event binding cases functions can be stacked by a plugin. This can be done by getting the current binding and adding to the front or back of the stack, and having the function possibly alter the operating of following functions. For example, if a plugin wishes to filter through the input from the main prompt area, it could call bind that widget to "MyFunction;[bind .promptline.mainent <Return>]". If that function wished to prevent any other stack function (such as the originally bound STDre) from working in this case it could just set .promptline.mainent to "", and if it wishes to have those functions work normally it could not reset the widget text.

For removal of bindings for Plugin Reload compatability the unbind command, detailed below, is available.

Plugin scripts are not run in the global scope. Any loaded functions enter the root namespace, as expected. Variables, on the other hand, are *not* put in the global scope. Any variable which is expected to be global must be declared global even at the main script level.

Plugins may load and save variables through the PREFS global array. Any variable which the plugin wishes to have loaded from the preferences file must be set to a reasonable default in the PREFS array at script execution time, not to be confused with script installation time (discussed later). Variables in the prefs array, such as PREFS(LCKCMD) will be loaded from the preferences file, and any default will be overwritten. Variables in the PREFS array are automatically saved with the rest of the preferences, which requires the user to do something which will invoke the function which saves the preferences... this can be forced by the plugin if it wishes, with the command "::Preferences::save".

Array saving is not possible. If a plugin needs more complex data management than single variables, the plugin should use its own data file, for easy data management and uninstallation.

TkTurf provides a Misc ButtonNotebook preferences frame for one or two preferences from a plugin. If more need be added the plugin should create its own page. To either add an entry or a page simply use ::Preferences::addHook to add a function which will add to the preferences widget to this list and the commands from it will be run when the preferences window is created. Said commands are executed in the scope of the main preferences window function, so you may use variables therein stored if you wish.

Any special preference application can be done by using ::Preferences::addApply. Preference application is done before destruction of the preferences window, and before saving of the preferences, so it is possible to grab text from any widget in the text window. Function bodies are executed directly inside the apply function's scope with [info body].

Preferences window and apply hooks can be removed with the ::Preferences::removeHook and ::Preferences::removeApply functions, as detailed below. This should be done at the appropriate time for Plugin Reload compatability.

Since most any plugin will need to affect the interface to be used, TkTurf's plugin API provides a system for installing the plugin after it has been initially loaded. To have itself installed a plugin should create a procedure in the root namespace which begins with "install", such as "install_historybox". And underscore is not needed, but any name should be unique enough that it does not conflict with other plugins (the name of the plugin is generally a good trailer, for clarity). This special reserved function will be run immediately after interface creation, and immediately before creation of the socket connection to Turf. Plugins are not required to have an uninstall function, and providing one should probably be viewed as a pollution of the namespace, rather than a feature. This is because a runtime manager of plugins is not likely to be added. (Personally, I'd like it, just so I can edit plugins without restarting every time I edit a function, but I'm generally content to just use the Plugins::load function, since most changes are not direct changes to the interface management code.)

TkTurf provides a nice tray space for icon button interfaces to plugins. The path for this is .promptline.tray, which is a frame any button may be packed into. For stylistic consistency icons should be roughly 12x12, and all buttons should have flat relief, and standard colors (unless a good reason precludes this, such as the errorlog plugin, which changes to a red icon to indicate a fault).

Sound events may be automatically loaded and saved to the preferences file by setting an element in the SOUNDSTUB global array (at load time). This sound event's value sound may be added to the preferences window sound editor by setting a human-readable name for this sound in soundnames array. Any sound not listed in this array will be left to the plugin to customize. Self entry and customization in either the Misc frame or a unique frame is the preferred method for plugin soud customization, to keep the page a reasonable size.

TkTurf includes a system for hiding "system" triggers, so that plugins may automatically add a trigger which will not appear in the trigger edit window. To specify a trigger as a system trigger, make the first line of the trigger execution code "#TkTurf System Trigger".

Triggers in TkTurf 3.02+ can destroy whatever text triggered them. To do so a trigger should use upvar on the line variable in the next level up of the stack, and set it to null. Example: "upvar line line" sets local variable line to refer to line in the executing scope, so line is the line that triggered the match. As of 3.02+ lines should be spooled line at a time to triggers, however this is not fully tested.

Aliases may also be made "system" aliases which are hidden from view. In the same manner as triggers the first line of their function should be "#TkTurf System Alias". (Although, with aliases it is not required that it by the first line.) Setting an alias manually in TkTurf can be done by creating the proper function in ::Aliases::. If an alias is not created at load time you must call ::Alias::makelist to refresh the alias listing.

Turf assumes that if a socket is blocked when Turf attempts to write to it that it is link-dead, but this can also happen when the socket is flooded. If a client will be sending large numbers of messages to remote clients it is necessary to slow the flow of messages, or one or both parties may lose their links. To accomplish this a message spooling system has been added. See details in the Spool namespace below. Spool::enqueue should not be used in high-performance situations.

TkTurf includes an Event system for easier session management. Several events are pre-defined and called by TkTurf, including: CONNECT, LOGIN and DISCONNECT, and SHUTDOWN. The system is open to the definition and calling of other events. Typically this system should be used for plugins such as biff, which must reset for every connection. This event system is in no way connected with the eventsound system for sounds.

Turf now includes a system for capturing output from commands with c15 h. Programmers interested in using this should consult the Turf Protocol documentation. TkTurf includes a system for gathering and distributing commands received under this new protocol with the Capture::addID command (see below). This allows the programmer to specify a function to be called which must take one argument. Data from a command should be sent in single-line chunks.
A unique identifier should be used for c15 h commands, and it is advisable to use the API "new" function. In the case that a unique window is also needed to go with this unique command it is advised that the same identifier be used for both, and the data reading command for the id can use the $::CMD_ID variable to get the current identifier. However, should additional data be needed for the capture function, ::Capture::addID uses scripts rather than functions for execution, however any script should be capable of taking the data argument as a final argument to the call.
When the output from the command is finished the read function for Capture will be called one more time with a null data argument. This is the only time it will be called with no data, and can be used to determine when the command is done returning information.

TkTurf now includes a system for plugin cooperation in areas where many plugins want jurisdiction, such as prompts and text output filters. See the Plugins::addFilter, Plugins::addPrompt, Plugins::addCommand, Plugins::removeFilter, Plugins::removePrompt, and Plugins::removeCommand functions below. The core of this system is not destroying anything already present, and returning unused data.

Function index (dictionary sort):

addhandler prefix handler

Adds a c15 c Turf protocol message handler. Messages beginning with "prefix" in the standard Turf protocol c15 c message format will be passed to the function "handler", which then has sole authority over handling them. Useful for game plugins, file transfer plugins, and other Turf protocol uses.

This function should be called instead of the native beep function, so that sounds can replace beeps if so configured.

This function creates a frame "frame" with a button notebook widget inside it. It also creates any number of page names specified in the list "args" (page names appear as the button names for each frame). This function returns the name of the created frame.

Returns the window pathname to the frame of page number "num" in the button notebook widget "frame".

Returns the window pathname for the next unedited page in the button notebook widget specified by the "frame" path.

This function adds a new page to the button notebook in the frame "frame", and returns the new page window path.

Add a handler for capture id id. Function should be prepared to take one argument which is data read from the socket. Data will always end in a newline and will never contain colour codes. See notes above about valid script arguments for this function.

Creates a challenge posing window for the game described by "game" (human-friendly string). "cmd" is run if the user accepts, "dcmd" is run if the user declines.

Plays the sound associated with the event event

Generate an event event and call all attached functions

Sets code fragment script to be called on event event

Removes script from being called when event is encountered.

Creates a window ."win", which is titled "title" and executes "cmd" to challenge a player. A handler function must be used to spool names into the window for the list, which will have the path ."win".listing.list

Returns a literal string "string" as a denatured regexp usable string.

Makes a toplevel window "win" act as a keypress relay to the promptline entry area. This is used by all the games and challenge messages to allow users to type into the main entry area as if the window was not in the way.

Returns a unique identifier. Useful when an anonymous window is needed, such as [toplevel .[new]] calls. Also useful with the c15 h protocol extension.

Plays the audio file "file" using the specified audio player.

Registers a plugin with the plugin registry. "name" is a arbitrary brief descriptive string, "version" is a floating point canonical major.minor version number, and "description" is a long string description of what the plugins does/provides.

Adds filterfunction to a list of filters to be called when the user sends a command through the command entry. The function should expect a single data argument and return any unused data.

Adds filterfunction to a list of filters to be called on output going to any window with the wintalk command. Function should expect three arguments, widget, data, and text flags. It may use or discard this data as needed, but *must* return unused portions of passed data (or that data will not be shown).

Adds promptfunction to a list of prompt filters to be called when the prompt is refreshed. This function will be called with one argument composed of the remaining prompt text. Any prompt filter function must return unused portions of this prompt.

Removes filterfunction from those called when whenever a command is sent through the command entry widget.

Removes filterfunction from those called when whenever output is sent to a window with the wintalk command.

Removes promptfunction from those called when whenever the prompt is refreshed.

Adds function to those called when the preferences are applied before preferences window destruction.

Adds function to those called when the preferences window is created.

Removes function from those called when the preferences are applied.

Removes functionfrom those called when the preferences window is created.

Saves all preferences.

Adds msym and description to the markers and descriptions presented and handled by the Prompt Builder plugin.

Removes msym to the markers presented and handled by the Prompt Builder plugin.

Creates a scrolled list with window path "frame" (list part is "frame".list). "args" are given to the list widget creation, and any valid listbox widget argument is valid. Returns "frame".list, the list widget path.

Creates a scrolled text widget frame "frame". "args" are applied to the text widget on creation. Any flag valid for a text widget is valid for the "args". Returns "frame".text, the path to the text component of the Scrolled Text Widget.

Sends the string "message" to the Turf socket connection.

Enqueues (a) message(s) for sending.

Removes script from the binding on tag for the event pattern sequence.

Put "message" in the text window "win" and apply "flags" as flags to the text. Note that flags is not an optional args value, it must either be a list of tags, or a null value. Used for standard text window writing.