class sap.m.Image

Control sample: sap.m.Image
Visiblity: public
UX Guidelines: Image
Implements: sap.ui.core.IFormContent
Available since: N/A
Module: sap/m/Image
Application Component: CA-UI5-CTR

A wrapper around the <img> tag; the image can be loaded from a remote or local server.

If property densityAware is true, a density-specific image will be loaded by constructing a density-specific image name in format [imageName]@[densityValue].[extension] from the given src and the devicePixelRatio of the current device. The only supported density values are 1, 1.5 and 2. If the original devicePixelRatio ratio isn't one of the three valid numbers, it will be rounded to the nearest one.

There are various size setting options available, and the images can be combined with actions.

From version 1.30, a new image mode sap.m.ImageMode.Background is added. When this mode is set, the src property is set using the CSS style background-image. The properties backgroundSize, backgroundPosition, and backgroundRepeat take effect only when the image is in sap.m.ImageMode.Background mode. In order to display the high density image correctly, the backgroundSize should be set to the dimension of the normal density version.

This control can be a drag source.

Constructor

Constructor for a new Image.

Accepts an object literal mSettings that defines initial property values, aggregated and associated objects as well as event handlers. See sap.ui.base.ManagedObject#constructor for a general description of the syntax of the settings object.

new sap.m.Image(sId?, mSettings?)
Param Type Default Value Description
sId? string

id for the new control, generated automatically if no id is given

mSettings? object

initial settings for the new control


Properties

Name Type Default Value Description
activeSrc sap.ui.core.URI empty string

The source property which is used when the image is pressed.

Visibility: public
alt string

The alternative text that is displayed in case the image is not available, or cannot be displayed.

If the image is set to decorative, this property is ignored.

Visibility: public
ariaHasPopup sap.ui.core.aria.HasPopup None

Defines the aria-haspopup attribute of the Image.

Guidance for choosing appropriate value:

  • We recommend you to use the property only when press handler is set.
  • If you use controls based on sap.m.Popover or sap.m.Dialog, then you must use AriaHasPopup.Dialog (both sap.m.Popover and sap.m.Dialog have role "dialog" assigned internally).
  • If you use other controls, or directly sap.ui.core.Popup, you need to check the container role/type and map the value of ariaHasPopup accordingly.


Since: 1.87.0.

Visibility: public
backgroundPosition string initial

Defines the position of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-position. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Since: 1.30.0.

Visibility: public
backgroundRepeat string no-repeat

Defines whether the source image is repeated when the output DOM element is bigger than the source.

This property is set on the output DOM element using the CSS style background-repeat. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Since: 1.30.0.

Visibility: public
backgroundSize string cover

Defines the size of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-size. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Since: 1.30.0.

Visibility: public
decorative boolean true

A decorative image is included for design reasons; accessibility tools will ignore decorative images.

Note: If the image has an image map (useMap is set), this property will be overridden (the image will not be rendered as decorative). A decorative image has no ALT attribute, so the alt property is ignored if the image is decorative.

Visibility: public
densityAware boolean false

If this is set to true, one or more network requests will be made that try to obtain the density perfect version of the image.

By default, this is set to false, so the src image is loaded directly without attempting to fetch the density perfect image for high-density devices.

Note: Before 1.60, the default value was set to true, which brought redundant network requests for apps that used the default but did not provide density perfect image versions on server-side. You should set this property to true only if you also provide the corresponding image versions for high-density devices.

Visibility: public
height sap.ui.core.CSSSize

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

Visibility: public
lazyLoading boolean false

Enables lazy loading for images that are offscreen. If set to true, the property ensures that offscreen images are loaded early enough so that they have finished loading once the user scrolls near them.

Note: Keep in mind that the property uses the loading attribute of HTML <img> element which is not supported for Internet Explorer.

Since: 1.87.

Visibility: public
mode sap.m.ImageMode Image

Defines how the src and the activeSrc is output to the DOM Element.

When set to sap.m.ImageMode.Image, which is the default value, the src (activeSrc) is set to the src attribute of the <img> tag. When set to sap.m.ImageMode.Background, the src (activeSrc) is set to the CSS style background-image and the root DOM element is rendered as a <span> tag instead of an <img> tag.

Since: 1.30.0.

Visibility: public
src sap.ui.core.URI

Relative or absolute path to URL where the image file is stored.

The path will be adapted to the density-aware format according to the density of the device following the naming convention [imageName]@[densityValue].[extension].

Visibility: public
useMap string

The name of the image map that defines the clickable areas.

