Controls from FORTRAN

By Glenn Forney, Gaithersburg, MD

Previous articles and examples in MacTutor have shown how to incorporate features of the Macintosh user interface such as menus and windows into FORTRAN applications. This article will show how to implement simple controls such as buttons, checkboxes and radio buttons.

The text will identify which tool box routines to call, where to call them and why. The example is a modified version of the shell program demo.for supplied by MicroSoft. It will give the details of how to implement controls in FORTRAN.

Control BASICS

The three types of standard controls: buttons, checkboxes and radio buttons are on/off switches and have control definition ID's of 0, 1 and 2. The scrollbar is a type of control known as a dial since it can take on more than two values. It has a control definition ID of 16. These ID's specify to the control manager what type of control to create.

A control is either active or inactive, i.e. highlighted or unhighlighted. A control can also be visible or invisible. Only when a control is active and visible will it respond to the mouse.

A control has another attribute known as a part number. Each part of a control has a unique part number. Simple controls such as buttons, check boxes and radio buttons have only one part and hence only one part number. The scroll bar on the other hand is more complicated and has five parts: elevator box or thumb, up arrow, down arrow, up button and down button. Part numbers and control definition ID's for the standard controls are listed in Figure 1.

Figure 1. Part codes and ID numbers for Standard Controls

Records Needed to Implement Controls

Control Record. A record is a Pascal data type used on the Macintosh to describe or specify windows, dialogs, controls, events, etc. Each control that is defined has a control record associated with it. A control record consists of 13 fields. Figure 2 lists these fields and gives decimal offsets which can be used to access the individual fields of the control record from FORTRAN. For example if CONTROLBEG is an INTEGER*4 variable containing the beginning address of the control record then the FORTRAN statement LONG(CONTROLBEG+4) will give the contrlOwner field of the control record. This field points to the window that contains the given control. Most of the fields in the control record can be accessed through tool box calls rather than directly with the LONG function. An exception is the first field of the control record, named nextControl, which is a handle to the next control in the window's control list. The fields of a control record that we will use to implement controls are: nextControl, controlValue and contrlRfcon.

The parameter, nextControl, is a handle for the next control record in the window's control list. So the control record for the next control in a window starts at the address given by the FORTRAN statement:

 LONG(LONG(nextControl))

When handling activate events one needs to activate or deactivate all controls in a window. The field nextControl then serves as the link which connects all controls belonging to a window.

The field contrlValue in the control record contains the value of the control. For simple controls this field simply indicates whether the control is on or off. A window can have several controls located in it. The application needs to know which one of the window's controls was pressed. This is done with the contrlRFCon field.

Our control example with two windows

The parameter contrlRFCon is used to store information about a control. This information could be an integer value that indexes a FORTRAN array describing the window's controls or a handle to a more complex data structure on the heap. In general these data structures allow the FORTRAN program to distinguish one control from another. For example when a mouse down event occurrs in a control, there is no way of knowing from the event record which control in the window was pressed. In the example program we simply number the controls 1, 2, 3, 4, 5 and set the controlRfCon field to these values.

Window Record. A second record needed to handle controls is the window record. The controlList field of this record gives a handle to the first control in the window's control list. So if WINDOWBEG is the address of the beginning of a window record then LONG(WINDOWBEG+Z'8C') is the handle to the control record of the first control in a window. If there are no controls in a window then this value is zero. The value Z'8C' is the hex value of the offset from the beginning of a window record. It indicates the location of the controlList field in the window record. For an illustration of this process see the code segment below the 'CASE(ACTIVATEEVT)' statement in the main event loop of the example program.

Event Record. Another record of interest when handling controls is the event record. Some examples of possible events are: the mouse is clicked ( a mouse down event), a window is drawn or erased ( an activate event), a window is covered or uncovered ( an update event). The individual fields of an event record are usually accessed with FORTRAN equivalence statements. The compiler does the work of computing offsets to individual fields of the event record rather than the programmer.

The event record gives a description of the state of the Macintosh when the event occurred, e.g. the time in ticks since startup, the mouse location in global coordinates, state of the keyboard, etc. We are interested in the fields: where, modifiers and message. When a mouse down event occurrs in the content region of a window, the where field, after converting to local coordinates with GLOBALTOLOCAL, indicates the mouse down location in the window. For an activate event, the modifiers field indicates whether a window should be activated or deactivated. For an update or activate event, the message field gives a pointer to the window where an update or activate event occurred. So when implementing controls we need to access these fields of the event record to determine how the program should respond to an event.

