Register Core

An infrastructure for building a modular matrix of cells like a spreadsheet or checkbook register. More...

Files
file	cellblock.h
	Declarations for the CellBlock object.
file	register-common.h
	Common declarations for the register core.
file	table-allgui.h
	Declarations for the Table object.

Data Structures
struct	CellBlock
struct	_VirtualCellLocation
struct	_VirtualLocation
struct	VirtualCell
struct	TableGUIHandlers
struct	table

Macros
#define	BASIC_CELL_TYPE_NAME   "basic-cell"
#define	COMBO_CELL_TYPE_NAME   "combo-cell"
#define	DATE_CELL_TYPE_NAME   "date-cell"
#define	NUM_CELL_TYPE_NAME   "num-cell"
#define	PRICE_CELL_TYPE_NAME   "price-cell"
#define	RECN_CELL_TYPE_NAME   "recn-cell"
#define	QUICKFILL_CELL_TYPE_NAME   "quickfill-cell"
#define	FORMULA_CELL_TYPE_NAME   "formula-cell"
#define	CHECKBOX_CELL_TYPE_NAME   "checkbox-cell"

Typedefs
typedef struct _VirtualCellLocation	VirtualCellLocation
typedef struct _VirtualLocation	VirtualLocation
typedef struct table	Table
typedef void(*	TableCursorRefreshCB )(Table *table, VirtualCellLocation vcell_loc, gboolean do_scroll)
typedef void(*	TableRedrawHelpCB )(Table *table)
typedef void(*	TableDestroyCB )(Table *table)

Enumerations
enum	RegisterColor {   COLOR_UNKNOWN_BG, COLOR_HEADER_BG, COLOR_PRIMARY_BG, COLOR_PRIMARY_BG_ACTIVE,   COLOR_SECONDARY_BG, COLOR_SECONDARY_BG_ACTIVE, COLOR_SPLIT_BG, COLOR_SPLIT_BG_ACTIVE,   COLOR_UNKNOWN_FG, COLOR_HEADER_FG, COLOR_PRIMARY_FG, COLOR_PRIMARY_FG_ACTIVE,   COLOR_SECONDARY_FG, COLOR_SECONDARY_FG_ACTIVE, COLOR_SPLIT_FG, COLOR_SPLIT_FG_ACTIVE,   COLOR_NEGATIVE }

