Namespace sap.ui.Device.mediaModule: sap/ui/Device

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));

Namespaces & Classes
RANGESETSEnumeration containing the names and settings of predefined screen width media query range sets.
Method Summary
attachHandler(fnFunction, oListener?, sName)Registers the given event handler to change events of the screen width based on the range set with the specified name.
detachHandler(fnFunction, oListener?, sName)Removes a previously attached event handler from the change events of the screen width.
getCurrentRange(sName)Returns information about the current active range of the range set with the given name.
hasRangeSet(sName)Returns true if a range set with the given name is already initialized.
initRangeSet(sName, aRangeBorders?, sUnit?, aRangeNames?, bSuppressClasses?)Initializes a screen width media query range set.
removeRangeSet(sName)Removes a previously initialized range set and detaches all registered handlers.
Method Detail
attachHandler(fnFunction, oListener?, sName)
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
Parameters:
{function}fnFunction 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).
{object}oListener? 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.
{String}sName The name of the range set to listen to. The range set must be initialized beforehand (sap.ui.Device.media.html#initRangeSet). If no name is provided, the default range set is used.
detachHandler(fnFunction, oListener?, sName)
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.

Parameters:
{function}fnFunction The handler function to detach from the event
{object}oListener? The object that wanted to be notified when the event occurred
{String}sName The name of the range set to listen to. If no name is provided, the default range set is used.
getCurrentRange(sName): map
Returns information about the current active range of the range set with the given name.
Parameters:
{String}sName The name of the range set. The range set must be initialized beforehand (sap.ui.Device.media.html#initRangeSet)
Returns:
{map} Information about the current active interval of the range set. The returned map has the same structure as the argument of the event handlers ({link sap.ui.Device.media#attachHandler})
hasRangeSet(sName): boolean
Returns true if a range set with the given name is already initialized.
Parameters:
{String}sName The name of the range set.
Returns:
{boolean} Returns true if a range set with the given name is already initialized
initRangeSet(sName, aRangeBorders?, sUnit?, aRangeNames?, bSuppressClasses?)
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.
Parameters:
{String}sName 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.
{int[]}aRangeBorders? The range borders
{String}sUnit? The unit which should be used for the values given in aRangeBorders. The allowed values are "px" (default), "em" or "rem"
{String[]}aRangeNames? 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.
{boolean}bSuppressClasses? Whether or not writing of CSS classes to the document root should be suppressed when aRangeNames are provided
removeRangeSet(sName)
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.

Parameters:
{String}sName The name of the range set which should be removed.