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 _Elm_Bg_Option
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
  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) EINA_ARG_NONNULL(1);
 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) EINA_ARG_NONNULL(1);
 119
 120    /**
 121     * Set the overlay object used for the background object.
 122     *
 123     * @param obj The bg object
 124     * @param overlay The overlay object
 125     *
 126     * This provides a way for elm_bg to have an 'overlay' that will be on top
 127     * of the bg. Once the over object is set, a previously set one will be
 128     * deleted, even if you set the new one to NULL. If you want to keep that
 129     * old content object, use the elm_bg_overlay_unset() function.
 130     *
 131     * @deprecated use elm_object_part_content_set() instead
 132     *
 133     * @ingroup Bg
 134     */
 135
 136    EINA_DEPRECATED EAPI void          elm_bg_overlay_set(Evas_Object *obj, Evas_Object *overlay) EINA_ARG_NONNULL(1);
 137
 138    /**
 139     * Get the overlay object used for the background object.
 140     *
 141     * @param obj The bg object
 142     * @return The content that is being used
 143     *
 144     * Return the content object which is set for this widget
 145     *
 146     * @deprecated use elm_object_part_content_get() instead
 147     *
 148     * @ingroup Bg
 149     */
 150    EINA_DEPRECATED EAPI Evas_Object  *elm_bg_overlay_get(const Evas_Object *obj) EINA_ARG_NONNULL(1);
 151
 152    /**
 153     * Get the overlay object used for the background object.
 154     *
 155     * @param obj The bg object
 156     * @return The content that was being used
 157     *
 158     * Unparent and return the overlay object which was set for this widget
 159     *
 160     * @deprecated use elm_object_part_content_unset() instead
 161     *
 162     * @ingroup Bg
 163     */
 164    EINA_DEPRECATED EAPI Evas_Object  *elm_bg_overlay_unset(Evas_Object *obj) EINA_ARG_NONNULL(1);
 165
 166    /**
 167     * Set the size of the pixmap representation of the image.
 168     *
 169     * This option just makes sense if an image is going to be set in the bg.
 170     *
 171     * @param obj The bg object
 172     * @param w The new width of the image pixmap representation.
 173     * @param h The new height of the image pixmap representation.
 174     *
 175     * This function sets a new size for pixmap representation of the given bg
 176     * image. It allows the image to be loaded already in the specified size,
 177     * reducing the memory usage and load time when loading a big image with load
 178     * size set to a smaller size.
 179     *
 180     * NOTE: this is just a hint, the real size of the pixmap may differ
 181     * depending on the type of image being loaded, being bigger than requested.
 182     *
 183     * @ingroup Bg
 184     */
 185    EAPI void          elm_bg_load_size_set(Evas_Object *obj, Evas_Coord w, Evas_Coord h) EINA_ARG_NONNULL(1);
 186
 187    /**
 188     * @}
 189     */
 190