libinfinity-0.6 Reference Manual: InfAdoptedUndoGrouping

## InfAdoptedUndoGrouping InfAdoptedUndoGrouping — Grouping of requests to be undone simultaneously |

## Stability Level

Unstable, unless otherwise indicated

## Functions

InfAdoptedUndoGrouping * | inf_adopted_undo_grouping_new ()
InfAdoptedAlgorithm * | inf_adopted_undo_grouping_get_algorithm ()
void | inf_adopted_undo_grouping_set_algorithm ()
void | inf_adopted_undo_grouping_start_group ()
void | inf_adopted_undo_grouping_end_group ()
guint | inf_adopted_undo_grouping_get_undo_size ()
guint | inf_adopted_undo_grouping_get_redo_size ()

## Properties

InfAdoptedAlgorithm * | algorithm | Read / Write
InfAdoptedUser * | user | Read / Write

## Signals

gboolean | group-requests | Run Last

## Types and Values

struct | InfAdoptedUndoGrouping
struct | InfAdoptedUndoGroupingClass

## Object Hierarchy

        GObject
        ╰── InfAdoptedUndoGrouping

## Includes

    #include <libinfinity/adopted/inf-adopted-undo-grouping.h>

## Description

InfAdoptedUndoGrouping groups related requests together so that they can be undone at the same time. For example, Undo in a text editor is normally expected to operate on written words, not characters. Therefore, multiple requests need to be undone at once.

The undo grouping helps with this. Everytime it needs to decide whether two requests should be grouped it emits “group-requests”. If the signal handler returns `TRUE` then the two requests will be undone at the same time, otherwise not.

It is also possible to explicitely group a bunch of requests that would not be grouped otherwise, by calling `inf_adopted_undo_grouping_start_group()` and `inf_adopted_undo_grouping_end_group()` before and after issuing the requests, respectively.

The default signal handler always returns `FALSE`. However, this behaviour can be changed in derived classes.

## Functions

### inf_adopted_undo_grouping_new ()

    InfAdoptedUndoGrouping *
    inf_adopted_undo_grouping_new (void);

Creates a new InfAdoptedUndoGrouping. To start grouping requests, set a user whose requests to group via `inf_adopted_undo_grouping_set_algorithm()`. Before doing so you might want to connect to “group-requests”, so the user's initial requests can be grouped correctly.

#### Returns

A new InfAdoptedUndoGrouping, to be freed via `g_object_unref()`.

### inf_adopted_undo_grouping_get_algorithm ()

    InfAdoptedAlgorithm *
    inf_adopted_undo_grouping_get_algorithm
                                   (InfAdoptedUndoGrouping *grouping);

Returns the InfAdoptedAlgorithm for `grouping` .

#### Parameters

grouping | A InfAdoptedUndoGrouping. |

#### Returns

`grouping` 's algorithm.

### inf_adopted_undo_grouping_set_algorithm ()

    void
    inf_adopted_undo_grouping_set_algorithm
                                   (InfAdoptedUndoGrouping *grouping,
                                    InfAdoptedAlgorithm *algorithm,
                                    InfAdoptedUser *user);

Sets the algorithm and user to group requests for. This function will group all requests in user's request log, and also each new request that is added to it's log. Requests that cannot be undone anymore (because they are too old), will be correctly taken care off.

#### Parameters

grouping | A InfAdoptedUndoGrouping. |
algorithm | The InfAdoptedAlgorithm for the document to group requests, or `NULL`. |
user | The user for which to group requests, or `NULL`. Ignored if `algorithm` is `NULL`. |

### inf_adopted_undo_grouping_start_group ()

    void
    inf_adopted_undo_grouping_start_group (InfAdoptedUndoGrouping *grouping,
                                           gboolean allow_group_with_prev);

Makes all requests issued after this call belong into the same group, i.e. they will be undone at once. This can make sense for example when the user copy+pastes something into the document which causes multiple requests to be generated. A call to `inf_adopted_undo_grouping_end_group()` restores the normal behavior.

#### Parameters

grouping | A InfAdoptedUndoGrouping. |
allow_group_with_prev | Whether the new group can be part of the previous group if “group-requests” allows. |

### inf_adopted_undo_grouping_end_group ()

    void
    inf_adopted_undo_grouping_end_group (InfAdoptedUndoGrouping *grouping,
                                         gboolean allow_group_with_next);

When `inf_adopted_undo_grouping_start_group()` was called before, then this function restores the normal behaviour of grouping requests.

#### Parameters

grouping | A InfAdoptedUndoGrouping. |
allow_group_with_next | Whether subsequent requests are allow to be part of this group if “group-requests” allows. |

### inf_adopted_undo_grouping_get_undo_size ()

    guint
    inf_adopted_undo_grouping_get_undo_size
                                   (InfAdoptedUndoGrouping *grouping);

Returns the number of requests to undo so that a whole group is being undone. This takes into account that possibly not the whole group cannot be undone due to the “max-total-log-size” constraint.

#### Parameters

grouping | A InfAdoptedUndoGrouping. |

#### Returns

The number of requests in the current undo group.

### inf_adopted_undo_grouping_get_redo_size ()

    guint
    inf_adopted_undo_grouping_get_redo_size
                                   (InfAdoptedUndoGrouping *grouping);

Returns the number of requests to redo so that a whole group is being redone. This takes into account that possibly not the whole group cannot be undone due to the “max-total-log-size” constraint.

#### Parameters

grouping | A InfAdoptedUndoGrouping. |

#### Returns

The number of requests in the current redo group.

## Types and Values

### struct InfAdoptedUndoGrouping

    struct InfAdoptedUndoGrouping;

InfAdoptedUndoGrouping is an opaque data type. You should only access it via the public API functions.

### struct InfAdoptedUndoGroupingClass

    struct InfAdoptedUndoGroupingClass {
      gboolean (*group_requests)(InfAdoptedUndoGrouping* grouping,
                                 InfAdoptedRequest* first,
                                 InfAdoptedRequest* second);
    };

This structure contains default signal handlers for InfAdoptedUndoGrouping.

#### Members

`group_requests` () | Default signal handler for the “group-requests” signal. |

## Property Details

### The `“algorithm”` property

      “algorithm”                InfAdoptedAlgorithm *

The algorithm for which to group requests.

Flags: Read / Write

### The `“user”` property

      “user”                     InfAdoptedUser *

The user for which to group requests.

Flags: Read / Write

## Signal Details

### The `“group-requests”` signal

    gboolean
    user_function (InfAdoptedUndoGrouping *grouping,
                   InfAdoptedRequest      *first,
                   InfAdoptedRequest      *second,
                   gpointer                user_data)

This signal is emitted whenever the InfAdoptedUndoGrouping needs to decide whether to put two requests into the same undo group or not. A signal handler should return `TRUE` if they belong into the same group or `FALSE` otherwise. Note however that the two requests may not immediately follow each other because other users may have issued requests inbetween. Check the vector times of the requests to find out, using `inf_adopted_request_get_vector()`.

#### Parameters

grouping | The InfAdoptedUndoGrouping which is about to group a request. |
first | The previous request. |
second | The current request. |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

## See Also

InfAdoptedAlgorithm