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