|
WSupported on Windows
|
USupported on Unix
|
VSupported on OpenVMS
|
NSupported in Synergy .NET
|
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: |
- On Windows, TKP_HELP calls U_WINDOW and uses a Windows-style pop-up window with an OK button.
- On Unix and OpenVMS if 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.
- On Unix and OpenVMS 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
