Cell Library: 2.3 Using the Cell Library: Actions on a Range of Cells

GEOS SDK TechDocs

2.2 Basic Cell Array Routines

RangeExists(), RangeInsert(), RangeEnum(), RangeSort(), RangeInsertParams

The cell library provides a number of routines which act on a range of cells. All of these routines take the address of a CellFunctionParameters structure as an argument. Many of these routines also take the address of a special parameter structure; for example, RangeInsert() takes the address of a RangeInsertParams structure. In these cases, the structure should be in locked or fixed memory. If the routine might allocate or resize cells, the structure must not be in an ungrouped DB item.

You may want to find out if there are any cells in a specified section of the cell file. To do this, call the routine RangeExists() . This routine takes five arguments:

• The address of the locked CellFunctionParameters structure
• The index of the first row in the section to be checked
• The index of the first column in the section to be checked
• The index of the last row in the section to be checked
• The index of the last column in the section to be checked

If any cells exist in that section, the routine returns true (i.e. non-zero). Otherwise, it returns false .

You may wish to insert several cells at once. For this reason, the cell library provides the routine RangeInsert() . This routine does not actually allocate cells; instead, it shifts existing cells to make room for new ones. You specify a section of the cell file to shift. Any cells in that section will be shifted over; the caller specifies whether they should be shifted horizontally or vertically. The routine takes two arguments, namely the address of the CellFunctionParameters and the address of a RangeInsertParams structure. It does not return anything. The definition of the RangeInsertParams structure is shown in The RangeInsertParams and Point structures. The calling geode should allocate it and initialize it before calling RangeInsert() .

Code Display 19-3 The RangeInsertParams and Point structures

typedef	struct {		/* defined in cell.h */
	Rectangle			RIP_bounds;		/* Range of cells to shift */
	Point			RIP_delta;		/* Specify which way to shift */
	CellFunctionParameters			*RIP_cfp;
} RangeInsertParams;

typedef	struct {		/* defined in graphics.h */
	sword		P_x;	/* Distance to shift horizontally */
	sword		P_y;	/* Distance to shift vertically */
} Point;

The RangeInsertParams structure has three fields. The calling geode should initialize the fields to determine the behavior of RangeInsert() :

RIP _bounds

This field specifies which cells should be shifted. The cells currently in this range will be shifted across or down, depending on the value of RIP_delta ; this shifts more cells, and so on, to the edge of the visible portion of the cell file. The field is a Rectangle structure. To insert an entire row (which is much faster than inserting a partial row), set RIP_bounds.R_left = 0 and RIP_bounds.R_right = LARGEST_COLUMN .

RIP _delta

This field specifies how far the cells should be shifted and in which direction. The field is a Point structure (see The RangeInsertParams and Point structures). If the range of cells is to be shifted horizontally, RIP_delta.P_x should specify how far the cells should be shifted to the right, and RIP_delta.P_y should be zero. If the cells are to be shifted vertically, RIP_delta.P_y should specify how far the cells should be shifted down, and RIP_delta.P_x should be zero.

RIP _cfp

This is the address of the CellFunctionParameters structure. You don't have to initialize this; the routine will do so automatically.

You may need to perform a certain function on every one of a range of cells. For this purpose, the cell library provides the routine RangeEnum() . This routine lets you specify a range of cells and a callback routine; the routine will be called on each cell in that range.

You can sort a range of cells, by row or by column, based on any criteria you choose. Use the routine RangeSort() . This routine uses a QuickSort algorithm to sort the cells specified. You supply a pointer to a callback routine which is used to compare cells.

GEOS SDK TechDocs

2.2 Basic Cell Array Routines