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  * Supported elm_object common APIs.
  19  * @li elm_object_part_content_set
  20  * @li elm_object_part_content_get
  21  * @li elm_object_part_content_unset
  22  *
  23  * Here is some sample code using it:
  24  * @li @ref bg_01_example_page
  25  * @li @ref bg_02_example_page
  26  * @li @ref bg_03_example_page
  27  */
  28
  29 /* bg */
  30 typedef enum
  31 {
  32    ELM_BG_OPTION_CENTER, /**< center the background */
  33    ELM_BG_OPTION_SCALE, /**< scale the background retaining aspect ratio */
  34    ELM_BG_OPTION_STRETCH, /**< stretch the background to fill */
  35    ELM_BG_OPTION_TILE /**< tile background at its original size */
  36 } Elm_Bg_Option;
  37
  38 /**
  39  * Add a new background to the parent
  40  *
  41  * @param parent The parent object
  42  * @return The new object or NULL if it cannot be created
  43  *
  44  * @ingroup Bg
  45  */
  46 EAPI Evas_Object                 *elm_bg_add(Evas_Object *parent);
  47
  48 /**
  49  * Set the file (image or edje) used for the background
  50  *
  51  * @param obj The bg object
  52  * @param file The file path
  53  * @param group Optional key (group in Edje) within the file
  54  *
  55  * This sets the image file used in the background object. The image (or edje)
  56  * will be stretched (retaining aspect if its an image file) to completely fill
  57  * the bg object. This may mean some parts are not visible.
  58  *
  59  * @note  Once the image of @p obj is set, a previously set one will be deleted,
  60  * even if @p file is NULL.
  61  *
  62  * @ingroup Bg
  63  */
  64 EAPI void                         elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
  65
  66 /**
  67  * Get the file (image or edje) used for the background
  68  *
  69  * @param obj The bg object
  70  * @param file The file path
  71  * @param group Optional key (group in Edje) within the file
  72  *
  73  * @ingroup Bg
  74  */
  75 EAPI void                         elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group);
  76
  77 /**
  78  * Set the option used for the background image
  79  *
  80  * @param obj The bg object
  81  * @param option The desired background option (TILE, SCALE)
  82  *
  83  * This sets the option used for manipulating the display of the background
  84  * image. The image can be tiled or scaled.
  85  *
  86  * @ingroup Bg
  87  */
  88 EAPI void                         elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option);
  89
  90 /**
  91  * Get the option used for the background image
  92  *
  93  * @param obj The bg object
  94  * @return The desired background option (CENTER, SCALE, STRETCH or TILE)
  95  *
  96  * @ingroup Bg
  97  */
  98 EAPI Elm_Bg_Option                elm_bg_option_get(const Evas_Object *obj);
  99 /**
 100  * Set the option used for the background color
 101  *
 102  * @param obj The bg object
 103  * @param r
 104  * @param g
 105  * @param b
 106  *
 107  * This sets the color used for the background rectangle. Its range goes
 108  * from 0 to 255.
 109  *
 110  * @ingroup Bg
 111  */
 112 EAPI void                         elm_bg_color_set(Evas_Object *obj, int r, int g, int b);
 113 /**
 114  * Get the option used for the background color
 115  *
 116  * @param obj The bg object
 117  * @param r
 118  * @param g
 119  * @param b
 120  *
 121  * @ingroup Bg
 122  */
 123 EAPI void                         elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b);
 124
 125 /**
 126  * Set the size of the pixmap representation of the image.
 127  *
 128  * This option just makes sense if an image is going to be set in the bg.
 129  *
 130  * @param obj The bg object
 131  * @param w The new width of the image pixmap representation.
 132  * @param h The new height of the image pixmap representation.
 133  *
 134  * This function sets a new size for pixmap representation of the given bg
 135  * image. It allows the image to be loaded already in the specified size,
 136  * reducing the memory usage and load time when loading a big image with load
 137  * size set to a smaller size.
 138  *
 139  * NOTE: this is just a hint, the real size of the pixmap may differ
 140  * depending on the type of image being loaded, being bigger than requested.
 141  *
 142  * @ingroup Bg
 143  */
 144 EAPI void                         elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
 145
 146 /**
 147  * @}
 148  */