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