uiinfhlp.asm

Dos6.0

        TITLE   uiinfhlp.asm - interface routines for new help engine.
;***
;uiinflp.asm
;
;       Copyright <C> 1985-1988, Microsoft Corporation
;
;Purpose:
;       Interface routines for the new help system.
;
;
;*******************************************************************************

        .xlist
        include version.inc
        .list
        UIINFHLP_ASM = ON


        include cw/version.inc
        include cw/windows.inc
        include cw/edityp.inc

        IncludeOnce architec
        Include     help.inc
        IncludeOnce qbimsgs
        IncludeOnce ui
        IncludeOnce uiint
        IncludeOnce uimenu
        IncludeOnce uinhelp

assumes DS,DATA
assumes ES,DATA
assumes SS,DATA

        subttl  DATA segment definitions.
        page

sBegin  DATA
        externB HelpFlags
        globalB fMessageBox,0,1         ; are we in a message box?
        externW efHelp                  ; Editmgr structure for Help Wnd.
        externW oCurTopic               ; offset to the current topic
        globalW iStaticHelpTopic,0,1    ; High word of NC during searches
        externB b$Buf1                  ; FILNAML-sized buffer
        externB b$Buf2
        externW iFileSize               ; Size of current help topic
        externW iCurRequestLine
        externW rgLineAttr              ; static attribute buffer
        externB fHelpAlloc

        HtSpot  EQU     b$Buf2          ; Static HotSpot structure

sEnd    DATA

        externFP GetEditMgrState
        externFP EditFilterWndProc
        externFP HelpSzContext
        externFP HelpHlNext
        externFP HelpNcPrev
        externFP HelpGetLineAttr
        externFP HelpGetLine
        externFP HelpNcNext


sBegin  UI
assumes CS,UI
        externNP toupper
        externNP GotoBookMark
        externNP SetBookMark
        externNP GetInitialPos
        externNP GetNextNc
        externNP SzSrchExcl
        externNP AppendBuf
        externNP CalcNc
        externNP MoveCursorPwnd
        externNP SizeHelpContext


;***
;DisplayHlpGeneric - Display either VarHelp or EngineHelp on screen
;
;Purpose:
;       Will deturmine the type of help specified and display it in
;       the help window.  It is expected to call this routine after
;       calling RetrieveHelpHistory, as its output parameters identically
;       match our input parameters.
;
;Entry:
;       DX:AX   - Help Topic (NC or Var Help ID)
;       CL      - Flags (EI_VARHELP only)
;                       0 => Engine help
;                      ~0 => Variable help
;
;Exit:
;       AL = 0    all ok
;       AL <> 0   failure (returns Error Code)
;****

cProc   DisplayHlpGeneric,<NEAR>
cBegin
        cCall   DisplayHlpWndNc         ; display the new topic

        ;AL = 0 if succeeded, error code otherwise

DisplayHlpGeneric_Exit:
cEnd


;***
;NextHotLink - Go to next hot link
;
;Purpose:
;       This routine will move the cursor to the next hot link in the
;       current topic.  Will wrap around the proper end of the help topic
;       to check for hot links if needed.
;
;Entry:
;       cLead : parameter to pass to HelpHlNext
;
;Exit:
;       None.
;
;****

cProc   NextHotLink,<NEAR>,<SI,DI>
parmW   cLead
cBegin
        ; This routine is only called when the help window is open
        ; and valid, thus we can assert HLP_GOTBUF and oCurTopic.

        DbAssertTst HelpFlags,ne,HLP_GOTBUF,UI,<NextHotLink:Buffers not initialized>


        DbChk   HoldBuf2                ; lock down the HotSpot

        ;Get current line#/column number

        mov     ax,EfHelp.EF_ipCur_ob   ; get the current column
        inc     ax                      ; make it 1 relative
        mov     HtSpot.colHS,ax         ; save it for HelpHlNext


        mov     ax,EfHelp.EF_ipCur_oln  ; current line #
        inc     ax                      ; make it 1 relative
        mov     HtSpot.lineHS,ax        ; save line number for help engine
        xor     di,di                   ; first time through

