<!--
  - Authors:
  -   Christian Schulte <schulte@ps.uni-sb.de>
  -
  - Contributors:
  -   Daniel Simon <dansim@ps.uni-sb.de>
  -   Andy Walter <anwalt@ps.uni-sb.de>
  -   
  - Copyright:
  -   Christian Schulte, 1998
  -
  - Last change:
  -   $Date: 1999/08/19 13:02:08 $ by $Author: schulte $
  -   $Revision: 1.14 $
  -
  - This file is part of Mozart, an implementation
  - of Oz 3
  -    http://www.mozart-oz.org
  -
  - See the file "LICENSE" or
  -    http://www.mozart-oz.org/LICENSE.html
  - for information on usage and redistribution
  - of this file, and for a DISCLAIMER OF ALL
  - WARRANTIES.
  -
  -->

<Chapter id="chapter.started">
  <Title/Getting Started/

  <P>
    This chapter shows a small graphical application from which we will
    identify the most important concepts found in the window
    interface. The presentation is really designed for identification
    of issues. An explanation of these issues follows in the remaining
    chapters of this document.

  <Section id="section.started.first">
    <Title/Our First Graphical Application/

    <P>
      <Ptr to="figure.intro.start"> shows a screen dump of our first
      graphical application.  It allows to enter text into the <span class=index/entry
      field/. Pressing the button toggles the capitalization of the
      text in that entry field.

    <p>
      <Figure id="figure.intro.start">
        <Caption/Our first graphical application./
<p>
               <picture.choice>
                 <Picture.Extern to="lower.gif" type=gif>
                 <Picture.Extern id="pict.ext.started.lower" to="pictures/started/lower.eps" type=ps>
               </picture.choice>
<p>
               <picture.choice>
                 <Picture.Extern to="upper.gif" type=gif>
                 <Picture.Extern id="pict.ext.started.upper" to="pictures/started/upper.eps" type=ps>
               </picture.choice>
      </Figure>


    <P>
      The program for the small graphical application is concerned
      with the following three issues:
      <list>
      <entry> <index/widget/widgets
      <item> Create the graphical entities called
             widgets. The application consists of three widgets: 
      a toplevel widget (this is the outermost window), an entry for
      entering text, and a button.
      <entry> <index/geometry/geometry
      <item> Arrange the entry and button such that they appear inside
      the toplevel widget.
      <entry> <index/action/actions
      <item> Attach an action to the button widget such that pressing
      the button changes the capitalization of the entry text.
      </list>
      In the sections below, we exhibit the code handling these
      issues. The complete application then has the following
      structure:
<chunk class=anonymous><title/Capitalization/
<chunk.ref/Widget creation/
<chunk.ref/Geometry management/
</chunk>
      

    <subsection >
      <title/Widgets/

      <p> 
        The following program fragment
<index class=tails/<<Tk>><And><<toplevel>>/
<index class=tails/<<Tk>><And><<entry>>/
<index class=tails/<<Tk>><And><<button>>/
<chunk><title/Widget creation/
W={New Tk.toplevel tkInit(title:'Capitalization')}
E={New Tk.entry    tkInit(parent:W)}
B={New Tk.button   tkInit(parent: W
                          text:   'Change Capitalization'
                          action: <chunk.ref/Action definition/)}
</chunk>
        creates and initializes the widget objects of our application.
        Creating and initializing a widget object creates a graphical image
        for the widget object.  We refer to the graphical image just as
        the widget.  Most often we do not distinguish between the object and
        its widget. All but the toplevel widget are linked by the
        <<parent>> features: this defines a <span class=index/widget hierarchy/ for
        closing widgets and geometry management.

    <subsection >
      <title/Geometry/

      <p> 
        Here we define the <index/geometry/geometry for the entry and button widgets:
