@enact/ui/resolution/index.d.ts

A collection of simplified unstyled cross-platform UI components for Enact

// Type definitions for ui/resolution

type Omit<T, K extends keyof T> = Pick<T, Exclude<keyof T, K>>;
type Merge<M, N> = Omit<M, Extract<keyof M, keyof N>> & N;

export interface ResolutionDecoratorConfig extends Object {
  /**
   * Attaches an event listener to the window to listen for resize events.
   */
  dynamic?: boolean;
  /**
 * An array of objects containing declarations for screen types to add to the list of known
screen types.
 */
  screenTypes?: object[];
}
export interface ResolutionDecoratorProps {}
export function ResolutionDecorator<P>(
  config: ResolutionDecoratorConfig,
  Component: React.ComponentType<P> | string,
): React.ComponentType<P & ResolutionDecoratorProps>;

export function ResolutionDecorator<P>(
  Component: React.ComponentType<P> | string,
): React.ComponentType<P & ResolutionDecoratorProps>;

/**
 * Object that stores the pixel conversion factors to each keyed unit.
 */
export declare const unitToPixelFactors: object;
/**
 * 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.
 * 
 * Example:
 * ```
import ri from 'enact/ui/resolution';

ri.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: 'uw-hd',   pxPerRem: 16, width: 1920, height: 804,  aspectRatioName: 'cinema'},
	{name: 'fhd',     pxPerRem: 24, width: 1920, height: 1080, aspectRatioName: 'hdtv', base: true},
	{name: 'uw-uxga', pxPerRem: 24, width: 2560, height: 1080, aspectRatioName: 'cinema'},
	{name: 'qhd',     pxPerRem: 32, width: 2560, height: 1440, aspectRatioName: 'hdtv'},
	{name: 'wqhd',    pxPerRem: 32, width: 3440, height: 1440, aspectRatioName: 'cinema'},
	{name: 'uhd',     pxPerRem: 48, width: 3840, height: 2160, aspectRatioName: 'hdtv'},
	{name: 'uhd2',    pxPerRem: 96, width: 7680, height: 4320, aspectRatioName: 'hdtv'}
]);
```
 */
export function defineScreenTypes(types: object[]): void;
/**
 * 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.)
 */
export function getScreenType(rez: object): 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:
 * ```
import ri from '@enact/ui/resolution';

ri.config.orientationHandling = 'scale';
ri.init();
```
 
 * This has no effect if the screen is in landscape, or if  `orientationHandling`  is unset.
 */
export function calculateFontSize(type: string): string;
/**
 * Returns the CSS classes for the given  `type` .
 */
export function getResolutionClasses(type: string): string;
/**
 * Returns the ratio of pixels per rem for the given  `type`  to the pixels per rem for the base type.
 */
export function getRiRatio(type: string): number;
/**
 * Returns the pixels per rem for the given  `type` .
 */
export function getUnitToPixelFactors(type: string): number;
/**
 * Calculates the aspect ratio of the specified screen type.
 *
 * If no screen type is provided, the current screen type is used.
 */
export function getAspectRatio(type: string): number;
/**
 * Returns the name of the aspect ratio for a specified screen type, or for the default
screen type if none is provided.
 */
export function getAspectRatioName(type: string): string;
/**
 * Takes a provided pixel value and performs a scaling operation based on the current
screen type.
 */
export function scale(px: number): number;
/**
 * 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
   object.
 * 
 * Example:
 * ```
import ri from '@enact/ui/resolution';

// Do calculations and get back the desired CSS unit.
var frameWidth = 250,
    frameWithMarginInches = ri.unit( 10 + frameWidth + 10, 'in' ), // '2.8125in' == frameWithMarginInches
    frameWithMarginRems = ri.unit( 10 + frameWidth + 10, 'rem' ); // '22.5rem' == frameWithMarginRems
```
 */
export function unit(pixels: string | number, toUnit: string): string | void;
/**
 * Shorthand for when you know you need to scale some pixel value and have it converted to "rem" for
proper scaling.
 * 
 * This runs    and    together.
 */
export function scaleToRem(pixels: number): string | void;
/**
 * The default configurable options for   . Additional resolutions
may be added.
 */
export interface selectSrcOptions {
  /**
   * HD / 720p Resolution image asset source URI/URL
   */
  hd?: string /**
   * FHD / 1080p Resolution image asset source URI/URL
   */;
  fhd?: string /**
   * UHD / 4K Resolution image asset source URI/URL
   */;
  uhd?: 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.
 * 
 * Example:
 * ```
// Take advantage of the multi-res mode
import {Image} from '@enact/ui/Image';

const 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/'
};
...
<Image src={src} ... />
...
```
 */
export function selectSrc(
  src: string | ui_resolution_selectSrcSrcOptions,
): string;
/**
 * This will need to be re-run any time the screen size changes, so all the values can be re-cached.
 */
export function init(args: object): void;