# HG changeset patch # User Mark Doliner # Date 1103856625 0 # Node ID 68d6065fc32ffe8288ee37b0118d95aa450a3e6e # Parent f53c59c95f0349a5763a2a10bad5c7323e572501 [gaim-migrate @ 11657] sf patch #1083616, from Balwinder Singh Dheeman Convert the TCL-HOWTO to a doxygen version committer: Tailor Script diff -r f53c59c95f03 -r 68d6065fc32f COPYRIGHT --- a/COPYRIGHT Fri Dec 24 02:29:24 2004 +0000 +++ b/COPYRIGHT Fri Dec 24 02:50:25 2004 +0000 @@ -37,6 +37,7 @@ Felipe Contreras Adam Cowell Jeramey Crawford +Balwinder Singh Dheeman Finlay Dobbie Mark Doliner Nuno Donato diff -r f53c59c95f03 -r 68d6065fc32f doc/Makefile.am --- a/doc/Makefile.am Fri Dec 24 02:29:24 2004 +0000 +++ b/doc/Makefile.am Fri Dec 24 02:50:25 2004 +0000 @@ -6,6 +6,7 @@ CREDITS \ FAQ \ PERL-HOWTO.dox \ + TCL-HOWTO.dox \ account-signals.dox \ blist-signals.dox \ connection-signals.dox \ diff -r f53c59c95f03 -r 68d6065fc32f doc/TCL-HOWTO.dox --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/TCL-HOWTO.dox Fri Dec 24 02:50:25 2004 +0000 @@ -0,0 +1,354 @@ +/** @page tcl-howto Tcl Scripting HOWTO + +@section Intoduction + +The Gaim Tcl interface provides a Tcl API for many useful gaim +functions. Like the perl API, the Tcl API does not provide +access to every corner of gaim exposed by the @e C interface. It does, +however, provide a very powerful interface to many of Gaim's functions +through a simple to learn and extend scripting language. + +If you are not familiar with Tcl, you will probably find it somewhat +different from what you are used to. Despite being somewhat unique +(more akin to shell programming than other traditional scripting +languages such as @e perl or @e python), it is simple to learn for +beginners and experienced programmers alike. There are numerous books +on the subject; we will not discuss it any further here. + +@section start Getting Started + +The only requirement placed on a Gaim Tcl script by Gaim is the +existence of a procedure called @c plugin_init. This procedure has +some limitations placed upon it; it will be parsed and evaluated before +the rest of the Tcl script, so it cannot reference any other variables +or procedures declared in the script. In practice this is not a +problem, as the only thing this procedure should do is return a simple +list containing five items: the @b name of the script, its @b version +number, a @b summary (just a few words) of its function, a short (longer +than the summary, but no more than a couple of sentences if possible) +@b description, the @b author, and a @b URL to web page. For example: + +@code +proc plugin_init { } { + return [ list "Example Plugin" \ + "1.0" \ + "Example plugin registration" \ + "Example of how to register a plugin for the Tcl HOWTO" \ + "Ethan Blanton " \ + "http://gaim.sf.net/" ] +} +@endcode + +The rest of the script will generally be registration to recieve +notification of various Gaim signals (more about this below) and +definitions of procedures to be executed when those signals occur. + +@section details Interpreter Details + +Gaim initializes and drives the Tcl event loop (similar to Tk), +meaning that commands like @c fileevent and @c after are available and +do not require @c vwait etc. The @c vwait actually seems to be somewhat +broken due to a bug somewhere in the Tcl/Glib event loop glue, and it +should not be used for now. + +The gaim-specific functions are provided in a statically-linked +package called @c gaim; this means that if you spawn a child +interpreter and wish to use the gaim-specific functions, you will need +to execute load {} gaim in that interpreter. + +@section internals Gaim Internal Procedures and Variables + +All of the information provided for your use by Gaim will be in the @c +::gaim namespace. This means that in order to access it you will either +have to import the gaim namespace (e.g. via the command namespace +import gaim::*) or reference it explicitly. The following +descriptions will reference it explicitly for clarity. + +@li Variables + +@code +gaim::version +@endcode + + This contains the version of the gaim process which loaded the + script. + +@li Commands + +@code +gaim::account alias account +gaim::account connect account +gaim::account connection account +gaim::account disconnect account +gaim::account find username protocol +gaim::account handle +gaim::account isconnected account +gaim::account list ?option? +gaim::account protocol account +gaim::account username account +@endcode + + The @c gaim::account command consists of a set of subcommands + pertaining to gaim accounts. + + @c alias returns the alias for the account @c account. If there is no + alias for the given account, it returns the empty string. + + The subcommand @c connect connects the named account if it is not + connected, and does nothing if it is. In either case, it returns + the @c gc for the account. + + @c connection returns the @c gc of the given account if it is connected, + or 0 if it is not. This @c gc is the gc used by gaim::connection and + other functions. + + @c disconnect disconnects the given @c account if it is connected, or + does nothing if it is. + + @c find finds an account by its @c username and @c protocol (as returned by + gaim::account username and gaim::account protocol) and + returns the account if found, or 0 otherwise. + + @c handle returns the instance handle required to connect to account + signals. (See gaim::signal connect). + + The @c isconnected query returns true if the given account is + connected and false otherwise. + + The @c list subcommand returns a list of all of the accounts known to + Gaim. The elements of this lists are accounts appropriate for the + @c account argument of the other subcommands. The @c -all option + (default) returns all accounts, while the @c -online option returns + only those accounts which are online. + + The @c protocol subcommand returns the protocol ID (e.g. "prpl-msn") + for the given account. + + The @c username subcommand returns the username for the account + @c account. + +@code +gaim::buddy alias buddy +gaim::buddy handle +gaim::buddy info ( buddy | account username ) +gaim::buddy list +@endcode + + @c gaim::buddy is a set of commands for retrieving information about + buddies and manipulating the buddy list. For the purposes of Tcl, + a "buddy" is currently a list of several elements, the first of + which being the type. The currently recognized types are "group", + "buddy", and "chat". A group node looks like: +@code + { group name { buddies } } +@endcode + A buddy node is: +@code + { buddy name account } +@endcode + And a chat node is: +@code + { chat alias account } +@endcode + + The @c alias subcommand returns the alias for the given buddy if it + exists, or the empty string if it does not. + + @c handle returns the blist handle for the purposes of connecting + signals to buddy list events. (See gaim::signal connect). + + @c info causes gaim to display the info dialog for the given buddy. + Since it is possible to request user info for a buddy not in your + buddy list, you may also specify a buddy by his or her username and + the account through which you wish to retrieve info. + + @c list returns a list of @c group structures, filled out with buddies + and chats as described above. + +@code +gaim::connection account gc +gaim::connection displayname gc +gaim::connection handle +gaim::connection list +@endcode + + @c gaim::connection is a collection of subcommands pertaining to + account connections. + + @c account returns the Gaim account associated with @c gc. This + account is the same account used by @c gaim::account and other + commands. + + @c displayname returns the display name (duh) of @c gc as reported by + gaim_connection_get_display_name(gc). + + @c handle returns the gaim connections instance handle. (See + gaim::signal connect). + + @c list returns a list of all known connections. The elements of + this list are appropriate as @c gc arguments to the other + @c gaim::connection subcommands or other commands requiring a gc. + +@code +gaim::conv_send account who text +@endcode + + @c gaim::conv is simply a convenience wrapper for @c gaim::send_im and + gaim::conversation write. It sends the IM, determines the from + and to arguments for gaim::conversation write, and prints the text + sent to the conversation as one would expect. For the curious, you + may view the source for it by typing info body gaim::conv_send at + a Gaim Commander prompt. + + Note that an error in either @c gaim::send_im or gaim::conversation + write will not be caught by this procedure, and will be propagated + to the caller. + +@code +gaim::conversation find ?-account account? name +gaim::conversation handle +gaim::conversation list +gaim::conversation new ?-chat? ?-im? account name +gaim::conversation write conversation style from to text +@endcode + + @c gaim::conversation provides an API for dealing with conversations. + Given that Gaim is an instant messenger program, you'll probably + spend a lot of time here. + + The command @c find attempts to find an existing conversation with + username @c name. If the @c -account option is given, it refines its + search to include only conversations on that account. + + @c handle returns the conversations instance handle for the purposes + of signal connection. (See gaim::signal connect). + + @c list returns a list of all currently open conversations. + + The @c new subcommand can be used to create a new conversation with + a specified user on a specified account if one does not exist, or + retrieve the existing conversation if it does. The @c -chat and + @c -im options specify whether the created conversation should be a + chat or a standard IM, respectively. + + @c write is used to write to the specified conversation. The @c style + argument specifies how the text should be printed -- as text coming + from the gaim user (style @c send), being sent to the gaim user + (style @c recv), or as a system message (such as "so-and-so has + signed off", style @c system). From is the name to whom the text + should be attributed -- you probably want to check for aliases here, + lest you confuse the user. @c text is the text to print. + +@code +gaim::core handle +gaim::core quit +@endcode + + This command exposes functionality provided by the gaim core API. + + gaim::core handle returns a handle to the gaim core for signal + connection. (See gaim::signal connect). + + @c quit exits gaim cleanly, and should be used in preference to the + tcl @c exit command. (Note that @c exit has not been removed, + however.) + +@code +gaim::debug level category message +@endcode + + Equivalent to the C gaim_debug function, this command outputs + debugging information to the gaim debug window (or stdout if gaim is + invoked with -d|--debug). The valid levels are, in increasing level + of severity, @c -misc, @c -info, @c -warning, and, or @c -error. @c + category is a short (a few characters ... for instance, "tcl" or "tcl + plugin") "topic" type name for this message, and @c message is the text + of the message. In the style of Tcl @e puts (and differing from + @e gaim_debug), no trailing \\n is required. (However, embedded newlines + may be generated with \\n). + +@code +gaim::notify ?type? title primary secondary +@endcode + + Also a direct equivalent to a C function, gaim_notify, this command + causes gaim to present the provided notification information to the + user via some appropriate UI method. The @c type argument, if + present, must be one of @c -error, @c -warning, or @c -info. The following + three arguments' absolute meanings may vary with the Gaim UI being + used (presently only a Gtk2 UI is available), but @c title should + generally be the title of the window, and @c primary and @c secondary + text within that window; in the Gtk2 UI, @c primary is slightly + larger than @c secondary and displayed in a @b boldface font. + +@code +gaim::send_im gc who text +@endcode + + This sends an IM in the fashion of serv_send_im. @c gc is the GC of + the connection on which you wish to send (as returned by most event + handlers), @c who is the nick of the buddy to which you wish to send, + and @c text is the text of the message. + +@code +gaim::signal connect instance signal args proc +gaim::signal disconnect instance signal +@endcode + + @c gaim::signal is a set of subcommands for dealing with gaim signals + (known as "events" prior to gaim 0.68). + + The @c connect subcommand registers the procedure @c proc as a handler + for the signal @c signal on the instance @c instance. @c instance + should be an instance handle as returned by one of the @c handle + commands from the various parts of gaim. @c args and @ proc are as in + the Tcl @e proc command; note that the number of arguments in @c args + must match the number of arguments emitted by the signal exactly, + although you need not use them all. The procedure @c proc may be + either a simple command or a procedure in curly brackets. Note that + only one procedure may be associated with each signal; an attempt to + connect a second procedure to the same signal will remove the + existing binding and replace it with the new procedure. + gaim::signal connect returns 0 on success and 1 on failure. + + @c disconnect removes any existing signal handler for the named + signal and instance. + +@code +gaim::unload +@endcode + + This unloads the current plugin. Note that preferences will not be + updated (yet). + +@section Signals + +Check the signals documentation for the meaning of these signals; this is +intended to be a list only of their arguments. Signal callbacks will +be made in their own namespace, and arguments to those signal +callbacks will live in the namespace @c event underneath that +namespace. To briefly illustrate, the signal @c receiving-im-msg is +provided with three arguments; the account on which the IM was +received, the screen name of the user sending the IM, and the text of +the IM. These arguments live in the variables @c event::account, +@c event::sender, and @c event::buffer, respectively. Therefore a callback +which notifies the user of an incoming IM containing the word 'shizzle' +might look like this: + +@code +gaim::signal connect [gaim::conversation handle] receiving-im-msg { + if {[ string match "*shizzle*" $event::buffer ]} { + gaim::notify -info "tcl plugin" "Fo' shizzle" \ + "$event::sender is down with the shizzle" + } +} +@endcode + +Note that for some signals (notably @c receiving-im-msg, @c sending-im-msg, +and their chat counterparts), changes to the event arguments will +change the message itself from Gaim's vantage. For those signals +whose return value is meaningful, returning a value from the Tcl event + +*/ + +// vim: syntax=c tw=75 et diff -r f53c59c95f03 -r 68d6065fc32f plugins/tcl/TCL-HOWTO --- a/plugins/tcl/TCL-HOWTO Fri Dec 24 02:29:24 2004 +0000 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,317 +0,0 @@ -Gaim Tcl plugin-writing HOWTO - -INTRODUCTION - -The Gaim Tcl interface provides a Tcl API for many useful gaim -functions. Like the perl API, the Tcl API does not provide access to -every corner of gaim exposed by the C interface. It does, however, -provide a very powerful interface to many of Gaim's functions through -a simple to learn and extend scripting language. - -If you are not familiar with Tcl, you will probably find it somewhat -different from what you are used to. Despite being somewhat unique -(more akin to shell programming than other traditional scripting -languages such as perl or python), it is simple to learn for beginners -and experienced programmers alike. There are numerous books on the -subject, we will not discuss it any further here. - -GETTING STARTED - -The only requirement placed on a Gaim Tcl script by Gaim is the -existence of a procedure called 'plugin_init'. This procedure has -some limitations placed upon it; it will be parsed and evaluated -before the rest of the Tcl script, so it cannot reference any other -variables or procedures declared in the script. In practice this is -not a problem, as the only thing this procedure should do is return a -simple list containing five items: the name of the script, its version -number, a summary (just a few words) of its function, a short (longer -than the summary, but no more than a couple of sentences if possible) -description, the author, and a web page. For example: - -proc plugin_init { } { - return [ list "Example Plugin" \ - "1.0" \ - "Example plugin registration" \ - "Example of how to register a plugin for the Tcl HOWTO" \ - "Ethan Blanton " \ - "http://gaim.sf.net/" ] -} - -The rest of the script will generally be registration to recieve -notification of various Gaim signals (more about this below) and -definitions of procedures to be executed when those signals occur. - -INTERPRETER DETAILS - -Gaim initializes and drives the Tcl event loop (similar to Tk), -meaning that commands like fileevent and after are available and -do not require 'vwait' etc. 'vwait' actually seems to be somewhat -broken due to a bug somewhere in the Tcl/Glib event loop glue, and it -should not be used for now. - -The gaim-specific functions are provided in a statically-linked -package called 'gaim'; this means that if you spawn a child -interpreter and wish to use the gaim-specific functions, you will need -to execute 'load {} gaim' in that interpreter. - -GAIM INTERNAL PROCEDURES AND VARIABLES - -All of the information provided for your use by Gaim will be in the -::gaim namespace. This means that in order to access it you will -either have to import the gaim namespace (e.g. via the command -'namespace import gaim::*') or reference it explicitly. The following -descriptions will reference it explicitly for clarity. - -* Variables - -gaim::version - - This contains the version of the gaim process which loaded the - script. - -* Commands - -gaim::account alias account -gaim::account connect account -gaim::account connection account -gaim::account disconnect account -gaim::account find username protocol -gaim::account handle -gaim::account isconnected account -gaim::account list ?option? -gaim::account protocol account -gaim::account username account - - The 'gaim::account' command consists of a set of subcommands - pertaining to gaim accounts. - - 'alias' returns the alias for the account 'account'. If there is no - alias for the given account, it returns the empty string. - - The subcommand 'connect' connects the named account if it is not - connected, and does nothing if it is. In either case, it returns - the gc for the account. - - 'connection' returns the gc of the given account if it is connected, - or 0 if it is not. This gc is the gc used by gaim::connection and - other functions. - - 'disconnect' disconnects the given account if it is connected, or - does nothing if it is. - - 'find' finds an account by its username and protocol (as returned by - 'gaim::account username' and 'gaim::account protocol') and returns - the account if found, or 0 otherwise. - - 'handle' returns the instance handle required to connect to account - signals. (See 'gaim::signal connect'). - - The 'isconnected' query returns true if the given account is - connected and false otherwise. - - The 'list' subcommand returns a list of all of the accounts known to - Gaim. The elements of this lists are accounts appropriate for the - 'account' argument of the other subcommands. The '-all' option - (default) returns all accounts, while the '-online' option returns - only those accounts which are online. - - The 'protocol' subcommand returns the protocol ID (e.g. "prpl-msn") - for the given account. - - The 'username' subcommand returns the username for the account - 'account'. - -gaim::buddy alias buddy -gaim::buddy handle -gaim::buddy info ( buddy | account username ) -gaim::buddy list - - 'gaim::buddy' is a set of commands for retrieving information about - buddies and manipulating the buddy list. For the purposes of Tcl, - a "buddy" is currently a list of several elements, the first of - which being the type. The currently recognized types are "group", - "buddy", and "chat". A group node looks like: - { group name { buddies } } - A buddy node is: - { buddy name account } - And a chat node is: - { chat alias account } - - The 'alias' subcommand returns the alias for the given buddy if it - exists, or the empty string if it does not. - - 'handle' returns the blist handle for the purposes of connecting - signals to buddy list events. (See 'gaim::signal connect'). - - 'info' causes gaim to display the info dialog for the given buddy. - Since it is possible to request user info for a buddy not in your - buddy list, you may also specify a buddy by his or her username and - the account through which you wish to retrieve info. - - 'list' returns a list of 'group' structures, filled out with buddies - and chats as described above. - -gaim::connection account gc -gaim::connection displayname gc -gaim::connection handle -gaim::connection list - - 'gaim::connection' is a collection of subcommands pertaining to - account connections. - - 'account' returns the Gaim account associated with 'gc'. This - account is the same account used by gaim::account and other - commands. - - 'displayname' returns the display name (duh) of 'gc' as reported by - gaim_connection_get_display_name(gc). - - 'handle' returns the gaim connections instance handle. (See - 'gaim::signal connect'). - - 'list' returns a list of all known connections. The elements of - this list are appropriate as 'gc' arguments to the other - gaim::connection subcommands or other commands requiring a gc. - - -gaim::conv_send account who text - - 'gaim::conv' is simply a convenience wrapper for 'gaim::send_im' and - 'gaim::conversation write'. It sends the IM, determines the from - and to arguments for 'gaim::conversation write', and prints the text - sent to the conversation as one would expect. For the curious, you - may view the source for it by typing 'info body gaim::conv_send' at - a Gaim Commander prompt. - - Note that an error in either gaim::send_im or 'gaim::conversation - write' will not be caught by this procedure, and will be propagated - to the caller. - -gaim::conversation find ?-account account? name -gaim::conversation handle -gaim::conversation list -gaim::conversation new ?-chat? ?-im? account name -gaim::conversation write conversation style from to text - - 'gaim::conversation' provides an API for dealing with conversations. - Given that Gaim is an instant messenger program, you'll probably - spend a lot of time here. - - The command 'find' attempts to find an existing conversation with - username 'name'. If the '-account' option is given, it refines its - search to include only conversations on that account. - - 'handle' returns the conversations instance handle for the purposes - of signal connection. (See 'gaim::signal connect'). - - 'list' returns a list of all currently open conversations. - - The 'new' subcommand can be used to create a new conversation with - a specified user on a specified account if one does not exist, or - retrieve the existing conversation if it does. The '-chat' and - '-im' options specify whether the created conversation should be a - chat or a standard IM, respectively. - - 'write' is used to write to the specified conversation. The 'style' - argument specifies how the text should be printed -- as text coming - from the gaim user (style 'send'), being sent to the gaim user - (style 'recv'), or as a system message (such as "so-and-so has - signed off", style 'system'). From is the name to whom the text - should be attributed -- you probably want to check for aliases here, - lest you confuse the user. 'text' is the text to print. - -gaim::core handle -gaim::core quit - - This command exposes functionality provided by the gaim core API. - - 'gaim::core handle' returns a handle to the gaim core for signal - connection. (See 'gaim::signal connect'). - - 'quit' exits gaim cleanly, and should be used in preference to the - tcl 'exit' command. (Note that 'exit' has not been removed, - however.) - -gaim::debug level category message - - Equivalent to the C gaim_debug function, this command outputs - debugging information to the gaim debug window (or stdout if gaim is - invoked with -n). The valid levels are, in increasing level of - severity, -misc, -info, -warning, and -error. 'category' is a short - (a few characters ... for instance, "tcl" or "tcl plugin") "topic" - type name for this message, and 'message' is the text of the - message. In the style of Tcl 'puts' (and differing from gaim_debug), - no trailing \n is required. (However, embedded newlines may be - generated with \n). - -gaim::notify ?type? title primary secondary - - Also a direct equivalent to a C function, gaim_notify, this command - causes gaim to present the provided notification information to the - user via some appropriate UI method. The 'type' argument, if - present, must be one of -error, -warning, or -info. The following - three arguments' absolute meanings may vary with the Gaim UI being - used (presently only a Gtk2 UI is available), but 'title' should - generally be the title of the window, and 'primary' and 'secondary' - text within that window; in the Gtk2 UI, 'primary' is slightly - larger than 'secondary' and displayed in a boldface font. - -gaim::send_im gc who text - - This sends an IM in the fashion of serv_send_im. 'gc' is the GC of - the connection on which you wish to send (as returned by most event - handlers), 'who' is the nick of the buddy to which you wish to send, - and 'text' is the text of the message. - -gaim::signal connect instance signal args proc -gaim::signal disconnect instance signal - - 'gaim::signal' is a set of subcommands for dealing with gaim signals - (known as "events" prior to gaim 0.68). - - The 'connect' subcommand registers the procedure 'proc' as a handler - for the signal 'signal' on the instance 'instance'. 'instance' - should be an instance handle as returned by one of the 'handle' - commands from the various parts of gaim. 'args' and 'proc' are as in - the Tcl 'proc' command; note that the number of arguments in 'args' - must match the number of arguments emitted by the signal exactly, - although you need not use them all. The procedure 'proc' may be - either a simple command or a procedure in curly brackets. Note that - only one procedure may be associated with each signal; an attempt to - connect a second procedure to the same signal will remove the - existing binding and replace it with the new procedure. - 'gaim::signal connect' returns 0 on success and 1 on failure. - - 'disconnect' removes any existing signal handler for the named - signal and instance. - -gaim::unload - - This unloads the current plugin. Note that preferences will not be - updated (yet). - -SIGNALS - -Check the file SIGNALS for the meaning of these signals; this is -intended to be a list only of their arguments. Signal callbacks will -be made in their own namespace, and arguments to those signal -callbacks will live in the namespace 'event' underneath that -namespace. To briefly illustrate, the signal receiving-im-msg is -provided with three arguments; the account on which the IM was -received, the screen name of the user sending the IM, and the text of -the IM. These arguments live in the variables event::account, -event::sender, and event::buffer, respectively. Therefore a callback -which notifies the user of an incoming IM containing the word 'shizzle' -might look like this: - -gaim::signal connect [gaim::conversation handle] receiving-im-msg { - if {[ string match "*shizzle*" $event::buffer ]} { - gaim::notify -info "tcl plugin" "Fo' shizzle" \ - "$event::sender is down with the shizzle" - } -} - -Note that for some signals (notably receiving-im-msg, sending-im-msg, -and their chat counterparts), changes to the event arguments will -change the message itself from Gaim's vantage. For those signals -whose return value is meaningful, returning a value from the Tcl event