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 /**
 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  */