Undo framework

["Iain *" <iaingnome gmail com>]

Hi,

I've had an undo framework in Marlin for years now, but recently
people have been using it in other things (notably Ross in Tasks - ok,
actually, he's the only one) and we discussed suggesting this for
inclusion in GTK at some point in the future. QT4[1] and Cocoa[2] both
have very similar frameworks. Attached are the header files.

The basic concepts are that there is an UndoManager object. When you
start an operation that can be undone you call
undo_manger_context_begin and this returns a UndoContext. Each part of
your operation then creates an Undoable setting the functions that
undo, redo and destroy it and set some userdata which contains enough
information to undo/redo it. These Undoables are then added to the
UndoContext. When the operation is finished you call
undo_manager_context_end which adds the operation to the undo/redo
stack.

The idea of having the smaller Undoables is to allow complex
operations to be built up from smaller ones. For example, in Marlin
muting a section of a sample is made up from a Delete and an Insert
Silence operation, but we want this to be presented to the user as a
single "Undo Mute Sample" operation rather than two: "Undo Insert
Silence" & "Undo Delete"

Ross has also written GtkActions for Undo/Redo which hook into the
UndoManager and provide menu and toolbar actions that just Do The
Right Thing. The menus have "Undo 'Mute Sample'" and "Redo 'Mute
Sample'" and the text changes as appropriate.

He has also written a GtkEntry subclass that has undo/redo
capabilities, and if/when this gets into GTK proper, we will hook it
into the GtkEntry/GtkTextView stuff as well. In these cases, each
widget would have its own UndoManager, so that the text entry changes
could be undone separatly from the main program's undo stack.

We can add this to libegg until people play with it a bit more and
find the various issues, but its been in Marlin for 3 years and seems
to work, but all comments and thoughts are welcome.

iain

[1] http://doc.trolltech.com/4.2/qundo.html#undo-framework
[2] http://developer.apple.com/documentation/Cocoa/Conceptual/UndoArchitecture/index.html

/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
 *  Authors: Iain Holmes <iain gnome org>
 *
 *  Copyright 2002 - 2007 Iain Holmes
 *
 *  This file is free software; you can redistribute it and/or
 *  modify it under the terms of version 2 of the GNU Library General Public
 *  License as published by the Free Software Foundation;
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public
 *  License along with this library; if not, write to the
 *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *  Boston, MA 02111-1307, USA.
 *
 */

#ifndef __EGG_UNDO_MANAGER_H__
#define __EGG_UNDO_MANAGER_H__

#include <glib-object.h>
#include <glib.h>

#include <undo-manager/egg-undoable.h>

G_BEGIN_DECLS

#define EGG_TYPE_UNDO_MANAGER (egg_undo_manager_get_type ())
#define EGG_UNDO_MANAGER(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), EGG_TYPE_UNDO_MANAGER, EggUndoManager))
#define EGG_UNDO_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), EGG_TYPE_UNDO_MANAGER, EggUndoManagerClass))
#define EGG_IS_UNDO_MANAGER(obj) (G_TYPE_CHECK_INSTANCE_TYPE ((obj), EGG_TYPE_UNDO_MANAGER))
#define EGG_IS_UNDO_MANAGER_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), EGG_TYPE_UNDO_MANAGER))
#define EGG_UNDO_MANAGER_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), EGG_TYPE_UNDO_MANAGER, EggUndoManagerClass))

typedef struct _EggUndoContext EggUndoContext;
typedef struct _EggUndoHistory {
	char *name;
	char *info;

	gboolean current; /* Is this the position we are at in the history */
	EggUndoContext *ctxt; 
} EggUndoHistory;

typedef struct _EggUndoManager EggUndoManager;
typedef struct _EggUndoManagerClass EggUndoManagerClass;

struct _EggUndoManager {
	GObject object;
};

struct _EggUndoManagerClass {
	GObjectClass parent_class;

	void (*changed) (EggUndoManager *manager);
};

GType egg_undo_manager_get_type (void);
EggUndoManager *egg_undo_manager_new (guint size);

gboolean egg_undo_manager_can_undo (EggUndoManager *manager);
gboolean egg_undo_manager_can_redo (EggUndoManager *manager);

EggUndoContext *egg_undo_manager_context_begin (EggUndoManager *manager,
						const char *name);
void egg_undo_manager_context_end (EggUndoManager *manager,
				   EggUndoContext *ctxt);
void egg_undo_manager_context_cancel (EggUndoManager *manager,
				      EggUndoContext *ctxt);

void egg_undo_context_add (EggUndoContext *context,
			   EggUndoable *undoable);
const char *egg_undo_manager_get_undo_name (EggUndoManager *manager);
const char *egg_undo_manager_get_redo_name (EggUndoManager *manager);

void egg_undo_manager_undo (EggUndoManager *manager);
void egg_undo_manager_redo (EggUndoManager *manager);

GList *egg_undo_manager_get_history (EggUndoManager *manager);

G_END_DECLS

#endif

/* -*- Mode: C; tab-width: 8; indent-tabs-mode: t; c-basic-offset: 8 -*- */
/*
 *  Authors: Iain Holmes <iain gnome org>
 *
 *  Copyright 2002 - 2007 Iain Holmes
 *
 *  This file is free software; you can redistribute it and/or
 *  modify it under the terms of version 2 of the GNU Library General Public
 *  License as published by the Free Software Foundation;
 *
 *  This library is distributed in the hope that it will be useful,
 *  but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  Library General Public License for more details.
 *
 *  You should have received a copy of the GNU Library General Public
 *  License along with this library; if not, write to the
 *  Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 *  Boston, MA 02111-1307, USA.
 *
 */

#ifndef __EGG_UNDOABLE_H__
#define __EGG_UNDOABLE_H__

#include <glib.h>

G_BEGIN_DECLS

typedef void (*EggUndoableFunc) (gpointer closure);

typedef struct _EggUndoable {
	/* The functions that will undo/redo the action if they are passed
	 * the data packet that is stored in closure */
	EggUndoableFunc undo; 
	EggUndoableFunc redo; 
	EggUndoableFunc destroy;

	gpointer closure; /* This is enough data for the undo/redo functions
			     to perform their actions */
} EggUndoable;

EggUndoable *egg_undoable_new (EggUndoableFunc undo,
			       EggUndoableFunc redo,
			       EggUndoableFunc destroy,
			       gpointer closure);
void egg_undoable_free (EggUndoable *undoable);
void egg_undoable_undo (EggUndoable *undoable);
void egg_undoable_redo (EggUndoable *undoable);

G_END_DECLS

#endif