Macros | Enumerations | Functions
Background

Background object, used for setting a solid color, image or Edje group as a background to a window or any container object. More...

Macros

#define ELM_BG_CLASS   elm_bg_class_get()
 The bg (background) widget is used for setting (solid) background decorations. More...
 

Enumerations

enum  Elm_Bg_Option {
  ELM_BG_OPTION_CENTER = 0,
  ELM_BG_OPTION_SCALE,
  ELM_BG_OPTION_STRETCH,
  ELM_BG_OPTION_TILE,
  ELM_BG_OPTION_LAST,
  ELM_BG_OPTION_CENTER = 0,
  ELM_BG_OPTION_SCALE,
  ELM_BG_OPTION_STRETCH,
  ELM_BG_OPTION_TILE,
  ELM_BG_OPTION_LAST
}
 Identifiers on how a background widget is to display its image. More...
 
enum  Elm_Bg_Option {
  ELM_BG_OPTION_CENTER = 0,
  ELM_BG_OPTION_SCALE,
  ELM_BG_OPTION_STRETCH,
  ELM_BG_OPTION_TILE,
  ELM_BG_OPTION_LAST,
  ELM_BG_OPTION_CENTER = 0,
  ELM_BG_OPTION_SCALE,
  ELM_BG_OPTION_STRETCH,
  ELM_BG_OPTION_TILE,
  ELM_BG_OPTION_LAST
}
 Identifiers on how a background widget is to display its image. More...
 

Functions

EOAPI void elm_obj_bg_option_set (Eo *obj, Elm_Bg_Option option)
 The mode of display for a given background widget's image. More...
 
EOAPI Elm_Bg_Option elm_obj_bg_option_get (const Eo *obj)
 The mode of display for a given background widget's image. More...
 
EOAPI void elm_obj_bg_color_set (Eo *obj, int r, int g, int b, int a)
 The color on a given background widget. More...
 
EOAPI void elm_obj_bg_color_get (const Eo *obj, int *r, int *g, int *b, int *a)
 The color on a given background widget. More...
 
EOAPI void elm_obj_bg_load_size_set (Eo *obj, int w, int h)
 Set the size of the pixmap representation of the image set on a given background widget. More...
 
void elm_bg_option_set (Elm_Bg *obj, Elm_Bg_Option option)
 The mode of display for a given background widget's image. More...
 
Elm_Bg_Option elm_bg_option_get (const Elm_Bg *obj)
 The mode of display for a given background widget's image. More...
 
void elm_bg_load_size_set (Elm_Bg *obj, int w, int h)
 Set the size of the pixmap representation of the image set on a given background widget. More...
 
Evas_Objectelm_bg_add (Evas_Object *parent)
 Add a new background to the parent. More...
 
void elm_bg_color_set (Evas_Object *obj, int r, int g, int b)
 Set the color on a given background widget. More...
 
void elm_bg_color_get (const Evas_Object *obj, int *r, int *g, int *b)
 Get the color set on a given background widget. More...
 
Eina_Bool elm_bg_file_set (Eo *obj, const char *file, const char *group)
 Set the file (image or edje collection) to give life for the background. More...
 
void elm_bg_file_get (const Eo *obj, const char **file, const char **group)
 Get the file (image or edje collection) set on a given background widget. More...
 

Detailed Description

Background object, used for setting a solid color, image or Edje group as a background to a window or any container object.

bg_inheritance_tree.png
preview-00.png

The bg (background) widget is used for setting (solid) background decorations to a window (unless it has transparency enabled) or to any container object. It works just like an image, but has some properties useful to a background, like setting it to tiled, centered, scaled or stretched.

This widget inherits from the Layout one, so that all the functions acting on it also work for background objects.

Default content parts of the bg widget that you can use for are:

Here is some sample code using it:

Macro Definition Documentation

◆ ELM_BG_CLASS

#define ELM_BG_CLASS   elm_bg_class_get()

The bg (background) widget is used for setting (solid) background decorations.

to a window (unless it has transparency enabled) or to any container object. It works just like an image, but has some properties useful to a background, like setting it to tiled, centered, scaled or stretched.

Referenced by elm_win_floating_mode_get().

Enumeration Type Documentation

◆ Elm_Bg_Option [1/2]

Identifiers on how a background widget is to display its image.

– if it was set to use an image file.

See also elm_obj_bg_option_set, elm_obj_bg_option_get.

Enumerator
ELM_BG_OPTION_CENTER 

