Enact

ui/resolution

Exports a number of useful methods for resolution independence as well as the ui/resolution.ResolutionDecorator Higher-order Component (HOC). The default export is an object containing the resolution independence methods.

import resolution from '@enact/ui/resolution';

Members

ResolutionDecoratorHigher-Order Component

Higher-order Component that configures resolution support for its wrapped component tree.

Configuration options:

  • dynamic: true - when true, updates the resolution classes when the window resizes

  • screenTypes: null - defines a set of screen types to support

Example:

// Will have the resolution classes and will be updated when the window resizes
const AppWithResolution = ResolutionDecorator(App);
// Will have the resolution classes for the screen at the time of render only
const AppWithStaticResolution = ResolutionDecorator({dynamic: false}, App);
const AppWithScreenTypes = ResolutionDecorator({screenTypes: [
	{name: 'hd', pxPerRem: 16, width: 1280, height: 720, aspectRatioName: 'hdtv', base: true}
]}, App);
import {ResolutionDecorator} from '@enact/ui/resolution';
Configuration
dynamic
Boolean

When true, an event listener will be attached to the window to listen for resize events.

Default: true
screenTypes
ArrayObject

An array of objects containing declarations for screen types to add to the list of known screen types.

Default: null

calculateFontSizeFunction

calculateFontSize(type)String

Calculate the base rem font size. This is how the magic happens. This accepts an optional screenType name. If one isn't provided, the currently detected screen type is used. This uses the config option "orientationHandling", which when set to "scale" and the screen is in portrait orientation, will dynamically calculate what the base font size should be, if the width were proportionally scaled down to fit in the portrait space.

To use, put the following in your application code:

	var RI = require('moonstone/resolution');

	RI.config.orientationHandling = 'scale';
	RI.init();

This has no effect if the screen is in landscape, or if orientationHandling is unset.

1 Param
type String

Screen type to base size the calculation on. If no screen type is provided, the current screen type will be used.

Returns
String

The calculated pixel size (with unit suffix. Ex: "24px").

configClass

The current configuration

import {config} from '@enact/ui/resolution';

defineScreenTypesFunction

defineScreenTypes(types)

Sets up screen resolution scaling capabilities by defining an array of all the screens being used. These should be listed in order from smallest to largest, according to width.

The name, pxPerRem, width, and aspectRatioName properties are required for each screen type in the array. Setting base: true on a screen type marks it as the default resolution, upon which everything else will be based.

Executing this method also initializes the rest of the resolution-independence code.

var resolution = require('enyo/resolution');

resolution.defineScreenTypes([
	{name: 'vga',     pxPerRem: 8,  width: 640,  height: 480,  aspectRatioName: 'standard'},
	{name: 'xga',     pxPerRem: 16, width: 1024, height: 768,  aspectRatioName: 'standard'},
	{name: 'hd',      pxPerRem: 16, width: 1280, height: 720,  aspectRatioName: 'hdtv'},
	{name: 'fhd',     pxPerRem: 24, width: 1920, height: 1080, aspectRatioName: 'hdtv', base: true},
	{name: 'uw-uxga', pxPerRem: 24, width: 2560, height: 1080, aspectRatioName: 'cinema'},
	{name: 'uhd',     pxPerRem: 48, width: 3840, height: 2160, aspectRatioName: 'hdtv'}
]);
1 Param
types Array

An array of objects containing screen configuration data, as in the preceding example.

getAspectRatioFunction

getAspectRatio(type)Number

Calculates the aspect ratio of the specified screen type. If no screen type is provided, the current screen type is used.

1 Param
type String

Screen type whose aspect ratio will be calculated. If no screen type is provided, the current screen type is used.

Returns
Number

The calculated screen ratio (e.g., 1.333, 1.777, 2.333, etc.)

getAspectRatioNameFunction

getAspectRatioName(type)String

Returns the name of the aspect ratio for a specified screen type, or for the default screen type if none is provided.

1 Param
type String

Screen type whose aspect ratio name will be returned. If no screen type is provided, the current screen type will be used.

Returns
String

The name of the screen type's aspect ratio

