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