GnuCash
5.6-150-g038405b370+
|
The "Table" is a displayed matrix. More...
Files | |
file | gtable.h |
This is the API for GTables, a datatype for 2-dimensional tables with automatic resizing and memory management. | |
file | table-allgui.h |
Declarations for the Table object. | |
file | table-control.h |
file | table-layout.h |
file | table-model.h |
Data Structures | |
struct | VirtualCell |
holds information about each virtual cell. More... | |
struct | TableGUIHandlers |
struct | Table |
struct | TableControl |
struct | PhysicalCellBorders |
struct | TableModel |
Macros | |
#define | CURSOR_HEADER "cursor-header" |
Standard Cursor Names. | |
Typedefs | |
typedef void(* | g_table_entry_constructor) (gpointer entry, gpointer user_data) |
typedef void(* | g_table_entry_destroyer) (gpointer entry, gpointer user_data) |
typedef void(* | TableCursorRefreshCB) (Table *table, VirtualCellLocation vcell_loc, gboolean do_scroll) |
typedef void(* | TableRedrawHelpCB) (Table *table) |
typedef void(* | TableDestroyCB) (Table *table) |
typedef void(* | TableMoveFunc) (VirtualLocation *new_virt_loc, gpointer user_data) |
typedef gboolean(* | TableTraverseFunc) (VirtualLocation *new_virt_loc, gncTableTraversalDir dir, gpointer user_data) |
typedef const char *(* | TableGetEntryHandler) (VirtualLocation virt_loc, gboolean translate, gboolean *conditionally_changed, gpointer user_data) |
typedef const char *(* | TableGetLabelHandler) (VirtualLocation virt_loc, gpointer user_data) |
typedef char *(* | TableGetHelpHandler) (VirtualLocation virt_loc, gpointer user_data) |
typedef char *(* | TableGetTooltipHandler) (VirtualLocation virt_loc, gpointer user_data) |
typedef CellIOFlags(* | TableGetCellIOFlagsHandler) (VirtualLocation virt_loc, gpointer user_data) |
typedef guint32(* | TableGetCellColorHandler) (VirtualLocation virt_loc, gboolean *hatching, gpointer user_data) |
typedef void(* | TableGetCellBorderHandler) (VirtualLocation virt_loc, PhysicalCellBorders *borders, gpointer user_data) |
typedef gboolean(* | TableConfirmHandler) (VirtualLocation virt_loc, gpointer user_data) |
typedef void(* | TableSaveCellHandler) (BasicCell *cell, gpointer save_data, gpointer user_data) |
typedef void(* | TableSaveHandler) (gpointer save_data, gpointer user_data) |
typedef gpointer(* | VirtCellDataAllocator) (void) |
typedef void(* | VirtCellDataDeallocator) (gpointer cell_data) |
typedef void(* | VirtCellDataCopy) (gpointer to, gconstpointer from) |
Enumerations | |
enum | RegisterColor { COLOR_UNDEFINED = 0, COLOR_HEADER, COLOR_PRIMARY, COLOR_PRIMARY_ACTIVE, COLOR_SECONDARY, COLOR_SECONDARY_ACTIVE, COLOR_SPLIT, COLOR_SPLIT_ACTIVE, COLOR_NEGATIVE = 16 } |
Color definitions used for table elements. | |
enum | gncTableTraversalDir { GNC_TABLE_TRAVERSE_POINTER, GNC_TABLE_TRAVERSE_LEFT, GNC_TABLE_TRAVERSE_RIGHT, GNC_TABLE_TRAVERSE_UP, GNC_TABLE_TRAVERSE_DOWN } |
enum | CellIOFlags { XACC_CELL_ALLOW_NONE = 0, XACC_CELL_ALLOW_INPUT = 1 << 0, XACC_CELL_ALLOW_SHADOW = 1 << 1, XACC_CELL_ALLOW_ALL = XACC_CELL_ALLOW_INPUT | XACC_CELL_ALLOW_SHADOW, XACC_CELL_ALLOW_EXACT_ONLY = 1 << 2, XACC_CELL_ALLOW_ENTER = 1 << 3, XACC_CELL_ALLOW_READ_ONLY = XACC_CELL_ALLOW_SHADOW | XACC_CELL_ALLOW_ENTER } |
enum | PhysicalCellBorderLineStyle { CELL_BORDER_LINE_NONE, CELL_BORDER_LINE_LIGHT, CELL_BORDER_LINE_NORMAL, CELL_BORDER_LINE_HEAVY, CELL_BORDER_LINE_HIGHLIGHT } |
Functions | |
GTable * | g_table_new (guint entry_size, g_table_entry_constructor constructor, g_table_entry_destroyer destroyer, gpointer user_data) |
Create a new table with the given entry constructor and destroyer. More... | |
void | g_table_destroy (GTable *gtable) |
Free the table and all associated table elements. More... | |
gpointer | g_table_index (GTable *gtable, int row, int col) |
Return the element at the given row and column. More... | |
void | g_table_resize (GTable *gtable, int rows, int cols) |
Resize the table, allocating and deallocating extra table members if needed. More... | |
int | g_table_rows (GTable *gtable) |
Return the number of table rows. More... | |
int | g_table_cols (GTable *gtable) |
Return the number of table columns. More... | |
void | gnc_table_set_default_gui_handlers (TableGUIHandlers *gui_handlers) |
Set the default gui handlers used by new tables. More... | |
Table * | gnc_table_new (TableLayout *layout, TableModel *model, TableControl *control) |
void | gnc_virtual_location_init (VirtualLocation *vloc) |
void | gnc_table_save_state (Table *table, const gchar *state_section) |
Implementation. | |
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) |
checks the given location and returns true if it is out of bounds of the table. More... | |
gboolean | gnc_table_virtual_location_in_header (Table *table, VirtualLocation virt_loc) |
VirtualCell * | gnc_table_get_virtual_cell (Table *table, VirtualCellLocation vcell_loc) |
returns the virtual cell associated with a particular virtual location. More... | |
const char * | gnc_table_get_entry (Table *table, VirtualLocation virt_loc) |
char * | gnc_table_get_tooltip (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_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) |
Return the virtual cell of the header. | |
void | gnc_table_set_size (Table *table, int virt_rows, int virt_cols) |
The gnc_table_set_size() method will resize the table to the indicated dimensions. More... | |
void | gnc_table_set_vcell (Table *table, CellBlock *cursor, gconstpointer vcell_data, gboolean visible, gboolean start_primary_color, VirtualCellLocation vcell_loc) |
Indicate what handler should be used for a given virtual block. | |
void | gnc_table_set_virt_cell_data (Table *table, VirtualCellLocation vcell_loc, gconstpointer vcell_data) |
Set the virtual cell data for a particular location. More... | |
void | gnc_table_set_virt_cell_visible (Table *table, VirtualCellLocation vcell_loc, gboolean visible) |
Set the visibility flag for a particular location. More... | |
void | gnc_table_set_virt_cell_cursor (Table *table, VirtualCellLocation vcell_loc, CellBlock *cursor) |
Set the cellblock handler for a virtual cell. More... | |
void | gnc_table_move_cursor (Table *table, VirtualLocation virt_loc) |
will move the cursor (but not the cursor GUI) to the indicated location. More... | |
void | gnc_table_move_cursor_gui (Table *table, VirtualLocation virt_loc) |
will move the cursor and its GUI to the indicated location. More... | |
gboolean | gnc_table_verify_cursor_position (Table *table, VirtualLocation virt_loc) |
checks the location of the cursor with respect to a virtual location position, and if the resulting virtual location has changed, repositions the cursor and gui to the new position. More... | |
gpointer | gnc_table_get_vcell_data (Table *table, VirtualCellLocation vcell_loc) |
returns the virtual cell data associated with a cursor located at the given virtual coords, or NULL if the coords are out of bounds. More... | |
gboolean | gnc_table_find_close_valid_cell (Table *table, VirtualLocation *virt_loc, gboolean exact_cell) |
Find a close valid cell. More... | |
void | gnc_table_init_gui (Table *table) |
UI-specific functions. More... | |
void | gnc_table_realize_gui (Table *table) |
void | gnc_table_refresh_current_cursor_gui (Table *table, gboolean do_scroll) |
Refresh the current cursor gui. | |
void | gnc_table_refresh_gui (Table *table, gboolean do_scroll) |
Refresh the whole GUI from the table. More... | |
void | gnc_table_show_range (Table *table, VirtualCellLocation start_loc, VirtualCellLocation end_loc) |
Try to show the whole range in the register. More... | |
void | gnc_table_refresh_cursor_gui (Table *table, VirtualCellLocation vcell_loc, gboolean do_scroll) |
Refresh the cursor in the given location. More... | |
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) |
Moves away from virtual location virt_loc by phys_row_offset physical rows. More... | |
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) |
TableControl * | gnc_table_control_new (void) |
void | gnc_table_control_destroy (TableControl *control) |
void | gnc_table_control_allow_move (TableControl *control, gboolean allow_move) |
TableLayout * | gnc_table_layout_new (void) |
API Declarations. | |
void | gnc_table_layout_destroy (TableLayout *layout) |
void | gnc_table_layout_add_cell (TableLayout *layout, BasicCell *cell) |
BasicCell * | gnc_table_layout_get_cell (TableLayout *layout, const char *cell_name) |
const char * | gnc_table_layout_get_cell_value (TableLayout *layout, const char *cell_name) |
gboolean | gnc_table_layout_get_cell_changed (TableLayout *layout, const char *cell_name, gboolean include_conditional) |
GList * | gnc_table_layout_get_cells (TableLayout *layout) |
void | gnc_table_layout_add_cursor (TableLayout *layout, CellBlock *cursor) |
CellBlock * | gnc_table_layout_get_cursor (TableLayout *layout, const char *cursor_name) |
GList * | gnc_table_layout_get_cursors (TableLayout *layout) |
void | gnc_table_layout_set_primary_cursor (TableLayout *layout, CellBlock *cursor) |
void | gnc_table_layout_set_cell (TableLayout *layout, CellBlock *cursor, const char *cell_name, int row, int col) |
CursorBuffer * | gnc_cursor_buffer_new (void) |
void | gnc_cursor_buffer_destroy (CursorBuffer *buffer) |
void | gnc_table_layout_save_cursor (TableLayout *layout, CellBlock *cursor, CursorBuffer *buffer) |
void | gnc_table_layout_restore_cursor (TableLayout *layout, CellBlock *cursor, CursorBuffer *buffer) |
TableModel * | gnc_table_model_new (void) |
void | gnc_table_model_destroy (TableModel *model) |
void | gnc_table_model_set_read_only (TableModel *model, gboolean read_only) |
gboolean | gnc_table_model_read_only (TableModel *model) |
void | gnc_table_model_set_reverse_sort (TableModel *model, gboolean read_only) |
void | gnc_table_model_set_entry_handler (TableModel *model, TableGetEntryHandler entry_handler, const char *cell_name) |
void | gnc_table_model_set_default_entry_handler (TableModel *model, TableGetEntryHandler entry_handler) |
TableGetEntryHandler | gnc_table_model_get_entry_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_label_handler (TableModel *model, TableGetLabelHandler label_handler, const char *cell_name) |
void | gnc_table_model_set_default_label_handler (TableModel *model, TableGetLabelHandler label_handler) |
TableGetLabelHandler | gnc_table_model_get_label_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_help_handler (TableModel *model, TableGetHelpHandler help_handler, const char *cell_name) |
void | gnc_table_model_set_default_help_handler (TableModel *model, TableGetHelpHandler help_handler) |
TableGetHelpHandler | gnc_table_model_get_help_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_tooltip_handler (TableModel *model, TableGetTooltipHandler tooltip_handler, const char *cell_name) |
void | gnc_table_model_set_default_tooltip_handler (TableModel *model, TableGetTooltipHandler tooltip_handler) |
TableGetTooltipHandler | gnc_table_model_get_tooltip_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_io_flags_handler (TableModel *model, TableGetCellIOFlagsHandler io_flags_handler, const char *cell_name) |
void | gnc_table_model_set_default_io_flags_handler (TableModel *model, TableGetCellIOFlagsHandler io_flags_handler) |
TableGetCellIOFlagsHandler | gnc_table_model_get_io_flags_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_cell_color_handler (TableModel *model, TableGetCellColorHandler io_flags_handler, const char *cell_name) |
void | gnc_table_model_set_default_cell_color_handler (TableModel *model, TableGetCellColorHandler io_flags_handler) |
TableGetCellColorHandler | gnc_table_model_get_cell_color_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_cell_border_handler (TableModel *model, TableGetCellBorderHandler io_flags_handler, const char *cell_name) |
void | gnc_table_model_set_default_cell_border_handler (TableModel *model, TableGetCellBorderHandler io_flags_handler) |
TableGetCellBorderHandler | gnc_table_model_get_cell_border_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_confirm_handler (TableModel *model, TableConfirmHandler io_flags_handler, const char *cell_name) |
void | gnc_table_model_set_default_confirm_handler (TableModel *model, TableConfirmHandler io_flags_handler) |
TableConfirmHandler | gnc_table_model_get_confirm_handler (TableModel *model, const char *cell_name) |
void | gnc_table_model_set_save_handler (TableModel *model, TableSaveCellHandler save_handler, const char *cell_name) |
void | gnc_table_model_set_pre_save_handler (TableModel *model, TableSaveHandler save_handler) |
void | gnc_table_model_set_post_save_handler (TableModel *model, TableSaveHandler save_handler) |
TableSaveCellHandler | gnc_table_model_get_save_handler (TableModel *model, const char *cell_name) |
TableSaveHandler | gnc_table_model_get_pre_save_handler (TableModel *model) |
TableSaveHandler | gnc_table_model_get_post_save_handler (TableModel *model) |
The "Table" is a displayed matrix.
The table is a complex object; it is not merely a Cellblock. The table provides all of the GUI infrastructure for displaying a row-column matrix of strings.
The table provides one very important function for minimizing memory usage for large matrixes - the notion of a "Cursor". The cursor is a Cellblock (an array of active cells) that is moved to the location that the user is currently editing. The cursor "virtualizes" Cell functions; that is, it makes it seem to the user as if all cells in the table are active, when in fact the only cell that actually needs to be active is the one that the user is currently editing.
The table design allows multiple cursors to be defined. When a user enters a cell, the appropriate cursor is positioned within the table. Cursors cannot overlap: any given cell can be mapped to at most one cursor. Multiple-cursor support allows tables to be designed that have a non-uniform layout. For example, the multiple-cursor support can be used to define a tree structure of headings and sub-headings, where the layout/format of the heading is different from the sub-headings. A financial example is a table which lists splits underneath their parent transaction. This is very different from a checkbook register, where all entries are uniform, and can be handled with a single repeated cursor.
Users of the table must provide a TableView object which provides an API the table uses to obtain information about the data it is displaying such as strings, colors, etc. Thus, the table represents the non-GUI portion of the View object in the Model-View-Controller paradigm.
int g_table_cols | ( | GTable * | gtable | ) |
void g_table_destroy | ( | GTable * | gtable | ) |
Free the table and all associated table elements.
Definition at line 69 of file gtable.c.
gpointer g_table_index | ( | GTable * | gtable, |
int | row, | ||
int | col | ||
) |
GTable* g_table_new | ( | guint | entry_size, |
g_table_entry_constructor | constructor, | ||
g_table_entry_destroyer | destroyer, | ||
gpointer | user_data | ||
) |
Create a new table with the given entry constructor and destroyer.
Both functions must be given. They are used to initialize the table entries and free unneeded memory when resizing and destroying.
Definition at line 44 of file gtable.c.
void g_table_resize | ( | GTable * | gtable, |
int | rows, | ||
int | cols | ||
) |
Resize the table, allocating and deallocating extra table members if needed.
The relationship between table members before and after resizing is undefined, except in the case where the number of rows changes, but not the number of columns. In that case, higher-numbered rows are discarded first.
Definition at line 104 of file gtable.c.
int g_table_rows | ( | GTable * | gtable | ) |
gboolean gnc_table_find_close_valid_cell | ( | Table * | table, |
VirtualLocation * | virt_loc, | ||
gboolean | exact_cell | ||
) |
Find a close valid cell.
If exact_cell is true, cells that must be explicitly selected by the user (as opposed to just tabbing into), are considered valid cells.
Definition at line 1504 of file table-allgui.c.
gpointer gnc_table_get_vcell_data | ( | Table * | table, |
VirtualCellLocation | vcell_loc | ||
) |
returns the virtual cell data associated with a cursor located at the given virtual coords, or NULL if the coords are out of bounds.
Definition at line 932 of file table-allgui.c.
VirtualCell* gnc_table_get_virtual_cell | ( | Table * | table, |
VirtualCellLocation | vcell_loc | ||
) |
returns the virtual cell associated with a particular virtual location.
If the location is out of bounds, NULL is * returned.
Definition at line 227 of file table-allgui.c.
void gnc_table_init_gui | ( | Table * | table | ) |
UI-specific functions.
Initialize the GUI from a table
Definition at line 158 of file table-gnome.c.
void gnc_table_move_cursor | ( | Table * | table, |
VirtualLocation | virt_loc | ||
) |
will move the cursor (but not the cursor GUI) to the indicated location.
This function is useful when loading the table from the cursor: data can be loaded into the cursor, then committed to the table, all without the annoying screen flashing associated with GUI redraw.
Definition at line 878 of file table-allgui.c.
void gnc_table_move_cursor_gui | ( | Table * | table, |
VirtualLocation | virt_loc | ||
) |
will move the cursor and its GUI to the indicated location.
Through a series of callbacks, all GUI elements get repositioned.
Definition at line 887 of file table-allgui.c.
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.
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. |
Definition at line 1602 of file table-allgui.c.
void gnc_table_refresh_cursor_gui | ( | Table * | table, |
VirtualCellLocation | vcell_loc, | ||
gboolean | do_scroll | ||
) |
Refresh the cursor in the given location.
If do_scroll is TRUE, scroll the register so the location is in view.
Definition at line 1514 of file table-allgui.c.
void gnc_table_refresh_gui | ( | Table * | table, |
gboolean | do_scroll | ||
) |
Refresh the whole GUI from the table.
Definition at line 165 of file table-gnome.c.
void gnc_table_set_default_gui_handlers | ( | TableGUIHandlers * | gui_handlers | ) |
Set the default gui handlers used by new tables.
Set the default gui handlers used by new tables.
Definition at line 67 of file table-allgui.c.
void gnc_table_set_size | ( | Table * | table, |
int | virt_rows, | ||
int | virt_cols | ||
) |
The gnc_table_set_size() method will resize the table to the indicated dimensions.
Definition at line 587 of file table-allgui.c.
void gnc_table_set_virt_cell_cursor | ( | Table * | table, |
VirtualCellLocation | vcell_loc, | ||
CellBlock * | cursor | ||
) |
Set the cellblock handler for a virtual cell.
Definition at line 737 of file table-allgui.c.
void gnc_table_set_virt_cell_data | ( | Table * | table, |
VirtualCellLocation | vcell_loc, | ||
gconstpointer | vcell_data | ||
) |
Set the virtual cell data for a particular location.
Definition at line 700 of file table-allgui.c.
void gnc_table_set_virt_cell_visible | ( | Table * | table, |
VirtualCellLocation | vcell_loc, | ||
gboolean | visible | ||
) |
Set the visibility flag for a particular location.
Definition at line 720 of file table-allgui.c.
void gnc_table_show_range | ( | Table * | table, |
VirtualCellLocation | start_loc, | ||
VirtualCellLocation | end_loc | ||
) |
Try to show the whole range in the register.
Definition at line 215 of file table-gnome.c.
gboolean gnc_table_verify_cursor_position | ( | Table * | table, |
VirtualLocation | virt_loc | ||
) |
checks the location of the cursor with respect to a virtual location position, and if the resulting virtual location has changed, repositions the cursor and gui to the new position.
Returns true if the cell cursor was repositioned.
Definition at line 898 of file table-allgui.c.
gboolean gnc_table_virtual_cell_out_of_bounds | ( | Table * | table, |
VirtualCellLocation | vcell_loc | ||
) |
checks the given location and returns true if it is out of bounds of the table.
Definition at line 207 of file table-allgui.c.