Function

Prepares a GET request and initiates the communication.

@author: Hans van den Akker (mysim1)

Prepares a POST request and initiates the communication.

Parses a url

Internal function used by the event decorators to generalize the idea of on, once, and off.

Adds an event listener to the renderable when specific event happened.

Example:

@layout.on('click', function() {this._handleClick})
thing = new Surface({properties: {backgroundColor: 'red'}});

_handleClick() { ... }

Adds an event listener to the renderable when specific event happened once.

Example:

@layout.size(100,100)
@layout.stick.center()
@layout.once('click', function() {this._handleClick})
thing = new Surface({properties: {backgroundColor: 'red'}});

_handleClick() { ... }

Pipes events from one renderable to another. The other renderable has to be declared above the one that is doing the piping, otherwise an exception will be thrown.

Example:

@layout.fullSize()
@layout.pipe('dbsv')
//Pipe events to another renderable declared above, called 'dbsv'
scrollableSurface = new Surface();

Sets the default flow options for a View. These options will be overridden by each of its renderables, if they have flow options defined through e.g. flow.stateStep()

Example:

@flow.defaultOptions({ transition: { curve: Easing.outCubic, duration: 200 } })
class MyView extends View {
}

Functions the same as @flow.stateStep(), and additionally also immediately applies the decorators passed into the 'transformations' argument. Used to define a state step, without having to also manually apply the same decorators to the renderable to ensure it is rendered this way on initial show.

Example:

// Initial size is [100, 100], and rendered at center of parent.
@flow.defaultState('active', {}, layout.size(100, 100), layout.stick.center())
myRenderable = new Surface();

A wrapper around @flow.stateStep, to allow defining multiple steps with the same state name.

Used to define a state that the renderable is able to flow to. When multiple state steps with the same state name are defined, flowing into that state will sequentially execute all defined steps with that state name.

Example:

// Initial size is [0, 0], and rendered at top left of parent, because no @flow.defaultStep() was done,
// and no other decorators are applied to the renderable.
@flow.stateStep('active', {}, layout.size(100, 100), layout.stick.center())
myRenderable = new Surface();

Defines the View-level states, that exist of concurrently and sequentially executed renderable-level states. When e.g. View.setViewFlowState('active') is called, the renderable states defined in the view-level state 'active' are executed.

Example:

// Calling setViewFlowState('active') will first hide the loader, and when that is completed, show both buttons at the same time.
@flow.viewStates({ 'active': [{loader: 'hidden'}, { button1: 'active', button2: 'active' }] })
class MyView extends View {

  @flow.defaultState('shown', {}, layout.opacity(1), layout.fullSize())
  @flow.stateStep('hidden', {}, layout.opacity(0))
  loader = new Surface();

  @flow.defaultState('inactive', {}, layout.opacity(0), layout.size(100, 100), layout.stick.top())
  @flow.stateStep('active', {}, layout.opacity(1))
  button1 = new Surface();

  @flow.defaultState('inactive', {}, layout.opacity(0), layout.size(100, 100), layout.stick.bottom())
  @flow.stateStep('active', {}, layout.opacity(1))
  button1 = new Surface();
}

Internal function to do docking

Translates the renderable by a proportion of the context size.

Example:

@layout.align(0.5, 0.5)
@layout.size(100,100)
//Displays a red box just below the vertical mid point and past the horizontal mid point
renderable = new Surface({properties: {backgroundColor: 'red'}});

Creates an animation controller to show/hide the renderable. Renderables can be shown by calling this.showRenderable(renderableName) and hidden using this.hideRenderable(renderableName) or this.showRenderable(renderableName, false). When a renderable has been shown, it will emit the event 'shown'.

Example:

@layout.stick.center()
@layout.size(100,100)
@layout.animate({transition: {duration: 350}})
renderable = new Surface({properties: {backgroundColor: 'red'}});

Like @layout.dockPadding, sets the padding between this view and its docked content. When the screen width plus this padding exceeds maxContentWidth, the padding is increased, so that the content is never wider than maxContentWidth.

Example:

@layout.columnDockPadding(720, [16])
//Creates a class with 16px margin on all sides for docked renderables
class myView extends View{

 //Will be displayed with margin to the top and sides, and will at max be 720px wide.
 @layout.dock.top(20)
 onTop = new Surface({content: "hello world"});

 //Will be displayed without margin since we're using @layout.stick instead of @layout.dock
 @layout.stick.bottom
 onButtom = new Surface({content: "hey hey"});
}

Adds a custom layout function to the view. This decorator works directly on the object so you shouldn't pass any arguments nor use parentheses.

Example:

