Skip to content

AutoLayout.md

Latest commit

 

History

History
520 lines (401 loc) · 21.9 KB

AutoLayout.md

File metadata and controls

520 lines (401 loc) · 21.9 KB
Raw

AutoLayout

AutoLayoutJS API reference.

Index

Entity Type Description
AutoLayout namespace Top level AutoLayout object.
VisualFormat namespace Parses VFL into constraints.
View class Main entity for adding & evaluating constraints.
SubView class SubView's are automatically created when constraints are added to views. They give access to the evaluated results.
Attribute enum Attribute types that are supported when adding constraints.
Relation enum Relationship types that are supported when adding constraints.
Priority enum Default priority values for when adding constraints.

AutoLayout

AutoLayout~View

Kind: inner class of AutoLayout

new View([options])

Param Type Description
[options] Object Configuration options.
[options.width] Number Initial width of the view.
[options.height] Number Initial height of the view.
[options.spacing] Number | Object Spacing for the view (default: 8) (see setSpacing).
[options.constraints] Array One or more constraint definitions (see addConstraints).

view.width : Number

Width that was set using setSize.

Kind: instance property of View
Read only: true

view.height : Number

Height that was set using setSize.

Kind: instance property of View
Read only: true

view.fittingWidth : Number

Width that is calculated from the constraints and the .intrinsicWidth of the sub-views.

When the width has been explicitely set using setSize, the fittingWidth will always be the same as the explicitely set width. To calculate the size based on the content, use:

var view = new AutoLayout.View({
  constraints: VisualFormat.parse('|-[view1]-[view2]-'),
  spacing: 20
});
view.subViews.view1.intrinsicWidth = 100;
view.subViews.view2.intrinsicWidth = 100;
console.log('fittingWidth: ' + view.fittingWidth); // 260

Kind: instance property of View
Read only: true

view.fittingHeight : Number

Height that is calculated from the constraints and the .intrinsicHeight of the sub-views.

See .fittingWidth.

Kind: instance property of View
Read only: true

view.subViews : Object.SubView

Dictionary of SubView objects that have been created when adding constraints.

Kind: instance property of View
Read only: true

view.setSize(width, height) ⇒ View

Sets the width and height of the view.

Kind: instance method of View
Returns: View - this

Param Type Description
width Number Width of the view.
height Number Height of the view.

view.setSpacing(spacing) ⇒ View

Sets the spacing for the view.

The spacing can be set for 7 different variables: top, right, bottom, left, width, height and zIndex. The left-spacing is used when a spacer is used between the parent-view and a sub-view (e.g. |-[subView]). The same is true for the right, top and bottom spacers. The width and height are used for spacers in between sub-views (e.g. [view1]-[view2]).

Instead of using the full spacing syntax, it is also possible to use shorthand notations:

Syntax Type Description
[top, right, bottom, left, width, height, zIndex] Array(7) Full syntax including z-index (clockwise order).
[top, right, bottom, left, width, height] Array(6) Full horizontal & vertical spacing syntax (no z-index) (clockwise order).
[horizontal, vertical, zIndex] Array(3) Horizontal = left, right, width, vertical = top, bottom, height.
[horizontal, vertical] Array(2) Horizontal = left, right, width, vertical = top, bottom, height, z-index = 1.
spacing Number Horizontal & vertical spacing are all the same, z-index = 1.

Examples:

view.setSpacing(10); // horizontal & vertical spacing 10
view.setSpacing([10, 15, 2]); // horizontal spacing 10, vertical spacing 15, z-axis spacing 2
view.setSpacing([10, 20, 10, 20, 5, 5]); // top, right, bottom, left, horizontal, vertical
view.setSpacing([10, 20, 10, 20, 5, 5, 1]); // top, right, bottom, left, horizontal, vertical, z

Kind: instance method of View
Returns: View - this

Param Type
spacing Number | Array

view.addConstraint(constraint) ⇒ View

Adds a constraint definition.

A constraint definition has the following format:

constraint: {
  view1: {String},
  attr1: {AutoLayout.Attribute},
  relation: {AutoLayout.Relation},
  view2: {String},
  attr2: {AutoLayout.Attribute},
  multiplier: {Number},
  constant: {Number},
  priority: {Number}(0..1000)
}

Kind: instance method of View
Returns: View - this

Param Type Description
constraint Object Constraint definition.

view.addConstraints(constraints) ⇒ View

Adds one or more constraint definitions.

A constraint definition has the following format:

constraint: {
  view1: {String},
  attr1: {AutoLayout.Attribute},
  relation: {AutoLayout.Relation},
  view2: {String},
  attr2: {AutoLayout.Attribute},
  multiplier: {Number},
  constant: {Number},
  priority: {Number}(0..1000)
}

Kind: instance method of View
Returns: View - this

Param Type Description
constraints Array One or more constraint definitions.

AutoLayout~SubView : object

A SubView is automatically generated when constraints are added to a View.

Kind: inner namespace of AutoLayout

subView.name : String

Name of the sub-view.

Kind: instance property of SubView
Read only: true

subView.left : Number

Left value (Attribute.LEFT).

Kind: instance property of SubView
Read only: true

subView.right : Number

Right value (Attribute.RIGHT).

Kind: instance property of SubView
Read only: true

subView.width : Number

Width value (Attribute.WIDTH).

Kind: instance property of SubView

subView.height : Number

Height value (Attribute.HEIGHT).

