InfAdoptedUndoGrouping

InfAdoptedUndoGrouping — Grouping of requests to be undone simultaneously

Stability Level

Unstable, unless otherwise indicated

Synopsis

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

                    InfAdoptedUndoGrouping;
                    InfAdoptedUndoGroupingClass;
InfAdoptedUndoGrouping * inf_adopted_undo_grouping_new  (void);
InfAdoptedAlgorithm * inf_adopted_undo_grouping_get_algorithm
                                                        (InfAdoptedUndoGrouping *grouping);
void                inf_adopted_undo_grouping_set_algorithm
                                                        (InfAdoptedUndoGrouping *grouping,
                                                         InfAdoptedAlgorithm *algorithm,
                                                         InfAdoptedUser *user);
void                inf_adopted_undo_grouping_start_group
                                                        (InfAdoptedUndoGrouping *grouping,
                                                         gboolean allow_group_with_prev);
void                inf_adopted_undo_grouping_end_group (InfAdoptedUndoGrouping *grouping,
                                                         gboolean allow_group_with_next);
guint               inf_adopted_undo_grouping_get_undo_size
                                                        (InfAdoptedUndoGrouping *grouping);
guint               inf_adopted_undo_grouping_get_redo_size
                                                        (InfAdoptedUndoGrouping *grouping);

Object Hierarchy

  GObject
   +----InfAdoptedUndoGrouping

Properties

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

Signals

  "group-requests"                                 : Run Last

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.

Details

InfAdoptedUndoGrouping

typedef struct _InfAdoptedUndoGrouping InfAdoptedUndoGrouping;

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


InfAdoptedUndoGroupingClass

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

This structure contains default signal handlers for InfAdoptedUndoGrouping.

group_requests ()

Default signal handler for the "group-requests" signal.

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.

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.

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.

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);

grouping :

allow_group_with_next :


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.

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.

grouping :

A InfAdoptedUndoGrouping.

Returns :

The number of requests in the current redo group.

Property Details

The "algorithm" property

  "algorithm"                InfAdoptedAlgorithm*  : Read / Write

The algorithm for which to group requests.


The "user" property

  "user"                     InfAdoptedUser*       : Read / Write

The user for which to group requests.

Signal Details

The "group-requests" signal

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

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

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.

See Also

InfAdoptedAlgorithm