/* help_proc.c *********** Copyright 1988-1993 by Vermont Creative Software *********** help_proc() Calls the help system Call #include int help_proc(helpp) HELPPTR helpp; Help structure pointer Returns 1 The help information was successfully displayed and viewed. 0 An event function returned 0 or an error occurred. In case of error, VV_ERR is set to one of the following: FILETOOBIG The keyworded section is too large to fit in the memory file. ERRREAD Error reading disk file. Description help_proc() examines the help structure whose address is passed and determines if there is help information that can be displayed. This is done by doing the following checks in the order presented: * If there is a memory file assigned to the help window, help_proc() calls mf_kwdset() to set the keyword specified in the help structure. If found, that section of the memory file is displayed in the help window. * If there is not a memory file assigned to the window or the keyword is not found in the memory file, the keyword is considered a help string. The help string is then displayed in the help window. * If there is a pointer to a next help structure, then help_proc() is called to find information to display from the next help structure. * If help information is not available from this help structure or subsequent next help structures, the default help message is displayed. * If the default help message is a NULLP, help_proc() beeps if beep on no action is enabled. If help information is to be displayed and the help window isn't already set, a local copy of the help window is set on the screen. The appropriate help string or text is then displayed in the window. A message is also displayed in the message window when the help text is displayed. If the information in the help window can be scrolled, the SCRLHELPMSG informational message is displayed. If the information fits completely in the help window, the EXHELPMSG informational message is displayed. These messages are defined in vv_infomsg.c and can be changed. Control is then passed to the user. Keystrokes and mouse actions entered by the user are searched for first in the system event table (SYSETP) and then the help event table (HELPETP). Provisions are made for the user to scroll in all directions, page up and down, toggle the size of the help window, and exit or quit the help system. The default event function in the HELPETP is to beep. When an event function moves the origin of the window within the memory file, the window is redrawn to display the appropriate part of the memory file. If the AC_ZOOM action code is set by an event function, help_proc() zooms or unzooms the help window depending on its previous state. If the AC_EXIT or AC_QUIT action code is set by an event function, then (1) the message window is removed from the screen, (2) if the help window was set at this help level, the help window is removed from the screen, and (3) help_proc() returns. If a keyword was set prior to calling help_proc(), that keyword is restored before help_proc() returns. */ #include #ifdef OLD_STYLE int FASTCALL help_proc(helpp) HELPPTR helpp; #else int FASTCALL help_proc(HELPPTR helpp) #endif { EVENT event; WINDOW msg_wn; /*local message window */ int r, c; /*temp storage for window members */ int r_org, c_org; ULONG flags; /*help window flags */ ULONG loopflags; /*help window flags in the loop */ int tr, tc; /*storage for cursor coordinates */ register int row_org; /*help window coordinates in mf */ register int col_org; int trb, tcb, tre, tce; /*temporary window coordinates */ MFILEPTR mfp, tmfp; /*memory file pointers */ WINDOWPTR tcurwnp; PTR townerp; HELPPTR nexthelp; /*pointer to the next help level */ UCHAR * mfkwdp; /*temporary storage for mf members */ UCHAR * kwdp; /*the keyword in the help structure */ int nextact; int keyret; /*return value from kt_proc() */ int retval = 0; /*predefined error return */ int secmsg = TRUE; /*second message flag */ int strhelp = FALSE; /*help string only flag */ #ifndef NO_DEBUG_CODE static UCHAR fn[] = "help_proc"; #endif INIT_MODULE(fn); csr_rd(&tr, &tc); /*read the physical cursor position */ helpp->tag = HELP_TAG; /*initialize the help structure */ helpp->wnp = HELP_WNP; flags = HELP_WNP->flags; r = HELP_WNP->r; c = HELP_WNP->c; r_org = HELP_WNP->row_org; c_org = HELP_WNP->col_org; cs_mv(0, 0, HELP_WNP); /*start in zero position */ HELP_WNP->flags |= CSRPLACE; /*turn on cursor placement for mf_disp*/ if (mfp = (MFILEPTR)userp_get(HELP_WNP)) { HELP_WNP->mfp = mfp; /* Restore mfp if null by first level */ _sw_inside(HELP_WNP); /* Reset virtual margins */ userp_set(NULLP, HELP_WNP); } else mfp = HELP_WNP->mfp; nexthelp = helpp->nexthelp; kwdp = helpp->kwdp; if (mfp) /*if mfp assigned */ { /*save members likely to change */ sw_org(0, 0, HELP_WNP); mfkwdp = mfp->kwdp; } if (!_wn_dupstruc(&msg_wn, MSG_WNP) || !wn_msmod(&msg_wn)) goto END; msg_wn.flags &= ~HEAP_WN; /*not a heap window */ if (mfp && kwdp && *kwdp == _kwdch && mf_kwdset(kwdp, mfp)) { if (mfp->vln_q <= HELP_WNP->re - HELP_WNP->rb + 1) secmsg = FALSE; /*do not print the first message */ } else if (kwdp && *kwdp != _kwdch || !nexthelp && (kwdp = _dhelpmsg)) { /*display the message directly */ userp_set(mfp, HELP_WNP); HELP_WNP->mfp = (MFILEPTR) NULLP; _sw_inside(HELP_WNP); /* Reset virtual margins */ wn_msmod(HELP_WNP); v_st(kwdp, HELP_WNP); /*print the message */ csr_mv(vs_rowq(), 0); /*hide the cursor */ if (_csrvis) /*place if could not hide */ csr_mv(0, 0); secmsg = FALSE; /*do not print the first message */ strhelp = TRUE; /*no scrolling possible */ } else if (nexthelp) { /*call the next help level */ tmfp = HELP_WNP->mfp; HELP_WNP->mfp = mfp; retval = help_proc(nexthelp); HELP_WNP->mfp = tmfp; ms_free(msg_wn.bufp); /*fix bug 694 */ goto END; } else /*nothing to display - beep */ { retval = 1; beep_vv(_beeps[BPNOACTION].duration, _beeps[BPNOACTION].pitch); goto END; } if (wn_isup(HELP_WNP)) /* If help window up, bring it to top */ { if (!(_wn_top(HELP_WNP))) /* If wn_top() didn't need to draw us */ wn_upd(HELP_WNP); /* do it ourselves */ } else if (!wn_up(HELP_WNP)) /* otherwise set the help window */ goto END; /* (If can't be set, quit.) */ if (secmsg) /*print first msg if both to be shown */ v_st(vv_infomsg(SCRLHELPMSG), &msg_wn); else /*else print the second message */ v_st(vv_infomsg(EXHELPMSG), &msg_wn); if (!strhelp) csr_plwn(HELP_WNP); if (!wn_up(&msg_wn)) /*set the message window */ goto END; tcurwnp = _curwnp; _curwnp = HELP_WNP; townerp = HELP_WNP->ownerp; HELP_WNP->ownerp = (PTR) helpp; do { helpp->nextact = (strhelp) ? AC_FIXED : AC_CONTINUE; row_org = HELP_WNP->row_org; /*save window position */ col_org = HELP_WNP->col_org; _evnt_keyloop(&event); if ((keyret = et_proc(&event, SYSETP, (PTR)helpp)) == -1) keyret = et_proc(&event, HELPETP, (PTR)helpp); if (!keyret) /*zero returned from the key function */ goto END; nextact = helpp->nextact; /*if window origin moves */ if (nextact == AC_NEXT || nextact == AC_ZOOM || row_org != HELP_WNP->row_org || col_org != HELP_WNP->col_org) { loopflags = HELP_WNP->flags; HELP_WNP->flags |= WNHIDDEN; /*turn off screen updating */ trb = HELP_WNP->rbf; tcb = HELP_WNP->cbf; tre = HELP_WNP->ref; tce = HELP_WNP->cef; if (nextact == AC_ZOOM) { HELP_WNP->flags = loopflags; wn_mod(_help_rb, _help_cb, _help_re - _help_rb + 1, _help_ce - _help_cb + 1, HELP_WNP); HELP_WNP->flags |= WNHIDDEN; } if (strhelp) /*print the message */ { if (HELP_WNP->mfp) { /* Undo memory file from second level */ userp_set(HELP_WNP->mfp, HELP_WNP); HELP_WNP->mfp = (MFILEPTR) NULLP; _sw_inside(HELP_WNP); wn_msmod(HELP_WNP); } else wn_clr(HELP_WNP); /*clear the window */ v_st(kwdp, HELP_WNP); csr_mv(vs_rowq(), 0); /*hide the cursor */ if (_csrvis) /*place if could not hide */ csr_mv(0, 0); if (!(loopflags & WNHIDDEN)) HELP_WNP->flags &= ~WNHIDDEN; } else { if (!(loopflags & WNHIDDEN)) /* Must unhide BEFORE mf_disp!*/ HELP_WNP->flags &= ~WNHIDDEN; mf_disp(HELP_WNP); /*redraw window */ } if (nextact == AC_ZOOM) { _wn_redraw(JUSTWN, HELP_WNP, _help_rb, _help_cb, _help_re, _help_ce); _wn_redraw(LOWERWN, HELP_WNP, trb, tcb, tre, tce); _help_rb = trb; _help_cb = tcb; _help_re = tre; _help_ce = tce; } else _wn_redraw(JUSTWN, HELP_WNP, trb, tcb, tre, tce); } else if (!strhelp) /*if not string help */ { if (HELP_WNP->flags & SBARAUTO && HELP_WNP->flags & WNECHO) _wn_sbauto(HELP_WNP); csr_plwn(HELP_WNP); /*place cursor at new location */ } if (secmsg) /*if the second message to be printed */ { cs_mv(0, 0, &msg_wn); v_st(vv_infomsg(EXHELPMSG), &msg_wn); secmsg = FALSE; } } while (nextact != AC_QUIT && nextact != AC_EXIT); HELP_WNP->ownerp = townerp; _curwnp = tcurwnp; wn_dn(&msg_wn); /*unset the message window */ wn_free(&msg_wn); /*free scroll bars and shadows */ if (!(flags & SET)) wn_dn(HELP_WNP); /*unset the help window */ retval = 1; /*set successful return */ END: csr_mv(tr, tc); if (mfp && mfkwdp && !mf_kwdset(mfkwdp, mfp)) /*restore keyword */ retval = 0; HELP_WNP->mfp = mfp; HELP_WNP->r = r; HELP_WNP->c = c; HELP_WNP->row_org = r_org; HELP_WNP->col_org = c_org; EXIT_NOERRH(fn); return(retval); }