Ecore_Evas methods to handle selection

Typedefs | Enumerations | Functions
Ecore_Evas methods to handle selection
Ecore » Ecore_Evas wrapper/helper set of functions

These methods perform Copy&Paste and Drag&Drop operations. More...

## Typedefs
typedef void(* | Ecore_Evas_Selection_Changed_Cb) (Ecore_Evas *ee, unsigned int seat, Ecore_Evas_Selection_Buffer selection)
| Callback called when the content of one of the selection buffers changes. More...
typedef void(* | Ecore_Evas_Drag_Finished_Cb) (Ecore_Evas *ee, unsigned int seat, void *data, Eina_Bool accepted)
| This method is called when the mouse pointer enters or exits the specified window while performing a drag operation. More...
typedef void(* | Ecore_Evas_Drag_State_Changed_Cb) (Ecore_Evas *ee, unsigned int seat, Eina_Position2D p, Eina_Bool inside)
| This method is called when the mouse pointer enters or exits the specified window while performing a drag operation. More...
typedef void(* | Ecore_Evas_Drag_Motion_Cb) (Ecore_Evas *ee, unsigned int seat, Eina_Position2D p)
| This method is called when the mouse pointer moves over the specified window while performing a drag operation. More...
typedef void(* | Ecore_Evas_Drop_Cb) (Ecore_Evas *ee, unsigned int seat, Eina_Position2D p, const char *action)
| This method is called when the mouse pointer is released over the specified window while performing a drag operation (thus dropping the dragged content over the window). More...

## Enumerations
enum | Ecore_Evas_Selection_Buffer { ECORE_EVAS_SELECTION_BUFFER_SELECTION_BUFFER = 0 , ECORE_EVAS_SELECTION_BUFFER_COPY_AND_PASTE_BUFFER = 1 , ECORE_EVAS_SELECTION_BUFFER_DRAG_AND_DROP_BUFFER = 2 , ECORE_EVAS_SELECTION_BUFFER_LAST = 3 }
| Data buffer to use in Copy&Paste (and Drag&Drop) operations. More...

## Functions
EAPI void | ecore_evas_callback_selection_changed_set (Ecore_Evas *ee, Ecore_Evas_Selection_Changed_Cb cb)
| Sets a callback for Ecore_Evas to be called when a selection buffer changes. More...
EAPI Eina_Bool | ecore_evas_selection_set (Ecore_Evas *ee, unsigned int seat, Ecore_Evas_Selection_Buffer buffer, Eina_Content *content)
| Sets the content of the specified selection buffer. More...
EAPI Eina_Bool | ecore_evas_selection_exists (Ecore_Evas *ee, unsigned int seat, Ecore_Evas_Selection_Buffer buffer)
| Checks if the specified selection buffer has content. More...
EAPI Eina_Future * | ecore_evas_selection_get (Ecore_Evas *ee, unsigned int seat, Ecore_Evas_Selection_Buffer buffer, Eina_Iterator *acceptable_types)
| Retrieves the content of the specified selection buffer. More...
EAPI Eina_Bool | ecore_evas_drag_start (Ecore_Evas *ee, unsigned int seat, Eina_Content *content, Ecore_Evas *drag_rep, const char *action, Ecore_Evas_Drag_Finished_Cb terminate_cb, void *data)
| Starts a new drag operation. More...
EAPI Eina_Bool | ecore_evas_drag_cancel (Ecore_Evas *ee, unsigned int seat)
| Cancels an ongoing drag operation. More...
EAPI void | ecore_evas_callback_drop_state_changed_set (Ecore_Evas *ee, Ecore_Evas_Drag_State_Changed_Cb cb)
| Sets the method (callback) to call when the mouse pointer enters or exits the specified window while performing a drag operation. More...
EAPI void | ecore_evas_callback_drop_motion_set (Ecore_Evas *ee, Ecore_Evas_Drag_Motion_Cb cb)
| Sets the method (callback) to call when the mouse pointer moves over the specified window while performing a drag operation. More...
EAPI void | ecore_evas_callback_drop_drop_set (Ecore_Evas *ee, Ecore_Evas_Drop_Cb cb)
| Sets the method (callback) to call when the mouse pointer is released over the specified window while performing a drag operation (thus dropping the dragged content over the window). More...
EAPI Eina_Accessor * | ecore_evas_drop_available_types_get (Ecore_Evas *ee, unsigned int seat)
| Retrieves the list of types the data currently being dragged can be automatically converted to. More...

