src/lib/elc_naviframe.h

   1 /**
   2  * @defgroup Naviframe Naviframe
   3  * @ingroup Elementary
   4  *
   5  * @image html naviframe_inheritance_tree.png
   6  * @image latex naviframe_inheritance_tree.eps
   7  *
   8  * @brief Naviframe stands for navigation frame. It's a views manager
   9  * for applications.
  10  *
  11  * A naviframe holds views (or pages) as its items. Those items are
  12  * organized in a stack, so that new items get pushed on top of the
  13  * old, and only the topmost view is displayed at one time. The
  14  * transition between views is animated, depending on the theme
  15  * applied to the widget.
  16  *
  17  * Naviframe views hold spaces to various elements, which are:
  18  * - back button, used to navigate to previous views,
  19  * - next button, used to navigate to next views in the stack,
  20  * - title label,
  21  * - sub-title label,
  22  * - title icon and
  23  * - content area.
  24  *
  25  * This widget inherits from the @ref Layout one, so that all the
  26  * functions acting on it also work for naviframe objects.
  27  *
  28  * Because this widget is a layout, one places content on those areas
  29  * by using elm_layout_content_set() on the right swallow part names
  30  * expected for each, which are:
  31  * @li @c "default" - The main content of the current page
  32  * @li @c "icon" - An icon in the title area of the current page
  33  * @li @c "prev_btn" - A button of the current page to go to the
  34  *                     previous page
  35  * @li @c "next_btn" - A button of the current page to go to the next
  36  *                     page
  37  *
  38  * For text, elm_layout_text_set() will work here on:
  39  * @li @c "default" - Title label in the title area of the current
  40  *                    page
  41  * @li @c "subtitle" - Sub-title label in the title area of the
  42  *                     current page
  43  *
  44  * Most of those content objects can be passed at the time of an item
  45  * creation (see elm_naviframe_item_push()).
  46  *
  47  * Naviframe items can have different styles, which affect the
  48  * transition between views, for example. On the default theme, two of
  49  * them are supported:
  50  * - @c "basic"   - views are switched sliding horizontally, one after
  51  *                  the other
  52  * - @c "overlap" - like the previous one, but the previous view stays
  53  *                  at its place and is overlapped by the new
  54  *
  55  *
  56  * This widget emits the following signals, besides the ones sent from
  57  * @ref Layout:
  58  * @li @c "transition,finished" - When the transition is finished in
  59  *                                changing the item
  60  * @li @c "title,clicked" - User clicked title area
  61  *
  62  * All the parts, for content and text, described here will also be
  63  * reachable by naviframe @b items direct calls:
  64  * @li @ref elm_object_item_part_text_set
  65  * @li @ref elm_object_item_part_text_get
  66  * @li @ref elm_object_item_part_content_set
  67  * @li @ref elm_object_item_part_content_get
  68  * @li @ref elm_object_item_part_content_unset
  69  * @li @ref elm_object_item_signal_emit
  70  *
  71  * What happens is that the topmost item of a naviframe will be the
  72  * widget's target layout, when accessed directly. Items lying below
  73  * the top one can be interacted with this way.
  74  */
  75
  76 /**
  77  * @typedef Elm_Naviframe_Item_Pop_Cb
  78  *
  79  * Pop callback called when @c it is going to be popped. @c data is user
  80  * specific data.
  81  *
  82  * @see elm_naviframe_item_pop_cb_set()
  83  *
  84  * @since 1.8
  85  */
  86 typedef void (*Elm_Naviframe_Item_Pop_Cb)(void *data, Elm_Object_Item *it);
  87
  88 /**
  89  * @addtogroup Naviframe
  90  * @{
  91  */
  92
  93 /**
  94  * @brief Add a new Naviframe object to the parent.
  95  *
  96  * @param parent Parent object
  97  * @return New object or @c NULL, if it cannot be created
  98  *
  99  * @ingroup Naviframe
 100  */
 101 EAPI Evas_Object     *elm_naviframe_add(Evas_Object *parent);
 102
 103 /**
 104  * @brief Push a new item to the top of the naviframe stack (and show it).
 105  *
 106  * @param obj The naviframe object
 107  * @param title_label The label in the title area. The name of the title
 108  *        label part is "elm.text.title"
 109  * @param prev_btn The button to go to the previous item. If it is NULL,
 110  *        then naviframe will create a back button automatically. The name of
 111  *        the prev_btn part is "elm.swallow.prev_btn"
 112  * @param next_btn The button to go to the next item. Or It could be just an
 113  *        extra function button. The name of the next_btn part is
 114  *        "elm.swallow.next_btn"
 115  * @param content The main content object. The name of content part is
 116  *        "elm.swallow.content"
 117  * @param item_style The current item style name. @c NULL would be default.
 118  * @return The created item or @c NULL upon failure.
 119  *
 120  * The item pushed becomes one page of the naviframe, this item will be
 121  * deleted when it is popped.
 122  *
 123  * @see also elm_naviframe_item_style_set()
 124  * @see also elm_naviframe_item_insert_before()
 125  * @see also elm_naviframe_item_insert_after()
 126  *
 127  * The following styles are available for this item:
 128  * @li @c "default"
 129  *
 130  * @ingroup Naviframe
 131  */
 132 EAPI Elm_Object_Item *elm_naviframe_item_push(Evas_Object *obj, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
 133
 134 /**
 135  * @brief Insert a new item into the naviframe before item @p before.
 136  *
 137  * @param obj The naviframe object
 138  * @param before The naviframe item to insert before.
 139  * @param title_label The label in the title area. The name of the title
 140  *        label part is "elm.text.title"
 141  * @param prev_btn The button to go to the previous item. If it is NULL,
 142  *        then naviframe will create a back button automatically. The name of
 143  *        the prev_btn part is "elm.swallow.prev_btn"
 144  * @param next_btn The button to go to the next item. Or It could be just an
 145  *        extra function button. The name of the next_btn part is
 146  *        "elm.swallow.next_btn"
 147  * @param content The main content object. The name of content part is
 148  *        "elm.swallow.content"
 149  * @param item_style The current item style name. @c NULL would be default.
 150  * @return The created item or @c NULL upon failure.
 151  *
 152  * The item is inserted into the naviframe straight away without any
 153  * transition operations. This item will be deleted when it is popped.
 154  *
 155  * @see also elm_naviframe_item_style_set()
 156  * @see also elm_naviframe_item_push()
 157  * @see also elm_naviframe_item_insert_after()
 158  *
 159  * The following styles are available for this item:
 160  * @li @c "default"
 161  *
 162  * @ingroup Naviframe
 163  */
 164 EAPI Elm_Object_Item *elm_naviframe_item_insert_before(Evas_Object *obj, Elm_Object_Item *before, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
 165
 166 /**
 167  * @brief Insert a new item into the naviframe after item @p after.
 168  *
 169  * @param obj The naviframe object
 170  * @param after The naviframe item to insert after.
 171  * @param title_label The label in the title area. The name of the title
 172  *        label part is "elm.text.title"
 173  * @param prev_btn The button to go to the previous item. If it is NULL,
 174  *        then naviframe will create a back button automatically. The name of
 175  *        the prev_btn part is "elm.swallow.prev_btn"
 176  * @param next_btn The button to go to the next item. Or It could be just an
 177  *        extra function button. The name of the next_btn part is
 178  *        "elm.swallow.next_btn"
 179  * @param content The main content object. The name of content part is
 180  *        "elm.swallow.content"
 181  * @param item_style The current item style name. @c NULL would be default.
 182  * @return The created item or @c NULL upon failure.
 183  *
 184  * The item is inserted into the naviframe straight away without any
 185  * transition operations. This item will be deleted when it is popped.
 186  *
 187  * @see also elm_naviframe_item_style_set()
 188  * @see also elm_naviframe_item_push()
 189  * @see also elm_naviframe_item_insert_before()
 190  *
 191  * The following styles are available for this item:
 192  * @li @c "default"
 193  *
 194  * @ingroup Naviframe
 195  */
 196 EAPI Elm_Object_Item *elm_naviframe_item_insert_after(Evas_Object *obj, Elm_Object_Item *after, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
 197
 198 /**
 199  * @brief Pop an item that is on top of the stack
 200  *
 201  * @param obj The naviframe object
 202  * @return @c NULL or the content object(if the
 203  *         elm_naviframe_content_preserve_on_pop_get is true).
 204  *
 205  * This pops an item that is on the top(visible) of the naviframe, makes it
 206  * disappear, then deletes the item. The item that was underneath it on the
 207  * stack will become visible.
 208  *
 209  * @see also elm_naviframe_content_preserve_on_pop_get()
 210  * @see also elm_naviframe_item_pop_cb_set()
 211  *
 212  * @ingroup Naviframe
 213  */
 214 EAPI Evas_Object     *elm_naviframe_item_pop(Evas_Object *obj);
 215
 216 /**
 217  * @brief Pop the items between the top and the above one on the given item.
 218  *
 219  * @param it The naviframe item
 220  *
 221  * @ingroup Naviframe
 222  */
 223 EAPI void             elm_naviframe_item_pop_to(Elm_Object_Item *it);
 224
 225 /**
 226  * Promote an item already in the naviframe stack to the top of the stack
 227  *
 228  * @param it The naviframe item
 229  *
 230  * This will take the indicated item and promote it to the top of the stack
 231  * as if it had been pushed there. The item must already be inside the
 232  * naviframe stack to work.
 233  *
 234  */
 235 EAPI void             elm_naviframe_item_promote(Elm_Object_Item *it);
 236
 237 /**
 238  * @brief preserve the content objects when items are popped.
 239  *
 240  * @param obj The naviframe object
 241  * @param preserve Enable the preserve mode if EINA_TRUE, disable otherwise
 242  *
 243  * @see also elm_naviframe_content_preserve_on_pop_get()
 244  *
 245  * @ingroup Naviframe
 246  */
 247 EAPI void             elm_naviframe_content_preserve_on_pop_set(Evas_Object *obj, Eina_Bool preserve);
 248
 249 /**
 250  * @brief Get a value whether preserve mode is enabled or not.
 251  *
 252  * @param obj The naviframe object
 253  * @return If @c EINA_TRUE, preserve mode is enabled
 254  *
 255  * @see also elm_naviframe_content_preserve_on_pop_set()
 256  *
 257  * @ingroup Naviframe
 258  */
 259 EAPI Eina_Bool        elm_naviframe_content_preserve_on_pop_get(const Evas_Object *obj);
 260
 261 /**
 262  * @brief Get a top item on the naviframe stack
 263  *
 264  * @param obj The naviframe object
 265  * @return The top item on the naviframe stack or @c NULL, if the stack is
 266  *         empty
 267  *
 268  * @ingroup Naviframe
 269  */
 270 EAPI Elm_Object_Item *elm_naviframe_top_item_get(const Evas_Object *obj);
 271
 272 /**
 273  * @brief Get a bottom item on the naviframe stack
 274  *
 275  * @param obj The naviframe object
 276  * @return The bottom item on the naviframe stack or @c NULL, if the stack is
 277  *         empty
 278  *
 279  * @ingroup Naviframe
 280  */
 281 EAPI Elm_Object_Item *elm_naviframe_bottom_item_get(const Evas_Object *obj);
 282
 283 /**
 284  * @brief Set an item style
 285  *
 286  * @param it The naviframe item
 287  * @param item_style The current item style name. @c NULL would be default
 288  *
 289  * The following styles are available for this item:
 290  * @li @c "default"
 291  *
 292  * @see also elm_naviframe_item_style_get()
 293  *
 294  * @ingroup Naviframe
 295  */
 296 EAPI void             elm_naviframe_item_style_set(Elm_Object_Item *it, const char *item_style);
 297
 298 /**
 299  * @brief Get an item style
 300  *
 301  * @param it The naviframe item
 302  * @return The current item style name
 303  *
 304  * @see also elm_naviframe_item_style_set()
 305  *
 306  * @ingroup Naviframe
 307  */
 308 EAPI const char      *elm_naviframe_item_style_get(const Elm_Object_Item *it);
 309
 310 /**
 311  * @brief Show/Hide the title area
 312  *
 313  * @param it The naviframe item
 314  * @param visible If @c EINA_TRUE, title area will be visible, hidden
 315  *        otherwise
 316  *
 317  * When the title area is invisible, then the controls would be hidden so as     * to expand the content area to full-size.
 318  *
 319  * @see also elm_naviframe_item_title_visible_get()
 320  *
 321  * @ingroup Naviframe
 322  */
 323 EAPI void             elm_naviframe_item_title_visible_set(Elm_Object_Item *it, Eina_Bool visible);
 324
 325 /**
 326  * @brief Get a value whether title area is visible or not.
 327  *
 328  * @param it The naviframe item
 329  * @return If @c EINA_TRUE, title area is visible
 330  *
 331  * @see also elm_naviframe_item_title_visible_set()
 332  *
 333  * @ingroup Naviframe
 334  */
 335 EAPI Eina_Bool        elm_naviframe_item_title_visible_get(const Elm_Object_Item *it);
 336
 337 /**
 338  * @brief Set a function to be called when @c it of the naviframe is going to be
 339  * popped.
 340  *
 341  * @param it The item to set the callback on
 342  * @param func the callback function.
 343  *
 344  * @warning Don't set "clicked" callback to the prev button additionally if the
 345  * function does a exact same logic with this @c func. When hardware back key is
 346  * pressed then both callbacks will be called.
 347  *
 348  * @since 1.8
 349  * @ingroup Naviframe
 350  */
 351 EAPI void             elm_naviframe_item_pop_cb_set(Elm_Object_Item *it, Elm_Naviframe_Item_Pop_Cb func, void *data);
 352
 353 /**
 354  * @brief Set creating prev button automatically or not
 355  *
 356  * @param obj The naviframe object
 357  * @param auto_pushed If @c EINA_TRUE, the previous button(back button) will
 358  *        be created internally when you pass the @c NULL to the prev_btn
 359  *        parameter in elm_naviframe_item_push
 360  *
 361  * @see also elm_naviframe_item_push()
 362  *
 363  * @ingroup Naviframe
 364  */
 365 EAPI void             elm_naviframe_prev_btn_auto_pushed_set(Evas_Object *obj, Eina_Bool auto_pushed);
 366
 367 /**
 368  * @brief Get a value whether prev button(back button) will be auto pushed or
 369  *        not.
 370  *
 371  * @param obj The naviframe object
 372  * @return If @c EINA_TRUE, prev button will be auto pushed.
 373  *
 374  * @see also elm_naviframe_item_push()
 375  *           elm_naviframe_prev_btn_auto_pushed_set()
 376  *
 377  * @ingroup Naviframe
 378  */
 379 EAPI Eina_Bool        elm_naviframe_prev_btn_auto_pushed_get(const Evas_Object *obj);
 380
 381 /**
 382  * @brief Get a list of all the naviframe items.
 383  *
 384  * @param obj The naviframe object
 385  * @return An Eina_List of naviframe items, #Elm_Object_Item,
 386  * or @c NULL on failure.
 387  * @note The returned list MUST be freed.
 388  *
 389  * @ingroup Naviframe
 390  */
 391 EAPI Eina_List *elm_naviframe_items_get(const Evas_Object *obj) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 392
 393 /**
 394  * @brief Set the event enabled when pushing/popping items
 395  *
 396  * If @c enabled is EINA_TRUE, the contents of the naviframe item will
 397  * receives events from mouse and keyboard during view changing such as
 398  * item push/pop.
 399  *
 400  * @param obj The naviframe object
 401  * @param enabled Events are received when enabled is @c EINA_TRUE, and
 402  * ignored otherwise.
 403  *
 404  * @warning Events will be blocked by calling evas_object_freeze_events_set()
 405  * internally. So don't call the API whiling pushing/popping items.
 406  *
 407  * @see elm_naviframe_event_enabled_get()
 408  * @see evas_object_freeze_events_set()
 409  *
 410  * @ingroup Naviframe
 411  */
 412 EAPI void             elm_naviframe_event_enabled_set(Evas_Object *obj, Eina_Bool enabled);
 413
 414 /**
 415  * @brief Get the value of event enabled status.
 416  *
 417  * @param obj The naviframe object
 418  * @return EINA_TRUE, when event is enabled
 419  *
 420  * @see elm_naviframe_event_enabled_set()
 421  *
 422  * @ingroup Naviframe
 423  */
 424 EAPI Eina_Bool        elm_naviframe_event_enabled_get(const Evas_Object *obj);
 425
 426 /**
 427  * @brief Simple version of item_push.
 428  *
 429  * @see elm_naviframe_item_push
 430  */
 431 static inline Elm_Object_Item *
 432 elm_naviframe_item_simple_push(Evas_Object *obj, Evas_Object *content)
 433 {
 434    Elm_Object_Item *it;
 435    it = elm_naviframe_item_push(obj, NULL, NULL, NULL, content, NULL);
 436    elm_naviframe_item_title_visible_set(it, EINA_FALSE);
 437    return it;
 438 }
 439
 440 /**
 441  * @brief Simple version of item_promote.
 442  *
 443  * @see elm_naviframe_item_promote
 444  */
 445 EAPI void             elm_naviframe_item_simple_promote(Evas_Object *obj, Evas_Object *content);
 446
 447 /**
 448  * @}
 449  */