src/lib/elm_widget_layout.h

   1 #ifndef ELM_WIDGET_LAYOUT_H
   2 #define ELM_WIDGET_LAYOUT_H
   3
   4 #include "elm_widget_container.h"
   5
   6 /**
   7  * @addtogroup Widget
   8  * @{
   9  *
  10  * @section elm-layout-class The Elementary Layout Class
  11  *
  12  * Elementary, besides having the @ref Layout widget, exposes its
  13  * foundation -- the Elementary Layout Class -- in order to create
  14  * other widgets which are, basically, a certain layout with some more
  15  * logic on top.
  16  *
  17  * The idea is to make the creation of that widgets as easy as possible,
  18  * factorizing code on this common base. For example, a button is a
  19  * layout (that looks like push button) that happens to react on
  20  * clicks and keyboard events in a special manner, calling its user
  21  * back on those events. That's no surprise, then, that the @ref
  22  * Button implementation relies on #Elm_Layout_Smart_Class, if you go
  23  * to check it.
  24  *
  25  * The Layout class inherits from
  26  * #Elm_Container_Smart_Class. Container parts, here, map directly to
  27  * Edje parts from the layout's Edje group. Besides that, there's a whole
  28  * infrastructure around Edje files:
  29  * - interfacing by signals,
  30  * - setting/retrieving text part values,
  31  * - dealing with table and box parts directly,
  32  * - etc.
  33  *
  34  * Take a look at #Elm_Layout_Smart_Class's 'virtual' functions to
  35  * understand the whole interface. Finally, layout objects will do
  36  * <b>part aliasing</b> for you, if you set it up properly. For that,
  37  * take a look at #Elm_Layout_Part_Alias_Description, where it's
  38  * explained in detail.
  39  */
  40
  41 /**
  42  * @def ELM_LAYOUT_CLASS
  43  *
  44  * Use this macro to cast whichever subclass of
  45  * #Elm_Layout_Smart_Class into it, so to access its fields.
  46  *
  47  * @ingroup Widget
  48  */
  49 #define ELM_LAYOUT_CLASS(x) ((Elm_Layout_Smart_Class *) x)
  50
  51 /**
  52  * @def ELM_LAYOUT_DATA
  53  *
  54  * Use this macro to cast whichever subdata of
  55  * #Elm_Layout_Smart_Data into it, so to access its fields.
  56  *
  57  * @ingroup Widget
  58  */
  59 #define ELM_LAYOUT_DATA(x) ((Elm_Layout_Smart_Data *) x)
  60
  61 /**
  62  * @def ELM_LAYOUT_SMART_CLASS_VERSION
  63  *
  64  * Current version for Elementary layout @b base smart class, a value
  65  * which goes to _Elm_Layout_Smart_Class::version.
  66  *
  67  * @ingroup Widget
  68  */
  69 #define ELM_LAYOUT_SMART_CLASS_VERSION 1
  70
  71 /**
  72  * @def ELM_LAYOUT_SMART_CLASS_INIT
  73  *
  74  * Initializer for a whole #Elm_Layout_Smart_Class structure, with
  75  * @c NULL values on its specific fields.
  76  *
  77  * @param smart_class_init initializer to use for the "base" field
  78  * (#Evas_Smart_Class).
  79  *
  80  * @see EVAS_SMART_CLASS_INIT_NULL
  81  * @see EVAS_SMART_CLASS_INIT_NAME_VERSION
  82  * @see ELM_LAYOUT_SMART_CLASS_INIT_NULL
  83  * @see ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION
  84  *
  85  * @ingroup Widget
  86  */
  87 #define ELM_LAYOUT_SMART_CLASS_INIT(smart_class_init)                        \
  88   {smart_class_init, ELM_LAYOUT_SMART_CLASS_VERSION, NULL, NULL, NULL, NULL, \
  89    NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL, NULL,   \
  90    NULL}
  91
  92 /**
  93  * @def ELM_LAYOUT_SMART_CLASS_INIT_NULL
  94  *
  95  * Initializer to zero out a whole #Elm_Layout_Smart_Class structure.
  96  *
  97  * @see ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION
  98  * @see ELM_LAYOUT_SMART_CLASS_INIT
  99  *
 100  * @ingroup Widget
 101  */
 102 #define ELM_LAYOUT_SMART_CLASS_INIT_NULL \
 103   ELM_LAYOUT_SMART_CLASS_INIT(EVAS_SMART_CLASS_INIT_NULL)
 104
 105 /**
 106  * @def ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION
 107  *
 108  * Initializer to zero out a whole #Elm_Layout_Smart_Class structure and
 109  * set its name and version.
 110  *
 111  * This is similar to #ELM_LAYOUT_SMART_CLASS_INIT_NULL, but it will
 112  * also set the version field of #Elm_Layout_Smart_Class (base field)
 113  * to the latest #ELM_LAYOUT_SMART_CLASS_VERSION and name it to the
 114  * specific value.
 115  *
 116  * It will keep a reference to the name field as a <c>"const char *"</c>,
 117  * i.e., the name must be available while the structure is
 118  * used (hint: static or global variable!) and must not be modified.
 119  *
 120  * @see ELM_LAYOUT_SMART_CLASS_INIT_NULL
 121  * @see ELM_LAYOUT_SMART_CLASS_INIT
 122  *
 123  * @ingroup Widget
 124  */
 125 #define ELM_LAYOUT_SMART_CLASS_INIT_NAME_VERSION(name) \
 126   ELM_LAYOUT_SMART_CLASS_INIT                          \
 127     (ELM_CONTAINER_SMART_CLASS_INIT_NAME_VERSION(name))
 128
 129 /**
 130  * @typedef Elm_Layout_Part_Alias_Description
 131  *
 132  * A layout part aliasing (proxying) description, used to get part
 133  * names aliasing independently of a widgets theme.
 134  *
 135  * @ingroup Widget
 136  */
 137 typedef struct _Elm_Layout_Part_Alias_Description Elm_Layout_Part_Alias_Description;
 138
 139 /**
 140  * @struct _Elm_Layout_Part_Alias_Description
 141  *
 142  * Elementary Layout-based widgets may declare part proxies, i.e., aliases
 143  * for real theme part names to expose to the API calls:
 144  * - elm_layout_text_set()
 145  * - elm_layout_text_get()
 146  * - elm_layout_content_set()
 147  * - elm_layout_content_get()
 148  * - elm_layout_content_unset()
 149  * and their equivalents. This list must be set on the
 150  * @c "_smart_set_user()" function of inheriting widgets, so that part
 151  * aliasing is handled automatically for them.
 152  *
 153  * @ingroup Widget
 154  */
 155 struct _Elm_Layout_Part_Alias_Description
 156 {
 157    const char *alias; /**< Alternate name for a given (real) part. Calls receiving this string as a part name will be translated to the string at _Elm_Layout_Part_Proxies_Description::real_part */
 158
 159    const char *real_part; /**< Target part name for the alias set on @ref _Elm_Layout_Part_Proxies_Description::real_part. An example of usage would be @c "default" on that field, with @c "elm.content.swallow" on this one */
 160 };
 161
 162 /**
 163  * Elementary layout base smart class. This inherits directly from
 164  * #Elm_Container_Smart_Class and is meant to build widgets relying on
 165  * an Edje layout as a building block of its visuals.
 166  *
 167  * For instance, the elm_layout @b widget itself is just a realization
 168  * of this smart class (see the code for elm_layout_add()). All of the
 169  * functions listed on @ref Layout namespace will work for objects
 170  * deriving from #Elm_Layout_Smart_Class.
 171  */
 172 typedef struct _Elm_Layout_Smart_Class
 173 {
 174    Elm_Container_Smart_Class base; /**< Elementary container widget class struct, since we're inheriting from it */
 175
 176    int                    version; /**< Version of this smart class definition */
 177
 178    void                   (*sizing_eval)(Evas_Object *obj); /* 'Virtual' function on evalutating the object's final geometry, accounting for its sub-objects */
 179    void                   (*signal)(Evas_Object *obj,
 180                                     const char *emission,
 181                                     const char *source); /* 'Virtual' function on emitting an (Edje) signal to the object, acting on its internal layout */
 182    void                   (*callback_add)(Evas_Object *obj,
 183                                           const char *emission,
 184                                           const char *source,
 185                                           Edje_Signal_Cb func,
 186                                           void *data); /* 'Virtual' function on adding an (Edje) signal callback to the object, proxyed from its internal layout */
 187    void                 * (*callback_del)(Evas_Object * obj,
 188                                           const char *emission,
 189                                           const char *source,
 190                                           Edje_Signal_Cb func); /* 'Virtual' function on deleting an (Edje) signal callback on the object, proxyed from its internal layout */
 191    Eina_Bool              (*text_set)(Evas_Object *obj,
 192                                       const char *part,
 193                                       const char *text); /* 'Virtual' function on setting text on an (Edje) part of the object, from its internal layout */
 194    const char            *(*text_get)(const Evas_Object * obj,
 195                                       const char *part); /* 'Virtual' function on fetching text from an (Edje) part of the object, on its internal layout */
 196
 197    Eina_Bool              (*box_append)(Evas_Object *obj,
 198                                         const char *part,
 199                                         Evas_Object *child); /* 'Virtual' function on appending an object to an (Edje) box part of the object, from its internal layout */
 200    Eina_Bool              (*box_prepend)(Evas_Object *obj,
 201                                          const char *part,
 202                                          Evas_Object *child); /* 'Virtual' function on prepending an object to an (Edje) box part of the object, from its internal layout */
 203    Eina_Bool              (*box_insert_before)(Evas_Object *obj,
 204                                                const char *part,
 205                                                Evas_Object *child,
 206                                                const Evas_Object *reference); /* 'Virtual' function on inserting an object to an (Edje) box part of the object, from its internal layout. The new child's position in the box is be prior to the one of a relative child already in the box */
 207    Eina_Bool              (*box_insert_at)(Evas_Object *obj,
 208                                            const char *part,
 209                                            Evas_Object *child,
 210                                            unsigned int pos); /* 'Virtual' function on inserting an object to an (Edje) box part of the object, from its internal layout. The new child's position number is passed explicitly */
 211    Evas_Object           *(*box_remove)(Evas_Object * obj,
 212                                         const char *part,
 213                                         Evas_Object * child); /* 'Virtual' function on removing an object from an (Edje) box part of the object, on its internal layout */
 214    Eina_Bool              (*box_remove_all)(Evas_Object *obj,
 215                                             const char *part,
 216                                             Eina_Bool clear); /* 'Virtual' function on removing @b all objects from an (Edje) box part of the object, on its internal layout */
 217    Eina_Bool              (*table_pack)(Evas_Object *obj,
 218                                         const char *part,
 219                                         Evas_Object *child,
 220                                         unsigned short col,
 221                                         unsigned short row,
 222                                         unsigned short colspan,
 223                                         unsigned short rowspan); /* 'Virtual' function on inserting an object to an (Edje) table part of the object, from its internal layout */
 224    Evas_Object           *(*table_unpack)(Evas_Object * obj,
 225                                           const char *part,
 226                                           Evas_Object * child); /* 'Virtual' function on removing an object from an (Edje) table part of the object, on its internal layout */
 227    Eina_Bool              (*table_clear)(Evas_Object *obj,
 228                                          const char *part,
 229                                          Eina_Bool clear); /* 'Virtual' function on removing @b all objects from an (Edje) table part of the object, on its internal layout */
 230
 231    const Elm_Layout_Part_Alias_Description *content_aliases; /**< List of (@c 'SWALLOW') part aliases, <b>@c NULL terminated</b>. If @c NULL is passed as part name, it will be translated to the 1st _Elm_Layout_Part_Proxies_Description::real_part field in the list. */
 232
 233    const Elm_Layout_Part_Alias_Description *text_aliases; /**< List of (@c 'TEXT' or 'TEXTBLOCK') part aliases, <b>@c NULL terminated</b>. If @c NULL is passed as part name, it will be translated to the 1st _Elm_Layout_Part_Proxies_Description::real_part field in the list. */
 234 } Elm_Layout_Smart_Class;
 235
 236 /**
 237  * Base widget smart data extended with layout instance data.
 238  */
 239 typedef struct _Elm_Layout_Smart_Data
 240 {
 241    Elm_Widget_Smart_Data base; /**< Base widget smart data as first member obligatory */
 242
 243    Eina_List            *subs; /**< List of Elm_Layout_Sub_Object_Data structs, to hold the actual sub objects */
 244    Eina_List            *edje_signals;
 245    Eina_List            *parts_cursors;
 246    const char           *klass, *group;
 247
 248    Eina_Bool             needs_size_calc : 1;
 249 } Elm_Layout_Smart_Data;
 250
 251 /**
 252  * @}
 253  */
 254
 255 EAPI extern const char ELM_LAYOUT_SMART_NAME[];
 256 EAPI const Elm_Layout_Smart_Class *elm_layout_smart_class_get(void);
 257
 258 #define ELM_LAYOUT_DATA_GET(o, sd) \
 259   Elm_Layout_Smart_Data * sd = evas_object_smart_data_get(o)
 260
 261 #define ELM_LAYOUT_DATA_GET_OR_RETURN(o, ptr)        \
 262   ELM_LAYOUT_DATA_GET(o, ptr);                       \
 263   if (!ptr)                                          \
 264     {                                                \
 265        CRITICAL("No widget data for object %p (%s)", \
 266                 o, evas_object_type_get(o));         \
 267        return;                                       \
 268     }
 269
 270 #define ELM_LAYOUT_DATA_GET_OR_RETURN_VAL(o, ptr, val) \
 271   ELM_LAYOUT_DATA_GET(o, ptr);                         \
 272   if (!ptr)                                            \
 273     {                                                  \
 274        CRITICAL("No widget data for object %p (%s)",   \
 275                 o, evas_object_type_get(o));           \
 276        return val;                                     \
 277     }
 278
 279 #define ELM_LAYOUT_CHECK(obj)                                                 \
 280   if (!elm_widget_type_check((obj), ELM_LAYOUT_SMART_NAME, __func__)) \
 281     return
 282
 283 #endif