![]() | ![]() | ![]() | DiaCanvas2 Reference Manual | ![]() |
---|
DiaHandle — Handles are used to modify objects on the canvas.
#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, constgdouble 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, constgdouble affine[6]); void dia_handle_update_i2w_affine (DiaHandle *handle, constgdouble 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);
GObject +----DiaHandle
"connectable"gboolean : Read / Write "connected-to" DiaCanvasItem : Read "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
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).
Like canvas items, handles do not handle user events themselves. Events for handles are handled by the DiaHandleTool.
The DiaHandleLayer 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
If a handle is connected to an item, it's the item who sends the connect signal, not the owner of the handle.
#define DIA_HANDLE(obj) (G_TYPE_CHECK_INSTANCE_CAST ((obj), DIA_TYPE_HANDLE, DiaHandle))
obj : |
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::
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. |
DiaHandle* dia_handle_new_with_pos (DiaCanvasItem *owner,gdouble x,gdouble y);
Create a new handle on position (x, y).
owner : | |
x : | |
y : | |
Returns : |
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 : |
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 : |
void dia_handle_set_pos_i_affine (DiaHandle *handle,gdouble x,gdouble y, constgdouble 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. |
void dia_handle_get_pos_w (DiaHandle *handle,gdouble *x,gdouble *y);
Retrieve the world coordinates of a handle.
handle : | |
x : | |
y : |
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 : |
void dia_handle_request_update_w2i (DiaHandle *handle);
Request a world to item synchronization.
handle : |
void dia_handle_update_w2i (DiaHandle *handle);
Update the item relative coordinate of handle.
handle : |
void dia_handle_update_w2i_affine (DiaHandle *handle, constgdouble affine[6]);
As dia_handle_update_w2i(), but also a transformation matrix is provided.
handle : | |
affine : |
void dia_handle_update_i2w_affine (DiaHandle *handle, constgdouble affine[6]);
Sync the item and world coordinates by changing the world coordinates.
handle : | |
affine : | item to world transformation matrix. |
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. |
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. |
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 : |
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 : |
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 : |
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 : |
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 : |
"connectable" ( |
|
"connected-to" (DiaCanvasItem : Read) |
|
"index" ( |
|
"movable" ( |
|
"owner" (DiaCanvasItem : Read / Write) |
|
"pos-i" (DiaPoint : Read / Write) |
|
"pos-w" (DiaPoint : Read / Write) |
|
"strength" (DiaStrength : Read / Write) |
|
<< DiaShape | DiaUndoManager >> |