Tutorial: Using the Table Widget

Hypertriton, Inc.
( Francais )

Introduction

The AG_Table widget displays a table where cells are associated with strings, numerical values or other types of information. It is possible to select individual cells, entire rows and entire columns. Custom popup menus can also be associated with cells, rows and columns.

To reduce code dependence on the GUI (and code bloat), we advocate the use of a polling function to update the contents of tables which are used to display some underlying data structure. Attempting to keep a table widget up to date with the underlying structure by explicitely updating rows is generally error-prone and not worth the performance gain. It is always nice to be able to disable GUI code using only one or two #ifdef's in any given source file.

Table cells generally contain data such as text or numbers, but they can also be associated with typed functions or typed pointers.

Creating the table

Here is a typical use of AG_TableNew() to create a new table. The AG_TABLE_EXPAND flag causes the table to expand to maximum size inside its parent container.

Example 1-1: Creating a table (source)

#include <agar/core.h>
#include <agar/gui.h>
 
int
main(int argc, char *argv)
{
	AG_Window *win;
	AG_Table *tbl;
 
	/* Initialize Agar. */
	if (AG_InitCore("table1", 0) == -1 ||
	    AG_InitVideo(320, 240, 32, AG_VIDEO_RESIZABLE) == -1)
		return (1);
 
	/* Create a new window. */
	win = AG_WindowNew(0);
 
	/* Create a new table that expands to fill the window. */
	tbl = AG_TableNew(win, AG_TABLE_EXPAND);
 
	/* Show the window and enter event loop. */
	AG_WindowShow(win);
	AG_EventLoop();
	return (0);
}

Adding columns

Columns are added with the AG_TableAddCol() function. The initial width of the column is specified in AG_SizeSpec format. If the size specification string is NULL, the column fills all remaining space. You can also provide an optional sorting function for items in the column.

Example 1-2 - Adding columns

The selection state of columns can be controlled with functions AG_TableSelectCol(), AG_TableDeselectCol() and AG_TableColSelected().

Example 1-2: Adding columns (source)

#include <agar/core.h>
#include <agar/gui.h>
 
static int
SortString(const void *p1, const void *p2)
{
	const AG_TableCell *c1 = p1;
	const AG_TableCell *c2 = p2;
	return (strcoll(c1->data.s, c2->data.s));
}
 
static int
SortInt(const void *p1, const void *p2)
{
	const AG_TableCell *c1 = p1;
	const AG_TableCell *c2 = p2;
	return (c1->data.i - c2->data.i);
}
 
int
main(int argc, char *argv)
{
	AG_Window *win;
	AG_Table *tbl;
 
	/* Initialize Agar. */
	if (AG_InitCore("table1", 0) == -1 ||
	    AG_InitVideo(320, 240, 32, AG_VIDEO_RESIZABLE) == -1)
		return (1);
 
	/* Create a new window. */
	win = AG_WindowNew(0);
 
	/* Create a new table that expands to fill the window. */
	tbl = AG_TableNew(win, AG_TABLE_EXPAND);
 
	/* Insert the columns. */
	AG_TableAddCol(tbl, "Item", "<Foo>", SortString);
	AG_TableAddCol(tbl, "Count", NULL, SortInt);
 
	/* Show the window and enter event loop. */
	AG_WindowShow(win);
	AG_EventLoop();
	return (0);
}

Adding rows

Example 1-3 - Adding rows

The AG_TableAddRow() function inserts a new row into the table. It accepts a colon-separated list of specifiers which define the types of the individual cells, such as "%s" for a string and "%i" for an int (see the AG_Table manual for a list of all recognized types).

Example 1-3: Adding rows (source)

#include <agar/core.h>
#include <agar/gui.h>
 
static int
SortString(const void *p1, const void *p2)
{
	const AG_TableCell *c1 = p1;
	const AG_TableCell *c2 = p2;
 
	return (strcoll(c1->data.s, c2->data.s));
}
 
static int
SortInt(const void *p1, const void *p2)
{
	const AG_TableCell *c1 = p1;
	const AG_TableCell *c2 = p2;
 
	return (c1->data.i - c2->data.i);
}
 
int
main(int argc, char *argv)
{
	AG_Window *win;
	AG_Table *tbl;
 
	/* Initialize Agar. */
	if (AG_InitCore("table1", 0) == -1 ||
	    AG_InitVideo(320, 240, 32, AG_VIDEO_RESIZABLE) == -1)
		return (1);
 
	/* Create a new window. */
	win = AG_WindowNew(0);
 
	/* Create a new table that expands to fill the window. */
	tbl = AG_TableNew(win, AG_TABLE_EXPAND);
 
	/* Insert the columns. */
	AG_TableAddCol(tbl, "Item", "<Foo>", SortString);
	AG_TableAddCol(tbl, "Count", NULL, SortInt);
 
	/* Insert the rows. */
	AG_TableAddRow(tbl, "%s:%i", "Foo", 10);
	AG_TableAddRow(tbl, "%s:%i", "Bar", 100);
	AG_TableAddRow(tbl, "%s:%i", "Baz", 1000);
 
	/* Show the window and enter event loop. */
	AG_WindowShow(win);
	AG_EventLoop();
	return (0);
}