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
- whentrue
, updates the resolution classes when the window resizesscreenTypes:
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
When
true
, an event listener will be attached to the window to listen for resize events.Default: true- screenTypes
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
, andaspectRatioName
properties are required for each screen type in the array. Settingbase: 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 type0 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
andwidth
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.