Typedefs | Enumerations | Functions
Ecore_Evas methods to handle selection

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_Futureecore_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_Accessorecore_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]eeThe Ecore_Evas that handles this selection.
[in]selectionThe 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]eeThe Ecore Evas the drag operation started on.
[in]pPosition (in window coordinates) where the event occurred.
[in]insideEINA_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]eeThe Ecore Evas the drag operation started on.
[in]pPosition (in window coordinates) where the event occurred.
[in]insideEINA_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]eeThe Ecore Evas the drag operation started on.
[in]pPosition (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]eeThe Ecore Evas the drag operation started on.
[in]pPosition (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

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]eeThe Ecore_Evas to set the callback on.
[in]cbThe 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]eeThe Ecore_Evas to set the selection buffer on.
[in]bufferThe selection buffer to set.
[in]contentContent 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]eeThe ecore evas to query
[in]bufferWhich 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]eeThe ecore evas to query.
[in]bufferSelection buffer to retrieve.
[in]acceptable_typesMIME 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]eeThe Ecore Evas the drag operation started on.
[in]contentThe 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_repAn 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]actionAction 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]eeThe 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]eeThe Ecore Evas the drag operation started on.
[in]cbMethod 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]eeThe Ecore Evas the drag operation started on.
[in]cbMethod 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]eeThe Ecore Evas the drag operation started on.
[in]cbMethod 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]eeThe 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.