undo: Gwyddion Application Library Reference Manual

## undo undo — Undo and redo facility |

## Functions

gulong | gwy_app_undo_checkpoint ()
gulong | gwy_app_undo_qcheckpoint ()
gulong | gwy_app_undo_checkpointv ()
gulong | gwy_app_undo_qcheckpointv ()
void | gwy_app_undo_undo_dict ()
void | gwy_app_undo_redo_dict ()
void | gwy_app_undo_dict_remove ()
gulong | gwy_undo_checkpoint ()
gulong | gwy_undo_qcheckpoint ()
gulong | gwy_undo_checkpointv ()
gulong | gwy_undo_qcheckpointv ()
void | gwy_undo_undo_dict ()
void | gwy_undo_redo_dict ()
gboolean | gwy_undo_dict_has_undo ()
gboolean | gwy_undo_dict_has_redo ()
void | gwy_undo_dict_remove ()
gboolean | gwy_undo_get_enabled ()
void | gwy_undo_set_enabled ()

## Includes

    #include <libgwyapp/gwyapp.h>

## Description

For a module developer, the only two useful undo/redo functions are probably `gwy_app_undo_checkpoint()` and `gwy_app_undo_checkpointv()` creating a checkpoint in the undo history to which is possible to return to later. You should use these functions before commiting changes to data.

The other functions actually perform undo or redo, and has little use outside main application, unless it wishes to implement its local undo.

