Image

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

validateFieldGroup

Events borrowed from class sap.ui.base.ManagedObject

formatError, modelContextChange, parseError, validationError, validationSuccess

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.

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(mArguments?)Fires event error to attached listeners.

fireLoad(mArguments?)Fires event load to attached listeners.

firePress(mArguments?)Fires event press to attached listeners.

fireTap(mArguments?)Fires event tap to attached listeners.

getAccessibilityInfo()

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.

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.

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.

Methods borrowed from class sap.ui.core.Control

Methods borrowed from class sap.ui.core.Element

Methods borrowed from class sap.ui.base.ManagedObject

addAggregation, addAssociation, applySettings, attachFormatError, attachModelContextChange, attachParseError, attachValidationError, attachValidationSuccess, bindAggregation, bindContext, bindObject, bindProperty, destroyAggregation, detachFormatError, detachModelContextChange, detachParseError, detachValidationError, detachValidationSuccess, findAggregatedObjects, fireFormatError, fireModelContextChange, fireParseError, fireValidationError, fireValidationSuccess, getAggregation, getAssociation, getBinding, getBindingContext, getBindingInfo, getBindingPath, getEventingParent, getId, getModel, getObjectBinding, getOriginInfo, getParent, getProperty, hasModel, indexOfAggregation, insertAggregation, isBound, isInvalidateSuppressed, isTreeBinding, propagateMessages, removeAggregation, removeAllAggregation, removeAllAssociation, removeAssociation, setAggregation, setAssociation, setBindingContext, setModel, setProperty, unbindAggregation, unbindContext, unbindObject, unbindProperty, validateAggregation, validateProperty

Methods borrowed from class sap.ui.base.EventProvider

attachEvent, attachEventOnce, detachEvent, hasListeners

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
- src : sap.ui.core.URI
- width : sap.ui.core.CSSSize
- height : sap.ui.core.CSSSize
- decorative : boolean (default: true)
- alt : string
- useMap : string
- densityAware : boolean (default: true)
- activeSrc : sap.ui.core.URI (default: )
- mode : sap.m.ImageMode (default: Image)
- backgroundSize : string (default: cover)
- backgroundPosition : string (default: initial)
- backgroundRepeat : string (default: no-repeat)
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:

{string}	sId?	id for the new control, generated automatically if no id is given
{object}	mSettings?	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.Event}	oControlEvent
{sap.ui.base.EventProvider}	oControlEvent.getSource
{object}	oControlEvent.getParameters

Since:: 1.36.2

load(oControlEvent)

Event is fired when the image resource is loaded.

Parameters:

{sap.ui.base.Event}	oControlEvent
{sap.ui.base.EventProvider}	oControlEvent.getSource
{object}	oControlEvent.getParameters

Since:: 1.36.2

press(oControlEvent)

Event is fired when the user clicks on the control.

Parameters:

{sap.ui.base.Event}	oControlEvent
{sap.ui.base.EventProvider}	oControlEvent.getSource
{object}	oControlEvent.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.Event}	oControlEvent
{sap.ui.base.EventProvider}	oControlEvent.getSource
{object}	oControlEvent.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:

{string}	sClassName	Name of the class being created
{object}	oClassInfo?	Object literal with information about the class
{function}	FNMetaImpl?	Constructor function for the metadata object; if not given, it defaults to `sap.ui.core.ElementMetadata`

Returns:

{function}

Created class / constructor function

sap.m.Image.getMetadata(): sap.ui.base.Metadata

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

Returns:

{sap.ui.base.Metadata}

Metadata 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:

{object}	oData?	An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}	fnFunction	The function to be called when the event occurs
{object}	oListener?	Context object to call the event handler with. Defaults to this `sap.m.Image` itself

Since:: 1.36.2

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

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:

{object}	oData?	An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}	fnFunction	The function to be called when the event occurs
{object}	oListener?	Context object to call the event handler with. Defaults to this `sap.m.Image` itself

Since:: 1.36.2

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

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:

{object}	oData?	An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}	fnFunction	The function to be called when the event occurs
{object}	oListener?	Context object to call the event handler with. Defaults to this `sap.m.Image` itself

Returns:

{sap.m.Image} Reference 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:

