next up previous contents
Next: 8.3 A simple example Up: 8 Designing Custom Qddb Previous: 8.1 Requirements

8.2 The tools

The Fx toolkit consists of three major Itcl classes: Fx_Menubar, Fx_Frame, and Fx_Entry. The Fx toolkit is initialized by a call to Fx:Init, which must be called before accessing any other Fx procedures or declaring any Fx class instances.

8.2.1 Fx:Init

The Fx toolkit routine Fx:Init must be called before creating the menubar, frames, and entries. You must set the global Tcl variable fx_config_dir, which points to a directory relative to your home directory, before calling Fx:Init. It holds your application-specific initialization code. The typical initialization sequence for an application looks like this:

    lappend auto_path $qddb_library/fx ;# autoload Fx toolkit
    if {[info exists blt_library]} {
        lappend auto_path $blt_library ;# autoload BLT library
    if {[catch "qddb_schema open [lindex $argv 0]" s] != 0} {
        puts "Cannot open Schema for relation: [lindex $argv 0]"
        puts "$s"
        exit 1
    set fx_config_dir .myapplication_config
    Fx:Init $s

Fx:Init takes care of (1) executing personal and global configuration files, (2) initializing fonts and other resources, and (3) setting up the key/mouse bindings.

8.2.2 Fx_Menubar

Fx_Menubar should be one of the first Tcl commands after calling Fx:Init. It creates the standard menubar, menubuttons, and menus for the Fx toolkit. It also controls the current schema, tuple, and view. Since Fx is very configurable, Fx_Menubar has many options.

Fx_Menubar is actually an Itcl class. When it is invoked, it creates a menubar instance. You can then link Fx_Frame and Fx_Entry instances to that menubar. The invocation that creates a new instance called menubar is as follows:

    Fx_Menubar menubar -w .menubar -schema $s \
        -config_dir .myapplication_config -array my_tuple_array

The above command creates not only creates the instance (called menubar), it also constructs a Tk frame containing the menubar (called .menubar). It also specifies the application's configuration directory with the -config_dir .myapplication_config option. The Tcl associative array that will hold the contents of the current tuple (in Add Mode, Change Mode, or Read-only Mode) is given by the -array my_tuple_array option.

You can specify actions (as Tcl commands) to perform before and after entering any of the modes. To do this, you specify the appropriate -after<modename>mode or -before<modename>mode option to the Fx_Menubar command. For example, to execute a Tcl command that sets a default value upon entering Add Mode, you could do the following:

    Fx_Menubar menubar -w .menubar -schema $s \
        -config_dir .myapplication_config -array my_tuple_array \
        -afteraddmode {
            global my_tuple_array
            uplevel \#0 {set my_tuple_array(MyAttribute) "Some default value"}

Most of the special options are interactively configurable from the menubar, but sometimes it is useful to restrict the user to certain options. All the menus (except Help and Configure) allow you to specify a Tcl list to evaluate after a menu button is selected. These options have the form -afterpost_<menuname>, where <menuname> is one of file, edit, modes, view, and templates. The -afterpost_ options are typically used to disable or enable menu entries based on some condition.

You can add your own menu buttons to the menubar by setting up the frame and declaring one Tk menubutton and menu before calling Fx_Menubar. If the frame you pass to Fx_Menubar already exists, Fx_Menubar will not create a new one. The new buttons are passed to Fx_Menubar by an -auxbuttons option. For example:

    frame .mb ;# set up the frame; Fx_Menubar will notice it exists.
    pack .mb -side top -fill x
    menubutton .mb.newitems -text "New Items" -menu \
        -underline 0
    # don't pack .mf.newitems if you want to maintain the Fx_Menubar's order
    menu add command -label "One new item" -underline 0 add command -label "Two new items" -underline 0
    Fx_Menubar menubar -w .mb -schema $s \
        -config_dir .myapplication_config -auxbuttons .mb.newitems

By convention, all menu buttons are named by their text label in all lower case. The corresponding menu is called menu. For example, to add a new item to the View menu button, you might:

    Fx_Menubar menubar -w .mb -schema $s -config_dir .myapp_config add command -label "New view command"

8.2.3 Fx_Frame

The command Fx_Frame (again, an Itcl class) instantiates an Fx frame, which associates a structured (and possibly expandable) attribute with a Tk frame. If the attribute given by the -attr option is expandable, then the command will create Add, View, and Del buttons. An example of creating an instance of Fx_Frame called ``myframe.f'' might be:

    Fx_Frame myframe.f -w .myframe.f -attr Attr1.Attr2 -setschema $s \
        -labelfg deeppink

The -w and -attr options are mandatory. The -setschema option must be supplied on the first call to Fx_Frame. After that, it is unnecessary; setschema is a common variable for the Fx_Frame class.

The Fx_Frame instance creates a Tk frame (specified by -w), an internal frame called f_0, a label f_0.l, and possibly three buttons f_0.b_add, f_0.b_view, and f_0.b_del. These widgets may be repacked with the Tk pack command if you want to arrange them in a particular way.

After an Fx frame has been built for an attribute, the application usually builds subframes for its subattributes by further calls to Fx_Frame. Leaf attributes are given Tk frames by a call to Fx_Entry, described below. After all the subattributes have been treated, the outer Fx frame instance is generally invoked with the -focus option to specify the entry where focus should be placed when the Add or View button is pressed for that Fx frame. For example, we might have an Fx frame with one Fx entry:

    Fx_Frame myframe -w .myframe -attr A;# outer attribute
    Fx_Entry myframe.b -w .myframe.b -attr A.B;# leaf attribute
    myframe configure -focus [myframe.b GetEntry]

The buttons (Add, View, Del) perform specific operations attribute instances. You can tell Fx to evaluate a Tcl command before and/or after each operation with the -after<op> and -before<op> options, where <op> is one of add, view, and delete. For example, you might want to prevent the user from deleting non-empty instances:

    Fx_Frame myframe -w .myframe -attr A \
        -beforedelete {
            if {[qddb_instance isempty $view A] == 0} {

Because the command lists are evaluated (in an environment in which view is set), the return statement returns from the DelInstance method instead of deleting the instance.

8.2.4 Fx_Entry

The command Fx_Entry (again, an Itcl class) instantiates an Fx entry, which assiciates a leaf (and possibly expandable) attribute with a Tk frame. You may place the Fx entry's Tk frame anywhere in the Tk widget hierarchy; traditionally, it is placed in its parent Fx frame's Tk frame.

Here is an example that creates an instance of Fx_Entry called myframe.f.f:

    Fx_Entry myframe.f.f -w .myframe.f.f -attr Attr1.Attr2.Attr3 \
        -setschema $s -labelfg blue -searchfor_entry [menubar SearchForEntry]

This example would place the new entry's frame inside the parent's Tk frame .myframe.f, which we declared earlier.

The -w and -attr options are mandatory for each call to Fx_Entry. The first call to Fx_Entry must also contain the -setschema and -searchfor_entry options. After the first call to Fx_Entry, you need not specify them again; they are common variables for the Fx_Entry class. The -searchfor_entry option establishes the Tk widget path for the "Search for:" entry. Usually, this value is discovered by invoking the Fx_Menubar instance's SearchForEntry method.

The Fx_Entry instance creates a Tk frame (specified by -w), an internal frame called f_0, a label f_0.l, and possibly three buttons f_0.b_add, f_0.b_view, and f_0.b_del. These widgets may be repacked with the Tk pack command if you want to arrange them in a particular way.

You can specify default entry types with the -type option. A type may be one of: Entry, Text, or Radiobutton (case is sensitive). If the type is Radiobutton, then you can specify a set of default values with the -default_values option. Each default value will produce one radio button with the value as the label.

8.2.5 Associating Fx_Frame and Fx_Entry with the Fx_Menubar

After you have created all the instances of Fx_Frame and Fx_Entry that you want, you must link the instances with the menubar instance. You can accomplish this with the following Tcl command, assuming your Fx menubar instance is called menubar:

    menubar configure -instances [Fx_Entry :: GetInstances] \
        -frames [Fx_Frame :: GetInstances]

next up previous contents
Next: 8.3 A simple example Up: 8 Designing Custom Qddb Previous: 8.1 Requirements

Herrin Software Development, Inc.