gwymodule-volume: Gwyddion Module Library Reference Manual

## gwymodule-volume gwymodule-volume — Volume data processing modules |

## Functions

void | (*GwyVolumeFunc) ()
gboolean | gwy_volume_func_register ()
void | gwy_volume_func_run ()
gboolean | gwy_volume_func_exists ()
GwyRunType | gwy_volume_func_get_run_types ()
const gchar * | gwy_volume_func_get_menu_path ()
const gchar * | gwy_volume_func_get_stock_id ()
const gchar * | gwy_volume_func_get_tooltip ()
guint | gwy_volume_func_get_sensitivity_mask ()
void | gwy_volume_func_foreach ()
const gchar * | gwy_volume_func_current ()

## Includes

    #include <libgwymodule/gwymodule.h>

## Description

Volume data processing modules implement function processing volume data represented with GwyBrick. They reigster functions that get a GwyContainer with data and either modify it or create a new data from it. In this regard, they are quite similar to regular (two-dimensional) data processing functions but they live in separate menus, toolbars, etc.

Volume data processing functions were introduced in version 2.32.

## Functions

### GwyVolumeFunc ()

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

The type of volume data processing function.

#### Parameters

data | The data container to operate on. |
run | Run mode. |
name | Function name from as registered with `gwy_volume_func_register()` (single-function modules can safely ignore this argument). |

Since: 2.32

### gwy_volume_func_register ()

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

Registers a volume 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.

#### 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 Volume Data 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. Volume 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_VOLUME, possibly other requirements. |
tooltip | Tooltip for this function. |

#### Returns

Normally `TRUE`; `FALSE` on failure.

Since: 2.32

### gwy_volume_func_run ()

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

Runs a volume data processing function identified by `name` .

#### Parameters

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

Since: 2.32

### gwy_volume_func_exists ()

    gboolean
    gwy_volume_func_exists (const gchar *name);

Checks whether a volume data processing function exists.

#### Parameters

name | Volume data processing function name. |

#### Returns

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

Since: 2.32

### gwy_volume_func_get_run_types ()

    GwyRunType
    gwy_volume_func_get_run_types (const gchar *name);

Returns run modes supported by a volume data processing function.

#### Parameters

name | Volume data processing function name. |

#### Returns

The run mode bit mask.

Since: 2.32

### gwy_volume_func_get_menu_path ()

    const gchar *
    gwy_volume_func_get_menu_path (const gchar *name);

Returns the menu path of a volume data processing function.

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

#### Parameters

name | Volume data processing function name. |

#### Returns

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

Since: 2.32

### gwy_volume_func_get_stock_id ()

    const gchar *
    gwy_volume_func_get_stock_id (const gchar *name);

Gets stock icon id of a volume data processing function.

#### Parameters

name | Volume data processing function name. |

#### Returns

The stock icon id. The returned string is owned by the module.

Since: 2.32

### gwy_volume_func_get_tooltip ()

    const gchar *
    gwy_volume_func_get_tooltip (const gchar *name);

Gets tooltip for a volume data processing function.

#### Parameters

name | Volume data processing function name. |

#### Returns

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

Since: 2.32

### gwy_volume_func_get_sensitivity_mask ()

    guint
    gwy_volume_func_get_sensitivity_mask (const gchar *name);

Gets menu sensititivy mask for a volume data processing function.

#### Parameters

name | Volume data processing function name. |

#### Returns

The menu item sensitivity mask (a combination of GwyMenuSensFlags flags).

Since: 2.32

### gwy_volume_func_foreach ()

    void
    gwy_volume_func_foreach (GFunc function,
                             gpointer user_data);

Calls a function for each volume function.

#### Parameters

function | Function to run for each volume 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` . |

Since: 2.32

### gwy_volume_func_current ()

    const gchar *
    gwy_volume_func_current (void);

Obtains the name of currently running volume data processing function.

If no volume data processing 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 volume data processing function or `NULL`.

Since: 2.38