5.3 Querying Tickle Objects

In the previous section we queried a Tk-variable's state with the methods tkReturnInt and tkReturnAtom. In fact it is possible to query the state of all tickle objects, in particular to query the state of widgets.

All tickle objects provide a method tkReturn. This method is similar to the tk method in that it sends a message to the graphics engine. After the message has been executed by the graphics engine, however, the tkReturn method returns a string, whereas the tk method ignores this string.

synchronization

The field of the tkReturn message with the largest integer feature is constrained to the string returned. The method tkReturn is asynchronous: it sends the message to the graphics engine but does not block the thread until the return string is available. Eventually the graphics engine writes the return string to the store.

The tkReturn message is sent asynchronously for efficiency reasons. One can start another calculation without having to wait for tkReturn's result. One can send several tkReturn messages consecutively, and they will be sent immediately. The messages will be handled by the graphics agent in the same order as they are sent.

If you want to be sure that you have received the return value, say X, of tkReturn before continuing, then you must use a {Wait X} statement.

illegal return values

Similar to the method tkReturn tickle objects provide methods that return atoms, integers, floats and lists of strings, atoms, integers, and floats. Rather than writing a string to the store they write a value to the store which is obtained by transforming the string to the particular type. If it is not possible to transform the string into a value of that type, the boolean value false is written to the store.

The methods that return a list of strings, atoms, integers, or floats split the string into substrings separated by space characters. For instance, the return string "a b c" is transformed into the list [a b c] by the method tkReturnListAtom. Table 5.1 lists the return methods and how the methods transform strings. Note that a string "1.0" is transformed by tkReturnInt to the integer 1.

Method	Example string	Return value
`tkReturn`	`"red 1 1.0"`	`"red 1 1.0"`
`tkReturnAtom`	`"red 1 1.0"`	`'red 1 1.0'`
`tkReturnInt`	`"1"`	`1`
`tkReturnFloat`	`"1.0"`	`1.0`
`tkReturnList`	`"red 1 1.0"`	`["red" "1" "1.0"]`
`tkReturnListAtom`	`"red 1 1.0"`	`[red '1' '1.0']`
`tkReturnListInt`	`"red 1 1.0"`	`[false 1 1]`
`tkReturnListFloat`	`"red 1 1.0"`	`[false 1.0 1.0]`

Table 5.1: Returns methods and examples of return values.

string handling procedures

The Tk Module provides also for a set of procedures that can transform strings into atoms, integers, floats and lists of these three types. With these procedures it is possible to transform return strings in a user defined fashion. For more information see Section 28.12 of ``System Modules''.

5.3.1 Querying Configuration Options

The values of configuration options of a widget can be queried with the configure command. Instead of giving a value to which the option is to be set, we give the tickle unit as value. The tickle unit expands to just nothing, meaning that the value is not to be set but to be queried. For example, to query the value of the bg option of a widget T, we can feed

{T tkReturnListAtom(configure bg:unit $)}

This displays a list of atoms, usually it suffices to know that the current value of the option is the fifth element of the list, whereas its default value is the fourth element of the list.

5.3.2 Querying Widget Parameters

The command winfo is helpful to query parameters of widgets. For instance, to query the position and geometry of a widget T, we can use the following:

{Browse {Map [rootx width rooty height] fun {$ A} {Tk.returnInt winfo(A T)} end}}

The winfo command provides more options than those used above, for the details please consult winfo.