Visibility: public
width sap.ui.core.CSSSize

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

Visibility: public

Aggregations

Default Aggregation:

Name Cardinality Type Description
detailBox 0..1 sap.m.LightBox

A sap.m.LightBox instance that will be opened automatically when the user interacts with the Image control.

The tap event will still be fired.


Associations

Name Cardinality Type Description
ariaDescribedBy 0..n sap.ui.core.Control

Association to controls / ids which describe this control (see WAI-ARIA attribute aria-describedby).

ariaDetails 0..n sap.ui.core.Control

Association to controls / IDs which are details to this control (see WAI-ARIA attribute aria-details).

Since: 1.79.

ariaLabelledBy 0..n sap.ui.core.Control

Association to controls / ids which label this control (see WAI-ARIA attribute aria-labelledBy).


Events Overview

Event Description
error

Event is fired when the image resource can't be loaded. If densityAware is set to true, the event is fired when none of the fallback resources can be loaded.

Since: 1.36.2.

load

Event is fired when the image resource is loaded.

Since: 1.36.2.

press

Event is fired when the user clicks on the control.

tap

Event is fired when the user clicks on the control. (This event is deprecated, use the press event instead)

error

Event is fired when the image resource can't be loaded. If densityAware is set to true, the event is fired when none of the fallback resources can be loaded.

Since: 1.36.2.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

load

Event is fired when the image resource is loaded.

Since: 1.36.2.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

press

Event is fired when the user clicks on the control.

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

tap

Event is fired when the user clicks on the control. (This event is deprecated, use the press event instead)

Param Type Description
oControlEvent sap.ui.base.Event
getSource sap.ui.base.EventProvider
getParameters object

Methods Overview

Method Description
_isValidBackgroundPositionValue

Checks if the given value is valid for the background-position CSS property

_isValidBackgroundSizeValue

Checks if the given value is valid for the background-size CSS property

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

addAriaDetails

Adds some ariaDetails into the association ariaDetails.

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

attachError

Attaches event handler fnFunction to the error event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the image resource can't be loaded. If densityAware is set to true, the event is fired when none of the fallback resources can be loaded.

attachLoad

Attaches event handler fnFunction to the load event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the image resource is loaded.

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the user clicks on the control.

attachTap

Attaches event handler fnFunction to the tap event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the user clicks on the control. (This event is deprecated, use the press event instead)

bindDetailBox

Binds aggregation detailBox to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

destroyDetailBox

Destroys the detailBox in the aggregation detailBox.

detachError

Detaches event handler fnFunction from the error event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

detachLoad

Detaches event handler fnFunction from the load event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

detachTap

Detaches event handler fnFunction from the tap event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

sap.m.Image.extend

Creates a new subclass of class sap.m.Image with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

fireError

Fires event error to attached listeners.

fireLoad

Fires event load to attached listeners.

firePress

Fires event press to attached listeners.

fireTap

Fires event tap to attached listeners.

getAccessibilityInfo

Returns the sap.m.Image accessibility information.

References:

  • sap.ui.core.Control#getAccessibilityInfo

getActiveSrc

Gets current value of property activeSrc.

The source property which is used when the image is pressed.

Default value is empty string.

getAlt

Gets current value of property alt.

The alternative text that is displayed in case the image is not available, or cannot be displayed.

If the image is set to decorative, this property is ignored.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaDetails

Returns array of IDs of the elements which are the current targets of the association ariaDetails.

getAriaHasPopup

Gets current value of property ariaHasPopup.

Defines the aria-haspopup attribute of the Image.

Guidance for choosing appropriate value:

  • We recommend you to use the property only when press handler is set.
  • If you use controls based on sap.m.Popover or sap.m.Dialog, then you must use AriaHasPopup.Dialog (both sap.m.Popover and sap.m.Dialog have role "dialog" assigned internally).
  • If you use other controls, or directly sap.ui.core.Popup, you need to check the container role/type and map the value of ariaHasPopup accordingly.

Default value is None.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getBackgroundPosition

Gets current value of property backgroundPosition.

Defines the position of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-position. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Default value is "initial".

getBackgroundRepeat

Gets current value of property backgroundRepeat.

Defines whether the source image is repeated when the output DOM element is bigger than the source.

This property is set on the output DOM element using the CSS style background-repeat. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Default value is "no-repeat".

getBackgroundSize

Gets current value of property backgroundSize.

Defines the size of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-size. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Default value is "cover".

getDecorative

Gets current value of property decorative.

