1.4 Return Values

1.4.1 Widget Constructor Return Values

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 destroy command. On failure, an error is signalled.

1.4.2 Widget Return Values

The widget 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.

(.hello :configure :text "Bye World" :return 'string)
==> "" 
==> T

the empty string is returned as first value, and the second value T 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 .hello function. More generally a user program may be running in GCL and be interrupted to receive and act on communications from the gcltksrv 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.

A special variable tk::*break-on-errors* which if not nil, requests that that LISP signal an error when a message is received indicating a function failed. Whenever a command fails, whether a return value was requested or not, gcltksrv 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 T to track down incorrect messages.

The gcltksrv process always returns strings as values. If :return type is specified, then conversion to type is accomplished by calling

(coerce-result return-string type)

Here type must be a symbol with a coercion-functions property. The builtin return types which may be requested are:

T

in which case the string passed back from the gcltksrv process, will be read by the lisp reader.

number

the string is converted to a number using the current *read-base*

list-strings

(coerce-result "a b {c d} e" 'list-strings)
==> ("a" "b" "c d" "e")

boolean

(coerce-result "1" ’boolean) ==> T (coerce-result "0" ’boolean) ==> NIL

The above symbols are in the TK or LISP package. It would be possible to add new types just as the :return t is done:

(setf (get 't 'coercion-functions)
      (cons #'(lambda (x) (our-read-from-string x 0))
	    #'(lambda (x) (format nil "~s" x))))

The coercion-functions property of a symbol, is a cons whose car is the coercion form from a string to some possibly different lisp object, and whose cdr 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.

1.4.3 Control Function Return Values

The control funcions (see Control) do not return a value or wait unless requested to do so, using the :return keyword. The types and method of specification are the same as for the Widget Functions in the previous section.

(winfo :width '.hello :return 'number)
==> 120

indicates that the .hello button is actually 120 pixels wide.