Class sap.m.ImageModule: sap/m/Image

extends Control
implements IFormContent

A wrapper around the IMG tag. The image can be loaded from a remote or local server.

Density related image will be loaded if image with density awareness name in format [imageName]@[densityValue].[extension] is provided. The valid desity values are 1, 1.5, 2. If the original devicePixelRatio isn't one of the three valid numbers, it's rounded up to the nearest one.

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

From version 1.30, 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', 'backgroundRepeat' have effect only when image is in sap.m.ImageMode.Background mode. In order to make the high density image correctly displayed, the 'backgroundSize' should be set to the dimension of the normal density version.

Constructor Summary
new sap.m.Image(sId?, mSettings?)Constructor for a new Image.
Event Summary
error(oControlEvent)Event is fired when the image resource can't be loaded.
load(oControlEvent)Event is fired when the image resource is loaded.
press(oControlEvent)Event is fired when the user clicks on the control.
tap(oControlEvent)Event is fired when the user clicks on the control.
Events borrowed from class sap.ui.core.Control
Method Summary
sap.m.Image.extend(sClassName, oClassInfo?, FNMetaImpl?)Creates a new subclass of class sap.m.Image with name sClassName and enriches it with the information contained in oClassInfo.
sap.m.Image.getMetadata()Returns a metadata object for class sap.m.Image.
attachError(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the error event of this sap.m.Image.
attachLoad(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the load event of this sap.m.Image.
attachPress(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the press event of this sap.m.Image.
attachTap(oData?, fnFunction, oListener?)Attaches event handler fnFunction to the tap event of this sap.m.Image.
bindDetailBox(oBindingInfo)Binds aggregation detailBox to model data.
destroyDetailBox()Destroys the detailBox in the aggregation detailBox.
detachError(fnFunction, oListener)Detaches event handler fnFunction from the error event of this sap.m.Image.
detachLoad(fnFunction, oListener)Detaches event handler fnFunction from the load event of this sap.m.Image.
detachPress(fnFunction, oListener)Detaches event handler fnFunction from the press event of this sap.m.Image.
detachTap(fnFunction, oListener)Detaches event handler fnFunction from the tap event of this sap.m.Image.
fireError(mParameters?)Fires event error to attached listeners.
fireLoad(mParameters?)Fires event load to attached listeners.
firePress(mParameters?)Fires event press to attached listeners.
fireTap(mParameters?)Fires event tap to attached listeners.
getActiveSrc()Gets current value of property activeSrc.
getAlt()Gets current value of property alt.
getBackgroundPosition()Gets current value of property backgroundPosition.
getBackgroundRepeat()Gets current value of property backgroundRepeat.
getBackgroundSize()Gets current value of property backgroundSize.
getDecorative()Gets current value of property decorative.
getDensityAware()Gets current value of property densityAware.
getDetailBox()Gets content of aggregation detailBox.
getHeight()Gets current value of property height.
getMode()Gets current value of property mode.
getSrc()Gets current value of property src.
getUseMap()Gets current value of property useMap.
getWidth()Gets current value of property width.
setActiveSrc(sActiveSrc)This overrides the default setter of the activeSrc property in order to avoid the rerendering.
setAlt(sAlt)Sets a new value for property alt.
setBackgroundPosition(sBackgroundPosition)Sets a new value for property backgroundPosition.
setBackgroundRepeat(sBackgroundRepeat)Sets a new value for property backgroundRepeat.
setBackgroundSize(sBackgroundSize)Sets a new value for property backgroundSize.
setDecorative(bDecorative)Sets a new value for property decorative.
setDensityAware(bDensityAware)Sets a new value for property densityAware.
setDetailBox(oLightBox)Sets the detailBox aggregation.
setHeight(sHeight)Sets a new value for property height.
setMode(sMode)Sets a new value for property mode.
setSrc(sSrc)This overrides the default setter of the src property and update the dom node.
setUseMap(sUseMap)Sets a new value for property useMap.
setWidth(sWidth)Sets a new value for property width.
unbindDetailBox()Unbinds aggregation detailBox from model data.
Constructor Detail
new sap.m.Image(sId?, mSettings?)

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 for a general description of the syntax of the settings object.

The supported settings are:

  • Properties

  • Aggregations

  • Events

    • tap : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • press : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • load : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]
    • error : fnListenerFunction or [fnListenerFunction, oListenerObject] or [oData, fnListenerFunction, oListenerObject]

In addition, all settings applicable to the base type sap.ui.core.Control can be used as well.

Parameters:
stringsId?id for the new control, generated automatically if no id is given
objectmSettings?initial settings for the new control
Event Detail
error(oControlEvent)
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.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Since:
1.36.2
load(oControlEvent)
Event is fired when the image resource is loaded.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Since:
1.36.2
press(oControlEvent)
Event is fired when the user clicks on the control.
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
tap(oControlEvent)
Event is fired when the user clicks on the control. (This event is deprecated, use the press event instead)
Parameters:
sap.ui.base.EventoControlEvent
sap.ui.base.EventProvideroControlEvent.getSource
objectoControlEvent.getParameters
Method Detail
sap.m.Image.extend(sClassName, oClassInfo?, FNMetaImpl?): function

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.

Parameters:
stringsClassNameName of the class being created
objectoClassInfo?Object literal with information about the class
functionFNMetaImpl?Constructor function for the metadata object; if not given, it defaults to sap.ui.core.ElementMetadata
Returns:
functionCreated class / constructor function
sap.m.Image.getMetadata(): sap.ui.base.Metadata
Returns a metadata object for class sap.m.Image.
Returns:
sap.ui.base.MetadataMetadata object describing this class
attachError(oData?, fnFunction, oListener?): sap.m.Image

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.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Image itself
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.36.2
attachLoad(oData?, fnFunction, oListener?): sap.m.Image

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.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Image itself
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.36.2
attachPress(oData?, fnFunction, oListener?): sap.m.Image

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.

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Image itself
Returns:
sap.m.ImageReference to this in order to allow method chaining
attachTap(oData?, fnFunction, oListener?): sap.m.Image

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)

Parameters:
objectoData?An application-specific payload object that will be passed to the event handler along with the event object when firing the event
functionfnFunctionThe function to be called when the event occurs
objectoListener?Context object to call the event handler with. Defaults to this sap.m.Image itself
Returns:
sap.m.ImageReference to this in order to allow method chaining
bindDetailBox(oBindingInfo): sap.m.Image

Binds aggregation detailBox to model data.

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

Parameters:
objectoBindingInfoThe binding information
Returns:
sap.m.ImageReference to this in order to allow method chaining
destroyDetailBox(): sap.m.Image
Destroys the detailBox in the aggregation detailBox.
Returns:
sap.m.ImageReference to this in order to allow method chaining
detachError(fnFunction, oListener): sap.m.Image

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.36.2
detachLoad(fnFunction, oListener): sap.m.Image

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.36.2
detachPress(fnFunction, oListener): sap.m.Image

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.ImageReference to this in order to allow method chaining
detachTap(fnFunction, oListener): sap.m.Image

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.

Parameters:
functionfnFunctionThe function to be called, when the event occurs
objectoListenerContext object on which the given function had to be called
Returns:
sap.m.ImageReference to this in order to allow method chaining
fireError(mParameters?): sap.m.Image
Fires event error to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.36.2
fireLoad(mParameters?): sap.m.Image
Fires event load to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.36.2
firePress(mParameters?): sap.m.Image
Fires event press to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ImageReference to this in order to allow method chaining
fireTap(mParameters?): sap.m.Image
Fires event tap to attached listeners.
Parameters:
objectmParameters?Parameters to pass along with the event
Returns:
sap.m.ImageReference to this in order to allow method chaining
getAccessibilityInfo()
See:
sap.ui.core.Control#getAccessibilityInfo
getActiveSrc(): sap.ui.core.URI

Gets current value of property activeSrc.

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

Default value is .

Returns:
sap.ui.core.URIValue of property activeSrc
getAlt(): string

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.

Returns:
stringValue of property alt
getBackgroundPosition(): string

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 CSS style 'background-position'. This property takes effect only when the 'mode' property is set to sap.m.ImageMode.Background.

Default value is initial.

Returns:
stringValue of property backgroundPosition
Since:
1.30.0
getBackgroundRepeat(): string

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 CSS style 'background-repeat'. This property takes effect only when the 'mode' property is set to sap.m.ImageMode.Background.

Default value is no-repeat.

Returns:
stringValue of property backgroundRepeat
Since:
1.30.0
getBackgroundSize(): string

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 CSS style 'background-size'. This property takes effect only when the 'mode' property is set to sap.m.ImageMode.Background.

Default value is cover.

Returns:
stringValue of property backgroundSize
Since:
1.30.0
getDecorative(): boolean

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.

Returns:
booleanValue of property decorative
getDensityAware(): boolean

Gets current value of property densityAware.

If this is set to false, the src image will be loaded directly without attempting to fetch the density perfect image for high density device.

By default, this is set to true but then one or more requests are sent trying to get the density perfect version of image if this version of image doesn't exist on the server.

If bandwidth is the key for the application, set this value to false.

Default value is true.

Returns:
booleanValue of property densityAware
getDetailBox(): sap.m.LightBox

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.

Returns:
sap.m.LightBox
getHeight(): sap.ui.core.CSSSize

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, the original ratio between width/height is maintained. When '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.

Returns:
sap.ui.core.CSSSizeValue of property height
getMode(): sap.m.ImageMode

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.

Returns:
sap.m.ImageModeValue of property mode
Since:
1.30.0
getSrc(): sap.ui.core.URI

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 convention that [imageName]@[densityValue].[extension]

Returns:
sap.ui.core.URIValue of property src
getUseMap(): string

Gets current value of property useMap.

The name of the image map that defines the clickable areas

Returns:
stringValue of property useMap
getWidth(): sap.ui.core.CSSSize

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, the original ratio between width/height is maintained. When '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.

Returns:
sap.ui.core.CSSSizeValue of property width
setActiveSrc(sActiveSrc): sap.m.Image
This overrides the default setter of the activeSrc property in order to avoid the rerendering.
Parameters:
sap.ui.core.URIsActiveSrc
Returns:
sap.m.Imagethis pointer for chaining
setAlt(sAlt): sap.m.Image

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.

Parameters:
stringsAltNew value for property alt
Returns:
sap.m.ImageReference to this in order to allow method chaining
setBackgroundPosition(sBackgroundPosition): sap.m.Image

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 CSS style 'background-position'. This property 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.

Parameters:
stringsBackgroundPositionNew value for property backgroundPosition
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.30.0
setBackgroundRepeat(sBackgroundRepeat): sap.m.Image

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 CSS style 'background-repeat'. This property 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.

Parameters:
stringsBackgroundRepeatNew value for property backgroundRepeat
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.30.0
setBackgroundSize(sBackgroundSize): sap.m.Image

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 CSS style 'background-size'. This property 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.

Parameters:
stringsBackgroundSizeNew value for property backgroundSize
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.30.0
setDecorative(bDecorative): sap.m.Image

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.

Parameters:
booleanbDecorativeNew value for property decorative
Returns:
sap.m.ImageReference to this in order to allow method chaining
setDensityAware(bDensityAware): sap.m.Image

Sets a new value for property densityAware.

If this is set to false, the src image will be loaded directly without attempting to fetch the density perfect image for high density device.

By default, this is set to true but then one or more requests are sent trying to get the density perfect version of image if this version of image doesn't exist on the server.

If bandwidth is the key for the application, set this value to false.

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

Default value is true.

Parameters:
booleanbDensityAwareNew value for property densityAware
Returns:
sap.m.ImageReference to this in order to allow method chaining
setDetailBox(oLightBox): object
Sets the detailBox aggregation.
Parameters:
sap.m.LightBox|undefinedoLightBoxInstance of the LightBox control or undefined
Returns:
objectthis for chaining
setHeight(sHeight): sap.m.Image

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, the original ratio between width/height is maintained. When '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.

Parameters:
sap.ui.core.CSSSizesHeightNew value for property height
Returns:
sap.m.ImageReference to this in order to allow method chaining
setMode(sMode): sap.m.Image

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.

Parameters:
sap.m.ImageModesModeNew value for property mode
Returns:
sap.m.ImageReference to this in order to allow method chaining
Since:
1.30.0
setSrc(sSrc)
This overrides the default setter of the src property and update the dom node.
Parameters:
sap.ui.core.URIsSrc
setUseMap(sUseMap): sap.m.Image

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.

Parameters:
stringsUseMapNew value for property useMap
Returns:
sap.m.ImageReference to this in order to allow method chaining
setWidth(sWidth): sap.m.Image

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, the original ratio between width/height is maintained. When '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.

Parameters:
sap.ui.core.CSSSizesWidthNew value for property width
Returns:
sap.m.ImageReference to this in order to allow method chaining
unbindDetailBox(): sap.m.Image
Unbinds aggregation detailBox from model data.
Returns:
sap.m.ImageReference to this in order to allow method chaining