uinhelp.asm

Microsoft MS-DOS6.0 完整源代码

;       cbMaxSize = biggest line to get.
;       cChar = control char to look for (usually 'n' or 'l').
;
;       DS:DI = * place to put result
;
;Exit:
;       DS:SI = * embedded help control info
;
;Uses:
;       Per convention, plus SI
;****

cProc   GetHelpControlInfo,<NEAR>
parmW   pHelpBdl                ; * bdl of current help context
parmW   cbMaxSize               ; biggest string allowed
parmW   cChar                   ; control char to search for (l or n)
cBegin

DbAssertRelB    fNoDelBufs,ne,0,UI,<GetHelpControlInfo:fNoDelBufs not set>

	; This routine does not have to worry about error handling for
	; HelpGetLine.  If there is any error in trying to get the
	; proper line, we will just assume that there were no more
	; lines.

	mov     bx,pHelpBdl     ; BX = *bdl of current help topic

	GETSEG  es,[bx].BDL_seg,bx,SIZE ; ES = context data segment
	mov     ax,-1                   ; AX = undefined for blasting help
	mov     es:[lnCurTH],ax         ; reset current line counter
					; so engine doesn't get confused
	xchg    es:[linCharTH],al       ; don't ignore any lines
	push    ax                      ; save line rejection char

	xor     si,si                   ; start at line 0

AnotherLine:
	inc     si                      ; advance to next line
	lea     bx,[bx].BDL_seg         ; BX = handle of data segment
	xor     ax,ax                   ; AX = context data offset (0)
	cCall   HelpGetLine,<si,cbMaxSize,ds,di,bx,ax>
	mov     bx,pHelpBdl             ; BX = *bdl of current help topic
	or      ax,ax                   ; any more lines?
	jz      NoEmbeddedInfo          ; brif not
	mov     ax,[di]                 ; AX = first 2 chars
	cmp     al,':'                  ; ":" command?
	jne     NoEmbeddedInfo          ; brif not -- they must come first
	cmp     ah,byte ptr (cChar)     ; the one we are searching for?
	jne     AnotherLine             ; brif not -- get another line

	mov     si,di                   ; DS:SI = *szTitle
	inc     si                      ; skip the ":"
	inc     si                      ; skip the control char
	SKIP2_PSW                       ; skip the XOR SI,SI
NoEmbeddedInfo:
	xor     si,si                   ; no szTitle found
	pop     ax                      ; restore old line rejection char
	GETSEG  es,[bx].BDL_seg,bx,SIZE ; ES = context data segment
	xchg    es:[linCharTH],al       ; restore old line rejection char
DbAssertRel     AX,E,-1,UI,<GetHelpControlInfo: AX should be -1>
	mov     es:[lnCurTH],ax         ; reset current line counter
					; so engine doesn't get confused

cEnd

;***
;SizeHelpContext
;
;Purpose:
;       Added with revision [2].
;
;       Returns total # of lines of help text for a given context, for use
;       in dialog box re-sizing, and scroll bar updating.
;
;
;Entry:
;       bdlText = * BDL containing a decompressed help context.
;
;Exit:
;       AX = iFileSize = # lines of help text present in this context.
;
;Uses:
;       Per Convention
;
;****

cProc   SizeHelpContext,<PUBLIC,NEAR>,<SI,DI>
ParmW   bdlText
cBegin
	mov     di,bdlText                      ; DI = *context BDL
	xor     si,si                           ; SI = count of # lines

Again:
	inc     si                              
	mov     cx,offset DGROUP:bufStdMsg      ; CX = &dummy sz
	mov     dx,CB_bufStdMsg                 ; DX = cbMax
	xor     ax,ax                           ; AX = context data offset (0)
	lea     bx,[di].BDL_seg                 ; BX = handle of data seg
	cCall   HelpGetLine,<SI,DX,DS,CX,BX,AX> 
	or      ax,ax                           ; success?
	jnz     Again                           ; brif so -- try again

	xchg    ax,si                           ; AX = # lines + 1
	dec     ax                              ; return AX = # lines
	mov     iFileSize,ax                    ; save # lines
