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:
|
|
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:
- The routine resides in your application’s main routine.
- The routine resides in an ELB that’s linked with your application, which you have previously opened with OPENELB or specified when you registered the routine.
- The routine resides in an OpenVMS shared image file you have previously opened with OPENELB or specified when you registered the routine.
- The routine is explicitly linked into your application. (Even if you do not call these routines yourself, you still need to reference them explicitly in order for them to be linked into your application. A tactic for creating an explicit reference to a customized routine is to include “dummy” calls after the XRETURN or FRETURN in a routine you know will be explicitly referenced, such as a start-up routine, or after the STOP in a main routine. This method is required if you use OpenVMS object libraries.)
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