Functions
CellBlock *	gnc_cellblock_new (int rows, int cols, const char *cursor_name)
void	gnc_cellblock_destroy (CellBlock *cellblock)
void	gnc_cellblock_set_cell (CellBlock *cellblock, int row, int col, BasicCell *cell)
BasicCell *	gnc_cellblock_get_cell (CellBlock *cellblock, int row, int col)
BasicCell *	gnc_cellblock_get_cell_by_name (CellBlock *cellblock, const char *cell_name, int *row, int *col)
int	gnc_cellblock_changed (CellBlock *cursor, gboolean include_conditional)
void	gnc_cellblock_clear_changes (CellBlock *cursor)
void	gnc_register_init (void)
void	gnc_register_shutdown (void)
void	gnc_register_add_cell_type (const char *cell_type_name, CellCreateFunc cell_creator)
BasicCell *	gnc_register_make_cell (const char *cell_type_name)
gboolean	virt_cell_loc_equal (VirtualCellLocation vcl1, VirtualCellLocation vcl2)
gboolean	virt_loc_equal (VirtualLocation vl1, VirtualLocation vl2)
void	gnc_table_set_default_gui_handlers (TableGUIHandlers *gui_handlers)
Table *	gnc_table_new (TableLayout *layout, TableModel *model, TableControl *control)
void	gnc_virtual_location_init (VirtualLocation *vloc)
void	gnc_table_save_state (Table *table, gchar *state_section)
void	gnc_table_destroy (Table *table)
int	gnc_table_current_cursor_changed (Table *table, gboolean include_conditional)
void	gnc_table_clear_current_cursor_changes (Table *table)
void	gnc_table_save_current_cursor (Table *table, CursorBuffer *buffer)
void	gnc_table_restore_current_cursor (Table *table, CursorBuffer *buffer)
const char *	gnc_table_get_current_cell_name (Table *table)
gboolean	gnc_table_get_current_cell_location (Table *table, const char *cell_name, VirtualLocation *virt_loc)
gboolean	gnc_table_virtual_cell_out_of_bounds (Table *table, VirtualCellLocation vcell_loc)
gboolean	gnc_table_virtual_location_in_header (Table *table, VirtualLocation virt_loc)
VirtualCell *	gnc_table_get_virtual_cell (Table *table, VirtualCellLocation vcell_loc)
const char *	gnc_table_get_entry (Table *table, VirtualLocation virt_loc)
const char *	gnc_table_get_label (Table *table, VirtualLocation virt_loc)
CellIOFlags	gnc_table_get_io_flags (Table *table, VirtualLocation virt_loc)
guint32	gnc_table_get_fg_color (Table *table, VirtualLocation virt_loc)
guint32	gnc_table_get_gtkrc_fg_color (Table *table, VirtualLocation virt_loc)
guint32	gnc_table_get_bg_color (Table *table, VirtualLocation virt_loc, gboolean *hatching)
guint32	gnc_table_get_gtkrc_bg_color (Table *table, VirtualLocation virt_loc, gboolean *hatching)
void	gnc_table_get_borders (Table *table, VirtualLocation virt_loc, PhysicalCellBorders *borders)
CellAlignment	gnc_table_get_align (Table *table, VirtualLocation virt_loc)
gboolean	gnc_table_is_popup (Table *table, VirtualLocation virt_loc)
char *	gnc_table_get_help (Table *table)
BasicCell *	gnc_table_get_cell (Table *table, VirtualLocation virt_loc)
const char *	gnc_table_get_cell_name (Table *table, VirtualLocation virt_loc)
const gchar *	gnc_table_get_cell_type_name (Table *table, VirtualLocation virt_loc)
gboolean	gnc_table_get_cell_location (Table *table, const char *cell_name, VirtualCellLocation vcell_loc, VirtualLocation *virt_loc)
void	gnc_table_save_cells (Table *table, gpointer save_data)
VirtualCell *	gnc_table_get_header_cell (Table *table)
void	gnc_table_set_size (Table *table, int virt_rows, int virt_cols)
void	gnc_table_set_vcell (Table *table, CellBlock *cursor, gconstpointer vcell_data, gboolean visible, gboolean start_primary_color, VirtualCellLocation vcell_loc)
void	gnc_table_set_virt_cell_data (Table *table, VirtualCellLocation vcell_loc, gconstpointer vcell_data)
void	gnc_table_set_virt_cell_visible (Table *table, VirtualCellLocation vcell_loc, gboolean visible)
void	gnc_table_set_virt_cell_cursor (Table *table, VirtualCellLocation vcell_loc, CellBlock *cursor)
void	gnc_table_move_cursor (Table *table, VirtualLocation virt_loc)
void	gnc_table_move_cursor_gui (Table *table, VirtualLocation virt_loc)
gboolean	gnc_table_verify_cursor_position (Table *table, VirtualLocation virt_loc)
gpointer	gnc_table_get_vcell_data (Table *table, VirtualCellLocation vcell_loc)
gboolean	gnc_table_find_close_valid_cell (Table *table, VirtualLocation *virt_loc, gboolean exact_cell)
void	gnc_table_init_gui (GtkWidget *widget, gchar *state_section)
void	gnc_table_realize_gui (Table *table)
void	gnc_table_refresh_current_cursor_gui (Table *table, gboolean do_scroll)
void	gnc_table_refresh_gui (Table *table, gboolean do_scroll)
void	gnc_table_show_range (Table *table, VirtualCellLocation start_loc, VirtualCellLocation end_loc)
void	gnc_table_refresh_cursor_gui (Table *table, VirtualCellLocation vcell_loc, gboolean do_scroll)
void	gnc_table_wrap_verify_cursor_position (Table *table, VirtualLocation virt_loc)
gboolean	gnc_table_virtual_loc_valid (Table *table, VirtualLocation virt_loc, gboolean exact_pointer)
gboolean	gnc_table_move_tab (Table *table, VirtualLocation *virt_loc, gboolean move_right)
gboolean	gnc_table_move_vertical_position (Table *table, VirtualLocation *virt_loc, int phys_row_offset)
gboolean	gnc_table_enter_update (Table *table, VirtualLocation virt_loc, int *cursor_position, int *start_selection, int *end_selection)
void	gnc_table_leave_update (Table *table, VirtualLocation virt_loc)
gboolean	gnc_table_confirm_change (Table *table, VirtualLocation virt_loc)
const char *	gnc_table_modify_update (Table *table, VirtualLocation virt_loc, const char *change, int change_len, const char *newval, int newval_len, int *cursor_position, int *start_selection, int *end_selection, gboolean *cancelled)
gboolean	gnc_table_direct_update (Table *table, VirtualLocation virt_loc, char **newval_ptr, int *cursor_position, int *start_selection, int *end_selection, gpointer gui_data)
gboolean	gnc_table_traverse_update (Table *table, VirtualLocation virt_loc, gncTableTraversalDir dir, VirtualLocation *dest_loc)

