<CHAPTER ID="chapter.introduction">
  <TITLE>Introduction</TITLE>

 
<P> 
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 controled using handlers. Miscellaneous facilities are also providden to fasten the GUI development of applications.

The <<QTk>> module is dedicaded to <EM>Oz 3</EM>. 

</P>
<P>

The documentation is separated in the following chapters :


<LIST>
<ITEM> <ptr to="chapter.example"> Introductory example : a notepad application
<ITEM> <ptr to="chapter.basics"> QTK basics
<ITEM> <ptr to="chapter.widgets"> Reference documentation to QTk widgets
<ITEM> <ptr to="chapter.misc"> Miscellaneous
</LIST>

</P>

<section><TITLE>Description-based User Interface Specification</TITLE>

<P>
The QTk module is based on using <EM>descriptions</EM> to define user
interfaces.  A description is a record value that defines completely
the user interface.
</P>
<P>
In general, there are three main ways of defining user interfaces:

<LIST>
<ITEM> By means of explicit calls to a user interface toolbox.
<ITEM> By means of an Interface Builder, a graphical tool that 
allows to create the interface interactively.
<ITEM> By means of <EM>descriptions</EM>.  A description is a data
   structure that defines the user interface.
</LIST>

QTk uses the description approach, where the descriptions are record
values.  (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.  They are much more cumbersome to use than records, for
example, they cannot be easily calculated in programs.)
</P>
<P>
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 and that define two buttons.  It defines a window with two
buttons, labeled Show and Close, which are linked to the actions of
displaying <<Hello World>> and closing the window.
</P>
<P>
There are at least five advantages to using descriptions:
<LIST>
<ITEM> Descriptions are part of the source language.  They allow to
   describe the user interface without leaving the source language.
<ITEM> It is possible to calculate descriptions.  For example, if the
   buttons are arranged in a geometrical pattern (e.g., over a map).
<ITEM> Since descriptions are values, they can be saved in files and
   loaded at will.
<ITEM> Saving descriptions in Ascii form allows them to be inspected and
   edited by humans.
<ITEM> 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.
</LIST>
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 result in <<D>> is still a record value, but the source code is
shorter. 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 'handles', which allow to do things with the
text--here, one of the boxes is read (through the 'get' method) and the
other is written (through the 'set' method).



</CHAPTER>
