Cellblock

A "Cellblock" is an array of active cells. More...

Files
file	cellblock.h
	Declarations for the CellBlock object.

Data Structures
struct	CellBlock

Functions
CellBlock *	gnc_cellblock_new (int rows, int cols, const char *cursor_name)
	Create a new CellBlock on the heap.
void	gnc_cellblock_destroy (CellBlock *cellblock)
	Delete a CellBlock and its Cells.
void	gnc_cellblock_set_cell (CellBlock *cellblock, int row, int col, BasicCell *cell)
	Add a cell to the CellBlock at the specified coordinates.
BasicCell *	gnc_cellblock_get_cell (CellBlock *cellblock, int row, int col)
	Retrieve the Cell at the specified coordinates.
BasicCell *	gnc_cellblock_get_cell_by_name (CellBlock *cellblock, const char *cell_name, int *row, int *col)
	Searches by name for a particular cell in a CellBlock.
int	gnc_cellblock_changed (CellBlock *cursor, gboolean include_conditional)
	Return number of changed cells.
void	gnc_cellblock_clear_changes (CellBlock *cursor)
	Sets all cells in the cellblock to not changed.

Detailed Description

A "Cellblock" is an array of active cells.

The cells are laid out in rows and columns. The cellblock serves as a convenient container for organizing active cells in an array. Through the mechanism of Cursors (defined below), it allows a group of cells to be treated as a single transactional entity. That is, the cursor/cellblock allows all edits to a groups of cells to be simultaneously committed or rejected by underlying engines. This makes it appropriate for use as a GUI for transaction-processing applications with two-phase commit requirements.

Function Documentation

gnc_cellblock_changed()

int gnc_cellblock_changed	(	CellBlock *	cursor,
		gboolean	include_conditional
	)

Return number of changed cells.

Parameters

cursor	The cellblock to query
include_conditional	If TRUE counts conditionally-changed cells

Returns

The number of changed cells found.

Definition at line 157 of file cellblock.c.

{
    int changed = 0;
    int r, c;
 
    if (!cursor)
        return FALSE;
 
    for (r = 0; r < cursor->num_rows; r++)
        for (c = 0; c < cursor->num_cols; c++)
        {
            BasicCell *cell;
 
            cell = gnc_cellblock_get_cell (cursor, r, c);
            if (cell == NULL)
                continue;
 
            if (gnc_basic_cell_get_changed (cell))
            {
                changed++;
                continue;
            }
 
            if (include_conditional &&
                    gnc_basic_cell_get_conditionally_changed (cell))
                changed++;
        }
 
    return changed;
}

gnc_cellblock_clear_changes()

void gnc_cellblock_clear_changes

(

CellBlock *

cursor

)

Sets all cells in the cellblock to not changed.

Parameters

cursor

The cellblock.

Definition at line 189 of file cellblock.c.

{
    int r, c;
 
    if (!cursor)
        return;
 
    for (r = 0; r < cursor->num_rows; r++)
        for (c = 0; c < cursor->num_cols; c++)
        {
            BasicCell *cell;
 
            cell = gnc_cellblock_get_cell (cursor, r, c);
            if (cell == NULL)
                continue;
 
            gnc_basic_cell_set_changed (cell, FALSE);
            gnc_basic_cell_set_conditionally_changed (cell, FALSE);
        }
}

gnc_cellblock_destroy()

void gnc_cellblock_destroy

(

CellBlock *

cellblock

)

Delete a CellBlock and its Cells.

Parameters

cellblock

The CellBlock to destroy.

Definition at line 78 of file cellblock.c.

{
    if (!cellblock) return;
 
    g_ptr_array_free (cellblock->cells, TRUE);
    cellblock->cells = NULL;
 
    g_free (cellblock->cursor_name);
    cellblock->cursor_name = NULL;
 
    g_free (cellblock);
}

gnc_cellblock_get_cell()

BasicCell * gnc_cellblock_get_cell	(	CellBlock *	cellblock,
		int	row,
		int	col
	)

Retrieve the Cell at the specified coordinates.

Parameters

cellblock	The CellBlock
row	The row of the requested Cell
col	The column of the requested Cell

Returns

A pointer to the requested Cell.

Definition at line 109 of file cellblock.c.

{
    if (cellblock == NULL)
        return NULL;
 
    if (row < 0 || row >= cellblock->num_rows)
        return NULL;
 
    if (col < 0 || col >= cellblock->num_cols)
        return NULL;
 
    return cellblock->cells->pdata[(row * cellblock->num_cols) + col];
}

gnc_cellblock_get_cell_by_name()

BasicCell * gnc_cellblock_get_cell_by_name	(	CellBlock *	cellblock,
		const char *	cell_name,
		int *	row,
		int *	col
	)

Searches by name for a particular cell in a CellBlock.

Parameters row and/or col may be NULL.

Parameters

cellblock	a CellBlock to search
cell_name	the name of the cell to find
row	pointer for returning the row in which the cell was found, or NULL
col	pointer for returning the column in which the cell was found, or NULL

Returns

the matching cell, or NULL

Definition at line 124 of file cellblock.c.

{
    int r, c, num_rows, num_cols;
 
    if (cellblock == NULL)
        return NULL;
 
    if (cell_name == NULL)
        return NULL;
 
    num_rows = cellblock->num_rows;
    num_cols = cellblock->num_cols;
    for (r = 0; r < num_rows; r++)
        for (c = 0; c < num_cols; c++)
        {
            BasicCell *cell = cellblock->cells->pdata[(r * num_cols) + c];
            if (!cell) continue;
            if (gnc_cell_name_equal(cell->cell_name, cell_name))
            {
                if (row)
                    *row = r;
                if (col)
                    *col = c;
                return cell;
            }
        }
 
    return NULL;
}

gnc_cellblock_new()

CellBlock * gnc_cellblock_new	(	int	rows,
		int	cols,
		const char *	cursor_name
	)

Create a new CellBlock on the heap.

Parameters

rows	Number of rows.
cols	Number of columns.
cursor_name	A string name for the CellBlock. It will be copied with a new string on the heap.

Returns

a newly-allocated CellBlock which should be deleted with gnc_cellblock_destroy.

Definition at line 44 of file cellblock.c.

{
    CellBlock *cellblock;
 
    g_return_val_if_fail (rows > 0, NULL);
    g_return_val_if_fail (cols > 0, NULL);
    g_return_val_if_fail (cursor_name != NULL, NULL);
 
    cellblock = g_new0 (CellBlock, 1);
 
    gnc_cellblock_init (cellblock, rows, cols);
 
    cellblock->cursor_name = g_strdup (cursor_name);
 
    return cellblock;
}

gnc_cellblock_set_cell()

void gnc_cellblock_set_cell	(	CellBlock *	cellblock,
		int	row,
		int	col,
		BasicCell *	cell
	)

Add a cell to the CellBlock at the specified coordinates.

The CellBlock takes ownership of the Cell. If there's already a Cell at the location it will be leaked, so callers should first call gnc_cellblock_get_cell() and delete the result if it's not NULL.

Parameters

cellblock	The CellBlock
row	The row at which to add the cell
col	The column at which to add the cell
cell	The cell to place at the coordinates.

Definition at line 92 of file cellblock.c.

{
    if (cellblock == NULL)
        return;
 
    if (row < 0 || row >= cellblock->num_rows)
        return;
 
    if (col < 0 || col >= cellblock->num_cols)
        return;
 
    cellblock->cells->pdata[(row * cellblock->num_cols) + col] = cell;
}