DiaHandle

DiaHandle — Handles are used to modify objects on the canvas.

Synopsis




#define     DIA_HANDLE                      (obj)
struct      DiaHandle;
DiaHandle*  dia_handle_new                  (DiaCanvasItem *owner);
DiaHandle*  dia_handle_new_with_pos         (DiaCanvasItem *owner,
                                             gdouble x,
                                             gdouble y);
void        dia_handle_get_pos_i            (DiaHandle *handle,
                                             gdouble *x,
                                             gdouble *y);
void        dia_handle_set_pos_i            (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);
void        dia_handle_set_pos_i_affine     (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y,
                                             const gdouble affine[6]);
void        dia_handle_get_pos_w            (DiaHandle *handle,
                                             gdouble *x,
                                             gdouble *y);
void        dia_handle_set_pos_w            (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);
void        dia_handle_request_update_w2i   (DiaHandle *handle);
void        dia_handle_update_w2i           (DiaHandle *handle);
void        dia_handle_update_w2i_affine    (DiaHandle *handle,
                                             const gdouble affine[6]);
void        dia_handle_update_i2w_affine    (DiaHandle *handle,
                                             const gdouble affine[6]);
gdouble     dia_handle_distance_i           (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);
gdouble     dia_handle_distance_w           (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);
void        dia_handle_set_strength         (DiaHandle *handle,
                                             DiaStrength strength);
void        dia_handle_add_constraint       (DiaHandle *handle,
                                             DiaConstraint *c);
void        dia_handle_add_line_constraint  (DiaHandle *begin,
                                             DiaHandle *end,
                                             DiaHandle *middle);
void        dia_handle_remove_constraint    (DiaHandle *handle,
                                             DiaConstraint *c);
void        dia_handle_remove_all_constraints
                                            (DiaHandle *handle);
gint        dia_handle_size                 (void);

Object Hierarchy


  GObject
   +----DiaHandle

Properties


  "connect"              DiaCanvasItem        : Read / Write
  "connectable"          gboolean             : Read / Write
  "connected-to"         DiaCanvasItem        : Read
  "disconnect"           DiaCanvasItem        : Read / Write
  "index"                gint                 : Read / Write
  "movable"              gboolean             : Read / Write
  "owner"                DiaCanvasItem        : Read / Write
  "pos-i"                DiaPoint             : Read / Write
  "pos-w"                DiaPoint             : Read / Write
  "strength"             DiaStrength          : Read / Write

Description

Handles serve a lot of purposes. They are an important part of the DiaCanvas. First of all they tell the user which objects are selected and which object has the focus. Selected objects have visible handles and the focused object has brighter handles than the selected objects.

Handles are also visible, even if the object itself is hidden behind some other object. This makes it possible to know where an object is located, even if you can't see the actual object.

Handles can be used to modify the object. For a line, for example, it is a good thing to have a handle on every corner. Moving a corner is done by moving the handle that defines that corner. On box-like objects handles can be used to resize and rotate the object.

One of the nicest properties of a handle is the ability to let one object connect to another object. If a handle is set to connectable (the handle has a small cross drawn inside), it will try to connect to the object most nearby. Connections are established and linear constraints are created to keep objects also visually connected (if a box moves, also the line-end connected to it should move, see DiaSolver).

Handles, however, are dumb objects: they do not handle user interaction themselves. Instead a DiaHandleLayer is added on top of every view. The handle layer takes care of drawing the handles and it also handles the events (this ensures that handles always receive events first). The owner of the handle (a DiaCanvasItem) is notified when a handle is moved. It is the handles owner that controls the movement of the handle by means of the handle_motion() callback function.

If a handle is connected to an item, it's the item who sends the connect signal, not the owner of the handle.

Details

DIA_HANDLE()

#define DIA_HANDLE(obj)			(G_TYPE_CHECK_INSTANCE_CAST ((obj), DIA_TYPE_HANDLE, DiaHandle))

obj :

struct DiaHandle

struct DiaHandle;

A handle is a special element in a Dia like canvas. Handles are used to modify the object (e.g. move a point) and to connect one element to another element. A handle does not grow/shrink if you zoom in/out.

A handle supports two coordinate systems: the item and the "world" (root item). If the item's position is changed, the world coordinates are updated immediately. If the world coordinates are changed (for example if the user drags a handle), the world to item update is delayed and taken care of by the DiaCanvasItem::update() function.


dia_handle_new ()

DiaHandle*  dia_handle_new                  (DiaCanvasItem *owner);

Create a new handle on position (0.0, 0.0). The handle is owner by owner.

owner : DiaCanvasItem owning the handle.
Returns : A borrowed reference to the newly created handle.

dia_handle_new_with_pos ()

