GLUT/Tk API

Example

Specification: Interface and Implementation Notes

For messages from GLUT back to Tcl, the Tcl command enable_glut_to_tk sets up a list of GLUT-clickable tk-buttons and then glutPressTkButton will perform a virtual button press.

glutCreateWindow4Tcl (GLUT)

Syntax:

int glutCreateWindow4Tcl (const char *title, const char *tk_script, 
                          const char *tk_arg1, const char *tk_arg2);

Semantics:

This is an enhanced version of glutCreateWindow. It creates a GLUT window, returns the window identifier, and suggests using title as its title. It also launches the Tk script named tk_script with which the GLUT process will exchange information. The two additional arguments (tk_arg1 and tk_arg2) are passed uninterpreted to the Tk script, which does whatever it wants (possibly nothing) with them. An application could set up several GLUT-Tk pairs of windows. Choose unique names for your different Tk scripts so that glutCreateWindow4Tcl does not accidentally run the wrong one.

Example:

win_ID = glutCreateWindow4Tcl (my_app_name, "./myapp.tk", "Dummy", 
                               using_sb ? "y" : "n");

This launches myapp.tk and passes two parameters to it - the second apparently indicates whether a spaceball is in use. The identifier of the GLUT window is saved in win_ID. The Tk script could access and save the second parameter with a statement such as:

        set using_sb [lindex $argv 1]

Implementation:

The main trick here is that the system-level identifier of the GLUT window is passed automatically to the Tcl process so that it knows where to send back events, typically as a result of a tk-button being clicked.

glutTclFunc (GLUT)

Syntax:

void glutTclFunc (void (*) (struct tclData *));

Semantics:

This is analogous to other GLUT functions for registering a callback to handle certain input events, e.g. glutKeyboardFunc. The passed function is invoked whenever a message is received from the Tcl process.

Example:

glutTclFunc (handle_tcl_msg);

The function handle_tcl_msg is invoked whenever a message is received from the Tcl process. The data will consist of either a character string or an array of up to five integers. Note that the meaning of these messages is entirely a matter of convention between the Tcl and GLUT processes. Here is a plausible declaration for the handler:

void handle_tcl_msg (struct tclData *xcd);

The data structure looks like this:

struct tclData
{
   int   format;
   int   int_val  [5];
   char  char_val [3000];
};

(This is declared within glut.h, so the application code should inherit it automatically.) The format field has a value of 8 (for character string) or 32 (for integer array). As can be seen, the character string is limited to 3000 characters. This should be enough to hold most filenames or URLs. If more information needs to be passed, the Tk script would have to write a file and pass the filename to GLUT.

Implementation:

This function is implemented just like the other GLUT callbacks: an entry is made in the appropriate GLUT-window data structure, and the handler function invoked as appropriate.

send_to_glut (Tcl)

Syntax:

send_to_glut s CHARACTER-STRING [maximum 3000 characters]
send_to_glut i INTEGER-ARRAY    [maximum 5 integers]

Semantics:

This Tcl command sends a message to the GLUT window that launched the Tcl process.

Example:

send_to_glut s "hi ho, here we go"
send_to_glut i 101 2 33

X Implementation:

The data are transported using ClientMessage events. Integers, and character strings of less than 19 characters can be sent in a single event. Longer character strings are sent as a series of events, re-assembled by the GLUT/Tk library and presented to the application as a single input message.

Windows Implementation:

Strings and integers are transported using WM_COPYDATA events to send the whole corresponding tclData structure intact.

enable_glut_to_tk (Tcl)

Syntax:

enable_glut_to_tk TK-BUTTON-LIST

Semantics:

This Tcl procedure sets up a list of tk-buttons that can be virtually clicked by the GLUT process. The order of the tk-buttons in the list is significant. In the current implementation, checkbuttons, radiobuttons, and scales, as well as plain old tk-buttons, can be enabled.

Example:

set targs {.mouse_mode.bot.spin  .mouse_mode.bot.pick \
           .mouse_mode.bot.move \
           .shapes.rt.tetra .shapes.rt.hexa .shapes.rt.octa \
           .shapes.rt.dodec .shapes.rt.icosa .style.globe }
after 800 {enable_glut_to_tcl $targs}

This sequence sets up a list of clickable tk-buttons, numbered from 1 to 9. E.g. "glutPressTkButton (3)" will simulate a press of the .mouse_mode.bot.move tk-button by mouse button number 1. The enabling operation is normally done near the end of the Tk script, before control is released to the implicit Tk loop. The "after 800" is a hack to allow enough time for the windows to be created.

Implementation:

Enable_glut_to_tk calls tcl_target (see below) for each window in the list, effectively sending the entire list of targets to the GLUT process. The GLUT process can then send events back to any windows in the list. To use enable_glut_to_tk, add the following code to your Tcl program.

proc enable_glut_to_tk {win_list} {
##   puts [format "win-list = %s" $win_list]
   foreach win $win_list {
      tcl_target $win
   }
}

tcl_target (Tcl)

Syntax:

tcl_target WINDOW-ID

Semantics:

This is the lower-level Tcl command used by the enable_glut_to_tcl procedure. Each call adds an entry to the end of the list of Tcl windows maintained by the GLUT process.

Example:

tcl_target .glorp.magic_button

This command tells the GLUT process to add .glorp.magic_button to the list of GLUT-clickable tk-buttons.

X Implementation:

A special ClientMessage event is sent to the GLUT process with the X window identifier of the tk-button. The GLUT process adds the identifier to the end of its list.

Windows Implementation:

Like the X implementation, except that an application-defined message GLUTTK_WINDOW_ID is used to send the Microsoft window identifer.

glutPressTkButton (GLUT)

Syntax:

void glutPressTkButton (int tcl_win_ix);

Semantics:

This function sends an event back to the Tcl process, simulating the effect of a user pressing a tk-button. The Tcl process will have already established a list of acceptable tk-buttons (see above) and this function simply causes tk-button number tcl_win_ix to act as if pressed by mouse button number 1.

Example:

glutPressTkButton (3);

A press of the 3rd tk-button in the list of GLUT-accessible tk-buttons is simulated.

Implementation:

The GLUT process invokes glutButton2Tk (see below) with mouse button number 1 at location 1,1.

glutButton2Tk (GLUT)

Syntax:

void glutButton2Tk (int tcl_win_ix, int button_num, int bx, int by);

Semantics:

This is a lower-level function providing more direct control over the events sent back to the Tcl process. Tk-button number tcl_win_ix acts as if pressed by mouse button number button_num at pixel location bx, by. Tk buttons, radiobuttons, and checkbuttons by default respond to button number 1, and the location is irrelevant. Tk scales respond to button number 2, and the effect does depend on the location. GLUT/Tk offers no support (at present) for mapping between the logical location and pixel location of a Tk scale widget.

Example:

glutButton2Tk (4, 2, 55,3)

A press of the 4th tk-button (presumably a scale widget) in the list of GLUT-accessible tk-buttons is simulated. The effect is as if mouse button number 2 were pressed at a location 55 pixels to the right of, and 3 pixels down from, the upper left corner of the tk-button.

X Implementation:

The GLUT process sends an EnterNotify, ButtonPress, and ButtonRelease event for the specified mouse button number to the appropriate specified Tk sub-window.

Windows Implementation:

The GLUT process sends a BN_CLICKED message for the specified mouse button number to the specified Tk sub-window.

Page last modified: 21 November 2002