diff options
author | Xavi Artigas <xavierartigas@yahoo.es> | 2020-03-03 11:12:08 +0100 |
---|---|---|
committer | Marcel Hollerbach <mail@marcel-hollerbach.de> | 2020-03-08 11:01:18 +0100 |
commit | 645c3d41ebd4b446c45e17a60fddf60302481bcc (patch) | |
tree | 88f2e79aa9fa24844a1f9cc7ea90876fdfcc1e03 | |
parent | 7dd92a2d98b983557fc4ce21f8d5740e81fa2a74 (diff) | |
download | efl-645c3d41ebd4b446c45e17a60fddf60302481bcc.tar.gz |
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
-rw-r--r-- | src/lib/ecore_evas/Ecore_Evas.h | 2 | ||||
-rw-r--r-- | src/lib/eina/eina_abstract_content.h | 68 | ||||
-rw-r--r-- | src/lib/elementary/efl_ui_dnd.eo | 82 | ||||
-rw-r--r-- | src/lib/elementary/efl_ui_selection.eo | 74 | ||||
-rw-r--r-- | src/lib/elementary/efl_ui_textbox.eo | 23 | ||||
-rw-r--r-- | src/lib/eo/eina_types.eot | 11 | ||||
-rw-r--r-- | src/modules/ecore_evas/engines/x/ecore_evas_x.c | 2 |
7 files changed, 163 insertions, 99 deletions
diff --git a/src/lib/ecore_evas/Ecore_Evas.h b/src/lib/ecore_evas/Ecore_Evas.h index ddc3622741..713ad9748f 100644 --- a/src/lib/ecore_evas/Ecore_Evas.h +++ b/src/lib/ecore_evas/Ecore_Evas.h @@ -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. */ diff --git a/src/lib/eina/eina_abstract_content.h b/src/lib/eina/eina_abstract_content.h index 1436543f4e..9b723d553f 100644 --- a/src/lib/eina/eina_abstract_content.h +++ b/src/lib/eina/eina_abstract_content.h @@ -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); diff --git a/src/lib/elementary/efl_ui_dnd.eo b/src/lib/elementary/efl_ui_dnd.eo index 8ef19110d5..49ef148723 100644 --- a/src/lib/elementary/efl_ui_dnd.eo +++ b/src/lib/elementary/efl_ui_dnd.eo @@ -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; diff --git a/src/lib/elementary/efl_ui_selection.eo b/src/lib/elementary/efl_ui_selection.eo index 492e60e117..7e0814d348 100644 --- a/src/lib/elementary/efl_ui_selection.eo +++ b/src/lib/elementary/efl_ui_selection.eo @@ -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.]] } } diff --git a/src/lib/elementary/efl_ui_textbox.eo b/src/lib/elementary/efl_ui_textbox.eo index ff0898b6fc..2605c477a3 100644 --- a/src/lib/elementary/efl_ui_textbox.eo +++ b/src/lib/elementary/efl_ui_textbox.eo @@ -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. - - Normally the entry allows both text and images to be pasted. + [[Controls the type of content which can be pasted into the widget. - 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 { diff --git a/src/lib/eo/eina_types.eot b/src/lib/eo/eina_types.eot index 106aa0885d..000a2567d9 100644 --- a/src/lib/eo/eina_types.eot +++ b/src/lib/eo/eina_types.eot @@ -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. diff --git a/src/modules/ecore_evas/engines/x/ecore_evas_x.c b/src/modules/ecore_evas/engines/x/ecore_evas_x.c index d689a5622c..36afeb5495 100644 --- a/src/modules/ecore_evas/engines/x/ecore_evas_x.c +++ b/src/modules/ecore_evas/engines/x/ecore_evas_x.c @@ -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; |