CALLBACK Verb - Register BBj Subroutine


Syntax

CALLBACK (eventType,subroutineName,contextID,{controlID})

or

CALLBACK (eventType,publicProgramEntryPoint,contextID,{controlID})

Description

A CALLBACK is used to execute a block of code at a given location when a specific event occurs. In some cases, this is tied to a specific control via the controlID.

The CALLBACK verb will implicitly GOSUB to the subroutine specified in subroutineName. Since the block of code executed at subroutineName is arrived at via an implicit GOSUB, a RETURN is required at the end of the subroutine.

The CALLBACK implicitly CALLs the publicProgram at the given EntryPoint when the CALLBACK VERB uses the publicProgramEntryPoint syntax (ie: "publicProgram::EntryPoint"). Since a CALL has been made to a public program, an ENTER may optionally be used at the beginning, and a EXIT is required at the end.

CALLBACKS must be registered before the PROCESS_EVENTS verb or within a SUBROUTINE that is called in response to an event.

The REMOVE_CALLBACK verb removes event handling for the eventType (specified event for a control).

For more information, see PROCESS_EVENTS.

 

Parameter

Description

eventType

An event type as seen in the table below.

subroutineName

A name of a subroutine that starts with and Alpha character and contains any number of alpha, numeric, and underscore characters.

contextID

An integer value between 0 and 32767.

controlID

Control ID number, which must be an integer between 1 and 32767 and unique within a given top-level window. Optional for window events.

publicProgramEntryPoint

A string of the form "publicProgramName::entryPoint". This parameter must be a BBj string expression:


This is valid:

CALLBACK(ON_BUTTON_PUSH,"foo::bar",0,101)

 

And so is this:

SUB$="foo::bar"

CALLBACK(ON_BUTTON_PUSH,SUB$,0,101)

 

But this is a syntax error:

CALLBACK(ON_BUTTON_PUSH,foo::bar,0,101)

Window Events

Callback Syntax

Event

Code

ON_ACTIVATE

Activation

A

ON_CLOSE

Window Close Box

X

ON_COLOR_CHANGE

System Color Change

s

ON_DEACTIVATE

Activation

A

ON_DOUBLE_CLICK

Mouse Double-Click

2

ON_KEYPRESS

Keypress

t

ON_MDI_CLOSING
(BBj 6.0 and higher)

MDI Closing Event

M

ON_MINIMIZE

Activation

A

ON_MOUSE_DOWN

Mouse Button Down

d

ON_MOUSE_ENTER

Mouse Enter/Exit Event

E

ON_MOUSE_EXIT

Mouse Enter/Exit Event

E

ON_MOUSE_MOVE

Mouse Move

m

ON_MOUSE_SCROLL
(BBj 6.0 and higher)

Mouse Scroll Wheel

w

ON_MOUSE_UP

Mouse Button Up

u

ON_RESIZE

Window Resize

S

ON_RESTORE

Activation

A

ON_SCREEN_RESIZE

Screen Resize Event

s

ON_WINDOW_GAINED_FOCUS
(BBj 6.0 and higher)

Window Focus Gained/Lost Event

F

ON_WINDOW_LOST_FOCUS
(BBj 6.0 and higher)

Window Focus Gained/Lost Event

F

ON_WINDOW_MOVE
(BBj 6.0 and higher)

Window Move Event

L

ON_WINDOW_SCROLL

Scrollbar Move

p

Menu Events

Callback Syntax

Event

Code

ON_MENU_ITEM_SELECT

Menu Selection

C

Popup Menu Events

Callback Syntax

Event

Code

ON_POPUP_ITEM_SELECT

Popup Menu Selection

r

Control Events

Callback Syntax

Event

Code

ON_BUTTON_PUSH

Push Button Event

B

ON_CHECK_OFF

Check/Uncheck Event

c

ON_CHECK_ON

Check/Uncheck Event

c

ON_COLORCHOOSER_APPROVE
(BBj 7.0 and higher)

ColorChooser Approve Event

 

ON_COLORCHOOSER_CANCEL
(BBj 7.0 and higher)

ColorChooser Cancel Event

 

ON_COLORCHOOSER_CHANGE
(BBj 7.0 and higher)

ColorChooser Change Event

 

ON_CONTROL_SCROLL

Scrollbar Move Event

p

