## Synthetic data modules

Synthetic data modules — Synthetic data modules

## Functions

void | (*GwySynthFunc) ()
gboolean | gwy_synth_func_register ()
void | gwy_synth_func_run ()
gboolean | gwy_synth_func_exists ()
GwyRunModeFlags | gwy_synth_func_get_run_modes ()
const gchar * | gwy_synth_func_get_menu_path ()
const gchar * | gwy_synth_func_get_icon_name ()
const gchar * | gwy_synth_func_get_tooltip ()
void | gwy_synth_func_foreach ()
const gchar * | gwy_synth_func_current ()

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

Synthetic data modules implement functions creating new data from scratch. They often query the current data (generally image data) and can take dimensions and units from or initialise the generator using them. They can also modify the current data. However, they can always be run without any other data loaded.

## Functions

### GwySynthFunc()

    void
    (*GwySynthFunc) (GwyFile *data,
                     GwyRunModeFlags run);

The type of synthetic data function.

Uniquely, `data` may be `NULL` for synthetic data functions. They need to create a new file then. Helper functions such as `gwy_synth_add_result_to_file()` exist to simplify and unify the implementation.

#### Parameters

data | The file data container to operate on. |
run | Run mode. |

### gwy_synth_func_register()

    gboolean
    gwy_synth_func_register (const gchar *name,
                             GwySynthFunc func,
                             const gchar *menu_path,
                             const gchar *icon_name,
                             GwyRunModeFlags modes,
                             const gchar *tooltip);

Registers a synthetic data 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.

#### Parameters

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 Synthetic menu. The menu path should be marked translatabe, but passed untranslated (to allow merging of translated and untranslated submenus). |
icon_name | Stock icon id for toolbar. |
modes | Supported run modes. Dynthetic data functions can have two run modes: `GWY_RUN_IMMEDIATE` (no questions asked) and `GWY_RUN_INTERACTIVE` (a modal dialog with parameters). |
tooltip | Tooltip for this function. |

#### Returns

Normally `TRUE`; `FALSE` on failure.

### gwy_synth_func_run()

    void
    gwy_synth_func_run (const gchar *name,
                        GwyFile *data,
                        GwyRunModeFlags mode);

Runs a synthetic data function identified by `name` .

#### Parameters

name | Curve map data processing function name. |
data | A file data container, possibly `NULL`. | [transfer none][nullable]
mode | How the function should be run. |

### gwy_synth_func_exists()

    gboolean
    gwy_synth_func_exists (const gchar *name);

Checks whether a synthetic data function exists.

#### Parameters

name | Curve map data processing function name. |

#### Returns

`TRUE` if function `name` exists, `FALSE` otherwise.

### gwy_synth_func_get_run_modes()

    GwyRunModeFlags
    gwy_synth_func_get_run_modes (const gchar *name);

Returns run modes supported by a synthetic data function.

#### Parameters

name | Curve map data processing function name. |

#### Returns

The run mode bit mask.

### gwy_synth_func_get_menu_path()

    const gchar *
    gwy_synth_func_get_menu_path (const gchar *name);

Returns the menu path of a synthetic data function.

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

#### Parameters

name | Curve map data processing function name. |

#### Returns

The menu path. The returned string is owned by the module.

### gwy_synth_func_get_icon_name()

    const gchar *
    gwy_synth_func_get_icon_name (const gchar *name);

Gets icon name of a synthetic data function.

#### Parameters

name | Curve map data processing function name. |

#### Returns

The icon name. The returned string is owned by the module.

### gwy_synth_func_get_tooltip()

    const gchar *
    gwy_synth_func_get_tooltip (const gchar *name);

Gets tooltip for a synthetic data function.

#### Parameters

name | Curve map data processing function name. |

#### Returns

The tooltip. The returned string is owned by the module.

### gwy_synth_func_foreach()

    void
    gwy_synth_func_foreach (GwyNameFunc function,
                            gpointer user_data);

Calls a function for each volume function.

#### Parameters

function | Function to run for each synthetic data function, passed by name. | [scope call]
user_data | Data to pass to `function` . |

### gwy_synth_func_current()

    const gchar *
    gwy_synth_func_current (void);

Obtains the name of currently running synthetic data function.

If no synthetic data function is currently running, `NULL` is returned.

If multiple nested functions are running (which is not usual but technically possible), the innermost function name is returned.

#### Returns

The name of currently running synthetic data function or `NULL`.