## gwymodule-process

gwymodule-process — Data processing modules

## Synopsis

    #include <libgwymodule/gwymodule.h>

    void                (*GwyProcessFunc)                   (GwyContainer *data,
                                                             GwyRunType run,
                                                             const gchar *name);
    gboolean            gwy_process_func_register           (const gchar *name,
                                                             GwyProcessFunc func,
                                                             const gchar *menu_path,
                                                             const gchar *stock_id,
                                                             GwyRunType run,
                                                             guint sens_mask,
                                                             const gchar *tooltip);
    void                gwy_process_func_run                (const gchar *name,
                                                             GwyContainer *data,
                                                             GwyRunType run);
    gboolean            gwy_process_func_exists             (const gchar *name);
    GwyRunType          gwy_process_func_get_run_types      (const gchar *name);
    const gchar*        gwy_process_func_get_menu_path      (const gchar *name);
    const gchar*        gwy_process_func_get_stock_id       (const gchar *name);
    const gchar*        gwy_process_func_get_tooltip        (const gchar *name);
    guint               gwy_process_func_get_sensitivity_mask
                                                            (const gchar *name);
    void                gwy_process_func_foreach            (GFunc function,
                                                             gpointer user_data);

## Description

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

## Details

### GwyProcessFunc ()

    void                (*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 as registered with `gwy_process_func_register()` (single-function modules can safely ignore this argument).

### gwy_process_func_register ()

    gboolean            gwy_process_func_register           (const gchar *name,
                                                             GwyProcessFunc func,
                                                             const gchar *menu_path,
                                                             const gchar *stock_id,
                                                             GwyRunType run,
                                                             guint sens_mask,
                                                             const gchar *tooltip);

Registers a data processing function.

Note: the string arguments are not copied as modules are not expected to vanish. If they are constructed (non-constant) strings, do not free them. Should modules ever become unloadable they will get a chance to clean-up.

`name` : | Name of function to register. It should be a valid identifier and if a module registers only one function, module and function names should be the same.
`func` : | The function itself.
`menu_path` : | Menu path under Data Process menu. The menu path should be marked translatabe, but passed untranslated (to allow merging of translated and untranslated submenus).
`stock_id` : | Stock icon id for toolbar.
`run` : | Supported run modes. Data processing functions can have two run modes: `GWY_RUN_IMMEDIATE` (no questions asked) and `GWY_RUN_INTERACTIVE` (a modal dialog with parameters).
`sens_mask` : | Sensitivity mask (a combination of GwyMenuSensFlags flags). Usually it contains GWY_MENU_FLAG_DATA, possibly other requirements.
`tooltip` : | Tooltip for this function.
Returns : | Normally `TRUE`; `FALSE` on failure.

### gwy_process_func_run ()

    void                gwy_process_func_run                (const gchar *name,
                                                             GwyContainer *data,
                                                             GwyRunType run);

Runs a data processing function identified by `name`.

`name` : | Data processing function name.
`data` : | Data (a GwyContainer).
`run` : | How the function should be run.

### gwy_process_func_exists ()

    gboolean            gwy_process_func_exists             (const gchar *name);

Checks whether a data processing function exists.

`name` : | Data processing function name.
Returns : | `TRUE` if function `name` exists, `FALSE` otherwise.

### gwy_process_func_get_run_types ()

    GwyRunType          gwy_process_func_get_run_types      (const gchar *name);

Returns run modes supported by a data processing function.

`name` : | Data processing function name.
Returns : | The run mode bit mask.

### gwy_process_func_get_menu_path ()

    const gchar*        gwy_process_func_get_menu_path      (const gchar *name);

Returns the menu path of a data processing function.

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 is owned by the module.

### gwy_process_func_get_stock_id ()

    const gchar*        gwy_process_func_get_stock_id       (const gchar *name);

Gets stock icon id of a data processing function.

`name` : | Data processing function name.
Returns : | The stock icon id. The returned string is owned by the module.

### gwy_process_func_get_tooltip ()

    const gchar*        gwy_process_func_get_tooltip        (const gchar *name);

Gets tooltip for a data processing function.

`name` : | Data processing function name.
Returns : | The tooltip. The returned string is owned by the module.

### gwy_process_func_get_sensitivity_mask ()

    guint               gwy_process_func_get_sensitivity_mask
                                                            (const gchar *name);

Gets menu sensititivy mask for a data processing function.

`name` : | Data processing function name.
Returns : | The menu item sensitivity mask (a combination of GwyMenuSensFlags flags).

### gwy_process_func_foreach ()

    void                gwy_process_func_foreach            (GFunc function,
                                                             gpointer user_data);

Calls a function for each process function.

`function` : | Function to run for each process function. It will get function name (constant string owned by module system) as its first argument, `user_data` as the second argument.
`user_data` : | Data to pass to `function`.