EHELP_METHOD

Perform help processing

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX
VSupported on OpenVMS
subroutine EHELP_METHOD
   a_ident      ,a

Arguments

a_ident

(optional) The help identifier. (a)

Discussion

EHELP_METHOD is a subroutine that you write and name. The name of your subroutine is registered with UI Toolkit using the E_METHOD subroutine.

EHELP_METHOD is called by UI Toolkit when a menu entry with the internal name O_HELP is selected. This routine will not be called unless that entry name is present on one of your menu columns.

UI Toolkit provides a help processing subroutine named TKP_HELP. You can overload it with a more robust or application-specific version.

EHELP_METHOD can be passed one argument, a_ident. UI Toolkit determines whether it will pass this argument, and if so, what it will pass in it. This is determined as follows:

IB_FIELD

L_CHR

L_SELECT

M_PROCESS

S_SELECT

S_SELECTCB

T_EDIT

T_VIEW

U_CHR

U_EDITKEYS

U_EDITREND

U_FLD

%U_GETFILENAME

U_MODREND

%U_MSGBOX

The help identifier associated with an input field or passed to one of the above routines can be used to support the mechanism you choose to provide help for the user. The help identifier can be the name of a help window or, perhaps, the key for an ISAM record that contains help text.

When writing your EHELP_METHOD, be sure to consider whether you want to support a second O_HELP request (for example, enabling the user to select Help while they are viewing the first Help window).

The TKP_HELP subroutine distributed with UI Toolkit goes through the following steps:

1. If g_enthlp is non-blank, UI Toolkit will search the window library for the window h_name where name is the contents of g_enthlp. This window will be displayed, if found, and UI Toolkit will skip to step 4. If not found, UI Toolkit proceeds to step 2.
2. If g_enthlp is blank or if the window h_name (in step 1) was not found, and if a_ident was passed, UI Toolkit will search the library for a window name, where name is the contents of a_ident. (If a_ident was not passed, UI Toolkit goes to step 3.) This window will be displayed, if found, and UI Toolkit will skip to step 4. If the window is not found, Toolkit will issue the message “No help available for identifier name” and proceed to step 3. (This message is in the text message file, facility DTK, mnemonic NOHELP. See Synergy UI Toolkit Control Panel (synctl) for information on customizing messages using the Synergy UI Toolkit Control Panel.)
3. If g_enthlp is blank or if the window h_name (in step 1) was not found, and a_ident was not passed, the window library is searched for a window named h_general. If this window cannot be found, Toolkit will issue the message “No help available for identifier ‘h_general.’”

If a window could be loaded, then TKP_HELP carries out steps 4 through 7.

4. It loads the information line with the message found in text message facility DTK, mnemonic HELPINFO, and a column named c_help is sought in the library opened on g_utlib. If found, TKP_HELP places the column. If not, no error occurs, but the user probably won’t be able to scroll the text. (Some of these actions are only applicable for scrollable windows. See the comments within the TKP_HELP source listed in the Examples.)
5. TKP_HELP calls U_HELPREND and applies any help renditions to the window. TKP_HELP also places the window at this time.
6. The help window is displayed:
7. If the user makes another selection of O_HELP, TKP_HELP looks for and displays a second help window named h_help (if found). When the user exits from this second help window, they will return to the first help window. (TKP_HELP will then return to the calling routine when one of the first two scenarios is true.)
8. TKP_HELP returns to the calling routine when

See also

Examples

The following is a listing of the TKP_HELP subroutine supplied with UI Toolkit. It includes comments that explain the operation of the subroutine. Note the following:

subroutine tkp_help
;
; Description: Default version of help utility
;
       a_id    ,a              ;(Optional) help identifier
;
; Notes:
;            This routine is called from within the higher-level input
;            routines whenever the menu entry "O_HELP" is selected.
;            Developers are encouraged to replace this version with
;            whatever help mechanisms are desired.
;
;            If a_id is passed, it is a help identifier, which is either
;            associated with an input field or was passed into the
;            routine which performed input. If no such help identifier
;            exists, a_id is not passed.
;
;            If g_enthlp is non-blank, it contains the name of a menu
;            entry which was highlighted on a dropped-down menu column
;            when the shortcut for O_HELP was pressed.
;
;            This default version operates as follows:
;
;      1. Determine the help identifier to use
;                  A. If g_enthlp is non-blank, use "h_%a", where %a is
;                      the contents of g_enthlp.
;                  B. Otherwise
;                        1. If a_id is passed, use it
;                        2. Otherwise, use "h_general"
;      2. Attempt to load a window from g_utlib named after the
;         identifier
;                  A. If unsuccessful and 1.A. was used above, go to
;                      1.B.
;                  B. If unsuccessful and 1.B. was used above, issue an
;                      error and exit.
;      3. Apply help renditions to the window.
;      4. Compare the display area to the size of the window
;            A. If the entire window is visible, ask the user to
;               press return.
;            B. If part of the window is not visible, perform text
;               viewing.
;                  1. Load an information line from the text message
;                     file.
;                  2. Attempt to load column "c_help" from g_utlib,
;                     ignoring errors.
;                  3. Setup the window for text viewing.
;                  4. View the text with T_VIEW.
;                  5. Exit on any non-text-viewing menu entry,
;                     clearing any "O_EXIT" to avoid further exiting.
;      5. Return to the calling routine.
;      
;      This routine also enters a private environment and exits it
;      before returning.
.include "WND:tools.def"
.include "UTL:dtkmsg.def"
.include "WND:windows.def"
.include "UTL:inpctl.def"
.align
record
        len     ,i4             ;Length of message line
        wnd     ,2i4            ;Help window ID
        ndx     ,i4             ;Index into help windows
        col     ,i4             ;Help column ID
        err     ,i4             ;Error return
        srch    ,i4             ;Search flag for window loads
        mnu     ,i4             ;Are we attempting menu entry help?
        line    ,a132           ;Message line
        helpid  ,a15            ;Help identifier to use
        chr     ,a1             ;Character typed
        wareas  ,8d3            ;Window areas from W_INFO
        display,a12 @wareas     ;Display area coordinates
        proc   ,a12 @wareas+12  ;Processing area coordinates