Kind: instance property of SubView
Read only: true

subView.intrinsicWidth : Number

Intrinsic width of the sub-view.

Use this property to explicitely set the width of the sub-view, e.g.:

var view = new AutoLayout.View(AutoLayout.VisualFormat.parse('|[child1][child2]|'), {
  width: 500
});
view.subViews.child1.intrinsicWidth = 100;
console.log('child2 width: ' + view.subViews.child2.width); // 400

Kind: instance property of SubView

subView.intrinsicHeight : Number

Intrinsic height of the sub-view.

See intrinsicWidth.

Kind: instance property of SubView

subView.top : Number

Top value (Attribute.TOP).

Kind: instance property of SubView
Read only: true

subView.bottom : Number

Bottom value (Attribute.BOTTOM).

Kind: instance property of SubView
Read only: true

subView.centerX : Number

Horizontal center (Attribute.CENTERX).

Kind: instance property of SubView
Read only: true

subView.centerY : Number

Vertical center (Attribute.CENTERY).

Kind: instance property of SubView
Read only: true

subView.zIndex : Number

Z-index (Attribute.ZINDEX).

Kind: instance property of SubView
Read only: true

subView.type : String

Returns the type of the sub-view.

Kind: instance property of SubView
Read only: true

subView.getValue(attr) ⇒ Number

Gets the value of one of the attributes.

Kind: instance method of SubView
Returns: Number - value or undefined

Param Type Description
attr String | Attribute Attribute name (e.g. 'right', 'centerY', Attribute.TOP).

AutoLayout~VisualFormat : object

VisualFormat

Kind: inner namespace of AutoLayout

VisualFormat.parseLine(visualFormat, [options]) ⇒ Array

Parses a single line of vfl into an array of constraint definitions.

When the visual-format could not be succesfully parsed an exception is thrown containing additional info about the parse error and column position.

Kind: static method of VisualFormat
Returns: Array - Array of constraint definitions.

Param Type Description
visualFormat String Visual format string (cannot contain line-endings!).
[options] Object Configuration options.
[options.extended] Boolean When set to true uses the extended syntax (default: false).
[options.outFormat] String Output format (constraints or raw) (default: constraints).
[options.lineIndex] Number Line-index used when auto generating equal-spacing constraints.

VisualFormat.parse(visualFormat, [options]) ⇒ Array

Parses one or more visual format strings into an array of constraint definitions.

When the visual-format could not be succesfully parsed an exception is thrown containing additional info about the parse error and column position.

Kind: static method of VisualFormat
Returns: Array - Array of constraint definitions.

Param Type Description
visualFormat String | Array One or more visual format strings.
[options] Object Configuration options.
[options.extended] Boolean When set to true uses the extended syntax (default: false).
[options.strict] Boolean When set to false trims any leading/trailing spaces and ignores empty lines (default: true).
[options.lineSeparator] String String that defines the end of a line (default \n).
[options.outFormat] String Output format (constraints or raw) (default: constraints).

VisualFormat.parseMetaInfo(visualFormat, [options]) ⇒ Object

Parses meta information from the comments in the VFL.

Additional meta information can be specified in the comments for previewing and rendering purposes. For instance, the view-port aspect-ratio, sub-view widths and colors, can be specified. The following example renders three colored circles in the visual-format editor:

//viewport aspect-ratio:3/1 max-height:300
//colors red:#FF0000 green:#00FF00 blue:#0000FF
//shapes red:circle green:circle blue:circle
H:|-[row:[red(green,blue)]-[green]-[blue]]-|
V:|[row]|

Supported categories and properties:

Category Property Example
viewport aspect-ratio:{width}/{height} //viewport aspect-ratio:16/9
width:[{number}/intrinsic] //viewport width:10
height:[{number}/intrinsic] //viewport height:intrinsic
min-width:{number}
max-width:{number}
min-height:{number}
max-height:{number}
spacing [{number}/array] //spacing:8 or //spacing:[10, 20, 5]
widths {view-name}:[{number}/intrinsic] //widths subview1:100
heights {view-name}:[{number}/intrinsic] //heights subview1:intrinsic
colors {view-name}:{color} //colors redview:#FF0000 blueview:#00FF00
shapes {view-name}:[circle/square] //shapes avatar:circle

Kind: static method of VisualFormat
Returns: Object - meta-info

Param Type Description
visualFormat String | Array One or more visual format strings.
[options] Object Configuration options.
[options.lineSeparator] String String that defines the end of a line (default \n).
[options.prefix] String When specified, also processes the categories using that prefix (e.g. "-dev-viewport max-height:10").

AutoLayout~Attribute : enum

Layout attributes.

Kind: inner enum of AutoLayout
Properties

Name Type Default Description
CONST String const
NOTANATTRIBUTE String const
VARIABLE String var
LEFT String left
RIGHT String right
TOP String top
BOTTOM String bottom
WIDTH String width
HEIGHT String height
CENTERX String centerX
CENTERY String centerY
ZINDEX String zIndex Used by the extended VFL syntax.

AutoLayout~Relation : enum

Relation types.

Kind: inner enum of AutoLayout
Properties

Name Type Default Description
LEQ String leq Less than or equal
EQU String equ Equal
GEQ String geq Greater than or equal

AutoLayout~Priority : enum

Layout priorities.

Kind: inner enum of AutoLayout
Properties

Name Type Default
REQUIRED String 1000
DEFAULTHIGH String 750
DEFAULTLOW String 250