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