enlightenment/efl
enlightenment
/
efl
8
7
Fork 14
Code Issues 13 Pull Requests 3 Projects Releases Wiki Activity

docs: Strengthen docs for Copy&Paste and Drag&Drop 

Including Eina.Content

And a typo/bugfix in ecore_evas_x.

Reviewed-by: Mike Blumenkrantz <michael.blumenkrantz@gmail.com>
Differential Revision: https://phab.enlightenment.org/D11204
This commit is contained in:
Xavi Artigas 2020-03-03 11:12:08 +01:00 committed by Marcel Hollerbach
parent 7dd92a2d98
commit 645c3d41eb
7 changed files with 163 additions and 99 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
src/lib/ecore_evas/Ecore_Evas.h
View File

@ -3695,8 +3695,6 @@ typedef void (*Ecore_Evas_Selection_Changed_Cb)(Ecore_Evas *ee, unsigned int sea
* Only one such callback can exist for each Ecore_Evas. Calling this method multiple
* times overwrites previous functions. Use a NULL @p func to stop being notified.
*
* You will not be notified about selection changes caused by yourself. (TODO: bu5hm4n?)
*
* @warning If and when this function is called depends on the underlying
* windowing system.
*/

68
src/lib/eina/eina_abstract_content.h
View File

@ -4,22 +4,22 @@
/**
* @typedef Eina_Content
* Defines a abstract content segment
* Container for any type of content.
*
* Each Abstract content contains out of a Eina_Slice of memory. And a type.
* The type are IANA meme types.
* Each Eina_Content is made of an Eina_Slice of memory and an IANA MIME type:
* https://www.iana.org/assignments/media-types/media-types.xhtml
*
* @note if the type is a text-style type, the last byte of the slice must be \0
* @note If the type is any kind of text the last byte of the slice must be \0.
*
* @since 1.24
*/
typedef struct _Eina_Content Eina_Content;
/**
* @typedef Eina_Content_Convertion_Callback
* @typedef Eina_Content_Conversion_Callback
*
* Callback called when convertion from one type to another type is requested.
* The from and to type is specified when the callback is registered.
* Method called when conversion from one type to another is requested.
* The from and to types are specified when the callback is registered.
* The to type is also passed in the callback here.
* The type of the from pointer does not need to be checked.
*/
@ -38,7 +38,7 @@ EAPI const char* eina_content_as_file(Eina_Content *content);
/**
* Convert the content of the object to another type.
*
* In case the convertion cannot be performaned, NULL is returned.
* In case the conversion cannot be performed, NULL is returned.
*
* @param[in] content The content to convert.
* @param[in] new_type The new type the returned content will have.
@ -57,19 +57,19 @@ EAPI Eina_Content* eina_content_convert(Eina_Content *content, const char *new_t
EAPI const char* eina_content_type_get(Eina_Content *content);
/**
* Get the type of the passed content.
* Get the Eina_Slice of the passed content.
*
* @param[in] content The content to fetch the type from.
* @param[in] content The content to fetch the data from.
*
* @return The path to the file. Do not free this.
* @return An Eina_Slice containing the data. Do not free.
*/
EAPI const Eina_Slice eina_content_data_get(Eina_Content *content);
/**
* Create a new content object, with the slice of data with a specific type.
* Create a new content object, with the provided data and type.
*
* @param[in] data A slice of memory, the memory is duplicated.
* @param[in] type The type of memory.
* @param[in] data A slice of memory. The memory is copied.
* @param[in] type The type this data represents.
*
* @return The new content object. The caller owns this object.
*/
@ -85,62 +85,62 @@ EAPI void eina_content_free(Eina_Content *content);
/**
* Register a new conversion callback.
*
* @param[in] from The tyoe you convert from.
* @param[in] in The type you convert to.
* @param[in] from The type to convert from.
* @param[in] to The type to convert to.
*
* @return True on success false otherwise.
* @return True if the callback was successfully registered.
*/
EAPI Eina_Bool eina_content_converter_conversion_register(const char *from, const char *to, Eina_Content_Conversion_Callback convertion);
/**
* Check if a specific convertion can be performanced.
* Check if a specific conversion can be performed.
*
* A convertion can only be performed if a callback is registered.
* A conversion can only be performed if a callback is registered.
*
* @param[in] from The type you convert from.
* @param[in] in The type you convert to.
* @param[in] from The type to convert from.
* @param[in] to The type to convert to.
*
* @return True if it can be performed, false if not.
* @return True if the conversion can be performed.
*/
EAPI Eina_Bool eina_content_converter_convert_can(const char *from, const char *to);
/**
* Returns a iterator that can be used to find all the possible types that can be converted to.
* Returns an iterator containing all the target types that the provided source type can be converted to.
*
* @param[in] form The type you convert from
* @param[in] from The type to convert from.
*
* @return A Iterator, containing strings, free this via eina_iterator_free.
* @return An Iterator containing MIME type strings. Free this via eina_iterator_free.
*/
EAPI Eina_Iterator* eina_content_converter_possible_conversions(const char *from);
EAPI extern const Eina_Value_Type *EINA_VALUE_TYPE_CONTENT;
/**
* Convert the Eina_Content object to a Eina_Value.
* Convert the Eina_Content object to an Eina_Value.
*
* @param[in] content The Eina_Content struct that will be converted to a Eina_Value
* @param[in] content The Eina_Content struct that will be converted to an Eina_Value.
*
* @return A Eina_Value that is allocated, you need to free it.
* @return An newly-allocated Eina_Value. Caller owns it.
*/
EAPI Eina_Value* eina_value_content_new(Eina_Content *content);
/**
* Convert the Eina_Content object to a Eina_Value.
* Creates an Eina_Value from an Eina_Content.
*
* @param[in] content The Eina_Content struct that will be converted to a Eina_Value
* @param[in] content The Eina_Content struct that will be converted to an Eina_Value.
*
* @return A Eina_Value with type EINA_VALUE_TYPE_CONTENT
* @return An Eina_Value with type EINA_VALUE_TYPE_CONTENT.
*/
EAPI Eina_Value eina_value_content_init(Eina_Content *content);
/**
* Get the content from the Eina_Value
* Gets the content from the Eina_Value.
*
* If the value is not of the type EINA_VALUE_TYPE_CONTENT, NULL will be returned and a error will be printed.
* If the value is not of the type EINA_VALUE_TYPE_CONTENT, NULL will be returned and an error will be printed.
*
* @param[in] value The value to get the content from
*
* @return A allocated Eina_Content, you need to free it.
* @return A newly-allocated Eina_Content. Caller owns it.
*/
EAPI Eina_Content* eina_value_to_content(const Eina_Value *value);

82
src/lib/elementary/efl_ui_dnd.eo
View File

@ -1,63 +1,89 @@
import eina_types;
struct @beta Efl.Ui.Drop_Event {
[[Event struct that contains information about what is avaiable at which position, in which seat]]
position : Eina.Position2D; [[The position of the Drop event]]
seat : uint; [[In which seat it is happening]]
available_types : accessor<string>; [[which types are avaiable, you should use one of these for a call to @Efl.Ui.Dnd.drop_data_get ]]
[[Information sent along with Drag & Drop events.]]
position : Eina.Position2D; [[The position where the drop event occurred, in window coordinates.]]
seat : uint; [[Which seat triggered the event.]]
available_types : accessor<string>; [[Types with automatic conversion available. Use one of them in the call to
@Efl.Ui.Dnd.drop_data_get.
Types are IANA MIME types:
https://www.iana.org/assignments/media-types/media-types.xhtml
]]
}
struct @beta Efl.Ui.Drop_Dropped_Event {
dnd : Efl.Ui.Drop_Event; [[The overall information]]
action : string; [[The action the client should take]]
[[Information sent along with Drop events.]]
dnd : Efl.Ui.Drop_Event; [[Common information.]]
action : string; [[Requested action to perform upon reception of this data.]]
}
struct @beta Efl.Ui.Drag_Started_Event {
seat : uint;
[[Information sent along with @Efl.Ui.Drag_Started_Event events.]]
seat : uint; [[Which seat triggered the event.]]
}
struct @beta Efl.Ui.Drag_Finished_Event {
seat : uint;
accepted : bool;
[[Information sent along with @Efl.Ui.Drag_Finished_Event events.]]
seat : uint; [[Which seat triggered the event.]]
accepted : bool; [[$true if the operation completed with a Drop, or $false if it was cancelled.]]
}
mixin @beta Efl.Ui.Dnd requires Efl.Object {
[[This mixin provides the ability to interact with the system's Drag & Drop facilities.
Applications starting a Drag & Drop operation operation are said to perform a "Drag" and use
the methods prefixed "drag_".
On the other hand, applications receiving dragged content are said to perform a "Drop" operation and use
the methods prefixed "drop_".
]]
methods {
drag_start {
[[Start a drag from this client.
[[Starts a drag from this client.
@[Efl.Ui.Dnd.drag,started] will be emitted each time a successfull drag will be started.
@[Efl.Ui.Dnd.drag,finished] will be emitted every time a drag is finished.
@[Efl.Ui.Dnd.drag,started] is emitted each time a successful drag is started.
@[Efl.Ui.Dnd.drag,finished] is emitted every time a drag is finished.
]]
params {
content : Eina.Content @by_ref; [[The content you want to provide via dnd]]
@in action: string; [[Action when data is transferred]]
@in seat: uint; [[Specified seat for multiple seats case.]]
content : Eina.Content @by_ref; [[The content being dragged.]]
@in action: string; [[Requested action to perform by the receiver once content is transferred.]]
@in seat: uint; [[Seat starting the drag operation. When in doubt use 0.]]
}
return : Efl.Content; [[A UI element where you can just set your visual representation into]]
return : Efl.Content; [[An Efl.Ui element which you can use to render a visual representation
of the content being dragged (like a thumbnail, for example).
Use @Efl.Content.content.set on it to do so.]]
}
drag_cancel {
[[Cancel the on-going drag]]
[[Cancels an on-going drag operation.]]
params {
@in seat: uint; [[Specified seat for multiple seats case.]]
@in seat: uint; [[Seat that started the drag operation. When in doubt use 0.]]
}
}
drop_data_get {
[[Get the data from the object that has selection]]
[[Retrieves the dropped data.]]
params {
seat : uint; [[Specified seat for multiple seats case.]]
acceptable_types : iterator<string>; [[The types that are acceptable for you]]
@in seat: uint; [[Seat that started the drag operation. When in doubt use 0.]]
@in acceptable_types : iterator<string>; [[List of strings describing the type of content the application
can accept. Types are IANA MIME types:
https://www.iana.org/assignments/media-types/media-types.xhtml.]]
}
return : future<Eina.Content> @move; [[fullfilled when the content is transmitted, and ready to use]]
return : future<Eina.Content> @move; [[This future is fulfilled when the content is received (asynchronously)
and ready to use.
The Eina.Content specifies the type of the data.
If no matching type was found it returns an error.
]]
}
}
events {
drop,entered : Efl.Ui.Drop_Event;
drop,left : Efl.Ui.Drop_Event;
drop,position,changed : Efl.Ui.Drop_Event;
drop,dropped : Efl.Ui.Drop_Dropped_Event;
drag,started : Efl.Ui.Drag_Started_Event;
drag,finished : Efl.Ui.Drag_Finished_Event;
drop,entered : Efl.Ui.Drop_Event; [[Dragged content entered the window. Its type can already be checked with
@.drop_data_get to react before it is dropped, for example.]]
drop,left : Efl.Ui.Drop_Event; [[Dragged content left the window.]]
drop,position,changed : Efl.Ui.Drop_Event; [[Dragged content moved over the window. Its type can already be
checked with @.drop_data_get to react before it is dropped,
for example.]]
drop,dropped : Efl.Ui.Drop_Dropped_Event; [[Dragged content was dropped over the window.]]
drag,started : Efl.Ui.Drag_Started_Event; [[A Drag operation started.]]
drag,finished : Efl.Ui.Drag_Finished_Event;[[A Drag operation finished.]]
}
implements {
Efl.Object.constructor;

74
src/lib/elementary/efl_ui_selection.eo
View File

@ -1,49 +1,76 @@
import eina_types;
enum @beta Efl.Ui.Cnp_Buffer{
selection = 0,
copy_and_paste = 1,
enum @beta Efl.Ui.Cnp_Buffer {
[[System buffer to use in Copy & Paste operations.]]
selection = 0, [[Buffer typically used when the user selects (highlights) some text without explicitly
requesting to copy it.]]
copy_and_paste = 1, [[Buffer used when the user requests that the current selection is copied (using
Ctrl+C, for example).]]
}
struct @beta Efl.Ui.Wm_Selection_Changed {
buffer : Efl.Ui.Cnp_Buffer;
caused_by : Efl.Ui.Selection;
seat : uint;
[[Information sent along the @[Efl.Ui.Selection.wm_selection,changed] event.]]
buffer : Efl.Ui.Cnp_Buffer; [[The system buffer that has changed.]]
caused_by : Efl.Ui.Selection; [[The EFL widget that triggered the change. $NULL if it is not an EFL widget.]]
seat : uint; [[The seat that triggered the change.]]
}
mixin @beta Efl.Ui.Selection requires Efl.Object {
[[This mixin provides the ability to interact with the system's Copy & Paste facilities.
]]
methods {
selection_set {
[[Set the selection data to the object]]
[[Sets the current selection.
This sends the selected data to the system's specified buffer, making it available to other
applications for "pasting" it.
This is typically used when the user requests a "copy" operation.
]]
params {
buffer : Efl.Ui.Cnp_Buffer;
content : Eina.Content @by_ref;
seat : uint;
buffer : Efl.Ui.Cnp_Buffer; [[System buffer to use.]]
content : Eina.Content @by_ref; [[Data to copy.]]
seat : uint; [[Seat the data comes from. Use 0 when in doubt.]]
}
}
selection_clear {
[[Clear the selection data from the object]]
[[Clears the current selection.
No data will be available to other applications to paste (until something else is selected).
]]
params {
buffer : Efl.Ui.Cnp_Buffer;
seat : uint;
buffer : Efl.Ui.Cnp_Buffer; [[System buffer to clear.]]
seat : uint; [[Seat to clear. Use 0 when in doubt.]]
}
}
selection_get {
[[Get the data from the object that has selection]]
[[Retrieves the data currently held in the specified buffer.
This is typically used when the user requests a "paste" operation.
This method is time consuming (since data can potentially be provided by another application), therefore,
it is recommended to verify the existence of a selection using @.has_selection before calling it.
]]
params {
buffer : Efl.Ui.Cnp_Buffer;
seat : uint;
acceptable_types : iterator<string>;
buffer : Efl.Ui.Cnp_Buffer; [[System buffer to use.]]
seat : uint; [[Seat where the data should be pasted. Use 0 when in doubt.]]
acceptable_types : iterator<string>; [[List of accepted IANA MIME types:
https://www.iana.org/assignments/media-types/media-types.xhtml
If automatic conversion cannot be provided to any of the accepted
types, an error will be returned.
]]
}
return : future<Eina.Content> @move;
return : future<Eina.Content> @move; [[A future that will be resolved to the requested content, or to an
error if type conversion is not available or the requested buffer
is empty.]]
}
has_selection {
[[Determine whether the selection data has owner]]
[[Checks if the specified system buffer has content.]]
params {
buffer : Efl.Ui.Cnp_Buffer;
seat : uint;
buffer : Efl.Ui.Cnp_Buffer; [[System buffer to query.]]
seat : uint; [[Seat to query. Use 0 when in doubt.]]
}
return : bool; [[$true if there is a available selection, $false if not]]
return : bool; [[$true if there is data available in the requested buffer.]]
}
}
implements {
@ -52,6 +79,7 @@ mixin @beta Efl.Ui.Selection requires Efl.Object {
Efl.Object.finalize;
}
events {
wm_selection,changed : Efl.Ui.Wm_Selection_Changed;
wm_selection,changed : Efl.Ui.Wm_Selection_Changed; [[Event emitted when the content of one of the system's
buffers changes.]]
}
}

23
src/lib/elementary/efl_ui_textbox.eo
View File

@ -1,8 +1,13 @@
enum Efl.Ui.Textbox_Cnp_Content {
Nothing = 0, [[You can paste or drop nothing]]
Text = 1, [[You can paste normal Text]]
Markup = 3, [[You can paste Markup (Normal text is also just markup)]]
Image = 4, [[You can paste Images]]
enum @beta Efl.Ui.Textbox_Cnp_Content {
[[What kind of content can be pasted into this widget using Copy & Paste or Drag & Drop functionality.
Multiple options can be OR-ed together.
]]
Nothing = 0, [[Nothing can be pasted or dropped into this widget.]]
Text = 1, [[Plain text can be pasted or dropped into this widget.]]
Markup = 3, [[Markup text can be pasted or dropped into this widget
(This includes Plain text).]]
Image = 4, [[Images can be pasted or dropped into this widget.]]
}
class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Clickable,
@ -39,18 +44,16 @@ class @beta Efl.Ui.Textbox extends Efl.Ui.Layout_Base implements Efl.Input.Click
}
}
@property cnp_dnd_mode @beta {
[[Control pasting of text and images for the widget.
[[Controls the type of content which can be pasted into the widget.
Normally the entry allows both text and images to be pasted.
Note: This only changes the behaviour of text.
By default, both text and images are allowed..
]]
set {
}
get {
}
values {
allowed_formats : Efl.Ui.Textbox_Cnp_Content; [[Format for cnp]]
allowed_formats : Efl.Ui.Textbox_Cnp_Content; [[Allowed content types.]]
}
}
@property selection_handles_enabled {

11
src/lib/eo/eina_types.eot
View File

@ -60,7 +60,16 @@ struct @extern Eina.Matrix3 {
zz: double; [[ZZ value.]]
}
struct @extern Eina.Content;
struct @extern Eina.Content; [[
Container for any type of content.
Each @Eina.Content is made of an @Eina.Slice of memory and an IANA MIME type:
https://www.iana.org/assignments/media-types/media-types.xhtml
If the type is a text-style type, the last byte of the slice must be \0.
@since 1.24
]]
struct @extern Eina.Matrix4 {
[[A bidimensional array of floating point values with 4 rows and 4 columns.

2
src/modules/ecore_evas/engines/x/ecore_evas_x.c
View File

@ -3794,7 +3794,7 @@ _search_fitting_type(Ecore_Evas *ee, Ecore_Evas_Engine_Data_X11 *edata, Ecore_Ev
if (mime_type == acceptable_type)
HANDLE_TYPE()
//if there is no available type yet, check if we can convert to the desiared type via this type
//if there is no available type yet, check if we can convert to the desired type via this type
if (!found_conversion)
{
const char *convertion_type = NULL;