All of the tool box routines that we want to use are documented in Inside Macintosh. To use these routines from FORTRAN one needs to know how to use toolbx.sub to implement PASCAL calls in FORTRAN. Figure 3 gives a list of common PASCAL data types and their FORTRAN counter parts. This along with the example program should aid in implementing other undocumented tool box routines.

Creating Controls

There are several methods for creating controls in FORTRAN. The first method is to create it in FORTRAN using the tool box routine NEWCONTROL. Another method of creating a control is to read in a control resource that was compiled with RMAKER using the tool box routine GETNEWCONTROL. The programmer needs to fill in the resource id number and the pointer to the window the control in which will be. As in NEWCONTROL the routine GETNEWCONTROL returns a handle to the newly created control. A third method is to read in a list of dialog items from a resource with the routine GETNEWDIALOG.

Controls and Events

Activate Event. When implementing a control in an application one needs to be concerned with three events. These are activate, update and mouse down events. If a user has controls in a window where an activate event occurs then (s)he is responsible for highlighting or unhighlighting the control. This is done with the tool box routine HILITECONTROL. The programmer passes a control handle and a highlight code of 0 or 255 to HILITECONTROL where 0 means highlight (the control is to become active) and 255 means unhighlight. To know whether to highlight or unhighlight, test the first bit of the modifiers field in the event record. If the first bit is 1 then the window is being activated so the control needs to be highlighted, otherwise the bit is 0 and the control needs to be unhighlighted. A code segment to illustrate this is listed under the CASE(ACTIVATEEVT) section of the example program.

Update Event. The next event of concern is the update event. An update event is passed to your application when the system determines that a window's contents have been changed and hence need to be updated. To handle an update event in a window that contains one or more controls, one simply redraws the controls by passing a window pointer to the tool box routine DRAWCONTROLS. The window manager redraws the window, the programmer however is responsible for redrawing the controls and any other contents in the window. Any output to the window while updating must be bracketted by calls to BEGINUPDATE and ENDUPDATE. BEGINUPDATE clears the update region of the window. If these routines are not called then after the controls are drawn the system still thinks that the window needs to be updated so another update event is generated and the controls are redrawn and so on. The result is that the Macintosh "locks up" and the window contents exhibit a rapid flickering.

Mouse Down Event. There are several types of mouse down events that can occur. For example the mouse can be clicked in a menu bar, in a system window or in the content region of an application window. The mouse down event in which we are interested is when the mouse is detected in the content region of an application window. In this case we need to know if it was clicked in a control.

Each control belongs to a particular window. The coordinates used to express the location of the control inside the window must be in the window's local coordinates. When a mouse down event occurs, the mouse location is given in global coordinates by the 'where' field of the event record. So the mouse position must be converted to local coordinates using the tool box routine GLOBALTOLOCAL. Next the application needs to call the routine FINDCONTROL to determine if the mouse was pressed in a visible, active control. FINDCONTROL is passed the mouse location in local coordinates and a window pointer. It returns a handle to the selected control and the part number where the mouse was down if the control was visible and active, otherwise FINDCONTROL returns a zero.

If FINDCONTROL determines that the mouse was clicked in a control then the application calls TRACKCONTROL to see if the mouse is still in the control when the mouse button is released. If this is so then TRACKCONTROL returns the part number of the control. It is up to the application then, to get the value of the control with GETCVALUE, set it to a new value with SETCVALUE and perform the action that the application requires. For example if an application window has a scroll bar that contains text and the control is set to some new value then the control manager will redraw the control. The application is responsible for redrawing the text to reflect the new value of the control.

All of these ideas are put together in the example program that follows. It is relatively short but it does exhibit all of the features necessary to implement a simple control.

Concluding Remarks

The tool box routine TRACKCONTROL has a calling argument named procPTR. The argument procPTR is a pointer to a procedure that TRACKCONTROL calls periodically while the mouse is down in a control. This is how auto scrolling is done. In standard FORTRAN it is not clear how you would pass a pointer to a FORTRAN routine through the calling list of TRACKCONTROL or any other tool box routine. Absoft has solved this problem by writing an Assembly language "glue" subroutine that returns the pointer to a FORTRAN subroutine. A future article is needed that discusses this glue routine for scrolling text windows.