A decorative image is included for design reasons; accessibility tools will ignore decorative images.

Note: If the image has an image map (useMap is set), this property will be overridden (the image will not be rendered as decorative). A decorative image has no ALT attribute, so the alt property is ignored if the image is decorative.

Default value is true.

getDensityAware

Gets current value of property densityAware.

If this is set to true, one or more network requests will be made that try to obtain the density perfect version of the image.

By default, this is set to false, so the src image is loaded directly without attempting to fetch the density perfect image for high-density devices.

Note: Before 1.60, the default value was set to true, which brought redundant network requests for apps that used the default but did not provide density perfect image versions on server-side. You should set this property to true only if you also provide the corresponding image versions for high-density devices.

Default value is false.

getDetailBox

Gets content of aggregation detailBox.

A sap.m.LightBox instance that will be opened automatically when the user interacts with the Image control.

The tap event will still be fired.

getHeight

Gets current value of property height.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

getLazyLoading

Gets current value of property lazyLoading.

Enables lazy loading for images that are offscreen. If set to true, the property ensures that offscreen images are loaded early enough so that they have finished loading once the user scrolls near them.

Note: Keep in mind that the property uses the loading attribute of HTML <img> element which is not supported for Internet Explorer.

Default value is false.

sap.m.Image.getMetadata

Returns a metadata object for class sap.m.Image.

getMode

Gets current value of property mode.

Defines how the src and the activeSrc is output to the DOM Element.

When set to sap.m.ImageMode.Image, which is the default value, the src (activeSrc) is set to the src attribute of the <img> tag. When set to sap.m.ImageMode.Background, the src (activeSrc) is set to the CSS style background-image and the root DOM element is rendered as a <span> tag instead of an <img> tag.

Default value is "Image".

getSrc

Gets current value of property src.

Relative or absolute path to URL where the image file is stored.

The path will be adapted to the density-aware format according to the density of the device following the naming convention [imageName]@[densityValue].[extension].

getUseMap

Gets current value of property useMap.

The name of the image map that defines the clickable areas.

getWidth

Gets current value of property width.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaDetails

Removes all the controls in the association named ariaDetails.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

removeAriaDetails

Removes an ariaDetails from the association named ariaDetails.

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

setActiveSrc

Sets a new value for property activeSrc.

The source property which is used when the image is pressed.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

setAlt

Sets a new value for property alt.

The alternative text that is displayed in case the image is not available, or cannot be displayed.

If the image is set to decorative, this property is ignored.

When called with a value of null or undefined, the default value of the property will be restored.

setAriaHasPopup

Sets a new value for property ariaHasPopup.

Defines the aria-haspopup attribute of the Image.

Guidance for choosing appropriate value:

  • We recommend you to use the property only when press handler is set.
  • If you use controls based on sap.m.Popover or sap.m.Dialog, then you must use AriaHasPopup.Dialog (both sap.m.Popover and sap.m.Dialog have role "dialog" assigned internally).
  • If you use other controls, or directly sap.ui.core.Popup, you need to check the container role/type and map the value of ariaHasPopup accordingly.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

setBackgroundPosition

Sets a new value for property backgroundPosition.

Defines the position of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-position. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "initial".

setBackgroundRepeat

Sets a new value for property backgroundRepeat.

Defines whether the source image is repeated when the output DOM element is bigger than the source.

This property is set on the output DOM element using the CSS style background-repeat. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "no-repeat".

setBackgroundSize

Sets a new value for property backgroundSize.

Defines the size of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-size. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "cover".

setDecorative

Sets a new value for property decorative.

A decorative image is included for design reasons; accessibility tools will ignore decorative images.

Note: If the image has an image map (useMap is set), this property will be overridden (the image will not be rendered as decorative). A decorative image has no ALT attribute, so the alt property is ignored if the image is decorative.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

setDensityAware

Sets a new value for property densityAware.

If this is set to true, one or more network requests will be made that try to obtain the density perfect version of the image.

By default, this is set to false, so the src image is loaded directly without attempting to fetch the density perfect image for high-density devices.

Note: Before 1.60, the default value was set to true, which brought redundant network requests for apps that used the default but did not provide density perfect image versions on server-side. You should set this property to true only if you also provide the corresponding image versions for high-density devices.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setDetailBox

Sets the detailBox aggregation.

setHeight

Sets a new value for property height.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

When called with a value of null or undefined, the default value of the property will be restored.

setLazyLoading

Sets a new value for property lazyLoading.

