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 <<<<<<< HEAD
   8  * @brief Background object, used for setting a solid color, image or Edje
   9  * group as background to a window or any container object.
  10  *
  11  * The bg object is used for setting a solid background to a window or
  12  * packing into any container object. It works just like an image, but has
  13  * some properties useful to a background, like setting it to tiled,
  14  * centered, scaled or stretched.
  15  *
  16  * Default contents parts of the bg widget that you can use for are:
  17 =======
  18  * @brief Background object, used for setting a solid color, image or
  19  * Edje group as a background to a window or any container object.
  20  *
  21  * The bg (background) widget is used for setting (solid) background
  22  * decorations to a window (unless it has transparency enabled) or to
  23  * any container object. It works just like an image, but has some
  24  * properties useful to a background, like setting it to tiled,
  25  * centered, scaled or stretched.
  26  *
  27  * Default content parts of the bg widget that you can use for are:
  28 >>>>>>> remotes/origin/upstream
  29  * @li "overlay" - overlay of the bg
  30  *
  31  * Supported elm_object common APIs.
  32  * @li elm_object_part_content_set
  33  * @li elm_object_part_content_get
  34  * @li elm_object_part_content_unset
  35  *
  36  * Here is some sample code using it:
  37  * @li @ref bg_01_example_page
  38  * @li @ref bg_02_example_page
  39  * @li @ref bg_03_example_page
  40  */
  41
  42 <<<<<<< HEAD
  43 /* bg */
  44 typedef enum
  45 {
  46    ELM_BG_OPTION_CENTER, /**< center the background */
  47    ELM_BG_OPTION_SCALE, /**< scale the background retaining aspect ratio */
  48    ELM_BG_OPTION_STRETCH, /**< stretch the background to fill */
  49    ELM_BG_OPTION_TILE /**< tile background at its original size */
  50 =======
  51 /**
  52  * Identifiers on how a background widget is to display its image --
  53  * if it was tset to use an image file.
  54  *
  55  * @see elm_bg_option_set()
  56  * @see elm_bg_option_get()
  57  */
  58 typedef enum
  59 {
  60    ELM_BG_OPTION_CENTER, /**< center the background image */
  61    ELM_BG_OPTION_SCALE, /**< scale the background image, retaining aspect ratio */
  62    ELM_BG_OPTION_STRETCH, /**< stretch the background image to fill the widget's area */
  63    ELM_BG_OPTION_TILE, /**< tile background image at its original size */
  64    ELM_BG_OPTION_LAST /**< sentinel value, also used to indicate errors */
  65 >>>>>>> remotes/origin/upstream
  66 } Elm_Bg_Option;
  67
  68 /**
  69  * Add a new background to the parent
  70  *
  71  * @param parent The parent object
  72  * @return The new object or NULL if it cannot be created
  73  *
  74  * @ingroup Bg
  75  */
  76 EAPI Evas_Object                 *elm_bg_add(Evas_Object *parent);
  77
  78 /**
  79 <<<<<<< HEAD
  80  * Set the file (image or edje) used for the background
  81  *
  82  * @param obj The bg object
  83  * @param file The file path
  84  * @param group Optional key (group in Edje) within the file
  85  *
  86  * This sets the image file used in the background object. The image (or edje)
  87  * will be stretched (retaining aspect if its an image file) to completely fill
  88  * the bg object. This may mean some parts are not visible.
  89  *
  90  * @note  Once the image of @p obj is set, a previously set one will be deleted,
  91  * even if @p file is NULL.
  92  *
  93  * @ingroup Bg
  94  */
  95 EAPI void                         elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
  96
  97 /**
  98  * Get the file (image or edje) used for the background
  99  *
 100  * @param obj The bg object
 101  * @param file The file path
 102  * @param group Optional key (group in Edje) within the file
 103 =======
 104  * Set the file (image or edje collection) to give life for the
 105  * background
 106  *
 107  * @param obj The background object handle
 108  * @param file The file path
 109  * @param group Optional key (group in Edje) within the file
 110  * @return @c EINA_TRUE on success, @c EINA_FALSE otherwise
 111  *
 112  * This sets the image file used in the background object. If the
 113  * image comes from an Edje group, it will be stretched to completely
 114  * fill the background object. If it comes from a traditional image file, it
 115  * will by default be centered in this widget's are (thus retaining
 116  * its aspect), what could lead to some parts being not visible. You
 117  * may change the mode of exhibition for a real image file with
 118  * elm_bg_option_set().
 119  *
 120  * @note Once the image of @p obj is set, a previously set one will be
 121  * deleted, even if @p file is NULL.
 122  *
 123  * @note This will only affect the contents of one of the background's
 124  * swallow spots, namely @c "elm.swallow.background". If you want to
 125  * achieve the @c Layout's file setting behavior, you'll have to call
 126  * that method on this object.
 127  *
 128  * @ingroup Bg
 129  */
 130 EAPI Eina_Bool                    elm_bg_file_set(Evas_Object *obj, const char *file, const char *group);
 131
 132 /**
 133  * Get the file (image or edje collection) set on a given background
 134  * widget
 135  *
 136  * @param obj The background object handle
 137  * @param file Where to store the requested file's path
 138  * @param group Where to store the optional key within @a file, @b if
 139  * it's an Edje file
 140  *
 141  * @note Use @c NULL pointers on the file components you're not
 142  * interested in: they'll be ignored by the function.
 143 >>>>>>> remotes/origin/upstream
 144  *
 145  * @ingroup Bg
 146  */
 147 EAPI void                         elm_bg_file_get(const Evas_Object *obj, const char **file, const char **group);
 148
 149 /**
 150 <<<<<<< HEAD
 151  * Set the option used for the background image
 152  *
 153  * @param obj The bg object
 154  * @param option The desired background option (TILE, SCALE)
 155  *
 156  * This sets the option used for manipulating the display of the background
 157  * image. The image can be tiled or scaled.
 158 =======
 159  * Set the mode of display for a given background widget's image
 160  *
 161  * @param obj The background object handle
 162  * @param option The desired background option (see #Elm_Bg_Option)
 163  *
 164  * This sets how the background widget will display its image. This
 165  * will only work if the elm_bg_file_set() was previously called with
 166  * an image file on @a obj. The image can be display tiled, scaled,
 167  * centered or stretched.
 168  *
 169  * @see elm_bg_option_get()
 170 >>>>>>> remotes/origin/upstream
 171  *
 172  * @ingroup Bg
 173  */
 174 EAPI void                         elm_bg_option_set(Evas_Object *obj, Elm_Bg_Option option);
 175
 176 /**
 177 <<<<<<< HEAD
 178  * Get the option used for the background image
 179  *
 180  * @param obj The bg object
 181  * @return The desired background option (CENTER, SCALE, STRETCH or TILE)
 182 =======
 183  * Get the mode of display for a given background widget's image
 184  *
 185  * @param obj The background object handle
 186  * @return The image displaying mode in use for @a obj or
 187  * #ELM_BG_OPTION_LAST, on errors.
 188  *
 189  * @see elm_bg_option_set() for more details
 190 >>>>>>> remotes/origin/upstream
 191  *
 192  * @ingroup Bg
 193  */
 194 EAPI Elm_Bg_Option                elm_bg_option_get(const Evas_Object *obj);
 195 <<<<<<< HEAD
 196 /**
 197  * Set the option used for the background color
 198  *
 199  * @param obj The bg object
 200  * @param r
 201  * @param g
 202  * @param b
 203  *
 204  * This sets the color used for the background rectangle. Its range goes
 205  * from 0 to 255.
 206 =======
 207
 208 /**
 209  * Set the color on a given background widget
 210  *
 211  * @param obj The background object handle
 212  * @param r The red color component's value
 213  * @param g The green color component's value
 214  * @param b The blue color component's value
 215  *
 216  * This sets the color used for the background rectangle, in RGB
 217  * format. Each color component's range is from 0 to 255.
 218  *
 219  * @note You probably only want to use this function if you haven't
 220  * previously called elm_bg_file_set(), so that you just want a solid
 221  * color background.
 222  *
 223  * @see elm_bg_color_get()
 224 >>>>>>> remotes/origin/upstream
 225  *
 226  * @ingroup Bg
 227  */
 228 EAPI void                         elm_bg_color_set(Evas_Object *obj, int r, int g, int b);
 229 <<<<<<< HEAD
 230 /**
 231  * Get the option used for the background color
 232  *
 233  * @param obj The bg object
 234  * @param r
 235  * @param g
 236  * @param b
 237 =======
 238
 239 /**
 240  * Get the color set on a given background widget
 241  *
 242  * @param obj The background object handle
 243  * @param r Where to store the red color component's value
 244  * @param g Where to store the green color component's value
 245  * @param b Where to store the blue color component's value
 246  *
 247  * @note Use @c NULL pointers on the file components you're not
 248  * interested in: they'll be ignored by the function.
 249  *
 250  * @see elm_bg_color_get() for more details
 251 >>>>>>> remotes/origin/upstream
 252  *
 253  * @ingroup Bg
 254  */
 255 EAPI void                         elm_bg_color_get(const Evas_Object *obj, int *r, int *g, int *b);
 256
 257 /**
 258 <<<<<<< HEAD
 259  * Set the size of the pixmap representation of the image.
 260  *
 261  * This option just makes sense if an image is going to be set in the bg.
 262  *
 263  * @param obj The bg object
 264  * @param w The new width of the image pixmap representation.
 265  * @param h The new height of the image pixmap representation.
 266  *
 267  * This function sets a new size for pixmap representation of the given bg
 268  * image. It allows the image to be loaded already in the specified size,
 269  * reducing the memory usage and load time when loading a big image with load
 270  * size set to a smaller size.
 271  *
 272  * NOTE: this is just a hint, the real size of the pixmap may differ
 273  * depending on the type of image being loaded, being bigger than requested.
 274 =======
 275  * Set the size of the pixmap representation of the image set on a
 276  * given background widget.
 277  *
 278  * @param obj The background object handle
 279  * @param w The new width of the image pixmap representation.
 280  * @param h The new height of the image pixmap representation.
 281  *
 282  * @warning This function just makes sense if an image file was set on
 283  * @p obj, with elm_bg_file_set().
 284  *
 285  * This function sets a new size for pixmap representation of the
 286  * given bg image. It allows for the image to be loaded already in the
 287  * specified size, reducing the memory usage and load time (for
 288  * example, when loading a big image file with its load size set to a
 289  * smaller size)
 290  *
 291  * @note This is just a hint for the underlying system. The real size
 292  * of the pixmap may differ depending on the type of image being
 293  * loaded, being bigger than requested.
 294 >>>>>>> remotes/origin/upstream
 295  *
 296  * @ingroup Bg
 297  */
 298 EAPI void                         elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h);
 299
 300 /**
 301  * @}
 302  */