uinhelp.asm

[随书类]Dos6.0源代码

;
;Purpose:
;	This routine will not only open the help window to the correct
;	size, but will adjust the size of the window to account
;	for the existance/non existance of the scroll bar.
;
;Entry:
;     ax = Size of window
;
;Exit:
;     None.
;****

DbPub OpenHelpWindow
cProc OpenHelpWindow,<NEAR>
cBegin
	cmp	pwndAct,OFFSET DGROUP:WndHelp ; in help window?
	je	InHelpWindow		; no, do not resize

	inc	ax			; add a line for scroll bar
InHelpWindow:
	cCall	WndHelpOpen,<AX>	; AX = actual size of window

	; We must always move the cursor to (0,0), otherwise the edit
	; manager may not realize that this is a new topic and would not
	; position it so that the first line is visible.

	xor	bx,bx			; cursor position is 0,0
	mov	ax,OFFSET DGROUP:wndHelp; window to receive the message
	push	ax			; save for second call
	cCall	MoveCursorPwnd,<AX,BX,BX> ; goto 0,0 in window

	cCall	GetInitialPos		; get initial position on screen

	cCall	MoveCursorPwnd,<DX,AX>	; goto hot link spot
cEnd

;***
;GetInitialPos - Calculate the initial cursor position in the help window
;
;Purpose:
;	Returns the initial cursor position in the help window.  This is
;	the (0 relative) coordinates of the first hot link (if it exists
;	and is visible), or (0,0).
;
;Entry:
;	None
;
;Exit:
;	(DX,AX) - initial Row/Column of the screen (0,0) or first hot spot
;
;Uses:
;	Per C Convention.
;****
cProc	GetInitialPos,<PUBLIC,NEAR>
cBegin
	DbChk	HoldBuf2		; lock down the hotspot

	test	HelpFlags,HLP_VARHELP	; are we in var help?
	jnz	Use00			; yes, there are no hotlinks

	mov	ax,1			; current row/column position
	mov	HtSpot.ColHS,ax 	
	mov	HtSpot.lineHS,ax	

DbAssertRel	oCurTopic,ne,0,UI,<GetInitialPos:oCurTopic invalid>
	mov	bx,oCurTopic
	lea	bx,[bx].bdlHelpText.BDL_seg
	mov	cx,OFFSET DGROUP:HtSpot
	dec	ax			; ax = 0
	cCall	HelpHlNext,<AX,BX,AX,DS,CX>
	or	ax,ax			; did we get a hot link?
	je	Use00			; no, use (0,0) as position
	mov	ax,HtSpot.ColHS 	; get position of hotlink
	mov	dx,HtSpot.lineHS	
	dec	dx			; make position 0 relative
	dec	ax
	
	; Make sure the hot link is visible.
	
	mov	cl,WndHelp.arcClipping.ayBottomArc
	sub	cl,WndHelp.arcClipping.ayTopArc ; CX = size of help window

	cmp	cl,dl			; within visible range?
	jae	GetInitialPos_Exit	; no, ignore the hotlink
Use00:
	xor	dx,dx
	xor	ax,ax

GetInitialPos_Exit:
	DbChk	FreeBuf2		; release HotSpot
cEnd

	subttl	Edit Manager Support Routines
	page



;Extracted and modified with revision [29].
;***
;GetHelpTitleStr - Returns the title for a given help topic
;
;Purpose:
;	Calculates the title, and returns it in bufStdMsg.
;	All titles are prefixed by "HELP: ".
;
;	Uses the ":n" information if the help file, if it exists.
;	Otherwise, returns the current context string.
;
;Entry:
;	pHelpBdl = *bdl containing decompressed help topic.
;	cbMaxSize = max title length allowed
;
;	If window help, curNc is the help context #
;	If dialog box help, szDialogHelpContext points to the current szContext
;
;Exit:
;	AX = number of characters in title
;	bufStdMsg = contains title.
;
;Uses:
;	Per Convention
;
;****
cProc	GetHelpTitleStr,<NEAR,PUBLIC>,<SI,DI>
parmW	pHelpBdl
parmW	cbMaxSize
cBegin

DbAssertTst	HelpFlags,nz,HLP_GOTBUF,UI,<GetHelpTitleStr:HLP_GOTBUF false>

	inc	fNoDelBufs		; do not delete buffers, we have
					; a generic ptr to a buffer

	; Setting fNoDelBufs is probably not needed as currently
	; pHelpBdl points to either oCurTopic or to a static
	; Bdl used by dialog help.	However, I doubt that we do any
	; allocs in this code, and I can not guarentee that pHelpBdl
	; is safe.


	mov	ax,MSG_HelpTitleQH	; first part of title ("MS-DOS Help: ")
	test	cmdSwitches,CMD_SW_QHELP ; /QHELP viewer?
	jnz	ghts1			;   YES, got title

	mov	ax,MSG_HelpTitle	; first part of title ("HELP: ")