Enables lazy loading for images that are offscreen. If set to true, the property ensures that offscreen images are loaded early enough so that they have finished loading once the user scrolls near them.

Note: Keep in mind that the property uses the loading attribute of HTML <img> element which is not supported for Internet Explorer.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

setMode

Sets a new value for property mode.

Defines how the src and the activeSrc is output to the DOM Element.

When set to sap.m.ImageMode.Image, which is the default value, the src (activeSrc) is set to the src attribute of the <img> tag. When set to sap.m.ImageMode.Background, the src (activeSrc) is set to the CSS style background-image and the root DOM element is rendered as a <span> tag instead of an <img> tag.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "Image".

setSrc

Sets a new value for property src.

Relative or absolute path to URL where the image file is stored.

The path will be adapted to the density-aware format according to the density of the device following the naming convention [imageName]@[densityValue].[extension].

When called with a value of null or undefined, the default value of the property will be restored.

setUseMap

Sets a new value for property useMap.

The name of the image map that defines the clickable areas.

When called with a value of null or undefined, the default value of the property will be restored.

setWidth

Sets a new value for property width.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

When called with a value of null or undefined, the default value of the property will be restored.

unbindDetailBox

Unbinds aggregation detailBox from model data.

_isValidBackgroundPositionValue

Checks if the given value is valid for the background-position CSS property

Param Type DefaultValue Description
sValue string

the value to check

_isValidBackgroundSizeValue

Checks if the given value is valid for the background-size CSS property

Param Type DefaultValue Description
sValue string

the value to check

addAriaDescribedBy

Adds some ariaDescribedBy into the association ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to add; if empty, nothing is inserted

addAriaDetails

Adds some ariaDetails into the association ariaDetails.

Param Type DefaultValue Description
vAriaDetails sap.ui.core.ID sap.ui.core.Control

The ariaDetails to add; if empty, nothing is inserted

addAriaLabelledBy

Adds some ariaLabelledBy into the association ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to add; if empty, nothing is inserted

attachError

Attaches event handler fnFunction to the error event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the image resource can't be loaded. If densityAware is set to true, the event is fired when none of the fallback resources can be loaded.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Image itself

attachLoad

Attaches event handler fnFunction to the load event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the image resource is loaded.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Image itself

attachPress

Attaches event handler fnFunction to the press event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the user clicks on the control.

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Image itself

attachTap

Attaches event handler fnFunction to the tap event of this sap.m.Image.

When called, the context of the event handler (its this) will be bound to oListener if specified, otherwise it will be bound to this sap.m.Image itself.

Event is fired when the user clicks on the control. (This event is deprecated, use the press event instead)

Param Type DefaultValue Description
oData object

An application-specific payload object that will be passed to the event handler along with the event object when firing the event

fnFunction function(sap.ui.base.Event) : void

The function to be called when the event occurs

oListener object

Context object to call the event handler with. Defaults to this sap.m.Image itself

bindDetailBox

Binds aggregation detailBox to model data.

See ManagedObject.bindAggregation for a detailed description of the possible properties of oBindingInfo.

Param Type DefaultValue Description
oBindingInfo sap.ui.base.ManagedObject.AggregationBindingInfo

The binding information

destroyDetailBox

Destroys the detailBox in the aggregation detailBox.

detachError

Detaches event handler fnFunction from the error event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachLoad

Detaches event handler fnFunction from the load event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachPress

Detaches event handler fnFunction from the press event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

detachTap

Detaches event handler fnFunction from the tap event of this sap.m.Image.

The passed function and listener object must match the ones used for event registration.

Param Type DefaultValue Description
fnFunction function(sap.ui.base.Event) : void

The function to be called, when the event occurs

oListener object

Context object on which the given function had to be called

sap.m.Image.extend

Creates a new subclass of class sap.m.Image with name sClassName and enriches it with the information contained in oClassInfo.

oClassInfo might contain the same kind of information as described in sap.ui.core.Control.extend.

Param Type DefaultValue Description
sClassName string

Name of the class being created

oClassInfo object

Object literal with information about the class

FNMetaImpl function

Constructor function for the metadata object; if not given, it defaults to the metadata implementation used by this class

fireError

Fires event error to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireLoad

Fires event load to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

firePress

Fires event press to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

fireTap

Fires event tap to attached listeners.

Param Type DefaultValue Description
mParameters object

Parameters to pass along with the event

getAccessibilityInfo

Returns the sap.m.Image accessibility information.

References:

getActiveSrc

Gets current value of property activeSrc.

