uinhelp.asm

Microsoft MS-DOS6.0 完整源代码

	DbChk   HoldBuf2                ; lock down the HotSpot
	DbChk   HoldBuf1                ; for composed hotlink names

	mov     bx,oCurTopic            ; get ptr to topic
	lea     bx,[bx].bdlHelpText.BDL_seg ; BX = handle to data seg
	mov     cx,rx
	inc     cx                      ; make column 1 relative
	mov     HtSpot.colHS,cx         
	mov     cx,ry                   ; get line number
	inc     cx                      ; make it 1 relative
	mov     HtSpot.lineHS,cx        ; and stick in HotSpot structure
	mov     ax,OFFSET DGROUP:HtSpot
	xor     cx,cx
	and     HelpFlags,NOT (HLP_FAILFNF OR HLP_FAILOOM) ; clear errors
	cCall   HelpXRef,<BX,CX,DS,AX>  ;Get context string for topic
	or      ax,ax                   ; did we get a topic
	jnz     GotSelection            ; yes, go display it
	test    HelpFlags,HLP_FAILFNF OR HLP_FAILOOM ; is error handled?
	jnz     NoBeep                  ; yes, do not beep
SelectHotLink_Beep:
	cmp     GiveBeep,0              ; should we give a beep?
	je      NoBeep                  ; no, just exit with error code
	cCall   CowMoo                  ; beep cow's speaker
NoBeep:
	mov     ax,sp                   ; return with non-zero value
	DbChk   FreeBuf2                ; release the HotSpot
	DbChk   FreeBuf1                ;  and our other buffer
	jmp     short NoSelection       ; and exit

GotSelection:
	;Copy context string into free part of Buf2 and display it in a help
	;window. The source string is in HtSpot.pXrefHS and is 0 terminated
	;We can not use the source directly, as it points into a BDL, and
	;we are not guarenteing a locked heap.

	push    ds                              ; set ES = DS = DGROUP
	pop     es                              
	mov     di,offset dgroup:b$buf1         ; ES:DI = destination
	push    di                              ; parm for DislplayHlpWnd
	lds     si,DWord Ptr HtSpot.pXrefHS     ; DS:SI = source

CopyLoop:
	lodsb                                   ; copy the byte
	stosb                                   
	or      al,al                           ; is it the 0 termiantor
	jne     CopyLoop                        ; no, do next byte
	lodsw                                   ; Copy next word
	stosw                                   ; incase it was local

	push    es                              ; restore DGROUP
	pop     ds                              

	DbChk   FreeBuf2                        ; release the HotSpot

	; Check to see if the context is !B.  If it is, then we should
	; execute a HelpBack command instead of displaying the context

	cmp     WORD PTR b$Buf1,'B!'            ; is it !B?
	jne     NotHelpBack                     ; no, go display it
	cmp     BYTE PTR b$Buf1+2,0             ; is it 0 terminated?
	jne     NotHelpBack                     ; no, go display it
DbAssertRel     pwndAct,e,<OFFSET DGROUP:wndHelp>,UI,<SelectHotLink:Not in help window>
	pop     ax                              ; restore stack (param to
						;  DisplayHlpwndSz not used)
	xor     ax,ax                           ; move to (0,0) so we will
	cCall   MoveCursorPwndCur,<ax,ax>       ; goto previous topic
	DbChk   FreeBuf1                        ; incase HelpBack wants it
	call    HelpBack                        ; do the help back
	jmp     short ExitSuccess               ; and exit

NotHelpBack:
	cCall   DisplayHlpWndSz                 ; display text
DbAssertRelB    al,ne,HELP_NF,UI,<SelectHotLink:Returned hot link not found>
						;ignore any errors
	DbChk   FreeBuf1                        ; release context string

ExitSuccess:
	xor     ax,ax                           ; return value of success
						; this way we will not put
						; up an error box, then
						; do something useful.
NoSelection:

cEnd



;Rewrote with [5]
;***
;FillContextNext - Fill the next buffer with the desired context information
;
;Purpose:
;       Read a help context into the help buffer given the position that
;       is previous to it.  The information needed for the new context
;       is obtained from the context given.  This routine will read in
;       as many contexts as desired.
;
;       Note: this routine does not return any errors, as its caller
;       does not check the error code (this is used to fill the buffer
;       with topics after the current topic, so if we could not read
;       in a topic for any reason, then we will just leave the buffer
;       partially empty).
;
;Entry:
;       BX = current buffer
;       DI = number of context to read
;
;Exit:
;       oLastBuf = Last valid buffer
;       numBuf updated
;
;****

cProc   FillContextNext,<NEAR>,<DI>
cBegin

DbAssertRelB    fNoDelBufs,ne,0,UI,<FillContextNext:Caller did not set fNoDelBufs>