## Detailed Description

These methods perform Copy&Paste and Drag&Drop operations.

Since
  1.24

## Typedef Documentation

## ◆ Ecore_Evas_Selection_Changed_Cb

typedef void(* Ecore_Evas_Selection_Changed_Cb) (Ecore_Evas *ee, unsigned int seat, Ecore_Evas_Selection_Buffer selection)

Callback called when the content of one of the selection buffers changes.

Parameters

  [in] | ee | The Ecore_Evas that handles this selection.
  [in] | selection | The selection buffer that has changed.

Since
  1.24

## ◆ Ecore_Evas_Drag_Finished_Cb

typedef void(* Ecore_Evas_Drag_Finished_Cb) (Ecore_Evas *ee, unsigned int seat, void *data, Eina_Bool accepted)

This method is called when the mouse pointer enters or exits the specified window while performing a drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | p | Position (in window coordinates) where the event occurred.
  [in] | inside | `EINA_TRUE` if the pointer just entered this window. `EINA_FALSE` if it has just exited.

Set this callback using ecore_evas_callback_drop_state_changed_set.

Since
  1.24

## ◆ Ecore_Evas_Drag_State_Changed_Cb

typedef void(* Ecore_Evas_Drag_State_Changed_Cb) (Ecore_Evas *ee, unsigned int seat, Eina_Position2D p, Eina_Bool inside)

This method is called when the mouse pointer enters or exits the specified window while performing a drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | p | Position (in window coordinates) where the event occurred.
  [in] | inside | `EINA_TRUE` if the pointer just entered this window. `EINA_FALSE` if it has just exited.

Set this callback using ecore_evas_callback_drop_state_changed_set.

Since
  1.24

## ◆ Ecore_Evas_Drag_Motion_Cb

typedef void(* Ecore_Evas_Drag_Motion_Cb) (Ecore_Evas *ee, unsigned int seat, Eina_Position2D p)

This method is called when the mouse pointer moves over the specified window while performing a drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | p | Position (in window coordinates) where the event occurred.

Set this callback using ecore_evas_callback_drop_motion_set.

Since
  1.24

## ◆ Ecore_Evas_Drop_Cb

typedef void(* Ecore_Evas_Drop_Cb) (Ecore_Evas *ee, unsigned int seat, Eina_Position2D p, const char *action)

This method is called when the mouse pointer is released over the specified window while performing a drag operation (thus dropping the dragged content over the window).

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | p | Position (in window coordinates) where the event occurred.

The dropped data can be retrieved using ecore_evas_selection_get and the ECORE_EVAS_SELECTION_BUFFER_DRAG_AND_DROP_BUFFER buffer.

Set this callback using ecore_evas_callback_drop_drop_set.

Since
  1.24

## Enumeration Type Documentation

## ◆ Ecore_Evas_Selection_Buffer

enum Ecore_Evas_Selection_Buffer

Data buffer to use in Copy&Paste (and Drag&Drop) operations.

Since
  1.24

Enumerator
ECORE_EVAS_SELECTION_BUFFER_SELECTION_BUFFER | Stores selected / highlighted selection.
ECORE_EVAS_SELECTION_BUFFER_COPY_AND_PASTE_BUFFER | Stores copied things (Ctrl + C)
ECORE_EVAS_SELECTION_BUFFER_DRAG_AND_DROP_BUFFER | Stores dragged things while drag and drop is happening.
ECORE_EVAS_SELECTION_BUFFER_LAST | Sentinel value. Do not use.

## Function Documentation

## ◆ ecore_evas_callback_selection_changed_set()

EAPI void ecore_evas_callback_selection_changed_set | ( | Ecore_Evas * | ee,
|  | Ecore_Evas_Selection_Changed_Cb | cb
| ) |  |

Sets a callback for Ecore_Evas to be called when a selection buffer changes.