The source property which is used when the image is pressed.

Default value is empty string.

getAlt

Gets current value of property alt.

The alternative text that is displayed in case the image is not available, or cannot be displayed.

If the image is set to decorative, this property is ignored.

getAriaDescribedBy

Returns array of IDs of the elements which are the current targets of the association ariaDescribedBy.

getAriaDetails

Returns array of IDs of the elements which are the current targets of the association ariaDetails.

getAriaHasPopup

Gets current value of property ariaHasPopup.

Defines the aria-haspopup attribute of the Image.

Guidance for choosing appropriate value:

Default value is None.

getAriaLabelledBy

Returns array of IDs of the elements which are the current targets of the association ariaLabelledBy.

getBackgroundPosition

Gets current value of property backgroundPosition.

Defines the position of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-position. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Default value is "initial".

getBackgroundRepeat

Gets current value of property backgroundRepeat.

Defines whether the source image is repeated when the output DOM element is bigger than the source.

This property is set on the output DOM element using the CSS style background-repeat. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Default value is "no-repeat".

getBackgroundSize

Gets current value of property backgroundSize.

Defines the size of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-size. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

Default value is "cover".

getDecorative

Gets current value of property decorative.

A decorative image is included for design reasons; accessibility tools will ignore decorative images.

Note: If the image has an image map (useMap is set), this property will be overridden (the image will not be rendered as decorative). A decorative image has no ALT attribute, so the alt property is ignored if the image is decorative.

Default value is true.

getDensityAware

Gets current value of property densityAware.

If this is set to true, one or more network requests will be made that try to obtain the density perfect version of the image.

By default, this is set to false, so the src image is loaded directly without attempting to fetch the density perfect image for high-density devices.

Note: Before 1.60, the default value was set to true, which brought redundant network requests for apps that used the default but did not provide density perfect image versions on server-side. You should set this property to true only if you also provide the corresponding image versions for high-density devices.

Default value is false.

getDetailBox

Gets content of aggregation detailBox.

A sap.m.LightBox instance that will be opened automatically when the user interacts with the Image control.

The tap event will still be fired.

getHeight

Gets current value of property height.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

getLazyLoading

Gets current value of property lazyLoading.

Enables lazy loading for images that are offscreen. If set to true, the property ensures that offscreen images are loaded early enough so that they have finished loading once the user scrolls near them.

Note: Keep in mind that the property uses the loading attribute of HTML <img> element which is not supported for Internet Explorer.

Default value is false.

sap.m.Image.getMetadata

Returns a metadata object for class sap.m.Image.

getMode

Gets current value of property mode.

Defines how the src and the activeSrc is output to the DOM Element.

When set to sap.m.ImageMode.Image, which is the default value, the src (activeSrc) is set to the src attribute of the <img> tag. When set to sap.m.ImageMode.Background, the src (activeSrc) is set to the CSS style background-image and the root DOM element is rendered as a <span> tag instead of an <img> tag.

Default value is "Image".

getSrc

Gets current value of property src.

Relative or absolute path to URL where the image file is stored.

The path will be adapted to the density-aware format according to the density of the device following the naming convention [imageName]@[densityValue].[extension].

getUseMap

Gets current value of property useMap.

The name of the image map that defines the clickable areas.

getWidth

Gets current value of property width.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

removeAllAriaDescribedBy

Removes all the controls in the association named ariaDescribedBy.

removeAllAriaDetails

Removes all the controls in the association named ariaDetails.

removeAllAriaLabelledBy

Removes all the controls in the association named ariaLabelledBy.

removeAriaDescribedBy

Removes an ariaDescribedBy from the association named ariaDescribedBy.

Param Type DefaultValue Description
vAriaDescribedBy int sap.ui.core.ID sap.ui.core.Control

The ariaDescribedBy to be removed or its index or ID

removeAriaDetails

Removes an ariaDetails from the association named ariaDetails.

Param Type DefaultValue Description
vAriaDetails int sap.ui.core.ID sap.ui.core.Control

The ariaDetails to be removed or its index or ID

removeAriaLabelledBy

Removes an ariaLabelledBy from the association named ariaLabelledBy.

Param Type DefaultValue Description
vAriaLabelledBy int sap.ui.core.ID sap.ui.core.Control

The ariaLabelledBy to be removed or its index or ID

setActiveSrc

Sets a new value for property activeSrc.

The source property which is used when the image is pressed.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is empty string.

Param Type DefaultValue Description
sActiveSrc sap.ui.core.URI ""

New value for property activeSrc

