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

	Copyright (c) GeoWorks 1991 -- All Rights Reserved

PROJECT:	PC GEOS
MODULE:		
FILE:		cell.def

AUTHOR:		John Wedgwood, December  5th, 1990

	
REVISION HISTORY:
	Name	Date		Description
	----	----		-----------
	jcw	12/ 5/90	Initial revision
	jcw	 3/29/91	Optimizations required a complete rewrite

DESCRIPTION:
	Definitions for the cell library.
		
	$Id: cell.def,v 1.1 97/04/04 14:22:55 newdeal Exp $

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

SetDef	__CELL

StartLibrary	cell

include graphics.def

;
; We refer to dbase items in a few places, so we need a structure for them.
;
DBaseItem	struct
    DBI_group	word		; The group in which the data resides
    DBI_item	word		; The item within that group
DBaseItem	ends

;
; The rows allowed are 0...LARGEST_ROW
; I figure that 16,384 will be the largest number of rows visible to the user
; The extra 128 rows are for applications to use for their own data.
;
LARGEST_VISIBLE_ROW	= 16383
LARGEST_ROW		= LARGEST_VISIBLE_ROW + 128

;
; The columns allowed are 0...LARGEST_COLUMN
;
LARGEST_COLUMN		= 255

;
; A row is an array of columns. The header doesn't contain much...
;
ColumnArrayHeader	struct
    CAH_numEntries	word	; Number of entries in the array
    CAH_rowFlags	word	;flags that exist for each row
ColumnArrayHeader	ends

;
; A row is a sparse array of references to cells.
;
ColumnArrayElement	struct
    CAE_column	byte		; The column number in which the cell resides.
    CAE_data	DBaseItem	; The item containing the cell data.
ColumnArrayElement	ends

;
; The maximum size of a single row
;
MAX_SINGLE_ROW_SIZE	= (LARGEST_COLUMN+1) * size ColumnArrayElement

;
; The number of rows we can store in a single row block. This must be some
; power of 2 in order to allow quick computation.
;
; Based on the above value for MAX_SINGLE_ROW_SIZE, we get
;	256*5 => 1280 bytes per row
;	65536 / 1280 => 51 rows per row/block
;
; The closest power of 2 is 32.
;
N_ROWS_PER_ROW_BLOCK	= 32

;
; These next two constants define how many shifts are needed to convert
; a row to a row-block and the mask to use when converting a row to an
; offset into a row block.
;
; You might want to look at cellMacros.def for more information.
;
ROW_TO_ROW_BLOCK_SHIFT_COUNT	= 5
ROW_TO_ROW_CHUNK_MASK		= 0x1f

;
; The number of entries in the array of row blocks.
; Just because it's useful to know, this number is 517.
;
N_ROW_BLOCKS	=	((LARGEST_ROW + 1) / N_ROWS_PER_ROW_BLOCK) + 1

;
; An empty row block is an lmem block with lots of handles in it.
; The truth is it doesn't really matter what it has in it because LMemInitHeap
; will truncate/expand the block anyway.
;
EmptyRowBlock	struct
    ERB_header	LMemBlockHeader <>
    ERB_handles	word N_ROWS_PER_ROW_BLOCK dup (0)
EmptyRowBlock	ends

;
; Flags associated with the parameter block
;
CellFunctionParameterFlags	record
    CFPF_DIRTY:1		; Set: The parameter block is dirty
    :4				; Unused
	;
	; This next part is only set temporarily in RangeEnum to make sure
	; that a callback doesn't attempt to free anything.
	;
    CFPF_NO_FREE_COUNT:3	; Counts the number of calls to a non-special
				;   RangeEnum()
CellFunctionParameterFlags	end

RowBlockList	struct
    RBL_blocks	nptr N_ROW_BLOCKS dup (0)
RowBlockList	ends

;
; This structure is passed to every one of the cell routines
;
CellFunctionParameters	struct
	;
	; Flags of mystery... These flags are set by the cell library and
	; shouldn't be modified by the application (except for initialization).
	;
    CFP_flags		CellFunctionParameterFlags
	;
	; The file handle
	;
    CFP_file		word
	;
	; Followed by an array of handles to the grouped row blocks.
	;
    CFP_rowBlocks	RowBlockList
CellFunctionParameters	ends

;-----------------------------------------------------------------------------
;
; Routines exported for general consumption.
;
global	CellReplace:far
global	CellGetDBItem:far

global	CellLock:far

global	CellGetExtent:far

global	RangeExists:far
global	RangeInsert:far
global	RangeSort:far
global	RangeEnum:far

global	RowGetFlags:far
global	RowSetFlags:far

CellUnlock equ DBUnlock
CellDirty equ DBDirty
 
;
; C versions
;
global	CELLREPLACE:far
global	CELLLOCK:far
global 	CELLLOCKGETREF:far
global	ROWGETFLAGS:far
global	ROWSETFLAGS:far
global	RANGEEXISTS:far
global	RANGEENUM:far

;-----------------------------------------------------------------------------

