uiinfhlp.asm

Dos6.0

;
;****

cProc   CmdHelpNext,<PUBLIC,NEAR>
cBegin

        cmp     fHelpVisible,0                  ; help window visible?
        je      CmdHelpBeep                     ; no, beep and exit

DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<CmdHelpNext:Help window open but not HLP_GOTBUF>
        mov     bx,oCurTopic
        mov     dx,Word Ptr [bx].ContextNum + 2 ; DX:AX = old context num
        mov     ax,Word Ptr [bx].ContextNum
        cCall   GetNextNc                       ; Set DX:AX
        jz      CmdHelpError                    ; check for errors
CmdHelpDisplay:                                 ; Called from CmdHelpPrev
        cCall   DisplayHlpWndNc
        or      al,al                           ; did we succeed?
        je      CmdHelpNext_Exit                ; yes, return.
CmdHelpError:
        cmp     al,HELP_HANDLED                 ; Will someone else handle?
        je      CmdHelpNext_Exit                ; yes, just exit
DbAssertRelB    al,e,HELP_NF,UI,<CmdHelpNext:Illegal error>

CmdHelpBeep:                                    ; NOTE: shared label
        cCall   CowMoo                          ; beep the speaker
CmdHelpNext_Exit:
cEnd

;Routine added with [1]
;***
;NormalizeTopic - Convert a context number to a standard form
;
;Purpose:
;       The current implementation of the help engine allows a piece of text
;       to have multiple context strings, thus multiple context numbers.
;       While searching, we use the context number to specify when we have
;       wrapped around the file and reached the starting point.  Thus, we
;       have to Normalize the topic number so it is the same one that will
;       be returned from HelpNcPrev or HelpNcNext.
;
;Entry:
;       AX : topic ID
;
;Exit:
;       if (CX != 0)
;          DX:AX : topic number
;       else
;          error (will have been signaled)
;
;Uses:
;       Per C Convention
;****

cProc   NormalizeTopic,<NEAR>
cBegin
        push    ax                      ; preserve Topic ID
        mov     dx,iStaticHelpTopic     ; DX:SI = context number
        ccall   HelpNcNext,<iStaticHelpTopic,AX> ; get previous one
        pop     bx                      ; BX = topic ID
        mov     cx,ax                   ; did we succeed?
        or      cx,dx
        jz      PrevNext                ; no, try to get one after the topic ID
        cCall   HelpNcPrev,<DX,AX>      ; yes, do a Prev to get normalized NC
        jmp     short CheckReturn       ; and return it
PrevNext:
        cCall   HelpNcPrev,<iStaticHelpTopic,bx> ; get NC before topic ID
        mov     cx,ax                   ; did this succeed?
        or      cx,dx
        jz      NormalizeExit_Err       ; no, exit with error
        cCall   HelpNcNext,<DX,AX>      ; get topic after that one

CheckReturn:
        mov     cx,ax                   ; set error condition
        or      cx,dx

NormalizeExit_Err:
cEnd


;***
;ChngHelpCurTopic - Cleans up after a help search
;
;Purpose:
;       The three routine set (GetHelpCurTopic, GetHelpNextTopic,
;       ChngHelpCurTopic) are used for a search or scan of the help file.
;
;       This routine will take a topic ID that was used to terminate
;       the search and prepare things for continued operation of the
;       help system.  This routine should only be called if we are
;       exiting from a search in a topic other than the original
;       topic, and want to change that topic to be the new current topic.
;
;Entry:
;       CX = previous topic
;
;Exit:
;       None.
;****
cProc   ChngHelpCurTopic,<NEAR>
cBegin

DbAssertTst     HelpFlags,e,HLP_VARHELP,UI,<ChngHelpCurTopic:Called when HLP_VARHELP>
        mov     ax,cx                   ; Set DX:AX to NC of topic
        mov     dx,iStaticHelpTopic
        or      dx,dx                   ; check to see if it is valid
        je      ChngHelp_Exit           ; no, just exit (we will close help wnd)

        inc     cx                      ; Topic ID = UNDEFINED ?
        je      ChngHelp_Exit           ; brif - identifier is invalid.

DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<ChngHelpCurTopic:iStaticHelpTopic non 0 without HLP_GOTBUF>

        cCall   RecordHelpHistory       ; record topic in help history list
ChngHelp_Exit:
        cCall   DrawDebugScr            ; make sure screen is redrawn so
                                        ; we get proper help title.
cEnd

