Table Of Contents (show)

1. Gui
2. Tag-Names
3. Attributes
1. 3.1 The -pos attribute.
2. 3.2 The -scroll attribute
3. 3.3 The -conf attribute.
4. 3.4 The -id and -gid attributes.
5. 3.5 The -useid attribute
4. The -sub* attributes
1. 4.1 The -subconf attribute
2. 4.2 The -subpos attribute
3. 4.3 The -subattr attribute
5. Message Attributes
1. 5.1 The -msg attribute
2. 5.2 The -msgopts attribute
3. 5.3 The -ns attribute
6. Implicit -id
7. Conventions
8. Gui in a .tcl file
9. Demo Applications
10. XML

1. Gui

Gui and styles provide a simplified way to define Tk user interfaces using an XTL description file as input.

See the Gui Introduction for a quick overview of Gui.

2. Tag-Names

Tag names for widgets use the class name (See the GuiRef for list of tags). Gui is usually used in conjunction with styles, to provide fast application layout and prototyping. It reduces code by eliminating the need to explicitly manage widget windows.

3. Attributes

Attributes are used to control various metrics of the layout. When not using XML, attributes always have a dash prefix.

3.1 The -pos attribute.

The -pos attribute is used to specify positioning, anchors and stickiness. It is probably the most important attribute to know. eg.

{Frame + -pos *} {
   {Entry - -pos _} {}
   {Text - -scroll se -pos *}  {}
   {Button} Ok
}

The two most important values are * which means expand and fill all, and _ which means fill horizontal.

3.2 The -scroll attribute

The -scroll attribute is used to setup scrollbars. The above example show use of -scroll to set scrollbars on the south and east sides. Use * to have auto-managed scrollbars.

3.3 The -conf attribute.

The -conf attribute can be used to pass attributes directly to a widget. eg.

{Frame +} {
   {Entry - -conf {-bg blue -bd 1} } {}
   {Text - -conf {-undo 1}}  {}
}

Generally, it is better to avoid this and use styles if at all possible.

3.4 The -id and -gid attributes.

The -id attribute uniquely identifies an element and is used as the tail portion of a windows path name. The -gid attribute defines groups for elements. This is primarily useful with styles. For example:

style {
   ^grp1  { -bd 1 }
   .myent { -relief sunken }
   .mytxt { -relief raised }
}
{Frame +} {
   {Entry - -gid grp1 -id myent} {}
   {Text  - -gid grp1 -id mytxt}  {}
   Button Done
}

3.5 The -useid attribute

The -useid attribute is used to replicate the body of another element having the given -id. See the example.

4. The -sub* attributes

The -sub* attributes are used to apply values to child elements. Prefixing a '&' to a value means it is to be recursively applied.

4.1 The -subconf attribute

The -subconf attribute is used to set -conf for all child elements.

4.2 The -subpos attribute

The -subpos attribute is used to set -pos for all child elements.

4.3 The -subattr attribute

The -subattr attribute is used to set attributes for all child elements.

5. Message Attributes

The message attributes deal with interfacing a Gui with applicationcode.

5.1 The -msg attribute

The -msg attribute specifies the name of proc or command to call in the default namespace. This can be used to override the default for buttons, eg.

    {Button - -msg DoIt} Ok

5.2 The -msgopts attribute

The -msgopts attribute specifies options to add to the command call. The substitutions %I and %W apply.

  script {
    proc Ok {_ id} { upvar $_ {};  DoIt $_; destroy $(w,$id) }
    proc Cancel {_ w} { destroy $w }

  }
  {Toplevel +} {
    {Button - -msgopts %I} Ok
    {Button - -msgopts {%W %_}} Cancel
  }

5.3 The -ns attribute

The -ns attribute specifies a sub-namespace to use for binding a -msg to a command/proc. By default, the namespace of the application that created the Gui is used.

6. Implicit -id

If you do not explicitly provide a -id to an element, Gui will generate one based on the lowercased class name of the widget, followed by an underscore and a number. For example, the following is valid:

  style {
    .canvas_1 { -height 50 }
    .canvas_2 { -height 100 -bg blue }
  }
  Canvas {}
  Canvas {}

The two ids canvas_1 and canavs_2 are autogenerated and used as the windows tail path.

7. Conventions

Reading GUI layouts can be simplified by placing these commonly used attributes first: -id, -pos, -subpos and -scroll.

8. Gui in a .tcl file

A .gui application can be executed directly by wize. It can also be run as a .tcl file using Tk::gui::create as follows:

#!/usr/bin/env wize
# "demo.tcl"
package require Mod
namespace eval ::app::demo {
   proc Main {_ args} {
   }

   Tk::gui create {
      {Toplevel +} {
         # ...
      }
   }
}

9. Demo Applications

Wize contains numerous example applications using Gui. To see the list run:

  wize  / Gui/?

For example you can run the Sqlite database GUI front-end Gsqlite using:

  wize  / Gui/Gsqlite

10. XML

Gui provides dynamic Tk user interface generation from XTL nested-pairs or from XML. eg.

{Frame + -pos *} {          <Frame pos="*">
   Entry  {}                   <Entry />
   {Text - -pos *} {}          <Text pos="*" />
   Button Ok                   <Button>Ok</Button>
}                           </Frame>

For the most part, tag names in GUI are based on widget class names (See the GuiRef for list of tags). Gui is usually used in conjunction with styles, to provide fast application layout and prototyping. It reduces code by eliminating the need to explicitly manage widget windows.