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
   8  * Edje group as a background to a window or any container object.
   9  *
  10  * The bg (background) widget is used for setting (solid) background
  11  * decorations to a window (unless it has transparency enabled) or to
  12  * any container object. It works just like an image, but has some
  13  * properties useful to a background, like setting it to tiled,
  14  * centered, scaled or stretched.
  15  *
  16  * Default content parts of the bg widget that you can use for are:
  17  * @li "overlay" - overlay of the bg
  18  *
  19  * Supported elm_object common APIs.
  20  * @li elm_object_part_content_set
  21  * @li elm_object_part_content_get
  22  * @li elm_object_part_content_unset
  23  *
  24  * Here is some sample code using it:
  25  * @li @ref bg_01_example_page
  26  * @li @ref bg_02_example_page
  27  * @li @ref bg_03_example_page
  28  */
  29
  30 /**
  31  * Identifiers on how a background widget is to display its image --
  32  * if it was tset to use an image file.
  33  *
  34  * @see elm_bg_option_set()
  35  * @see elm_bg_option_get()
  36  */
  37 typedef enum
  38 {
  39    ELM_BG_OPTION_CENTER, /**< center the background image */
  40    ELM_BG_OPTION_SCALE, /**< scale the background image, retaining aspect ratio */
  41    ELM_BG_OPTION_STRETCH, /**< stretch the background image to fill the widget's area */
  42    ELM_BG_OPTION_TILE, /**< tile background image at its original size */
  43    ELM_BG_OPTION_LAST /**< sentinel value, also used to indicate errors */
  44 } Elm_Bg_Option;
  45
  46 /**
  47  * Add a new background to the parent
  48  *
  49  * @param parent The parent object
  50  * @return The new object or NULL if it cannot be created
  51  *
  52  * @ingroup Bg
  53  */
  54 EAPI Evas_Object                 *elm_bg_add(Evas_Object *parent);
  55
  56 /**
  57  * Set the file (image or edje collection) to give life for the
  58  * background
  59  *
  60  * @param obj The background object handle
  61  * @param file The file path
  62  * @param group Optional key (group in Edje) within the file
  63  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
  64  *
  65  * This sets the image file used in the background object. If the
  66  * image comes from an Edje group, it will be stretched to completely
  67  * fill the background object. If it comes from a traditional image file, it
  68  * will by default be centered in this widget's are (thus retaining
  69  * its aspect), what could lead to some parts being not visible. You
  70  * may change the mode of exhibition for a real image file with
  71  * elm_bg_option_set().
  72  *
  73  * @note Once the image of @p obj is set, a previously set one will be
  74  * deleted, even if @p file is NULL.
  75  *
  76  * @note This will only affect the contents of one of the background's
  77  * swallow spots, namely @c "elm.swallow.background". If you want to
  78  * achieve the @c Layout's file setting behavior, you'll have to call
  79  * that method on this object.
  80  *
  81  * @ingroup Bg
  82  */
  83 EAPI Eina_Bool                    elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
  84
  85 /**
  86  * Get the file (image or edje collection) set on a given background
  87  * widget
  88  *
  89  * @param obj The background object handle
  90  * @param file Where to store the requested file's path
  91  * @param group Where to store the optional key within @a file, @b if
  92  * it's an Edje file
  93  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
  94  *
  95  * @note Use @c NULL pointers on the file components you're not
  96  * interested in: they'll be ignored by the function.
  97  *
  98  * @ingroup Bg
  99  */
 100 EAPI Eina_Bool                    elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group);
 101
 102 /**
 103  * Set the mode of display for a given background widget's image
 104  *
 105  * @param obj The background object handle
 106  * @param option The desired background option (see #Elm_Bg_Option)
 107  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 108  *
 109  * This sets how the background widget will display its image. This
 110  * will only work if the elm_bg_file_set() was previously called with
 111  * an image file on @a obj. The image can be display tiled, scaled,
 112  * centered or streched.
 113  *
 114  * @see elm_bg_option_get()
 115  *
 116  * @ingroup Bg
 117  */
 118 EAPI Eina_Bool                    elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option);
 119
 120 /**
 121  * Get the mode of display for a given background widget's image
 122  *
 123  * @param obj The background object handle
 124  * @return The image displaying mode in use for @a obj or
 125  * #ELM_BG_OPTION_LAST, on errors.
 126  *
 127  * @see elm_bg_option_set() for more details
 128  *
 129  * @ingroup Bg
 130  */
 131 EAPI Elm_Bg_Option                elm_bg_option_get(const Evas_Object *obj);
 132
 133 /**
 134  * Set the color on a given background widget
 135  *
 136  * @param obj The background object handle
 137  * @param r The red color component's value
 138  * @param g The green color component's value
 139  * @param b The blue color component's value
 140  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 141  *
 142  * This sets the color used for the background rectangle, in RGB
 143  * format. Each color component's range is from 0 to 255.
 144  *
 145  * @note You probably only want to use this function if you haven't
 146  * previously called elm_bg_file_set(), so that you just want a solid
 147  * color background.
 148  *
 149  * @see elm_bg_color_get()
 150  *
 151  * @ingroup Bg
 152  */
 153 EAPI Eina_Bool                    elm_bg_color_set(Evas_Object *obj, int r, int g, int b);
 154
 155 /**
 156  * Get the color set on a given background widget
 157  *
 158  * @param obj The background object handle
 159  * @param r Where to store the red color component's value
 160  * @param g Where to store the green color component's value
 161  * @param b Where to store the blue color component's value
 162  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 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 Eina_Bool                    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 Eina_Bool                    elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
 197
 198 /**
 199  * @}
 200  */