cEnd


;***
;CmdHelpClose - Close the help window (from ESC)
;
;Purpose:
;       Close the help window.  Attached to the ESC accelerator.
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;Uses:
;       Per C Convention
;
;****

cProc   CmdHelpClose,<PUBLIC,NEAR>
cBegin
	mov     oCurTopic,0             ; indicate no valid help
	cCall   WndHelpClose            ; close the window
cEnd


	subttl  Miscellanious Help Routines
	page

;***
;GetNextNc      - Advance a NC to the next topic
;
;Purpose:
;       Get the next physical context number given a context num.
;       Will not wrap from one file to another.
;
;Entry:
;       DX:AX = current context number
;
;Exit:
;       if ZF set (zero)
;          No next topic
;          CX = 0
;          AL = error code      (HELP_HANDLED, HELP_NF)
;       else
;          DX:AX is context number
;          CX != 0
;
;Uses:
;       Per C Convention
;
;****

cProc   GetNextNc,<PUBLIC,NEAR>
cBegin
	and     HelpFlags,NOT (HLP_FAILFNF OR HLP_FAILOOM); clear errors
	push    dx                              ; value to compare against
	push    dx                              ; push current context number
	push    ax
	cCall   HelpNcNext                      ; get next Context Num
	pop     bx
	cmp     bx,dx                           ; is it in a different file?
	jne     GetNextNc_Err                   ; yes, give error
	mov     cx,ax                           ; check if no more contexts
	or      cx,dx                           ; NZ & CX != 0 if no error
	jnz     GetNextNC_exit                  ; exit if success
GetNextNc_Err:
	mov     al,HELP_HANDLED                 ; assume handled error
	test    HelpFlags,HLP_FAILFNF OR HLP_FAILOOM ; was it?
	jnz     GetNextNc_Err2                  ; yes, use this code
	mov     al,HELP_NF                      ; context not found
GetNextNc_Err2:
	xor     cx,cx                           ; set CX = 0, ZF
GetNextNc_exit:
cEnd


;***
;CreateContext - convert a number into a context string
;char *(NEAR CreateContext(iContextNumber ))
;
;Purpose:
;       This routine takes a number and an initial character and
;       creates a context string out of it. The context string will
;       be of the form  "-1234" were '-' is the character and "1234"
;       is an ASCII representation of the number.  The string is
;       returned in a static buffer.
;
;       The number must be 0 < iContextNumber < 32768
;
;Entry:
;       iContextNumber : integer which will be remaining digits
;
;Exit:
;       AX = pSz : near pointer to string with results
;
;Uses:
;       AX, BX, CX, DX.
;
;****

cProc   CreateContext,<NEAR,PUBLIC>
	parmW   HelpId                  
cBegin
	mov     al,VT_I2                ;Format an integer
	lea     bx,HelpId               ; BX = ptr to number to format

	DbAssertRel [bx],g,0,UI,<CreateContext: Bad Help ID>

	call    B$IFOUT                 ;BX = address of 0 terminated string

	mov     BYTE PTR [bx],PREFIX_MESSAGE ; Replace space with character
					; that belongs in first postion
	xchg    ax,bx                   ;return *sz in AX
cEnd

;***
;ShrinkHelp - Compress Help system memory usage
;
;Purpose:
;       Reduce the amount of memory that the help system uses without
;       impeeding the functionallity of the help system.
;
;       WARNING!!!
;           Any time that this routine may be called (i.e. any time an alloc
;           is done), you must either set fNoDelBufs or guarentee that
;           numBuf = 0, or guarentee that oCurTopic, oFirstBuf and oLastBuf
;           are correct.
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;Uses:
;       Per C Convention.
;
;****
cProc   ShrinkHelp,<PUBLIC,FAR>
cBegin

	DbHeapMoveOff                   ; FH callback can't cause movement

	test    HelpFlags,HLP_NOSHRINK  ; are we allowed to call HelpShrink?
	jnz     NoHelpShrink            ; no, check for deleting buffers
	cCall   HelpShrink              ; Tell help engine to shrink down
