InfAdoptedUndoGrouping

InfAdoptedUndoGrouping — Grouping of requests to be undone simultaneously

Stability Level

Unstable, unless otherwise indicated

Functions

Properties

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

Signals

gboolean group-requests Run Last

Types and Values

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.

[constructor]

Returns

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

[transfer full]


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.

[transfer none]


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.

Owner: InfAdoptedUndoGrouping

Flags: Read / Write


The “user” property

  “user”                     InfAdoptedUser *

The user for which to group requests.

Owner: InfAdoptedUndoGrouping

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