Parameters

  [in] | ee | The Ecore_Evas to set the callback on.
  [in] | cb | The function to call.

A call to this function will set a callback on an Ecore_Evas, causing `func` to be called whenever `ee` selections change. Only one such callback can exist for each Ecore_Evas. Calling this method multiple times overwrites previous functions. Use a NULL `func` to stop being notified.

Warning
  If and when this function is called depends on the underlying windowing system.

Since
  1.24

## ◆ ecore_evas_selection_set()

EAPI Eina_Bool ecore_evas_selection_set | ( | Ecore_Evas * | ee,
|  | unsigned int | seat,
|  | Ecore_Evas_Selection_Buffer | buffer,
|  | Eina_Content * | content
| ) |  |

Sets the content of the specified selection buffer.

Parameters

  [in] | ee | The Ecore_Evas to set the selection buffer on.
  [in] | buffer | The selection buffer to set.
  [in] | content | Content to set to the selection buffer. The Eina_Content specifies the MIME type of the data. Ownership of the content is transferred.

Note
  Only ECORE_EVAS_SELECTION_BUFFER_SELECTION_BUFFER and ECORE_EVAS_SELECTION_BUFFER_COPY_AND_PASTE_BUFFER buffers can be set. Drag and drop operations use a different set of methods.

Since
  1.24

References ECORE_EVAS_SELECTION_BUFFER_DRAG_AND_DROP_BUFFER, ECORE_EVAS_SELECTION_BUFFER_LAST, EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, ERR, and INF.

Referenced by elm_cnp_selection_set(), and elm_object_cnp_selection_clear().

## ◆ ecore_evas_selection_exists()

EAPI Eina_Bool ecore_evas_selection_exists | ( | Ecore_Evas * | ee,
|  | unsigned int | seat,
|  | Ecore_Evas_Selection_Buffer | buffer
| ) |  |

Checks if the specified selection buffer has content.

Parameters

  [in] | ee | The ecore evas to query
  [in] | buffer | Which selection buffer to ask

Returns
  EINA_TRUE if there is an available selection for the specified buffer.

EINA_TRUE is also returned when the selection is in the window associated with `ee`

Note
  Due to the asynchronous nature of selection buffers, this method might not return the right result when invoked from the selection callback set with ecore_evas_callback_selection_changed_set.

Since
  1.24

References ECORE_EVAS_SELECTION_BUFFER_LAST, EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and INF.

Referenced by elm_cnp_clipboard_selection_has_owner().

## ◆ ecore_evas_selection_get()

EAPI Eina_Future* ecore_evas_selection_get | ( | Ecore_Evas * | ee,
|  | unsigned int | seat,
|  | Ecore_Evas_Selection_Buffer | buffer,
|  | Eina_Iterator * | acceptable_types
| ) |  |

Retrieves the content of the specified selection buffer.

Parameters

  [in] | ee | The ecore evas to query.
  [in] | buffer | Selection buffer to retrieve.
  [in] | acceptable_types | MIME types which are acceptable for the returned Eina_Content. The iterator contains plain strings (char *). Ownership is transferred for the iterator but not for the strings. This is convenient for the usual case of a hard-coded array of strings, since the iterator can be generated on the fly, used and forgotten.

Returns
  An Eina_Future containing an Eina_Content which has one of the types in `acceptable_type`. An error is delivered when no matching type is found or when the requested selection buffer is empty.

This method is time consuming, therefore, it is recommended to verify the existence of a selection using ecore_evas_selection_exists before calling it.

Since
  1.24

References ECORE_EVAS_SELECTION_BUFFER_LAST, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, and INF.

Referenced by elm_cnp_selection_get().

## ◆ ecore_evas_drag_start()

EAPI Eina_Bool ecore_evas_drag_start | ( | Ecore_Evas * | ee,
|  | unsigned int | seat,
|  | Eina_Content * | content,
|  | Ecore_Evas * | drag_rep,
|  | const char * | action,
|  | Ecore_Evas_Drag_Finished_Cb | terminate_cb,
|  | void * | data
| ) |  |