Center the background image.

ELM_BG_OPTION_SCALE 

Scale the background image, retaining aspect ratio (default).

ELM_BG_OPTION_STRETCH 

Stretch the background image to fill the widget's area.

ELM_BG_OPTION_TILE 

Tile background image at its original size.

ELM_BG_OPTION_LAST 

Sentinel value to indicate last enum field during iteration.

Also used to indicate errors

ELM_BG_OPTION_CENTER 

Center the background image.

ELM_BG_OPTION_SCALE 

Scale the background image, retaining aspect ratio (default).

ELM_BG_OPTION_STRETCH 

Stretch the background image to fill the widget's area.

ELM_BG_OPTION_TILE 

Tile background image at its original size.

ELM_BG_OPTION_LAST 

Sentinel value to indicate last enum field during iteration.

Also used to indicate errors

◆ Elm_Bg_Option [2/2]

Identifiers on how a background widget is to display its image.

– if it was set to use an image file.

See also elm_bg_option_set, elm_bg_option_get.

Enumerator
ELM_BG_OPTION_CENTER 

Center the background image.

ELM_BG_OPTION_SCALE 

Scale the background image, retaining aspect ratio (default).

ELM_BG_OPTION_STRETCH 

Stretch the background image to fill the widget's area.

ELM_BG_OPTION_TILE 

Tile background image at its original size.

ELM_BG_OPTION_LAST 

Sentinel value to indicate last enum field during iteration.

Also used to indicate errors

ELM_BG_OPTION_CENTER 

Center the background image.

ELM_BG_OPTION_SCALE 

Scale the background image, retaining aspect ratio (default).

ELM_BG_OPTION_STRETCH 

Stretch the background image to fill the widget's area.

ELM_BG_OPTION_TILE 

Tile background image at its original size.

ELM_BG_OPTION_LAST 

Sentinel value to indicate last enum field during iteration.

Also used to indicate errors

Function Documentation

◆ elm_obj_bg_option_set()

EOAPI void elm_obj_bg_option_set ( Eo obj,
Elm_Bg_Option  option 
)

The mode of display for a given background widget's image.

This sets how the background widget will display its image. This will only work if the efl_file_set was previously called with an image file on obj. The image can be display tiled, scaled, centered or stretched. ELM_BG_OPTION_SCALE by default.

Parameters
[in]optionThe desired background option(See Elm_Bg_Option)

Referenced by elm_bg_option_set().

◆ elm_obj_bg_option_get()

EOAPI Elm_Bg_Option elm_obj_bg_option_get ( const Eo obj)

The mode of display for a given background widget's image.

Returns
The desired background option(See Elm_Bg_Option)

Referenced by elm_bg_option_get().

◆ elm_obj_bg_color_set()

EOAPI void elm_obj_bg_color_set ( Eo obj,
int  r,
int  g,
int  b,
int  a 
)

The color on a given background widget.

This sets the color used for the background rectangle, in RGB format. Each color component's range is from 0 to 255.

Note
You probably only want to use this function if you haven't previously called efl_file_set, so that you just want a solid color background.
You can reset the color by setting r, g, b as -1, -1, -1.
Parameters
[in]rThe red color component's value
[in]gThe green color component's value
[in]bThe blue color component's value
[in]aThe alpha color component's value

Referenced by elm_bg_color_set().

◆ elm_obj_bg_color_get()

EOAPI void elm_obj_bg_color_get ( const Eo obj,
int *  r,
int *  g,
int *  b,
int *  a 
)

The color on a given background widget.

Note
Use null pointers on the file components you're not interested in: they'll be ignored by the function.
Parameters
[out]rThe red color component's value
[out]gThe green color component's value
[out]bThe blue color component's value
[out]aThe alpha color component's value

Referenced by elm_bg_color_get().

◆ elm_obj_bg_load_size_set()

EOAPI void elm_obj_bg_load_size_set ( Eo obj,
int  w,
int  h 
)

Set the size of the pixmap representation of the image set on a given background widget.

Warning
This function just makes sense if an image file was set on obj, with efl_file_set

This function sets a new size for pixmap representation of the given bg image. It allows for the image to be loaded already in the specified size, reducing the memory usage and load time (for example, when loading a big image file with its load size set to a smaller size)

Note
This is just a hint for the underlying system. The real size of the pixmap may differ depending on the type of image being loaded, being bigger than requested.
Parameters
[in]wThe new width of the image pixmap representation.
[in]hThe new height of the image pixmap representation.