cEnd


;Added with [5]
;***
;GetHelpMsgNcFill - get a help message from a context number, fill in fields
;
;Purpose:
;       Calls GetHelpMsgNc, and fills in all the fields of the buffer except
;       for the first line number of the context.
;
;Entry:
;       DX:AX = context number to be filled in
;       BX = ptr to context
;Exit:
;       if (AL = 0)
;           BX = ptr to context
;           all fields of context are filled in
;       else
;           AL = HELP_HANDLED.
;
;****
cProc   GetHelpMsgNcFill,<NEAR>
cBegin
	push    bx                              ; We need to preserve BX
	mov     Word Ptr [bx].ContextNum,ax     ; save Context Num in Buffer
	mov     Word Ptr [bx].ContextNum+2,dx
	lea     cx,[bx].bdlHelpText             ; point to BLD
	cCall   GetHelpMsgNc,<dx,ax,cx>         ; get message
						; (AL = return code)
	pop     bx                              ; BX = *Buffer

Fill_Exit:
cEnd

;***
;GetHelpMsgSz - get a help message from a context string
;GetHelpMsgNc - get a help message from a context number
;
;Purpose:
;       This routine calls the help engine to obtain the help text
;       associated with a context string.  The text is returned in a BDL.
;       No buffering of the help context is performed.
;
;       NOTE: Does not require oFirstBuf or oLastBuf to be set.
;
;Entry:
;       szContext : pointer to context string
;       BdlText : pointer to bdl owner structure.
;
;Exit:
;       AL = HELP_OK (0) if success.
;       AL = HELP_HANDLED, HELP_NF
;
;Uses:
;       Per convention
;
;Exceptions:
;       
;****
cProc   GetHelpMsgSz,<NEAR,PUBLIC>
parmW   szContext
parmW   BdlText
cBegin
DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<GetHelpMsgSz:HLP_GOTBUF false>
	mov     ax,szContext            ; AX = context string
	cCall   CalcNc,<AX>             ; DX:AX = nc for context string
	jcxz    GetHelpMsgSzExit        ; return with error code (AL) if error

	cCall   GetHelpMsgNc,<DX,AX,BdlText> ; get message
GetHelpMsgSzExit:
cEnd

DbPub   GetHelpMsgNc
cProc   GetHelpMsgNc,<NEAR>,<SI,DI>
parmW   ncHigh
parmW   ncLow
parmW   BdlText
cBegin
DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<GetHelpMsgNc:HLP_GOTBUF false>
DbAssertRelB    fHelpAlloc,ne,0,UI,<GetHelpMsgNc:fHelpAlloc not set>

	mov     di,ncHigh               ;set DI:SI to context string
	mov     si,ncLow

	and     HelpFlags,NOT (HLP_FAILFNF OR HLP_FAILOOM) ; clear flags

	cCall   HelpNcCb,<DI,SI>        ; AX = #bytes for decompressed topic

	xchg    ax,cx                                   ; save size in CX
	test    HelpFlags,HLP_FAILFNF OR HLP_FAILOOM    ; did we fail it?
	mov     al,HELP_HANDLED                         ; assume so
	jnz     GetHelpMsgNcExit_Near                   ; exit if error

	mov     bx,offset DGROUP:BdlTemp
	cCall   BdlAlloc,<BX,CX>        ; alloc bdl for compressed data
	or      ax,ax                   ; OOM error?
	jz      GetHelpMsgOOM           ; yes, go handle it

	lea     bx,[BdlTemp.BDL_seg]    ; BX = handle to data segment
	xor     ax,ax                   ; offset 0
	cCall   HelpLook,<DI,SI,BX,AX>  ; AX = # bytes uncompressed
	xchg    cx,ax                   ; CX = # bytes uncompressed
	jcxz    FreeExitError           ; brif error -- release bdl & exit

	inc     fNoDelBufs              ; don't delete buffers

	mov     bx,BdlText              ; bx = *BDL owner
	cCall   BdlAlloc,<BX, CX>       ; alloc BDL for uncompressed data
	or      ax,ax                   ; ZF ==> error
	jnz     DecompressHelp          ; no error, go decompress help topic
	cCall   GiveHelpOOM             ; generate OOM error
	dec     fNoDelBufs              ; restore buffer flag
	jmp     short FreeExitError     ; free Bdl and exit

GetHelpMsgOOM:
	cCall   GiveHelpOOM             ; signal an OOM error
	mov     al,HELP_HANDLED         
GetHelpMsgNcExit_Near:                  
	jmp     Short GetHelpMsgNcExit  ; brif so -- give error and exit

