entity's tcl API

This document describes the concepts of entity's tcl API. The complete reference of new tcl commands is found in another document. Documentation about the gtk tag reference and the perl API are found elsewhere.

1. embedding tcl code between the tags <tcl> and </tcl>.

The tcl-code is evaluated, once a xml-tree is created. So the most simple embedded tcl code could look like this:

    #!/usr/local/bin/entity
    <app>
      <tcl>
          puts [list hello, world]
      </tcl>
    </app>
    

The message "hello, world" is printed to stdout while entity parses the file, that is -- only once.

2. binding events to event handlers

The gtk rendering engine must be told when to call tcl code. This is accomplished with binding events to tcl procs. Entity supports multiple languages which can even be mixed within one application. There are two ways to call entity to use tcl:

1. the attribute default-lang="tcl" in the tag <app> -- <app default-lang="tcl">
2. prefixing the callback name with the language name tcl separated by a colon -- tcl:my_handler

If no language is specified it defaults to perl. The following example prints a well-known message to stdout each time a key is pressed. The event handler hello is bound to the event onkeypress.

    #!/usr/local/bin/entity
    <app default-lang="tcl">
      <window title="simple" onkeypress="hello">
        <label text="hello"/>
        <tcl>
          proc hello args {
            puts [list hello, world]
          }
        </tcl>
      </window>
    </app>
    

3. query and modify the xml

The tcl API introduces a set of commands to query and / or modify xml code from within your tcl code. All commands from the tcl API reside in the namespace ::Entity. The commands can be imported to the current namespace, wich the usual restriction that they should not conflict with existing command names. The following example examples creates an entry widgets whose content is printed to stdout each time the return key is pressed.

    #!/usr/local/bin/entity
    <app default-lang="tcl">
      <window title="entry">
        <entry name = "fred" onenter = "dump"/>
        <tcl>
          namespace import ::Entity::*
          proc dump args {
            puts [get_attr entry.fred text]
          }
        </tcl>
      </window>
    </app>
    

4. scope

Each application evalutes tcl code in a unique namespace, which is different from namespaces of other applications. Entity takes care of creating unique namespaces for each application. The code of the previous example is actually evaluated like this

    namespace eval namespace7 {
      namespace import ::Entity::*
      proc dump args {
        puts [get_attr entry.fred text]
      }
    }
    

where namespace7 could be an arbitrary name chosen by entity. Note that importing Entity::* wouldn't work because there's no namespace Entity within the namespace7.

Entity always uses the proper namespace when calling event handlers. Calling the event handler of the previous example would actually be accomplished like this: (where path is the path of the calling node, see the reference)

    namespace eval namespace7 {
      dump path
    }
    

This should be kept in mind when accessing elements of different namespaces. The usage of global variables is deprecated (as always). To share variables between different procs the tcl variable should be used:

    #!/usr/local/bin/entity
    <app default-lang="tcl">
      <tcl>
        variable pi 3.1415927
        proc dump_pi args {
          variable pi
          puts $pi
        }
      </tcl>
    </app>