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