# 1 Introduction

The `QTk` module implements a description-based abstraction to help programmers efficiently build graphical user interfaces. Windows are built in a declarative way, expressing the widgets that compose the window along with their geometry. Widgets can be dynamically controlled by handles. Miscellaneous facilities are also provided to facilitate the development of an application's GUI. The `QTk` module is dedicated to Oz 3. It can be loaded by:

- From the OPI: `declare [QTk]={Module.link ["x-oz://system/wp/QTk.ozf"]}`

- In a functor, in the `import` part: `import QTk at 'x-oz://system/wp/QTk.oz'`

The documentation is split in the following chapters:

- Chapter 2 The Prototyper application

- Chapter 3 Tutorial example: a notepad application

- Chapter 4 Basics

- Chapter 5 Advanced topics

- Chapter 6 Standard dialog boxes

- Chapter 7 Widget reference

- Chapter 8 Miscellaneous

## 1.1 Description-based User Interface Specification

The QTk module is based on using descriptions to define user interfaces. A description is an Oz record value.

In general, there are three main ways of defining user interfaces:

- By means of explicit calls to a user interface toolbox (Tcl/Tk, AWT, GTk, ...).

- By means of an Interface Builder, a graphical tool that allows to create the interface interactively (Visual tools, Delphi, ...).

- By means of descriptions. A description is a data structure that defines the user interface (HTML, XML, ...).

QTk uses the description approach, where the descriptions are Oz record values. Note that the QTk Prototyper provides an interactive interface; this regains part of the advantage of using an Interface Builder. The Macintosh has popularized the notion of "resources", which are graphical descriptions of user interfaces that correspond to records. However, they are intended to be used graphically, through an Interface Builder. Consequently they are limited to parts of the user interface known before the execution of the application. Description records on the other hand can be calculated on the fly as needed at runtime by the application.

The description approach is particularly useful in a symbolic language such as Oz that allows easy and concise creation of data structures. QTk uses record values, which are well supported by Oz. For example, the following code defines a record and references it in D:

> `
> declare
> D=td(button(text:"Show"
> action:proc{$} {Show 'Hello World'} end)
> button(text:"Close"
> action:toplevel#close))
> `

The record with label `td` has two fields that themselves contain records defining two buttons that are labelled Show and Close. These buttons are linked to the actions of displaying `Hello World` and closing the window.

There are at least five advantages to using descriptions:

- Descriptions are part of the source language. The user interface are described without leaving the source language.

- It is possible to calculate descriptions at runtime, as dynamically required by the application.

- Since descriptions are values, they can be saved in files and loaded at will.

- Saving descriptions in Ascii form allows them to be inspected and edited by humans.

- Records in Oz are written in a very concise, symbolic way. This means that the description itself is already a kind of visual representation. As a result, the conceptual distance between the description and its user interface meaning is small.

By mixing functions and records, descriptions can be made both concise and readable. Here's an example:

> `
> declare
> In Out
> fun {Txt T H S}
> lr(glue:nswe
> label(text:T)
> text(handle:H glue:nswe tdscrollbar:S))
> end
> fun {But T A}
> button(glue:we text:T action:A)
> end
> D=td(tdrubberframe(glue:nswe
> {Txt "Expression" In false}
> {Txt "Result" Out true})
> lr(glue:we
> {But "Eval" proc {$} V={E {In get($)}} in {Out set(V)} end}
> {But "Quit" toplevel#close}))
> `

The functions `Txt` and `But` shorten the writing of the record `D`. This defines a window with one rubber frame, two text labels, two text boxes (including one with scrollbar), two buttons (each with an action). One of the actions is a procedure that does a calculation (defined by the function E), the other simply closes the window. The text boxes have `handle` parameters that give control over these widgets. Here, one of the boxes is read (through the `get` method) and the other is written (through the `set` method).