GnuCash  5.6-150-g038405b370+
Files | Data Structures | Functions

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

Files

file  cellblock.h
 Declarations for the CellBlock object.
 

Data Structures

struct  CellBlock
 

Functions

CellBlockgnc_cellblock_new (int rows, int cols, const char *cursor_name)
 Create a new CellBlock on the heap. More...
 
void gnc_cellblock_destroy (CellBlock *cellblock)
 Delete a CellBlock and its Cells. More...
 
void gnc_cellblock_set_cell (CellBlock *cellblock, int row, int col, BasicCell *cell)
 Add a cell to the CellBlock at the specified coordinates. More...
 
BasicCell * gnc_cellblock_get_cell (CellBlock *cellblock, int row, int col)
 Retrieve the Cell at the specified coordinates. More...
 
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. More...
 
int gnc_cellblock_changed (CellBlock *cursor, gboolean include_conditional)
 Return number of changed cells. More...
 
void gnc_cellblock_clear_changes (CellBlock *cursor)
 Sets all cells in the cellblock to not changed. More...
 

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
cursorThe cellblock to query
include_conditionalIf TRUE counts conditionally-changed cells
Returns
The number of changed cells found.

Definition at line 157 of file cellblock.c.

158 {
159  int changed = 0;
160  int r, c;
161 
162  if (!cursor)
163  return FALSE;
164 
165  for (r = 0; r < cursor->num_rows; r++)
166  for (c = 0; c < cursor->num_cols; c++)
167  {
168  BasicCell *cell;
169 
170  cell = gnc_cellblock_get_cell (cursor, r, c);
171  if (cell == NULL)
172  continue;
173 
174  if (gnc_basic_cell_get_changed (cell))
175  {
176  changed++;
177  continue;
178  }
179 
180  if (include_conditional &&
181  gnc_basic_cell_get_conditionally_changed (cell))
182  changed++;
183  }
184 
185  return changed;
186 }
BasicCell * gnc_cellblock_get_cell(CellBlock *cellblock, int row, int col)
Retrieve the Cell at the specified coordinates.
Definition: cellblock.c:109

◆ gnc_cellblock_clear_changes()

void gnc_cellblock_clear_changes ( CellBlock cursor)

Sets all cells in the cellblock to not changed.

Parameters
cursorThe cellblock.

Definition at line 189 of file cellblock.c.

190 {
191  int r, c;
192 
193  if (!cursor)
194  return;
195 
196  for (r = 0; r < cursor->num_rows; r++)
197  for (c = 0; c < cursor->num_cols; c++)
198  {
199  BasicCell *cell;
200 
201  cell = gnc_cellblock_get_cell (cursor, r, c);
202  if (cell == NULL)
203  continue;
204 
205  gnc_basic_cell_set_changed (cell, FALSE);
206  gnc_basic_cell_set_conditionally_changed (cell, FALSE);
207  }
208 }
BasicCell * gnc_cellblock_get_cell(CellBlock *cellblock, int row, int col)
Retrieve the Cell at the specified coordinates.
Definition: cellblock.c:109

◆ gnc_cellblock_destroy()

void gnc_cellblock_destroy ( CellBlock cellblock)

Delete a CellBlock and its Cells.

Parameters
cellblockThe CellBlock to destroy.

Definition at line 78 of file cellblock.c.

79 {
80  if (!cellblock) return;
81 
82  g_ptr_array_free (cellblock->cells, TRUE);
83  cellblock->cells = NULL;
84 
85  g_free (cellblock->cursor_name);
86  cellblock->cursor_name = NULL;
87 
88  g_free (cellblock);
89 }

◆ gnc_cellblock_get_cell()

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

Retrieve the Cell at the specified coordinates.

Parameters
cellblockThe CellBlock
rowThe row of the requested Cell
colThe column of the requested Cell
Returns
A pointer to the requested Cell.

Definition at line 109 of file cellblock.c.

110 {
111  if (cellblock == NULL)
112  return NULL;
113 
114  if (row < 0 || row >= cellblock->num_rows)
115  return NULL;
116 
117  if (col < 0 || col >= cellblock->num_cols)
118  return NULL;
119 
120  return cellblock->cells->pdata[(row * cellblock->num_cols) + col];
121 }

◆ 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
cellblocka CellBlock to search
cell_namethe name of the cell to find
rowpointer for returning the row in which the cell was found, or NULL
colpointer 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.

127 {
128  int r, c, num_rows, num_cols;
129 
130  if (cellblock == NULL)
131  return NULL;
132 
133  if (cell_name == NULL)
134  return NULL;
135 
136  num_rows = cellblock->num_rows;
137  num_cols = cellblock->num_cols;
138  for (r = 0; r < num_rows; r++)
139  for (c = 0; c < num_cols; c++)
140  {
141  BasicCell *cell = cellblock->cells->pdata[(r * num_cols) + c];
142  if (!cell) continue;
143  if (gnc_cell_name_equal(cell->cell_name, cell_name))
144  {
145  if (row)
146  *row = r;
147  if (col)
148  *col = c;
149  return cell;
150  }
151  }
152 
153  return NULL;
154 }

◆ gnc_cellblock_new()

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

Create a new CellBlock on the heap.

Parameters
rowsNumber of rows.
colsNumber of columns.
cursor_nameA 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.

45 {
46  CellBlock *cellblock;
47 
48  g_return_val_if_fail (rows > 0, NULL);
49  g_return_val_if_fail (cols > 0, NULL);
50  g_return_val_if_fail (cursor_name != NULL, NULL);
51 
52  cellblock = g_new0 (CellBlock, 1);
53 
54  gnc_cellblock_init (cellblock, rows, cols);
55 
56  cellblock->cursor_name = g_strdup (cursor_name);
57 
58  return cellblock;
59 }

◆ 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
cellblockThe CellBlock
rowThe row at which to add the cell
colThe column at which to add the cell
cellThe cell to place at the coordinates.

Definition at line 92 of file cellblock.c.

95 {
96  if (cellblock == NULL)
97  return;
98 
99  if (row < 0 || row >= cellblock->num_rows)
100  return;
101 
102  if (col < 0 || col >= cellblock->num_cols)
103  return;
104 
105  cellblock->cells->pdata[(row * cellblock->num_cols) + col] = cell;
106 }