Structure of a Rexx/Tk program

DESCRIPTION

This manual entry describes the typical structure of a Rexx/Tk program and also provides information on using the Rexx/Tk functions.

A typical Rexx/Tk program will look like the following simple program:

/**/
Call RxFuncAdd 'TkLoadFuncs', 'rexxtk', 'TkLoadFuncs'
Call TkLoadFuncs

Call CreateWindow

/* 
 * This is a typical dispatch loop if you set the "rexx"
 * options in the widgets to be a name of a subroutine that
 * you write (like below). 
 */
Do Forever
   /* 
    * TkWait returns whatever you typed as the value of the
    * "rexx" option for whatever control is pushed, moved,
    * chosen, etc 
    */
   Interpret 'Call' TkWait()
End
/*
 * Normally you never get here, as the QuitProgram procedure is
 * called when the top level window is closed.
 */
/*
 * Always call TKDropFuncs at the end of the program, particularly
 * under OS/2, otherwise you will be left with the created windows
 * and no way to close them!
 */
Call TkDropFuncs
Return 0

CreateWindow:
/* 
 * make a menu that will be our main window menubar
 */
menubar = TkMenu('.m1')
If rc \= 0 Then Call Abort
/* 
 * Add a File menu to the menubar.  The file menu will 'cascade' off of the menu bar 
 */
menu = TkMenu(menubar'.m1','-tearoff', 0)
If tkrc \= 0 Then Call Abort
label = 'File'
Call TkAdd menubar, 'cascade', 'label', 'menu',
If tkrc \= 0 Then Call Abort
/* 
 * now add items to the File menu; just a Quit for now
 */
Call TkAdd menu, 'command', '-label', 'Quit', '-rexx', 'QuitProgram'
If tkrc \= 0 Then Call Abort
/* 
 * attach the menubar to the main window 
 */
Call TkConfig '.', '-menu', menubar
If tkrc \= 0 Then Call Abort

Return 0

Abort:
Say 'Error in program:' TkError()
/*
 * Always call TKDropFuncs at the end of the program, particularly
 * under OS/2, otherwise you will be left with the created windows
 * and no way to close them!
 */
Call TkDropFuncs
Exit

QuitProgram: Procedure
Say 'Exiting from sample...'
/*
 * Always call TKDropFuncs at the end of the program, particularly
 * under OS/2, otherwise you will be left with the created windows
 * and no way to close them!
 */
Call TkDropFuncs
Exit

Some usage notes

• All Rexx/Tk functions set the Rexx tkrc variable to be 0 if the function succeeded, or a negative number on error, or a positive number on warning. The text of the message is available by calling the TkError function.
• All widgets are derived from the toplevel widget, which is the application's main window, which has a name of '.'. Hence all widgets derive their name from the toplevel window's name. Thus the name of a label widget l1 within a frame widget f1 is .f1.l1
• The Tcl language is case-sensitive, so be careful when using Tcl commands or widget names; they must be quoted.

Some general design notes

In general, the names of the Rexx/Tk functions match the names of the Tk commands with the same functionality.
eg Tk: menu Rexx/Tk: TkMenu
Where a Tk command has sub-commands; and most do, the equivalent Rexx/Tk function will be named as the Tk command and the Tk sub-command. eg. Tk: menu post Rexx/Tk: TkMenuPost

Where a Tk sub-command is common between multiple Tk commands; like configure, Rexx/Tk defines a common function; TkConfig (yes its an abbreviation!)

Where a Tk widget allows the creation of another object type within that widget, the Rexx/Tk function will not use the full Tk sub-command strings
eg. canvas create oval Rexx/Tk: TkCanvasOval