src/lib/elm_pager.h

   1    /**
   2     * @defgroup Pager Pager
   3     *
   4     * @image html img/widget/pager/preview-00.png
   5     * @image latex img/widget/pager/preview-00.eps
   6     *
   7     * @brief Widget that allows flipping between one or more “pages”
   8     * of objects.
   9     *
  10     * The flipping between pages of objects is animated. All content
  11     * in the pager is kept in a stack, being the last content added
  12     * (visible one) on the top of that stack.
  13     *
  14     * Objects can be pushed or popped from the stack or deleted as
  15     * well. Pushes and pops will animate the widget accordingly to its
  16     * style (a pop will also delete the child object once the
  17     * animation is finished). Any object already in the pager can be
  18     * promoted to the top (from its current stacking position) through
  19     * the use of elm_pager_content_promote(). New objects are pushed
  20     * to the top with elm_pager_content_push(). When the top item is
  21     * no longer wanted, simply pop it with elm_pager_content_pop() and
  22     * it will also be deleted. If an object is no longer needed and is
  23     * not the top item, just delete it as normal. You can query which
  24     * objects are the top and bottom with
  25     * elm_pager_content_bottom_get() and elm_pager_content_top_get().
  26     *
  27     * Signals that you can add callbacks for are:
  28     * - @c "show,finished" - when a new page is actually shown on the top
  29     * - @c "hide,finished" - when a previous page is hidden
  30     *
  31     * Only after the first of that signals the child object is
  32     * guaranteed to be visible, as in @c evas_object_visible_get().
  33     *
  34     * This widget has the following styles available:
  35     * - @c "default"
  36     * - @c "fade"
  37     * - @c "fade_translucide"
  38     * - @c "fade_invisible"
  39     *
  40     * @note These styles affect only the flipping animations on the
  41     * default theme; the appearance when not animating is unaffected
  42     * by them.
  43     *
  44     * @ref tutorial_pager gives a good overview of the usage of the API.
  45     * @{
  46     */
  47
  48    /**
  49     * Add a new pager to the parent
  50     *
  51     * @param parent The parent object
  52     * @return The new object or NULL if it cannot be created
  53     *
  54     * @ingroup Pager
  55     */
  56    EAPI Evas_Object *elm_pager_add(Evas_Object *parent) EINA_ARG_NONNULL(1);
  57
  58    /**
  59     * @brief Push an object to the top of the pager stack (and show it).
  60     *
  61     * @param obj The pager object
  62     * @param content The object to push
  63     *
  64     * The object pushed becomes a child of the pager, it will be controlled and
  65     * deleted when the pager is deleted.
  66     *
  67     * @note If the content is already in the stack use
  68     * elm_pager_content_promote().
  69     * @warning Using this function on @p content already in the stack results in
  70     * undefined behavior.
  71     */
  72    EAPI void         elm_pager_content_push(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
  73
  74    /**
  75     * @brief Pop the object that is on top of the stack
  76     *
  77     * @param obj The pager object
  78     *
  79     * This pops the object that is on the top(visible) of the pager, makes it
  80     * disappear, then deletes the object. The object that was underneath it on
  81     * the stack will become visible.
  82     */
  83    EAPI void         elm_pager_content_pop(Evas_Object *obj) EINA_ARG_NONNULL(1);
  84
  85    /**
  86     * @brief Moves an object already in the pager stack to the top of the stack.
  87     *
  88     * @param obj The pager object
  89     * @param content The object to promote
  90     *
  91     * This will take the @p content and move it to the top of the stack as
  92     * if it had been pushed there.
  93     *
  94     * @note If the content isn't already in the stack use
  95     * elm_pager_content_push().
  96     * @warning Using this function on @p content not already in the stack
  97     * results in undefined behavior.
  98     */
  99    EAPI void         elm_pager_content_promote(Evas_Object *obj, Evas_Object *content) EINA_ARG_NONNULL(1);
 100
 101    /**
 102     * @brief Return the object at the bottom of the pager stack
 103     *
 104     * @param obj The pager object
 105     * @return The bottom object or NULL if none
 106     */
 107    EAPI Evas_Object *elm_pager_content_bottom_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 108
 109    /**
 110     * @brief  Return the object at the top of the pager stack
 111     *
 112     * @param obj The pager object
 113     * @return The top object or NULL if none
 114     */
 115    EAPI Evas_Object *elm_pager_content_top_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 116
 117    /**
 118     * @}
 119     */
 120