Clutter.DragAction¶

Subclasses:: None

Methods¶

Inherited:: Clutter.ActorMeta (5), GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`get_drag_area` ()
	`get_drag_axis` ()
	`get_drag_handle` ()
	`get_drag_threshold` ()
	`get_motion_coords` ()
	`get_press_coords` ()
	`set_drag_area` (drag_area)
	`set_drag_axis` (axis)
	`set_drag_handle` (handle)
	`set_drag_threshold` (x_threshold, y_threshold)

Virtual Methods¶

Inherited:: Clutter.ActorMeta (1), GObject.Object (7)

	`do_drag_begin` (actor, event_x, event_y, modifiers)
	`do_drag_end` (actor, event_x, event_y, modifiers)
	`do_drag_motion` (actor, delta_x, delta_y)
	`do_drag_progress` (actor, delta_x, delta_y)

Properties¶

Inherited:: Clutter.ActorMeta (3)

Name	Type	Flags	Short Description
`drag-area`	`Clutter.Rect`	r/w	Constrains the dragging to a rectangle
`drag-area-set`	`bool`	r	Whether the drag area is set
`drag-axis`	`Clutter.DragAxis`	r/w	Constraints the dragging to an axis
`drag-handle`	`Clutter.Actor`	r/w	The actor that is being dragged
`x-drag-threshold`	`int`	r/w	The horizontal amount of pixels required to start dragging
`y-drag-threshold`	`int`	r/w	The vertical amount of pixels required to start dragging

Signals¶

Inherited:: GObject.Object (1)

Name	Short Description
`drag-begin`	The `::drag-begin` signal is emitted when the `Clutter.DragAction` starts the dragging The emission of this signal can be delayed by using the `Clutter.DragAction` `:x-drag-threshold` and `Clutter.DragAction` `:y-drag-threshold` properties
`drag-end`	The `::drag-end` signal is emitted at the end of the dragging, when the pointer button’s is released This signal is emitted if and only if the `Clutter.DragAction` `::drag-begin` signal has been emitted first
`drag-motion`	The `::drag-motion` signal is emitted for each motion event after the `Clutter.DragAction` `::drag-begin` signal has been emitted.
`drag-progress`	The `::drag-progress` signal is emitted for each motion event after the `Clutter.DragAction` `::drag-begin` signal has been emitted.

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
parent_instance	`Clutter.Action`	r

Class Details¶

class Clutter.DragAction(**kwargs)¶

Bases:: Clutter.Action
Abstract:: No
Structure:: Clutter.DragActionClass

The Clutter.DragAction structure contains only private data and should be accessed using the provided API

New in version 1.4.

classmethod new()¶

Returns:: the newly created Clutter.DragAction
Return type:: Clutter.Action

Creates a new Clutter.DragAction instance

New in version 1.4.

get_drag_area()¶

Returns:

True if the actor is actually constrained (and thus drag_area is valid), False otherwise

drag_area:: a Clutter.Rect to be filled

Return type:

(bool, drag_area: Clutter.Rect)

Retrieves the “drag area” associated with self, that is a Clutter.Rect that constrains the actor movements, in parents coordinates.

get_drag_axis()¶

Returns:: the axis constraint
Return type:: Clutter.DragAxis

Retrieves the axis constraint set by Clutter.DragAction.set_drag_axis()

New in version 1.4.

get_drag_handle()¶

Returns:: a Clutter.Actor, used as the drag handle, or None if none was set
Return type:: Clutter.Actor

Retrieves the drag handle set by Clutter.DragAction.set_drag_handle()

New in version 1.4.

get_drag_threshold()¶

Returns:

x_threshold:: return location for the horizontal drag threshold value, in pixels
y_threshold:: return location for the vertical drag threshold value, in pixels

Return type:

(x_threshold: int, y_threshold: int)

Retrieves the values set by Clutter.DragAction.set_drag_threshold().

If the Clutter.DragAction :x-drag-threshold property or the Clutter.DragAction :y-drag-threshold property have been set to -1 then this function will return the default drag threshold value as stored by the Clutter.Settings :dnd-drag-threshold property of Clutter.Settings.

New in version 1.4.

get_motion_coords()¶

Returns:

motion_x:: return location for the latest motion event’s X coordinate
motion_y:: return location for the latest motion event’s Y coordinate

Return type:

(motion_x: float, motion_y: float)

