DiaCanvas

DiaCanvas — Class that holds the canvas model.

Synopsis




#define     DIA_CANVAS                      (obj)
struct      DiaCanvas;
struct      DiaCanvasIter;
DiaCanvas*  dia_canvas_new                  (void);
void        dia_canvas_set_extents          (DiaCanvas *canvas,
                                             const DiaRectangle *extents);
void        dia_canvas_set_static_extents   (DiaCanvas *canvas,
                                             gboolean stat);
void        dia_canvas_set_snap_to_grid     (DiaCanvas *canvas,
                                             gboolean snap);
void        dia_canvas_snap_to_grid         (DiaCanvas *canvas,
                                             gdouble *x,
                                             gdouble *y);
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);
void        dia_canvas_request_update       (DiaCanvas *canvas);
void        dia_canvas_update_now           (DiaCanvas *canvas);
void        dia_canvas_resolve_now          (DiaCanvas *canvas);
void        dia_canvas_add_constraint       (DiaCanvas *canvas,
                                             DiaConstraint *c);
void        dia_canvas_remove_constraint    (DiaCanvas *canvas,
                                             DiaConstraint *c);
void        dia_canvas_redraw_views         (DiaCanvas *canvas);
GList*      dia_canvas_find_objects_in_rectangle
                                            (DiaCanvas *canvas,
                                             DiaRectangle *rect);
void        dia_canvas_preserve             (DiaCanvas *canvas,
                                             GObject *object,
                                             const char *property_name,
                                             const GValue *value,
                                             gboolean last);
void        dia_canvas_preserve_property    (DiaCanvas *canvas,
                                             GObject *object,
                                             const char *property_name);
void        dia_canvas_preserve_property_last
                                            (DiaCanvas *canvas,
                                             GObject *object,
                                             const char *property_name);
void        dia_canvas_push_undo            (DiaCanvas *canvas,
                                             const char *optional_comment);
void        dia_canvas_pop_undo             (DiaCanvas *canvas);
void        dia_canvas_clear_undo           (DiaCanvas *canvas);
guint       dia_canvas_get_undo_depth       (DiaCanvas *canvas);
void        dia_canvas_pop_redo             (DiaCanvas *canvas);
void        dia_canvas_clear_redo           (DiaCanvas *canvas);
guint       dia_canvas_get_redo_depth       (DiaCanvas *canvas);
void        dia_canvas_set_undo_stack_depth (DiaCanvas *canvas,
                                             guint depth);
guint       dia_canvas_get_undo_stack_depth (DiaCanvas *canvas);
void        dia_canvas_iter_init            (DiaCanvasIter *iter);
void        dia_canvas_iter_destroy         (DiaCanvasIter *iter);

Object Hierarchy


  GObject
   +----DiaCanvas

Properties


  "allow-state-requests" gboolean             : Read / Write
  "allow-undo"           gboolean             : Read / Write
  "extents"              DiaRectangle         : Read / Write
  "grid-bg"              gulong               : Read / Write
  "grid-color"           gulong               : Read / Write
  "grid-int-x"           gdouble              : Read / Write
  "grid-int-y"           gdouble              : Read / Write
  "grid-ofs-x"           gdouble              : Read / Write
  "grid-ofs-y"           gdouble              : Read / Write
  "pango-layout"         PangoLayout          : Read
  "snap-to-grid"         gboolean             : Read / Write
  "static-extents"       gboolean             : Read / Write

Signal Prototypes


"extents-changed"
            void        user_function      (DiaCanvas *diacanvas,
                                            gpointer arg1,
                                            gpointer user_data);
"redraw-view"
            void        user_function      (DiaCanvas *diacanvas,
                                            gpointer user_data);
"undo"      void        user_function      (DiaCanvas *diacanvas,
                                            gpointer user_data);

Description

A DiaCanvas object holds the contents of the canvas. The actual objects on the canvas are represented by DiaCanvasItem objects. The DiaCanvas itself only holds the upper most canvas item and it holds some generic properties, like grid information and undo information. A constraint solver (DiaSolver) is also placed in the DiaCanvas class.

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.

