1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- Created by GNU Texinfo 6.7, http://www.gnu.org/software/texinfo/ -->
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>Return Values (GCL TK Manual)</title>
<meta name="description" content="Return Values (GCL TK Manual)">
<meta name="keywords" content="Return Values (GCL TK Manual)">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<link href="index.html" rel="start" title="Top">
<link href="wm.html#SEC_Contents" rel="contents" title="Table of Contents">
<link href="General.html" rel="up" title="General">
<link href="Argument-Lists.html" rel="next" title="Argument Lists">
<link href="Common-Features-of-Widgets.html" rel="prev" title="Common Features of Widgets">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.indentedblock {margin-right: 0em}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
kbd {font-style: oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
span.nolinebreak {white-space: nowrap}
span.roman {font-family: initial; font-weight: normal}
span.sansserif {font-family: sans-serif; font-weight: normal}
ul.no-bullet {list-style: none}
-->
</style>
</head>
<body lang="en">
<span id="Return-Values"></span><div class="header">
<p>
Next: <a href="Argument-Lists.html" accesskey="n" rel="next">Argument Lists</a>, Previous: <a href="Common-Features-of-Widgets.html" accesskey="p" rel="prev">Common Features of Widgets</a>, Up: <a href="General.html" accesskey="u" rel="up">General</a> [<a href="wm.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
</div>
<hr>
<span id="Return-Values-1"></span><h3 class="section">1.4 Return Values</h3>
<span id="Widget-Constructor-Return-Values"></span><h4 class="subsection">1.4.1 Widget Constructor Return Values</h4>
<p>On successful completion, the widget constructor functions return the
symbol passed in as the first argument. It will now have a functional
binding. It is an error to pass in a symbol which already corresponds
to a widget, without first calling the <code>destroy</code> command. On failure,
an error is signalled.
</p>
<span id="Widget-Return-Values"></span><h4 class="subsection">1.4.2 Widget Return Values</h4>
<p>The <i>widget</i> functions themselves, do not normally return any value.
Indeed the lisp process does not wait for them to return, but merely
dispatches the commands, such as to change the text in themselves.
Sometimes however you either wish to wait, in order to synchronize, or
you wish to see if your command fails or succeeds. You request values
by passing the keyword :return and a value indicating the type.
</p>
<div class="example">
<pre class="example">(.hello :configure :text "Bye World" :return 'string)
==> ""
==> T
</pre></div>
<p>the empty string is returned as first value, and the second value
<code>T</code> indicates that the new text value was successfully set. LISP
will not continue until the tkclsrv process indicates back that the
function call has succeeded. While waiting of course LISP will continue
to process other graphics events which arrive, since otherwise a
deadlock would arise: the user for instance might click on a mouse, just after
we had decided to wait for a return value from the <code>.hello</code> function.
More generally a user program may be running in <b>GCL</b> and be interrupted
to receive and act on communications from the <samp>gcltksrv</samp>
process. If an error occurred then the second return value of the
lisp function will be NIL. In this case the first value, the string
is usually an informative message about the type of error.
</p>
<p>A special variable <code>tk::*break-on-errors*</code> which if not
<code>nil</code>, requests that that <b>LISP</b> signal an error when a message
is received indicating a function failed. Whenever a command fails,
whether a return value was requested or not, <samp>gcltksrv</samp> returns a
message indicating failure. The default is to not go into the
debugger. When debugging your windows it may be convenient however to
set this variable to <code>T</code> to track down incorrect messages.
</p>
<p>The <samp>gcltksrv</samp> process always returns strings as values.
If <code>:return</code> <i>type</i> is specified, then conversion to <i>type</i>
is accomplished by calling
</p>
<div class="example">
<pre class="example">(coerce-result <i>return-string</i> <i>type</i>)
</pre></div>
<p>Here <i>type</i> must be a symbol with a <code>coercion-functions</code>
property.
The builtin return types which may be requested are:
</p>
<dl compact="compact">
<dt><code>T</code></dt>
<dd><p>in which case
the string passed back from the <samp>gcltksrv</samp> process, will be read by the
lisp reader.
</p></dd>
<dt><code>number</code></dt>
<dd><p>the string is converted to a number using the current *read-base*
</p></dd>
<dt><code>list-strings</code></dt>
<dd>
<div class="example">
<pre class="example">(coerce-result "a b {c d} e" 'list-strings)
==> ("a" "b" "c d" "e")
</pre></div>
</dd>
<dt><code>boolean</code></dt>
<dd><p>(coerce-result "1" ’boolean)
==> T
(coerce-result "0" ’boolean)
==> NIL
</p></dd>
</dl>
<p>The above symbols are in the <code>TK</code> or <code>LISP</code> package.
It would be possible to add new types just as the <code>:return t</code>
is done:
</p>
<div class="example">
<pre class="example">(setf (get 't 'coercion-functions)
(cons #'(lambda (x) (our-read-from-string x 0))
#'(lambda (x) (format nil "~s" x))))
</pre></div>
<p>The <code>coercion-functions</code> property of a symbol, is a cons whose
<code>car</code> is the coercion form from a string to some possibly different
lisp object, and whose <code>cdr</code> is a function which builds a string
to send to the graphics server. Often the two functions are inverse
functions one of the other up to equal.
</p>
<span id="Control-Function-Return-Values"></span><h4 class="subsection">1.4.3 Control Function Return Values</h4>
<p>The <i>control</i> functions (see <a href="Control.html">Control</a>) do not return a value
or wait unless requested to do so, using the <code>:return</code> keyword.
The types and method of specification are the same as for the
Widget Functions in the previous section.
</p>
<div class="example">
<pre class="example">(winfo :width '.hello :return 'number)
==> 120
</pre></div>
<p>indicates that the <code>.hello</code> button is actually 120 pixels
wide.
</p>
<hr>
<div class="header">
<p>
Next: <a href="Argument-Lists.html" accesskey="n" rel="next">Argument Lists</a>, Previous: <a href="Common-Features-of-Widgets.html" accesskey="p" rel="prev">Common Features of Widgets</a>, Up: <a href="General.html" accesskey="u" rel="up">General</a> [<a href="wm.html#SEC_Contents" title="Table of contents" rel="contents">Contents</a>]</p>
</div>
</body>
</html>
|
