IARRIVE_METHOD

Perform input field arrive processing

subroutine IARRIVE_METHOD
 a_inpinfo              ,a
 a_inprec               ,a
 a_methoddata1          ,any
       .
       .
       .
 a_methoddata20         ,any

Arguments

a_inpinfo

The structure of input information. (a)

a_inprec

The data_area argument (or data_location argument for I_INPFLD on Windows) passed to the calling input routine. (a)

a_methoddata1 through a_methoddata20

(optional) Up to 20 additional data arguments. (any)

Discussion

IARRIVE_METHOD is a subroutine you write and name when you want your program to perform extra actions before a specific input field is processed.

This subroutine is called by I_INPUT, I_INPFLD (Windows only), and L_INPUT when an arrive method is specified for the field about to be processed. You can specify an arrive method for the field by using the ARRIVE_METHOD qualifier in a .FIELD script command or the D_FLD_ARRIVE option in I_FLDMOD or IB_FIELD.

The a_inpinfo argument is defined in inpinf.def. It is defined as a group and must be included within a record or as an argument. You can define multiple copies of it within your method routine. For example:

record data1
.include "WND:inpinf.def"
record data2
.include "WND:inpinf.def"

You can also use .INCLUDE to define this group argument without having to move it into a local data area. For example:

subroutine my_arrive_method
.include "WND:inpinf.def"
a_inprec       ,a
a_methoddata1  ,any
  .
  .
a_methoddata20 ,any

Note the following:

For performance, make sure that this group is aligned.
Do not modify the data in a_inpinfo.
To retrieve the strings associated with the pointers, use the function %I_GETSTRING. (See %I_GETSTRING for more information.)
The inp_entered and inp_return fields in a_inpinfo will be false in the arrive method. (See Appendix D: Methods for information on values for these fields in leave methods.)

For information on a_inpinfo group members, see the comments in inpinf.def. Additionally, note that the inp_navevent field lists the event that triggered navigation (arriving or leaving a field). It can have one of the following values (defined in tools.def):

D_NAVMOUSE, which indicates that a mouse click occurred in the field (and that no subsequent event triggered focus). Note, however, that in a change, display, or leave method, this indicates that a mouse click occurred on some other window (and that no subsequent event triggered a loss of focus).
D_NAVTAB, which indicates that the user pressed Tab to arrive on this field. Note that the same is true for edit format methods. For change, display, and leave methods, however, this indicates that the user pressed Tab to leave the field.
D_NAVSTAB, which indicates that the user pressed Shift+Tab to arrive on this field. Note that the same is true for edit format methods. For change, display, and leave methods, however, this indicates that the user pressed Shift+Tab to leave the field.
D_NAVNONE, which indicates that navigation happened for some reason other than those listed above (Enter, menu entry, or I_NEXT, for example). Note that on Unix and OpenVMS, this is always the value in inp_navevent, so you will need to use other data members (inp_return, g_select, and g_entnam) to determine the cause.

A_inprec is the record passed to the data_area argument for I_INPUT and L_INPUT and, on Windows, the data_location argument for I_INPFLD. (On Unix and OpenVMS, this argument is not passed if I_INPFLD is the calling routine.)

A_methoddata1 through a_methoddata20 are up to 20 additional optional arguments that can be passed to I_INPUT, I_INPFLD, or L_INPUT. They are passed, in turn, directly to IARRIVE_METHOD. This enables you to communicate additional information to IARRIVE_METHOD.

See also

Overloading UI Toolkit routines for more information on creating this subroutine
Appendix D: Methods

Examples

.field custno, d6, user("h_popup=h_custno"), arrive_method("popup")

Given the above field definition, the following arrive method, popup, displays a popup-style window for the custno field.

subroutine popup
.include "WND:inpinf.def"               ;Input window information
        a_inprec          ,a            ;Input record
.include "WND:fldinf.def"
.include "WND:tools.def"
external common
        g_popupwnd      ,i4             ;ID of currently placed popup
.align
record
        ndx             ,i4             ;instr index
        scrch           ,i4             ;Search
        err             ,i4             ;Error
        name            ,a30            ;Doubles as field name/window name
        user            ,a80            ;User text
.define D_POPID ,"hpopup="
proc
      if (g_popupwnd)            ;Any currently placed window?
        begin
          xcall u_window(D_DELETE, g_popupwnd)     ;Delete it
          clear g_popupwnd                         ;Note none placed
        end
                                                   ;Get field information
xcall i_fldinf(inp_wndid, name, inp_fldnum,, gs_inpfld)
      user = %i_getstring(inp_wndid, inp_usertext) ;Get user text

      if (ndx = %instr(1, user, D_POPID))          ;Any popup specified?
        name = user(ndx+^size(D_POPID),^size(user))             ;Load it
      if (ndx = %instr(1, name, ','))
        clear name(ndx,^size(name)                      ;Allow comma delimiter
      if (.not. name)                                   ;Just "hpopup="
        xreturn
      xcall u_ldwnd(g_popupwnd, g_utlib, name,, srch, err);Load the window
      if (err)
        xreturn                                         ;No such window
;Place the window one row below and one column beyond the field being processed.
      xcall u_window(D_PLACE, g_popupwnd,
  &                 %w_info(WIF_PLCROW, inp_wndid) + gs_frow,
  &                 %w_info(WIF_PLCCOL, inp_wndid) + gs_fcol + gs_dsplen)
      xreturn
endsubroutine