Next: Argument Lists, Previous: Common Features of Widgets, Up: General [Contents]

### 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 functions (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.

Next: Argument Lists, Previous: Common Features of Widgets, Up: General [Contents]