2 * @defgroup CopyPaste CopyPaste
5 * Implements the following functionality
6 * a. select, copy/cut and paste
9 * in order to share data across application windows.
11 * Contains functions to select text or a portion of data,
12 * send it to a buffer, and paste the data into a target.
14 * elm_cnp provides a generic copy and paste facility based on its windowing system.
15 * It is not necessary to know the details of each windowing system,
16 * but some terms and behavior are common.
17 * Currently the X11 window system is widely used, and only X11 functionality is implemented.
19 * In X11R6 window system, CopyPaste works like a peer-to-peer communication.
20 * Copying is an operation on an object in an X server.
21 * X11 calls those objects 'selections' which have names.
22 * Generally, two selection types are needed for copy and paste:
23 * The Primary selection and the Clipboard selection.
24 * Primary selection is for selecting text (that means highlighted text).
25 * Clipboard selection is for explicit copying behavior
26 * (such as ctrl+c, or 'copy' in a menu).
27 * Thus, in applications most cases only use the clipboard selection.
28 * As stated before, taking ownership of a selection doesn't move any actual data.
29 * Copying and Pasting is described as follows:
30 * 1. Copy text in Program A : Program A takes ownership of the selection
31 * 2. Paste text in Program B : Program B notes that Program A owns the selection
32 * 3. Program B asks A for the text
33 * 4. Program A responds and sends the text to program B
34 * 5. Program B pastes the response
35 * More information is on
36 * - http://www.jwz.org/doc/x-cut-and-paste.html
37 * - X11R6 Inter-Client Communication Conventions Manual, section 2
39 * TODO: add for other window system.
45 * Defines the types of selection property names.
46 * @see http://www.x.org/docs/X11/xlib.pdf
51 ELM_SEL_TYPE_PRIMARY, /**< Primary text selection (highlighted or selected text) */
52 ELM_SEL_TYPE_SECONDARY, /**< Used when primary selection is in use */
53 ELM_SEL_TYPE_XDND, /**< Drag 'n' Drop */
54 ELM_SEL_TYPE_CLIPBOARD, /**< Clipboard selection (ctrl+C) */
58 * Defines the types of content.
62 /** For matching every possible atom */
63 ELM_SEL_FORMAT_TARGETS = -1,
64 /** Content is from outside of Elementary */
65 ELM_SEL_FORMAT_NONE = 0x0,
66 /** Plain unformatted text: Used for things that don't want rich markup */
67 ELM_SEL_FORMAT_TEXT = 0x01,
68 /** Edje textblock markup, including inline images */
69 ELM_SEL_FORMAT_MARKUP = 0x02,
71 ELM_SEL_FORMAT_IMAGE = 0x04,
73 ELM_SEL_FORMAT_VCARD = 0x08,
74 /** Raw HTML-like data (eg. webkit) */
75 ELM_SEL_FORMAT_HTML = 0x10,
79 * Structure holding the info about selected data.
81 struct _Elm_Selection_Data
84 Elm_Sel_Format format;
88 typedef struct _Elm_Selection_Data Elm_Selection_Data;
91 * Callback invoked in when the selected data is 'dropped' at its destination.
93 * @param data Application specific data
94 * @param obj The evas object where selected data is 'dropped'.
95 * @param ev struct holding information about selected data
96 * FIXME: this should probably be a smart callback
98 typedef Eina_Bool (*Elm_Drop_Cb)(void *data, Evas_Object *obj, Elm_Selection_Data *ev);
101 * Callback invoked in when the selection ownership for a given selection is lost.
103 * @param data Application specific data
104 * @param selection The selection that is lost
107 typedef void (*Elm_Selection_Loss_Cb)(void *data, Elm_Sel_Type selection);
111 * @brief Set copy data for a widget.
113 * Set copy data and take ownership of selection. Format is used for specifying the selection type,
114 * and this is used during pasting.
116 * @param selection Selection type for copying and pasting
117 * @param obj The source widget pointer
118 * @param format Selection format
119 * @param buf The data selected
120 * @param buflen The size of @p buf
121 * @return If EINA_TRUE, setting data was successful.
126 EAPI Eina_Bool elm_cnp_selection_set(Evas_Object *obj, Elm_Sel_Type selection,
127 Elm_Sel_Format format,
128 const void *buf, size_t buflen);
131 * @brief Retrieve data from a widget that has a selection.
133 * Gets the current selection data from a widget.
134 * The widget input here will usually be elm_entry,
135 * in which case @p datacb and @p udata can be NULL.
136 * If a different widget is passed, @p datacb and @p udata are used for retrieving data.
138 * @see also elm_cnp_selection_set()
140 * @param selection Selection type for copying and pasting
141 * @param format Selection format
142 * @param obj The source widget
143 * @param datacb The user data callback if the target widget isn't elm_entry
144 * @param udata The user data pointer for @p datacb
145 * @return If EINA_TRUE, getting selection data was successful.
149 EAPI Eina_Bool elm_cnp_selection_get(Evas_Object *obj, Elm_Sel_Type selection,
150 Elm_Sel_Format format,
151 Elm_Drop_Cb datacb, void *udata);
154 * @brief Clear the selection data of a widget.
156 * Clear all data from the selection which is owned by a widget.
158 * @see also elm_cnp_selection_set()
160 * @param obj The source widget
161 * @param selection Selection type for copying and pasting
162 * @return If EINA_TRUE, clearing data was successful.
167 EAPI Eina_Bool elm_object_cnp_selection_clear(Evas_Object *obj,
168 Elm_Sel_Type selection);
172 * @brief Set a function to be called when a selection is lost
174 * The function @p func is set of be called when selection @p selection is lost
175 * to another process or when elm_cnp_selection_set() is called. If @p func
176 * is NULL then it is not called. @p data is passed as the data parameter to
177 * the callback functions and selection is passed in as the selection that
180 * elm_cnp_selection_set() and elm_object_cnp_selection_clear() automatically
181 * set this los callback to NULL when called. If you wish to take the selection
182 * and then be notified of loss please do this (for example):
185 * elm_cnp_selection_set(obj, ELM_SEL_TYPE_PRIMARY, ELM_SEL_FORMAT_TEXT, "hello", strlen(hello));
186 * elm_cnp_selection_loss_callback_set(obj, ELM_SEL_TYPE_PRIMARY, loss_cb, NULL);
189 * @see also elm_cnp_selection_set()
191 * @param obj The object to indicate the window target/display system.
192 * @param selection Selection to be notified of for loss
193 * @param func The function to call
194 * @param data The data pointer passed to the function.
200 EAPI void elm_cnp_selection_loss_callback_set(Evas_Object *obj, Elm_Sel_Type selection, Elm_Selection_Loss_Cb func, const void *data);