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