DiaHandle*  dia_handle_new_with_pos         (DiaCanvasItem *owner,
                                             gdouble x,
                                             gdouble y);

Create a new handle on position (x, y).

owner :
x :
y :
Returns :

dia_handle_get_pos_i ()

void        dia_handle_get_pos_i            (DiaHandle *handle,
                                             gdouble *x,
                                             gdouble *y);

Get the item relative position of the handle. If the handle needs a world->item update, that is done first.

handle :
x :
y :

dia_handle_set_pos_i ()

void        dia_handle_set_pos_i            (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);

Set a new position in item relative coordinates and request for an update.

handle :
x :
y :

dia_handle_set_pos_i_affine ()

void        dia_handle_set_pos_i_affine     (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y,
                                             const gdouble affine[6]);

Set the position of the handle, in item relative coordinates.

handle :
x : new x position, in item coordinates.
y : new y position, in item coordinates.
affine : Item to world transforation matrix.

dia_handle_get_pos_w ()

void        dia_handle_get_pos_w            (DiaHandle *handle,
                                             gdouble *x,
                                             gdouble *y);

Retrieve the world coordinates of a handle.

handle :
x :
y :

dia_handle_set_pos_w ()

void        dia_handle_set_pos_w            (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);

Assign handle a new position in world coordinates. All items that requested a item to world update will be updated also.

handle :
x :
y :

dia_handle_request_update_w2i ()

void        dia_handle_request_update_w2i   (DiaHandle *handle);

Request a world to item synchronization.

handle :

dia_handle_update_w2i ()

void        dia_handle_update_w2i           (DiaHandle *handle);

Update the item relative coordinate of handle.

handle :

dia_handle_update_w2i_affine ()

void        dia_handle_update_w2i_affine    (DiaHandle *handle,
                                             const gdouble affine[6]);

As dia_handle_update_w2i(), but also a transformation matrix is provided.

handle :
affine :

dia_handle_update_i2w_affine ()

void        dia_handle_update_i2w_affine    (DiaHandle *handle,
                                             const gdouble affine[6]);

Sync the item and world coordinates by changing the world coordinates.

handle :
affine : item to world transformation matrix.

dia_handle_distance_i ()

gdouble     dia_handle_distance_i           (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);

Calculate the distance from (x, y) to the handle. Note that the handle is internally represented as a point rather than a rectangle (it is visualized as a rectangle).

handle :
x :
y :
Returns : The calculated distance.

dia_handle_distance_w ()

gdouble     dia_handle_distance_w           (DiaHandle *handle,
                                             gdouble x,
                                             gdouble y);

Calculate the distance from one point to the handle, using manhattan calculation.

handle :
x : x position relative to the root canvas item.
y : y position relative to the root canvas item.
Returns : The distance.

dia_handle_set_strength ()

void        dia_handle_set_strength         (DiaHandle *handle,
                                             DiaStrength strength);

Set the strength of the handle. A strong handle is less likely to move than a weak handle.

handle :
strength :

dia_handle_add_constraint ()

void        dia_handle_add_constraint       (DiaHandle *handle,
                                             DiaConstraint *c);

Add constraint c to the handle. The constraint should be used to connect the handle to another object than its owner.

The constraint will automatically be removed if the handle is disconnected.

handle :
c :

dia_handle_add_line_constraint ()

void        dia_handle_add_line_constraint  (DiaHandle *begin,
                                             DiaHandle *end,
                                             DiaHandle *middle);

Create constraints for middle. middle should be between begin and end. The constraints will let middle stay on the line. If begin or end moves, middle is kept there.

begin :
end :
middle :

dia_handle_remove_constraint ()

void        dia_handle_remove_constraint    (DiaHandle *handle,
                                             DiaConstraint *c);

remove c from the handle. If c does not exist in handle's context, a warning is issued.

handle :
c :

dia_handle_remove_all_constraints ()

void        dia_handle_remove_all_constraints
                                            (DiaHandle *handle);

Remove all constraints from handle. This is typically done if a DiaCanvasItem is disconnected from another DiaCanvasItem.

handle :

dia_handle_size ()

gint        dia_handle_size                 (void);

Return the size of a handle (currently 9).

Returns :

Properties

"connect" (DiaCanvasItem : Read / Write)

"connectable" (gboolean : Read / Write)

"connected-to" (DiaCanvasItem : Read)

"disconnect" (DiaCanvasItem : Read / Write)

"index" (gint : Read / Write)

"movable" (gboolean : Read / Write)

"owner" (DiaCanvasItem : Read / Write)

"pos-i" (DiaPoint : Read / Write)

"pos-w" (DiaPoint : Read / Write)

"strength" (DiaStrength : Read / Write)

See Also

DiaCanvasItem, DiaCanvasView, DiaHandleLayer, DiaSolver