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

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 rc \= 0 Then Call Abort
label = 'File'
Call TkAdd menubar, 'cascade', 'label', 'menu',
If rc \= 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 rc \= 0 Then Call Abort
/* 
 * attach the menubar to the main window 
 */
Call TkConfig '.', '-menu', menubar
If rc \= 0 Then Call Abort

Return 0

Abort:
Say 'Error in program:' TkError()
Exit

QuitProgram: Procedure
Say 'Exiting from sample...'
Exit

Some usage notes

• All Rexx/Tk functions set the Rexx rc variable to be 0 if the function succeeded, or a negative number on error, or a positive number on warning.
• 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

Differences between Rexx/Tk 004 and later releases

With the introduction of many more functions, it became apparent that some minor changes needed to be made to make the interface more consistent and flexible. The following changes have been made:

• All Rexx/Tk functions set the Rexx rc variable and never cause a syntax error to be generated and cause the program to stop.
• The introduction of the -rexx options as documented in the Extra Rexx/Tk Options man page. This enables the programmer to execute Tcl/Tk commands or Rexx commands in response to widget actions.
• Any values passed as parameters to the -rexx options will be quoted. This was not the case in the 004 beta.