10409
+ ��膩��鰹申鐃順�渇��膩��� 1 /** @page tcl-howto Tcl Scripting HOWTO
+ ��膩��鰹申鐃順�渇��膩��� 2
+ ��膩��鰹申鐃順�渇��膩��� 3 @section Intoduction
+ ��膩��鰹申鐃順�渇��膩��� 4
10597
+ ��膩��鰹申鐃順�渇��膩��� 5 NOTA BENE: This documentation is badly out of date for 2.x.
+ ��膩��鰹申鐃順�渇��膩��� 6
10409
+ ��膩��鰹申鐃順�渇��膩��� 7 The Gaim Tcl interface provides a Tcl API for many useful gaim
+ ��膩��鰹申鐃順�渇��膩��� 8 functions. Like the perl API, the Tcl API does not provide
+ ��膩��鰹申鐃順�渇��膩��� 9 access to every corner of gaim exposed by the @e C interface. It does,
+ ��膩��鰹申鐃順�渇��膩��� 10 however, provide a very powerful interface to many of Gaim's functions
+ ��膩��鰹申鐃順�渇��膩��� 11 through a simple to learn and extend scripting language.
+ ��膩��鰹申鐃順�渇��膩��� 12
+ ��膩��鰹申鐃順�渇��膩��� 13 If you are not familiar with Tcl, you will probably find it somewhat
+ ��膩��鰹申鐃順�渇��膩��� 14 different from what you are used to. Despite being somewhat unique
+ ��膩��鰹申鐃順�渇��膩��� 15 (more akin to shell programming than other traditional scripting
+ ��膩��鰹申鐃順�渇��膩��� 16 languages such as @e perl or @e python), it is simple to learn for
+ ��膩��鰹申鐃順�渇��膩��� 17 beginners and experienced programmers alike. There are numerous books
+ ��膩��鰹申鐃順�渇��膩��� 18 on the subject; we will not discuss it any further here.
+ ��膩��鰹申鐃順�渇��膩��� 19
+ ��膩��鰹申鐃順�渇��膩��� 20 @section start Getting Started
+ ��膩��鰹申鐃順�渇��膩��� 21
+ ��膩��鰹申鐃順�渇��膩��� 22 The only requirement placed on a Gaim Tcl script by Gaim is the
+ ��膩��鰹申鐃順�渇��膩��� 23 existence of a procedure called @c plugin_init. This procedure has
+ ��膩��鰹申鐃順�渇��膩��� 24 some limitations placed upon it; it will be parsed and evaluated before
+ ��膩��鰹申鐃順�渇��膩��� 25 the rest of the Tcl script, so it cannot reference any other variables
+ ��膩��鰹申鐃順�渇��膩��� 26 or procedures declared in the script. In practice this is not a
+ ��膩��鰹申鐃順�渇��膩��� 27 problem, as the only thing this procedure should do is return a simple
+ ��膩��鰹申鐃順�渇��膩��� 28 list containing five items: the @b name of the script, its @b version
+ ��膩��鰹申鐃順�渇��膩��� 29 number, a @b summary (just a few words) of its function, a short (longer
+ ��膩��鰹申鐃順�渇��膩��� 30 than the summary, but no more than a couple of sentences if possible)
+ ��膩��鰹申鐃順�渇��膩��� 31 @b description, the @b author, and a @b URL to web page. For example:
+ ��膩��鰹申鐃順�渇��膩��� 32
+ ��膩��鰹申鐃順�渇��膩��� 33 @code
+ ��膩��鰹申鐃順�渇��膩��� 34 proc plugin_init { } {
+ ��膩��鰹申鐃順�渇��膩��� 35 return [ list "Example Plugin" \
+ ��膩��鰹申鐃順�渇��膩��� 36 "1.0" \
+ ��膩��鰹申鐃順�渇��膩��� 37 "Example plugin registration" \
+ ��膩��鰹申鐃順�渇��膩��� 38 "Example of how to register a plugin for the Tcl HOWTO" \
+ ��膩��鰹申鐃順�渇��膩��� 39 "Ethan Blanton <eblanton@cs.purdue.edu>" \
+ ��膩��鰹申鐃順�渇��膩��� 40 "http://gaim.sf.net/" ]
+ ��膩��鰹申鐃順�渇��膩��� 41 }
+ ��膩��鰹申鐃順�渇��膩��� 42 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 43
+ ��膩��鰹申鐃順�渇��膩��� 44 The rest of the script will generally be registration to recieve
+ ��膩��鰹申鐃順�渇��膩��� 45 notification of various Gaim signals (more about this below) and
+ ��膩��鰹申鐃順�渇��膩��� 46 definitions of procedures to be executed when those signals occur.
+ ��膩��鰹申鐃順�渇��膩��� 47
+ ��膩��鰹申鐃順�渇��膩��� 48 @section details Interpreter Details
+ ��膩��鰹申鐃順�渇��膩��� 49
+ ��膩��鰹申鐃順�渇��膩��� 50 Gaim initializes and drives the Tcl event loop (similar to Tk),
+ ��膩��鰹申鐃順�渇��膩��� 51 meaning that commands like @c fileevent and @c after are available and
+ ��膩��鰹申鐃順�渇��膩��� 52 do not require @c vwait etc. The @c vwait actually seems to be somewhat
+ ��膩��鰹申鐃順�渇��膩��� 53 broken due to a bug somewhere in the Tcl/Glib event loop glue, and it
+ ��膩��鰹申鐃順�渇��膩��� 54 should not be used for now.
+ ��膩��鰹申鐃順�渇��膩��� 55
+ ��膩��鰹申鐃順�渇��膩��� 56 The gaim-specific functions are provided in a statically-linked
+ ��膩��鰹申鐃順�渇��膩��� 57 package called @c gaim; this means that if you spawn a child
+ ��膩��鰹申鐃順�渇��膩��� 58 interpreter and wish to use the gaim-specific functions, you will need
+ ��膩��鰹申鐃順�渇��膩��� 59 to execute <tt>load {} gaim</tt> in that interpreter.
+ ��膩��鰹申鐃順�渇��膩��� 60
+ ��膩��鰹申鐃順�渇��膩��� 61 @section internals Gaim Internal Procedures and Variables
+ ��膩��鰹申鐃順�渇��膩��� 62
+ ��膩��鰹申鐃順�渇��膩��� 63 All of the information provided for your use by Gaim will be in the @c
+ ��膩��鰹申鐃順�渇��膩��� 64 ::gaim namespace. This means that in order to access it you will either
+ ��膩��鰹申鐃順�渇��膩��� 65 have to import the gaim namespace (e.g. via the command <tt>namespace
+ ��膩��鰹申鐃順�渇��膩��� 66 import gaim::*</tt>) or reference it explicitly. The following
+ ��膩��鰹申鐃順�渇��膩��� 67 descriptions will reference it explicitly for clarity.
+ ��膩��鰹申鐃順�渇��膩��� 68
+ ��膩��鰹申鐃順�渇��膩��� 69 @li Variables
+ ��膩��鰹申鐃順�渇��膩��� 70
+ ��膩��鰹申鐃順�渇��膩��� 71 @code
+ ��膩��鰹申鐃順�渇��膩��� 72 gaim::version
+ ��膩��鰹申鐃順�渇��膩��� 73 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 74
+ ��膩��鰹申鐃順�渇��膩��� 75 This contains the version of the gaim process which loaded the
+ ��膩��鰹申鐃順�渇��膩��� 76 script.
+ ��膩��鰹申鐃順�渇��膩��� 77
+ ��膩��鰹申鐃順�渇��膩��� 78 @li Commands
+ ��膩��鰹申鐃順�渇��膩��� 79
+ ��膩��鰹申鐃順�渇��膩��� 80 @code
+ ��膩��鰹申鐃順�渇��膩��� 81 gaim::account alias account
+ ��膩��鰹申鐃順�渇��膩��� 82 gaim::account connect account
+ ��膩��鰹申鐃順�渇��膩��� 83 gaim::account connection account
+ ��膩��鰹申鐃順�渇��膩��� 84 gaim::account disconnect account
+ ��膩��鰹申鐃順�渇��膩��� 85 gaim::account find username protocol
+ ��膩��鰹申鐃順�渇��膩��� 86 gaim::account handle
+ ��膩��鰹申鐃順�渇��膩��� 87 gaim::account isconnected account
+ ��膩��鰹申鐃順�渇��膩��� 88 gaim::account list ?option?
+ ��膩��鰹申鐃順�渇��膩��� 89 gaim::account protocol account
+ ��膩��鰹申鐃順�渇��膩��� 90 gaim::account username account
+ ��膩��鰹申鐃順�渇��膩��� 91 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 92
+ ��膩��鰹申鐃順�渇��膩��� 93 The @c gaim::account command consists of a set of subcommands
+ ��膩��鰹申鐃順�渇��膩��� 94 pertaining to gaim accounts.
+ ��膩��鰹申鐃順�渇��膩��� 95
+ ��膩��鰹申鐃順�渇��膩��� 96 @c alias returns the alias for the account @c account. If there is no
+ ��膩��鰹申鐃順�渇��膩��� 97 alias for the given account, it returns the empty string.
+ ��膩��鰹申鐃順�渇��膩��� 98
+ ��膩��鰹申鐃順�渇��膩��� 99 The subcommand @c connect connects the named account if it is not
+ ��膩��鰹申鐃順�渇��膩��� 100 connected, and does nothing if it is. In either case, it returns
+ ��膩��鰹申鐃順�渇��膩��� 101 the @c gc for the account.
+ ��膩��鰹申鐃順�渇��膩��� 102
+ ��膩��鰹申鐃順�渇��膩��� 103 @c connection returns the @c gc of the given account if it is connected,
+ ��膩��鰹申鐃順�渇��膩��� 104 or 0 if it is not. This @c gc is the gc used by gaim::connection and
+ ��膩��鰹申鐃順�渇��膩��� 105 other functions.
+ ��膩��鰹申鐃順�渇��膩��� 106
+ ��膩��鰹申鐃順�渇��膩��� 107 @c disconnect disconnects the given @c account if it is connected, or
+ ��膩��鰹申鐃順�渇��膩��� 108 does nothing if it is.
+ ��膩��鰹申鐃順�渇��膩��� 109
+ ��膩��鰹申鐃順�渇��膩��� 110 @c find finds an account by its @c username and @c protocol (as returned by
+ ��膩��鰹申鐃順�渇��膩��� 111 <tt>gaim::account username</tt> and <tt>gaim::account protocol</tt>) and
+ ��膩��鰹申鐃順�渇��膩��� 112 returns the account if found, or 0 otherwise.
+ ��膩��鰹申鐃順�渇��膩��� 113
+ ��膩��鰹申鐃順�渇��膩��� 114 @c handle returns the instance handle required to connect to account
+ ��膩��鰹申鐃順�渇��膩��� 115 signals. (See <tt>gaim::signal connect</tt>).
+ ��膩��鰹申鐃順�渇��膩��� 116
+ ��膩��鰹申鐃順�渇��膩��� 117 The @c isconnected query returns true if the given account is
+ ��膩��鰹申鐃順�渇��膩��� 118 connected and false otherwise.
+ ��膩��鰹申鐃順�渇��膩��� 119
+ ��膩��鰹申鐃順�渇��膩��� 120 The @c list subcommand returns a list of all of the accounts known to
+ ��膩��鰹申鐃順�渇��膩��� 121 Gaim. The elements of this lists are accounts appropriate for the
+ ��膩��鰹申鐃順�渇��膩��� 122 @c account argument of the other subcommands. The @c -all option
+ ��膩��鰹申鐃順�渇��膩��� 123 (default) returns all accounts, while the @c -online option returns
+ ��膩��鰹申鐃順�渇��膩��� 124 only those accounts which are online.
+ ��膩��鰹申鐃順�渇��膩��� 125
+ ��膩��鰹申鐃順�渇��膩��� 126 The @c protocol subcommand returns the protocol ID (e.g. "prpl-msn")
+ ��膩��鰹申鐃順�渇��膩��� 127 for the given account.
+ ��膩��鰹申鐃順�渇��膩��� 128
+ ��膩��鰹申鐃順�渇��膩��� 129 The @c username subcommand returns the username for the account
+ ��膩��鰹申鐃順�渇��膩��� 130 @c account.
+ ��膩��鰹申鐃順�渇��膩��� 131
+ ��膩��鰹申鐃順�渇��膩��� 132 @code
+ ��膩��鰹申鐃順�渇��膩��� 133 gaim::buddy alias buddy
+ ��膩��鰹申鐃順�渇��膩��� 134 gaim::buddy handle
+ ��膩��鰹申鐃順�渇��膩��� 135 gaim::buddy info ( buddy | account username )
+ ��膩��鰹申鐃順�渇��膩��� 136 gaim::buddy list
+ ��膩��鰹申鐃順�渇��膩��� 137 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 138
+ ��膩��鰹申鐃順�渇��膩��� 139 @c gaim::buddy is a set of commands for retrieving information about
+ ��膩��鰹申鐃順�渇��膩��� 140 buddies and manipulating the buddy list. For the purposes of Tcl,
+ ��膩��鰹申鐃順�渇��膩��� 141 a "buddy" is currently a list of several elements, the first of
+ ��膩��鰹申鐃順�渇��膩��� 142 which being the type. The currently recognized types are "group",
+ ��膩��鰹申鐃順�渇��膩��� 143 "buddy", and "chat". A group node looks like:
+ ��膩��鰹申鐃順�渇��膩��� 144 @code
+ ��膩��鰹申鐃順�渇��膩��� 145 { group name { buddies } }
+ ��膩��鰹申鐃順�渇��膩��� 146 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 147 A buddy node is:
+ ��膩��鰹申鐃順�渇��膩��� 148 @code
+ ��膩��鰹申鐃順�渇��膩��� 149 { buddy name account }
+ ��膩��鰹申鐃順�渇��膩��� 150 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 151 And a chat node is:
+ ��膩��鰹申鐃順�渇��膩��� 152 @code
+ ��膩��鰹申鐃順�渇��膩��� 153 { chat alias account }
+ ��膩��鰹申鐃順�渇��膩��� 154 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 155
+ ��膩��鰹申鐃順�渇��膩��� 156 The @c alias subcommand returns the alias for the given buddy if it
+ ��膩��鰹申鐃順�渇��膩��� 157 exists, or the empty string if it does not.
+ ��膩��鰹申鐃順�渇��膩��� 158
+ ��膩��鰹申鐃順�渇��膩��� 159 @c handle returns the blist handle for the purposes of connecting
+ ��膩��鰹申鐃順�渇��膩��� 160 signals to buddy list events. (See <tt>gaim::signal connect</tt>).
+ ��膩��鰹申鐃順�渇��膩��� 161
+ ��膩��鰹申鐃順�渇��膩��� 162 @c info causes gaim to display the info dialog for the given buddy.
+ ��膩��鰹申鐃順�渇��膩��� 163 Since it is possible to request user info for a buddy not in your
+ ��膩��鰹申鐃順�渇��膩��� 164 buddy list, you may also specify a buddy by his or her username and
+ ��膩��鰹申鐃順�渇��膩��� 165 the account through which you wish to retrieve info.
+ ��膩��鰹申鐃順�渇��膩��� 166
+ ��膩��鰹申鐃順�渇��膩��� 167 @c list returns a list of @c group structures, filled out with buddies
+ ��膩��鰹申鐃順�渇��膩��� 168 and chats as described above.
+ ��膩��鰹申鐃順�渇��膩��� 169
+ ��膩��鰹申鐃順�渇��膩��� 170 @code
+ ��膩��鰹申鐃順�渇��膩��� 171 gaim::connection account gc
+ ��膩��鰹申鐃順�渇��膩��� 172 gaim::connection displayname gc
+ ��膩��鰹申鐃順�渇��膩��� 173 gaim::connection handle
+ ��膩��鰹申鐃順�渇��膩��� 174 gaim::connection list
+ ��膩��鰹申鐃順�渇��膩��� 175 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 176
+ ��膩��鰹申鐃順�渇��膩��� 177 @c gaim::connection is a collection of subcommands pertaining to
+ ��膩��鰹申鐃順�渇��膩��� 178 account connections.
+ ��膩��鰹申鐃順�渇��膩��� 179
+ ��膩��鰹申鐃順�渇��膩��� 180 @c account returns the Gaim account associated with @c gc. This
+ ��膩��鰹申鐃順�渇��膩��� 181 account is the same account used by @c gaim::account and other
+ ��膩��鰹申鐃順�渇��膩��� 182 commands.
+ ��膩��鰹申鐃順�渇��膩��� 183
+ ��膩��鰹申鐃順�渇��膩��� 184 @c displayname returns the display name (duh) of @c gc as reported by
+ ��膩��鰹申鐃順�渇��膩��� 185 <tt>gaim_connection_get_display_name(gc)</tt>.
+ ��膩��鰹申鐃順�渇��膩��� 186
+ ��膩��鰹申鐃順�渇��膩��� 187 @c handle returns the gaim connections instance handle. (See
+ ��膩��鰹申鐃順�渇��膩��� 188 <tt>gaim::signal connect</tt>).
+ ��膩��鰹申鐃順�渇��膩��� 189
+ ��膩��鰹申鐃順�渇��膩��� 190 @c list returns a list of all known connections. The elements of
+ ��膩��鰹申鐃順�渇��膩��� 191 this list are appropriate as @c gc arguments to the other
+ ��膩��鰹申鐃順�渇��膩��� 192 @c gaim::connection subcommands or other commands requiring a gc.
+ ��膩��鰹申鐃順�渇��膩��� 193
+ ��膩��鰹申鐃順�渇��膩��� 194 @code
+ ��膩��鰹申鐃順�渇��膩��� 195 gaim::conv_send account who text
+ ��膩��鰹申鐃順�渇��膩��� 196 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 197
+ ��膩��鰹申鐃順�渇��膩��� 198 @c gaim::conv is simply a convenience wrapper for @c gaim::send_im and
+ ��膩��鰹申鐃順�渇��膩��� 199 <tt>gaim::conversation write</tt>. It sends the IM, determines the from
+ ��膩��鰹申鐃順�渇��膩��� 200 and to arguments for <tt>gaim::conversation write</tt>, and prints the text
+ ��膩��鰹申鐃順�渇��膩��� 201 sent to the conversation as one would expect. For the curious, you
+ ��膩��鰹申鐃順�渇��膩��� 202 may view the source for it by typing <tt>info body gaim::conv_send</tt> at
+ ��膩��鰹申鐃順�渇��膩��� 203 a Gaim Commander prompt.
+ ��膩��鰹申鐃順�渇��膩��� 204
+ ��膩��鰹申鐃順�渇��膩��� 205 Note that an error in either @c gaim::send_im or <tt>gaim::conversation
+ ��膩��鰹申鐃順�渇��膩��� 206 write</tt> will not be caught by this procedure, and will be propagated
+ ��膩��鰹申鐃順�渇��膩��� 207 to the caller.
+ ��膩��鰹申鐃順�渇��膩��� 208
+ ��膩��鰹申鐃順�渇��膩��� 209 @code
+ ��膩��鰹申鐃順�渇��膩��� 210 gaim::conversation find ?-account account? name
+ ��膩��鰹申鐃順�渇��膩��� 211 gaim::conversation handle
+ ��膩��鰹申鐃順�渇��膩��� 212 gaim::conversation list
+ ��膩��鰹申鐃順�渇��膩��� 213 gaim::conversation new ?-chat? ?-im? account name
+ ��膩��鰹申鐃順�渇��膩��� 214 gaim::conversation write conversation style from to text
+ ��膩��鰹申鐃順�渇��膩��� 215 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 216
+ ��膩��鰹申鐃順�渇��膩��� 217 @c gaim::conversation provides an API for dealing with conversations.
+ ��膩��鰹申鐃順�渇��膩��� 218 Given that Gaim is an instant messenger program, you'll probably
+ ��膩��鰹申鐃順�渇��膩��� 219 spend a lot of time here.
+ ��膩��鰹申鐃順�渇��膩��� 220
+ ��膩��鰹申鐃順�渇��膩��� 221 The command @c find attempts to find an existing conversation with
+ ��膩��鰹申鐃順�渇��膩��� 222 username @c name. If the @c -account option is given, it refines its
+ ��膩��鰹申鐃順�渇��膩��� 223 search to include only conversations on that account.
+ ��膩��鰹申鐃順�渇��膩��� 224
+ ��膩��鰹申鐃順�渇��膩��� 225 @c handle returns the conversations instance handle for the purposes
+ ��膩��鰹申鐃順�渇��膩��� 226 of signal connection. (See <tt>gaim::signal connect</tt>).
+ ��膩��鰹申鐃順�渇��膩��� 227
+ ��膩��鰹申鐃順�渇��膩��� 228 @c list returns a list of all currently open conversations.
+ ��膩��鰹申鐃順�渇��膩��� 229
+ ��膩��鰹申鐃順�渇��膩��� 230 The @c new subcommand can be used to create a new conversation with
+ ��膩��鰹申鐃順�渇��膩��� 231 a specified user on a specified account if one does not exist, or
+ ��膩��鰹申鐃順�渇��膩��� 232 retrieve the existing conversation if it does. The @c -chat and
+ ��膩��鰹申鐃順�渇��膩��� 233 @c -im options specify whether the created conversation should be a
+ ��膩��鰹申鐃順�渇��膩��� 234 chat or a standard IM, respectively.
+ ��膩��鰹申鐃順�渇��膩��� 235
+ ��膩��鰹申鐃順�渇��膩��� 236 @c write is used to write to the specified conversation. The @c style
+ ��膩��鰹申鐃順�渇��膩��� 237 argument specifies how the text should be printed -- as text coming
+ ��膩��鰹申鐃順�渇��膩��� 238 from the gaim user (style @c send), being sent to the gaim user
+ ��膩��鰹申鐃順�渇��膩��� 239 (style @c recv), or as a system message (such as "so-and-so has
+ ��膩��鰹申鐃順�渇��膩��� 240 signed off", style @c system). From is the name to whom the text
+ ��膩��鰹申鐃順�渇��膩��� 241 should be attributed -- you probably want to check for aliases here,
+ ��膩��鰹申鐃順�渇��膩��� 242 lest you confuse the user. @c text is the text to print.
+ ��膩��鰹申鐃順�渇��膩��� 243
+ ��膩��鰹申鐃順�渇��膩��� 244 @code
+ ��膩��鰹申鐃順�渇��膩��� 245 gaim::core handle
+ ��膩��鰹申鐃順�渇��膩��� 246 gaim::core quit
+ ��膩��鰹申鐃順�渇��膩��� 247 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 248
+ ��膩��鰹申鐃順�渇��膩��� 249 This command exposes functionality provided by the gaim core API.
+ ��膩��鰹申鐃順�渇��膩��� 250
+ ��膩��鰹申鐃順�渇��膩��� 251 <tt>gaim::core handle</tt> returns a handle to the gaim core for signal
+ ��膩��鰹申鐃順�渇��膩��� 252 connection. (See <tt>gaim::signal connect</tt>).
+ ��膩��鰹申鐃順�渇��膩��� 253
+ ��膩��鰹申鐃順�渇��膩��� 254 @c quit exits gaim cleanly, and should be used in preference to the
+ ��膩��鰹申鐃順�渇��膩��� 255 tcl @c exit command. (Note that @c exit has not been removed,
+ ��膩��鰹申鐃順�渇��膩��� 256 however.)
+ ��膩��鰹申鐃順�渇��膩��� 257
+ ��膩��鰹申鐃順�渇��膩��� 258 @code
+ ��膩��鰹申鐃順�渇��膩��� 259 gaim::debug level category message
+ ��膩��鰹申鐃順�渇��膩��� 260 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 261
+ ��膩��鰹申鐃順�渇��膩��� 262 Equivalent to the C gaim_debug function, this command outputs
+ ��膩��鰹申鐃順�渇��膩��� 263 debugging information to the gaim debug window (or stdout if gaim is
+ ��膩��鰹申鐃順�渇��膩��� 264 invoked with -d|--debug). The valid levels are, in increasing level
+ ��膩��鰹申鐃順�渇��膩��� 265 of severity, @c -misc, @c -info, @c -warning, and, or @c -error. @c
+ ��膩��鰹申鐃順�渇��膩��� 266 category is a short (a few characters ... for instance, "tcl" or "tcl
+ ��膩��鰹申鐃順�渇��膩��� 267 plugin") "topic" type name for this message, and @c message is the text
+ ��膩��鰹申鐃順�渇��膩��� 268 of the message. In the style of Tcl @e puts (and differing from
+ ��膩��鰹申鐃順�渇��膩��� 269 @e gaim_debug), no trailing \\n is required. (However, embedded newlines
+ ��膩��鰹申鐃順�渇��膩��� 270 may be generated with \\n).
+ ��膩��鰹申鐃順�渇��膩��� 271
+ ��膩��鰹申鐃順�渇��膩��� 272 @code
+ ��膩��鰹申鐃順�渇��膩��� 273 gaim::notify ?type? title primary secondary
+ ��膩��鰹申鐃順�渇��膩��� 274 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 275
+ ��膩��鰹申鐃順�渇��膩��� 276 Also a direct equivalent to a C function, gaim_notify, this command
+ ��膩��鰹申鐃順�渇��膩��� 277 causes gaim to present the provided notification information to the
+ ��膩��鰹申鐃順�渇��膩��� 278 user via some appropriate UI method. The @c type argument, if
+ ��膩��鰹申鐃順�渇��膩��� 279 present, must be one of @c -error, @c -warning, or @c -info. The following
+ ��膩��鰹申鐃順�渇��膩��� 280 three arguments' absolute meanings may vary with the Gaim UI being
+ ��膩��鰹申鐃順�渇��膩��� 281 used (presently only a Gtk2 UI is available), but @c title should
+ ��膩��鰹申鐃順�渇��膩��� 282 generally be the title of the window, and @c primary and @c secondary
+ ��膩��鰹申鐃順�渇��膩��� 283 text within that window; in the Gtk2 UI, @c primary is slightly
+ ��膩��鰹申鐃順�渇��膩��� 284 larger than @c secondary and displayed in a @b boldface font.
+ ��膩��鰹申鐃順�渇��膩��� 285
+ ��膩��鰹申鐃順�渇��膩��� 286 @code
+ ��膩��鰹申鐃順�渇��膩��� 287 gaim::send_im gc who text
+ ��膩��鰹申鐃順�渇��膩��� 288 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 289
+ ��膩��鰹申鐃順�渇��膩��� 290 This sends an IM in the fashion of serv_send_im. @c gc is the GC of
+ ��膩��鰹申鐃順�渇��膩��� 291 the connection on which you wish to send (as returned by most event
+ ��膩��鰹申鐃順�渇��膩��� 292 handlers), @c who is the nick of the buddy to which you wish to send,
+ ��膩��鰹申鐃順�渇��膩��� 293 and @c text is the text of the message.
+ ��膩��鰹申鐃順�渇��膩��� 294
+ ��膩��鰹申鐃順�渇��膩��� 295 @code
+ ��膩��鰹申鐃順�渇��膩��� 296 gaim::signal connect instance signal args proc
+ ��膩��鰹申鐃順�渇��膩��� 297 gaim::signal disconnect instance signal
+ ��膩��鰹申鐃順�渇��膩��� 298 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 299
+ ��膩��鰹申鐃順�渇��膩��� 300 @c gaim::signal is a set of subcommands for dealing with gaim signals
+ ��膩��鰹申鐃順�渇��膩��� 301 (known as "events" prior to gaim 0.68).
+ ��膩��鰹申鐃順�渇��膩��� 302
+ ��膩��鰹申鐃順�渇��膩��� 303 The @c connect subcommand registers the procedure @c proc as a handler
+ ��膩��鰹申鐃順�渇��膩��� 304 for the signal @c signal on the instance @c instance. @c instance
+ ��膩��鰹申鐃順�渇��膩��� 305 should be an instance handle as returned by one of the @c handle
+ ��膩��鰹申鐃順�渇��膩��� 306 commands from the various parts of gaim. @c args and @ proc are as in
+ ��膩��鰹申鐃順�渇��膩��� 307 the Tcl @e proc command; note that the number of arguments in @c args
+ ��膩��鰹申鐃順�渇��膩��� 308 must match the number of arguments emitted by the signal exactly,
+ ��膩��鰹申鐃順�渇��膩��� 309 although you need not use them all. The procedure @c proc may be
+ ��膩��鰹申鐃順�渇��膩��� 310 either a simple command or a procedure in curly brackets. Note that
+ ��膩��鰹申鐃順�渇��膩��� 311 only one procedure may be associated with each signal; an attempt to
+ ��膩��鰹申鐃順�渇��膩��� 312 connect a second procedure to the same signal will remove the
+ ��膩��鰹申鐃順�渇��膩��� 313 existing binding and replace it with the new procedure.
+ ��膩��鰹申鐃順�渇��膩��� 314 <tt>gaim::signal connect</tt> returns 0 on success and 1 on failure.
+ ��膩��鰹申鐃順�渇��膩��� 315
+ ��膩��鰹申鐃順�渇��膩��� 316 @c disconnect removes any existing signal handler for the named
+ ��膩��鰹申鐃順�渇��膩��� 317 signal and instance.
+ ��膩��鰹申鐃順�渇��膩��� 318
+ ��膩��鰹申鐃順�渇��膩��� 319 @code
+ ��膩��鰹申鐃順�渇��膩��� 320 gaim::unload
+ ��膩��鰹申鐃順�渇��膩��� 321 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 322
+ ��膩��鰹申鐃順�渇��膩��� 323 This unloads the current plugin. Note that preferences will not be
+ ��膩��鰹申鐃順�渇��膩��� 324 updated (yet).
+ ��膩��鰹申鐃順�渇��膩��� 325
+ ��膩��鰹申鐃順�渇��膩��� 326 @section Signals
+ ��膩��鰹申鐃順�渇��膩��� 327
+ ��膩��鰹申鐃順�渇��膩��� 328 Check the signals documentation for the meaning of these signals; this is
+ ��膩��鰹申鐃順�渇��膩��� 329 intended to be a list only of their arguments. Signal callbacks will
+ ��膩��鰹申鐃順�渇��膩��� 330 be made in their own namespace, and arguments to those signal
+ ��膩��鰹申鐃順�渇��膩��� 331 callbacks will live in the namespace @c event underneath that
+ ��膩��鰹申鐃順�渇��膩��� 332 namespace. To briefly illustrate, the signal @c receiving-im-msg is
+ ��膩��鰹申鐃順�渇��膩��� 333 provided with three arguments; the account on which the IM was
+ ��膩��鰹申鐃順�渇��膩��� 334 received, the screen name of the user sending the IM, and the text of
+ ��膩��鰹申鐃順�渇��膩��� 335 the IM. These arguments live in the variables @c event::account,
+ ��膩��鰹申鐃順�渇��膩��� 336 @c event::sender, and @c event::buffer, respectively. Therefore a callback
+ ��膩��鰹申鐃順�渇��膩��� 337 which notifies the user of an incoming IM containing the word 'shizzle'
+ ��膩��鰹申鐃順�渇��膩��� 338 might look like this:
+ ��膩��鰹申鐃順�渇��膩��� 339
+ ��膩��鰹申鐃順�渇��膩��� 340 @code
+ ��膩��鰹申鐃順�渇��膩��� 341 gaim::signal connect [gaim::conversation handle] receiving-im-msg {
+ ��膩��鰹申鐃順�渇��膩��� 342 if {[ string match "*shizzle*" $event::buffer ]} {
+ ��膩��鰹申鐃順�渇��膩��� 343 gaim::notify -info "tcl plugin" "Fo' shizzle" \
+ ��膩��鰹申鐃順�渇��膩��� 344 "$event::sender is down with the shizzle"
+ ��膩��鰹申鐃順�渇��膩��� 345 }
+ ��膩��鰹申鐃順�渇��膩��� 346 }
+ ��膩��鰹申鐃順�渇��膩��� 347 @endcode
+ ��膩��鰹申鐃順�渇��膩��� 348
+ ��膩��鰹申鐃順�渇��膩��� 349 Note that for some signals (notably @c receiving-im-msg, @c sending-im-msg,
+ ��膩��鰹申鐃順�渇��膩��� 350 and their chat counterparts), changes to the event arguments will
+ ��膩��鰹申鐃順�渇��膩��� 351 change the message itself from Gaim's vantage. For those signals
+ ��膩��鰹申鐃順�渇��膩��� 352 whose return value is meaningful, returning a value from the Tcl event
10410
+ ��膩��鰹申鐃順�渇��膩��� 353 will return that value as it would in C.
10409
+ ��膩��鰹申鐃順�渇��膩��� 354
+ ��膩��鰹申鐃順�渇��膩��� 355 */
+ ��膩��鰹申鐃順�渇��膩��� 356
10410
+ ��膩��鰹申鐃順�渇��膩��� 357 // vim: syntax=c tw=72 et