ghts1:
	cCall	ListStdMsg,<AX> 	; put in bufStdMsg

	push	ax			; save length of static portion
	add	ax,OFFSET DGROUP:bufStdMsg ; ds:di = useful buffer
	xchg	di,ax
	mov	al,'n'			; look for ":nTITLE"
	cCall	GetHelpControlInfo,<pHelpBdl,cbMaxSize,ax> ; SI = *embedded title, if any
	or	si,si			; title found?
	jnz	AppendTitle		; brif so

	mov	si,szDialogHelpContext	; use current context string as title
					; for dialog box help
	cmp	pHelpBdl,offset DGROUP:bdlHelp	; title for dialog box help?
	je	AppendTitle		; brif so -- append string to title

	mov	bx,oCurTopic		; ptr to current topic data
	or	bx,bx			; is it valid?
	je	GetHelpTitleStr_Fail	; no, use MSG_HelpTitle for now

	push	ds			;push far address to load szContext
	push	di
	push	Word Ptr [bx].ContextNum+2 ; push context number
	push	Word Ptr [bx].ContextNum
	cCall	HelpSzContext		;Get text
	or	ax,ax			; did we succeed?
	je	GetHelpTitleStr_Fail	; no, exit with error

	;Strip off the filename at the begining of the context

	cCall	szSrchExcl,<di> 	; search for '!' in *di
	DbAssertRel ax,ne,0,UI,<GetHelpTitleStr: Illegal string from HelpSzContext>
	inc	ax			; point to chr beyond '!'
	xchg	si,ax			;di = *buffer, si = *szContext

AppendTitle:				; append title to bufStdMsg
					; DS:SI= *title
					; DS:DI= where to put it

	pop	bx			; BX = length of static portion
	push	ds			; ES = DS for string ops
	pop	es			

AnotherChar:				
	lodsb				; append szTitle to "HELP:" in
	stosb				; bufStdMsg
	inc	bx			; seen another char
	or	al,al			; more chars to do?
	jnz	AnotherChar		; brif so
	dec	bx			; don't  include NULL in count

	cmp	bx,cbMaxSize		; is it larger than we want to return
	jbe	GetHelpTitleStr_Exit	; no, exit
	mov	bx,cbMaxSize-1		; return maximum size (without NULL)
	mov	byte ptr [bufstdMsg+bx+1],al ; truncate the string

GetHelpTitleStr_Exit:			
	xchg	ax,bx			; return count in AX

	SKIP1_PSW			; skip the pop ax
GetHelpTitleStr_Fail:			
	pop	ax			; get length in case of error
	dec	fNoDelBufs		; reenable buffer deletes.
	DbAssertRel ax,be,cbMaxSize,UI,<GetHelpTitleStr: title too big>
cEnd

;Added with revision [29].
;***
;GetHelpContextLen - Returns the length to use for a given help topic
;
;Purpose:
;	Returns the suggested # lines to use to display a topic.
;	Uses ":lLENGTH" if it exists. Otherwise, returns the total # lines
;	in the topic.
;
;Entry:
;	pHelpBdl = *bdl containing decompressed help topic.
;
;Exit:
;	AX = number of lines to use
;
;Uses:
;	Per Convention
;
;****
cProc	GetHelpContextLen,<NEAR,PUBLIC>,<SI,DI>
parmW	pHelpBdl
cBegin
	inc	fNoDelBufs		; do not delete buffers, we have
					; a generic ptr to a buffer

	; Setting fNoDelBufs is probably not needed as currently
	; pHelpBdl points to either oCurTopic or to a static
	; Bdl used by dialog help.	However, I doubt that we do any
	; allocs in this code, and I can not guarentee that pHelpBdl
	; is safe.

	mov	di,OFFSET DGROUP:bufStdMsg ; ds:di = useful buffer
	mov	cx,6			; max len we care about
	mov	al,'l'			; look for ":l<LENGTH>"
	cCall	GetHelpControlInfo,<pHelpBdl,cx,ax> ; SI = *embedded len,
	or	si,si			; length found?
	jz	GetTotalLines		; brif not -- get the line count

	push	si			; arg on stack
	call	_atoi			; AX = result
	pop	bx			; clean stack (C calling conventions)
	jmp	SHORT GetHelpContextLen_Exit

GetTotalLines:
	cCall	SizeHelpContext,<pHelpBdl> ;AX = # lines in context
					; sets iFileSize

GetHelpContextLen_Exit:
	dec	fNoDelBufs		 ; reenable buffer deletes.
cEnd


;Extracted and modified with revision [29].
;***
;GetHelpControlInfo
;
;Purpose:
;	Returns the control information in a given help context, if any.
;
;Entry:
;	pHelpBdl = * bdl containing decompressed help topic
;	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
;
;****