namespace sap.ui.Device.media

Control sample: sap.ui.Device.media
Visiblity: public
Available since: N/A
Module: sap/ui/Device
Application Component:

Event API for screen width changes.

This API is based on media queries but can also be used if media queries are not natively supported by the used browser. In this case, the behavior of media queries is simulated by this API.

There are several predefined range sets available. Each of them defines a set of intervals for the screen width (from small to large). Whenever the screen width changes and the current screen width is in a different interval to the one before the change, the registered event handlers for the range set are called.

If needed, it is also possible to define a custom set of intervals.

The following example shows a typical use case:

function sizeChanged(mParams) {
    switch(mParams.name) {
        case "Phone":
            // Do what is needed for a little screen
            break;
        case "Tablet":
            // Do what is needed for a medium sized screen
            break;
        case "Desktop":
            // Do what is needed for a large screen
    }
}

// Register an event handler to changes of the screen size
sap.ui.Device.media.attachHandler(sizeChanged, null, sap.ui.Device.media.RANGESETS.SAP_STANDARD);
// Do some initialization work based on the current size
sizeChanged(sap.ui.Device.media.getCurrentRange(sap.ui.Device.media.RANGESETS.SAP_STANDARD));


Nodes Overview

Node Description
sap.ui.Device.media.RANGESETS

Enumeration containing the names and settings of predefined screen width media query range sets.


Methods Overview

Method Description
sap.ui.Device.media.attachHandler

Registers the given event handler to change events of the screen width based on the range set with the specified name.

The event is fired whenever the screen width changes and the current screen width is in a different interval of the given range set than before the width change.

The event handler is called with a single argument: a map mParams which provides the following information about the entered interval:

  • mParams.from: The start value (inclusive) of the entered interval as a number
  • mParams.to: The end value (exclusive) range of the entered interval as a number or undefined for the last interval (infinity)
  • mParams.unit: The unit used for the values above, e.g. "px"
  • mParams.name: The name of the entered interval, if available

sap.ui.Device.media.detachHandler

Removes a previously attached event handler from the change events of the screen width.

The passed parameters must match those used for registration with #.attachHandler beforehand.

sap.ui.Device.media.getCurrentRange

Returns information about the current active range of the range set with the given name.

If the optional parameter iWidth is given, the active range will be determined for that width, otherwise it is determined for the current window size.

sap.ui.Device.media.hasRangeSet

Returns true if a range set with the given name is already initialized.

sap.ui.Device.media.initRangeSet

Initializes a screen width media query range set.

This initialization step makes the range set ready to be used for one of the other functions in namespace sap.ui.Device.media. The most important predefined range sets are initialized automatically.

To make a not yet initialized predefined range set ready to be used, call this function with the name of the range set to be initialized:

sap.ui.Device.media.initRangeSet(sap.ui.Device.media.RANGESETS.SAP_3STEPS);

Alternatively it is possible to define custom range sets as shown in the following example:

sap.ui.Device.media.initRangeSet("MyRangeSet", [200, 400], "px", ["Small", "Medium", "Large"]);
This example defines the following named ranges:
  • "Small": For screens smaller than 200 pixels.
  • "Medium": For screens greater than or equal to 200 pixels and smaller than 400 pixels.
  • "Large": For screens greater than or equal to 400 pixels.
The range names are optional. If they are specified a CSS class (e.g. sapUiMedia-MyRangeSet-Small) is also added to the document root depending on the current active range. This can be suppressed via parameter bSuppressClasses.

sap.ui.Device.media.removeRangeSet

Removes a previously initialized range set and detaches all registered handlers.

Only custom range sets can be removed via this function. Initialized predefined range sets (sap.ui.Device.media.RANGESETS) cannot be removed.

sap.ui.Device.media.attachHandler

Registers the given event handler to change events of the screen width based on the range set with the specified name.

The event is fired whenever the screen width changes and the current screen width is in a different interval of the given range set than before the width change.

The event handler is called with a single argument: a map mParams which provides the following information about the entered interval:

Param Type DefaultValue Description
fnFunction function

The handler function to call when the event occurs. This function will be called in the context of the oListener instance (if present) or on the window instance. A map with information about the entered range set is provided as a single argument to the handler (see details above).

oListener object

The object that wants to be notified when the event occurs (this context within the handler function). If it is not specified, the handler function is called in the context of the window.

sName string

The name of the range set to listen to. The range set must be initialized beforehand (sap.ui.Device.media.initRangeSet). If no name is provided, the default range set is used.

sap.ui.Device.media.detachHandler

Removes a previously attached event handler from the change events of the screen width.

The passed parameters must match those used for registration with #.attachHandler beforehand.

Param Type DefaultValue Description
fnFunction function

The handler function to detach from the event

oListener object

The object that wanted to be notified when the event occurred

sName string

The name of the range set to listen to. If no name is provided, the default range set is used.

sap.ui.Device.media.getCurrentRange

Returns information about the current active range of the range set with the given name.

If the optional parameter iWidth is given, the active range will be determined for that width, otherwise it is determined for the current window size.

Param Type DefaultValue Description
sName string

The name of the range set. The range set must be initialized beforehand (sap.ui.Device.media.initRangeSet)

iWidth int

An optional width, based on which the range should be determined; If iWidth is not a number, the window size will be used.

sap.ui.Device.media.hasRangeSet

Returns true if a range set with the given name is already initialized.

Param Type DefaultValue Description
sName string

The name of the range set.

sap.ui.Device.media.initRangeSet

Initializes a screen width media query range set.

This initialization step makes the range set ready to be used for one of the other functions in namespace sap.ui.Device.media. The most important predefined range sets are initialized automatically.

To make a not yet initialized predefined range set ready to be used, call this function with the name of the range set to be initialized:

sap.ui.Device.media.initRangeSet(sap.ui.Device.media.RANGESETS.SAP_3STEPS);

Alternatively it is possible to define custom range sets as shown in the following example:

sap.ui.Device.media.initRangeSet("MyRangeSet", [200, 400], "px", ["Small", "Medium", "Large"]);
This example defines the following named ranges: The range names are optional. If they are specified a CSS class (e.g. sapUiMedia-MyRangeSet-Small) is also added to the document root depending on the current active range. This can be suppressed via parameter bSuppressClasses.

Param Type DefaultValue Description
sName string

The name of the range set to be initialized - either a predefined or custom one. The name must be a valid id and consist only of letters and numeric digits.

aRangeBorders int[]

The range borders

sUnit string

The unit which should be used for the values given in aRangeBorders. The allowed values are "px" (default), "em" or "rem"

aRangeNames string[]

The names of the ranges. The names must be a valid id and consist only of letters and digits. If names are specified, CSS classes are also added to the document root as described above. This behavior can be switched off explicitly by using bSuppressClasses. Note: aRangeBorders with n entries define n+1 ranges. Therefore n+1 names must be provided.

bSuppressClasses boolean

Whether or not writing of CSS classes to the document root should be suppressed when aRangeNames are provided

sap.ui.Device.media.removeRangeSet

Removes a previously initialized range set and detaches all registered handlers.

Only custom range sets can be removed via this function. Initialized predefined range sets (sap.ui.Device.media.RANGESETS) cannot be removed.

Param Type DefaultValue Description
sName string

The name of the range set which should be removed.