proc
        clear g_select, ndx     ;Assume we will satisfy O_HELP
        if (g_enthlp) then      ;Were we sitting on a menu entry?
          begin
            mnu = TRUE          ;Yes, attempt menu help
            xcall s_bld(helpid, , "h_%a", g_enthlp)
          end
        else
          begin
use_id,     clear mnu           ;No, use any passed identifier
            if (^passed(a_id)) then
              helpid = a_id
            else
              helpid = "h_general"      ;Or h_general if none
          end
       call do_help
       xreturn
do_help,
        xcall e_enter           ;Enter a private environment
        xcall e_state(D_OFF, D_ECHO, D_CURSOR)
        incr ndx
                                     ;Attempt to load the window
        xcall u_ldwnd(wnd(ndx), g_utlib, helpid,, srch, err,,, TRUE)
        if (err)
          begin                      ;Could not find it
            if (mnu)                 ;If we were attempting menu entry
              begin
                decr ndx
                xcall e_exit
                call use_id          ;try any passed identifier instead
                return
              end
            xcall u_msg("DTK", DTK_NOHELP, D_ERROR, , helpid)
            goto exit                ;Issue error message and exit
          end
        xcall u_helprend(wnd(ndx))   ;Apply help renditions to window
.ifdef D_DTKGUI
        xcall u_window(D_REMOVE, wnd(ndx))
        xcall synmsw_popup(wnd(ndx))
.else
        xcall w_area(wnd(ndx), WA_COPY, WAC_WTOP)    ;Test window areas
        xcall w_info(WI_AREAS, wnd(ndx), wareas)
        if (display .ne. proc) then                  ;Scrollable?
          begin
           xcall u_text(g_txtlib, "DTK", DTK_HELPINFO2, line, len)
           xcall e_sect(line(1:len), D_INFO, D_CENTER);Load info from msg
                                                      ;file
                                 ;Attempt to load column, ignoring errors
            xcall m_ldcol(col, g_utlib, "c_help", D_NOPLC, srch, err)
            xcall t_setup(wnd(ndx))             ;Setup for text viewing
            repeat
              begin
                xcall t_view(wnd(ndx), col, err)   ;View the text
                if (g_select) then
                  begin
                    case g_entnam of
                     begincase
         "O_EXIT ":    clear g_select
         "O_ABANDON ": clear g_select
         "O_HELP ":    begin
                          clear g_select
                          if (helpid .ne. "h_help ")
                            begin
                              helpid = "h_help"
                              clear mnu
                              call do_help
                            end
                           nextloop
                          end
                     endcase
                    exitloop
                  end
                else
                  if (err) then
                    xcall u_beep
                  else
                    exitloop                            ;On return
              end
          end
        else
          begin
            xcall u_text(g_txtlib, "DTK", DTK_HELPINFO2, line, len)
            ;Load info line from our message file
            xcall e_sect(line(1:len), D_INFO, D_CENTER)
repeat                                      ;Full window
              begin
                xcall u_chr_p(chr)
                if (g_select) then
                  begin
                     case g_entnam of
                     begincase
        "O_EXIT ":     clear g_select
        "O_ABANDON ":  clear g_select
        "O_HELP ":     begin
                        clear g_select
                        if (helpid .ne. "h_help")
                           begin
                             helpid = "h_help"
                             clear mnu
                             call do_help
                           end
                        nextloop
                      end
                    endcase
                    exitloop
                  end
                else
                    if (gi_sts .eq. RETURN_KEY) then
                      exitloop
                    else
                      xcall u_beep
              end
          end
.endc
exit,
          decr ndx
          xcall e_exit                    ;Exit the private environment
          return                          ;Return to caller
endsubroutine