getResolutionClassesFunction

getResolutionClasses(type)String

Returns the CSS classes for the given type

1 Param
type String
default: screenType

Screen type

Returns
String

classes CSS class names

getRiRatioFunction

getRiRatio({type})Number

Returns the ratio of pixels per rem for the given type to the pixels per rem for the base type

0 or more Params
type String
optional
default: screenType

Screen type

Returns
Number

ratio

getScreenTypeFunction

getScreenType({rez})String

Fetches the name of the screen type that best matches the current screen size. The best match is defined as the screen type that is the closest to the screen resolution without going over. ("The Price is Right" style.)

0 or more Params
rez Object
optional

Optional measurement scheme. Must include height and width properties.

Returns
String

Screen type (e.g., 'fhd', 'uhd', etc.)

getUnitToPixelFactorsFunction

getUnitToPixelFactors({type})Number

Returns the pixels per rem for the given type

0 or more Params
type String
optional
default: screenType

Screen type

Returns
Number

pixels per rem

initFunction

init()

This will need to be re-run any time the screen size changes, so all the values can be re-cached.

scaleFunction

scale(px)Number

Takes a provided pixel value and performs a scaling operation based on the current screen type.

1 Param
px Number

The quantity of standard-resolution pixels to scale to the current screen resolution.

Returns
Number

The scaled value based on the current screen scaling factor

scaleToRemFunction

scaleToRem(pixels)

Shorthand for when you know you need to scale some pixel value and have it converted to "rem" for proper scaling. This runs ui/resolution.scale and ui/resolution.unit together.

1 Param
pixels Number

The quantity of standard-resolution pixels to scale to rems

selectSrcFunction

selectSrc(src)String

Selects the ideal image asset from a set of assets, based on various screen resolutions: HD (720p), FHD (1080p), UHD (4k). When a src argument is provided, selectSrc() will choose the best image with respect to the current screen resolution. src may be either the traditional string, which will pass straight through, or a hash/object of screen types and their asset sources (keys:screen and values:src). The image sources will be used when the screen resolution is less than or equal to the provided screen types.

// Take advantage of the multi-res mode
var
	kind = require('enyo/kind'),
	Image = require('enyo/Image');

{kind: Image, src: {
	'hd': 'http://lorempixel.com/64/64/city/1/',
	'fhd': 'http://lorempixel.com/128/128/city/1/',
	'uhd': 'http://lorempixel.com/256/256/city/1/'
}, alt: 'Multi-res'},

// Standard string `src`
{kind: Image, src: http://lorempixel.com/128/128/city/1/', alt: 'Large'},
1 Param
src StringselectSrcSrcOptions

A string containing a single image source or a key/value hash/object containing keys representing screen types ('hd', 'fhd', 'uhd', etc.) and values containing the asset source for that target screen resolution.

Returns
String

The chosen source, given the string or hash provided

selectSrcOptionsObject

The default configurable options for ui/resolution.selectSrc.

hd
String

HD / 720p Resolution image asset source URI/URL

fhd
String

FHD / 1080p Resolution image asset source URI/URL

uhd
String

UHD / 4K Resolution image asset source URI/URL

unitFunction

unit(pixels, toUnit)

Convert to various unit formats. Useful for converting pixels to a resolution-independent measurement method, like "rem". Other units are available if defined in the ui/resolution.unitToPixelFactors object.

var
	dom = require('enyo/dom');

// Do calculations and get back the desired CSS unit.
var frameWidth = 250,
    frameWithMarginInches = dom.unit( 10 + frameWidth + 10, 'in' ),
    frameWithMarginRems = dom.unit( 10 + frameWidth + 10, 'rem' );
// '2.8125in' == frameWithMarginInches
// '22.5rem' == frameWithMarginRems
2 Params
pixels StringNumber

The pixels or math to convert to the unit. ("px" suffix in String format is permitted. ex: '20px')

toUnit String

The name of the unit to convert to.

unitToPixelFactors

Object that stores all of the pixel conversion factors to each keyed unit.

ArrayBooleanFunctionModuleNumberObjectString