ON_CONTROL_VALIDATION
(BBj 5.0 and higher)

Control Validation Event

v

ON_DB_GRID_ROW_CHANGE_REQUEST (BBj 7.0 and higher)

N/A

 

ON_DRAG_SOURCE_DROP
(BBj 7.0 and higher)

Drag Source Drop Event

O

ON_DROP_TARGET_DROP
(BBj 7.0 and higher)

Drop Target Drop Event

D

ON_EDIT_KEYPRESS

Edit Control Notify

N (Notify code 1)

ON_EDIT_MODIFY

Edit Control Modify Event

e

ON_FILECHOOSER_APPROVE
(BBj 7.0 and higher)

FileChooser Approve Event

x

ON_FILECHOOSER_CANCEL
(BBj 7.0 and higher)

FileChooser Cancel Event

x

ON_FILECHOOSER_CHANGE
(BBj 13.0 and higher)

FileChooser Change Event

x

ON_FILECHOOSER_FILTER
(BBj 13.0 and higher)

FileChooser Filter Event

x

ON_FONTCHOOSER_APPROVE
(BBj 7.0 and higher)

FontChooser Approve Event

x

ON_FONTCHOOSER_CANCEL
(BBj 7.0 and higher)

FontChooser Cancel Event

x

ON_FONTCHOOSER_CHANGE
(BBj 7.0 and higher)

FontChooser Change Event

x

ON_FORM_VALIDATION
(BBj 5.0 and higher)

Form Validation Event

V

ON_GAINED_FOCUS

Control Focus Gained/Lost Event

f

ON_GRID_CELL_MODIFY

EDITCHANGE Grid Notify Event

N (Notify code 5)

ON_GRID_CELL_QUERY
(BBj 8.0 and higher)

Grid Cell Query Event

N (Notify code 33)

ON_GRID_CELL_VALIDATION
(BBj 5.0 and higher)

Grid Cell Validation Event

N (Notify code 32)

ON_GRID_CHECK_OFF

CELLCHECKED Grid Control Event

N (Notify code 30)

ON_GRID_CHECK_ON

CELLCHECKED Grid Control Event

N (Notify code 30)

ON_GRID_COLUMN_SIZE

COLUMNSIZED Grid Notify Event

N (Notify code 1)

ON_GRID_DOUBLE_CLICK

DCLICKED Grid Notify Event

N (Notify code 3)

ON_GRID_DRAG_DROP

DRAGDROP Grid Notify Event

N (Notify code 4)

ON_GRID_EDIT_START

EDITSET Grid Notify Event

N (Notify code 8)

ON_GRID_EDIT_STOP

EDITKILL Grid Notify Event

N (Notify code 7)

ON_GRID_ENTER_KEY

ENTER Grid Notify Event

N (Notify code 9)

ON_GRID_ERROR

ERROR Grid Notify Event

N (Notify code 29)

ON_GRID_GAINED_FOCUS

SETFOCUS

N (Notify code 20)

ON_GRID_HIT_BOTTOM

HITBOTTOM Grid Notify Event

N (Notify code 10)

ON_GRID_HIT_TOP

HITTOP Grid Notify Event

N (Notify code 11)

ON_GRID_KEYPRESS

KEYBOARD Grid Notify Event

N (Notify code 12)

ON_GRID_LEFT_COLUMN_CHANGE

LEFTCOLCHANGE Grid Notify Event

N (Notify code 16)

ON_GRID_LIST_CANCEL
(BBj 15.0 and higher)

LISTCANCEL Grid Notify Event

N (Notify code 34)

ON_GRID_LIST_CHANGE
(BBj 15.0 and higher)

LISTCHANGE Grid Notify Event

N (Notify code 35)

ON_GRID_LIST_CLICK
(BBj 15.0 and higher)

LISTCLICK Grid Notify Event

N (Notify code 36)

ON_GRID_LIST_CLOSE
(BBj 15.0 and higher)

LISTCLOSE Grid Notify Event

N (Notify code 37)

ON_GRID_LIST_OPEN
(BBj 15.0 and higher)

LISTOPEN Grid Notify Event

N (Notify code 38)

ON_GRID_LIST_SELECT
(BBj 15.0 and higher)

LISTSELECT Grid Notify Event

N (Notify code 39)

ON_GRID_LOST_FOCUS

KILLFOCUS