DbAssertRel     oCurTopic,ne,0,UI,<NextHotLink:oCurTopic invalid>

        mov     si,oCurTopic            ; get ptr to current topic
HotSpotRetry:
        lea     bx,[si].bdlHelpText.BDL_seg ; BX = handle of text seg
        xor     ax,ax                   ; ax = offset of text
        mov     cx,OFFSET DGROUP:HtSpot ; cx = offset of HotSPot
        push    HtSpot.lineHS           ; save row and column of hot spot
        push    HtSpot.colHS
        cCall   HelpHlNext,<cLead,BX,AX,DS,CX>
        pop     bx                      ; restore row and column of old hot spot
        pop     cx
        or      ax,ax                   ; did we get a hot linK?
        je      NextHotLink_Retry       ; no, go complain
        mov     ax,di                   ; save old loop counter
        inc     di                      ; one more time through loop
        or      ax,ax                   ; first time through?
        jne     MoveCursorToHotLink     ; no, it is a real hot link
        cmp     cx,HtSpot.lineHS        ; on the same row?
        jne     MoveCursorToHotLink     ; no, must be a real hot link
        cmp     bx,HtSpot.colHS         ; old column in current hot spot?
        jl      MoveCursorToHotLink     ; no, must be a real hot link
        mov     ax,HtSpot.ecolHS        ; AX = ending column of hot spot
        cmp     bx,ax                   ; old column in current hot spot
        ja      MoveCursorToHotLink     ; no, must be a real hot link
        inc     ax                      ; try again after the hot spot
        mov     HtSpot.colHS,ax         ; set position
        jmp     HotSpotRetry            ; and try again

NextHotLink_Beep:
        cCall   CowMoo                  ; beep the speaker
        jmp     short NextHotLink_Exit  ; and leave.

NextHotLink_Retry:
        cmp     di,1                    ; Have we already wrapped around?
        ja      NextHotLink_Beep        ; yes, nothing to find
        mov     di,2                    ; set wrapped flag
        mov     ax,1                    ; assume wrapping backwards
        mov     HtSpot.lineHS,ax        ; set line + col position
        mov     HtSpot.colHS,ax
        test    cLead,8000H             ; forward (+) or backwards (-)?
        jz      HotSpotRetry            ; we assumed right
        mov     ax,iFileSize            ; get last line number
        mov     HtSpot.lineHS,ax
        mov     HtSpot.colHS,-1         ; column position FFFF
        jmp     HotSpotRetry


MoveCursorToHotLink:
        ;Move the cursor to the position specified in the HotSpot structure
        mov     ax,HtSpot.lineHS        ; get the context relative row
        dec     ax                      ; make it 0 relative
        mov     cx,OFFSET DGROUP:wndHelp
        mov     bx,HtSpot.colHS         ; get the context relative column
        dec     bx                      ; make it 0 relative
        cCall   MoveCursorPwnd,<cx,ax,bx> ; move cursor to hotspot

NextHotLink_Exit:

        DbChk   FreeBuf2                ; release the HotSpot
cEnd


;***
;HelpBack - Backup one level of help (if possible)
;
;Purpose:
;       Implements ALT-F1.  The user asked us to go to the help topic
;       that was previously shown.
;
;
;       NOTE: SLIME: this routine uses iStaticHelpTopic for a temporary
;                    Dgroup storage location.  This should cause no problems,
;                    as HelpBack and searching are mutually exclusive.
;
;Entry:
;       None
;
;Exit:
;       None
;
;Uses:
;       Per Convention
;
;****
cProc   HelpBack,<PUBLIC, NEAR>,<SI,DI>
cBegin

;There are two cases to handle:
;       1) If the cursor is not at the start of a topic, move to start of topic
;          (note: the start of the topic is 0,0 and (if visible on the screen)
;          the first hot link.
;       2) If the cursor is at the start of a topic, move to previous topic
;
;General Algorithm when EI_VARHELP is turned on
;       Get Last topic from help history (should be displayed topic)
;       save topic
;       if (cursor not at start-of-topic)
;           Display Saved Topic  (will force cursor to start of topic)
;       else
;           while (New topic not displayed OK)
;               if (Topic Exists)
;                   Get Last topic from help history (topic to be displayed)
;                   Try to Display Topic
;               else
;                   Display Saved Topic

