Undo

Every modern computer program has the option to correct mistakes by means of an undo button. Of course DiaCanvas2 also needs such functionality.

Before a property of an object is changed (most like by using g_object_set()), it's original can be saved on the undo stack by calling dia_canvas_preserve_property(). This function takes as arguments the object who owns the property and the name of the property. For canvas items the function dia_canvas_item_preserve_property() can be used as a shorthand. To distinguish between atomic undo actions (for example on a mouse click), a collection of properties can be put in a stack. The stack depth is variable.

static void
dia_canvas_line_set_property (GObject *object, guint property_id,
			      const GValue *value, GParamSpec *pspec)
{
	DiaCanvasItem *item = (DiaCanvasItem*) object;
	DiaCanvasLine *line = (DiaCanvasLine*) object;

	switch (property_id) {
	case PROP_LINE_WIDTH:
		dia_canvas_item_preserve_property (item, "line_width");
		line->line_width = g_value_get_double (value);
		dia_canvas_item_request_update (DIA_CANVAS_ITEM (line));
		break;
	case PROP_COLOR:
		dia_canvas_item_preserve_property (item, "color");
		line->color = (DiaColor) g_value_get_ulong (value);
		dia_canvas_item_request_update (DIA_CANVAS_ITEM (line));
		break;
	/* ... */
	}
}

DIA_CANVAS()

#define DIA_CANVAS(obj)			(G_TYPE_CHECK_INSTANCE_CAST ((obj), DIA_TYPE_CANVAS, DiaCanvas))

DiaCanvas

typedef struct _DiaCanvas DiaCanvas;

DiaCanvas holds the data structure that represents the content that is displayed in a DiaCanvasView. One DiaCanvas can have zero or more views.

DiaCanvasIter

typedef struct {
	gpointer data[3];
	GDestroyNotify destroy_func;
	gint stamp;
} DiaCanvasIter;

dia_canvas_new ()

DiaCanvas*  dia_canvas_new                  (void);

Create a new canvas.

dia_canvas_set_extents ()

void        dia_canvas_set_extents          (DiaCanvas *canvas,
                                             const DiaRectangle *extents);

Set the boundries for the canvas. Use this in combination with the "static_extents" option.

dia_canvas_set_static_extents ()

void        dia_canvas_set_static_extents   (DiaCanvas *canvas,
                                             gboolean stat);

Set extents. Normally (with this option turned off) the boundries of the canvas will grow or shrink depending on the position of the objects (so the placement of the objects determine the actual size).

Turn this option on if you don't want the canvas to dynamically resize.

dia_canvas_set_snap_to_grid ()

void        dia_canvas_set_snap_to_grid     (DiaCanvas *canvas,
                                             gboolean snap);

Turn the snap to grid option on or off.

dia_canvas_snap_to_grid ()

void        dia_canvas_snap_to_grid         (DiaCanvas *canvas,
                                             gdouble *x,
                                             gdouble *y);

This function takes two arguments (x and y) and returnes them with a grid position. If the "snap_to_grid" option is turned off, this function does nothing.

dia_canvas_glue_handle ()

gdouble     dia_canvas_glue_handle          (DiaCanvas *canvas,
                                             const DiaHandle *handle,
                                             const gdouble dest_x,
                                             const gdouble dest_y,
                                             gdouble *glue_x,
                                             gdouble *glue_y,
                                             DiaCanvasItem **item);

Find a point to glue the handle to. Point (dest_x, dest_y) is the position where the handle should move to if no glue point is found. This can be useful if the handle is in a motion and you have to calculate the place where the handle should move to.

dia_canvas_request_update ()

void        dia_canvas_request_update       (DiaCanvas *canvas);

Ask the canvas to schedule a update handler. The actual update will happen diuring idle time or if dia_canvas_update_now() is called.

dia_canvas_update_now ()

void        dia_canvas_update_now           (DiaCanvas *canvas);

Force an update of the internat state of the canvas. This will set the canvas in a consistent state by running the update() callback of every DiaCanvasItem that requested an update.

dia_canvas_resolve_now ()

void        dia_canvas_resolve_now          (DiaCanvas *canvas);

Ask the constraint solver to resolve it's constraints.

dia_canvas_add_constraint ()

void        dia_canvas_add_constraint       (DiaCanvas *canvas,
                                             DiaConstraint *c);

Add a constraint to the canvas' constraint solver.

dia_canvas_remove_constraint ()

void        dia_canvas_remove_constraint    (DiaCanvas *canvas,
                                             DiaConstraint *c);

Remove constraint c from the canvas.

dia_canvas_redraw_views ()

void        dia_canvas_redraw_views         (DiaCanvas *canvas);

This function will emit a signal that will cause all views to update and redraw itself. There are very few cases in which this function is useful. Calling this function often will dramatically reduce the speed of the canvas.

dia_canvas_find_objects_in_rectangle ()

GList*      dia_canvas_find_objects_in_rectangle
                                            (DiaCanvas *canvas,
                                             DiaRectangle *rect);

Find all objects that are within rectangle rect and return them in a GList. The returned list should be freed by the caller. Note that the root object is not included in the selection, only non-composite leaf objects are selected.

dia_canvas_preserve ()

void        dia_canvas_preserve             (DiaCanvas *canvas,
                                             GObject *object,
                                             const char *property_name,
                                             const GValue *value,
                                             gboolean last);

