jsdom-browser.screen-orientation v0.1.1

jsdom-browser.screen-orientation

The implementation of the Screen Orientation API for jsdom-browser.

jsdom-browser is a simulator of a Web browser with JSDOM.

This module is implemented along the Screen Orientation API on 26 September 2018. This specification may become older than the latest version.

Install

$ npm install jsdom-browser.screen-orientation

Usage

Creates and updates the current orientation type and angle

Creates a ScreenOrientation object and its config object:

const { ScreenConfig } = require('jsdom-browser.screen')
const { ScreenOrientation, ScreenOrientationConfig } = require('jsdom-browser.screen-orientation')

const { JSDOM } = require('jsdom')
const window = new JSDOM().window

const screenConfig = new ScreenConfig({ width: 768, height: 1024 })
screenConfig.configure(window.screen)

const orientationConfig = new ScreenOrientationConfig({
  relationsOfTypeAndAngle: {
    'landscape-primary': 0,
    'portrait-primary': 90,
    'landscape-secondary': 180,
    'portrait-secondary': 270,
  }
})
const orientation = ScreenOrientation.create([], {
  associatedDocument: window.document,
})
orientationConfig.configure(orientation)
window.screen.orientation = orientation


orientation.addEventListener('change', () => {
  console.log(`Orientation was changed: ${orientation.type}`);
})
orientation.onchange = () => {
  console.log(`Orientation was changed (onchange): ${orientation.type}`);
}
orientationConfig.on('change', cfg => {
  console.log(`Orientation was changed (config): ${cfg.currentType}`)
})

Gets the current orientation type and angle:

window.screen.width // => 1024
window.screen.height // => 768
window.screen.orientation.type  // => 'landscape-primary'
window.screen.orientation.angle // => 0

screenConfig.width // => 768
screenConfig.height // => 1024
screenConfig.deviceAngle // => 0
screenConfig.screenAngle // => 0
screenConfig.baseAngle   // => 90

orientationConfig.currentType // => 'landscape-primary'
orientationConfig.currentAngle // => 0
orientationConfig.orientations
// => ['portrait-primary', 
//     'landscape-primary',
//     'portrait-secondary',
//     'landscape-secondary' ]

Simulates of rotating screen:

screenConfig.deviceAngle = -110
orientationConfig.handleRotation()

window.screen.width // => 768
window.screen.height // => 1024
window.screen.orientation.type  // => 'portrait-primary'
window.screen.orientation.angle // => 90

screenConfig.width // => 768
screenConfig.height // => 1024
screenConfig.deviceAngle // => -110
screenConfig.screenAngle // => 90
screenConfig.baseAngle   // => 90

orientationConfig.currentType // => 'portrait-primary'
orientationConfig.currentAngle // => 90
orientationConfig.orientations
// => ['portrait-primary', 
//     'landscape-primary',
//     'portrait-secondary',
//     'landscape-secondary' ]

The output to console is as follows:

Orientation was changed (config): portrait-primary
Orientation was changed: portrait-primary
Orientation was changed (onchange): portrait-primary

Lock the orientation

orientation.lock('landscape').then(() => {
  console.log('Orientation was locked')

  window.screen.width // => 1024
  window.screen.height // => 768
  window.screen.orientation.type  // => 'landscape-primary'
  window.screen.orientation.angle // => 0

  screenConfig.width // => 768
  screenConfig.height // => 1024
  screenConfig.deviceAngle // => -110
  screenConfig.screenAngle // => 0
  screenConfig.baseAngle   // => 90

  orientationConfig.currentType // => 'landscape-primary'
  orientationConfig.currentAngle // => 0

  orientationConfig.orientations
  // => ['landscape-primary',
  //     'landscape-secondary']
}).catch(() => {
  console.log('Orientation lock was rejected')
})

The output to console is as follows:

Orientation was locked
Orientation was changed (config): landscape-primary
Orientation was changed: landscape-primary
Orientation was changed (onchange): landscape-primary

Unlock the orientation

orientation.unlock()

window.screen.width // => 1024
window.screen.height // => 768
window.screen.orientation.type  // => 'landscape-primary'
window.screen.orientation.angle // => 0

screenConfig.width // => 768
screenConfig.height // => 1024
screenConfig.deviceAngle // => -110
screenConfig.screenAngle // => 0
screenConfig.baseAngle   // => 90

orientationConfig.currentType // => 'landscape-primary'
orientationConfig.currentAngle // => 0

orientatonConfig.orientations
// => ['portrait-primary',
//     'landscape-primary',
//     'portrait-secondary',
//     'landscape-secondary' ]

API

class ScreenOrientation : EventTarget

Is an implementation of ScreenOrientation API.

Properties:

lock (lockType) => Promise

Locks the orientation to an orientation type set associated with the specified orientation lock type.

Parameters:

Returns:

A promise object

unlock () => Void

Locks the orientation to default orientation set.

class ScreenOrientationConfig

Is a configuration class to configure a ScreenOrientation object.

Properties:

constructor (screenConfig, initConfig) => ScreenOrientationConfig

Creates an instance of this class. This constructor requires screenConfig as the first argument to get its device angle, screen angle and orientation config array of which elements are the ScreenOrientationConfig objects dangled a same top window. Also, this constructor can accept initConfig as the second argument to configure this instance.

Parameters:

• Properties of initConfig

  See ./src/default.js

  Name	Type	Description
  deviceAngle	number	An angle of device which is used when updating orientation.
  relationsOfTypeAndAngle	object	A mapping of orientation types and orientation angles.
  defaultOrientation	Array	An array of orientation types when orientation is unlocked.
  isSecurityError	boolean	A flag to cause a security error forcely when locking.
  isActiveOrientationLock	boolean	A flag to abort locking because of not active orientatin lock.
  messages	object	Messages for some errors.

update () => Void

Updates the orientation type and angle with the device angle of the ScreenConfig object and the orientations property of this object.

This method fires no change event even if this orientation type is changed.

handleRotation () => Void

Updates the orientation type and angle with the device angle of the ScreenConfig object and the orientations property of this object.

This method fires change events to the orientations associated with the current document, the top document and the all other descendant documents of the top document if this orientation type is changed.

handleVisible () => Void

Updates the orientation type and angle with the device angle of the ScreenConfig object and the orientations property of this object.

This method fires a change event to the current orientation if this orientation type is changed.

on (eventName, handler) => Void

Registers an event handler of an event of which name is eventName.

WebIDL

See the Screen Orientation API,

[Exposed=Window]
interface ScreenOrientation : EventTarget {
  Promise<void> lock(OrientationLockType orientation);
  void unlock();
  readonly attribute OrientationType type;
  readonly attribute unsigned short angle;
  attribute EventHandler onchange;
};

License

Copyright (C) 2018 Takayuki Sato

This program is free software under MIT License. See the file LICENSE in this distribution for more details.