Starts a new drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | content | The content to delivery at the drop site (ownership is transferred). The Eina_Content has data and its associated MIME type, plus a list of alternate types that can be provided.
  [in] | drag_rep | An Ecore_Evas used as a visual representation of the content being dragged. It must have the same type as `ee`. This is the transparent object dragged along the mouse pointer to indicate that a drag operation is in progress. `terminate_cb` will be called when `drag_rep` is not needed anymore and it must be disposed of. Use `data` to convey `drag_rep` to `terminate_cb`. For example, if `drag_rep` is owned by an Efl_Window, `data` can point to that window.
  [in] | action | Action the target application should perform upon receiving this content. It is entirely up to the target application to honor (or even understand) this request.

Returns
  `EINA_TRUE` if the drag operation has been successfully started.

This method must be called when a drag operation is initiated in order to provide the necessary information.

Since
  1.24

References ECORE_EVAS_SELECTION_BUFFER_DRAG_AND_DROP_BUFFER, EINA_FALSE, EINA_SAFETY_ON_FALSE_RETURN_VAL, EINA_SAFETY_ON_NULL_RETURN_VAL, EINA_TRUE, and INF.

## ◆ ecore_evas_drag_cancel()

EAPI Eina_Bool ecore_evas_drag_cancel | ( | Ecore_Evas * | ee,
|  | unsigned int | seat
| ) |  |

Cancels an ongoing drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.

Returns
  `EINA_TRUE` if the drag operation has been successfully cancelled.

The initiator of a drag operation can call this method to abort it.

Since
  1.24

References EINA_FALSE, EINA_SAFETY_ON_NULL_RETURN_VAL, and INF.

## ◆ ecore_evas_callback_drop_state_changed_set()

EAPI void ecore_evas_callback_drop_state_changed_set | ( | Ecore_Evas * | ee,
|  | Ecore_Evas_Drag_State_Changed_Cb | cb
| ) |  |

Sets the method (callback) to call when the mouse pointer enters or exits the specified window while performing a drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | cb | Method to call when the events are received.

Only one such callback can exist for each Ecore_Evas. Calling this method multiple times overwrites previous functions. Use a NULL `cb` func to stop being notified.

Since
  1.24

## ◆ ecore_evas_callback_drop_motion_set()

EAPI void ecore_evas_callback_drop_motion_set | ( | Ecore_Evas * | ee,
|  | Ecore_Evas_Drag_Motion_Cb | cb
| ) |  |

Sets the method (callback) to call when the mouse pointer moves over the specified window while performing a drag operation.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | cb | Method to call when the events are received.

Only one such callback can exist for each Ecore_Evas. Calling this method multiple times overwrites previous functions. Use a NULL `cb` func to stop being notified.

Since
  1.24

## ◆ ecore_evas_callback_drop_drop_set()

EAPI void ecore_evas_callback_drop_drop_set | ( | Ecore_Evas * | ee,
|  | Ecore_Evas_Drop_Cb | cb
| ) |  |

Sets the method (callback) to call when the mouse pointer is released over the specified window while performing a drag operation (thus dropping the dragged content over the window).

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.
  [in] | cb | Method to call when the events are received.

Only one such callback can exist for each Ecore_Evas. Calling this method multiple times overwrites previous functions. Use a NULL `cb` func to stop being notified.

Since
  1.24

## ◆ ecore_evas_drop_available_types_get()

EAPI Eina_Accessor* ecore_evas_drop_available_types_get | ( | Ecore_Evas * | ee,
|  | unsigned int | seat
| ) |  |

Retrieves the list of types the data currently being dragged can be automatically converted to.

Parameters

  [in] | ee | The Ecore Evas the drag operation started on.

Returns

This can be used in any of the drag and drop callbacks (Ecore_Evas_Drag_State_Changed_Cb, Ecore_Evas_Drag_Motion_Cb and Ecore_Evas_Drop_Cb) to check if the data being dragged is acceptable and give the user some early feedback before the data is actually dropped on the window.

This is functionally equivalent to calling ecore_evas_selection_get and examining the available types in the returned Eina_Content, but much faster since the actual data does not have to be asynchronously requested to the initiator application.

Since
  1.24

References eina_array_accessor_new(), eina_hash_find(), and EINA_SAFETY_ON_NULL_RETURN_VAL.