N (Notify code 13)

ON_GRID_MOUSE_DOWN

LCLICKED Grid Notify Event

LCLICKED2 Grid Notify Event

N (Notify code 14)

N (Notify code 15)

ON_GRID_MOUSE_DRAG

MOUSECAPTURE Grid Notify Event

N (Notify code 17)

ON_GRID_MOUSE_MOVE

MOUSECAPTURE Grid Notify Event

N (Notify code 17)

ON_GRID_MOUSE_UP

LCLICKED Grid Notify Event

N (Notify code 14)

ON_GRID_RIGHT_MOUSE_DOWN

RCLICKED Grid Notify Event

N (Notify code 18)

ON_GRID_RIGHT_MOUSE_UP

RCLICKED Grid Notify Event

N (Notify code 18)

ON_GRID_ROW_DELETE

ROWDELETE Grid Notify Event

N (Notify code 25)

ON_GRID_ROW_INSERT

ROWINSERT Grid Notify Event

N (Notify code 24)

ON_GRID_ROW_INSERT_CANCEL

ROWCANCEL Grid Notify Event

N (Notify code 26)

ON_GRID_ROW_UPDATE

ROWUPDATE Grid Notify Event

N (Notify code 27)

ON_GRID_ROW_VALIDATION
(BBj 5.0 and higher)

ROWVALIDATION Notify Event

N (Notify code 31)

ON_GRID_SELECT_COLUMN

COLCHANGE Grid Notify Event

N (Notify code 2)

ON_GRID_SELECT_ROW

ROWCHANGE Grid Notify Event

N (Notify code 19)

ON_GRID_SPECIAL_KEY

EDITKEY Grid Notify Event

N (Notify code 6)

ON_GRID_TOP_ROW_CHANGE

TOPROWCHANGE Grid Notify Event

N (Notify code 21)

ON_GRID_UPDATE

TABLEUPDATE Grid Notify Event

N (Notify code 22)

ON_HYPERLINK_ACTIVATE
(BBj 7.0 and higher)

Hyperlink Activate Event

x

ON_HYPERLINK_ENTER
(BBj 7.0 and higher)

Hyperlink Enter Event

x

ON_HYPERLINK_EXIT
(BBj 7.0 and higher)

Hyperlink Exit Event

x

ON_INPUT_KEYPRESS

Input Control Keypress

N (Notify Code 1)

ON_LIST_CANCEL
(BBj 5.0 and higher)

List Button and List Edit Notify Events

N (Notify code 4)

ON_LIST_CHANGE

List Button and List Edit Notify Events

N (Notify code 5)

ON_LIST_CLICK

List Item Click Event

l (lower case L)

ON_LIST_CLOSE

List Button and List Edit Notify Events

N (Notify code 3)

ON_LIST_DOUBLE_CLICK

List Item Click Event

l (lower case L)

ON_LIST_OPEN

List Button and List Edit Notify Events

N (Notify code 1)

ON_LIST_SELECT

List Button and List Edit Notify Events

N (Notify code 2)

ON_LOST_FOCUS

Control Focus Gained/Lost Event

f

ON_MOUSE_ENTER

Mouse Enter/Exit Event

E

ON_MOUSE_EXIT

Mouse Enter/Exit Event

E

ON_NAV_FIRST
(BBj 6.0 and higher)

Navigator Notify Event

N (Notify code 1)

ON_NAV_LAST
(BBj 6.0 and higher)

Navigator Notify Event

N (Notify code 1)

ON_NAV_NEXT
(BBj 6.0 and higher)

Navigator Notify Event

N (Notify code 1)

ON_NAV_PREVIOUS
(BBj 6.0 and higher)

Navigator Notify Event

N (Notify code 1)

ON_PAGE_LOADED
(BBj 7.0 and higher)

Page Loaded Event

 

ON_POPUP_REQUEST

Popup Request Event

p

ON_RIGHT_MOUSE_DOWN
(BBj 2.01 and higher)

Right Mouse Button Down Event

R

ON_SPIN
(BBj 7.0 and higher)

N/A

 

ON_TAB_DESELECT

Tab Selection Notify Event

N (Notify code 3)

ON_TAB_KEYPRESS

Keypress Notify Event - Tab Control

N (Notify code 1)

ON_TAB_SELECT

Tab Selection Notify Event

