Phaser API Documentation

  Version: 
Filter
This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Structs . Size

This is a beta release of our new docs system. Found an issue?
Please tell us about it in the #📖-newdocs-feedback channel on the Phaser Discord

Phaser . Structs . Size

The Size component allows you to set width and height properties and define the relationship between them.

The component can automatically maintain the aspect ratios between the two values, and clamp them to a defined min-max range. You can also control the dominant axis. When dimensions are given to the Size component that would cause it to exceed its min-max range, the dimensions are adjusted based on the dominant axis.

Constructor:

new Size([width], [height], [aspectMode], [parent])

Parameters:

name type arguments Default description
width number <optional> 0

The width of the Size component.

height number <optional> width

The height of the Size component. If not given, it will use the width.

aspectMode number <optional> 0

The aspect mode of the Size component. Defaults to 0, no mode.

parent any <optional> null

The parent of this Size component. Can be any object with public width and height properties. Dimensions are clamped to keep them within the parent bounds where possible.

Since: 3.16.0
Source: src/structs/Size.js (Line 12)

Members

<static, constant> ENVELOP: number
Focus
Focus

Description:

The width and height are automatically adjusted to make the size cover the entire target area while keeping the aspect ratio. This may extend further out than the target size.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 762)
Focus
Focus
<static, constant> FIT: number
Focus
Focus

Description:

The width and height are automatically adjusted to fit inside the given target area, while keeping the aspect ratio. Depending on the aspect ratio there may be some space inside the area which is not covered.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 752)
Focus
Focus
<static, constant> HEIGHT_CONTROLS_WIDTH: number
Focus
Focus

Description:

The width is automatically adjusted based on the height.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 742)
Focus
Focus
<static, constant> NONE: number
Focus
Focus

Description:

Do not make the size fit the aspect ratio. Change the ratio when the size changes.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 722)
Focus
Focus
<static, constant> WIDTH_CONTROLS_HEIGHT: number
Focus
Focus

Description:

The height is automatically adjusted based on the width.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 732)
Focus
Focus
<private> _height: number
Focus
Focus

Description:

Internal height value.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 51)
Focus
Focus
<private> _parent: any
Focus
Focus

Description:

Internal parent reference.

Type:
any
Since: 3.16.0
Source: src/structs/Size.js (Line 61)
Focus
Focus
<private> _width: number
Focus
Focus

Description:

Internal width value.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 41)
Focus
Focus
<readonly> aspectMode: number
Focus
Focus

Description:

The aspect mode this Size component will use when calculating its dimensions. This property is read-only. To change it use the setAspectMode method.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 71)
Focus
Focus
<readonly> aspectRatio: number
Focus
Focus

Description:

The proportional relationship between the width and height.

This property is read-only and is updated automatically when either the width or height properties are changed, depending on the aspect mode.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 82)
Focus
Focus
height: number
Focus
Focus

Description:

The height of this Size component.

This value is clamped to the range specified by minHeight and maxHeight, if enabled.

A height can never be less than zero.

Changing this value will automatically update the width if the aspect ratio lock is enabled. You can also use the setHeight and getHeight methods.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 692)
Focus
Focus
<readonly> maxHeight: number
Focus
Focus

Description:

The maximum allowed height. This value is read-only. To change it see the setMax method.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 130)
Focus
Focus
<readonly> maxWidth: number
Focus
Focus

Description:

The maximum allowed width. This value is read-only. To change it see the setMax method.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 119)
Focus
Focus
<readonly> minHeight: number
Focus
Focus

Description:

The minimum allowed height. Cannot be less than zero. This value is read-only. To change it see the setMin method.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 107)
Focus
Focus
<readonly> minWidth: number
Focus
Focus

Description:

The minimum allowed width. Cannot be less than zero. This value is read-only. To change it see the setMin method.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 95)
Focus
Focus
<readonly> snapTo: Phaser.Math.Vector2
Focus
Focus

Description:

A Vector2 containing the horizontal and vertical snap values, which the width and height are snapped to during resizing.

By default this is disabled.

This property is read-only. To change it see the setSnap method.

Type:
Since: 3.16.0
Source: src/structs/Size.js (Line 141)
Focus
Focus
width: number
Focus
Focus

Description:

The width of this Size component.

This value is clamped to the range specified by minWidth and maxWidth, if enabled.

A width can never be less than zero.

Changing this value will automatically update the height if the aspect ratio lock is enabled. You can also use the setWidth and getWidth methods.

Type:
number
Since: 3.16.0
Source: src/structs/Size.js (Line 664)
Focus
Focus

Methods