DecompressHelp:
DbAssertTst     HelpFlags,z,HLP_NOSHRINK,UI,<GetHelpMsgNc:NOSHRINK set>
	or      HelpFlags,HLP_NOSHRINK  ; don't shrink during HelpDecomp
					; otherwise it will fail.
	mov     bx,BdlText              ; bx = *BDL owner (could have moved)
	xor     ax,ax                   ; offset 0
	lea     dx,[BX].BDL_seg         ; DX = handle of destination seg
	lea     bx,[BdlTemp.BDL_seg]    ; BX = handle of source segment
	cCall   HelpDecomp,<BX,AX,DX,AX,DI,SI>
					; decompress help text
	dec     fNoDelBufs              ; reset buffer delete flag
	and     HelpFlags,NOT HLP_NOSHRINK ; reenable shrinking.

	or      ax,ax                   ; did we get an error?
	jz      FreeExit                ; no, free temp BDL and exit
	mov     ax,BdlText              ; get pointer to bdl
	cCall   BdlFree,<AX>            ; and deallocate it

	test    HelpFlags,HLP_FAILOOM or HLP_FAILFNF ; have we reported?
	jnz     FreeExitError           ; yes, get return code
	cCall   GiveHelpOOM             ; report the error.

FreeExitError:
	mov     al,HELP_HANDLED         ; prepare to return error

FreeExit:
	push    ax                      ; save return code
	mov     ax,OFFSET DGROUP:BdlTemp
	cCall   BdlFree,<AX>            ; release compressed data

	pop     ax                      ; AX = return code (NZ ==> success)

GetHelpMsgNcExit:

cEnd


	subttl  Display Text in the Help Window

;Rewrote with [5]
;***
;DisplayHlpWndSz - Display help in a window given a context string
;DisplayHlpWndNc - Display help in a window given a context number
;
;Purpose:
;       Displays a context in the help window given either a context
;       string (DisplayHlpWndSz) or a context number (DisplayHlpWndNc).
;       This routine will open the help window if it is not already
;       opened.
;
;Entry:
;       szContext : pointer to a context string  (DisplayHlpWndSz)
;                          or
;       DX:AX     : context number               (DisplayHlpWndNc)
;
;Exit:
;       AL = error code (HELP_OK, HELP_HANDLED, HELP_NF)
;
;Uses:
;       Per Convention
;
;****

cProc   DisplayHlpWndSz,<PUBLIC,NEAR>
parmW   szContext
cBegin

DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<DisplayHlpWndSz:HLP_GOTBUF false>

	mov     ax,szContext            ;AX = context string
	cCall   CalcNc,<AX>             ; DX:AX = nc for context string
	jcxz    HlpWndSzExit            ; there was an error, exit
	cCall   DisplayHlpWndNc         ;display help for this context number

HlpWndSzExit:                           ;AL = return code
cEnd


cProc   DisplayHlpWndNc,<PUBLIC,NEAR>
cBegin

DbAssertTst     HelpFlags,ne,HLP_GOTBUF,UI,<DisplayHlpWndNc:HLP_GOTBUF false>

	cCall   BufferNc                ; BX = ptr to new context
	or      al,al                   ; was there an error?
	jne     DisplayFailure          ; yes, exit with error code

	push    bx                      ; save buffer pointer
	mov     dx,Word Ptr [bx].ContextNum+2  ; Get context number into
	mov     ax,Word Ptr [bx].ContextNum    ;  DX:AX
	cCall   RecordHelpHistory       ; record context number for Ctrl-F1
	pop     bx                      ; restore buffer pointer

	lea     ax,[bx].bdlHelpText     
	push    ax                      ; save for call to GetHelpContextLen
	cCall   SizeHelpContext,<ax>    ; get # lines in the help topic
					; sets iFileSize
	cCall   GetHelpContextLen       ; AX = get suggested size of wnd
	cCall   OpenHelpWindow          ; go open the window (to size AX)
	cCall   DrawDebugScr            ; force help title to be redrawn

	xor     ax,ax                   ; return 0 for no-errors

DisplayFailure:
	cCall   CloseCurHelpFile        ; shut down current help file, if
					; any opened. (preserves AX, DX)
cEnd




;***
;BufferNc - Given a context number, properly buffer in context
;
;Purpose:
;       This routine will refill the help buffer so that Nc is
;       present.  If Nc did not exist, the buffer is flushed and
;       refilled.
;
;Entry:
;       DX:AX   : Context number to be buffered
;
;Exit:
;       if (successful)
;               AL = HELP_OK  (=0)
;               BX = new buffer ptr
;               numBuf updated
;               oCurTopic = BX
;       else
;               AL = HELP_HANDLED
;
;****
cProc   BufferNc,<PUBLIC,NEAR>,<DI>
cBegin

	;See if the context number is already buffered