N (Notify code 2)

ON_TOOL_BUTTON_PUSH

Tool Button Push Event

b

ON_TREE_COLLAPSE

Tree Node Collapsed

N (Notify Code 4)

ON_TREE_DESELECT

Tree Node Deselected

N (Notify Code 2)

ON_TREE_DOUBLE_CLICK

Double-click on Tree

N (Notify Code 7)

ON_TREE_EDIT_STOP

Tree Node Edit Stopped

N (Notify Code 5)

ON_TREE_EXPAND

Tree Node Expanded

N (Notify Code 3)

ON_TREE_MOUSE_DOWN

Left Mouse Down

N (Notify Code 6)

ON_TREE_MOUSE_UP

Left Mouse Up

N (Notify Code 6)

ON_TREE_RIGHT_MOUSE_DOWN

Right Mouse Down

N (Notify Code 8)

ON_TREE_RIGHT_MOUSE_UP

Right Mouse Up

N (Notify Code 8)

ON_TREE_SELECT

Tree Node Selected

N (Notify Code 1)

Other Events

Callback Syntax

Event

Code

ON_GEOLOCATION_POSITION
(BBj 11.0 and higher)

N/A

G

ON_GEOLOCATION_WATCH
(BBj 11.0 and higher)

N/A

G

ON_NAMESPACE_SET
(BBj 6.0 and higher)

BBjNamespaceEvent

N (Notify Code 1)

ON_NAMESPACE_CHANGE
(BBj 6.0 and higher)

BBjNamespaceEvent

N (Notify Code 2)

ON_TIMER
(BBj 6.0 and higher)

Timer Event

T

 ON_WEB_CONNECTION
(BBj 12.0 and higher)

N/A

 

Example

REM CallBack Example

SYSGUI=UNT

OPEN (SYSGUI)"X0"

SysGui! = BBjAPI().getSysGui()

 

REM Create Controls

PRINT (SYSGUI)'WINDOW'(50,50,400,200,"Example",$00090003$)

PRINT (SYSGUI)'EDIT'(100,50,50,125,25,"",$$)

PRINT (SYSGUI)'EDIT'(103,200,50,125,25,"",$$)

PRINT (SYSGUI)'BUTTON'(110,62,125,75,25,"Button 1",$$)

PRINT (SYSGUI)'BUTTON'(111,212,125,75,25,"Button 2",$$)

 

REM Build the event base info templates

DIM GENERIC$:NOTICETPL(0,0)

DIM EVENT$:TMPL(SYSGUI)

 

CONTEXT = 0

VAR = 2

 

REM PublicProgramEntryPoint

CALLBACK(ON_BUTTON_PUSH,pgm(-2)+"::BUTTON1_PUSH",CONTEXT,110)

REM Subroutine Name

CALLBACK(ON_BUTTON_PUSH,BUTTON2_PUSH,CONTEXT,111)

CALLBACK(ON_EDIT_MODIFY,EDIT_MODIFY,CONTEXT,100)

CALLBACK(ON_EDIT_MODIFY,EDIT_MODIFY,CONTEXT,103)

CALLBACK(ON_CLOSE,EXIT_PROGRAM,CONTEXT,0)

 

REM Process Events

PROCESS_EVENTS

 

REM This Callback is registered using PublicProgramEntryPoint

REM and therefore can Optionally do an ENTER

REM and always uses an EXIT.

BUTTON1_PUSH:

ENTER

PRINT (SYSGUI)'TITLE'(100,"Button 1: VAR = "+str(VAR))

PRINT (SYSGUI)'TITLE'(103,"")

EXIT

 

REM This Callback is registered using SubroutineName

REM and therfore does a RETURN

BUTTON2_PUSH:

PRINT (SYSGUI)'TITLE'(100,"")

PRINT (SYSGUI)'TITLE'(103,"You Pressed Button 2!")

RETURN

 

REM This Callback is registered using SubroutineName

REM and therfore does a RETURN

EDIT_MODIFY:

   event! = sysgui!.getLastEvent()

   print "Edit control contains: ",event!.getText()

RETURN

 

EXIT_PROGRAM:

RELEASE

See Also

Verbs - Alphabetical Listing



______________________________________________________________________________________

Copyright BASIS International Ltd. BBj®, Visual PRO/5®, PRO/5®, and BBx® are registered trademarks.