gwymodule-process

gwymodule-process — Data field processing modules

Synopsis




enum        GwyRunType;
struct      GwyProcessFuncInfo;
gboolean    (*GwyProcessFunc)               (GwyContainer *data,
                                             GwyRunType run,
                                             const gchar *name);
gboolean    gwy_process_func_register       (const gchar *modname,
                                             GwyProcessFuncInfo *func_info);
gboolean    gwy_process_func_run            (const guchar *name,
                                             GwyContainer *data,
                                             GwyRunType run);
GwyRunType  gwy_process_func_get_run_types  (const gchar *name);
gchar*      gwy_process_func_get_menu_path  (const gchar *name);
GtkObject*  gwy_process_func_build_menu     (GtkObject *item_factory,
                                             const gchar *prefix,
                                             GCallback item_callback);
guint       gwy_process_func_get_sensitivity_flags
                                            (const gchar *name);

Description

Data processing modules implement the actual ability to do something useful with the data. They reigster functions that get a GwyContainer with data and either modify it or create a new data field from it.

Details

enum GwyRunType

typedef enum {
    GWY_RUN_NONE           = 0,
    GWY_RUN_WITH_DEFAULTS  = 1 << 0,
    GWY_RUN_NONINTERACTIVE = 1 << 1,
    GWY_RUN_MODAL          = 1 << 2,
    GWY_RUN_INTERACTIVE    = 1 << 3,
    GWY_RUN_MASK           = 0x0f
} GwyRunType;

Data processing function run-modes.

GWY_RUN_NONE None.
GWY_RUN_WITH_DEFAULTS The function is run non-interactively, and it should use default parameter values.
GWY_RUN_NONINTERACTIVE The function is run non-interactively, and it should use parameter values stored in the container to reproduce previous runs.
GWY_RUN_MODAL The function presents a [presumably simple] modal GUI to the user, it returns after finishing all operations.
GWY_RUN_INTERACTIVE The function presents a non-modal GUI to the user, it returns while after setting up the GUI, not after finishing its work.
GWY_RUN_MASK The mask for all the run modes.

struct GwyProcessFuncInfo

struct GwyProcessFuncInfo {

    const gchar *name;
    const gchar *menu_path;
    GwyProcessFunc process;
    GwyRunType run;
    guint sens_flags;    /* guint, don't depend on libgwyapp */
};

Information about one data processing function.

const gchar *name An unique data processing function name.
const gchar *menu_path A path under "/Data Process" where the function should appear. It must start with "/".
GwyProcessFunc process The function itself.
GwyRunType run Possible run-modes for this function.
guint sens_flags

GwyProcessFunc ()

gboolean    (*GwyProcessFunc)               (GwyContainer *data,
                                             GwyRunType run,
                                             const gchar *name);

The type of data processing function.

data : The data container to operate on.
run : Run mode.
name : Function name from GwyProcessFuncInfo (most modules can safely ignore this argument)
Returns : Whether it changed data. (Incidentally, creation of a new data window without touching data does not change data.)

gwy_process_func_register ()

gboolean    gwy_process_func_register       (const gchar *modname,
                                             GwyProcessFuncInfo *func_info);

Registeres a data processing function.

To keep compatibility with old versions func_info should not be an automatic variable. However, since 1.6 it keeps a copy of func_info.

modname : Module identifier (name).
func_info : Data processing function info.
Returns : TRUE on success, FALSE on failure.

gwy_process_func_run ()

gboolean    gwy_process_func_run            (const guchar *name,
                                             GwyContainer *data,
                                             GwyRunType run);

Runs a data processing function identified by name.

It guarantees the container lifetime spans through the actual processing, so the module function doesn't have to care about it.

name : Data processing function name.
data : Data (a GwyContainer).
run : How the function should be run.
Returns : TRUE on success, FALSE on failure.

gwy_process_func_get_run_types ()

GwyRunType  gwy_process_func_get_run_types  (const gchar *name);

Returns possible run modes for a data processing function identified by name.

This function is the prefered one for testing whether a data processing function exists, as function with no run modes cannot be registered.

name : Data processing function name.
Returns : The run mode bit mask, zero if the function does not exist.

gwy_process_func_get_menu_path ()

gchar*      gwy_process_func_get_menu_path  (const gchar *name);

Returns the menu path of a data processing function identified by name.

The returned menu path is only the tail part registered by the function, i.e., without any leading "/Data Process".

name : Data processing function name.
Returns : The menu path. The returned string must be treated as constant and never modified or freed.

gwy_process_func_build_menu ()

GtkObject*  gwy_process_func_build_menu     (GtkObject *item_factory,
                                             const gchar *prefix,
                                             GCallback item_callback);

Creates GtkItemFactory for a data processing menu with all registered data processing functions.

item_factory : A GtkItemFactory to add items to.
prefix : Where to add the menu items to the factory.
item_callback : A GtkItemFactoryCallback1 called when an item from the menu is selected.
Returns : The menu item factory as a GtkObject.

gwy_process_func_get_sensitivity_flags ()

guint       gwy_process_func_get_sensitivity_flags
                                            (const gchar *name);

Returns menu sensititivy flags for function name.

name : Data processing function name.
Returns : The menu item sensitivity flags, as it was set with gwy_process_func_set_sensitivity_flags(), i.e., without any implied flags.

Since 1.2.