There are two types of functions app-level and container-level. App-level functions (have `app' in their names) should be generally used only by the main application as they update menus and toolboxes according to undo and redo state. Container-level functions only perform the actual undo or redo and can be used for local undo implementation.

Undo information for a GwyDict is automatically destroyed when the container is finalized.

## Functions

### gwy_app_undo_checkpoint()

    gulong
    gwy_app_undo_checkpoint (GwyDict *data,
                             ...);

Create a point in the undo history it is possible to return to.

In addition to what `gwy_undo_checkpoint()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container. |
... | `NULL`-terminated list of container item names to save. |

#### Returns

Undo level id (zero if undo/redo is disabled). Not useful (yet).

### gwy_app_undo_qcheckpoint()

    gulong
    gwy_app_undo_qcheckpoint (GwyDict *data,
                              ...);

Create a point in the undo history it is possible to return to.

In addition to what `gwy_undo_checkpoint()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container. |
... | 0-terminated list of container item quark keys to save. |

#### Returns

Undo level id. Not useful (yet).

### gwy_app_undo_checkpointv()

    gulong
    gwy_app_undo_checkpointv (GwyDict *data,
                              guint n,
                              const gchar **keys);

Create a point in the undo history it is possible to return to.

In addition to what `gwy_undo_checkpointv()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container. |
n | The number of strings in `keys` . |
keys | An array of container string keys to save data. It can contain holes, that is NUL's, they are ignored. However, it should contain at least one real key. |

#### Returns

Undo level id. Not useful (yet).

### gwy_app_undo_qcheckpointv()

    gulong
    gwy_app_undo_qcheckpointv (GwyDict *data,
                               guint n,
                               const GQuark *keys);

Create a point in the undo history it is possible to return to.

In addition to what `gwy_undo_checkpointv()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container. |
n | The number of strings in `keys` . |
keys | An array of container quark keys to save data. It can contain holes, that is 0's, they are ignored. However, it should contain at least one real key. |

#### Returns

Undo level id. Not useful (yet).

### gwy_app_undo_undo_dict()

    void
    gwy_app_undo_undo_dict (GwyDict *data);

Performs undo on a data container.

It must have undo available.

In addition to what `gwy_undo_undo_dict()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container. |

### gwy_app_undo_redo_dict()

    void
    gwy_app_undo_redo_dict (GwyDict *data);

Performs undo on a data container.

It must have redo available.

In addition to what `gwy_undo_redo_dict()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container. |

### gwy_app_undo_dict_remove()

    void
    gwy_app_undo_dict_remove (GwyDict *data,
                              const gchar *prefix);

Removes undo/redo information for a data container.

In addition to what `gwy_undo_dict_remove()` does, this function takes care of updating application controls state.

#### Parameters

data | A data container managed by the data-browser. |
prefix | Prefix to remove undo/redo information under. Pass `NULL` to remove undo/redo information altogether. |

### gwy_undo_checkpoint()

    gulong
    gwy_undo_checkpoint (GwyDict *data,
                         ...);

Create a point in the undo history it is possible to return to.

#### Parameters

data | A data container. |
... | `NULL`-terminated list of container item names to save. |

#### Returns

Undo level id. Not useful (yet).

### gwy_undo_qcheckpoint()

    gulong
    gwy_undo_qcheckpoint (GwyDict *data,
                          ...);

Create a point in the undo history it is possible to return to.

#### Parameters

data | A data container. |
... | 0-terminated list of container item quark keys to save. |

#### Returns

Undo level id. Not useful (yet).

### gwy_undo_checkpointv()

    gulong
    gwy_undo_checkpointv (GwyDict *data,
                          guint n,
                          const gchar **keys);

Create a point in the undo history it is possible to return to.

#### Parameters

data | A data container. |
n | The number of strings in `keys` . |
keys | An array of container string keys to save data. It can contain holes, that is NUL's, they are ignored. However, it should contain at least one real key. |

#### Returns

Undo level id. Not useful (yet).

### gwy_undo_qcheckpointv()

    gulong
    gwy_undo_qcheckpointv (GwyDict *data,
                           guint n,
                           const GQuark *keys);

Create a point in the undo history it is possible to return to.

#### Parameters

data | A data container. |
n | The number of strings in `keys` . |
keys | An array of container quark keys to save data. It can contain holes, that is 0's, they are ignored. However, it should contain at least one real key. |

#### Returns

Undo level id. Not useful (yet).

### gwy_undo_undo_dict()

    void
    gwy_undo_undo_dict (GwyDict *data);

Performs undo on a data container.

It must have undo available.

#### Parameters

data | A data container. |

### gwy_undo_redo_dict()

    void
    gwy_undo_redo_dict (GwyDict *data);

Performs undo on a data container.

It must have redo available.

#### Parameters

data | A data container. |

### gwy_undo_dict_has_undo()

    gboolean
    gwy_undo_dict_has_undo (GwyDict *data);

Returns whether there is any undo available for a container.

#### Parameters

data | Data container to get undo infomation of. |

#### Returns

`TRUE` if there is undo, `FALSE` otherwise.

### gwy_undo_dict_has_redo()

    gboolean
    gwy_undo_dict_has_redo (GwyDict *data);

Returns whether there is any redo available for a container.

#### Parameters

data | Data container to get redo infomation of. |

#### Returns

`TRUE` if there is redo, `FALSE` otherwise.

### gwy_undo_dict_remove()

    void
    gwy_undo_dict_remove (GwyDict *data,
                          const gchar *prefix);

Removes undo/redo information for a data container.

#### Parameters

data | A data container. |
prefix | Prefix to remove undo/redo information under. Pass `NULL` to remove undo/redo information altogether. |

### gwy_undo_get_enabled()

    gboolean
    gwy_undo_get_enabled (void);

Reports whether undo/redo is globally enabled.

#### Returns

`TRUE` if undo/redo is enabled, `FALSE` if it is disabled.

### gwy_undo_set_enabled()

    void
    gwy_undo_set_enabled (gboolean setting);

Globally enables or disables undo/redo.

By default, undo/redo is enabled. Non-GUI applications that run module functions may wish to disable it to conserve resources.

If undo/redo is disabled undo information manipulating functions such as `gwy_app_undo_qcheckpoint()` become no-op and `gwy_undo_dict_get_modified()` always returns zero. Disabling undo also removes saved undo data of all containers.

#### Parameters

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