Tools

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

Synopsis




            DiaTool;
            DiaPlacementTool;
DiaTool*    dia_placement_tool_new          (GType object_type,
                                             const gchar *first_property_name,
                                             ...);
            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);
            DiaDefaultTool;
DiaTool*    dia_default_tool_new            (void);
            DiaHandleTool;
DiaTool*    dia_handle_tool_new             (void);
            DiaItemTool;
DiaTool*    dia_item_tool_new               (void);
            DiaSelectionTool;
DiaTool*    dia_selection_tool_new          (void);

Object Hierarchy


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

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

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

Signals


"button-press-event"
            gboolean    user_function      (DiaTool        *diatool,
                                            DiaCanvasView  *arg1,
                                            GdkEventButton *event,
                                            gpointer        user_data)      : Run last
"button-release-event"
            gboolean    user_function      (DiaTool        *diatool,
                                            DiaCanvasView  *arg1,
                                            GdkEventButton *event,
                                            gpointer        user_data)      : Run last
"key-press-event"
            gboolean    user_function      (DiaTool       *diatool,
                                            DiaCanvasView *arg1,
                                            GdkEventKey   *event,
                                            gpointer       user_data)      : Run last
"key-release-event"
            gboolean    user_function      (DiaTool       *diatool,
                                            DiaCanvasView *arg1,
                                            GdkEventKey   *event,
                                            gpointer       user_data)      : Run last
"motion-notify-event"
            gboolean    user_function      (DiaTool        *diatool,
                                            DiaCanvasView  *arg1,
                                            GdkEventMotion *event,
                                            gpointer        user_data)      : 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

DiaTool

typedef struct _DiaTool DiaTool;


DiaPlacementTool

typedef struct _DiaPlacementTool 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

DiaStackTool

typedef struct _DiaStackTool DiaStackTool;


dia_stack_tool_new ()

DiaTool*    dia_stack_tool_new              (void);

Returns :

dia_stack_tool_push ()

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

stack_tool :
tool :

dia_stack_tool_pop ()

void        dia_stack_tool_pop              (DiaStackTool *stack_tool);

stack_tool :

DiaDefaultTool

typedef struct {
	DiaTool object;

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

	DiaTool *current_tool;
} DiaDefaultTool;

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

Returns :

DiaHandleTool

typedef struct {
	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;
} DiaHandleTool;

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

Returns :

DiaItemTool

typedef struct {
	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;
} DiaItemTool;

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

Returns :

DiaSelectionTool

typedef struct {
	DiaTool object;

	GnomeCanvasItem *selector;
} DiaSelectionTool;

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


dia_selection_tool_new ()

DiaTool*    dia_selection_tool_new          (void);

Returns :

Signal Details

The "button-press-event" signal

gboolean    user_function                  (DiaTool        *diatool,
                                            DiaCanvasView  *arg1,
                                            GdkEventButton *event,
                                            gpointer        user_data)      : Run last

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

The "button-release-event" signal

gboolean    user_function                  (DiaTool        *diatool,
                                            DiaCanvasView  *arg1,
                                            GdkEventButton *event,
                                            gpointer        user_data)      : Run last

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

The "key-press-event" signal

gboolean    user_function                  (DiaTool       *diatool,
                                            DiaCanvasView *arg1,
                                            GdkEventKey   *event,
                                            gpointer       user_data)      : Run last

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

The "key-release-event" signal

gboolean    user_function                  (DiaTool       *diatool,
                                            DiaCanvasView *arg1,
                                            GdkEventKey   *event,
                                            gpointer       user_data)      : Run last

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

The "motion-notify-event" signal

gboolean    user_function                  (DiaTool        *diatool,
                                            DiaCanvasView  *arg1,
                                            GdkEventMotion *event,
                                            gpointer        user_data)      : Run last

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

See Also

DiaCanvasView