mobile/src/lib/elm_bg.h

   1 /**
   2  * @defgroup Bg Background
   3  * @ingroup Elementary
   4  *
   5  * @image html bg_inheritance_tree.png
   6  * @image latex bg_inheritance_tree.eps
   7  *
   8  * @image html img/widget/bg/preview-00.png
   9  * @image latex img/widget/bg/preview-00.eps
  10  *
  11  * @brief Background object, used for setting a solid color, image or
  12  * Edje group as a background to a window or any container object.
  13  *
  14  * The bg (background) widget is used for setting (solid) background
  15  * decorations to a window (unless it has transparency enabled) or to
  16  * any container object. It works just like an image, but has some
  17  * properties useful to a background, like setting it to tiled,
  18  * centered, scaled or stretched.
  19  *
  20  * This widget inherits from the @ref Layout one, so that all the
  21  * functions acting on it also work for background objects.
  22  *
  23  * Default content parts of the bg widget that you can use for are:
  24  * @li @c "overlay" - overlay of the bg
  25  *
  26  * Here is some sample code using it:
  27  * @li @ref bg_01_example_page
  28  * @li @ref bg_02_example_page
  29  * @li @ref bg_03_example_page
  30  */
  31
  32 /**
  33  * Identifiers on how a background widget is to display its image --
  34  * if it was set to use an image file.
  35  *
  36  * @see elm_bg_option_set()
  37  * @see elm_bg_option_get()
  38  *
  39  * @ingroup Bg
  40  */
  41 typedef enum
  42 {
  43    ELM_BG_OPTION_CENTER, /**< center the background image */
  44    ELM_BG_OPTION_SCALE, /**< scale the background image, retaining aspect ratio */
  45    ELM_BG_OPTION_STRETCH, /**< stretch the background image to fill the widget's area */
  46    ELM_BG_OPTION_TILE, /**< tile background image at its original size */
  47    ELM_BG_OPTION_LAST /**< sentinel value, also used to indicate errors */
  48 } Elm_Bg_Option;
  49
  50 /**
  51  * Add a new background to the parent
  52  *
  53  * @param parent The parent object
  54  * @return The new object or @c NULL if it cannot be created
  55  *
  56  * @ingroup Bg
  57  */
  58 EAPI Evas_Object                 *elm_bg_add(Evas_Object *parent);
  59
  60 /**
  61  * Set the file (image or edje collection) to give life for the
  62  * background
  63  *
  64  * @param obj The background object handle
  65  * @param file The file path
  66  * @param group Optional key (group in Edje) within the file
  67  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
  68  *
  69  * This sets the image file used in the background object. If the
  70  * image comes from an Edje group, it will be stretched to completely
  71  * fill the background object. If it comes from a traditional image file, it
  72  * will by default be centered in this widget's are (thus retaining
  73  * its aspect), what could lead to some parts being not visible. You
  74  * may change the mode of exhibition for a real image file with
  75  * elm_bg_option_set().
  76  *
  77  * @note Once the image of @p obj is set, a previously set one will be
  78  * deleted, even if @p file is @c NULL.
  79  *
  80  * @note This will only affect the contents of one of the background's
  81  * swallow spots, namely @c "elm.swallow.background". If you want to
  82  * achieve the @c Layout's file setting behavior, you'll have to call
  83  * that method on this object.
  84  *
  85  * @ingroup Bg
  86  */
  87 EAPI Eina_Bool                    elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
  88
  89 /**
  90  * Get the file (image or edje collection) set on a given background
  91  * widget
  92  *
  93  * @param obj The background object handle
  94  * @param file Where to store the requested file's path
  95  * @param group Where to store the optional key within @a file, @b if
  96  * it's an Edje file
  97  *
  98  * @note Use @c NULL pointers on the file components you're not
  99  * interested in: they'll be ignored by the function.
 100  *
 101  * @ingroup Bg
 102  */
 103 EAPI void                         elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group);
 104
 105 /**
 106  * Set the mode of display for a given background widget's image
 107  *
 108  * @param obj The background object handle
 109  * @param option The desired background option (see #Elm_Bg_Option)
 110  *
 111  * This sets how the background widget will display its image. This
 112  * will only work if the elm_bg_file_set() was previously called with
 113  * an image file on @a obj. The image can be display tiled, scaled,
 114  * centered or stretched.
 115  *
 116  * @see elm_bg_option_get()
 117  *
 118  * @ingroup Bg
 119  */
 120 EAPI void                         elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option);
 121
 122 /**
 123  * Get the mode of display for a given background widget's image
 124  *
 125  * @param obj The background object handle
 126  * @return The image displaying mode in use for @a obj or #ELM_BG_OPTION_LAST,
 127  * on errors.
 128  *
 129  * @see elm_bg_option_set() for more details
 130  *
 131  * @ingroup Bg
 132  */
 133 EAPI Elm_Bg_Option                elm_bg_option_get(const Evas_Object *obj);
 134
 135 /**
 136  * Set the color on a given background widget
 137  *
 138  * @param obj The background object handle
 139  * @param r The red color component's value
 140  * @param g The green color component's value
 141  * @param b The blue color component's value
 142  *
 143  * This sets the color used for the background rectangle, in RGB
 144  * format. Each color component's range is from 0 to 255.
 145  *
 146  * @note You probably only want to use this function if you haven't
 147  * previously called elm_bg_file_set(), so that you just want a solid
 148  * color background.
 149  *
 150  * @see elm_bg_color_get()
 151  *
 152  * @ingroup Bg
 153  */
 154 EAPI void                         elm_bg_color_set(Evas_Object *obj, int r, int g, int b);
 155
 156 /**
 157  * Get the color set on a given background widget
 158  *
 159  * @param obj The background object handle
 160  * @param r Where to store the red color component's value
 161  * @param g Where to store the green color component's value
 162  * @param b Where to store the blue color component's value
 163  *
 164  * @note Use @c NULL pointers on the file components you're not
 165  * interested in: they'll be ignored by the function.
 166  *
 167  * @see elm_bg_color_get() for more details
 168  *
 169  * @ingroup Bg
 170  */
 171 EAPI void                         elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b);
 172
 173 /**
 174  * Set the size of the pixmap representation of the image set on a
 175  * given background widget.
 176  *
 177  * @param obj The background object handle
 178  * @param w The new width of the image pixmap representation.
 179  * @param h The new height of the image pixmap representation.
 180  *
 181  * @warning This function just makes sense if an image file was set on
 182  * @p obj, with elm_bg_file_set().
 183  *
 184  * This function sets a new size for pixmap representation of the
 185  * given bg image. It allows for the image to be loaded already in the
 186  * specified size, reducing the memory usage and load time (for
 187  * example, when loading a big image file with its load size set to a
 188  * smaller size)
 189  *
 190  * @note This is just a hint for the underlying system. The real size
 191  * of the pixmap may differ depending on the type of image being
 192  * loaded, being bigger than requested.
 193  *
 194  * @ingroup Bg
 195  */
 196 EAPI void                         elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
 197
 198 /**
 199  * @}
 200  */