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 a portion of text, send it to a buffer,
  11  * and paste the selection into a target.
  12  *
  13  * @{
  14  */
  15
  16 /**
  17  * Defines the types of selection property names.
  18  * @see http://www.x.org/docs/X11/xlib.pdf
  19  * for more details.
  20  */
  21 typedef enum
  22 {
  23    ELM_SEL_TYPE_PRIMARY, /**< Primary text selection (middle mouse) */
  24    ELM_SEL_TYPE_SECONDARY, /**< Used when primary selection is in use */
  25    ELM_SEL_TYPE_XDND, /**< Drag 'n' Drop */
  26    ELM_SEL_TYPE_CLIPBOARD, /**< Clipboard selection (ctrl+C)
  27 } Elm_Sel_Type;
  28
  29 /**
  30  * Defines the types of content.
  31  */
  32 typedef enum
  33 {
  34    /** For matching every possible atom */
  35    ELM_SEL_FORMAT_TARGETS = -1,
  36    /** Content is from outside of Elementary */
  37    ELM_SEL_FORMAT_NONE = 0x0,
  38    /** Plain unformatted text: Used for things that don't want rich markup */
  39    ELM_SEL_FORMAT_TEXT = 0x01,
  40    /** Edje textblock markup, including inline images */
  41    ELM_SEL_FORMAT_MARKUP = 0x02,
  42    /** Images */
  43    ELM_SEL_FORMAT_IMAGE = 0x04,
  44    /** Vcards */
  45    ELM_SEL_FORMAT_VCARD = 0x08,
  46    /** Raw HTML-like data (eg. webkit) */
  47    ELM_SEL_FORMAT_HTML = 0x10,
  48 } Elm_Sel_Format;
  49
  50 /**
  51  * Structure holding the info about selected data.
  52  */
  53 struct _Elm_Selection_Data
  54 {
  55    Evas_Coord     x, y;
  56    Elm_Sel_Format format;
  57    void          *data;
  58    size_t         len;
  59 };
  60 typedef struct _Elm_Selection_Data Elm_Selection_Data;
  61
  62 /**
  63  * Callback invoked in when the selected data is 'dropped' at its destination.
  64  *
  65  * @param data Application specific data
  66  * @param obj The evas object where selected data is 'dropped'.
  67  * @param ev struct holding information about selected data
  68  * FIXME: this should probably be a smart callback
  69  */
  70 typedef Eina_Bool (*Elm_Drop_Cb)(void *data, Evas_Object *obj, Elm_Selection_Data *ev);
  71
  72
  73 /**
  74  * @brief Set copy and paste data for a widget.
  75  *
  76  * XXX: need to be rewritten.
  77  * Append the given callback to the list.
  78  *
  79  * @param selection Selection type for copying and pasting
  80  * @param obj The source widget pointer
  81  * @param format Selection format
  82  * @param buf The data selected
  83  * @param buflen The size of @p buf
  84  * @return If EINA_TRUE, setting data was successful.
  85  *
  86  * @ingroup CopyPaste
  87  *
  88  */
  89 // XXX: EAPI void elm_object_cnp_selection_set(Evas_Object *obj, Elm_Sel_Type selection,
  90 //                                             Elm_Sel_Format format, const void *buf,
  91 //                                             size_t buflen);
  92 EAPI Eina_Bool elm_cnp_selection_set(Elm_Sel_Type selection, Evas_Object *obj,
  93                                      Elm_Sel_Format format, const void *buf,
  94                                      size_t buflen);
  95
  96 /**
  97  * @brief Retrieve selection data from a widget.
  98  *
  99  * Gets the current selection data from a widget.
 100  * The widget input here will usually be elm_entry,
 101  * in which case @p datacb and @p udata can be NULL.
 102  * If a different widget is passed, @p datacb and @p udata are used for retrieving data.
 103  *
 104  * @see also elm_cnp_selection_set()
 105  *
 106  * @param selection Selection type for copying and pasting
 107  * @param format Selection format
 108  * @param obj The source widget
 109  * @param datacb The user data callback if the target widget isn't elm_entry
 110  * @param udata The user data pointer for @p datacb
 111  * @return If EINA_TRUE, getting selection data was successful.
 112  *
 113  * @ingroup CopyPaste
 114  *
 115  */
 116 // XXX: This api needs to be refined by cnp experts.
 117 //      I suggest:
 118 //         1. return copy and paste data.
 119 //         2. call cnp callback regardless of widget type.
 120 //         3. apps insert text data into entry manually.
 121 // XXX: EAPI void *elm_object_cnp_selection_get(Evas_Object *obj,
 122 //                                              Elm_Sel_Type selection,
 123 //                                              Elm_Sel_Format format,
 124 //                                              Elm_Cnp_Cb datacb);
 125 EAPI Eina_Bool elm_cnp_selection_get(Elm_Sel_Type selection,
 126                                      Elm_Sel_Format format, Evas_Object *obj,
 127                                      Elm_Drop_Cb datacb, void *udata);
 128
 129 /**
 130  * @brief Clear the selection data of a widget.
 131  *
 132  * @see also elm_cnp_selection_set()
 133  *
 134  * @param obj The source widget
 135  * @param selection Selection type for copying and pasting
 136  * @return If EINA_TRUE, clearing data was successful.
 137  *
 138  * @ingroup CopyPaste
 139  *
 140  */
 141 EAPI Eina_Bool elm_object_cnp_selection_clear(Evas_Object *obj,
 142                                                Elm_Sel_Type selection);
 143
 144 /**
 145  * @}
 146  */