Retrieves the coordinates, in stage space, of the latest motion event during the dragging

New in version 1.4.

get_press_coords()¶

Returns:

press_x:: return location for the press event’s X coordinate
press_y:: return location for the press event’s Y coordinate

Return type:

(press_x: float, press_y: float)

Retrieves the coordinates, in stage space, of the press event that started the dragging

New in version 1.4.

set_drag_area(drag_area)¶

Parameters:: drag_area (Clutter.Rect or None) – a Clutter.Rect

Sets drag_area to constrain the dragging of the actor associated with self, so that it position is always within drag_area, expressed in parent’s coordinates. If drag_area is None, the actor is not constrained.

set_drag_axis(axis)¶

Parameters:: axis (Clutter.DragAxis) – the axis to constraint the dragging to

Restricts the dragging action to a specific axis

New in version 1.4.

set_drag_handle(handle)¶

Parameters:: handle (Clutter.Actor or None) – a Clutter.Actor, or None to unset

Sets the actor to be used as the drag handle.

New in version 1.4.

set_drag_threshold(x_threshold, y_threshold)¶

Parameters:

x_threshold (int) – a distance on the horizontal axis, in pixels, or -1 to use the default drag threshold from Clutter.Settings
y_threshold (int) – a distance on the vertical axis, in pixels, or -1 to use the default drag threshold from Clutter.Settings

Sets the horizontal and vertical drag thresholds that must be cleared by the pointer before self can begin the dragging.

If x_threshold or y_threshold are set to -1 then the default drag threshold stored in the Clutter.Settings :dnd-drag-threshold property of Clutter.Settings will be used.

New in version 1.4.

do_drag_begin(actor, event_x, event_y, modifiers) virtual¶

Parameters:

actor (Clutter.Actor) –
event_x (float) –
event_y (float) –
modifiers (Clutter.ModifierType) –

do_drag_end(actor, event_x, event_y, modifiers) virtual¶

Parameters:

actor (Clutter.Actor) –
event_x (float) –
event_y (float) –
modifiers (Clutter.ModifierType) –

do_drag_motion(actor, delta_x, delta_y) virtual¶

Parameters:

actor (Clutter.Actor) –
delta_x (float) –
delta_y (float) –

do_drag_progress(actor, delta_x, delta_y) virtual¶

Parameters:

actor (Clutter.Actor) –
delta_x (float) –
delta_y (float) –

Return type:

bool

Signal Details¶

Clutter.DragAction.signals.drag_begin(drag_action, actor, event_x, event_y, modifiers)¶

Signal Name:

drag-begin

Flags:

RUN_LAST

Parameters:

drag_action (Clutter.DragAction) – The object which received the signal
actor (Clutter.Actor) – the Clutter.Actor attached to the action
event_x (float) – the X coordinate (in stage space) of the press event
event_y (float) – the Y coordinate (in stage space) of the press event
modifiers (Clutter.ModifierType) – the modifiers of the press event

The ::drag-begin signal is emitted when the Clutter.DragAction starts the dragging

The emission of this signal can be delayed by using the Clutter.DragAction :x-drag-threshold and Clutter.DragAction :y-drag-threshold properties

New in version 1.4.

Clutter.DragAction.signals.drag_end(drag_action, actor, event_x, event_y, modifiers)¶

Signal Name:

drag-end

Flags:

RUN_LAST

Parameters:

drag_action (Clutter.DragAction) – The object which received the signal
actor (Clutter.Actor) – the Clutter.Actor attached to the action
event_x (float) – the X coordinate (in stage space) of the release event
event_y (float) – the Y coordinate (in stage space) of the release event
modifiers (Clutter.ModifierType) – the modifiers of the release event

The ::drag-end signal is emitted at the end of the dragging, when the pointer button’s is released

This signal is emitted if and only if the Clutter.DragAction ::drag-begin signal has been emitted first

New in version 1.4.

Clutter.DragAction.signals.drag_motion(drag_action, actor, delta_x, delta_y)¶

Signal Name:

drag-motion

Flags:

RUN_LAST

Parameters:

drag_action (Clutter.DragAction) – The object which received the signal
actor (Clutter.Actor) – the Clutter.Actor attached to the action
delta_x (float) – the X component of the distance between the press event that began the dragging and the current position of the pointer, as of the latest motion event
delta_y (float) – the Y component of the distance between the press event that began the dragging and the current position of the pointer, as of the latest motion event