Put a variable on the undo stack. The variable is described by its property_name and the undo_data.

If an object/property_name combination is preserved multiple times, only the first occurance is stored.

dia_canvas_preserve_property ()

void        dia_canvas_preserve_property    (DiaCanvas *canvas,
                                             GObject *object,
                                             const char *property_name);

This is an easy way to save properties. The value of the property is preserved so the change can be undone by dia_canvas_undo_pop().

dia_canvas_preserve_property_last ()

void        dia_canvas_preserve_property_last
                                            (DiaCanvas *canvas,
                                             GObject *object,
                                             const char *property_name);

This is a special version of dia_canvas_preserve_property(): it preserves a property, but adds it to the end of the list, in stead of the beginning. This is needed for some special actions.

This function won't be used in normal usage.

dia_canvas_push_undo ()

void        dia_canvas_push_undo            (DiaCanvas *canvas,
                                             const char *optional_comment);

Push a bunch of preserved values on the undo stack. If no values are stored using dia_canvas_preserve() or dia_canvas_preserve_property(), nothing is pushed on the stack.

dia_canvas_pop_undo ()

void        dia_canvas_pop_undo             (DiaCanvas *canvas);

Undo a set of actions. Undone actions are stored on the redo-stack, so they can be undone too.

dia_canvas_clear_undo ()

void        dia_canvas_clear_undo           (DiaCanvas *canvas);

Clear the undo stack.

dia_canvas_get_undo_depth ()

guint       dia_canvas_get_undo_depth       (DiaCanvas *canvas);

Return the amount of undo entries on the undo stack. The depth can be at most the dia_canvas_get_stack_depth() + 1 (the current undo entry).

dia_canvas_pop_redo ()

void        dia_canvas_pop_redo             (DiaCanvas *canvas);

Opposite of dia_canvas_undo_pop(). Undone actions are undone themselves ;-)

dia_canvas_clear_redo ()

void        dia_canvas_clear_redo           (DiaCanvas *canvas);

Clear the redo stack. This should be automatically done after an interactive operation on the canvas (e.g. an item is moved).

dia_canvas_get_redo_depth ()

guint       dia_canvas_get_redo_depth       (DiaCanvas *canvas);

Return the amount of undo entries on the undo stack.

dia_canvas_set_undo_stack_depth ()

void        dia_canvas_set_undo_stack_depth (DiaCanvas *canvas,
                                             guint depth);

Set a limit of the length of the undo/redo stack (default 10).

dia_canvas_get_undo_stack_depth ()

guint       dia_canvas_get_undo_stack_depth (DiaCanvas *canvas);

Get the current stack depth.

dia_canvas_iter_init ()

void        dia_canvas_iter_init            (DiaCanvasIter *iter);

Initialize the iterator iter with some neuteral values.

dia_canvas_iter_destroy ()

void        dia_canvas_iter_destroy         (DiaCanvasIter *iter);

Indicate that the iterator is no longer used. if iter->destroy_func is set, it is executed.

The "allow-state-requests" property

  "allow-state-requests" gboolean              : Read / Write

Let canvas items query their visual state (selected, focused, grabbed).

Default value: TRUE

The "allow-undo" property

  "allow-undo"           gboolean              : Read / Write

You should set this property to TRUE if you want to enable undo support (disabled by default).

Default value: FALSE

The "extents" property

  "extents"              DiaRectangle          : Read / Write

Set the boundaries for the canvas. This property depends on the static-extents property.

The "grid-bg" property

  "grid-bg"              gulong                : Read / Write

Grid background color. Note that this is also the canvas' background color.

The "grid-color" property

  "grid-color"           gulong                : Read / Write

Color of the grid points.

The "grid-int-x" property

  "grid-int-x"           gdouble               : Read / Write

Set the X interval for the grid (space between grid points).

Allowed values: >= 0

Default value: 10

The "grid-int-y" property

  "grid-int-y"           gdouble               : Read / Write

Set the Y interval for the grid.

Allowed values: >= 0

Default value: 10

The "grid-ofs-x" property

  "grid-ofs-x"           gdouble               : Read / Write

Add an addition offset to the grid points. Make sure that the offset is less than grid-int-x.

Allowed values: >= 0

Default value: 0

The "grid-ofs-y" property

  "grid-ofs-y"           gdouble               : Read / Write

Add an addition offset to the grid points. Make sure that the offset is less than grid-int-y.

Allowed values: >= 0

Default value: 0

The "pango-layout" property

  "pango-layout"         PangoLayout           : Read

A newly created pango layout.

The "snap-to-grid" property

  "snap-to-grid"         gboolean              : Read / Write

Turns on and off the snap to grid option.

Default value: FALSE

The "static-extents" property

  "static-extents"       gboolean              : Read / Write

Tell the canvas to have static events (the size of the canvas does not change) or dynamic extents (the size of the canvas depends on the position of the items on the canvas.

Default value: FALSE

The "extents-changed" signal

void        user_function                  (DiaCanvas *diacanvas,
                                            gpointer arg1,
                                            gpointer user_data);

The "redraw-view" signal

void        user_function                  (DiaCanvas *diacanvas,
                                            gpointer user_data);

Request all views to redraw themselves.

The "undo" signal

void        user_function                  (DiaCanvas *diacanvas,
                                            gpointer user_data);