Referenced by elm_bg_load_size_set().

◆ elm_bg_option_set()

void elm_bg_option_set ( Elm_Bg *  obj,
Elm_Bg_Option  option 
)

The mode of display for a given background widget's image.

This sets how the background widget will display its image. This will only work if the Efl.File.file.set was previously called with an image file on obj. The image can be display tiled, scaled, centered or stretched. ELM_BG_OPTION_SCALE by default.

Parameters
[in]optionThe desired background option(See Elm_Bg_Option)

References elm_obj_bg_option_set().

◆ elm_bg_option_get()

Elm_Bg_Option elm_bg_option_get ( const Elm_Bg *  obj)

The mode of display for a given background widget's image.

Returns
The desired background option(See Elm_Bg_Option)

References elm_obj_bg_option_get().

◆ elm_bg_load_size_set()

void elm_bg_load_size_set ( Elm_Bg *  obj,
int  w,
int  h 
)

Set the size of the pixmap representation of the image set on a given background widget.

Warning
This function just makes sense if an image file was set on obj, with Efl.File.file.set

This function sets a new size for pixmap representation of the given bg image. It allows for the image to be loaded already in the specified size, reducing the memory usage and load time (for example, when loading a big image file with its load size set to a smaller size)

Note
This is just a hint for the underlying system. The real size of the pixmap may differ depending on the type of image being loaded, being bigger than requested.
Parameters
[in]wThe new width of the image pixmap representation.
[in]hThe new height of the image pixmap representation.

References elm_obj_bg_load_size_set().

◆ elm_bg_add()

Evas_Object* elm_bg_add ( Evas_Object parent)

Add a new background to the parent.

Parameters
parentThe parent object
Returns
The new object or NULL if it cannot be created

Referenced by elm_quicklaunch_seed(), and elm_win_floating_mode_get().

◆ elm_bg_color_set()

void elm_bg_color_set ( Evas_Object obj,
int  r,
int  g,
int  b 
)

Set the color on a given background widget.

Parameters
objThe background object handle
rThe red color component's value
gThe green color component's value
bThe blue color component's value

This sets the color used for the background rectangle, in RGB format. Each color component's range is from 0 to 255.

Note
You probably only want to use this function if you haven't previously called elm_bg_file_set(), so that you just want a solid color background.
You can reset the color by setting r, g, b as -1, -1, -1.
See also
elm_bg_color_get()

References elm_layout_content_set(), elm_layout_sizing_eval(), elm_obj_bg_color_set(), evas_object_color_set(), evas_object_del(), and evas_object_rectangle_add().

◆ elm_bg_color_get()

void elm_bg_color_get ( const Evas_Object obj,
int *  r,
int *  g,
int *  b 
)

Get the color set on a given background widget.

Parameters
objThe background object handle
rWhere to store the red color component's value
gWhere to store the green color component's value
bWhere to store the blue color component's value
Note
Use NULL pointers on the file components you're not interested in: they'll be ignored by the function.
See also
elm_bg_color_get() for more details

References elm_obj_bg_color_get(), evas_object_color_get(), and evas_smart_legacy_type_register().

◆ elm_bg_file_set()

Eina_Bool elm_bg_file_set ( Eo obj,
const char *  file,
const char *  group 
)

Set the file (image or edje collection) to give life for the background.

Returns
EINA_TRUE on success, EINA_FALSE otherwise

This sets the image file used in the background object. If the image comes from an Edje group, it will be stretched to completely fill the background object. If it comes from a traditional image file, it will by default be centered in this widget's area (thus retaining its aspect), what could lead to some parts being not visible. You may change the mode of exhibition for a real image file with elm_bg_option_set().

Note
Once the image of obj is set, a previously set one will be deleted, even if file is NULL.
This will only affect the contents of one of the background's swallow spots, namely "elm.swallow.background". If you want to achieve the Layout's file setting behavior, you'll have to call that method on this object.
Parameters
[in]fileThe file path
[in]groupOptional key (group in Edje) within the file

◆ elm_bg_file_get()

void elm_bg_file_get ( const Eo obj,
const char **  file,
const char **  group 
)

Get the file (image or edje collection) set on a given background widget.

Note
Use NULL pointers on the file components you're not interested in: they'll be ignored by the function.
Parameters
[out]fileThe file path
[out]groupOptional key (group in Edje) within the file