annotate doc/TCL-HOWTO.dox @ 27687:527836da73d1

Minor cleanup: this callback is only triggered for IMs.
author Paul Aurich <paul@darkrain42.org>
date Sun, 26 Jul 2009 00:19:59 +0000
parents e5ebf3abd9f8
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
10409
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
1 /** @page tcl-howto Tcl Scripting HOWTO
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
2
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
3 @section Intoduction
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
4
10597
0e886a234d92 [gaim-migrate @ 12012]
Ethan Blanton <elb@pidgin.im>
parents: 10410
diff changeset
5 NOTA BENE: This documentation is badly out of date for 2.x.
0e886a234d92 [gaim-migrate @ 12012]
Ethan Blanton <elb@pidgin.im>
parents: 10410
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
12
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
13 If you are not familiar with Tcl, you will probably find it somewhat
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
14 different from what you are used to. Despite being somewhat unique
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
15 (more akin to shell programming than other traditional scripting
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
16 languages such as @e perl or @e python), it is simple to learn for
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
17 beginners and experienced programmers alike. There are numerous books
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
18 on the subject; we will not discuss it any further here.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
19
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
20 @section start Getting Started
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
23 existence of a procedure called @c plugin_init. This procedure has
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
24 some limitations placed upon it; it will be parsed and evaluated before
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
25 the rest of the Tcl script, so it cannot reference any other variables
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
26 or procedures declared in the script. In practice this is not a
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
27 problem, as the only thing this procedure should do is return a simple
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
28 list containing five items: the @b name of the script, its @b version
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
29 number, a @b summary (just a few words) of its function, a short (longer
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
30 than the summary, but no more than a couple of sentences if possible)
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
31 @b description, the @b author, and a @b URL to web page. For example:
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
32
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
33 @code
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
34 proc plugin_init { } {
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
35 return [ list "Example Plugin" \
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
36 "1.0" \
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
37 "Example plugin registration" \
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
38 "Example of how to register a plugin for the Tcl HOWTO" \
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
39 "Ethan Blanton <eblanton@cs.purdue.edu>" \
16196
1414e0e01dc5 More renaming.
Richard Laager <rlaager@wiktel.com>
parents: 10597
diff changeset
40 "http://pidgin.im/" ]
10409
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
41 }
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
42 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
43
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
48
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
49 @section details Interpreter Details
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
52 meaning that commands like @c fileevent and @c after are available and
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
53 do not require @c vwait etc. The @c vwait actually seems to be somewhat
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
54 broken due to a bug somewhere in the Tcl/Glib event loop glue, and it
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
55 should not be used for now.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
68 descriptions will reference it explicitly for clarity.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
69
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
70 @li Variables
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
71
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
74 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
77 script.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
78
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
79 @li Commands
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
80
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
92 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
96
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
97 @c alias returns the alias for the account @c account. If there is no
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
98 alias for the given account, it returns the empty string.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
99
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
100 The subcommand @c connect connects the named account if it is not
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
101 connected, and does nothing if it is. In either case, it returns
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
102 the @c gc for the account.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
103
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
106 other functions.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
107
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
108 @c disconnect disconnects the given @c account if it is connected, or
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
109 does nothing if it is.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
110
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
113 returns the account if found, or 0 otherwise.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
114
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
117
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
118 The @c isconnected query returns true if the given account is
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
119 connected and false otherwise.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
120
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
123 @c account argument of the other subcommands. The @c -all option
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
124 (default) returns all accounts, while the @c -online option returns
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
125 only those accounts which are online.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
126
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
127 The @c protocol subcommand returns the protocol ID (e.g. "prpl-msn")
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
128 for the given account.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
129
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
130 The @c username subcommand returns the username for the account
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
131 @c account.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
132
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
138 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
141 buddies and manipulating the buddy list. For the purposes of Tcl,
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
142 a "buddy" is currently a list of several elements, the first of
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
143 which being the type. The currently recognized types are "group",
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
144 "buddy", and "chat". A group node looks like:
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
145 @code
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
146 { group name { buddies } }
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
147 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
148 A buddy node is:
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
149 @code
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
150 { buddy name account }
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
151 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
152 And a chat node is:
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
153 @code
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
154 { chat alias account }
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
155 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
156
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
157 The @c alias subcommand returns the alias for the given buddy if it
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
158 exists, or the empty string if it does not.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
159
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
167
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
168 @c list returns a list of @c group structures, filled out with buddies
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
169 and chats as described above.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
170
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
177 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
180 account connections.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
184 commands.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
185
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
191
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
192 @c list returns a list of all known connections. The elements of
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
201 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
211 write</tt> will not be caught by this procedure, and will be propagated
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
212 to the caller.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
213
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
220 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
225
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
226 The command @c find attempts to find an existing conversation with
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
227 username @c name. If the @c -account option is given, it refines its
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
228 search to include only conversations on that account.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
229
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
232
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
233 @c list returns a list of all currently open conversations.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
234
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
235 The @c new subcommand can be used to create a new conversation with
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
236 a specified user on a specified account if one does not exist, or
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
237 retrieve the existing conversation if it does. The @c -chat and
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
238 @c -im options specify whether the created conversation should be a
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
239 chat or a standard IM, respectively.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
240
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
241 @c write is used to write to the specified conversation. The @c style
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
244 (style @c recv), or as a system message (such as "so-and-so has
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
245 signed off", style @c system). From is the name to whom the text
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
246 should be attributed -- you probably want to check for aliases here,
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
247 lest you confuse the user. @c text is the text to print.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
248
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
252 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
262
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
265 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
276
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
279 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
290
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
293 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
294
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
295 This sends an IM in the fashion of serv_send_im. @c gc is the GC of
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
296 the connection on which you wish to send (as returned by most event
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
297 handlers), @c who is the nick of the buddy to which you wish to send,
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
298 and @c text is the text of the message.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
299
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
303 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
307
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
308 The @c connect subcommand registers the procedure @c proc as a handler
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
309 for the signal @c signal on the instance @c instance. @c instance
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
314 although you need not use them all. The procedure @c proc may be
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
315 either a simple command or a procedure in curly brackets. Note that
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
320
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
321 @c disconnect removes any existing signal handler for the named
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
322 signal and instance.
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
323
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
326 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
327
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
328 This unloads the current plugin. Note that preferences will not be
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
329 updated (yet).
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
330
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
331 @section Signals
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
332
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
333 Check the signals documentation for the meaning of these signals; this is
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
334 intended to be a list only of their arguments. Signal callbacks will
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
335 be made in their own namespace, and arguments to those signal
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
336 callbacks will live in the namespace @c event underneath that
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
337 namespace. To briefly illustrate, the signal @c receiving-im-msg is
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
340 the IM. These arguments live in the variables @c event::account,
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
341 @c event::sender, and @c event::buffer, respectively. Therefore a callback
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
342 which notifies the user of an incoming IM containing the word 'shizzle'
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
343 might look like this:
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
344
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
349 "$event::sender is down with the shizzle"
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
350 }
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
351 }
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
352 @endcode
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
353
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
354 Note that for some signals (notably @c receiving-im-msg, @c sending-im-msg,
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
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
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
357 whose return value is meaningful, returning a value from the Tcl event
10410
f7878475292c [gaim-migrate @ 11658]
Ethan Blanton <elb@pidgin.im>
parents: 10409
diff changeset
358 will return that value as it would in C.
10409
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
359
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
360 */
68d6065fc32f [gaim-migrate @ 11657]
Mark Doliner <mark@kingant.net>
parents:
diff changeset
361
10410
f7878475292c [gaim-migrate @ 11658]
Ethan Blanton <elb@pidgin.im>
parents: 10409
diff changeset
362 // vim: syntax=c tw=72 et