constrain([width], [height], [fit])
Focus
Focus

Description:

The current width and height are adjusted to fit inside the given dimensions, while keeping the aspect ratio.

If fit is true there may be some space inside the target area which is not covered if its aspect ratio differs. If fit is false the size may extend further out than the target area if the aspect ratios differ.

If this Size component has a parent set, then the width and height passed to this method will be clamped so it cannot exceed that of the parent.

Parameters:

name type arguments Default description
width number <optional> 0

The new width of the Size component.

height number <optional>

The new height of the Size component. If not given, it will use the width value.

fit boolean <optional> true

Perform a fit (true) constraint, or an envelop (false) constraint.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 452)
Focus
Focus
copy(destination)
Focus
Focus

Description:

Copies the aspect mode, aspect ratio, width and height from this Size component to the given Size component. Note that the parent, if set, is not copied across.

Parameters:

name type description
destination Phaser.Structs.Size

The Size component to copy the values to.

Returns:
Description:

The updated destination Size component.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 628)
Focus
Focus
destroy()
Focus
Focus

Description:

Destroys this Size component.

This clears the local properties and any parent object, if set.

A destroyed Size component cannot be re-used.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 648)
Focus
Focus
envelop([width], [height])
Focus
Focus

Description:

The current width and height are adjusted so that they fully envelope the given dimensions, while keeping the aspect ratio.

The size may extend further out than the target area if the aspect ratios differ.

If this Size component has a parent set, then the values are clamped so that it never exceeds the parent on the longest axis.

Parameters:

name type arguments description
width number <optional>

The new width of the Size component.

height number <optional>

The new height of the Size component. If not given, it will use the width value.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 542)
Focus
Focus
fitTo([width], [height])
Focus
Focus

Description:

The current width and height are adjusted to fit inside the given dimensions, while keeping the aspect ratio.

There may be some space inside the target area which is not covered if its aspect ratio differs.

If this Size component has a parent set, then the width and height passed to this method will be clamped so it cannot exceed that of the parent.

Parameters:

name type arguments description
width number <optional>

The new width of the Size component.

height number <optional>

The new height of the Size component. If not given, it will use the width value.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 521)
Focus
Focus
getNewHeight(value, [checkParent])
Focus
Focus

Description:

Takes a new height and passes it through the min/max clamp and then checks it doesn't exceed the parent height.

Parameters:

name type arguments Default description
value number

The value to clamp and check.

checkParent boolean <optional> true

Check the given value against the parent, if set.

Returns:
Description:

The modified height value.

Type:
  • number
Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 427)
Focus
Focus
getNewWidth(value, [checkParent])
Focus
Focus

Description:

Takes a new width and passes it through the min/max clamp and then checks it doesn't exceed the parent width.

Parameters:

name type arguments Default description
value number

The value to clamp and check.

checkParent boolean <optional> true

Check the given value against the parent, if set.

Returns:
Description:

The modified width value.

Type:
  • number
Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 402)
Focus
Focus
resize(width, [height])
Focus
Focus

Description:

Sets a new width and height for this Size component and updates the aspect ratio based on them.

It doesn't change the aspectMode and still factors in size limits such as the min max and parent bounds.

Parameters:

name type arguments Default description
width number

The new width of the Size component.

height number <optional> width

The new height of the Size component. If not given, it will use the width.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 380)
Focus
Focus
setAspectMode([value])
Focus
Focus

Description:

Sets the aspect mode of this Size component.

The aspect mode controls what happens when you modify the width or height properties, or call setSize.

It can be a number from 0 to 4, or a Size constant:

  1. NONE = Do not make the size fit the aspect ratio. Change the ratio when the size changes.
  2. WIDTH_CONTROLS_HEIGHT = The height is automatically adjusted based on the width.
  3. HEIGHT_CONTROLS_WIDTH = The width is automatically adjusted based on the height.
  4. FIT = The width and height are automatically adjusted to fit inside the given target area, while keeping the aspect ratio. Depending on the aspect ratio there may be some space inside the area which is not covered.
  5. ENVELOP = The width and height are automatically adjusted to make the size cover the entire target area while keeping the aspect ratio. This may extend further out than the target size.

Calling this method automatically recalculates the width and the height, if required.

Parameters:

name type arguments description
value number <optional>

The aspect mode value.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 156)
Focus
Focus
setAspectRatio(ratio)
Focus
Focus

Description:

Sets a new aspect ratio, overriding what was there previously.

It then calls setSize immediately using the current dimensions.

Parameters:

name type description
ratio number

The new aspect ratio.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 361)
Focus
Focus
setCSS(element)
Focus
Focus

