<!--
  - Authors:
  -   Christian Schulte <schulte@ps.uni-sb.de>
  -
  - Contributors:
  -   Martin Homik <homik@ps.uni-sb.de>
  -
  - Copyright:
  -   Christian Schulte, 1998
  -
  - Last change:
  -   $Date: 2001-10-22 11:42:07 +0200 (Mon, 22 Oct 2001) $ by $Author: kornstae $
  -   $Revision: 14403 $
  -
  - 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.TkTools">
  <Title/Graphical Tools: <<TkTools>>/

  <p>

  <Section id="section.tkTools.error">
    <Title/Error/
    <index class=module/TkTools<and>error/

      <p>

      The <<TkTools.error>> class extends <<TkTools.dialog>>.

      <list>

      <entry> <<tkInit>> <index class=module/TkTools<and>error<and>tkInit/
        <synopsis>
          <<< 
tkInit(title:  ?+{TitleTcl}  <= 'Error'
       master: ?+{MasterTcl} <= NoArg
       aspect: ?+{AspectI}   <= 250
       text:   ?+{TextTcl})
          >>>
        <item>
           Initialise the widget object and create a new error dialog.
	   <p>
	   ?+{AspectI} specifies a non-negative integer value
      indicating desired aspect ratio for the text. The aspect ratio
      is specified as 100*width/height. 100 means the text should be
      as wide as it is tall, 200 means the text should be twice as
      wide as it is tall, 50 means the text should be twice as tall as
      it is wide, and so on.

      </list>
  </Section>

  <Section id="section.tkTools.dialog">
    <Title/Dialog/
    <index class=module/TkTools<and>dialog/

    <p>

    The <<TkTools.dialog>> class extends <<Tk.frame>>.

    <list>

      <entry> <<tkInit>> <index class=module/TkTools<and>dialog<and>tkInit/
        <synopsis>
          <<<
tkInit(title:   ?+{TitleTcl}
       master:  ?+{WidgetO}      <= NoArg
       root:    ?+{Root}         <= master
       buttons: ?+{ButtonsL}
       pack:    ?+{PackB}        <= true
       focus:   ?+{FocusI}       <= 0
       bg:      ?+{BackgroundA}  <= NoArg
       default: ?+{DefaultI}     <= 0
       delete:  ?+{DeleteAction} <= NoArg)
>>>
        <item>
           Initialise the widget object and create a new dialog. This widget
	   needs at least two informations: the title and a list of buttons.
	   Each element of the button list is of the form: 
	   <<LabelTcl # nullary procedure>>. Two examples are:
           <list>
	   <item> <<'close' # tkClose>>
	   <item> <<'nothing'# proc {$} skip end>>
	   </list>

	   A master widget is specified by ?+{WidgetO}. Depending on
	   ?+{Root} the widget will be placed in relation to the master
	   like following:

	   <list>
	     <entry> <<master>>
	       <item>
	         The dialog will be placed in the upper left corner
		 within the master widget.
	     <entry> <<master#XOff#YOff>>
	       <item>
	         The dialog will be placed in the upper left corner
		 of the master widget plus the xoffset and yoffset.
	     <entry> <<pointer>>
	       <item>
	        The dialog will be placed on the current pointer position.
             <entry> <<X#Y>>
               <item>
		User defined position.
	   </list>
	   
	   If you want to use a focus then you describe by ?+{FocusI} the 
	   button that gets the focus.

	   By ?+{DefaultI} you set the default button.

      <entry> <<tkPack>> <index class=module/TkTools<and>dialog<and>tkPack/
        <synopsis>
          <<< tkPack>>>
        <item>
           Pack the dialog.

      <entry> <<tkClose>> <index class=module/TkTools<and>dialog<and>tkClose/
        <synopsis>
          <<< tkClose>>>
        <item>
           Close the dialog.

      </list>

  </Section>

  <Section id="section.tkTools.menubar">
    <Title/Menubar/
    <index class=module/TkTools<and>menubar/
    
    <p>
    <<<{TkTools.menubar ?+{PWidgetO} ?+{KBWidgetO}  ?+{L} ?+{R} ??{Widget0}}>>
    <p>
      The <<TkTools.menubar>> function creates a menubar widget. The
      parent is described by ?+{PWidgetO}, while the KeyBinder is
      specified by ?+{KBWidgetO}. Usually both the parent and the key
      binder are the toplevel window. If you press a key combination,
      that is an abbreviation for a menu entry, within the key binder area
      the associated action will be done.

      <p>
      
      Menu entries are specified by the lists ?+{L} and ?+{R}, one for the
      left and one for the right menu part. Each element of both lists
      is a record with the label <<menubutton>>. The record has four features:
      <<text>>, <<underline>>, <<menu>> and <<feature>>.