;***
;GetHelpNextTopic - Prepares the next topic for looking
;
;Purpose:
;       The three routine set (GetHelpCurTopic, GetHelpNextTopic,
;       ChngHelpCurTopic) are used for a search or scan of the help file.
;
;       This routine will take a Topic ID and return the next physical
;       Topic ID.  If the presented Topic ID was the last one in a section,
;       this routine will wrap around to the begining of the section.
;
;
;Entry:
;       CX = previous topic
;
;Exit:
;       AX = new Topic Identifier if engine help
;            0                    if var help (will work as topic id)
;            UNDEFINED            if error
;****

cProc   GetHelpNextTopic,<NEAR>,<DI>
cBegin
        DbChk   HoldBuf1                ; use BUF1 as a temporary buffer

        test    HelpFlags,HLP_COMPRESS  ; help shutting down
DJMP    jnz     NextTopic_Exit          ; yes, exit


        mov     dx,iStaticHelpTopic     ; get static high word of NC
        or      dx,dx                   ; is it 0 (help system shut down)
DJMP    je      NextTopic_Fail          ; yes, return error

DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<GetHelpNextTopic:iStaticHelpTopic non 0 without HLP_GOTBUF>

        mov     ax,cx                   ; DX:AX = old topic number
        cCall   GetNextNc               ; DX:AX = next context number
DJMP    jnz     GotNextTopic            ; we were successful

        cmp     al,HELP_HANDLED         ; error message already displayed?
DJMP    je      NextTopic_Fail          ; yes, return error code

DbAssertRelB    al,e,HELP_NF,UI,<GetHelpNextTopic:illegal error from GetNextNc>



        ;Goto the first topic of this section of the file.  We are guarenteed
        ;that the topic h.pg1 (MSG_FirstContextStr) exists at the begining of
        ;each section of the help system.  Thus, we pick off the file name
        ;part of any context string of the section and goto filename!h.pg1


        mov     bx,oCurTopic                    ; get ptr to a legal buffer
        mov     di,OFFSET DGROUP:B$Buf1         ; store results in B$Buf1
        push    ds                              ; far ptr to buffer
        push    di
        push    Word Ptr [bx].ContextNum+2      ; context number
        push    Word Ptr [bx].ContextNum
        cCall   HelpSzContext                   ; get current filename
        or      ax,ax                           ; was the call successful?
        je      NextTopic_Fail                  ; no, exit with error

        cCall   szSrchExcl,<DI>                 ; AX = pos of '!' or 0
DbAssertRel     ax,ne,0,UI,<szComposeContext:Illegal string from HelpSzContext>

        mov     bx,MSG_FirstContextStr          ; message to append
        cCall   AppendBuf,<AX,BX>               ; stick it on
        xchg    ax,bx
        mov     Byte Ptr [bx],0                 ; and 0 terminate it.

        ;Get the context number + context for this name
        ;param for CalcNc pushed above

        cCall   CalcNc,<DI>             ; convert to context number
        jcxz    NextTopic_DbFail        ; brif we couldn't locate it

        cCall   NormalizeTopic          ; normalize topic number
        jcxz    NextTopic_Fail          ; brif it can't be normalized

GotNextTopic:
        mov     di,ax                   ; save value to be returned
        cCall   BufferNc                ; BX = ptr to buffered context
        or      al,al                   ; error in buffering?
        jne     NextTopic_Fail          ; yes, return with error code
        lea     ax,[bx].bdlHelpText     ; get ptr to BDL
        cCall   SizeHelpContext,<ax>    ; AX = # lines in this topic
                                        ; sets iFileSize
        xchg    ax,di                   ; restore return value
        jmp     short NextTopic_Exit    ; and return

NextTopic_DbFail:
        DbAssertRelB al,ne,HELP_NF,UI,<GethelpNextTopic:h.pg1 missing from file>


        ;If we get a fatal error, we have to close the help window.  There
        ;is no guarentee that we can redisplay the original topic, and to
        ;display some random topic would be poor.  Thus, make sure the
        ;bit to close the help window in DoDrawDebugScr is set.

NextTopic_Fail:
        or      HelpFlags,HLP_COMPRESS  ; close help window at earliest time
        mov     ax,UNDEFINED            ; assume we will get an error
NextTopic_Exit:
        DbChk   FreeBuf1                ; release buffer
cEnd

;***
;GetHelpCurTopic - Start search and returns the current topic id
;
;Purpose:
;       The three routine set (GetHelpCurTopic, GetHelpNextTopic,
;       ChngHelpCurTopic) are used for a search or scan of the help file.
;
;       This routine will prepare for a linear scan of the help file
;       and will return the Topic Id for the currently displayed help
;       topic.
;
;       A Topic ID is a word that references a help topic.  It is the
;       lower word of a NC, so it is valid only as long as we do not
;       shut down the help system.
;
;Entry:
;       None.
;
;Exit:
;       AX = cur Topic Identifier if engine help
;            0                    if var help (will work as topic id)
;            UNDEFINED            if error
;****

