PROCESS_EVENTS Verb - Continually Process Events/Call Registered Callback Routine

Syntax

PROCESS_EVENTS {,TIM=int}{,ERR=lineref}

Description

The PROCESS_EVENTS verb continually processes user interface events.

If the callback subroutine registered to handle the event is invalid, an !ERROR=21 is returned.

In BBj 5.0 and higher, the Process Events verb supports an optional error branch.

 

In BBj 17.0 and higher, the PROCESS_EVENTS verb supports an optional timeout, specified in seconds.

The following rules determine the dispatch of events from the server's event queue:

1. If a control has been destroyed, the event is discarded.

2. If a control's callback has been unregistered for an event, the event is discarded.

3. If a control's callback does not exist in the program, an error is thrown.

4. Otherwise, the event is read off the queue, and if processing events, the callback is
  executed.


A BBj program may use both PROCESS_EVENTS and READ RECORD styles of event handling, either by nesting a READ RECORD within a CALLBACK routine or by calling another BBj program which uses a different event style.

When a program switches between event handling styles, the event and notify queues are emptied. In other words, when a program that was currently using PROCESS_EVENTS style calls READ RECORD, the event and notify queues are emptied. Conversely, when a program that was currently using READ RECORD calls PROCESS_EVENTS the event and notify queues are emptied.

An example of a menu program using either event style calling a program utilizing either event style follows. The example programs below expect an argument of either of the following:

- rr

READ RECORD

- pe

PROCESS_EVENTS

Example 1

REM Using both READ RECORD and PROCESS_EVENTS interchangeably

REM Obtain the instance of the BBjAPI object
LET myAPI!=BBjAPI()

REM Open the SysGui device
SYSGUI=UNT
OPEN (SYSGUI) "X0"

REM Obtain the instance of the BBjSysGui object
LET mySysGui!=myAPI!.getSysGui()

REM SET style to 0(INVALID style) [1(READ RECORD), 2(PROCESSEVENTS)]
LET style = 0

REM Set addWindow param values
X=10
Y=10
WIDTH=200
HEIGHT=200
TITLE$="BBj Window"

REM Set the current context
mySysGui!.setContext(0)
REM Create a window with a title in the current context
myWindow! = mySysGui!.addWindow(X,Y,WIDTH,HEIGHT,TITLE$)

REM Create the menu bar
myMenuBar!=myWindow!.addMenuBar()

REM Add a menu to the menu bar
myMenu!=myMenuBar!.addMenu(-100,"&Menu")

REM Add menu items to the menu
myMenu!.addMenuItem(-101,"&Read Record Program")
myMenu!.addMenuItem(-102,"&Process Events Program")

REM Flag to determine if valid event style
LET valid = 0



REM display event style information as static text based on command line
args

