src/lib/elm_cnp.h

   1 /**
   2  * @defgroup CopyPaste CopyPaste
   3  *
   4  * Implements the following functionality
   5  *    a. select, copy/cut and paste
   6  *    b. clipboard
   7  *    c. drag and drop
   8  * in order to share data across application windows.
   9  *
  10  * Contains functions to select text or a portion of data,
  11  * send it to a buffer, and paste the data into a target.
  12  *
  13  * elm_cnp provides a generic copy and paste facility based on its windowing system.
  14  * It is not necessary to know the details of each windowing system,
  15  * but some terms and behavior are common.
  16  * Currently the X11 window system is widely used, and only X11 functionality is implemented.
  17  *
  18  * In X11R6 window system, CopyPaste works like a peer-to-peer communication.
  19  * Copying is an operation on an object in an X server.
  20  * X11 calls those objects 'selections' which have names.
  21  * Generally, two selection types are needed for copy and paste:
  22  * The Primary selection and the Clipboard selection.
  23  * Primary selection is for selecting text (that means highlighted text).
  24  * Clipboard selection is for explicit copying behavior
  25  * (such as ctrl+c, or 'copy' in a menu).
  26  * Thus, in applications most cases only use the clipboard selection.
  27  * As stated before, taking ownership of a selection doesn't move any actual data.
  28  * Copying and Pasting is described as follows:
  29  *  1. Copy text in Program A : Program A takes ownership of the selection
  30  *  2. Paste text in Program B : Program B notes that Program A owns the selection
  31  *  3. Program B asks A for the text
  32  *  4. Program A responds and sends the text to program B
  33  *  5. Program B pastes the response
  34  * More information is on
  35  *  - http://www.jwz.org/doc/x-cut-and-paste.html
  36  *  - X11R6 Inter-Client Communication Conventions Manual, section 2
  37  *
  38  * TODO: add for other window system.
  39  *
  40  * @{
  41  */
  42
  43 /**
  44  * Defines the types of selection property names.
  45  * @see http://www.x.org/docs/X11/xlib.pdf
  46  * for more details.
  47  */
  48 typedef enum
  49 {
  50    ELM_SEL_TYPE_PRIMARY, /**< Primary text selection (highlighted or selected text) */
  51    ELM_SEL_TYPE_SECONDARY, /**< Used when primary selection is in use */
  52    ELM_SEL_TYPE_XDND, /**< Drag 'n' Drop */
  53    ELM_SEL_TYPE_CLIPBOARD, /**< Clipboard selection (ctrl+C) */
  54 } Elm_Sel_Type;
  55
  56 /**
  57  * Defines the types of content.
  58  */
  59 typedef enum
  60 {
  61    /** For matching every possible atom */
  62    ELM_SEL_FORMAT_TARGETS =   -1,
  63    /** Content is from outside of Elementary */
  64    ELM_SEL_FORMAT_NONE    =  0x0,
  65    /** Plain unformatted text: Used for things that don't want rich markup */
  66    ELM_SEL_FORMAT_TEXT    = 0x01,
  67    /** Edje textblock markup, including inline images */
  68    ELM_SEL_FORMAT_MARKUP  = 0x02,
  69    /** Images */
  70    ELM_SEL_FORMAT_IMAGE   = 0x04,
  71    /** Vcards */
  72    ELM_SEL_FORMAT_VCARD   = 0x08,
  73    /** Raw HTML-like data (eg. webkit) */
  74    ELM_SEL_FORMAT_HTML    = 0x10,
  75 } Elm_Sel_Format;
  76
  77 /**
  78  * Structure holding the info about selected data.
  79  */
  80 struct _Elm_Selection_Data
  81 {
  82    Evas_Coord     x, y;
  83    Elm_Sel_Format format;
  84    void          *data;
  85    size_t         len;
  86 };
  87 typedef struct _Elm_Selection_Data Elm_Selection_Data;
  88
  89 /**
  90  * Callback invoked in when the selected data is 'dropped' at its destination.
  91  *
  92  * @param data Application specific data
  93  * @param obj The evas object where selected data is 'dropped'.
  94  * @param ev struct holding information about selected data
  95  * FIXME: this should probably be a smart callback
  96  */
  97 typedef Eina_Bool (*Elm_Drop_Cb)(void *data, Evas_Object *obj, Elm_Selection_Data *ev);
  98
  99
 100 /**
 101  * @brief Set copy data for a widget.
 102  *
 103  * Set copy data and take ownership of selection. Format is used for specifying the selection type,
 104  * and this is used during pasting.
 105  *
 106  * @param selection Selection type for copying and pasting
 107  * @param obj The source widget pointer
 108  * @param format Selection format
 109  * @param buf The data selected
 110  * @param buflen The size of @p buf
 111  * @return If EINA_TRUE, setting data was successful.
 112  *
 113  * @ingroup CopyPaste
 114  *
 115  */
 116 EAPI Eina_Bool elm_cnp_selection_set(Evas_Object *obj, Elm_Sel_Type selection,
 117                                      Elm_Sel_Format format,
 118                                      const void *buf, size_t buflen);
 119
 120 /**
 121  * @brief Retrieve data from a widget that has a selection.
 122  *
 123  * Gets the current selection data from a widget.
 124  * The widget input here will usually be elm_entry,
 125  * in which case @p datacb and @p udata can be NULL.
 126  * If a different widget is passed, @p datacb and @p udata are used for retrieving data.
 127  *
 128  * @see also elm_cnp_selection_set()
 129  *
 130  * @param selection Selection type for copying and pasting
 131  * @param format Selection format
 132  * @param obj The source widget
 133  * @param datacb The user data callback if the target widget isn't elm_entry
 134  * @param udata The user data pointer for @p datacb
 135  * @return If EINA_TRUE, getting selection data was successful.
 136  *
 137  * @ingroup CopyPaste
 138  */
 139 EAPI Eina_Bool elm_cnp_selection_get(Evas_Object *obj, Elm_Sel_Type selection,
 140                                      Elm_Sel_Format format,
 141                                      Elm_Drop_Cb datacb, void *udata);
 142
 143 /**
 144  * @brief Clear the selection data of a widget.
 145  *
 146  * Clear all data from the selection which is owned by a widget.
 147  *
 148  * @see also elm_cnp_selection_set()
 149  *
 150  * @param obj The source widget
 151  * @param selection Selection type for copying and pasting
 152  * @return If EINA_TRUE, clearing data was successful.
 153  *
 154  * @ingroup CopyPaste
 155  *
 156  */
 157 EAPI Eina_Bool elm_object_cnp_selection_clear(Evas_Object *obj,
 158                                               Elm_Sel_Type selection);
 159
 160 /**
 161  * @}
 162  */