src/lib/elm_cnp.h

   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  * Callback invoked in when the selection ownership for a given selection is lost.
 102  *
 103  * @param data Application specific data
 104  * @param selection The selection that is lost
 105  * @since 1.7
 106  */
 107 typedef void (*Elm_Selection_Loss_Cb)(void *data, Elm_Sel_Type selection);
 108
 109
 110 /**
 111  * @brief Set copy data for a widget.
 112  *
 113  * Set copy data and take ownership of selection. Format is used for specifying the selection type,
 114  * and this is used during pasting.
 115  *
 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.
 122  *
 123  * @ingroup CopyPaste
 124  *
 125  */
 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);
 129
 130 /**
 131  * @brief Retrieve data from a widget that has a selection.
 132  *
 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.
 137  *
 138  * @see also elm_cnp_selection_set()
 139  *
 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.
 146  *
 147  * @ingroup CopyPaste
 148  */
 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);
 152
 153 /**
 154  * @brief Clear the selection data of a widget.
 155  *
 156  * Clear all data from the selection which is owned by a widget.
 157  *
 158  * @see also elm_cnp_selection_set()
 159  *
 160  * @param obj The source widget
 161  * @param selection Selection type for copying and pasting
 162  * @return If EINA_TRUE, clearing data was successful.
 163  *
 164  * @ingroup CopyPaste
 165  *
 166  */
 167 EAPI Eina_Bool elm_object_cnp_selection_clear(Evas_Object *obj,
 168                                               Elm_Sel_Type selection);
 169
 170
 171 /**
 172  * @brief Set a function to be called when a selection is lost
 173  *
 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
 178  * has been lost.
 179  *
 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):
 183  *
 184  * @code
 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);
 187  * @endcode
 188  *
 189  * @see also elm_cnp_selection_set()
 190  *
 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.
 195  *
 196  * @ingroup CopyPaste
 197  *
 198  * @since 1.7
 199  */
 200 EAPI void elm_cnp_selection_loss_callback_set(Evas_Object *obj, Elm_Sel_Type selection, Elm_Selection_Loss_Cb func, const void *data);
 201
 202 /**
 203  * @}
 204  */