{object}	oData?	An application-specific payload object that will be passed to the event handler along with the event object when firing the event
{function}	fnFunction	The function to be called when the event occurs
{object}	oListener?	Context object to call the event handler with. Defaults to this `sap.m.Image` itself

Returns:

{sap.m.Image} Reference 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:

{function}	fnFunction	The function to be called, when the event occurs
{object}	oListener	Context object on which the given function had to be called

Since:: 1.36.2

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

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:

{function}	fnFunction	The function to be called, when the event occurs
{object}	oListener	Context object on which the given function had to be called

Since:: 1.36.2

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

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:

{function}	fnFunction	The function to be called, when the event occurs
{object}	oListener	Context object on which the given function had to be called

Returns:

{sap.m.Image} Reference 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:

{function}	fnFunction	The function to be called, when the event occurs
{object}	oListener	Context object on which the given function had to be called

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

fireError(mArguments?): sap.m.Image

Fires event error to attached listeners.

Parameters:

{Map}

mArguments?

The arguments to pass along with the event

Since:: 1.36.2

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

fireLoad(mArguments?): sap.m.Image

Fires event load to attached listeners.

Parameters:

{Map}

mArguments?

The arguments to pass along with the event

Since:: 1.36.2

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

firePress(mArguments?): sap.m.Image

Fires event press to attached listeners.

Parameters:

{Map}

mArguments?

The arguments to pass along with the event

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

fireTap(mArguments?): sap.m.Image

Fires event tap to attached listeners.

Parameters:

{Map}

mArguments?

The arguments to pass along with the event

Returns:

{sap.m.Image} Reference 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.URI} Value 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:

{string} Value 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.

Since:: 1.30.0

Returns:

{string} Value of property backgroundPosition

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.

Since:: 1.30.0

Returns:

{string} Value of property backgroundRepeat

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.

Since:: 1.30.0

Returns:

{string} Value of property backgroundSize

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:

{boolean} Value 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:

{boolean} Value of property densityAware

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.CSSSize} Value 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.

Since:: 1.30.0

Returns:

{sap.m.ImageMode} Value of property mode

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.URI} Value of property src

getUseMap(): string

Gets current value of property useMap.

The name of the image map that defines the clickable areas

Returns:

{string} Value of property useMap

getWidth(): sap.ui.core.CSSSize

Gets current value of property width.

Returns:

{sap.ui.core.CSSSize} Value of property width

setActiveSrc(sActiveSrc)

This overrides the default setter of the activeSrc property in order to avoid the rerendering.

Parameters:

{sap.ui.core.URI}

sActiveSrc

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:

{string} sAlt New value for property alt

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setBackgroundPosition(sBackgroundPosition): sap.m.Image

Sets a new value for property backgroundPosition.

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

Default value is initial.

Parameters:

{string} sBackgroundPosition New value for property backgroundPosition

Since:: 1.30.0

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setBackgroundRepeat(sBackgroundRepeat): sap.m.Image

Sets a new value for property backgroundRepeat.

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

Default value is no-repeat.

Parameters:

{string} sBackgroundRepeat New value for property backgroundRepeat

Since:: 1.30.0

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setBackgroundSize(sBackgroundSize): sap.m.Image

Sets a new value for property backgroundSize.

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

Default value is cover.

Parameters:

{string} sBackgroundSize New value for property backgroundSize

Since:: 1.30.0

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

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.

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

Default value is true.

Parameters:

{boolean} bDecorative New value for property decorative

Returns:

{sap.m.Image} Reference 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:

{boolean} bDensityAware New value for property densityAware

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setHeight(sHeight): sap.m.Image

Sets a new value for property height.

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

Parameters:

{sap.ui.core.CSSSize} sHeight New value for property height

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setMode(sMode): sap.m.Image

Sets a new value for property mode.

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.ImageMode} sMode New value for property mode

Since:: 1.30.0

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setSrc(sSrc)

This overrides the default setter of the src property and update the dom node.

Parameters:

{sap.ui.core.URI}

sSrc

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:

{string} sUseMap New value for property useMap

Returns:

{sap.m.Image} Reference to this in order to allow method chaining

setWidth(sWidth): sap.m.Image

Sets a new value for property width.

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

Parameters:

{sap.ui.core.CSSSize} sWidth New value for property width

Returns:

{sap.m.Image} Reference to this in order to allow method chaining