log: Gwyddion Application Library Reference Manual

## log log — Logging data processing operations |

## Functions

void | gwy_app_channel_log_add ()
void | gwy_app_volume_log_add ()
void | gwy_app_xyz_log_add ()
void | gwy_app_curve_map_log_add ()
void | gwy_app_channel_log_add_proc ()
void | gwy_app_volume_log_add_volume ()
void | gwy_app_xyz_log_add_xyz ()
void | gwy_app_curve_map_log_add_curve_map ()
GtkWidget * | gwy_app_log_browser_for_channel ()
GtkWidget * | gwy_app_log_browser_for_volume ()
GtkWidget * | gwy_app_log_browser_for_xyz ()
GtkWidget * | gwy_app_log_browser_for_curve_map ()
gboolean | gwy_log_get_enabled ()
void | gwy_log_set_enabled ()

## Includes

    #include <app/gwyapp.h>

## Description

The data processing operation log is a linear sequence of operations applied to a image, volume, XYZ or curve map data. The log is informative and not meant to capture all information necessary to reply the operations, even though it can be sufficient for this purpose in simple cases.

The log is a linear sequence. This is only an approximation of the actual flow of information in the data processing, which corresponds to an acyclic directed graph (not necessarily connected as data, masks and presentations can have distinct sources). The following rules thus apply to make it meaningful and useful.

Each logging function takes two data identifiers: source and target. The source corresponds to the operation input, the target corresponds to the data whose log is being updated. The target may have already a log only if it is the same as the source (which corresponds to simple data modification such as levelling or grain marking). In all other cases the target must not have a log yet – they represent the creation of new data either from scratch or based on existing data (in the latter case the log of the existing data is replicated to the new one).

Complex multi-data operations are approximated by one of the simple operations. For instance, data arithmetic can be treated as the construction of a new channel from scratch as it is unclear which input data the output channel is actually based on, if any at all. Modifications that use data from other channels, such as masking using another data or tip convolution, should be represented as simple modifications of the primary channel.

Logging functions such as `gwy_app_channel_log_add()` take settings values corresponding to the function name and store them in the log entry. If the settings are stored under a different name, use the "settings-name" logging option to set the correct name.

## Functions

### gwy_app_channel_log_add ()

    void
    gwy_app_channel_log_add (GwyContainer *data,
                             gint previd,
                             gint newid,
                             const gchar *function,
                             ...);

Adds an entry to the log of data processing operations for a channel.

See the introduction for a description of valid `previd` and `newid` .

It is possible to pass `NULL` as `function` . In this case the log is just copied from source to target without adding any entries. This can be useful to prevent duplicate log entries in modules that modify a data field and then can also create secondary outputs. Note you still need to pass a second `NULL` argument as the option terminator.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) data channel in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) data channel in the container. |
function | Quailified name of the function applied as shown by the module browser. For instance "proc::facet-level" or "tool::GwyToolCrop". |
... | Logging options as a `NULL`-terminated list of pairs name, value. |

Since: 2.35

### gwy_app_volume_log_add ()

    void
    gwy_app_volume_log_add (GwyContainer *data,
                            gint previd,
                            gint newid,
                            const gchar *function,
                            ...);

Adds an entry to the log of data processing operations for volume data.

See the introduction for a description of valid `previd` and `newid` .

It is possible to pass `NULL` as `function` . In this case the log is just copied from source to target without adding any entries. This can be useful to prevent duplicate log entries in modules that modify a data field and then can also create secondary outputs. Note you still need to pass a second `NULL` argument as the option terminator.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) volume data in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) volume data in the container. |
function | Quailified name of the function applied as shown by the module browser. For instance "volume::volume_invert". |
... | Logging options as a `NULL`-terminated list of pairs name, value. |

Since: 2.35

### gwy_app_xyz_log_add ()

    void
    gwy_app_xyz_log_add (GwyContainer *data,
                         gint previd,
                         gint newid,
                         const gchar *function,
                         ...);

Adds an entry to the log of data processing operations for XYZ data.

See the introduction for a description of valid `previd` and `newid` .

It is possible to pass `NULL` as `function` . In this case the log is just copied from source to target without adding any entries. This can be useful to prevent duplicate log entries in modules that modify a data field and then can also create secondary outputs. Note you still need to pass a second `NULL` argument as the option terminator.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) XYZ data in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) XYZ data in the container. |
function | Quailified name of the function applied as shown by the module browser. For instance "xyz::xyz_invert". |
... | Logging options as a `NULL`-terminated list of pairs name, value. |

Since: 2.45

### gwy_app_curve_map_log_add ()

    void
    gwy_app_curve_map_log_add (GwyContainer *data,
                               gint previd,
                               gint newid,
                               const gchar *function,
                               ...);

Adds an entry to the log of data processing operations for GwyLawn curve map.

See the introduction for a description of valid `previd` and `newid` .

