User interface activities
[Estron support library]

---

Detailed Description

API for handling user interface activities. "Actions" typically get run as a result of the GUI user clicking on a button or performing some other user interface activity. An action stores state information about what should happen when the button-click/signal/etc. occurs.

More precisely, actions are triggered by GTK signals issued from GTK widgets. The action stores the template of an SQL query that will be run when the signal is caught. Along with this, it stores the widgets that will be queried to fill in the blanks in the SQL statement.

The action also stores a list of reports that need to be refreshed when the SQL query is completed.

Not all actions need to perform SQL queries. Some (wtokey) cause data to be copied from the user interface widgets to the key-value pair tree. Others (wtoobj) copy the data to GLib-2.0 GObjects.

Functions
DuiAction *	dui_action_new (const char *name)
void	dui_action_destroy (DuiAction *)
const char *	dui_action_get_name (DuiAction *)
void	dui_action_set_interface (DuiAction *act, DuiInterface *)
void	dui_action_add_resolver (DuiAction *, DuiResolverFieldFunc, gpointer user_data)
void	dui_action_add_realizer (DuiAction *, DuiResolverRealizeFunc, gpointer user_data)
void	dui_action_set_database_name (DuiAction *act, const char *dbname)
void	dui_action_add_row (DuiAction *, DuiTxnQuery *qry)
DuiTxnQuery *	dui_action_get_query (DuiAction *)
void	dui_action_add_term (DuiAction *act, DuiFieldMap *fm)
void	dui_action_set_report (DuiAction *, const char *name)
const char *	dui_action_get_report (DuiAction *)
void	dui_action_add_refresh (DuiAction *, const char *name)
void	dui_action_rerun_last_query (DuiAction *act)
void	dui_action_add_chain (DuiAction *act, const char *actionname)
void	dui_action_do_realize (DuiAction *)
void	dui_action_db_connect (DuiAction *act)
int	dui_action_run (DuiAction *act)

---

Function Documentation

void dui_action_add_chain	(	DuiAction *	act,
		const char *	actionname
	)

Add a chained action

void dui_action_add_refresh	(	DuiAction *	,
		const char *	name
	)

Add a window that needs to be refreshed when this action is performed

void dui_action_add_resolver	(	DuiAction *	,
		DuiResolverFieldFunc	,
		gpointer	user_data
	)

Tell the action about how to convert names into actual objects

Definition at line 383 of file action.c.

{
    if (!act) return;
    dui_resolver_add_resolver (act->resolver, fn, ud);
}

void dui_action_add_row	(	DuiAction *	,
		DuiTxnQuery *	qry
	)

Add a 'row' to the action. The row will typically hold a table widget, or possibly an object class name. If the row holds a table widget (e.g. gtklist, gtkctree, etc.), then the rows of the table will be used to formulate the SQL query. If the row holds an object class, then the action will find the matching instances of that class, and use those instances to formulate the query.

Definition at line 238 of file action.c.

{
    if (!act || !qry) return;

    dui_txnquery_set_resolver (qry, act->resolver);

    /* XXX we should do something if this is called twice ... */
    if (act->query)
    {
        PERR ("There already is a query in this action");
    }
    act->query = qry;
}

void dui_action_add_term	(	DuiAction *	act,
		DuiFieldMap *	fm
	)

Add a term, which may be an sql select, sql update, sql where matcher, or it might be a non-sql map

< Database table column

< match to database column

< Field with const value

Definition at line 260 of file action.c.

{
    if (!act || !fm) return;

    if (DUI_FIELD_IS_TYPE(&fm->target, DUI_FIELD_SQL) ||
        DUI_FIELD_IS_TYPE(&fm->target, DUI_FIELD_WHERE) ||
        DUI_FIELD_IS_TYPE(&fm->target, DUI_FIELD_CONST))
    {
        if (NULL == act->query)
        {
            DuiTxnQuery *qry = dui_txnquery_new();
            dui_action_add_row (act, qry);
            act->query = qry;
        }
        dui_txnquery_add_term (act->query, fm);
    }
    else
    {
        dui_resolver_add_field (act->resolver, &fm->source);
        dui_resolver_add_field (act->resolver, &fm->target);
        act->non_table_targets = g_list_append (act->non_table_targets, fm);
    }
}

void dui_action_db_connect

(

DuiAction *

act

)

Force the db to connect. This will cause any connect errors to be reported.

Definition at line 410 of file action.c.

{
    if (!act) return;
    dui_txnquery_connect (act->query);
}

void dui_action_do_realize

(

DuiAction *

)

Resolve stuff; the book/window/interface must be set before calling this. The action must be realized before it can be run.

Definition at line 397 of file action.c.

{
    if (!act) return;

    ENTER ("(act=%p)", act);
    final_setup (act);
    dui_resolver_realize (act->resolver);
    LEAVE ("(act=%p)", act);
}

void dui_action_rerun_last_query

(

DuiAction *

act

)

Rerun the last query (and display it in a report). this routine is used to refresh a window.

Definition at line 473 of file action.c.

{
    DuiDBRecordSet *recs = NULL;

    if (!act) return;

    ENTER ("(act=%p \'%s\')", act, dui_action_get_name (act));

    /* Issue same query as before, and display the results */
    recs = dui_txnquery_rerun_last_query (act->query);
    dui_report_show_data (act->report, recs);
    dui_recordset_free (recs);

    LEAVE ("(act=%p \'%s\')", act, dui_action_get_name (act));
}

int dui_action_run

(

DuiAction *

act

)

Cause the indicated action to be run.

Definition at line 419 of file action.c.

{
    DuiDBRecordSet *recs = NULL;
    GList *node;
    gint rc = 0;

    if (!act) return 0;
    ENTER ("(act=%p \'%s\')", act, dui_action_get_name (act));
    final_setup (act);

    /* We need to resolve the widgets again, because the action window
     * may have been closed. When it is re-realized, there will be all
     * new widgets for the thing.  It would probably be more efficient
     * (and more complex) to catch the window-close signal. Oh well. */
    resolve_widget_again (act);

    /* Loop over chained actions; quit if one of them handled things */
    for (node=act->check_list; node; node=node->next)
    {
        DuiCheck *chk = node->data;
        rc = dui_action_run (chk->action);
        if (rc) return rc;
    }

    /* Loop over list of field maps that don't involve any SQL tables,
     * and move the data from the source to the target. */
    for (node = act->non_table_targets; node; node=node->next)
    {
        DuiFieldMap *fm = node->data;
        dui_field_map_transfer_data (fm);
    }

    recs = dui_txnquery_run (act->query);

    /* Now report the results. */
    dui_report_set_last_action (act->report, act);
    rc = dui_report_show_data (act->report, recs);

    /* Don't need it no more */
    dui_recordset_free (recs);

    /* Refresh all windows that show data modified by this query */
    for (node=act->refresh_list; node; node=node->next)
    {
        DuiRefresh *rsh = node->data;
        dui_report_refresh (rsh->report);
    }
    LEAVE ("(act=%p \'%s\') rc=%d", act, dui_action_get_name (act), rc);
    return rc;
}

void dui_action_set_database_name	(	DuiAction *	act,
		const char *	dbname
	)

Set the name of the database connection that will be used to perform queries on

void dui_action_set_interface	(	DuiAction *	act,
		DuiInterface *
	)

Tell the action about where to find the 'global' objects, such as kvp trees, gobjects etc.

Definition at line 376 of file action.c.

{
    if (!act) return;
    act->interface = iface;
}

void dui_action_set_report	(	DuiAction *	,
		const char *	name
	)

Cross-reference to the reports that will show the results.