<<<
menubutton(text:      ?+{TextTcl}
           underline: ?+{ULI}
	   menu:      ?+{MenuL}
	   feature:   ?+{Atom})
>>>      

      The field under the feature <<menu>> describes the view of the menu.
      It is a list of menu entries. Each entry may be: <<command>>, 
      <<separator>>, <<ckeckbutton>>, <<radiobutton>> or cascade.
      <p>
      The <<separator>> is just an Atom. While <<checkbutton>> and 
      <<radiobutton>> are usual Tk widgets, the <<command>> button is
      a new element and has the following form:

<<< 
command(label:   ?+{TextTcl} 
        action:  ?+{Action} 
        key:     ?+{KeyTcl}
        feature: ?+{Atom}) 
>>> 

      The value for the key describes the keyboard accelerator and
      event binding to be created. They can be used as follows:

      <Table>
	<TR>
	  <TH/<<key>> option value/
	  <TH/accelerator/
	  <TH/event binding/
	<TR>
	  <TD/<<a>>/
	  <TD/<Key/a//
	  <TD/<Samp/a//
	<TR>
	  <TD/<<ctrl(a)>>/
	  <TD/<Key/C-a//
	  <TD/<Samp/&lt;Control-a&gt;//
	<TR>
	  <TD/<<alt(a)>>/
	  <TD/<Key/A-a//
	  <TD/<Samp/&lt;Alt-a&gt;//
	<TR>
	  <TD/<<alt(ctrl(a))>>/
	  <TD/<Key/A-C-a//
	  <TD/<Samp/&lt;Alt-Control-a&gt;//
	<TR>
	  <TD/<<ctrl(alt(a))>>/
	  <TD/<Key/C-A-a//
	  <TD/<Samp/&lt;Control-Alt-a&gt;//
      </Table>
      
     <p>   
      If you like to place a submenu you have to describe a <<cascade>>
      element, which consists only of the two features <<label>> and <<menu>>.
<<<
cascade(label: ?+{TextTcl} 
        menu:  ?+{MenuL})
>>>   
      
  </Section>

  <Section id="section.tkTools.popupmenu">
    <Title/Popup Menu/
    <index class=module/TkTools<and>popupmenu/

    <p>

    The <<TkTools.popupmenu>> class extends <<Tk.menubutton>>.

    <list>
      <entry> <<tkInit>> <index class=module/TkTools<and>popupmenu<and>tkInit/
        <synopsis>
<<< 	 
meth tkInit(parent:   ?+{WidgetO}
            entries:  ?+{EL}      <= [empty]
            selected: ?+{SelI}    <= 1
            font:     ?+{FontO}   <= unit
            action:   ?+{ActionP} <= proc {$ S} skip end ...)   
