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