<index class=tails/<<Tk>><And><<send>>/
<chunk><title/Geometry management/
{Tk.send pack(E B fill:x padx:4 pady:4)}
</chunk>

    <subsection >
      <title/Actions/

      <p> 
        The remaining program fragment:
<chunk><title/Action definition/
proc {$}
   S={E tkReturn(get $)}
in
   {E tk(delete 0 'end')}
   {E tk(insert 0 {Map S <chunk.ref/Change capitalization/})}
end
</chunk>
        defines the action as a procedure to be executed when the
        button is pressed. It retrieves the current content
        <<S>> from entry <code/E/, clears <code/E/, and reinserts
	<<S>> in <code/E/, but with toggled
        capitalization. <index/<<tkReturn>>/
<code/tkReturn/ illustrates another important
	issue: returning values from widgets.
    

  <Section id="section.started.architecture">
    <Title/The Architecture/

    <p>
      <ptr to="figure.started.architecture"> shows a sketch of the
      architecture of the window interface in Mozart. Its core part is 
      the graphics engine. The <index/graphics engine/graphics engine computes graphical
      output and displays it according to the input received.

      <figure id="figure.started.architecture">
        <caption/Architecture sketch./
        <picture latex>
          {\sf\psset{nodesep=2pt}
          \newrgbcolor{ColorBack}{0.9961 0.5469 0}
          \begin{tabular}{l@{\qquad}l@{\qquad\qquad}l}
          \rnode{return}{return values}\\[1em]
          \rnode{action}{\quad actions}\\[2em]
          &\ovalnode[fillstyle=solid,fillcolor=ColorBack]{engine}{graphics
          engine}&\rnode{event}{events}\\[1em]
          \rnode{send}{\texttt{\qquad Tk.send}}\\[1em]
          \rnode{init}{\texttt{\quad tkInit}}\\[1em]
          \rnode{tk}{\texttt{tk}}
          \end{tabular}
          \nccurve[angleA=90]{->}{engine}{return}
          \nccurve[angleA=110]{->}{engine}{action}
          \nccurve[angleA=260]{<-}{engine}{send}
          \nccurve[angleA=270]{<-}{engine}{init}
          \nccurve[angleA=280]{<-}{engine}{tk}
          \nccurve[angleA=180]{->}{event}{engine}}
        </picture>
      </figure>

    <p>
      Initializing widgets with the method <span class=index/<<tkInit>>/ and applying
      widgets to the <span class=index/<<tk>>/ method send messages to the graphics
      engine. <index class=tails/<<Tk>><and><<send>>/Additionally, the procedure <<Tk.send>> we used for
      geometry management sends messages to the graphics engine. The
      graphics engine understands tickles, <<Tk.send>> in fact just
      takes a tickle and sends it to the engine. Also
      <<tkInit>> and <<tk>> methods map straightforwardly to tickle
      messages.

    <p> 
      The graphics engine is sequential, each tickle is executed in
      order. User events are considered only when the graphics engine
      is idle, then the attached actions are executed. 


  <Section id="section.started.implementation">
    <Title/Implementation/

    <p>
      The implementation idea of the window interface is quite
      simple. The graphics engine is executed by a separate
      operating system process (it runs in fact a modified
      <kbd/wish/). Any communication with the graphics engine is done
      via strings. The interface maps tickles and tickle messages to
      strings (this is done in a fairly efficient way). In the reverse
      direction, strings can be mapped back to &Oz; data types like
      integers, atoms, lists of integers or lists of atoms.

    <p>
      To get an impression of the efficiency of the implementation,
      try some examples, as well as the <ref.extern to="ozdoc:demo"/demos/
      and the <ref.extern
      to="ozdoc:tools"/tools/ that come with Mozart. They are all
      built on top of the Tk window programming interface.



<![ %EXTRA; [
<section><title/Examples/
<p>
<chunk><title/EXAMPLES/
%%%
%%% Chapter: Getting started
%%%

declare
<chunk.ref/Capitalization/





</chunk>
]]>


</Chapter>