;
; Flags to RangeEnum
;
RangeEnumFlags	record
    REF_ALL_CELLS:1		; Set: callback for all cells.
    REF_NO_LOCK:1		; Set: callback will lock/unlock cells.
    REF_ROW_FLAGS:1		; Set: get row flags when calling back
    REF_MATCH_ROW_FLAGS:1	; Set: callback for cells w/matching row flags
	;
	; These next ones are returned from the callback routine.
	;
    REF_CELL_ALLOCATED:1	; Set: The callback routine allocated the cell
				;      for which the callback occurred.
    REF_CELL_FREED:1		; Set: The callback routine freed the cell for
				;      which the callback occurred.

    REF_OTHER_ALLOC_OR_FREE:1	; Set: The callback routine may have allocated
				;      or freed a cell other than the one for
				;      which the callback occurred.
    REF_ROW_FLAGS_MODIFIED:1	; Set: The callback routine changed 
				;      the row flags
RangeEnumFlags	end

;
; Parameters to RangeEnum
;
RangeEnumParams	struct
    REP_callback		fptr.far	;routine to call
    REP_bounds			Rectangle	;cells to enumerate
    ;
    ; Stuff below this point is filled in by RangeEnum() and can be
    ; used by the callback.
    ;
    REP_rowFlags		word		;current row flags
    ;
    ; Stuff below this point is setup by RangeEnum(). Applications don't
    ; need to worry about it.
    ;
    REP_cfp			fptr.CellFunctionParameters
    ;
    ; Stuff below this point is only used with REF_MATCH_ROW_FLAGS
    ;
    REP_matchFlags		word		;flags to match
    REP_flagRow			word		;row we locked for flags
RangeEnumParams	ends

;
; C version of RangeEnumParams
;
CRangeEnumParams	struct
    CREP_params		RangeEnumParams
    CREP_locals		fptr		;ptr to local variables or other
    ;
    ; The rest is used internally
    ;
    CREP_callback	fptr.far
CRangeEnumParams	ends

;
; C version of what callback function is called with
;
CRangeEnumCallbackParams	struct
    CRECP_rangeParams	fptr.CRangeEnumParams
    CRECP_row		word		;current row
    CRECP_column	word		;current column
    CRECP_cellData	fptr		;NULL if no data or REF_NO_LOCK passed
    CRECP_rangeFlags	RangeEnumFlags	;Range flags.
CRangeEnumCallbackParams	ends


;
; Parameters to RangeInsert
;
RangeInsertParams	struct
	;
	; Applications should initialize these.
	;
    RIP_bounds		Rectangle		; Range of cells to move
    RIP_delta		Point			; Amount to move by
	;
	; The rest is used in RangeInsert and should be ignored.
	;
    RIP_cfp		dword			; Pointer to CFP block
RangeInsertParams	ends

;
; Parameters to RangeSort
;
RangeSortFlags	record
    RSF_SORT_ROWS:1			; Set: Sort rows
    RSF_SORT_ASCENDING:1		; Set: Sort in ascending order
    RSF_IGNORE_CASE:1			; Set: Ignore case in string compares
    :4
    RSF_IGNORE_SPACES:1			; Set: Ignore spaces & punctuation
					; NOTE: this is not supported directly
					; by the Cell library, but is placed
					; here for the convenience of apps.
RangeSortFlags	end

;
; These flags are passed to the callback routine that compares two cells.
; The flags are created by shifting the carry into a register after calling
; CellLock(). As a result the bits are in the bottom of the byte
;
RangeSortCellExistsFlags	record
    :6					; Unused bits
    RSCEF_SECOND_CELL_EXISTS:1		; Set: Second cell exists
    RSCEF_FIRST_CELL_EXISTS:1		; Set: First cell exists
RangeSortCellExistsFlags	end

RangeSortParams	struct
    RSP_range		Rectangle		; Range to sort
    RSP_active		Point			; The cell in the row/column
						;    to sort on.
    RSP_callback	dword			; Comparison routine
	;
	; Callback is defined as:
	;	PASS:	ds:si	= Pointer to first cells data
	;		es:di	= Pointer to second cells data
	;		ax	= RangeSortCellExistsFlags
	;		ss:bx	= Parameters passed to RangeSort
	;	RETURN:	Flags set for comparison of the two cells
	;	DESTROYED: cx, dx, di, si, bp
	;
    RSP_flags		RangeSortFlags		; The flags
	align	word
	;
	; The rest is used in RangeSort and should be ignored.
	;
    RSP_cfp		dword			; CellFunctionParameters
    RSP_sourceChunk	word			; Source/dest row chunks
    RSP_destChunk	word			;     for swapping
    RSP_base		word			; Base row/column for sort block
    RSP_lockedEntry	dword			; The entry that is currently
						;    locked. If the segment
						;    is -1, nothing is locked
    RSP_cachedFlags	byte			; Flags (carry set if cell
						;    exists)
	align	word
RangeSortParams	ends

RangeSortError	etype	word, 0, 1
RSE_NO_ERROR		enum	RangeSortError
;
; No error, the sort was successful.
;

RSE_UNABLE_TO_ALLOC	enum	RangeSortError
;
; The sorting code was unable to allocate the temporary block it needs to
; sort the data.
;

EndLibrary	cell