cProc   GetHelpCurTopic,<NEAR>
cBegin
        test    HelpFlags,HLP_GOTBUF    ; are we initialized?
        mov     ax,UNDEFINED            ; assume not
        je      CurTopic_Exit           ; brif not - give error and ret.


DbAssertRel     oCurTopic,ne,0,UI,<GetHelpCurTopic:oCurTopic invalid>
        mov     bx,oCurTopic            ; get a pointer to the current topic
        mov     ax,Word Ptr [bx].ContextNum ; get topic specific part of NC
        mov     dx,Word Ptr [bx].ContextNum+2
        mov     iStaticHelpTopic,dx     ; save static part of NC
        cCall   NormalizeTopic          ; Normalize the topic number
        inc     cx                      ; JCXNZ
        loop    CurTopic_Exit           ; brif success
        mov     ax,-1                   ; set failure flag
CurTopic_Exit:

cEnd

;Added with [4]
;***
;RestoreHelpTopic - Return help system to state before a search
;
;Purpose:
;       The search code needs the original help topic restored to the screen.
;       We get the topic from the help history list and redisplay it.
;
;       Note: we can not use DisplayHlpWndNc, as it will change the position
;       of the cursor and resize the window.
;
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;****

DbPub   RestoreHelpTopic
cProc   RestoreHelpTopic,<NEAR>
cBegin
        test    HelpFlags,HLP_VARHELP   ; are we in variable help?
        jnz     exit                    ; yes, exit. nothing to restore
        cCall   RetrieveHelpHistory     ; get the last history item
DbAssertRel     cx,ne,0,UI,<RestoreHelpTopic:History list empty>
        push    ax                      ; save context number
        push    dx
        cCall   BufferNc                ; load context into memory, al=err code
        pop     dx                      ; restore context number
        pop     cx
        or      al,al                   ; any errors?
        jne     RestoreTopic_Fail       ; yes, handle them
        push    bx                      ; save ptr to help context
        xchg    ax,cx                   ; DX:AX = context number
        cCall   RecordHelpHistory       ; save this in the history list
        pop     bx                      ; return ptr to help context
        lea     ax,[bx].bdlHelpText     ; Get ptr to BDL of this help topic
        cCall   SizeHelpContext,<ax>    ; calculate size, set iFileSize
        jmp     short exit              ; get out of here

RestoreTopic_Fail:
        DbAssertRelB    al,e,HELP_HANDLED,UI,<RestoreHelpTopic:Unable to regenerate initial topic>
        or      HelpFlags,HLP_COMPRESS  ; no error should have happened, we
                                        ; have no idea what state we are in,
                                        ; so close help window
exit:
cEnd

;***
;GetHelpTitle - Returns the title for the currently displayed help item
;
;Purpose:
;       Calculates the title that should go on the help window and
;       returns it in bufStdMsg.
;
;Entry:
;       CX = max title length allowed
;
;Exit:
;       AX = number of characters in title
;       bufStdMsg = contains title.
;
;Uses:
;       Per Convention
;****

DbPub   GetHelpTitle
cProc   GetHelpTitle,<NEAR>,<SI>
cBegin
        mov     si,cx                   ; SI = cbMaxTitle
        mov     ax,MSG_HelpTitleQH      ; first part of title ("MS-DOS Help: ")
        test    cmdSwitches,CMD_SW_QHELP ; /QHELP viewer?
        jnz     ght1                    ;   YES, got title

        mov     ax,MSG_HelpTitle        ; Yes normal help window title

ght1:
        cCall   ListStdMsg,<AX>         ; put in bufStdMsg

        mov     bl,HelpFlags                    ; get a copy of the flags
        and     bl,HLP_GOTBUF or HLP_COMPRESS   ; mask out all but these
        cmp     bl,HLP_GOTBUF                   ; brif NOT HLP_GOTBUF or
        jne     GetHelpTitle_Exit               ;  HLP_COMPRESS

; HLP_INHELP will only be set if we are about to do something that can
; put up a dialog/message box.  If this routine is called with it set,
; then we are trying to redraw the screen after the box has been removed.
; This can be dangerious, as we may not be in a state where we can
; generate a help title.  So return with what we have.

        test    HelpFlags,HLP_INHELP    ; are we called recursively?
        jz      NotRecursiveGHT         ; no, try to get a title
        cmp     fMessageBox,0           ; are we in a dialog box?
        jnz     GetHelpTitle_Exit       ; yes, exit with what we have.

NotRecursiveGHT:


HelpTitleNotVarHelp:
        mov     bx,oCurTopic
        or      bx,bx                   ; current topic invalid?
        je      GethelpTitle_Exit       ; yes, return with what we have
        lea     ax,[bx].bdlHelpText     ; get ptr to the BDL