1.  Gui Tutorial

The following example demonstrates the evolution of a simple editor using Gui.

See Demos for more complex and complete examples.

2.  A Basic GUI

Following is the framework for a simple editor:

#!/usr/bin/env wize
# "File gtest1.gui (this is a comment)"
{Toplevel +} {
   {Text - -pos *} {}
   {Frame + -pos _} {
      {Button - -pos l} Quit
      {Entry - -pos l*} {}
   }
}

This gui contains no code, but simply lays out a number of widgets using the -pos attribute.

We run it using:

  % wize gtest1.gui

#or, assuming wize is in the unix path..

  % chmod u+x gtest1.gui
  % ./gtest1.gui

Note: Elements begining with #are interpreted by gui as comments, but unix uses #! to execute wize.

3.  Adding Style and Code

The following extends the basic gui:

#!/usr/bin/env wize
# "File gtest2.gui"
{Toplevel +} {
   {title} "A simple editor"

   {script} {
      proc Quit {_} { ::Delete $_ }
      proc Main {_ args} { upvar $_ {};  set (v,status) "Starting" }
   }

   {style} {
      Button  { -pady 0 }
      .txt    { -bg LightBlue }
      .status { -state disabled -disabledforeground Black }
    }

   {Text - -id txt -scroll * -pos *} {}

   {Frame + -pos _ -subpos l} {
      {Button - -id open} Open
      {Button - -id save} Save
      {Button - -id quit} Quit
      {Entry - -id status -pos l*} {}
   }
}

We've added a few more Buttons and three new tags:

3.1  title

The title tag provides a title for the window.

3.2  script

The script tag is used to provide code for the application.

The proc Main and Cleanup may be defined for getting control at startup and shutdown.

The script is evaluated in the applications namespace (this defaults to ::app::FILE where FILE is the basename of the file).

Errors, if any, will not be seen unless run with wize -Wall.

3.3  styles

The styles tag provides configuration to apply to elements of the gui. We've have added -id attributes to the GUI elements to facilitate this.

4.  Finishing

To finish the application, we add code to handle file open and save. Also, the style has been extended to define gui attributes.

#!/usr/bin/env wize
# "File gtest3.gui"

{script} {
    *array _ { fn {} }

    proc Open {_ {fn {}}} {
        upvar $_ {}
        if {$fn == {}} { set fn [tk_getOpenFile] }
        if {$fn == {}} return
        $(w,txt) delete 1.0 end
        Text insert $(w,txt) end [*fread $fn]
        set (fn) $fn
        set (v,status) "Loaded $fn"
    }

    proc Save {_} {
        upvar $_ {}
        if {$(fn) == {}} {
            set fn [tk_getSaveFile]
            if {$fn == {}} return
            set (fn) $fn
        }
        set data [Text get $(w,txt) 1.0 end]
        *fwrite $(fn) $data
        set (v,status) "Saved $(fn)"
    }

    proc Quit {_} { ::Delete $_ }
    proc Main {_ args} {
       upvar $_ {}
       set (v,status) "Starting"
       if {[llength $args]>1} {
          Open $_ [lindex $args 0]
       }
    }

}

{Toplevel +} {
   {title} "A simple editor"
   {style} {
      Toplevel {
        @guiattr {
           -tip {
             open "Open a new file to edit"
             save "Save to file"
             quit "Exit the edit application"
          }
          -icon {
             open fileopen
             save filesave
             quit exit
          }
        }
      }
      .txt    { -bg LightBlue }
      .status { -state disabled -disabledforeground Black }
      Button { -pady 0 }
   }

   {Text - -id txt -pos *} {}

   {Frame + -pos _ -subpos l} {
      {Button - -id open} Open
      {Button - -id save} Save
      {Button - -id quit} Quit
      {Entry - -id status -pos l*} {}
   }
}

5.  Embedding a GUI

A Gui application can be embedded in a .tcl file quite simply using Tk::gui::create:

#!/usr/bin/env wize
# "gtest.tcl"

package require Mod

namespace eval ::app::gtest {

   Mod export

   proc Main {_ args} {
      # ...
   }

   Tk::gui create {
      {Toplevel +} {
         {Text - -pos *} {}
         {Frame + -pos _} {
            {Button - -pos l} Quit
            {Entry - -pos l*} {}
         }
      }
   }
}

The Main proc is the entry point. After the program is running, new instances can be created by calling ::app::gtest::new.

6.  Doing More

See GuiTutorial2.

© 2008 Peter MacDonald