Description:

Sets the values of this Size component to the element.style.width and height properties of the given DOM Element. The properties are set as px values.

Parameters:

name type description
element HTMLElement

The DOM Element to set the CSS style on.

Examples:
Since: 3.17.0
Source: src/structs/Size.js (Line 610)
Focus
Focus
setHeight(height)
Focus
Focus

Description:

Sets the height of this Size component.

Depending on the aspect mode, changing the height may also update the width and aspect ratio.

Parameters:

name type description
height number

The new height of the Size component.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 580)
Focus
Focus
setMax([width], [height])
Focus
Focus

Description:

Set the maximum width and height values this Size component will allow.

Setting this will automatically adjust both the width and height properties to ensure they are within range.

Note that based on the aspect mode, and if this Size component has a parent set or not, the maximums set here can be exceed in some situations.

Parameters:

name type arguments Default description
width number <optional> Number.MAX_VALUE

The maximum allowed width of the Size component.

height number <optional> width

The maximum allowed height of the Size component. If not given, it will use the width.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 276)
Focus
Focus
setMin([width], [height])
Focus
Focus

Description:

Set the minimum width and height values this Size component will allow.

The minimum values can never be below zero, or greater than the maximum values.

Setting this will automatically adjust both the width and height properties to ensure they are within range.

Note that based on the aspect mode, and if this Size component has a parent set or not, the minimums set here can be exceed in some situations.

Parameters:

name type arguments Default description
width number <optional> 0

The minimum allowed width of the Size component.

height number <optional> width

The minimum allowed height of the Size component. If not given, it will use the width.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 247)
Focus
Focus
setParent([parent])
Focus
Focus

Description:

Sets, or clears, the parent of this Size component.

To clear the parent call this method with no arguments.

The parent influences the maximum extents to which this Size component can expand, based on the aspect mode:

NONE - The parent clamps both the width and height. WIDTH_CONTROLS_HEIGHT - The parent clamps just the width. HEIGHT_CONTROLS_WIDTH - The parent clamps just the height. FIT - The parent clamps whichever axis is required to ensure the size fits within it. ENVELOP - The parent is used to ensure the size fully envelops the parent.

Calling this method automatically calls setSize.

Parameters:

name type arguments description
parent any <optional>

Sets the parent of this Size component. Don't provide a value to clear an existing parent.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 217)
Focus
Focus
setSize([width], [height])
Focus
Focus

Description:

Sets the width and height of this Size component based on the aspect mode.

If the aspect mode is 'none' then calling this method will change the aspect ratio, otherwise the current aspect ratio is honored across all other modes.

If snapTo values have been set then the given width and height are snapped first, prior to any further adjustment via min/max values, or a parent.

If minimum and/or maximum dimensions have been specified, the values given to this method will be clamped into that range prior to adjustment, but may still exceed them depending on the aspect mode.

If this Size component has a parent set, and the aspect mode is fit or envelop, then the given sizes will be clamped to the range specified by the parent.

Parameters:

name type arguments Default description
width number <optional> 0

The new width of the Size component.

height number <optional> width

The new height of the Size component. If not given, it will use the width.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 303)
Focus
Focus
setSnap([snapWidth], [snapHeight])
Focus
Focus

Description:

By setting a Snap To value when this Size component is modified its dimensions will automatically by snapped to the nearest grid slice, using floor. For example, if you have snap value of 16, and the width changes to 68, then it will snap down to 64 (the closest multiple of 16 when floored)

Note that snapping takes place before adjustments by the parent, or the min / max settings. If these values are not multiples of the given snap values, then this can result in un-snapped dimensions.

Call this method with no arguments to reset the snap values.

Calling this method automatically recalculates the width and the height, if required.

Parameters:

name type arguments Default description
snapWidth number <optional> 0

The amount to snap the width to. If you don't want to snap the width, pass a value of zero.

snapHeight number <optional> snapWidth

The amount to snap the height to. If not provided it will use the snapWidth value. If you don't want to snap the height, pass a value of zero.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 187)
Focus
Focus
setWidth(width)
Focus
Focus

Description:

Sets the width of this Size component.

Depending on the aspect mode, changing the width may also update the height and aspect ratio.

Parameters:

name type description
width number

The new width of the Size component.

Returns:
Description:

This Size component instance.

Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 563)
Focus
Focus
toString()
Focus
Focus

Description:

Returns a string representation of this Size component.

Returns:
Description:

A string representation of this Size component.

Type:
  • string
Examples:
Since: 3.16.0
Source: src/structs/Size.js (Line 597)
Focus
Focus