NoHelpShrink:


	cmp     fNoDelBufs,0            ; Can we delete help buffers also?
	jnz     ShrinkHelp_Exit         ; no, just return

	xor     cx,cx
	mov     cl,numBuf               ; cx = # buffers in use
	jcxz    ShrinkHelp_Exit         ; exit if there are none
	cmp     oCurTopic,0             ; do we have a current topic?
	jz      NoCurrentTopic          ; no, do not keep it in memory
	dec     cx                      ; do not delete the current topic
NoCurrentTopic:
	cCall   FlushBuffer             ; delete CX buffers
ShrinkHelp_Exit:


	DbHeapMoveOn                    ; remove our lock on the heap
cEnd

;***
;CompressHelp - Close down the help system
;
;Purpose:
;       This routine is called before we execute any user code so that
;       the help system can release all the memory that it does not need.
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;Uses:
;       AX,BX,CX,DX
;
;Preserves:
;       ES
;****

cProc   CompressHelp,<PUBLIC,FAR>,<ES>  
cBegin
	DbHeapMoveOff                   ; we are called from FHAlloc
					; not allowed to move heaps

	test    HelpFlags,HLP_GOTBUF    ; Help system started?
	jz      NoFreeHelpBuffer        ; brif not -- nothing to do

	cmp     fHelpAlloc,0            ; doing a help alloc?
	jnz     NoFreeHelpBuffer        ; yes, do not shut down help system

	xor     ax,ax                   ; Nc of 0 => close all files
	cCall   HelpClose,<AX,AX>       ; Shut down the help engine

	; we will ignore any file errors on the close


	cCall   DiscardHelpBookMarks    ; free bookmark ptrs into help


NoHelpBuffer:
	xor     ax,ax                   ; get a convenient 0
	mov     iStaticHelpTopic,ax     ; clear current search topic
	mov     oCurTopic,ax            ; clear current topic ptr.
	mov     iCurRequestLine,ax      ; clear GetHelpLine succeeded flag

	; zero the initial context number
	mov     WORD PTR ncInitial,ax   
	mov     WORD PTR ncInitial+2,ax

	or      HelpFlags,HLP_COMPRESS  ; flag help has been compressed
	cCall   DrawDebugScr            ; make sure screen is redrawn.

DbAssertRel     BdlHelpHist.BDL_Seg,ne,UNDEFINED,UI,<CompressHelp:HLP_GOTBUF is true, but no HistoryBuf Allocated>
	PUSHI   ax,<OFFSET DGROUP:BdlHelpHist>  ; Free up the history buf
	cCall   BdlFree                 
	mov     cl,numBuf               ; number of buffers to deallocate
	xor     ch,ch                   
	cCall   FlushBuffer             ; Delete all the help buffers
	and     HelpFlags,NOT HLP_GOTBUF ; indicate buffer unallocated

NoFreeHelpBuffer:
	DbHeapMoveOn                    ; remove our heap lock
cEnd



; ReWrote with [39]
;***
;GiveHelpOOM - Queue a message to give OOM for Help
;
;Purpose:
;       Indicate to the error handling code that an OOM error has occured
;       in the help system.  This routine may be called as many times as
;       desired before DisplayHelpOOM is called, and the error will only
;       be reported once.
;
;Entry:
;       None.
;
;Exit:
;       None.
;
;Uses:
;       By Convention
;
;****

cProc   GiveHelpOOM,<PUBLIC,NEAR>
cBegin
	or      HelpFlags,HLP_FAILOOM   ; indicate We failed due to OOM
	mov     ax,MSG_HelpOOM          
	cCall   SetUiErr,<AX>           
cEnd

;Added with [39]
;***
;DisplayHelpOOM - Display an OOM error
;
;Purpose:
;       Displays an OOM error messages box for help, closes the help window,
;       and resets static variables.
;
;Entry:
;       None.
;