EHELP_METHOD
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:
- If the user has a menu column dropped down and selects O_HELP, UI Toolkit will set g_enthlp to the internal menu entry name of the highlighted menu entry. The a_ident argument will not be passed.
- If the user has no menu column dropped down and selects O_HELP while on an input field that has a help identifier specified (either in the .FIELD script or with IB_FIELD), UI Toolkit will pass help identifier as the a_ident argument.
- If the user has no menu column dropped down and is not on an input field with a help identifier specified, but the current subroutine was passed a help identifier, UI Toolkit will pass that help identifier value as the a_ident argument. The following subroutines can be passed a help identifier:
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
- In all other cases, UI Toolkit will not pass the a_ident argument. (This includes the case where O_HELP is selected while the input termination message is displayed.)
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: |
- If in a Windows environment, TKP_HELP calls U_WINDOW and uses a Windows-style pop-up window with an OK button.
- If in a UNIX or OpenVMS environment and the entire window is visible (i.e., the display area matches the window area), TKP_HELP displays a message requesting the user to press Return (Enter) when done viewing the window.
- If in a UNIX or OpenVMS environment and if TKP_HELP can show only part of the window, the window is considered scrollable, and T_VIEW is used to enable the user to browse the window.
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 |
- the entire window is visible and the user presses Enter or, on Windows, the user clicks on the OK button.
- the window is scrollable and the user selects any menu entry that T_VIEW does not recognize (other than O_HELP). If the entry is O_EXIT, g_select is returned false to the caller in order to avoid further exiting. Any other menu entry is returned to the caller.
See also
- Synergy UI Toolkit Control Panel (synctl) for information on customizing the HELPINFO and NOHELP text messages
- S_SELECT routine for an example of how a help identifier is passed
- U_HELPREND routine for help window renditions
- Overloading UI Toolkit routines for more information on creating this subroutine
- Appendix D: Methods
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:
- g_select must be cleared so that the menu processing subroutine (M_PROCESS or I_INPUT) continues without interruption.
- Synmsw_popup and u_chr_p are internal routines. They are not supported for any other use or in any other context.
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