Clutter.DragAction

g Clutter.Action Clutter.Action Clutter.DragAction Clutter.DragAction Clutter.Action->Clutter.DragAction Clutter.ActorMeta Clutter.ActorMeta Clutter.ActorMeta->Clutter.Action GObject.InitiallyUnowned GObject.InitiallyUnowned GObject.InitiallyUnowned->Clutter.ActorMeta GObject.Object GObject.Object GObject.Object->GObject.InitiallyUnowned

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:
do_drag_end(actor, event_x, event_y, modifiers) virtual
Parameters:
do_drag_motion(actor, delta_x, delta_y) virtual
Parameters:
do_drag_progress(actor, delta_x, delta_y) virtual
Parameters:
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:

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:

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.