[Implementation notes: In compiling and executing this example, we had the usual pains with the latest Microsoft Fortran 2.1 version. For one thing, the include statement for the menu.inc file produced an error! It seems someone either left out the last line in that include file or forgot to close the line with a ")". We wonder how many other include files also have bugs! Once over that problem, we had to get the include statements to specify the complete path name of the files. We got a lot of compile errors on this one. We finally got it to work after re-typing the path name in by hand, but never did really figure out what the compiler didn't like. Then came the wonderful HFS brain damaged linker! It seems the linker doesn't like complete path names. We had to specify a partial path name from the current level where the linker was located down to our file. Guess the linker can only look down, not up. At any rate, we finally got a compilation and linkage. The linker script produces an application file. And the compiler produces an application file! And the resource compiler also produces an application file, so now you have three application files floating about, only one of which is the "real" application! So be careful. We called the output of the compiler, "control example apl", then called the linker output "control" and finally, the RMaker output, "RealControl" since it was the "real" one. As you can guess, we compiled, then linked in the run time library, and finally merged the resources in with RMaker to produce the final application. -Ed]

      PROGRAM CONTROLEXAMPLE
*
*   THIS PROGRAM IMPLEMENTS SIMPLE CONTROLS IN FORTRAN
*
*   AUTHOR: GLENN FORNEY
*   DATE:   8/86

      IMPLICIT NONE         ! HELPS KEEP US OUT OF TROUBLE
*
*   THE FOLLOWING INCLUDE FILES ARE INCLUDED WITH MS FORTRAN
*   YOU SHOULD CHANGE THE PATHNAMES TO MATCH YOUR SETUP
*
 include XP40-6:MacFortran:IncludeFiles:window.inc
 include XP40-6:MacFortran:IncludeFiles:dialog.inc
 include XP40-6:MacFortran:IncludeFiles:event.inc
 include XP40-6:MacFortran:IncludeFiles:menu.inc
 include XP40-6:MacFortran:IncludeFiles:control.inc
 include XP40-6:MacFortran:IncludeFiles:quickdraw.inc
 include XP40-6:MacFortran:IncludeFiles:misc.inc
*
*  DECLARATIONS
*
      INTEGER*4 TOOLBX               ! THE TOOL BOX INTERFACE
      INTEGER*4 WINDOW               ! GENERAL PURPOSE POINTER
      INTEGER*2 RECT(4)              ! RECTANGLE COORDINATES
      INTEGER*4 CONTROL_WINDOW ! POINTER TO THE CONTROL WINDOW
      INTEGER DUMMYHANDLE            ! HANDLE TO DUMMY WINDOW
      INTEGER MENUHANDLE             ! HANDLE TO MENUS
*
* WCONTRLLIST IS AN OFFSET THAT GIVES A 
* HANDLE TO THE FIRST CONTROL IN A WINDOW
* HEX 8C = DECIMAL 140, SO WCONTROLLIST BEGINS AT THE
* 140'TH BYTE IN THE WINDOW RECORD
*
      INTEGER WCONTROLLIST
      PARAMETER (WCONTROLLIST = Z'8C')
*
* DECLARATIONS FOR VARIOUS EVENTS AND MOUSE DOWN LOCATIONS
*        
      INTEGER ACTIVATE,CONTROL_HAN,SAVEPORT
      INTEGER MOUSEDOWN,UPDATEEVT,ACTIVATEEVT
      PARAMETER (MOUSEDOWN=1,UPDATEEVT=6,ACTIVATEEVT=8)

      EVENTMASK = -1  ! PROCESS ALL EVENTS