It is possible to pass `NULL` as `function` . In this case the log is just copied from source to target without adding any entries. This can be useful to prevent duplicate log entries in modules that modify a data field and then can also create secondary outputs. Note you still need to pass a second `NULL` argument as the option terminator.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) GwyLawn curve map in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) GwyLawn curve map in the container. |
function | Quailified name of the function applied as shown by the module browser. For instance "cmap::cmap_crop". |
... | Logging options as a `NULL`-terminated list of pairs name, value. |

Since: 2.60

### gwy_app_channel_log_add_proc ()

    void
    gwy_app_channel_log_add_proc (GwyContainer *data,
                                  gint previd,
                                  gint newid);

Adds an entry to the log of the current data processing operations for a channel.

This simplified variant of `gwy_app_channel_log_add()` takes the currently running data processing function name and constructs the qualified function name from that.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) data channel in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) data channel in the container. |

Since: 2.38

### gwy_app_volume_log_add_volume ()

    void
    gwy_app_volume_log_add_volume (GwyContainer *data,
                                   gint previd,
                                   gint newid);

Adds an entry to the log of the current volume data processing operations for volume data.

This simplified variant of `gwy_app_volume_log_add()` takes the currently running function volume data processing name and constructs the qualified function name from that.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) volume data in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) volume data in the container. |

Since: 2.38

### gwy_app_xyz_log_add_xyz ()

    void
    gwy_app_xyz_log_add_xyz (GwyContainer *data,
                             gint previd,
                             gint newid);

Adds an entry to the log of the current XYZ data processing operations for XYZ data.

This simplified variant of `gwy_app_xyz_log_add()` takes the currently running function XYZ data processing name and constructs the qualified function name from that.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) XYZ data in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) XYZ data in the container. |

Since: 2.45

### gwy_app_curve_map_log_add_curve_map ()

    void
    gwy_app_curve_map_log_add_curve_map (GwyContainer *data,
                                         gint previd,
                                         gint newid);

Adds an entry to the log of the current GwyLawn curve map processing operations for GwyLawn curve map.

This simplified variant of `gwy_app_curve_map_log_add()` takes the currently running function GwyLawn curve map processing name and constructs the qualified function name from that.

#### Parameters

data | A data container. |
previd | Identifier of the previous (source) GwyLawn curve map in the container. Pass -1 for a no-source (or unclear source) operation. |
newid | Identifier of the new (target) GwyLawn curve map in the container. |

Since: 2.60

### gwy_app_log_browser_for_channel ()

    GtkWidget *
    gwy_app_log_browser_for_channel (GwyContainer *data,
                                     gint id);

Shows a simple log browser for a channel.

If the log browser is already shown for this channel it is just raised and given focus. Otherwise, a new window is created.

#### Parameters

data | A data container. |
id | Id of a channel in `data` to show log for. |

#### Returns

The log browser (owned by the library). Usually, you can ignore the return value.

Since: 2.35

### gwy_app_log_browser_for_volume ()

    GtkWidget *
    gwy_app_log_browser_for_volume (GwyContainer *data,
                                    gint id);

Shows a simple log browser for volume data.

If the log browser is already shown for this volume data it is just raised and given focus. Otherwise, a new window is created.

#### Parameters

data | A data container. |
id | Id of volume data in `data` to show log for. |

#### Returns

The log browser (owned by the library). Usually, you can ignore the return value.

Since: 2.35

### gwy_app_log_browser_for_xyz ()

    GtkWidget *
    gwy_app_log_browser_for_xyz (GwyContainer *data,
                                 gint id);

Shows a simple log browser for XYZ data.

If the log browser is already shown for this XYZ data it is just raised and given focus. Otherwise, a new window is created.

#### Parameters

data | A data container. |
id | Id of XYZ data in `data` to show log for. |

#### Returns

The log browser (owned by the library). Usually, you can ignore the return value.

Since: 2.45

### gwy_app_log_browser_for_curve_map ()

    GtkWidget *
    gwy_app_log_browser_for_curve_map (GwyContainer *data,
                                       gint id);

Shows a simple log browser for GwyLawn curve map.

If the log browser is already shown for this GwyLawn curve map it is just raised and given focus. Otherwise, a new window is created.

#### Parameters

data | A data container. |
id | Id of GwyLawn curve map in `data` to show log for. |

#### Returns

The log browser (owned by the library). Usually, you can ignore the return value.

Since: 2.60

### gwy_log_get_enabled ()

    gboolean
    gwy_log_get_enabled (void);

Reports whether logging of data processing operations is globally enabled.

#### Returns

`TRUE` if logging is enabled, `FALSE` if it is disabled.

Since: 2.35

### gwy_log_set_enabled ()

    void
    gwy_log_set_enabled (gboolean setting);

Globally enables or disables logging of data processing operations.

By default, logging is enabled. Non-GUI applications that run module functions may wish to disable it. Of course, the log will presist only if the data container is saved into a GWY file.

If logging is disabled logging functions such as `gwy_app_channel_log_add()` become no-op. It is possible to run the log viewer with `gwy_app_log_browser_for_channel()` to see log entries created when logging was enabled.

#### Parameters

setting | `TRUE` to enable logging, `FALSE` to disable it. |

Since: 2.35