Mercurial > pidgin
annotate doc/TCL-HOWTO.dox @ 31537:6ec53e134447
bonjour: Recurse through user IP addresses instead of using the first one only
This, among other things, makes interactivity with iChat more reliable because
iChat apparently advertises an IPv6 address, but doesn't listen on it.
Fixes #13773
committer: Daniel Atallah <daniel.atallah@gmail.com>
author | Simon van der Linden <simon@vanderlinden.eu.org> |
---|---|
date | Tue, 03 May 2011 16:12:36 +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 |