;
; We do not call HelpStart, as there is no reason to start the help system
; if it is not already started.  No Help => No Help Back => exit with error
;

        test    HelpFlags,HLP_GOTBUF    ; are we initialized?
        jne     Initialized             ; yes, see if we can get history
HelpBack_Err:
        cCall   CowMoo                  ; beep the speaker
DJMP    jmp     short HelpBack_Exit     ; and return

Initialized:
        cCall   RetrieveHelpHistory     ; get the currently displayed item
        jcxz    HelpBack_Err            ; no current topic? exit
                                        ; (possible if no help ask for yet)
        mov     si,dx                   ; set SI:DI = context info.
        mov     di,ax



        ;Test for cursor at begining of topic

        xor     ax,ax                   ; 0 to compare against
        cmp     fHelpVisible,al         ; help window visible?
        je      CurrentTopic            ; no, goto current topic

        cmp     EfHelp.EF_ipCur_ob,ax   ; at column 0?
        jne     CheckHotLink            ; no, goto initial position
        cmp     EfHelp.EF_ipCur_oln,ax  ; on first line?
        je      PreviousTopic           ; yes, goto previous topic

CheckHotLink:
        cCall   GetInitialPos           ; (DX,AX) is initial cursor position
        cmp     EfHelp.EF_ipCur_ob,ax   ; in the right column?
        jne     CurrentTopic            ; no, redisplay current topic
        cmp     EfHelp.EF_ipCur_oln,dx  ; in the right row?
        jne     CurrentTopic            ; no, redisplay current topic

PreviousTopic:
        cCall   RetrieveHelpHistory     ; get the item to goto
        jcxz    CurrentTopicBeep        ; none, beep and exit (CX = 0)

        cCall   DisplayHlpWndNc         ; display the topic
        cmp     al,HELP_HANDLED         ; did we get an error?
        je      CurrentTopic            ; yes, try to clean up and exit
        or      al,al                   ; did we succeed?
        jne     PreviousTopic           ; no, try topic before it

        jmp     short HelpBack_Exit     ; we succeeded, exit


CurrentTopicBeep:
        cCall   CowMoo                  ; tell user of error
CurrentTopic:
        mov     dx,si
        mov     ax,di
        cCall   DisplayHlpWndNc         ; display the topic

        ;any error at this point must have been caused by OOM or Missing varhelp

        or      al,al                   ; could we redisplay?
        je      HelpBack_Exit           ; yes, we are done
        cCall   GiveHelpOOM             ; display OOM message

HelpBack_Exit:
        DbAssertRel     curHelpFile,e,0,UI,<HelpBack: help file open>

cEnd

;***
;CmdHelpPrev - Goto Previous Help Topic
;
;Purpose:
;       The user has requested that we goto the previous help topic. Beeps
;       if this is not possible or the help window is not open.
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;Uses:
;       Per C Convention
;
;****

cProc   CmdHelpPrev,<PUBLIC,NEAR>
cBegin
        cmp     fHelpVisible,0                  ; help window visible?
DJMP    je      CmdHelpBeep                     ; no, beep and exit

DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<CmdHelpPrev:Help window open but not HLP_GOTBUF>
        and     HelpFlags,NOT (HLP_FAILFNF OR HLP_FAILOOM) ;  clear flags
        mov     bx,oCurTopic                    ; get ptr to current topic
        push    Word Ptr [bx].ContextNum+2      ; parameter to HelpNcPrev
        push    Word Ptr [bx].ContextNum
        cCall   HelpNcPrev                      ; get next NC
        mov     cx,ax                           ; is it 0? (non available)
        or      cx,dx
        jne     CmdHelpDisplay                  ; no, try to display it
        test    HelpFlags,HLP_FAILFNF OR HLP_FAILOOM ; already displayed msg
        jz      CmdHelpBeep                     ; no, topic not found=>beep
cEnd

;***
;CmdHelpNext - Goto Next Help Topic
;
;Purpose:
;       The user has requested that we goto the next help topic. Beeps
;       if this is not possible or the help window is not open.
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;Uses:
;       Per C Convention