src/lib/elm_inwin.h

   1 /**
   2  * @defgroup Inwin Inwin
   3  * @ingroup Win
   4  *
   5  * @image html inwin_inheritance_tree.png
   6  * @image latex inwin_inheritance_tree.eps
   7  *
   8  * @image html img/widget/inwin/preview-00.png
   9  * @image latex img/widget/inwin/preview-00.eps
  10  * @image html img/widget/inwin/preview-01.png
  11  * @image latex img/widget/inwin/preview-01.eps
  12  * @image html img/widget/inwin/preview-02.png
  13  * @image latex img/widget/inwin/preview-02.eps
  14  *
  15  * An inwin is a window inside a window that is useful for a quick popup.
  16  * It does not hover.
  17  *
  18  * It works by creating an object that will occupy the entire window, so it
  19  * must be created using an @ref Win "elm_win" as parent only. The inwin
  20  * object can be hidden or restacked below every other object if it's
  21  * needed to show what's behind it without destroying it. If this is done,
  22  * the elm_win_inwin_activate() function can be used to bring it back to
  23  * full visibility again.
  24  *
  25  * There are three styles available in the default theme. These are:
  26  * @li default: The inwin is sized to take over most of the window it's
  27  * placed in.
  28  * @li minimal: The size of the inwin will be the minimum necessary to show
  29  * its contents.
  30  * @li minimal_vertical: Horizontally, the inwin takes as much space as
  31  * possible, but it's sized vertically the most it needs to fit its\
  32  * contents.
  33  *
  34  * This widget inherits from the @ref Layout one, so that all the
  35  * functions acting on it also work for inner windown objects. It also
  36  * emits the signals inherited from @ref Layout.
  37  *
  38  * Some examples of Inwin can be found in the following:
  39  * @li @ref inwin_example_01
  40  *
  41  * @{
  42  */
  43
  44 /**
  45  * Adds an inwin to the current window
  46  *
  47  * The @p obj used as parent @b MUST be an @ref Win "Elementary Window".
  48  * Never call this function with anything other than the top-most window
  49  * as its parameter, unless you are fond of undefined behavior.
  50  *
  51  * After creating the object, the widget will set itself as resize object
  52  * for the window with elm_win_resize_object_add(), so when shown it will
  53  * appear to cover almost the entire window (how much of it depends on its
  54  * content and the style used). It must not be added into other container
  55  * objects and it needs not be moved or resized manually.
  56  *
  57  * @param parent The parent object
  58  * @return The new object or NULL if it cannot be created
  59  *
  60  * @ingroup Inwin
  61  */
  62 EAPI Evas_Object *elm_win_inwin_add(Evas_Object *parent);
  63
  64 /**
  65  * Activates an inwin object, ensuring its visibility
  66  *
  67  * This function will make sure that the inwin @p obj is completely visible
  68  * by calling evas_object_show() and evas_object_raise() on it, to bring it
  69  * to the front. It also sets the keyboard focus to it, which will be passed
  70  * onto its content.
  71  *
  72  * The object's theme will also receive the signal "elm,action,show" with
  73  * source "elm".
  74  *
  75  * @param obj The inwin to activate
  76  *
  77  * @ingroup Inwin
  78  */
  79 EAPI void         elm_win_inwin_activate(Evas_Object *obj);
  80
  81 /**
  82  * Set the content of an inwin object.
  83  *
  84  * Once the content object is set, a previously set one will be deleted.
  85  * If you want to keep that old content object, use the
  86  * elm_win_inwin_content_unset() function.
  87  *
  88  * @param obj The inwin object
  89  * @param content The object to set as content
  90  *
  91  * @ingroup Inwin
  92  */
  93 EAPI void         elm_win_inwin_content_set(Evas_Object *obj, Evas_Object *content);
  94
  95 /**
  96  * Get the content of an inwin object.
  97  *
  98  * Return the content object for this widget.
  99  *
 100  * The returned object is valid as long as the inwin is still alive and no
 101  * other content is set on it. Deleting the object will notify the inwin
 102  * about it and this one will be left empty.
 103  *
 104  * If you need to remove an inwin's content to be reused somewhere else,
 105  * see elm_win_inwin_content_unset().
 106  *
 107  * @param obj The inwin object
 108  * @return The content that is being used
 109  *
 110  * @ingroup Inwin
 111  */
 112 EAPI Evas_Object *elm_win_inwin_content_get(const Evas_Object *obj);
 113
 114 /**
 115  * Unset the content of an inwin object.
 116  *
 117  * Unparent and return the content object which was set for this widget.
 118  *
 119  * @param obj The inwin object
 120  * @return The content that was being used
 121  *
 122  * @ingroup Inwin
 123  */
 124 EAPI Evas_Object *elm_win_inwin_content_unset(Evas_Object *obj);
 125
 126 /**
 127  * @}
 128  */
 129