Detailed Description

An infrastructure for building a modular matrix of cells like a spreadsheet or checkbook register.

Each cell may be specialized to perform a particular function, e.g. to read dates, numerical amounts, or text. The register core has been designed to be easy to extend, modular, easy to maintain, and memory efficient. It is intended to be used for building financial apps and spreadsheets.

The register core is built from several types of components: Cells, Cellblocks, Cursors, and the Table.

The register core should not have any 'knowledge' of the accounting model of GnuCash or of the workings of the main application. It should not be specific to a particular GUI (such as Gnome/GTK). It should be possible to use the register core in a stand-alone fashion.

For information on the GnuCash-specific register implementation that has been built atop this core, see Split Register.

Enumeration Type Documentation

enum RegisterColor

Color definitions used for table elements

Definition at line 160 of file table-allgui.h.

{
    /* Colors used for background drawing */
    COLOR_UNKNOWN_BG,
    COLOR_HEADER_BG,
    COLOR_PRIMARY_BG,
    COLOR_PRIMARY_BG_ACTIVE,
    COLOR_SECONDARY_BG,
    COLOR_SECONDARY_BG_ACTIVE,
    COLOR_SPLIT_BG,
    COLOR_SPLIT_BG_ACTIVE,

    /* Colors used for foreground drawing (text etc)
     * ATTENTION: the background and foreground lists should have
     *            the same types (the same amount of entries) !
     *            The code relies on this ! */
    COLOR_UNKNOWN_FG,
    COLOR_HEADER_FG,
    COLOR_PRIMARY_FG,
    COLOR_PRIMARY_FG_ACTIVE,
    COLOR_SECONDARY_FG,
    COLOR_SECONDARY_FG_ACTIVE,
    COLOR_SPLIT_FG,
    COLOR_SPLIT_FG_ACTIVE,

    /* Other colors */
    COLOR_NEGATIVE, /* Color to use for negative numbers */
} RegisterColor;

Function Documentation

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;
}

void gnc_table_init_gui	(	GtkWidget *	widget,
		gchar *	state_section
	)

UI-specific functions

Definition at line 157 of file table-gnome.c.

{
    GNCHeaderWidths widths;
    GnucashSheet *sheet;
    GnucashRegister *greg;
    Table *table;
    GList *node;
    gchar *key;
    guint value;
    GKeyFile *state_file = gnc_state_get_current();
 
    // Stuff for per-register settings load.
    g_return_if_fail (widget != NULL);
    g_return_if_fail (GNUCASH_IS_REGISTER (widget));
    
    PINFO("state_section=%s",state_section);
    
    ENTER("widget=%p, data=%p", widget, "");
    

    greg = GNUCASH_REGISTER (widget);
    sheet = GNUCASH_SHEET (greg->sheet);
    table = sheet->table;

    table->gui_handlers.redraw_help = table_ui_redraw_cb;
    table->gui_handlers.destroy = table_destroy_cb;
    table->ui_data = sheet;

    g_object_ref (sheet);

    /* config the cell-block styles */

    widths = gnc_header_widths_new ();

    if (state_section && gnc_prefs_get_bool(GNC_PREFS_GROUP_GENERAL, GNC_PREF_SAVE_GEOMETRY))
    {
        node = gnc_table_layout_get_cells (table->layout);
        for (; node; node = node->next)
        {
            BasicCell *cell = node->data;

            if (cell->expandable)
                continue;

            /* Remember whether the column is visible */
            key = g_strdup_printf("%s_width", cell->cell_name);
            value = g_key_file_get_integer (state_file, state_section, key, NULL);
            if (value != 0)
                gnc_header_widths_set_width (widths, cell->cell_name, value);
            g_free(key);
        }
    }

    gnucash_sheet_create_styles (sheet);

    gnucash_sheet_set_header_widths (sheet, widths);

    gnucash_sheet_compile_styles (sheet);

    gnucash_sheet_table_load (sheet, TRUE);
    gnucash_sheet_cursor_set_from_table (sheet, TRUE);
    gnucash_sheet_redraw_all (sheet);

    gnc_header_widths_destroy (widths);

    LEAVE(" ");
}

