Mercurial > hg > xemacs-beta

comparison man/lispref/tooltalk.texi @ 0:376386a54a3c r19-14

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Import from CVS: tag r19-14
author cvs
date Mon, 13 Aug 2007 08:45:50 +0200
parents
children ec9a17fef872
comparison
equal deleted inserted replaced
-1:000000000000 0:376386a54a3c
1 @c -*-texinfo-*-
2 @c This is part of the XEmacs Lisp Reference Manual.
3 @c Copyright (C) 1990, 1991, 1992, 1993 Free Software Foundation, Inc.
4 @c See the file lispref.texi for copying conditions.
5 @setfilename ../../info/tooltalk.info
6 @node ToolTalk Support, Internationalization, X-Windows, top
7 @chapter ToolTalk Support
8 @cindex ToolTalk
9
10 @menu
11 * XEmacs ToolTalk API Summary::
12 * Sending Messages::
13 * Receiving Messages::
14 @end menu
15
16 @node XEmacs ToolTalk API Summary
17 @section XEmacs ToolTalk API Summary
18
19 The XEmacs Lisp interface to ToolTalk is similar, at least in spirit,
20 to the standard C ToolTalk API. Only the message and pattern parts
21 of the API are supported at present; more of the API could be added
22 if needed. The Lisp interface departs from the C API in a few ways:
23
24 @itemize @bullet
25 @item
26 ToolTalk is initialized automatically at XEmacs startup-time. Messages
27 can only be sent other ToolTalk applications connected to the same X11
28 server that XEmacs is running on.
29
30 @item
31 There are fewer entry points; polymorphic functions with keyword
32 arguments are used instead.
33
34 @item
35 The callback interface is simpler and marginally less functional.
36 A single callback may be associated with a message or a pattern;
37 the callback is specified with a Lisp symbol (the symbol should
38 have a function binding).
39
40 @item
41 The session attribute for messages and patterns is always
42 initialized to the default session.
43
44 @item
45 Anywhere a ToolTalk enum constant, e.g. @samp{TT_SESSION}, is valid, one
46 can substitute the corresponding symbol, e.g. @code{'TT_SESSION}. This
47 simplifies building lists that represent messages and patterns.
48 @end itemize
49
50 @node Sending Messages
51 @section Sending Messages
52 @cindex sending ToolTalk messages
53 @cindex ToolTalk message
54
55 @menu
56 * Example of Sending Messages::
57 * Elisp Interface for Sending Messages::
58 @end menu
59
60 @node Example of Sending Messages
61 @subsection Example of Sending Messages
62
63 Here's a simple example that sends a query to another application
64 and then displays its reply. Both the query and the reply are
65 stored in the first argument of the message.
66
67 @example
68 (defun tooltalk-random-query-handler (msg)
69 (let ((state (get-tooltalk-message-attribute msg 'state)))
70 (cond
71 ((eq state 'TT_HANDLED)
72 (message (get-tooltalk-message-attribute msg arg_val 0)))
73 ((memq state '(TT_FAILED TT_REJECTED))
74 (message "Random query turns up nothing")))))
75
76 (defvar random-query-message
77 '( class TT_REQUEST
78 scope TT_SESSION
79 address TT_PROCEDURE
80 op "random-query"
81 args '((TT_INOUT "?" "string"))
82 callback tooltalk-random-query-handler))
83
84 (let ((m (make-tooltalk-message random-query-message)))
85 (send-tooltalk-message m))
86 @end example
87
88 @node Elisp Interface for Sending Messages
89 @subsection Elisp Interface for Sending Messages
90
91 @defun make-tooltalk-message attributes
92 Create a ToolTalk message and initialize its attributes.
93 The value of @var{attributes} must be a list of alternating keyword/values,
94 where keywords are symbols that name valid message attributes.
95 For example:
96
97 @example
98 (make-tooltalk-message
99 '(class TT_NOTICE
100 scope TT_SESSION
101 address TT_PROCEDURE
102 op "do-something"
103 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
104 @end example
105
106 Values must always be strings, integers, or symbols that represent
107 ToolTalk constants. Attribute names are the same as those supported by
108 @code{set-tooltalk-message-attribute}, plus @code{args}.
109
110 The value of @code{args} should be a list of message arguments where
111 each message argument has the following form:
112
113 @quotation
114 @samp{(mode [value [type]])} or just @samp{value}
115 @end quotation
116
117 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
118 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
119 specified then @code{int} is used if @var{value} is a number; otherwise
120 @code{string} is used. If @var{type} is @code{string} then @var{value}
121 is converted to a string (if it isn't a string already) with
122 @code{prin1-to-string}. If only a value is specified then @var{mode}
123 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
124 @var{value} and @var{type} don't need to be specified. You can find out
125 more about the semantics and uses of ToolTalk message arguments in
126 chapter 4 of the @cite{ToolTalk Programmer's Guide}.
127 @refill
128 @end defun
129
130 @defun send-tooltalk-message msg
131 Send the message on its way. Once the message has been sent it's almost
132 always a good idea to get rid of it with
133 @code{destroy-tooltalk-message}.
134 @refill
135 @end defun
136
137 @defun return-tooltalk-message msg &optional mode
138 Send a reply to this message. The second argument can be @code{reply},
139 @code{reject} or @code{fail}; the default is @code{reply}. Before
140 sending a reply, all message arguments whose mode is @code{TT_INOUT} or
141 @code{TT_OUT} should have been filled in -- see
142 @code{set-tooltalk-message-attribute}.
143 @refill
144 @end defun
145
146 @defun get-tooltalk-message-attribute msg attribute &optional argn
147 Returns the indicated ToolTalk message attribute. Attributes are
148 identified by symbols with the same name (underscores and all) as the
149 suffix of the ToolTalk @samp{tt_message_<attribute>} function that
150 extracts the value. String attribute values are copied and enumerated
151 type values (except disposition) are converted to symbols;
152 e.g. @samp{TT_HANDLER} is @code{'TT_HANDLER}, @samp{uid} and @samp{gid}
153 are represented by fixnums (small integers), @samp{opnum} is converted
154 to a string, and @samp{disposition} is converted to a fixnum. We
155 convert @samp{opnum} (a C int) to a string (e.g. @code{123} @result{}
156 @code{"123"}) because there's no guarantee that opnums will fit within
157 the range of XEmacs Lisp integers.
158 @refill
159
160 [TBD] Use the @code{plist} attribute instead of C API @code{user}
161 attribute for user-defined message data. To retrieve the value of a
162 message property, specify the indicator for @var{argn}. For example, to
163 get the value of a property called @code{rflag}, use
164
165 @example
166 (get-tooltalk-message-attribute msg 'plist 'rflag)
167 @end example
168
169 To get the value of a message argument use one of the @code{arg_val}
170 (strings), @code{arg_ival} (integers), or @code{arg_bval} (strings with
171 embedded nulls), attributes. For example, to get the integer value of
172 the third argument:
173
174 @example
175 (get-tooltalk-message-attribute msg 'arg_ival 2)
176 @end example
177
178 As you can see, argument numbers are zero-based. The type of each
179 arguments can be retrieved with the @code{arg_type} attribute; however
180 ToolTalk doesn't define any semantics for the string value of
181 @code{arg_type}. Conventionally @code{string} is used for strings and
182 @code{int} for 32 bit integers. Note that XEmacs Lisp stores the lengths
183 of strings explicitly (unlike C) so treating the value returned by
184 @code{arg_bval} like a string is fine.
185 @refill
186 @end defun
187
188 @defun set-tooltalk-message-attribute value msg attribute &optional argn
189 Initialize one ToolTalk message attribute.
190
191 Attribute names and values are the same as for
192 @code{get-tooltalk-message-attribute}. A property list is provided for
193 user data (instead of the @code{user} message attribute); see
194 @code{get-tooltalk-message-attribute}.
195 @refill
196
197 Callbacks are handled slightly differently than in the C ToolTalk API.
198 The value of @var{callback} should be the name of a function of one
199 argument. It will be called each time the state of the message changes.
200 This is usually used to notice when the message's state has changed to
201 @code{TT_HANDLED} (or @code{TT_FAILED}), so that reply argument values
202 can be used.
203 @refill
204
205 If one of the argument attributes is specified as @code{arg_val},
206 @code{arg_ival}, or @code{arg_bval}, then @var{argn} must be the
207 number of an already created argument. Arguments can be added to a
208 message with @code{add-tooltalk-message-arg}.
209 @refill
210 @end defun
211
212 @defun add-tooltalk-message-arg msg mode type &optional value
213 Append one new argument to the message. @var{mode} must be one of
214 @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}, @var{type} must be a
215 string, and @var{value} can be a string or an integer. ToolTalk doesn't
216 define any semantics for @var{type}, so only the participants in the
217 protocol you're using need to agree what types mean (if anything).
218 Conventionally @code{string} is used for strings and @code{int} for 32
219 bit integers. Arguments can initialized by providing a value or with
220 @code{set-tooltalk-message-attribute}; the latter is neccessary if you
221 want to initialize the argument with a string that can contain embedded
222 nulls (use @code{arg_bval}).
223 @refill
224 @end defun
225
226 @defun create-tooltalk-message
227 Create a new ToolTalk message. The message's session attribute is
228 initialized to the default session. Other attributes can be intialized
229 with @code{set-tooltalk-message-attribute}.
230 @code{make-tooltalk-message} is the preferred way to create and
231 initialize a message.
232 @refill
233 @end defun
234
235 @defun destroy-tooltalk-message msg
236 Apply @samp{tt_message_destroy} to the message. It's not necessary to
237 destroy messages after they've been processed by a message or pattern
238 callback, the Lisp/ToolTalk callback machinery does this for you.
239 @end defun
240
241 @node Receiving Messages
242 @section Receiving Messages
243 @cindex ToolTalk pattern
244 @cindex receiving ToolTalk messages
245
246 @menu
247 * Example of Receiving Messages::
248 * Elisp Interface for Receiving Messages::
249 @end menu
250
251 @node Example of Receiving Messages
252 @subsection Example of Receiving Messages
253
254 Here's a simple example of a handler for a message that tells XEmacs to
255 display a string in the mini-buffer area. The message operation is
256 called @samp{emacs-display-string}. Its first (0th) argument is the
257 string to display.
258
259 @example
260 (defun tooltalk-display-string-handler (msg)
261 (message (get-tooltalk-message-attribute msg 'arg_val 0)))
262
263 (defvar display-string-pattern
264 '(category TT_HANDLE
265 scope TT_SESSION
266 op "emacs-display-string"
267 callback tooltalk-display-string-handler))
268
269 (let ((p (make-tooltalk-pattern display-string-pattern)))
270 (register-tooltalk-pattern p))
271 @end example
272
273 @node Elisp Interface for Receiving Messages
274 @subsection Elisp Interface for Receiving Messages
275
276 @defun make-tooltalk-pattern attributes
277 Create a ToolTalk pattern and initialize its attributes.
278 The value of attributes must be a list of alternating keyword/values,
279 where keywords are symbols that name valid pattern attributes
280 or lists of valid attributes. For example:
281
282 @example
283 (make-tooltalk-pattern
284 '(category TT_OBSERVE
285 scope TT_SESSION
286 op ("operation1" "operation2")
287 args ("arg1" 12345 (TT_INOUT "arg3" "string"))))
288 @end example
289
290 Attribute names are the same as those supported by
291 @code{add-tooltalk-pattern-attribute}, plus @code{'args}.
292
293 Values must always be strings, integers, or symbols that represent
294 ToolTalk constants or lists of same. When a list of values is provided
295 all of the list elements are added to the attribute. In the example
296 above, messages whose @samp{op} attribute is @samp{"operation1"} or
297 @samp{"operation2"} would match the pattern.
298
299 The value of @var{args} should be a list of pattern arguments where each
300 pattern argument has the following form:
301
302 @quotation
303 @samp{(mode [value [type]])} or just @samp{value}
304 @end quotation
305
306 Where @var{mode} is one of @code{TT_IN}, @code{TT_OUT}, or
307 @code{TT_INOUT} and @var{type} is a string. If @var{type} isn't
308 specified then @code{int} is used if @var{value} is a number; otherwise
309 @code{string} is used. If @var{type} is @code{string} then @var{value}
310 is converted to a string (if it isn't a string already) with
311 @code{prin1-to-string}. If only a value is specified then @var{mode}
312 defaults to @code{TT_IN}. If @var{mode} is @code{TT_OUT} then
313 @var{value} and @var{type} don't need to be specified. You can find out
314 more about the semantics and uses of ToolTalk pattern arguments in
315 chapter 3 of the @cite{ToolTalk Programmer's Guide}.
316 @refill
317 @end defun
318
319 @defun register-tooltalk-pattern pat
320 XEmacs will begin receiving messages that match this pattern.
321 @end defun
322
323 @defun unregister-tooltalk-pattern pat
324 XEmacs will stop receiving messages that match this pattern.
325 @end defun
326
327 @defun add-tooltalk-pattern-attribute value pat indicator
328 Add one value to the indicated pattern attribute. The names of
329 attributes are the same as the ToolTalk accessors used to set them less
330 the @samp{tooltalk_pattern_} prefix and the @samp{_add} suffix. For
331 example, the name of the attribute for the
332 @samp{tt_pattern_disposition_add} attribute is @code{disposition}. The
333 @code{category} attribute is handled specially, since a pattern can only
334 be a member of one category (@code{TT_OBSERVE} or @code{TT_HANDLE}).
335 @refill
336
337 Callbacks are handled slightly differently than in the C ToolTalk API.
338 The value of @var{callback} should be the name of a function of one
339 argument. It will be called each time the pattern matches an incoming
340 message.
341 @end defun
342
343 @defun add-tooltalk-pattern-arg pat mode type value
344 Add one fully-specified argument to a ToolTalk pattern. @var{mode} must
345 be one of @code{TT_IN}, @code{TT_INOUT}, or @code{TT_OUT}. @var{type}
346 must be a string. @var{value} can be an integer, string or @code{nil}.
347 If @var{value} is an integer then an integer argument
348 (@samp{tt_pattern_iarg_add}) is added; otherwise a string argument is
349 added. At present there's no way to add a binary data argument.
350 @refill
351 @end defun
352
353 @defun create-tooltalk-pattern
354 Create a new ToolTalk pattern and initialize its session attribute to
355 be the default session.
356 @end defun
357
358 @defun destroy-tooltalk-pattern pat
359 Apply @samp{tt_pattern_destroy} to the pattern. This effectively
360 unregisters the pattern.
361 @end defun
362
363 @defun describe-tooltalk-message msg &optional stream
364 Print the message's attributes and arguments to @var{stream}. This is
365 often useful for debugging.
366 @end defun