Mercurial > pidgin
annotate doc/TCL-HOWTO.dox @ 31806:49d6ee09c74d
Fix a leak found by HanzZ.
author | Elliott Sales de Andrade <qulogic@pidgin.im> |
---|---|
date | Wed, 17 Aug 2011 22:00:37 +0000 |
parents | e5ebf3abd9f8 |
children |
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 |
26626
e5ebf3abd9f8
Add the Tcl command purple::connection state (purple_connection_get_state).
Ethan Blanton <elb@pidgin.im>
parents:
25925
diff
changeset
|
176 purple::connection state |
10409 | 177 @endcode |
178 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
179 @c purple::connection is a collection of subcommands pertaining to |
10409 | 180 account connections. |
181 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
182 @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
|
183 account is the same account used by @c purple::account and other |
10409 | 184 commands. |
185 | |
186 @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
|
187 <tt>purple_connection_get_display_name(gc)</tt>. |
10409 | 188 |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
189 @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
|
190 <tt>purple::signal connect</tt>). |
10409 | 191 |
192 @c list returns a list of all known connections. The elements of | |
193 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
|
194 @c purple::connection subcommands or other commands requiring a gc. |
10409 | 195 |
26626
e5ebf3abd9f8
Add the Tcl command purple::connection state (purple_connection_get_state).
Ethan Blanton <elb@pidgin.im>
parents:
25925
diff
changeset
|
196 @c state returns the PurpleConnectionState of this account as one of |
e5ebf3abd9f8
Add the Tcl command purple::connection state (purple_connection_get_state).
Ethan Blanton <elb@pidgin.im>
parents:
25925
diff
changeset
|
197 the strings "connected", "disconnected", or "connecting". |
e5ebf3abd9f8
Add the Tcl command purple::connection state (purple_connection_get_state).
Ethan Blanton <elb@pidgin.im>
parents:
25925
diff
changeset
|
198 |
10409 | 199 @code |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
200 purple::conv_send account who text |
10409 | 201 @endcode |
202 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
203 @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
|
204 <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
|
205 and to arguments for <tt>purple::conversation write</tt>, and prints the text |
10409 | 206 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
|
207 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
|
208 a Purple Commander prompt. |
10409 | 209 |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
210 Note that an error in either @c purple::send_im or <tt>purple::conversation |
10409 | 211 write</tt> will not be caught by this procedure, and will be propagated |
212 to the caller. | |
213 | |
214 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
215 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
|
216 purple::conversation handle |
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
217 purple::conversation list |
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
218 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
|
219 purple::conversation write conversation style from to text |
10409 | 220 @endcode |
221 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
222 @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
|
223 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
|
224 programs, you'll probably spend a lot of time here. |
10409 | 225 |
226 The command @c find attempts to find an existing conversation with | |
227 username @c name. If the @c -account option is given, it refines its | |
228 search to include only conversations on that account. | |
229 | |
230 @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
|
231 of signal connection. (See <tt>purple::signal connect</tt>). |
10409 | 232 |
233 @c list returns a list of all currently open conversations. | |
234 | |
235 The @c new subcommand can be used to create a new conversation with | |
236 a specified user on a specified account if one does not exist, or | |
237 retrieve the existing conversation if it does. The @c -chat and | |
238 @c -im options specify whether the created conversation should be a | |
239 chat or a standard IM, respectively. | |
240 | |
241 @c write is used to write to the specified conversation. The @c style | |
242 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
|
243 from the purple user (style @c send), being sent to the purple user |
10409 | 244 (style @c recv), or as a system message (such as "so-and-so has |
245 signed off", style @c system). From is the name to whom the text | |
246 should be attributed -- you probably want to check for aliases here, | |
247 lest you confuse the user. @c text is the text to print. | |
248 | |
249 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
250 purple::core handle |
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
251 purple::core quit |
10409 | 252 @endcode |
253 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
254 This command exposes functionality provided by the purple core API. |
10409 | 255 |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
256 <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
|
257 connection. (See <tt>purple::signal connect</tt>). |
10409 | 258 |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
259 @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
|
260 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
|
261 been removed, however.) |
10409 | 262 |
263 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
264 purple::debug level category message |
10409 | 265 @endcode |
266 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
267 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
|
268 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
|
269 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
|
270 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
|
271 -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
|
272 ... 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
|
273 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
|
274 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
|
275 required. (However, embedded newlines may be generated with \\n). |
10409 | 276 |
277 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
278 purple::notify ?type? title primary secondary |
10409 | 279 @endcode |
280 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
281 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
|
282 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
|
283 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
|
284 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
|
285 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
|
286 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
|
287 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
|
288 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
|
289 displayed in a @b boldface font. |
10409 | 290 |
291 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
292 purple::send_im gc who text |
10409 | 293 @endcode |
294 | |
295 This sends an IM in the fashion of serv_send_im. @c gc is the GC of | |
296 the connection on which you wish to send (as returned by most event | |
297 handlers), @c who is the nick of the buddy to which you wish to send, | |
298 and @c text is the text of the message. | |
299 | |
300 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
301 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
|
302 purple::signal disconnect instance signal |
10409 | 303 @endcode |
304 | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
305 @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
|
306 signals. |
10409 | 307 |
308 The @c connect subcommand registers the procedure @c proc as a handler | |
309 for the signal @c signal on the instance @c instance. @c instance | |
310 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
|
311 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
|
312 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
|
313 args must match the number of arguments emitted by the signal exactly, |
10409 | 314 although you need not use them all. The procedure @c proc may be |
315 either a simple command or a procedure in curly brackets. Note that | |
316 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
|
317 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
|
318 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
|
319 connect</tt> returns 0 on success and 1 on failure. |
10409 | 320 |
321 @c disconnect removes any existing signal handler for the named | |
322 signal and instance. | |
323 | |
324 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
325 purple::unload |
10409 | 326 @endcode |
327 | |
328 This unloads the current plugin. Note that preferences will not be | |
329 updated (yet). | |
330 | |
331 @section Signals | |
332 | |
333 Check the signals documentation for the meaning of these signals; this is | |
334 intended to be a list only of their arguments. Signal callbacks will | |
335 be made in their own namespace, and arguments to those signal | |
336 callbacks will live in the namespace @c event underneath that | |
337 namespace. To briefly illustrate, the signal @c receiving-im-msg is | |
338 provided with three arguments; the account on which the IM was | |
25925
6e1967b0f90b
Change "screen name" to "username" or "buddy name" in a whole bunch of
Mark Doliner <mark@kingant.net>
parents:
24375
diff
changeset
|
339 received, the name of the buddy sending the IM, and the text of |
10409 | 340 the IM. These arguments live in the variables @c event::account, |
341 @c event::sender, and @c event::buffer, respectively. Therefore a callback | |
342 which notifies the user of an incoming IM containing the word 'shizzle' | |
343 might look like this: | |
344 | |
345 @code | |
24375
73e827a93ae9
Update the TCL-HOWTO to some more modern nomenclature
Ethan Blanton <elb@pidgin.im>
parents:
16196
diff
changeset
|
346 purple::signal connect [purple::conversation handle] receiving-im-msg { |
10409 | 347 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
|
348 purple::notify -info "tcl plugin" "Fo' shizzle" \ |
10409 | 349 "$event::sender is down with the shizzle" |
350 } | |
351 } | |
352 @endcode | |
353 | |
354 Note that for some signals (notably @c receiving-im-msg, @c sending-im-msg, | |
355 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
|
356 change the message itself from libpurple's vantage. For those signals |
10409 | 357 whose return value is meaningful, returning a value from the Tcl event |
10410 | 358 will return that value as it would in C. |
10409 | 359 |
360 */ | |
361 | |
10410 | 362 // vim: syntax=c tw=72 et |