diff options
Diffstat (limited to '')
-rw-r--r-- | libraries/elementary/src/lib/elm_cnp.h | 163 |
1 files changed, 163 insertions, 0 deletions
diff --git a/libraries/elementary/src/lib/elm_cnp.h b/libraries/elementary/src/lib/elm_cnp.h new file mode 100644 index 0000000..2b45c91 --- /dev/null +++ b/libraries/elementary/src/lib/elm_cnp.h | |||
@@ -0,0 +1,163 @@ | |||
1 | /** | ||
2 | * @defgroup CopyPaste CopyPaste | ||
3 | * @ingroup Elementary | ||
4 | * | ||
5 | * Implements the following functionality | ||
6 | * a. select, copy/cut and paste | ||
7 | * b. clipboard | ||
8 | * c. drag and drop | ||
9 | * in order to share data across application windows. | ||
10 | * | ||
11 | * Contains functions to select text or a portion of data, | ||
12 | * send it to a buffer, and paste the data into a target. | ||
13 | * | ||
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. | ||
18 | * | ||
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 | ||
38 | * | ||
39 | * TODO: add for other window system. | ||
40 | * | ||
41 | * @{ | ||
42 | */ | ||
43 | |||
44 | /** | ||
45 | * Defines the types of selection property names. | ||
46 | * @see http://www.x.org/docs/X11/xlib.pdf | ||
47 | * for more details. | ||
48 | */ | ||
49 | typedef enum | ||
50 | { | ||
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) */ | ||
55 | } Elm_Sel_Type; | ||
56 | |||
57 | /** | ||
58 | * Defines the types of content. | ||
59 | */ | ||
60 | typedef enum | ||
61 | { | ||
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, | ||
70 | /** Images */ | ||
71 | ELM_SEL_FORMAT_IMAGE = 0x04, | ||
72 | /** Vcards */ | ||
73 | ELM_SEL_FORMAT_VCARD = 0x08, | ||
74 | /** Raw HTML-like data (eg. webkit) */ | ||
75 | ELM_SEL_FORMAT_HTML = 0x10, | ||
76 | } Elm_Sel_Format; | ||
77 | |||
78 | /** | ||
79 | * Structure holding the info about selected data. | ||
80 | */ | ||
81 | struct _Elm_Selection_Data | ||
82 | { | ||
83 | Evas_Coord x, y; | ||
84 | Elm_Sel_Format format; | ||
85 | void *data; | ||
86 | size_t len; | ||
87 | }; | ||
88 | typedef struct _Elm_Selection_Data Elm_Selection_Data; | ||
89 | |||
90 | /** | ||
91 | * Callback invoked in when the selected data is 'dropped' at its destination. | ||
92 | * | ||
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 | ||
97 | */ | ||
98 | typedef Eina_Bool (*Elm_Drop_Cb)(void *data, Evas_Object *obj, Elm_Selection_Data *ev); | ||
99 | |||
100 | |||
101 | /** | ||
102 | * @brief Set copy data for a widget. | ||
103 | * | ||
104 | * Set copy data and take ownership of selection. Format is used for specifying the selection type, | ||
105 | * and this is used during pasting. | ||
106 | * | ||
107 | * @param selection Selection type for copying and pasting | ||
108 | * @param obj The source widget pointer | ||
109 | * @param format Selection format | ||
110 | * @param buf The data selected | ||
111 | * @param buflen The size of @p buf | ||
112 | * @return If EINA_TRUE, setting data was successful. | ||
113 | * | ||
114 | * @ingroup CopyPaste | ||
115 | * | ||
116 | */ | ||
117 | EAPI Eina_Bool elm_cnp_selection_set(Evas_Object *obj, Elm_Sel_Type selection, | ||
118 | Elm_Sel_Format format, | ||
119 | const void *buf, size_t buflen); | ||
120 | |||
121 | /** | ||
122 | * @brief Retrieve data from a widget that has a selection. | ||
123 | * | ||
124 | * Gets the current selection data from a widget. | ||
125 | * The widget input here will usually be elm_entry, | ||
126 | * in which case @p datacb and @p udata can be NULL. | ||
127 | * If a different widget is passed, @p datacb and @p udata are used for retrieving data. | ||
128 | * | ||
129 | * @see also elm_cnp_selection_set() | ||
130 | * | ||
131 | * @param selection Selection type for copying and pasting | ||
132 | * @param format Selection format | ||
133 | * @param obj The source widget | ||
134 | * @param datacb The user data callback if the target widget isn't elm_entry | ||
135 | * @param udata The user data pointer for @p datacb | ||
136 | * @return If EINA_TRUE, getting selection data was successful. | ||
137 | * | ||
138 | * @ingroup CopyPaste | ||
139 | */ | ||
140 | EAPI Eina_Bool elm_cnp_selection_get(Evas_Object *obj, Elm_Sel_Type selection, | ||
141 | Elm_Sel_Format format, | ||
142 | Elm_Drop_Cb datacb, void *udata); | ||
143 | |||
144 | /** | ||
145 | * @brief Clear the selection data of a widget. | ||
146 | * | ||
147 | * Clear all data from the selection which is owned by a widget. | ||
148 | * | ||
149 | * @see also elm_cnp_selection_set() | ||
150 | * | ||
151 | * @param obj The source widget | ||
152 | * @param selection Selection type for copying and pasting | ||
153 | * @return If EINA_TRUE, clearing data was successful. | ||
154 | * | ||
155 | * @ingroup CopyPaste | ||
156 | * | ||
157 | */ | ||
158 | EAPI Eina_Bool elm_object_cnp_selection_clear(Evas_Object *obj, | ||
159 | Elm_Sel_Type selection); | ||
160 | |||
161 | /** | ||
162 | * @} | ||
163 | */ | ||