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