>>>
	<item>
	  Initialise the widget object and create a new popup menu.
	  You always need to declare the parent of the widget. The 
	  field under the feature <<entries>> is a list of popup menu
	  entries. Each entry is of the form: <<LabelAtom#ColorAtom>>.
	  Although it is possible to declare an entry as 
	  <<[push#black push#green]>>, you should not do this.
	  <p>
	  By ?+{SelI} you declare the initial entry. If action should be 
	  performed you have to declare a unary procedure.

      <entry> <<getCurrent>> <index class=module/TkTools<and>popupmenu<and>getCurrent/
        <synopsis><<<getCurrent(??{Atom})>>>
	  <item>
	    Return the current active entry label.

      <entry> <<add>> <index class=module/TkTools<and>popupmenu<and>add/
        <synopsis><<<add(?+{E})>>>
	  <item>
	    Add a new entry. The entry must have the form:
	    <<ColorAtom#LabelAtom>>.

      <entry> <<rem>> <index class=module/TkTools<and>popupmenu<and>rem/
        <synopsis><<<rem(?+{LabelA})>>>
	  <item>
	    Remove (all) entries with the label ?+{LabelA}.
    </list>

  </Section>

  <Section id="section.tkTools.textframe">
    <Title/Textframe/
    <index class=module/TkTools<and>textframe/

    <p>

    The <<TkTools.textframe>> class extends <<Tk.frame>> and
    has only one method.

    <list>
    
      <entry> <<tkInit>> <index class=module/TkTools<and>textframe<and>tkInit/
        <synopsis>
<<<
tkInit(parent:  ?+{WidgetO}
       'class': ?+{ClassTcl} <= unit
       text:    ?+{TextTcl}
       font:    ?+{FontO}    <= DefaultFont)
>>>
	 <item>
           Initialise the widget object and create a new textframe. 
	    
    </list>
  </Section>

  <Section id="section.tkTools.notebook">
    <Title/Notebook/
    <index class=module/TkTools<and>notebook/

    <p>

    The <<TkTools.notebook>> class extends <<Tk.canvas>>.

    <list>
    
      <entry> <<tkInit>> <index class=module/TkTools<and>notebook<and>tkInit/
        <synopsis>
<<<
tkInit(parent:  ?+{WidgetO}
       font:    ?+{FontO}    <= DefaultFont)
>>>
	 <item>
           Initialise the widget object and create a new notebook. 

      <entry> <<add>> <index class=module/TkTools<and>notebook<and>add/
        <synopsis><<<add(?+{NoteO})>>>
	  <item>
	    Add a new note.

      <entry> <<remove>> <index class=module/TkTools<and>notebook<and>remove/
        <synopsis><<<remove(?+{NoteO})>>>
	  <item>
	    Remove a note.

      <entry> <<toTop>> <index class=module/TkTools<and>notebook<and>topTop/
        <synopsis><<<toTop(?+{NoteO})>>>
	  <item>
	    Bring note ?+{NoteO} to the top.

      <entry> <<getTop>> <index class=module/TkTools<and>notebook<and>getTop/
        <synopsis><<<getTop(??{NoteO})>>>
	  <item>
	    Return the top note.

    </list>
      
  </Section>

  <Section id="section.tkTools.note">
    <Title/Note/
    <index class=module/TkTools<and>note/

    <p>

    The <<TkTools.note>> class extends <<Tk.frame>>.

    <list>
    
      <entry> <<tkInit>> <index class=module/TkTools<and>note<and>tkInit/
        <synopsis>
<<<
tkInit(parent:  ?+{WidgetO}
       text:    ?+{TextTcl})
>>>
	 <item>
           Initialise the widget object and create a new note. The note packs
	   itself, thus you should avoid sending packaging commands, otherwise
	   the system hangs.	    

      <entry> <<toTop>> <index class=module/TkTools<and>note<and>toTop/
        <synopsis><<<toTop()>>>
	  <item>
	    This is an empty method. If yo want any action to
	    be performed you have to derive the <<TkTools.note>>
	    class and to overwrite the <<toTop>> method.
	 
    </list>

  </Section>

  <Section id="section.tkTools.scale">
    <Title/Scale/
    <index class=module/TkTools<and>scale/

    <p>

    The <<TkTools.scale>> class extends <<Tk.frame>>.

    <list>
    
      <entry> <<init>> <index class=module/TkTools<and>scale<and>init/
        <synopsis>
<<<
init(parent:  ?+{WidgetO}
     width:   ?+{WidthI}
     values:  ?+{ValuesL}
     initpos: ?+{PosI})
>>>
	 <item>
           Initialise the widget object and create a new scale.The field
	   ?+{ValuesL} describes all possible values, whereby the initial
	   value is described by position ?+{PosI}.

      <entry> <<drawTicks>> <index class=module/TkTools<and>scale<and>drawTicks/
        <synopsis><<<drawTicks()>>>
	 <item>
           Draw.

      <entry> <<get>> <index class=module/TkTools<and>scale<and>get/
        <synopsis><<<get(??{ValueI})>>>
	 <item>
	   Get the current value.

    </list>

  </Section>

  <Section id="section.tkTools.numberentry">
    <Title/Number Entry/
    <index class=module/TkTools<and>numberentry/

    <p>

    The <<TkTools.numberentry>> class extends <<Tk.frame>>.

    <list>
    
      <entry> <<tkInit>> <index class=module/TkTools<and>numberentry<and>tkInit/
        <synopsis>
<<<
tkInit(parent:       ?+{WidgetO}
       min:          ?+{MinI}    <= unit
       max:          ?+{MaxI}    <= unit
       val:          ?+{ValI}    <= MinI
       font:         ?+{FontO}   <= DefaultFont
       width:        ?+{WidthI}  <= 6
       action:       ?+{ActionP} <= DummyAction
       returnaction: ?+{RetActP} <= unit)
>>>
	 <item>
           Initialise the widget object and create a new number entry.
	   The number entry contains all values within ?+{MinI} and ?+{MaxI},
	   and shows initially the value ?+{ValI}. Allthough it is possible
	   to set ?+{ValI} less than ?+{MinI} you should not do it. 
	   <p>
	   By ?+{ActionP} you define an unary procedure that is each time invoked,
	   when alter the value of the number entry. Furthermore you may
	   set a return procedure, that is invoked when you press <<Return>>.  

      <entry> <<tkAction>> <index class=module/TkTools<and>numberentry<and>tkAction/
        <synopsis><<<tkAction(?+{ActionP} <= unit)>>>
	 <item>
	   Set a new action procedure.

      <entry> <<tkSet>> <index class=module/TkTools<and>numberentry<and>tkSet/
        <synopsis><<<tkSet(?+{ValI})>>>
	 <item>
	   Set a new value.

      <entry> <<tkGet>> <index class=module/TkTools<and>numberentry<and>tkGet/
        <synopsis><<<tkGet(??{ValI})>>>
	 <item>
	   Get value.

      <entry> <<enter>> <index class=module/TkTools<and>numberentry<and>enter/
        <synopsis><<<enter(?+{B})>>>
	 <item>
	   Hm. I see no difference.

    </list>

  </Section>

  <Section id="section.tkTools.images">
    <Title/Images/
    <index class=module/TkTools<and>images/
    
    <p>

      The function
      
      <<<{TkTools.images ?+{L} ??+{R}}>>>

      takes a list of URLs as input and returns a record of images,
      where the fields are atoms derived naturally from the URLs.

      <p>
      
      First the basename of the URL is computed by taking the last
      fragment of the URL (that is, 'wp.gif' for example).  The
      extension (the part following the period, 'gif' for example),
      determines the type and format of the image. The part of the
      basename that precedes the period yields the feature.

  </Section>

  <Section id="section.tkTools.resolveImages">
    <Title/Resolve Images/
    <index class=module/TkTools<and>resolveImages/
    
    <p>
    <<TkTools.resolveImages>> is deprecated.
    Please use <<TkTools.images>> instead.

</Section>
  
    

</Chapter>