*
*  CLOSE MACFORTRAN I/O WINDOW (NEVER MAKE A DISPOSEWINDOW
*       CALL ON THIS WINDOW SINCE WE DIDN'T ALLOCATE IT)
*
      WINDOW = TOOLBX(FRONTWINDOW)
      CALL TOOLBX(CLOSEWINDOW,WINDOW)
*
* INITIALIZE MENU
*
      MENUHANDLE = TOOLBX(NEWMENU, 1,CHAR(7)//"OPTIONS")
      CALL TOOLBX(APPENDMENU,MENUHANDLE,
     +        CHAR(32)//"CONTROL WINDOW;DUMMY WINDOW;QUIT")
      CALL TOOLBX(INSERTMENU,MENUHANDLE,0)
      CALL TOOLBX(DRAWMENUBAR)
*
*   READ IN CONTROL_WINDOW WITH "REGULAR" CONTROLS FROM 
*   RESOURCE ID 128, 0 MEANS ALLOCATE STORAGE ON HEAP, -1
*   MEANS BRING WINDOW IN FRONT OF ALL OTHER WINDOWS
*
        CONTROL_WINDOW = TOOLBX(GETNEWDIALOG,128,0,-1)
*
*   PLACE INFORMATION IN CONTROL_WINDOW'S REFCON FIELD 
*   TO BE USED BY APPLICATION
*
      CALL INITVALUES(CONTROL_WINDOW,2)
*
*   SET UP DUMMY WINDOW TO MAKE SURE UPDATE AND ACTIVATE
*   EVENTS ARE HANDLED RIGHT
*
      RECT(1) = 40
      RECT(2) = 30
      RECT(3) = 300
      RECT(4) = 270
      DUMMYHANDLE = TOOLBX(NEWWINDOW,0,RECT,
     +      CHAR(12)//"DUMMY WINDOW",.TRUE.,4,-1,.TRUE.,0)
     
      RECT(1) = 25 ! WINDOWDRAG CONTSTRAINTS
      RECT(2) = 25
      RECT(3) = 300
      RECT(4) = 500
*
*  MAIN EVENT PROCESSING LOOP
*
      DO
        IF (TOOLBX(GETNEXTEVENT,EVENTMASK,EVENTRECORD)) THEN

          SELECT CASE (WHAT)

            CASE (MOUSEDOWN)      ! HANDLE MOUSE DOWN
              CALL DOMOUSEDOWN(WHERE,WINDOW,DUMMYHANDLE,
     1               CONTROL_WINDOW,RECT,EVENTRECORD)
     
            CASE(UPDATEEVT)     ! HANDLE UPDATE EVENT
*
*  MUST ALWAYS SET THE PORT TO THE WINDOW WHERE OUTPUT IS TO
*  OCCUR MESSAGE IS PASSED TO US IN THE EVENT RECORD AND IS A
*  POINTER TO THE WINDOW BEING UPDATED
*
    CALL TOOLBX(GETPORT,SAVEPORT)  ! SAVE THE PORT
    CALL TOOLBX(SETPORT,MESSAGE)   ! SET PORT TO UPDATE WINDOW
    CALL TOOLBX(BEGINUPDATE,MESSAGE) ! USE BEFORE UPDATE
    CALL TOOLBX(DRAWCONTROLS,MESSAGE) ! DRAW THE CONTROLS
    CALL TOOLBX(ENDUPDATE,MESSAGE)  !  USE AFTER UPDATE
    CALL TOOLBX(SETPORT,SAVEPORT)  ! RESTORE PREVIOUS PORT

            CASE(ACTIVATEEVT)    ! HANDLE ACTIVATE EVENT
              CALL TOOLBX(SETPORT,MESSAGE)
              ACTIVATE = 255  !  UNHILIGHT CONTROLS
              IF(MOD(MODIFIERS,2).EQ.1)ACTIVATE = 0 ! HILIGHT 
              CONTROL_HAN = LONG(MESSAGE+WCONTROLLIST) !1st
*
* LOOP THROUGH ALL CONTROLS IN A WINDOW
*
              WHILE(CONTROL_HAN.NE.0)
               CALL TOOLBX(HILITECONTROL,CONTROL_HAN,ACTIVATE)
               CONTROL_HAN = LONG(LONG(CONTROL_HAN)) ! NEXT
              REPEAT
              
            CASE DEFAULT
          END SELECT
        END IF
      REPEAT
      END
      SUBROUTINE DOMOUSEDOWN(WHERE,WINDOW,DUMMYWINDOW,
     1             CONTROL_WINDOW,RECT,EVENTRECORD)
*
*  THIS ROUTINE HANDLES MOUSE DOWN EVENTS
*
      IMPLICIT NONE
      INTEGER WINDOW,CONTROL_WINDOW,MOUSELOC
      INTEGER TOOLBX,SIZE
      INTEGER SAVEPORT,TTY_CT,WHICH_CTRL
      INTEGER*2 EVENTRECORD(8)    ! OVERLYING STRUCTURE
      INTEGER*2 WHERE(2),RECT(4),INVAL_RECT(4), MENUSELECTION(2)
      LOGICAL FLAG
      INTEGER QUIT, OPTIONS,CIRCLES,MENUDATA,DUMMY,DUMMYWINDOW
      PARAMETER (QUIT=3,OPTIONS=1,CIRCLES=1,DUMMY=2)
      
 include XP40-6:MacFortran:IncludeFiles:window.inc
 include XP40-6:MacFortran:IncludeFiles:menu.inc
 include XP40-6:MacFortran:IncludeFiles:control.inc
 include XP40-6:MacFortran:IncludeFiles:quickdraw.inc
*
*  MOUSE DOWN LOCATIONS
*
      INTEGER MENUBAR,SYSTEMWINDOW,CONTENTREGION,DRAGREGION
      INTEGER GROWREGION,GOAWAYREGION,NONE
      PARAMETER (MENUBAR=1,SYSTEMWINDOW=2,CONTENTREGION=3)
      PARAMETER (DRAGREGION=4,GOAWAYREGION=6,NONE=0)
      PARAMETER (GROWREGION=5)
      EQUIVALENCE (MENUDATA,MENUSELECTION)
        
      MOUSELOC = TOOLBX(FINDWINDOW,WHERE,WINDOW)

      IF (MOUSELOC=MENUBAR) THEN
        MENUDATA = TOOLBX(MENUSELECT,WHERE)
        SELECT CASE (MENUSELECTION(1))
          CASE (OPTIONS)   ! THE "OPTIONS" MENU WAS SELECTED

          SELECT CASE (MENUSELECTION(2))

            CASE (CIRCLES)
               WINDOW = CONTROL_WINDOW
            CASE (DUMMY)
               WINDOW = DUMMYWINDOW
            CASE (QUIT)
               STOP
          END SELECT

          CALL TOOLBX(SHOWWINDOW,WINDOW)
          CALL TOOLBX(SELECTWINDOW,WINDOW)
          CALL TOOLBX(HILITEMENU,0)

          CASE DEFAULT      ! JUST PLAYING WITH THE MOUSE

        END SELECT

       ELSE IF (MOUSELOC=CONTENTREGION) THEN
        CALL TOOLBX(SELECTWINDOW,WINDOW)
*
*   HANDLE MOUSEDOWN IN CONTROL
* 
        CALL TOOLBX(GETPORT,SAVEPORT)   ! SAVE CURRENT PORT
        CALL TOOLBX(SETPORT,WINDOW)     ! SET PORT TO WINDOW
        CALL TOOLBX(GLOBALTOLOCAL,WHERE)  ! TO LOCAL COORD
        CALL INCONTROL(WHERE,WINDOW)    ! HANDLE IF CTRL CLICK
        CALL TOOLBX(SETPORT,SAVEPORT) ! RESTORE PORT

       ELSE IF (MOUSELOC=DRAGREGION) THEN 
        CALL TOOLBX(DRAGWINDOW,WINDOW,WHERE,RECT)

       ELSE IF (MOUSELOC=GOAWAYREGION) THEN
        IF (TOOLBX(TRACKGOAWAY,WINDOW,WHERE))
     +     CALL TOOLBX(HIDEWINDOW,WINDOW)
      END IF
      RETURN
      END
      SUBROUTINE INCONTROL(WHERE,WINDOW)
*
*  HANDLE EVENT IF MOUSE IS DOWN IN CONTROL
*
      IMPLICIT NONE
      INTEGER*2 WHERE(2)
      INTEGER WHICH_CTRL,WINDOW,PART_NUMBER,IVALUE4,TOOLBX
      
 include XP40-6:MacFortran:IncludeFiles:control.inc
*
* DEFINE SYMBOLIC NAMES FOR CONTROL ITEMS
* NAMING CONVENTION TAKEN FROM INSIDE MACINTOSH
*
      INTEGER INBUTTON, INCHECKBOX, INUPBUTTON, INDOWNBUTTON
      INTEGER INPAGEUP, INPAGEDOWN, INTHUMB
      PARAMETER (INBUTTON=10, INCHECKBOX=11, INUPBUTTON=20)
      PARAMETER (INDOWNBUTTON=21, INPAGEUP=22, INPAGEDOWN=23)
      PARAMETER (INTHUMB=129)
      INTEGER PUSHBUTPROC,CHECKBOXPROC,RADIOBUTPROC, SCROLLBARPROC
      PARAMETER (PUSHBUTPROC=0,CHECKBOXPROC=1,RADIOBUTPROC=2)
      PARAMETER (SCROLLBARPROC=16)
      INTEGER MENUBAR,SYSTEMWINDOW,CONTENTREGION,DRAGREGION
      INTEGER GROWREGION,GOAWAYREGION
      PARAMETER (MENUBAR=1,SYSTEMWINDOW=2,CONTENTREGION=3)
      PARAMETER (DRAGREGION=4,GOAWAYREGION=6)
      PARAMETER (GROWREGION=5)

      IF(TOOLBX(FINDCONTROL,WHERE,WINDOW,WHICH_CTRL).NE.0)THEN
*
*    IS MOUSEUP IN CONTROL? IF SO HANDLE CONTROL
*
        PART_NUMBER = TOOLBX(TRACKCONTROL,WHICH_CTRL,WHERE,0)
        IF(PART_NUMBER.EQ.INBUTTON)THEN
*
*    BUTTON CONTROL DOES NOT NEED TO HAVE ITS VALUE CHANGED
*
         ELSE IF(PART_NUMBER.EQ.INCHECKBOX)THEN    
          IVALUE4 = 1 - TOOLBX(GETCTLVALUE,WHICH_CTRL)
          CALL TOOLBX(SETCTLVALUE,WHICH_CTRL,IVALUE4)
*
*   IF WE WERE HANDLING SCROLL BARS THEN CODE TO HANDLE MOUSE
*   DOWN IN SCROLL BAR PARTS WOULD GO HERE
*
        ENDIF
      ENDIF
      RETURN
      END
      SUBROUTINE INITVALUES(WINDOW,IVALUE)
*
*   INITIALIZE THE REFCON FIELD OF ALL CONTROLS IN WINDOW
*
      IMPLICIT NONE
      INTEGER WINDOW, IVALUE, CONTROL_HAN,IVAL_CTRL
      
        include XP40-6:MacFortran:IncludeFiles:window.inc
 include XP40-6:MacFortran:IncludeFiles:control.inc
*
* HANDLE TO LIST OF CONTROLS OF THIS WINDOW
*
      INTEGER WCONTROLLIST
      PARAMETER (WCONTROLLIST = Z'8C')
*
*   INITIALIZE THE WINDOW REFCON FIELD
*
      CALL TOOLBX(SETWREFCON,WINDOW,IVALUE)
      CONTROL_HAN = LONG(WINDOW+WCONTROLLIST) ! FIRST CTRL 
      IVAL_CTRL = 1
      IF(IVALUE.EQ.1)IVAL_CTRL = 129
      WHILE(CONTROL_HAN.NE.0)
        CALL TOOLBX(SETCREFCON,CONTROL_HAN,IVAL_CTRL)
        IVAL_CTRL = IVAL_CTRL + 1
*
* NEXT CONTROL IN WINDOW (LAST CONTROL IN WINDOW POINTS TO 0)
*
        CONTROL_HAN = LONG(LONG(CONTROL_HAN))
      REPEAT
      RETURN
      END


XP40-6:SoftwareDev:MacFortran:RealControl
APPLGPFR
INCLUDE XP40-6:SoftwareDev:MacFortran:control
TYPE DLOG
 ,128
CONTROL WINDOW
95 150 300 350 
Visible  GoAway
0
0
129

TYPE DITL
,129
4

button
10 20 30 58 
OK?

button 
40 20 60 99 
Cancel

checkBox
70 20 90 100 
Check

radioButton
100 20 130 120 
Radio
Link Script File
f control example apl
f :Subroutines:errmsg
f :Subroutines:toolbx
o control
l :f77 overlays:f77.rl