src/lib/elm_bg.h

   1 /**
   2  * @defgroup Bg Bg
   3  *
   4  * @image html img/widget/bg/preview-00.png
   5  * @image latex img/widget/bg/preview-00.eps
   6  *
   7  * @brief Background object, used for setting a solid color, image or Edje
   8  * group as background to a window or any container object.
   9  *
  10  * The bg object is used for setting a solid background to a window or
  11  * packing into any container object. It works just like an image, but has
  12  * some properties useful to a background, like setting it to tiled,
  13  * centered, scaled or stretched.
  14  *
  15  * Default contents parts of the bg widget that you can use for are:
  16  * @li "overlay" - overlay of the bg
  17  *
  18  * Here is some sample code using it:
  19  * @li @ref bg_01_example_page
  20  * @li @ref bg_02_example_page
  21  * @li @ref bg_03_example_page
  22  */
  23
  24 /* bg */
  25 typedef enum _Elm_Bg_Option
  26 {
  27    ELM_BG_OPTION_CENTER, /**< center the background */
  28    ELM_BG_OPTION_SCALE, /**< scale the background retaining aspect ratio */
  29    ELM_BG_OPTION_STRETCH, /**< stretch the background to fill */
  30    ELM_BG_OPTION_TILE /**< tile background at its original size */
  31 } Elm_Bg_Option;
  32
  33 /**
  34  * Add a new background to the parent
  35  *
  36  * @param parent The parent object
  37  * @return The new object or NULL if it cannot be created
  38  *
  39  * @ingroup Bg
  40  */
  41 EAPI Evas_Object *
  42                                   elm_bg_add(Evas_Object *parent)
  43 EINA_ARG_NONNULL(1);
  44
  45 /**
  46  * Set the file (image or edje) used for the background
  47  *
  48  * @param obj The bg object
  49  * @param file The file path
  50  * @param group Optional key (group in Edje) within the file
  51  *
  52  * This sets the image file used in the background object. The image (or edje)
  53  * will be stretched (retaining aspect if its an image file) to completely fill
  54  * the bg object. This may mean some parts are not visible.
  55  *
  56  * @note  Once the image of @p obj is set, a previously set one will be deleted,
  57  * even if @p file is NULL.
  58  *
  59  * @ingroup Bg
  60  */
  61 EAPI void                         elm_bg_file_set(Evas_Object *obj, const char *file, const char *group) EINA_ARG_NONNULL(1);
  62
  63 /**
  64  * Get the file (image or edje) used for the background
  65  *
  66  * @param obj The bg object
  67  * @param file The file path
  68  * @param group Optional key (group in Edje) within the file
  69  *
  70  * @ingroup Bg
  71  */
  72 EAPI void                         elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group) EINA_ARG_NONNULL(1);
  73
  74 /**
  75  * Set the option used for the background image
  76  *
  77  * @param obj The bg object
  78  * @param option The desired background option (TILE, SCALE)
  79  *
  80  * This sets the option used for manipulating the display of the background
  81  * image. The image can be tiled or scaled.
  82  *
  83  * @ingroup Bg
  84  */
  85 EAPI void                         elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option) EINA_ARG_NONNULL(1);
  86
  87 /**
  88  * Get the option used for the background image
  89  *
  90  * @param obj The bg object
  91  * @return The desired background option (CENTER, SCALE, STRETCH or TILE)
  92  *
  93  * @ingroup Bg
  94  */
  95 EAPI Elm_Bg_Option                elm_bg_option_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
  96 /**
  97  * Set the option used for the background color
  98  *
  99  * @param obj The bg object
 100  * @param r
 101  * @param g
 102  * @param b
 103  *
 104  * This sets the color used for the background rectangle. Its range goes
 105  * from 0 to 255.
 106  *
 107  * @ingroup Bg
 108  */
 109 EAPI void                         elm_bg_color_set(Evas_Object *obj, int r, int g, int b) EINA_ARG_NONNULL(1);
 110 /**
 111  * Get the option used for the background color
 112  *
 113  * @param obj The bg object
 114  * @param r
 115  * @param g
 116  * @param b
 117  *
 118  * @ingroup Bg
 119  */
 120 EAPI void                         elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b) EINA_ARG_NONNULL(1);
 121
 122 /**
 123  * Set the overlay object used for the background object.
 124  *
 125  * @param obj The bg object
 126  * @param overlay The overlay object
 127  *
 128  * This provides a way for elm_bg to have an 'overlay' that will be on top
 129  * of the bg. Once the over object is set, a previously set one will be
 130  * deleted, even if you set the new one to NULL. If you want to keep that
 131  * old content object, use the elm_bg_overlay_unset() function.
 132  *
 133  * @deprecated use elm_object_part_content_set() instead
 134  *
 135  * @ingroup Bg
 136  */
 137
 138 EINA_DEPRECATED EAPI void         elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) EINA_ARG_NONNULL(1);
 139
 140 /**
 141  * Get the overlay object used for the background object.
 142  *
 143  * @param obj The bg object
 144  * @return The content that is being used
 145  *
 146  * Return the content object which is set for this widget
 147  *
 148  * @deprecated use elm_object_part_content_get() instead
 149  *
 150  * @ingroup Bg
 151  */
 152 EINA_DEPRECATED EAPI Evas_Object *elm_bg_overlay_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 153
 154 /**
 155  * Get the overlay object used for the background object.
 156  *
 157  * @param obj The bg object
 158  * @return The content that was being used
 159  *
 160  * Unparent and return the overlay object which was set for this widget
 161  *
 162  * @deprecated use elm_object_part_content_unset() instead
 163  *
 164  * @ingroup Bg
 165  */
 166 EINA_DEPRECATED EAPI Evas_Object *elm_bg_overlay_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 167
 168 /**
 169  * Set the size of the pixmap representation of the image.
 170  *
 171  * This option just makes sense if an image is going to be set in the bg.
 172  *
 173  * @param obj The bg object
 174  * @param w The new width of the image pixmap representation.
 175  * @param h The new height of the image pixmap representation.
 176  *
 177  * This function sets a new size for pixmap representation of the given bg
 178  * image. It allows the image to be loaded already in the specified size,
 179  * reducing the memory usage and load time when loading a big image with load
 180  * size set to a smaller size.
 181  *
 182  * NOTE: this is just a hint, the real size of the pixmap may differ
 183  * depending on the type of image being loaded, being bigger than requested.
 184  *
 185  * @ingroup Bg
 186  */
 187 EAPI void                         elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
 188
 189 /**
 190  * @}
 191  */