COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

	Copyright (c) GeoWorks 1991 -- All Rights Reserved

PROJECT:	Handwriting Recognition Library
FILE:		hwr.def


REVISION HISTORY:
	
	Name	Date		Description
	----	----		-----------
	atw	12/11/91	Initial revision


DESCRIPTION:
	This file contains exported routines/structures for the HWR library.
		
	$Id: hwr.def,v 1.1 97/04/04 14:23:04 newdeal Exp $

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@

SetDef	__HWR

StartLibrary	hwr

;----------------------------------------------------------------------------
;		HWR library protocol
;----------------------------------------------------------------------------

; All hwr libraries will need to have the following line in their
; local.mk file:
;	PROTOCONST	= HWRLIB
;

HWRLIB_PROTO_MAJOR		equ	2
HWRLIB_PROTO_MINOR		equ	0
HWRLIB_PROTO_MAJOR_FOR_2_1	equ	2

; This is the number of library entry points reserved for future use.
;
HWR_NUMBER_RESERVED_ENTRIES	equ	16

COMMENT @%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

MACRO:		CallHWRLibrary

DESCRIPTION:	Call the hand writing library

ARGUMENTS:
	entrynum	Library entry number

CAVEATS:
	requires the local variable libHandle

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@
CallHWRLibrary	macro	entrynum
	mov	ax, entrynum
	mov	bx, libHandle
	call	ProcGetLibraryEntry
	call	ProcCallFixedOrMovable

endm

if DBCS_PCGEOS 
HWR_STRING_ESCAPE_VALUE		=	0xee01
else
HWR_STRING_ESCAPE_VALUE		=	0xff01
endif

;
;NOTE: All of the HWR Library routines are assumed to destroy:
;
;		AX,BX,CX,DX,ES
;
;	And they preserve
;
;		BP, DI, SI, DS	
;

HWRRoutine	etype	word

HWRR_BEGIN_INTERACTION			enum HWRRoutine
HWRR_END_INTERACTION			enum HWRRoutine
;
;	Most HWR drivers can not handle multiple clients at once. Clients
;	should call HWRR_BEGIN_INTERACTION before any other HWR calls, and
;	HWRR_END_INTERACTION after their HWR calls.
;
;	NOTE: Assume that after you call HWRR_END_INTERACTION, all of the
;	      parameters you've set up (points added, filters activated) will
;	      be destroyed.
;
;	Pass: nothing
;	Returns: HWRR_BEGIN_INTERACTION returns AX=0 to show that
;		 everything is fine, else there is an error.
;		 If HWRR_BEGIN_INTERACTION returns an error, do not call
;		 HWRR_END_INTERACTION.
;

HWRR_RESET				enum HWRRoutine
;
;	Resets the library in preparation of sending a new set of ink data
;	to it. This nukes all old points, and re-enables the entire character
;	set.
;
;	Pass: nothing
;	Returns: nothing
;	Destroyed: nothing
;

HWRR_DISABLE_CHAR_RANGE			enum HWRRoutine
;
;	Disables the passed range of characters - this means that strokes
;	will not be recognized as these characters.
;
;	Pass: (on stack)
;
;		word - first char in range to disable
;		word - last char in range to disable
;
;	Return: nothing
;

HWRR_ENABLE_CHAR_RANGE			enum HWRRoutine
;
;	Enables the passed range of characters - this means that strokes
;	can be recoginized by these characters.
;
;	Pass: (on stack)
;
;		word - first char in range to disable
;		word - last char in range to disable
;
;	Return: nothing
;

HWRR_SET_CHAR_FILTER_CALLBACK		enum HWRRoutine
;
;	Calls the passed callback routine with characters.
;
;	Pass: (push in this order)
;		fptr to callback routine
;		fptr to callback data
;
;	Return: nothing
;
;	Callback is passed (on stack):
;
;		word 	number of choices for character
;		word 	offset of first point in char
;		word	offset of last point in char
;		fptr 	array of 16-bit characters
;		fptr 	callback data
;
;	Callback should return:
;
;		AX = character chosen (it does not necessarily have to be
;		     one of the characters in the passed array)
;
;	Callback can destroy: ax, bx, cx, dx
;

HWRR_SET_STRING_FILTER_CALLBACK		enum HWRRoutine
;
;	This allows the application to specify his own filter routine on
;	an entire word basis (as opposed to a char by char basis)
;
;	NOTE: If the app specifies a "WHOLE_WORD" filter callback, it should
;	      not also specify a "CHAR_FILTER" callback, as the "CHAR_FILTER"
;	      callback will not be called.
;
;	Pass: (on stack - push in this order)
;		fptr to callback routine
;		fptr to callback data
;
;	Returns: nothing
;
;	Callback routine is passed (on stack - pascal model):
;
;		word	number of characters recognized
;		fptr	array of CharChoiceInformation structures
;		fptr	callback data
;
;	Callback routine returns:
;
;		AX - handle of block containing null-terminated
;		     ink data
;
;	Callback routine can destroy:
;
;		AX, BX, CX, DX
;

CharChoiceInformation	struct
	CCI_numChoices	word
	; The # choices for this character (can be 0)
	
	CCI_firstPoint	word
	; Offset to the first point in the ink data corresponding to this char

	CCI_lastPoint	word
	; Offset to the last point in the ink data in this char

	CCI_data	fptr.word
	; Ptr to characters

CharChoiceInformation	ends

InkXCoord	record
	IXC_TERMINATE_STROKE:1
	IXC_X_COORD:15
InkXCoord	end

