Overloading UI Toolkit routines

UI Toolkit includes many routines that you can overload. At runtime, you register the name of your customized routine, and UI Toolkit will call it at the appropriate time. If you do not register your routine, Toolkit will use the default implementation.

You can name your routines almost anything you want (following general routine naming conventions). However, do not use the prefix “TKP_”, which is used internally by UI Toolkit for its default implementation of customizable routines.

The following routines can be overloaded at runtime:

%EAPPMOVE_METHOD

IARRIVE_METHOD

%EAPPSIZE_METHOD

%ICHANGE_METHOD

%EAPPSTATE_METHOD

%IDISPLAY_METHOD

%ECENTURY_METHOD

IDRILL_METHOD

ECHKFLD_METHOD

%IEDITFMT_METHOD

ECLOSE_METHOD

IHYPER_METHOD

EDSPFLD_METHOD

ILEAVE_METHOD

EEDTDSP_METHOD

LARRIVE_METHOD / LLEAVE_METHOD

EENTRST_METHOD

LDBLCLICK_METHOD

EFKEY_METHOD

LLOAD_METHOD

EHELP_METHOD

USTART_METHOD

ESCRIPTERR_METHOD

%UWNDEVENTS_METHOD

EUTILS_METHOD

 

There are various ways to overload these routines. In general, you need to do the following:

1. Write your customized routine.
2. Register your routine.
3. Make sure your customized routine is available to UI Toolkit. See Making your routine available to UI Toolkit below. Refer to the specific user‑overloadable routines for more detailed information.

Making your routine available to UI Toolkit

In order for Toolkit to be able to locate your customized routine, one of the following must be true:

Overloading examples

Example 1: Creating explicit references

In the following example, the routines my_help and my_utils are explicitly linked into the application by specifying dummy references to them within the application but outside of the code sequence. The routine my_help is registered as the help method, and the routine my_utils is the utility method. They are drawn from an ELB or shared image that’s linked with the application.

subroutine my_startup
proc
    xcall u_start(...)
    xcall e_method(D_METH_HELP, "my_help", D_METH_UTILS, "my_utils")
    .
    .   (other application‑specific start‑up code)
    .
    xreturn 
xcall my_help       ;Dummy references to ensure availability.
xcall my_utils      ;Note that no arguments are required because these
                    ; statements are never actually invoked.
endsubroutine

Example 2: Specifying the library

In the example below, the routine myhelp is registered as the help method and will be drawn from whatever source is available (program image or most recently opened ELB). The utility method will be the routine myutils, and the function key mapping method will be myfkey, both of which are drawn from the ELB or shared image pointed to by the logical symbol USRLIB. A different library, pointed to by the logical symbol APPLIB, is used to supply the user‑defined field support methods mychkfld, mydspfld, and myedtdsp. The routine myclose is used for the application close method, but no specific library will be used (as with myhelp above). The Toolkit is initialized with the window library mywnds, with one header and one footer line.

xcall u_start("mywnds", 1, 1,,,,,,,,"mystart", "USRLIB:") ;Start Toolkit 
subroutine mystart
;
; User start-up routine example which also registers other methods
;
.include "WND:tools.def"
proc
    xcall e_method(D_METH_HELP, "myhelp",
  &                D_METH_LIBRARY, "USRLIB:",
  &                D_METH_UTILS, "myutils",
  &                D_METH_FKEY, "myfkey",
  &                D_METH_LIBRARY, "APPLIB:",
  &                D_METH_CHKFLD, "mychkfld",
  &                D_METH_DSPFLD, "mydspfld",
  &                D_METH_EDTDSP, "myedtdsp",
  &                D_METH_LIBRARY,,
  &                D_METH_APPCLOSE, "myclose")
    xreturn
endsubroutine