src/lib/elc_naviframe.h

   1 /**
   2  * @defgroup Naviframe Naviframe
   3  * @ingroup Elementary
   4  *
   5  * @brief Naviframe is a kind of view manager for the applications.
   6  *
   7  * Naviframe provides functions to switch different pages with stack
   8  * mechanism. It means if one page(item) needs to be changed to the new one,
   9  * then naviframe would push the new page to it's internal stack. Of course,
  10  * it can be back to the previous page by popping the top page. Naviframe
  11  * provides some transition effect while the pages are switching (same as
  12  * pager).
  13  *
  14  * Since each item could keep the different styles, users could keep the
  15  * same look & feel for the pages or different styles for the items in it's
  16  * application.
  17  *
  18  * Default content parts of the naviframe that you can use content hooks for
  19  * are:
  20  * @li "default" - The main content of the current page
  21  * @li "icon" - An icon in the title area of the current page
  22  * @li "prev_btn" - A button of the current page to go to the previous page
  23  * @li "next_btn" - A button of the current page to go to the next page
  24  *
  25  * Default text parts of the naviframe that you can use for are:
  26  * @li "default" - Title label in the title area of the current page
  27  * @li "subtitle" - Sub-title label in the title area of the current page
  28  *
  29  * Signals that you can add callback for are:
  30  * @li "transition,finished" - When the transition is finished in changing the
  31  * item
  32  * @li "title,clicked" - User clicked title area
  33  *
  34  * Item Signals that you can add callback for are:
  35  * @li "show,begin" - When the item is started to be top item.
  36  * @li "hide,finished" - When a new top item is finished to push onto the
  37  * item.
  38  *
  39  * Default content parts of the naviframe items that you can use content hooks
  40  * for are:
  41  * @li "default" - The main content of the page
  42  * @li "icon" - An icon in the title area
  43  * @li "prev_btn" - A button to go to the previous page
  44  * @li "next_btn" - A button to go to the next page
  45  *
  46  * Default text parts of the naviframe items that you can use for are:
  47  * @li "default" - Title label in the title area
  48  * @li "subtitle" - Sub-title label in the title area
  49  *
  50  * Supported elm_object common APIs.
  51  * @li elm_object_signal_emit
  52  * @li elm_object_part_text_set
  53  * @li elm_object_part_text_get
  54  * @li elm_object_part_content_set
  55  * @li elm_object_part_content_get
  56  * @li elm_object_part_content_unset
  57  *
  58  * Supported elm_object_item common APIs.
  59  * @li elm_object_item_part_text_set
  60  * @li elm_object_item_part_text_get
  61  * @li elm_object_item_part_content_set
  62  * @li elm_object_item_part_content_get
  63  * @li elm_object_item_part_content_unset
  64  * @li elm_object_item_signal_emit
  65  */
  66
  67 /**
  68  * @addtogroup Naviframe
  69  * @{
  70  */
  71
  72 /**
  73  * @brief Add a new Naviframe object to the parent.
  74  *
  75  * @param parent Parent object
  76  * @return New object or @c NULL, if it cannot be created
  77  *
  78  * @ingroup Naviframe
  79  */
  80 EAPI Evas_Object     *elm_naviframe_add(Evas_Object *parent);
  81
  82 /**
  83  * @brief Push a new item to the top of the naviframe stack (and show it).
  84  *
  85  * @param obj The naviframe object
  86  * @param title_label The label in the title area. The name of the title
  87  *        label part is "elm.text.title"
  88  * @param prev_btn The button to go to the previous item. If it is NULL,
  89  *        then naviframe will create a back button automatically. The name of
  90  *        the prev_btn part is "elm.swallow.prev_btn"
  91  * @param next_btn The button to go to the next item. Or It could be just an
  92  *        extra function button. The name of the next_btn part is
  93  *        "elm.swallow.next_btn"
  94  * @param content The main content object. The name of content part is
  95  *        "elm.swallow.content"
  96  * @param item_style The current item style name. @c NULL would be default.
  97  * @return The created item or @c NULL upon failure.
  98  *
  99  * The item pushed becomes one page of the naviframe, this item will be
 100  * deleted when it is popped.
 101  *
 102  * @see also elm_naviframe_item_style_set()
 103  * @see also elm_naviframe_item_insert_before()
 104  * @see also elm_naviframe_item_insert_after()
 105  *
 106  * The following styles are available for this item:
 107  * @li @c "default"
 108  *
 109  * @ingroup Naviframe
 110  */
 111 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);
 112
 113 /**
 114  * @brief Insert a new item into the naviframe before item @p before.
 115  *
 116  * @param before The naviframe item to insert before.
 117  * @param title_label The label in the title area. The name of the title
 118  *        label part is "elm.text.title"
 119  * @param prev_btn The button to go to the previous item. If it is NULL,
 120  *        then naviframe will create a back button automatically. The name of
 121  *        the prev_btn part is "elm.swallow.prev_btn"
 122  * @param next_btn The button to go to the next item. Or It could be just an
 123  *        extra function button. The name of the next_btn part is
 124  *        "elm.swallow.next_btn"
 125  * @param content The main content object. The name of content part is
 126  *        "elm.swallow.content"
 127  * @param item_style The current item style name. @c NULL would be default.
 128  * @return The created item or @c NULL upon failure.
 129  *
 130  * The item is inserted into the naviframe straight away without any
 131  * transition operations. This item will be deleted when it is popped.
 132  *
 133  * @see also elm_naviframe_item_style_set()
 134  * @see also elm_naviframe_item_push()
 135  * @see also elm_naviframe_item_insert_after()
 136  *
 137  * The following styles are available for this item:
 138  * @li @c "default"
 139  *
 140  * @ingroup Naviframe
 141  */
 142 EAPI Elm_Object_Item *elm_naviframe_item_insert_before(Elm_Object_Item *before, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
 143
 144 /**
 145  * @brief Insert a new item into the naviframe after item @p after.
 146  *
 147  * @param after The naviframe item to insert after.
 148  * @param title_label The label in the title area. The name of the title
 149  *        label part is "elm.text.title"
 150  * @param prev_btn The button to go to the previous item. If it is NULL,
 151  *        then naviframe will create a back button automatically. The name of
 152  *        the prev_btn part is "elm.swallow.prev_btn"
 153  * @param next_btn The button to go to the next item. Or It could be just an
 154  *        extra function button. The name of the next_btn part is
 155  *        "elm.swallow.next_btn"
 156  * @param content The main content object. The name of content part is
 157  *        "elm.swallow.content"
 158  * @param item_style The current item style name. @c NULL would be default.
 159  * @return The created item or @c NULL upon failure.
 160  *
 161  * The item is inserted into the naviframe straight away without any
 162  * transition operations. This item will be deleted when it is popped.
 163  *
 164  * @see also elm_naviframe_item_style_set()
 165  * @see also elm_naviframe_item_push()
 166  * @see also elm_naviframe_item_insert_before()
 167  *
 168  * The following styles are available for this item:
 169  * @li @c "default"
 170  *
 171  * @ingroup Naviframe
 172  */
 173 EAPI Elm_Object_Item *elm_naviframe_item_insert_after(Elm_Object_Item *after, const char *title_label, Evas_Object *prev_btn, Evas_Object *next_btn, Evas_Object *content, const char *item_style);
 174
 175 /**
 176  * @brief Pop an item that is on top of the stack
 177  *
 178  * @param obj The naviframe object
 179  * @return @c NULL or the content object(if the
 180  *         elm_naviframe_content_preserve_on_pop_get is true).
 181  *
 182  * This pops an item that is on the top(visible) of the naviframe, makes it
 183  * disappear, then deletes the item. The item that was underneath it on the
 184  * stack will become visible.
 185  *
 186  * @see also elm_naviframe_content_preserve_on_pop_get()
 187  *
 188  * @ingroup Naviframe
 189  */
 190 EAPI Evas_Object     *elm_naviframe_item_pop(Evas_Object *obj);
 191
 192 /**
 193  * @brief Pop the items between the top and the above one on the given item.
 194  *
 195  * @param it The naviframe item
 196  *
 197  * @ingroup Naviframe
 198  */
 199 EAPI void             elm_naviframe_item_pop_to(Elm_Object_Item *it);
 200
 201 /**
 202  * Promote an item already in the naviframe stack to the top of the stack
 203  *
 204  * @param it The naviframe item
 205  *
 206  * This will take the indicated item and promote it to the top of the stack
 207  * as if it had been pushed there. The item must already be inside the
 208  * naviframe stack to work.
 209  *
 210  */
 211 EAPI void             elm_naviframe_item_promote(Elm_Object_Item *it);
 212
 213 /**
 214  * @brief preserve the content objects when items are popped.
 215  *
 216  * @param obj The naviframe object
 217  * @param preserve Enable the preserve mode if EINA_TRUE, disable otherwise
 218  *
 219  * @see also elm_naviframe_content_preserve_on_pop_get()
 220  *
 221  * @ingroup Naviframe
 222  */
 223 EAPI void             elm_naviframe_content_preserve_on_pop_set(Evas_Object *obj, Eina_Bool preserve);
 224
 225 /**
 226  * @brief Get a value whether preserve mode is enabled or not.
 227  *
 228  * @param obj The naviframe object
 229  * @return If @c EINA_TRUE, preserve mode is enabled
 230  *
 231  * @see also elm_naviframe_content_preserve_on_pop_set()
 232  *
 233  * @ingroup Naviframe
 234  */
 235 EAPI Eina_Bool        elm_naviframe_content_preserve_on_pop_get(const Evas_Object *obj);
 236
 237 /**
 238  * @brief Get a top item on the naviframe stack
 239  *
 240  * @param obj The naviframe object
 241  * @return The top item on the naviframe stack or @c NULL, if the stack is
 242  *         empty
 243  *
 244  * @ingroup Naviframe
 245  */
 246 EAPI Elm_Object_Item *elm_naviframe_top_item_get(const Evas_Object *obj);
 247
 248 /**
 249  * @brief Get a bottom item on the naviframe stack
 250  *
 251  * @param obj The naviframe object
 252  * @return The bottom item on the naviframe stack or @c NULL, if the stack is
 253  *         empty
 254  *
 255  * @ingroup Naviframe
 256  */
 257 EAPI Elm_Object_Item *elm_naviframe_bottom_item_get(const Evas_Object *obj);
 258
 259 /**
 260  * @brief Set an item style
 261  *
 262  * @param it The naviframe item
 263  * @param item_style The current item style name. @c NULL would be default
 264  *
 265  * The following styles are available for this item:
 266  * @li @c "default"
 267  *
 268  * @see also elm_naviframe_item_style_get()
 269  *
 270  * @ingroup Naviframe
 271  */
 272 EAPI void             elm_naviframe_item_style_set(Elm_Object_Item *it, const char *item_style);
 273
 274 /**
 275  * @brief Get an item style
 276  *
 277  * @param it The naviframe item
 278  * @return The current item style name
 279  *
 280  * @see also elm_naviframe_item_style_set()
 281  *
 282  * @ingroup Naviframe
 283  */
 284 EAPI const char      *elm_naviframe_item_style_get(const Elm_Object_Item *it);
 285
 286 /**
 287  * @brief Show/Hide the title area
 288  *
 289  * @param it The naviframe item
 290  * @param visible If @c EINA_TRUE, title area will be visible, hidden
 291  *        otherwise
 292  *
 293  * When the title area is invisible, then the controls would be hidden so as     * to expand the content area to full-size.
 294  *
 295  * @see also elm_naviframe_item_title_visible_get()
 296  *
 297  * @ingroup Naviframe
 298  */
 299 EAPI void             elm_naviframe_item_title_visible_set(Elm_Object_Item *it, Eina_Bool visible);
 300
 301 /**
 302  * @brief Get a value whether title area is visible or not.
 303  *
 304  * @param it The naviframe item
 305  * @return If @c EINA_TRUE, title area is visible
 306  *
 307  * @see also elm_naviframe_item_title_visible_set()
 308  *
 309  * @ingroup Naviframe
 310  */
 311 EAPI Eina_Bool        elm_naviframe_item_title_visible_get(const Elm_Object_Item *it);
 312
 313 /**
 314  * @brief Set creating prev button automatically or not
 315  *
 316  * @param obj The naviframe object
 317  * @param auto_pushed If @c EINA_TRUE, the previous button(back button) will
 318  *        be created internally when you pass the @c NULL to the prev_btn
 319  *        parameter in elm_naviframe_item_push
 320  *
 321  * @see also elm_naviframe_item_push()
 322  *
 323  * @ingroup Naviframe
 324  */
 325 EAPI void             elm_naviframe_prev_btn_auto_pushed_set(Evas_Object *obj, Eina_Bool auto_pushed);
 326
 327 /**
 328  * @brief Get a value whether prev button(back button) will be auto pushed or
 329  *        not.
 330  *
 331  * @param obj The naviframe object
 332  * @return If @c EINA_TRUE, prev button will be auto pushed.
 333  *
 334  * @see also elm_naviframe_item_push()
 335  *           elm_naviframe_prev_btn_auto_pushed_set()
 336  *
 337  * @ingroup Naviframe
 338  */
 339 EAPI Eina_Bool        elm_naviframe_prev_btn_auto_pushed_get(const Evas_Object *obj);
 340
 341 /**
 342  * @brief Get a list of all the naviframe items.
 343  *
 344  * @param obj The naviframe object
 345  * @return An Eina_List of naviframe items, #Elm_Object_Item,
 346  * or @c NULL on failure.
 347  * @note The returned list MUST be freed.
 348  *
 349  * @ingroup Naviframe
 350  */
 351 EAPI Eina_List *elm_naviframe_items_get(const Evas_Object *obj) EINA_MALLOC EINA_WARN_UNUSED_RESULT;
 352
 353 /**
 354  * @brief Set the event enabled when pushing/popping items
 355  *
 356  * If @c enabled is EINA_TRUE, the contents of the naviframe item will
 357  * receives events from mouse and keyboard during view changing such as
 358  * item push/pop.
 359  *
 360  * @param obj The naviframe object
 361  * @param enabled Events are received when enabled is @c EINA_TRUE, and
 362  * ignored otherwise.
 363  *
 364  * @warning Events will be blocked by calling evas_object_freeze_events_set()
 365  * internally. So don't call the API whiling pushing/popping items.
 366  *
 367  * @see elm_naviframe_event_enabled_get()
 368  * @see evas_object_freeze_events_set()
 369  *
 370  * @ingroup Naviframe
 371  */
 372 EAPI void             elm_naviframe_event_enabled_set(Evas_Object *obj, Eina_Bool enabled);
 373
 374 /**
 375  * @brief Get the value of event enabled status.
 376  *
 377  * @param obj The naviframe object
 378  * @return EINA_TRUE, when event is enabled
 379  *
 380  * @see elm_naviframe_event_enabled_set()
 381  *
 382  * @ingroup Naviframe
 383  */
 384 EAPI Eina_Bool        elm_naviframe_event_enabled_get(const Evas_Object *obj);
 385
 386 /**
 387  * @brief Set the default item style.
 388  *
 389  * Default item style will be used with items who's style is NULL
 390  *
 391  * @param obj The naviframe object
 392  * @param style The style
 393  *
 394  * @ingroup Naviframe
 395  */
 396 EAPI void             elm_naviframe_item_style_default_set(Evas_Object *obj, const char *style);
 397
 398 /**
 399  * @brief Get the default item style
 400  *
 401  * @param obj The naviframe object
 402  * @return the default item style
 403  *
 404  * @see elm_naviframe_item_style_default_set()
 405  *
 406  * @ingroup Naviframe
 407  */
 408 EAPI const char      *elm_naviframe_item_style_default_get(const Evas_Object *obj);
 409
 410 /**
 411  * @brief Simple version of item_push.
 412  *
 413  * @see elm_naviframe_item_push
 414  */
 415 static inline Elm_Object_Item *
 416 elm_naviframe_item_simple_push(Evas_Object *obj, Evas_Object *content)
 417 {
 418    Elm_Object_Item *it;
 419    it = elm_naviframe_item_push(obj, NULL, NULL, NULL, content, NULL);
 420    elm_naviframe_item_title_visible_set(it, EINA_FALSE);
 421    return it;
 422 }
 423
 424 /**
 425  * @brief Simple version of item_promote.
 426  *
 427  * @see elm_naviframe_item_promote
 428  */
 429 EAPI void             elm_naviframe_item_simple_promote(Evas_Object *obj, Evas_Object *content);
 430
 431 /**
 432  * @}
 433  */