HWRR_ADD_POINT				enum HWRRoutine
;
;	This allows the application to add one point at a time to the list of
;	points being collected and recognized
;
;	Pass: (on stack)
;		InkXCoord		;X coordinate
;		word			;Y coordinate
;		dword			;time stamp	
;	      		       (normally passed as 0, but can be passed
;		   	       as an actual value for certain real-time
;			       applications, such as signature verification)
;	Returns: nothing
;	

HWRR_ADD_POINTS			enum HWRRoutine
;
;	This adds a bunch of points at once.
;
;	Pass: (on stack)
;	      word	num points	
;	      fptr 	array of InkPoint structures
;	Return: nothing
;
InkPoint	struct
	IP_x	InkXCoord
	IP_y	word
InkPoint	ends

GestureType		etype	word
	GT_NO_GESTURE				enum GestureType
	GT_DELETE_CHARS				enum GestureType
	GT_SELECT_CHARS				enum GestureType
	GT_V_CROSSOUT				enum GestureType
	GT_H_CROSSOUT				enum GestureType
	GT_BACKSPACE				enum GestureType
;
; The following gestures types were added for release 2.1 and later
;
	GT_CHAR					enum GestureType
	GT_STRING_MACRO				enum GestureType
	GT_IGNORE_GESTURE			enum GestureType
	GT_COPY					enum GestureType
	GT_PASTE				enum GestureType
	GT_CUT					enum GestureType
	GT_MODE_CHAR				enum GestureType
	GT_REPLACE_LAST_CHAR			enum GestureType

HWRStringMacro	struct
	HWRSM_deleteCount	word
	HWRSM_string		label	word
HWRStringMacro	ends


HWRR_DO_GESTURE_RECOGNITION	enum HWRRoutine
;
;	Checks to see if the points are a single gesture.
;
;	Pass: nothing
;	Return: AX <- return
;

HWRR_DO_SINGLE_CHAR_RECOGNITION	enum HWRRoutine
;
;	This returns a single char that was recognized from the ink input
;
;	Pass: nothing
;	Return: AX <- character
;

HWRR_DO_MULTIPLE_CHAR_RECOGNITION	enum HWRRoutine
;
;	This returns a null-terminated string that was recognized from the
;	input.
;
;	Pass: nothing
;	Return: AX <- handle of block containing null-terminated ink data
;

HWRR_GET_HWR_MANUF_ID		enum HWRRoutine
;
;	Returns the manufacturer of the HWR. This may be useful if you want
;	to call certain special features that only exist in certain drivers.
;	(For example, if one was writing a signature verification application
;	that required a specific HWR driver).
;
;	Pass: nothing
;	Returns: AX - ManufacturerID
;

HWRR_SET_CONTEXT		enum HWRRoutine
;
;	Puts the hwr engine in line/grid/boxed mode.
;
;	Pass (on stack)
;      	      fptr to HWRContext union
;

HWRMode			etype	word
	HM_NONE					enum	HWRMode
	; The user is writing in a multi-line object - no guidelines

	HM_LINE					enum 	HWRMode
	; The user has a reference line to write on

	HM_BOX					enum 	HWRMode
	; The user has a box to write into

	HM_GRID					enum 	HWRMode
	; The user has a grid to write chars into (one char per box)

HWRNoneData		struct
	HWRND_mode	HWRMode	
HWRNoneData		ends

HWRLineData		struct
	HWRLD_mode	HWRMode
	HWRLD_line	sword	
HWRLineData		ends

HWRBoxData		struct
	HWRBD_mode	HWRMode
	HWRBD_top	sword
	HWRBD_bottom	sword	
HWRBoxData		ends

HWRGridData		struct
	HWRGD_mode	HWRMode
	HWRGD_bounds	Rectangle
	; Bounds of grid area (in same coords as ink data)

	HWRGD_xOffset	sword
	HWRGD_yOffset	sword
	; X/Y offsets between grid lines
HWRGridData		ends

HWRContext		union
      	HWRC_none	HWRNoneData
	HWRC_lined	HWRLineData
	HWRC_boxed	HWRBoxData
	HWRC_grid	HWRGridData
HWRContext		end

HWRR_SET_LANGUAGE		enum HWRRoutine
;
;	Sets the default recognition language of the HWR
;	Pass: 		(push in this order)
;			word - StandardLanguage
;	Returns:	nothing
;

;
; The following routines were added for release 2.1 and later.
;

HWRR_GET_GESTURE_BOUNDS		enum HWRRoutine
;
;	Returns a handle to a Rectangle structure which contains the
;	bounds of the the last gesture recognized.  Must be called
;	after a HWRR_DO_GESTURE_RECOGNITON call.
;	
;	Pass: nothing
;	Returns: AX - handle to Rectangle struct
;


HWRR_RESET_MACRO		enum HWRRoutine
;
;	Tells the HWR library that the current macro in progress must
;	be cleared. Returns a handle to a HWRStringMacro that will
;	clean up anything displayed for the current macro
;
;	Pass:		nothing
;	Returns:	AX - Handle to HWRStringMacro

HWRR_GET_CHAR_BOUNDS		enum HWRRoutine
;
;	Is called from the custom char callback to get the absolute
;	bounds of the character.
;	Pass:		nothing
;	Returns		AX - handle to Rectangle

HWRR_LAST_RESERVED_ENTRY equ HWRR_GET_CHAR_BOUNDS + HWR_NUMBER_RESERVED_ENTRIES
;
;  A HWR Library should use skip until HWRR_LAST_RESERVED_ENTRY in its
;  .gp file between the exported routines defined for geos, and any
;  exported routines specific to that Library.
;

EndLibrary	hwr

