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