setAlt

Sets a new value for property alt.

The alternative text that is displayed in case the image is not available, or cannot be displayed.

If the image is set to decorative, this property is ignored.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sAlt string

New value for property alt

setAriaHasPopup

Sets a new value for property ariaHasPopup.

Defines the aria-haspopup attribute of the Image.

Guidance for choosing appropriate value:

When called with a value of null or undefined, the default value of the property will be restored.

Default value is None.

Param Type DefaultValue Description
sAriaHasPopup sap.ui.core.aria.HasPopup None

New value for property ariaHasPopup

setBackgroundPosition

Sets a new value for property backgroundPosition.

Defines the position of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-position. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "initial".

Param Type DefaultValue Description
sBackgroundPosition string "initial"

New value for property backgroundPosition

setBackgroundRepeat

Sets a new value for property backgroundRepeat.

Defines whether the source image is repeated when the output DOM element is bigger than the source.

This property is set on the output DOM element using the CSS style background-repeat. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "no-repeat".

Param Type DefaultValue Description
sBackgroundRepeat string "no-repeat"

New value for property backgroundRepeat

setBackgroundSize

Sets a new value for property backgroundSize.

Defines the size of the image in sap.m.ImageMode.Background mode.

This property is set on the output DOM element using the CSS style background-size. It takes effect only when the mode property is set to sap.m.ImageMode.Background.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "cover".

Param Type DefaultValue Description
sBackgroundSize string "cover"

New value for property backgroundSize

setDecorative

Sets a new value for property decorative.

A decorative image is included for design reasons; accessibility tools will ignore decorative images.

Note: If the image has an image map (useMap is set), this property will be overridden (the image will not be rendered as decorative). A decorative image has no ALT attribute, so the alt property is ignored if the image is decorative.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is true.

Param Type DefaultValue Description
bDecorative boolean true

New value for property decorative

setDensityAware

Sets a new value for property densityAware.

If this is set to true, one or more network requests will be made that try to obtain the density perfect version of the image.

By default, this is set to false, so the src image is loaded directly without attempting to fetch the density perfect image for high-density devices.

Note: Before 1.60, the default value was set to true, which brought redundant network requests for apps that used the default but did not provide density perfect image versions on server-side. You should set this property to true only if you also provide the corresponding image versions for high-density devices.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bDensityAware boolean false

New value for property densityAware

setDetailBox

Sets the detailBox aggregation.

Param Type DefaultValue Description
oLightBox sap.m.LightBox undefined

Instance of the LightBox control or undefined

setHeight

Sets a new value for property height.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sHeight sap.ui.core.CSSSize

New value for property height

setLazyLoading

Sets a new value for property lazyLoading.

Enables lazy loading for images that are offscreen. If set to true, the property ensures that offscreen images are loaded early enough so that they have finished loading once the user scrolls near them.

Note: Keep in mind that the property uses the loading attribute of HTML <img> element which is not supported for Internet Explorer.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is false.

Param Type DefaultValue Description
bLazyLoading boolean false

New value for property lazyLoading

setMode

Sets a new value for property mode.

Defines how the src and the activeSrc is output to the DOM Element.

When set to sap.m.ImageMode.Image, which is the default value, the src (activeSrc) is set to the src attribute of the <img> tag. When set to sap.m.ImageMode.Background, the src (activeSrc) is set to the CSS style background-image and the root DOM element is rendered as a <span> tag instead of an <img> tag.

When called with a value of null or undefined, the default value of the property will be restored.

Default value is "Image".

Param Type DefaultValue Description
sMode sap.m.ImageMode "Image"

New value for property mode

setSrc

Sets a new value for property src.

Relative or absolute path to URL where the image file is stored.

The path will be adapted to the density-aware format according to the density of the device following the naming convention [imageName]@[densityValue].[extension].

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sSrc sap.ui.core.URI

New value for property src

setUseMap

Sets a new value for property useMap.

The name of the image map that defines the clickable areas.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sUseMap string

New value for property useMap

setWidth

Sets a new value for property width.

When the empty value is kept, the original size is not changed.

It is also possible to make settings for width or height only, in which case the original ratio between width/height is maintained. When the mode property is set to sap.m.ImageMode.Background, this property always needs to be set. Otherwise the output DOM element has a 0 size.

When called with a value of null or undefined, the default value of the property will be restored.

Param Type DefaultValue Description
sWidth sap.ui.core.CSSSize

New value for property width

unbindDetailBox

Unbinds aggregation detailBox from model data.