src/lib/elm_cnp.h

   1 /**
   2  * @defgroup CopyPaste
   3  *
   4  * Implement the copy and paste + clipboard functionality, in order to
   5  * share data across application windows.
   6  *
   7  * Contains functions to select a portion of text, stick it to a clipboard
   8  * and to paste the selection to an appropriate place.
   9  *
  10  *
  11  *
  12  * @{
  13  */
  14
  15 /**
  16  * Defines the types of selection property names.
  17  * Kindly refer to http://www.x.org/docs/X11/xlib.pdf
  18  * for more details.
  19  */
  20 typedef enum
  21 {
  22    ELM_SEL_TYPE_PRIMARY, // refers to primary text selection
  23    ELM_SEL_TYPE_SECONDARY, // used when primary selection is in use.
  24    ELM_SEL_TYPE_XDND, // drag and drop
  25    ELM_SEL_TYPE_CLIPBOARD, // selected text
  26 } Elm_Sel_Type;
  27
  28 /**
  29  * Defines the types of target.
  30  */
  31 typedef enum
  32 {
  33    /** Targets: for matching every atom requesting */
  34    ELM_SEL_FORMAT_TARGETS = -1,
  35    /** they come from outside of elm */
  36    ELM_SEL_FORMAT_NONE = 0x0,
  37    /** Plain unformatted text: Used for things that don't want rich markup */
  38    ELM_SEL_FORMAT_TEXT = 0x01,
  39    /** Edje textblock markup, including inline images */
  40    ELM_SEL_FORMAT_MARKUP = 0x02,
  41    /** Images */
  42    ELM_SEL_FORMAT_IMAGE = 0x04,
  43    /** Vcards */
  44    ELM_SEL_FORMAT_VCARD = 0x08,
  45    /** Raw HTML-like things for widgets that want that stuff (hello webkit!) */
  46    ELM_SEL_FORMAT_HTML = 0x10,
  47 } Elm_Sel_Format;
  48
  49 /**
  50  * Structure holding the info about selected data.
  51  */
  52 struct _Elm_Selection_Data
  53 {
  54    Evas_Coord     x, y;
  55    Elm_Sel_Format format;
  56    void          *data;
  57    size_t         len;
  58 };
  59 typedef struct _Elm_Selection_Data Elm_Selection_Data;
  60
  61 /**
  62  * Callback invoked in when the selected data is 'dropped' at its destination.
  63  *
  64  * @param d Application specific data
  65  * @param o The evas object where selected data is 'dropped'.
  66  * @param data struct holding information about selected data
  67  */
  68 typedef Eina_Bool (*Elm_Drop_Cb)(void *d, Evas_Object *o, Elm_Selection_Data *data);
  69
  70
  71 /**
  72  * @brief Set copy and paste data to a widget.
  73  *
  74  * XXX: need to be rewritten.
  75  * Append the given callback to the list. This functions will be called.
  76  *
  77  * @param selection Selection type for copying and pasting
  78  * @param obj The source widget pointer
  79  * @param format Type of selection format
  80  * @param buf The pointer of data source
  81  * @param buflen The size of @c buf
  82  * @return If EINA_TRUE, setting data is success.
  83  *
  84  * @ingroup CopyPaste
  85  *
  86  */
  87 // XXX: EAPI void elm_object_cnp_selection_set(Evas_Object *obj, Elm_Sel_Type selection,
  88 //                                             Elm_Sel_Format format, const void *buf,
  89 //                                             size_t buflen);
  90 EAPI Eina_Bool elm_cnp_selection_set(Elm_Sel_Type selection, Evas_Object *obj,
  91                                      Elm_Sel_Format format, const void *buf,
  92                                      size_t buflen);
  93
  94 /**
  95  * @brief Retrieve the copy and paste data from the widget.
  96  *
  97  * Gets the data from the widget which is set for copying and pasting.
  98  * Mainly the widget is elm_entry. If then @p datacb and @p udata can be NULL.
  99  * If not, @p datacb and @p udata are used for retrieving data.
 100  *
 101  * @see also elm_cnp_selection_set()
 102  *
 103  * @param selection Selection type for copying and pasting
 104  * @param format Type of selection format
 105  * @param obj The source widget pointer
 106  * @param datacb The user data callback if the target widget isn't elm_entry
 107  * @param udata The user data pointer for @p datacb
 108  * @return If EINA_TRUE, getting data is success.
 109  *
 110  * @ingroup CopyPaste
 111  *
 112  */
 113 // XXX: This api needs to be refined by cnp experts.
 114 //      I suggest:
 115 //         1. return copy and paste data.
 116 //         2. call cnp callback regardless of widget type.
 117 //         3. apps insert text data into entry manually.
 118 // XXX: EAPI void *elm_object_cnp_selection_get(Evas_Object *obj,
 119 //                                              Elm_Sel_Type selection,
 120 //                                              Elm_Sel_Format format,
 121 //                                              Elm_Cnp_Cb datacb);
 122 EAPI Eina_Bool elm_cnp_selection_get(Elm_Sel_Type selection,
 123                                      Elm_Sel_Format format, Evas_Object *obj,
 124                                      Elm_Drop_Cb datacb, void *udata);
 125
 126 /**
 127  * @brief Clear the selected/copied data in the widget.
 128  *
 129  * @see also elm_cnp_selection_set()
 130  *
 131  * @param obj The source widget pointer
 132  * @param selection Selection type for copying and pasting
 133  * @return If EINA_TRUE, clearing data is success.
 134  *
 135  * @ingroup CopyPaste
 136  *
 137  */
 138 EAPI Eina_Bool elm_object_cnp_selection_clear(Evas_Object *obj,
 139                                                Elm_Sel_Type selection);
 140
 141 /**
 142  * @}
 143  */