src/lib/elm_bg.h

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