if ARGC > 1 then

    if ARGV(1) = "rr" or ARGV(1) = "RR" then
    myStaticText! = myWindow!.addStaticText(107,20,80,100,30,"Event Style:
READ RECORD",$0000$)
    style = 1
    valid = 1
    fi

    if ARGV(1) = "pe" or ARGV(1) = "PE" then
    myStaticText! = myWindow!.addStaticText(107,20,80,100,30,"Event Style:
PROCESS EVENTS",$0000$)
    style = 2
    valid = 1
    fi

    if valid = 0 then
    myStaticText! = myWindow!.addStaticText(107,20,80,100,30,"Invalid Event
Style",$0000$)
    myStaticText2! = myWindow!.addStaticText(108,20,110,100,30,"Specify - rr
or - pe to select event style.",$0000$)
    style = 0
    fi

else
    myStaticText! = myWindow!.addStaticText(107,20,80,100,30,"Specify - rr
or - pe to select event style.",$0000$)
fi

DONE:

IF style = 1 THEN
    REM READ RECORD STYLE
    DIM EVENT$:TMPL(SYSGUI)
    LET EVENT=LEN(EVENT$)

    while(1)
       READ RECORD(SYSGUI,SIZ=EVENT)EVENT$
       REM APPCLOSE
       IF EVENT.CODE$="X" THEN RELEASE

       REM MENU EVENTS
       IF EVENT.CODE$="C" THEN

        IF EVENT.ID = 101 THEN CALL"MixedEventStyles2.bbj::READRECORDSTYLE"
        IF EVENT.ID = 102 THEN CALL"MixedEventStyles2.bbj::PROCESSEVENTSSTYLE"

       FI
    WEND
FI



IF style = 2 THEN
    REM PROCESS_EVENTS STYLE

    REM Register the CALLBACK routines
    CALLBACK(ON_CLOSE,APP_CLOSE,mySysGui!.getContext())
    CALLBACK(ON_MENU_ITEM_SELECT,MENU1_SELECT,mySysGui!.getContext(),-101)
    CALLBACK(ON_MENU_ITEM_SELECT,MENU2_SELECT,mySysGui!.getContext(),-102)


    REM Process Events
    PROCESS_EVENTS

    REM Callback routine called when the user closes the application window
    APP_CLOSE:
    RELEASE
    RETURN

    REM Callback routine called when the user selects menuItem1
    MENU1_SELECT:
    CALL"MixedEventStyles2.bbj::READRECORDSTYLE"
    REM restore context to current window
    mySysGui!.setContext(0)
    RETURN

    REM Callback routine called when the user selects menuItem2
    MENU2_SELECT:
    CALL"MixedEventStyles2.bbj::PROCESSEVENTSSTYLE"
    REM restore context to current window
    mySysGui!.setContext(0)
    RETURN
FI

IF style = 0 THEN
    REM NO VALID STYLE
    PRINT "NO VALID EVENT STYLE"
    PRINT "SPECIFY - RR or - PE ON COMMAND LINE"
    WHILE (1)
    WAIT(1)
    WEND
FI

Example 2

REM Program to be demonstrate using both event styles from a menu
GOTO DEFAULT


BUILDWINDOW:
REM BUILD THE WINDOW TO BE USED BY EITHER EVENT STYLE

REM Obtain the instance of the BBjAPI object
LET myAPI!=BBjAPI()

REM Open the SysGui device
SYSGUI=UNT
OPEN (SYSGUI) "X0"

REM Obtain the instance of the BBjSysGui object
LET mySysGui!=myAPI!.getSysGui()

REM Set addWindow param values
X=10
Y=10
WIDTH=250
HEIGHT=200
TITLE$="BBj Window"

LET FL = 0

REM Set the current context
mySysGui!.setContext(1)

REM Create a window
myWindow! = mySysGui!.addWindow(X,Y,WIDTH,HEIGHT,TITLE$)

REM Add a button on the window
myRedButton! = myWindow!.addButton(101,50,100,90,30,"Red",$0800$)

REM RETURN TO EITHER READRECORDS OR PROCESS EVENTS
RETURN





READRECORDSTYLE:

GOSUB BUILDWINDOW

myWindow!.setTitle("using READ RECORD")

DIM EVENT$:TMPL(SYSGUI)
LET EVENT=LEN(EVENT$)

WHILE(1)

    READ RECORD(SYSGUI,SIZ=EVENT)EVENT$
    REM APPCLOSE
       IF EVENT.CODE$="X" THEN
       myWindow!.destroy()
       exit
       FI
       IF EVENT.CODE$="B" THEN
           REM TOGGLE THE BUTTON COLOR
           IF FL = 0 THEN
            myColorRed! = mySysGui!.makeColor(mySysGui!.RED)
            myRedButton!.setText("Blue")
            FL = 1
           else
            myColorRed! = mySysGui!.makeColor(mySysGUI!.BLUE)
            myRedButton!.setText("Red")
            FL = 0
       FI
       myRedButton!.setBackColor(myColorRed!)
    FI



wend



PROCESSEVENTSSTYLE:

GOSUB BUILDWINDOW
myWindow!.setTitle("Using PROCESS_EVENTS")

REM Register the CALLBACK routines
CALLBACK(ON_BUTTON_PUSH,RED_BUTTON_PUSHED,mySysGui!.getContext(),myRedButton
!.getID())
CALLBACK(ON_CLOSE,APP_CLOSE,mySysGui!.getContext())

REM PROCESS EVENTS
PROCESS_EVENTS

REM Callback routine called when the user closes the application window
APP_CLOSE:
myWindow!.destroy()
exit
RETURN

REM Callback routine called when the red button is pressed
RED_BUTTON_PUSHED:
REM Create the BBjColor Object using colorNum constant
REM TOGGLE THE BUTTON COLOR
if FL = 0 THEN
myColorRed! = mySysGui!.makeColor(mySysGui!.RED)
myRedButton!.setText("Blue")
FL = 1
else
myColorRed! = mySysGui!.makeColor(mySysGUI!.BLUE)
myRedButton!.setText("Red")
FL = 0
fi
myRedButton!.setBackColor(myColorRed!)
RETURN

DEFAULT:
PRINT "This program is intended to called by MixedEventStyles.bbj"
PRINT "Call using labels READRECORDSTYLE or PROCESSEVENTSSTYLE"
PRINT "Running in PROCESS_EVENTS STYLE MODE"
GOTO PROCESSEVENTSSTYLE

See Also

READ Verb - BBj

BBjControl::setCallback

BBjControl::clearCallback

Verbs - Alphabetical Listing