undo

undo — Undo and redo facility

Synopsis

#include <app/gwyapp.h>

gulong              gwy_app_undo_checkpoint             (GwyContainer *data,
                                                         ...);
gulong              gwy_app_undo_qcheckpoint            (GwyContainer *data,
                                                         ...);
gulong              gwy_app_undo_checkpointv            (GwyContainer *data,
                                                         guint n,
                                                         const gchar **keys);
gulong              gwy_app_undo_qcheckpointv           (GwyContainer *data,
                                                         guint n,
                                                         const GQuark *keys);
void                gwy_app_undo_undo_container         (GwyContainer *data);
void                gwy_app_undo_redo_container         (GwyContainer *data);
void                gwy_app_undo_container_remove       (GwyContainer *data,
                                                         const gchar *prefix);
gulong              gwy_undo_checkpoint                 (GwyContainer *data,
                                                         ...);
gulong              gwy_undo_qcheckpoint                (GwyContainer *data,
                                                         ...);
gulong              gwy_undo_checkpointv                (GwyContainer *data,
                                                         guint n,
                                                         const gchar **keys);
gulong              gwy_undo_qcheckpointv               (GwyContainer *data,
                                                         guint n,
                                                         const GQuark *keys);
void                gwy_undo_undo_container             (GwyContainer *data);
void                gwy_undo_redo_container             (GwyContainer *data);
gboolean            gwy_undo_container_has_undo         (GwyContainer *data);
gboolean            gwy_undo_container_has_redo         (GwyContainer *data);
gint                gwy_undo_container_get_modified     (GwyContainer *data);
void                gwy_undo_container_set_unmodified   (GwyContainer *data);
void                gwy_undo_container_remove           (GwyContainer *data,
                                                         const gchar *prefix);
gboolean            gwy_undo_get_enabled                (void);
void                gwy_undo_set_enabled                (gboolean setting);

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 GwyContainer is automatically destroyed when the container is finalized.

Details

gwy_app_undo_checkpoint ()

gulong              gwy_app_undo_checkpoint             (GwyContainer *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.

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            (GwyContainer *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.

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            (GwyContainer *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.

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           (GwyContainer *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.

If keys include channel keys the corresponding channel calibration data is saved together with the data and then removed from the container. This prevents mismatch between a data field and its calibration data. Therefore, if you perform a data operation that can also meaningfully transform the corresponding calibration data take care to obtain it before saving undo.

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_container ()

void                gwy_app_undo_undo_container         (GwyContainer *data);

Performs undo on a data container.

It must have undo available.

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

data :

A data container.

gwy_app_undo_redo_container ()

void                gwy_app_undo_redo_container         (GwyContainer *data);

Performs undo on a data container.

It must have redo available.

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

data :

A data container.

gwy_app_undo_container_remove ()

void                gwy_app_undo_container_remove       (GwyContainer *data,
                                                         const gchar *prefix);

Removes undo/redo information for a data container.

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

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.

Since 2.23


gwy_undo_checkpoint ()

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

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

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                (GwyContainer *data,
                                                         ...);

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

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                (GwyContainer *data,
                                                         guint n,
                                                         const gchar **keys);

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

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               (GwyContainer *data,
                                                         guint n,
                                                         const GQuark *keys);

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

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_container ()

void                gwy_undo_undo_container             (GwyContainer *data);

Performs undo on a data container.

It must have undo available.

data :

A data container.

gwy_undo_redo_container ()

void                gwy_undo_redo_container             (GwyContainer *data);

Performs undo on a data container.

It must have redo available.

data :

A data container.

gwy_undo_container_has_undo ()

gboolean            gwy_undo_container_has_undo         (GwyContainer *data);

Returns whether there is any undo available for a container.

data :

Data container to get undo infomation of.

Returns :

TRUE if there is undo, FALSE otherwise.

gwy_undo_container_has_redo ()

gboolean            gwy_undo_container_has_redo         (GwyContainer *data);

Returns whether there is any redo available for a container.

data :

Data container to get redo infomation of.

Returns :

TRUE if there is redo, FALSE otherwise.

gwy_undo_container_get_modified ()

gint                gwy_undo_container_get_modified     (GwyContainer *data);

Tests whether a container was modified.

FIXME: it may not work.

data :

Data container to get modification infomation of.

Returns :

TRUE if container was modified, FALSE otherwise.

gwy_undo_container_set_unmodified ()

void                gwy_undo_container_set_unmodified   (GwyContainer *data);

Marks a data container as umodified (that is, saved).

data :

Data container to set modification infomation of.

gwy_undo_container_remove ()

void                gwy_undo_container_remove           (GwyContainer *data,
                                                         const gchar *prefix);

Removes undo/redo information for a data container.

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.

Since 2.21


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_container_get_modified() always returns zero. Disabling undo also removes saved undo data of all containers.

setting :

TRUE to enable undo, FALSE to disable it.

Since 2.21