The ::drag-motion signal is emitted for each motion event after the Clutter.DragAction ::drag-begin signal has been emitted.

The components of the distance between the press event and the latest motion event are computed in the actor’s coordinate space, to take into account eventual transformations. If you want the stage coordinates of the latest motion event you can use Clutter.DragAction.get_motion_coords().

The default handler of the signal will call Clutter.Actor.move_by() either on actor or, if set, of Clutter.DragAction :drag-handle using the delta_x and delta_y components of the dragging motion. If you want to override the default behaviour, you can connect to the Clutter.DragAction ::drag-progress signal and return False from the handler.

New in version 1.4.

Clutter.DragAction.signals.drag_progress(drag_action, actor, delta_x, delta_y)¶

Signal Name:

drag-progress

Flags:

RUN_LAST

Parameters:

drag_action (Clutter.DragAction) – The object which received the signal
actor (Clutter.Actor) – the Clutter.Actor attached to the action
delta_x (float) – the X component of the distance between the press event that began the dragging and the current position of the pointer, as of the latest motion event
delta_y (float) – the Y component of the distance between the press event that began the dragging and the current position of the pointer, as of the latest motion event

Returns:

True if the drag should continue, and False if it should be stopped.

Return type:

bool

The ::drag-progress signal is emitted for each motion event after the Clutter.DragAction ::drag-begin signal has been emitted.

The components of the distance between the press event and the latest motion event are computed in the actor’s coordinate space, to take into account eventual transformations. If you want the stage coordinates of the latest motion event you can use Clutter.DragAction.get_motion_coords().

The default handler will emit Clutter.DragAction ::drag-motion, if Clutter.DragAction ::drag-progress emission returns True.

New in version 1.12.

Property Details¶

Clutter.DragAction.props.drag_area¶

Name:: drag-area
Type:: Clutter.Rect
Default Value:: None
Flags:: READABLE, WRITABLE

Constains the dragging action (or in particular, the resulting actor position) to the specified Clutter.Rect, in parent’s coordinates.

New in version 1.12.

Clutter.DragAction.props.drag_area_set¶

Name:: drag-area-set
Type:: bool
Default Value:: False
Flags:: READABLE

Whether the Clutter.DragAction :drag-area property has been set.

New in version 1.12.

Clutter.DragAction.props.drag_axis¶

Name:: drag-axis
Type:: Clutter.DragAxis
Default Value:: Clutter.DragAxis.AXIS_NONE
Flags:: READABLE, WRITABLE

Constraints the dragging action to the specified axis

New in version 1.4.

Clutter.DragAction.props.drag_handle¶

Name:: drag-handle
Type:: Clutter.Actor
Default Value:: None
Flags:: READABLE, WRITABLE

The Clutter.Actor that is effectively being dragged

A Clutter.DragAction will, be default, use the Clutter.Actor that has been attached to the action; it is possible to create a separate Clutter.Actor and use it instead.

Setting this property has no effect on the Clutter.Actor argument passed to the Clutter.DragAction signals

New in version 1.4.

Clutter.DragAction.props.x_drag_threshold¶

Name:: x-drag-threshold
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The horizontal threshold, in pixels, that the cursor must travel in order to begin a drag action.

When set to a positive value, Clutter.DragAction will only emit Clutter.DragAction ::drag-begin if the pointer has moved horizontally at least of the given amount of pixels since the button press event.

When set to -1, Clutter.DragAction will use the default threshold stored in the Clutter.Settings :dnd-drag-threshold property of Clutter.Settings.

When read, this property will always return a valid drag threshold, either as set or the default one.

New in version 1.4.

Clutter.DragAction.props.y_drag_threshold¶

Name:: y-drag-threshold
Type:: int
Default Value:: 0
Flags:: READABLE, WRITABLE

The vertical threshold, in pixels, that the cursor must travel in order to begin a drag action.

When set to a positive value, Clutter.DragAction will only emit Clutter.DragAction ::drag-begin if the pointer has moved vertically at least of the given amount of pixels since the button press event.

When set to -1, Clutter.DragAction will use the value stored in the Clutter.Settings :dnd-drag-threshold property of Clutter.Settings.

When read, this property will always return a valid drag threshold, either as set or the default one.

New in version 1.4.