@layout.custom((context) => {
 context.set('myRenderable', {
 size: [100, 100]
})
class MyView extends View {
 constructor(options) {
     super(options);
     this.renderables.myRenderable = new Surface({properties: {backgroundColor: 'red'}});
 }
}

Docks the renderable to the bottom. When using both a docked size and the layout.size decorator, then that layout.size becomes the actual inner size. The renderable can then be stickd within the docking area with origin and align. When combined with align, treats the context size the docking size. When using layout.size without specifying a docked size, it will use that size as docking size. Useful for automatic sizing when parent defines true size and orthogonal size (e.g. height for dock 'left') has to be defined.

Example:

@layout.dock.bottom(30, 0, 10)
@layout.size(15, undefined)
@layout.origin(0.5, 0)
@layout.align(0.5, 0)
dockedRenderable = new Surface({properties: {backgroundColor: 'red'}});

Fills the space that is left after the docking with this renderable. When using layout.size, it will use that size as an inner size. This works similarly to other docking, from where translate, size, origin, align, etc can be specified.

Example:

@layout.dock.fill()
filledRenderable = new Surface({properties: {backgroundColor: 'red'}});

Docks the renderable to the left. When using both a docked size and the layout.size decorator, then that layout.size becomes the actual inner size. The renderable can then be stickd within the docking area with origin and align. When combined with align, treats the context size the docking size. When using layout.size without specifying a docked size, it will use that size as docking size. Useful for automatic sizing when parent defines true size and orthogonal size (e.g. height for dock 'left') has to be defined.

Example:

@layout.dock.left(30, 0, 10)
@layout.size(15, undefined)
@layout.origin(0.5, 0)
@layout.align(0.5, 0)
dockedRenderable = new Surface({properties: {backgroundColor: 'red'}});

Marks the renderable as not being docked anymore. Useful when dynamically changing decorations through this.decorateRenderable or this.setRenderableFlowState

Example:

@layout.dock.fill()
@flow.stateStep('nonFilled', layout.dock.none(), layout.size(100, 100))
filledRenderable = new Surface({properties: {backgroundColor: 'red'}});

Docks the renderable to the right. When using both a docked size and the layout.size decorator, then that layout.size becomes the actual inner size. The renderable can then be stickd within the docking area with origin and align. When combined with align, treats the context size the docking size. When using layout.size without specifying a docked size, it will use that size as docking size. Useful for automatic sizing when parent defines true size and orthogonal size (e.g. height for dock 'left') has to be defined.

Example:

@layout.dock.right(30, 0, 10)
@layout.size(15, undefined)
@layout.origin(0.5, 0)
@layout.align(0.5, 0)
dockedRenderable = new Surface({properties: {backgroundColor: 'red'}});

Docks the renderable to the top. When using both a docked size and the layout.size decorator, then that layout.size becomes the actual inner size. The renderable can then be stickd within the docking area with origin and align. When combined with align, treats the context size the docking size. When using layout.size without specifying a docked size, it will use that size as docking size. Useful for automatic sizing when parent defines true size and orthogonal size (e.g. height for dock 'left') has to be defined.

Example:

@layout.dock.top(30, 0, 10)
@layout.size(15, undefined)
@layout.origin(0.5, 0)
@layout.align(0.5, 0)
dockedRenderable = new Surface({properties: {backgroundColor: 'red'}});

Sets the margins for the docked content. This can be applied both to a child and a class. When in conflict, the parent will override the child's setting. If the margin is set on a Surface, then CSS padding will be set. margins can be 1, 2, or 4, parameters, which can be specified as shorthand in the same way as CSS does it.

Example:

@layout.dockPadding(15)
//Creates a class with 15px margin on all sides for docked renderables
class myView extends View{

 //Will be displayed with margin
 @layout.dock.top(20)
 onTop = new Surface({content: "hello world"});

 //Will be displayed without margin since we're using @layout.stick
 @layout.stick.bottom
 onButtom = new Surface({content: "hey hey"});
}

Specifies the space that should come before the docked renderable. Useful when not specifying the size in the layout.dock function. Note that the space does not appear if there isn't any renderable with a size greater than zero before it.

Example:

// there's a 20px space before this box
@layout.dockSpace(20)
@layout.size(100, 100)
@layout.dock.left()
box = new Surface({properties: {backgroundColor: 'red'}});

Makes the renderable allowed to be dragged around. this.renderables[name] refers to a RenderNode containing this draggable along with the renderable itself.

Example:

@layout.draggable({xRange: [0, 100}, yRange: [0, 200]})
@layout.size(100, 100)
// Makes a draggable square that is red
draggableRenderable = new Surface({properties: {backgroundColor: 'red'});

Makes the view flow by tweening all intermediate stages of a changed attribute of any renderable.

Example:

@layout.flow({spring: {dampingRatio: 0.8, period: 1000}})
class myView extends View{
...
}

Marks the renderable to cover the entire screen. Translate can also be specified on such a renderable.

Example:

@layout.fullSize()
// View will have a red background
background = new Surface({properties: {backgroundColor: 'red'}});

Experimental feature of scrolling natively.

Sets the opacity of a renderable.

Example:

@layout.opacity(0.5)
@layout.size(100, 10)
@layout.place.center()
// Writes text that is half invisible
renderable = new Surface({content: 'Half invisible'});

Sets the point where the renderable has its anchor from where rotation and translation will be done. You could consider it as translating the negative of the proportion times its size. The arguments are always between and including 0 and 1.

Example:

@layout.origin(0.5, 0)
@layout.align(0.5, 0.5)
@layout.size(100,100)
//Displays a red box horizontically centered and displays just below the vertical mid point
renderable = new Surface({properties: {backgroundColor: 'red'}});

Merely marks a view property as a decorated renderable, which allows it to be rendered. Use this in combination with a @layout.custom decorator on the view in which this renderable resides.

Example:

@layout.renderable
renderable = new Surface();

Rotates the renderable around any of the three axes (in radians).

Example:

@layout.size(100,100)
@layout.rotate(0, 0, Math.PI)
// Writes text upside down
renderable = new Surface({content: 'upside down text'});

Rotates the renderable around any of the three axes (in radians) relatively to the current rotation

Example:

@layout.size(100,100)
@layout.rotate(0, 0, Math.PI)
// Writes text upside down
renderable = new Surface({content: 'upside down text'});

Specifies the scale of a renderable. Can be applied to every kind of renderable.

Example:

 class myView extends View{
 @layout.scale(2, 2, 2)
 @layout.fullscreen
 // Will scale the renderable by 2 in the x,y,z dimension
 myBackground = new Surface({properties: {backgroudColor: 'red'}});
}

Makes the view as scrollable. This will put the entire content in a ReflowingScrollView that uses getSize on the view to determine scrolling size. If the size cannot be determined, you might consider declaring your own getSize() on the View.

Example:

@layout.scrollable()
class myView extends View{
...
}

Specifies the size of the renderable. For both of the parameters, sizes can be interpreted as follows:

If specified as a function, then the argument passed is the context size of the specified dimension (width or height). Note that if an arrow function is used, this scoping cannot be used when inside a decorator, since the scope will be the global scope.

If true is specified or a tilde with a size (e.g. ~300), then the renderable will be automatically sized. If a tilde is used to indicate the size, then the size after the tilde will be used when/if the renderable doesn't have a size, or turn into the actual size if it can be determined. This is useful when wanting to reduce the flickering of surfaces who's size cannot be determined the first render tick. Beware that true sizing of surfaces or other raw dom elements (input surfaces, image surfaces, text boxes etc) often comes with a perfomance penalty and should only be used when necessary. Also beware that any negative size will be interpreted as a tilde, since ~x = 1 - x

If undefined is specified, then the size of that dimension will equal the entire context size.

If a size between 0 and 1 is specified, then that will be interpreted as a proportion of the context size. For example if 0.5 is specified, then the size will be half of the context size (the parent's size). Instead of specifying 1 to cover the entire context size, use undefined instead.

Example:

@layout.size(function(contextWidth) {return Math.max(contextWidth, this.options.maxWidth)}, ~300)
// Creates a renderable where the width is equal to the text width and the height is whatever is bigger,
// options.maxWidth, or the context size
text = new Surface({content: 'This is some text', properties: {backgroundColor: 'red'}});

Specifies the skew of a renderable. Can be applied to every kind of renderable.

Example:

 class myView extends View{
 @layout.skew(2, 2, 2)
 @layout.fullscreen
 // Will skew the renderable by 2 in the x,y,z dimension
 myBackground = new Surface({properties: {backgroudColor: 'red'}});
}

Makes the renderable swipable with physics-like velocity after the dragging is released. Emits event 'thresholdReached' with arguments ('x'|'y', 0|1) when any thresholds have been reached. this.renderables[name] now refers to a a RenderNode containing a positionModifier along with the renderable itself.

Example:

@layout.size(100, 100)
@layout.swipable({xRange: [0, 100], snapX: true})
//Make a red box that can slide to the right
swipable = new Surface({properties: {backgroundColor: 'red'});

Specifies a translation of a renderable. Can be applied to every kind of renderable (docked, fullSize, and normal). Can also be applied on view level to translate every renderable of that view. The view wide translation defaults to [0, 0, 10] in order to always increase the z space of every level of the Famous rendering tree.

Example:

@layout.translate(0, 0, 20)
class myView extends View{
 @layout.translate(0, 0, -20)
 @layout.fullSize()
 // Will display relatively at z level 0 (20 minus 20)
 myBackground = new Surface({properties: {backgroudColor: 'red'}});
}

Specifies a relative translation of a renderable. Can be applied to every kind of renderable (docked, fullSize, and normal). Can also be applied on view level to translate every renderable of that view. The view wide translation defaults to [0, 0, 10] in order to always increase the z space of every level of the Famous rendering tree.

Example:

@layout.translateFrom(0, 0, 20)
class myView extends View{
 @layout.translateFrom(0, 0, -20)
 @layout.fullSize()
 // Will display relatively at z level 0 (20 minus 20)
 myBackground = new Surface({properties: {backgroudColor: 'red'}});
}

@author: Tom Clement (tjclement)