Mercurial > pidgin.yaz
annotate doc/TCL-HOWTO.dox @ 26262:b03430dae08e
Add xmlnode_set_attrib_full that enables you to set an attribute with both
a prefix and a namespace. Also, change xmlnode_remove_attribute to remove
all existing attributes that match the name. Otherwise, it would just take
out the first one, and may not do what you want.
Change Bonjour and XMPP to use the new function.
References #7681.
Fixes #8318.
author | Elliott Sales de Andrade <qulogic@pidgin.im> |
---|---|
date | Fri, 13 Mar 2009 04:29:11 +0000 |
parents | 6e1967b0f90b |
children | e5ebf3abd9f8 |
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 |
24318
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 |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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, | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 |
24318
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 |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 |
24318
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 |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
24318
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 | |
25416
6e1967b0f90b
Change "screen name" to "username" or "buddy name" in a whole bunch of
Mark Doliner <mark@kingant.net>
parents:
24318
diff
changeset
|
335 received, the name of the buddy sending the IM, and the text of |
10409 | 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 | |
24318
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 ]} { |
24318
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 | |
24318
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 |