Example 1. Undo example from dia-canvas-line.c

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;
	/* ... */
	}
}

Details

DIA_CANVAS()

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

obj :

struct DiaCanvas

struct DiaCanvas;

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


struct DiaCanvasIter

struct DiaCanvasIter {

	gpointer data[3];
	GDestroyNotify destroy_func;
	gint stamp;
};


dia_canvas_new ()

DiaCanvas*  dia_canvas_new                  (void);

Create a new canvas.

Returns : 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.

canvas :
extents : new extents for the canvas.

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.

canvas :
stat : Turn static extents on (TRUE) or off (FALSE).

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.

canvas :
snap : Turn snap on (TRUE) or off (FALSE).

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.

canvas :
x : X pos to be snapped.
y : Y pos to be snapped.

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.

canvas : Canvas to find a connection point on.
handle : Handle to be glued to an item somewhere on the canvas.
dest_x : (to be) position of the handle.
dest_y :
glue_x : [OUT] closest glue point.
glue_y : [OUT] ,,
item : [OUT] The item the handle should connect() to.
Returns : The distance from the handle to the closest connection point.

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.

canvas :

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.

canvas :

dia_canvas_resolve_now ()

void        dia_canvas_resolve_now          (DiaCanvas *canvas);

Ask the constraint solver to resolve it's constraints.

canvas :

dia_canvas_add_constraint ()

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

Add a constraint to the canvas' constraint solver.

canvas :
c : Constraint to add

dia_canvas_remove_constraint ()

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

Remove constraint c from the canvas.

canvas :
c : Constraint to be removed.

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.

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.

canvas :
rect : A rectangle that determines the boundries in which objects should live.
Returns : A list of objects that are within the rectangle.

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.

canvas :
object : object that should be undone
property_name : static const string for a property (should NOT be freed!)
value : data to be undone
last : append rather than prepend the property.

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

canvas :
object :
property_name : Property to preserve

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.

canvas :
object :
property_name :

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.

canvas :
optional_comment : An optional comment. May be NULL.

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.

canvas :

dia_canvas_clear_undo ()

void        dia_canvas_clear_undo           (DiaCanvas *canvas);

Clear the undo stack.

canvas :

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

canvas :
Returns :

dia_canvas_pop_redo ()

void        dia_canvas_pop_redo             (DiaCanvas *canvas);

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

canvas :

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

canvas :

dia_canvas_get_redo_depth ()

guint       dia_canvas_get_redo_depth       (DiaCanvas *canvas);

Return the amount of undo entries on the undo stack.

canvas :
Returns :

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

canvas :
depth : New depth for the undo/redo stack.

dia_canvas_get_undo_stack_depth ()

guint       dia_canvas_get_undo_stack_depth (DiaCanvas *canvas);

Get the current stack depth.

canvas :
Returns :

dia_canvas_iter_init ()

void        dia_canvas_iter_init            (DiaCanvasIter *iter);

Initialize the iterator iter with some neuteral values.

iter :

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.

iter :

Properties

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

"allow-undo" (gboolean : Read / Write)

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

"extents" (DiaRectangle : Read / Write)

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

"grid-bg" (gulong : Read / Write)

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

"grid-color" (gulong : Read / Write)

Color of the grid points.

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

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

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

Set the Y interval for the grid.

"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.

"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.

"pango-layout" (PangoLayout : Read)

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

Turns on and off the snap to grid option.

"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.

Signals

The "extents-changed" signal

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

diacanvas :the object which received the signal.
arg1 :
user_data :user data set when the signal handler was connected.

The "redraw-view" signal

void        user_function                  (DiaCanvas *diacanvas,
                                            gpointer user_data);

Request all views to redraw themselves.

diacanvas :the object which received the signal.
user_data :user data set when the signal handler was connected.

The "undo" signal

void        user_function                  (DiaCanvas *diacanvas,
                                            gpointer user_data);

diacanvas :the object which received the signal.
user_data :user data set when the signal handler was connected.

See Also

DiaCanvasItem, DiaCanvasView