Tools

Tools — Tools are used to add behavior to a canvas view.

Synopsis

struct              DiaTool;
struct              DiaPlacementTool;
DiaTool *           dia_placement_tool_new              (GType object_type,
                                                         const gchar *first_property_name,
                                                         ...);
struct              DiaStackTool;
DiaTool *           dia_stack_tool_new                  (void);
void                dia_stack_tool_push                 (DiaStackTool *stack_tool,
                                                         DiaTool *tool);
void                dia_stack_tool_pop                  (DiaStackTool *stack_tool);
struct              DiaDefaultTool;
DiaTool *           dia_default_tool_new                (void);
struct              DiaHandleTool;
DiaTool *           dia_handle_tool_new                 (void);
struct              DiaItemTool;
DiaTool *           dia_item_tool_new                   (void);
struct              DiaSelectionTool;
DiaTool *           dia_selection_tool_new              (void);

Object Hierarchy

  GObject
   +----DiaTool
         +----DiaPlacementTool
         +----DiaStackTool
  GObject
   +----DiaTool
         +----DiaPlacementTool
  GObject
   +----DiaTool
         +----DiaStackTool

Signals

  "button-press-event"                             : Run Last
  "button-release-event"                           : Run Last
  "key-press-event"                                : Run Last
  "key-release-event"                              : Run Last
  "motion-notify-event"                            : Run Last

Description

A canvas is no fun if users can't modify it. Behavior is added using Tools.

A tool can be set on a view using dia_canvas_view_set_tool(). If no tool tool is set the view will fall back on the default tool. This is the tool that adds default behavior to a canvas view, such as selecting items and moving items. The default behavior of the canvas view is defined by DiaDefaultTool. This tool makes use of DiaHandleTool, DiaItemTool and DiaSelectionTool.

Details

struct DiaTool

struct DiaTool;


struct DiaPlacementTool

struct DiaPlacementTool;

This is the default tool for object placement. You can give extra options to the constructor. Those options will be passed to the object constructor.


dia_placement_tool_new ()

DiaTool *           dia_placement_tool_new              (GType object_type,
                                                         const gchar *first_property_name,
                                                         ...);

Create a new placement tool for an item of type object_type.

object_type :

GType of the item

first_property_name :

the name of the first property

... :

the value of the first property, followed optionally by more name/value pairs, followed by NULL

Returns :

The new placement tool, or NULL if an error occured

struct DiaStackTool

struct DiaStackTool;


dia_stack_tool_new ()

DiaTool *           dia_stack_tool_new                  (void);


dia_stack_tool_push ()

void                dia_stack_tool_push                 (DiaStackTool *stack_tool,
                                                         DiaTool *tool);


dia_stack_tool_pop ()

void                dia_stack_tool_pop                  (DiaStackTool *stack_tool);


struct DiaDefaultTool

struct DiaDefaultTool {
	DiaTool object;

	DiaTool *handle_tool;
	DiaTool *selection_tool;
	DiaTool *item_tool;

	DiaTool *current_tool;
};

This tool provides the default behavior for the DiaCanvasView. It first checks if a users has clicked on a handle. If no handle was selected there might be a canvas item selected. If that is not the case either, a rubberband selection is started.

This tool delegates its events to DiaHandleTool, DiaItemTool and DiaSelectionTool.


dia_default_tool_new ()

DiaTool *           dia_default_tool_new                (void);


struct DiaHandleTool

struct DiaHandleTool {
	DiaTool object;

	/* Amount of pixels that should maximal be used when glue()-ing */
	gint glue_distance;
	
	DiaHandle *grabbed_handle;

	/* This is the item the handle will connect to on a BUTTON_RELEASE. */
	DiaCanvasItem *connect_to;

	DiaEventMask event_mask;
};

This tool works on the handles (DiaHandle) of items. If the user clicks on a handle, the handle is selected and can be moved.


dia_handle_tool_new ()

DiaTool *           dia_handle_tool_new                 (void);


struct DiaItemTool

struct DiaItemTool {
	DiaTool object;

	/* current_item is the item that was found on a button press event.
	 */
	DiaCanvasViewItem *current_item;

	DiaCanvasViewItem *grabbed_item;

	gdouble old_x, old_y;
};

The Item tool handles events that affect the items on the canvas (not their handles, those events are handles by DiaHandleTool). This tool handles the selection of items, what happens when an item is double-clicked, etc.


dia_item_tool_new ()

DiaTool *           dia_item_tool_new                   (void);


struct DiaSelectionTool

struct DiaSelectionTool {
	DiaTool object;

	GnomeCanvasItem *selector;
};

This tool resembles the behavior of a selection box for rubberband selection.


dia_selection_tool_new ()

DiaTool *           dia_selection_tool_new              (void);

Signal Details

The "button-press-event" signal

gboolean            user_function                      (DiaTool       *diatool,
                                                        DiaCanvasView *arg1,
                                                        GdkEvent      *arg2,
                                                        gpointer       user_data)      : Run Last

diatool :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "button-release-event" signal

gboolean            user_function                      (DiaTool       *diatool,
                                                        DiaCanvasView *arg1,
                                                        GdkEvent      *arg2,
                                                        gpointer       user_data)      : Run Last

diatool :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "key-press-event" signal

gboolean            user_function                      (DiaTool       *diatool,
                                                        DiaCanvasView *arg1,
                                                        GdkEvent      *arg2,
                                                        gpointer       user_data)      : Run Last

diatool :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "key-release-event" signal

gboolean            user_function                      (DiaTool       *diatool,
                                                        DiaCanvasView *arg1,
                                                        GdkEvent      *arg2,
                                                        gpointer       user_data)      : Run Last

diatool :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

The "motion-notify-event" signal

gboolean            user_function                      (DiaTool       *diatool,
                                                        DiaCanvasView *arg1,
                                                        GdkEvent      *arg2,
                                                        gpointer       user_data)      : Run Last

diatool :

the object which received the signal.

user_data :

user data set when the signal handler was connected.

See Also

DiaCanvasView