Polled Tables

From Agar

Source found in agar/demos/table/table.c

Two widgets are included in the Agar distribution which implement the display of content (text, images, controls) in tabular format. They are AG_Table(3) and AG_Treetbl(3). This tutorial discusses the former.

AG_Table is designed to graphically display an existing list or array of data structures. Unlike AG_Treetbl, it is not designed to store or retain data in uniquely-named rows and columns. Keeping AG_Table populated with dynamic data is typically done from a function which we refer to as the polling function.

Creating the Table and columns

Typical initialization code for an AG_Table:

AG_Table *tbl;
 
tbl = AG_TableNewPolled(parent, 0, UpdateTable, NULL);
AG_TableAddCol(tbl, "Column 1", "<8888>", NULL);
AG_TableAddCol(tbl, "Column 2", "<888888888>", NULL);
AG_Expand(tbl);

We create the table using AG_TableNewPolled(), which accepts a pointer to the polling function, UpdateTable(). We create two columns and define their default width (here we use the width of some strings - other formats such as "100px" or "10%" are allowed, see AG_SizeSpec(3) for details).

The AG_Expand() call stretches the table to fit the available space in the parent container widget.

Implementing a polling function

The polling routine simply populates the table by adding rows:

static void
UpdateTable(AG_Event *event)
{
        AG_Table *tbl = AG_SELF();
        int i;
 
        AG_TableBegin(tbl);
        for (i = 0; i < prev; i++) {
                AG_TableAddRow(tbl, "%d:Element %d", i, i);
        }
        AG_TableEnd(tbl);
}

We start with AG_TableBegin() which "clears" the table (actually moves contents to a temporary buffer). The table is then populated with AG_TableAddRow(). The format string we use is not a "printf" style format string - it follows a specific format (see the manual page for a list of accepted specifiers).

Using embedded widgets

Arbitrary widgets can be displays as cells in an AG_Table. In a polled table, the widgets are recreated on refresh. Therefore, to embed widgets in polled tables, you must rely on bindings:

int myData[20];
 
...
 
void
UpdateTable(AG_Event *event)
{
        AG_Table *tbl = AG_SELF();
        int i;
 
        for (i = 0; i < 20; i++) {
                AG_Button *btn;
 
                btn = AG_ButtonNewInt(NULL, AG_BUTTON_STICKY, "Select",
                    &myData[i]);
                AG_TableAddRow(tbl, "%[W]:Row %d", btn, i);
        }
}

The widget to embed is allocated, but must not be attached to any parent (the first argument to AG_ButtonNewInt() should be NULL). The %[W] specifier inserts a widget in the given cell.

See also

• Widget Bindings
• AG_Table(3), AG_Treetbl(3), AG_Button(3)