gboolean gnc_table_move_vertical_position	(	Table *	table,
		VirtualLocation *	virt_loc,
		int	phys_row_offset
	)

Moves away from virtual location virt_loc by phys_row_offset physical rows. Virtual cells that are not visible are skipped over.

Parameters

table	The table
virt_loc	The virtual location to start from. If the move succeeds, it is updated with the new location.
phys_row_offset	The number of physical rows to move. A positive number moves down and a negative number moves up.

Returns

TRUE if the location changed, FALSE otherwise

Definition at line 1629 of file table-allgui.c.

{
    VirtualLocation vloc;
    VirtualCell *vcell;
    gint last_visible_row;

    if ((table == NULL) || (virt_loc == NULL))
        return FALSE;

    vloc = *virt_loc;
    last_visible_row = vloc.vcell_loc.virt_row;

    vcell = gnc_table_get_virtual_cell (table, vloc.vcell_loc);
    if ((vcell == NULL) || (vcell->cellblock == NULL))
        return FALSE;

    while (phys_row_offset != 0)
    {
        /* going up */
        if (phys_row_offset < 0)
        {
            phys_row_offset++;

            /* room left in the current cursor */
            if (vloc.phys_row_offset > 0)
            {
                vloc.phys_row_offset--;
                continue;
            }

            /* end of the line */
            if (vloc.vcell_loc.virt_row == 1)
                break;

            do
            {
                vloc.vcell_loc.virt_row--;

                vcell = gnc_table_get_virtual_cell (table, vloc.vcell_loc);
            }
            while (vcell && vcell->cellblock && !vcell->visible);

            if (!vcell || !vcell->cellblock)
                break;

            last_visible_row = vloc.vcell_loc.virt_row;
            vloc.phys_row_offset = vcell->cellblock->num_rows - 1;
        }
        /* going down */
        else
        {
            phys_row_offset--;

            /* room left in the current cursor */
            if (vloc.phys_row_offset < (vcell->cellblock->num_rows - 1))
            {
                vloc.phys_row_offset++;
                continue;
            }

            /* end of the line */
            if (vloc.vcell_loc.virt_row == (table->num_virt_rows - 1))
                break;

            do
            {
                vloc.vcell_loc.virt_row++;

                vcell = gnc_table_get_virtual_cell (table, vloc.vcell_loc);
            }
            while (vcell && vcell->cellblock && !vcell->visible);

            if (!vcell || !vcell->cellblock)
                break;

            last_visible_row = vloc.vcell_loc.virt_row;
            vloc.phys_row_offset = 0;
        }
    }

    vloc.vcell_loc.virt_row = last_visible_row;

    {
        gboolean changed = !virt_loc_equal (vloc, *virt_loc);

        *virt_loc = vloc;

        return changed;
    }
}

void gnc_table_save_state	(	Table *	table,
		gchar *	state_section
	)

Implementation

Definition at line 68 of file table-gnome.c.

{
    GnucashSheet *sheet;
    GNCHeaderWidths widths;
    GList *node;
    gchar *key;
    GKeyFile *state_file = gnc_state_get_current();
    
    if (!table)
        return;

    if (table->ui_data == NULL)
        return;

    if (!gnc_prefs_get_bool(GNC_PREFS_GROUP_GENERAL, GNC_PREF_SAVE_GEOMETRY))
        return;

    sheet = GNUCASH_SHEET (table->ui_data);

    widths = gnc_header_widths_new ();

    gnucash_sheet_get_header_widths (sheet, widths);

    node = gnc_table_layout_get_cells (table->layout);
    for (; node; node = node->next)
    {
        BasicCell *cell = node->data;
        int width;

        width = gnc_header_widths_get_width (widths, cell->cell_name);

        /* Remember whether the column is visible */
        key = g_strdup_printf("%s_width", cell->cell_name);
        if ((width > 0) && (!cell->expandable))
        {
            g_key_file_set_integer (state_file, state_section, key, width);
        }
        else if (g_key_file_has_key (state_file, state_section, key, NULL))
            g_key_file_remove_key (state_file, state_section, key, NULL);
        g_free (key);
    }

    gnc_header_widths_destroy (widths);
}

void gnc_table_set_default_gui_handlers

(

TableGUIHandlers *

gui_handlers

)

Implementation

Definition at line 67 of file table-allgui.c.

{
    if (!gui_handlers)
        memset (&default_gui_handlers, 0, sizeof (default_gui_handlers));
    else
        default_gui_handlers = *gui_handlers;
}