Changed Item::scaleInPoint() to be absolute

# Item

    'use strict'

    assert = require 'src/assert'
    utils = require 'src/utils'
    signal = require 'src/signal'
    List = require 'src/list'
    Matrix = require 'src/renderer/utils/Matrix'

    {isArray} = Array
    {emitSignal} = signal.Emitter

    assert = assert.scope 'Renderer.Item'

    module.exports = (Renderer, Impl, itemUtils) -> class Item extends itemUtils.Object
        @__name__ = 'Item'
        @__path__ = 'Renderer.Item'

        Document = require 'src/document'
        DocElement = Document.Element

## *Item* Item.New([*Object* options])

        @New = (opts) ->
            item = new Item
            itemUtils.Object.initialize item, opts
            item

## *Item* Item::constructor()

This is a base class for everything which is visible.

        constructor: ->
            assert.instanceOf @, Item

            super()
            @_parent = null
            @_children = null
            @_previousSibling = null
            @_nextSibling = null
            @_belowSibling = null
            @_aboveSibling = null
            @_width = 0
            @_height = 0
            @_x = 0
            @_y = 0
            @_z = 0
            @_visible = true
            @_clip = false
            @_scale = 1
            @_rotation = 0
            @_opacity = 1
            @_linkUri = ''
            @_anchors = null
            @_layout = null
            @_keys = null
            @_pointer = null
            @_margin = null
            @_classes = null
            @_query = ''
            @_node = null

### Custom properties

```nml
Item {
    id: main
    property currentLife: 0.8
    Text {
        text: "Life: " + main.currentLife
    }
}
```

### Custom signals

```nml
Item {
    signal onPlayerCollision
    onPlayerCollision(){
        // boom!
    }
}
```

## ReadOnly *String* Item::query

        utils.defineProperty @::, 'query', null, ->
            @_query
        , (val) ->
            if @_query is ''
                @_query = val
            return

## ReadOnly *Document.Element* Item::node

## *Signal* Item::onNodeChange(*Document.Element* oldValue)

```javascript
Text {
    text: this.node.props.value
}
```

```javascript
Text {
    onNodeChange: function(){
        var inputs = this.node.queryAll('input[type=string]');
    }
}
```

        itemUtils.defineProperty
            constructor: @
            name: 'node'
            defaultValue: null
            developmentSetter: (val) ->
                if val?
                    assert.instanceOf val, DocElement

## *Signal* Item::ready()

Called when the Item is ready, that is, all
properties have been set and it's ready to use.

```nml
Rectangle {
    width: 200
    height: 50
    color: 'green'
    Rectangle {
        width: parent.width / 2
        height: parent.height / 2
        color: 'yellow'
        onReady: function(){
            console.log(this.width, this.height);
            // 100, 25
        }
    }
}
```

        signal.Emitter.createSignal @, 'onReady'

## *Signal* Item::onAnimationFrame(*Integer* miliseconds)

        signal.Emitter.createSignal @, 'onAnimationFrame', do ->
            now = Date.now()
            items = []

            frame = ->
                oldNow = now
                now = Date.now()
                ms = now - oldNow

                for item in items
                    emitSignal item, 'onAnimationFrame', ms
                requestAnimationFrame frame

            requestAnimationFrame? frame

            (item) ->
                items.push item

## ReadOnly *String* Item::id

## *Object* Item::children

        utils.defineProperty @::, 'children', null, ->
            @_children ||= new ChildrenObject(@)
        , (val) ->
            assert.isArray val, "Item.children needs to be an array, but #{val} given"
            @clear()
            for item in val
                val.parent = @
            return

## *Signal* Item::onChildrenChange(*Item* added, *Item* removed)

        signal.Emitter.createSignal @, 'onChildrenChange'

        class ChildrenObject extends itemUtils.MutableDeepObject
            constructor: (ref) ->
                @_layout = null
                @_target = null
                @_firstChild = null
                @_lastChild = null
                @_bottomChild = null
                @_topChild = null
                @_length = 0
                super ref

### ReadOnly *Item* Item::children.firstChild

            utils.defineProperty @::, 'firstChild', null, ->
                @_firstChild
            , null

### ReadOnly *Item* Item::children.lastChild

            utils.defineProperty @::, 'lastChild', null, ->
                @_lastChild
            , null

### ReadOnly *Item* Item::children.bottomChild

            utils.defineProperty @::, 'bottomChild', null, ->
                @_bottomChild
            , null

### ReadOnly *Item* Item::children.topChild

            utils.defineProperty @::, 'topChild', null, ->
                @_topChild
            , null

### ReadOnly *Integer* Item::children.length

            utils.defineProperty @::, 'length', null, ->
                @_length
            , null

### *Item* Item::children.layout

Item used to position children items.
Can be e.g. *Flow*, *Grid* etc.

### *Signal* Item::children.onLayoutChange(*Item* oldValue)

            itemUtils.defineProperty
                constructor: @
                name: 'layout'
                defaultValue: null
                developmentSetter: (val) ->
                    if val?
                        assert.instanceOf val, Item, """
                            Item.children.layout needs to be an Item, but #{val} given
                        """
                setter: (_super) -> (val) ->
                    if @_layout?.effectItem
                        @_layout.parent = null
                        @_layout.effectItem = @_layout

                    _super.call @, val

                    if '_effectItem' of @_ref
                        @_ref.effectItem = if val then null else @_ref

                    if val?
                        ref = @_ref
                        setFakeParent val, ref, 0
                        if val.effectItem
                            val.effectItem = ref

                    return

### *Item* Item::children.target

A new child trying to be added into the item with the `children.target` defined
will be added into the `target` item.

### *Signal* Item::children.onTargetChange(*Item* oldValue)

            itemUtils.defineProperty
                constructor: @
                name: 'target'
                defaultValue: null
                developmentSetter: (val) ->
                    if val?
                        assert.instanceOf val, Item, """
                            Item.children.target needs to be an Item, but #{val} given
                        """

### *Item* Item::children.get(*Integer* index)

Returns an item with the given index.

            get: (val) ->
                assert.operator val, '>=', 0, """
                    Item.children.get index cannot be lower than zero, #{val} given
                """
                assert.operator val, '<', @length, """
                    Item.children.get index must be lower than children.length, \
                    #{val} given
                """

                if val < @length / 2
                    sibling = @firstChild
                    while val > 0
                        sibling = sibling.nextSibling
                        val--
                else
                    sibling = @lastChild
                    while val > 0
                        sibling = sibling.previousSibling
                        val--

                sibling

### *Integer* Item::children.index(*Item* value)

Returns an index of the given child in the children array.

            index: (val) ->
                if @has(val)
                    val.index
                else
                    -1

### *Boolean* Item::children.has(*Item* value)

Returns `true` if the given item is an item child.

            has: (val) ->
                @_ref is val._parent

### Item::children.clear()

Removes all children from the item.

            clear: ->
                while last = @last
                    last.parent = null
                return

## *Item* Item::parent = `null`

## *Signal* Item::onParentChange(*Item* oldParent)

        setFakeParent = (child, parent, index=-1) ->
            child.parent = null

            if index >= 0 and parent.children._length < index
                Impl.insertItemBefore.call child, parent.children[index]
            else
                Impl.setItemParent.call child, parent

            child._parent = parent
            emitSignal child, 'onParentChange', null
            return

        updateZSiblingsForAppendedItem = (item, z, newChildren) ->
            child = newChildren._topChild
            while child
                if child._z <= z
                    if item._aboveSibling = child._aboveSibling
                        item._aboveSibling._belowSibling = item
                    item._belowSibling = child
                    child._aboveSibling = item
                    return
                unless nextChild = child._belowSibling
                    item._aboveSibling = child
                    child._belowSibling = item
                    item._belowSibling = null
                    return
                child = nextChild
            return

        insertItemInImpl = (item) ->
            if aboveSibling = item._aboveSibling
                Impl.insertItemBefore.call item, aboveSibling
            else
                Impl.setItemParent.call item, item._parent
            return

        itemUtils.defineProperty
            constructor: @
            name: 'parent'
            defaultValue: null
            setter: (_super) -> (val = null) ->
                old = @_parent
                oldChildren = old?.children
                valChildren = val?.children

                if valChildren?._target
                    # detect whether target is a child of this item
                    containsItem = false
                    tmpItem = valChildren._target
                    while tmpItem
                        if tmpItem is @
                            containsItem = true
                            break
                        tmpItem = tmpItem._parent

                    unless containsItem
                        val = valChildren._target
                        valChildren = val.children

                if old is val
                    return

                assert.isNot @, val, "Item.parent cannot be set with context item, #{val} given"

                if pointer = @_pointer
                    pointer.hover = pointer.pressed = false

                if val isnt null
                    assert.instanceOf val, Item, """
                        Item.parent needs to be an Item or null, but #{val} given
                    """

                # old siblings
                oldPreviousSibling = @_previousSibling
                oldNextSibling = @_nextSibling
                if oldPreviousSibling isnt null
                    oldPreviousSibling._nextSibling = oldNextSibling
                if oldNextSibling isnt null
                    oldNextSibling._previousSibling = oldPreviousSibling

                # new siblings
                if val isnt null
                    if previousSibling = @_previousSibling = valChildren.lastChild
                        previousSibling._nextSibling = @
                else
                    @_previousSibling = null
                if oldNextSibling isnt null
                    @_nextSibling = null

                # children
                if oldChildren
                    oldChildren._length -= 1
                    if oldChildren.firstChild is @
                        oldChildren._firstChild = oldNextSibling
                    if oldChildren.lastChild is @
                        oldChildren._lastChild = oldPreviousSibling
                if valChildren
                    if ++valChildren._length is 1
                        valChildren._firstChild = @
                    valChildren._lastChild = @

                # old z-index siblings
                oldBelowSibling = @_belowSibling
                oldAboveSibling = @_aboveSibling
                if oldBelowSibling isnt null
                    oldBelowSibling._aboveSibling = oldAboveSibling
                if oldAboveSibling isnt null
                    oldAboveSibling._belowSibling = oldBelowSibling

                # new z-index siblings
                @_belowSibling = @_aboveSibling = null
                if valChildren
                    updateZSiblingsForAppendedItem @, @_z, valChildren

                # z-index children
                if oldChildren
                    unless oldAboveSibling
                        oldChildren._topChild = oldBelowSibling
                    unless oldBelowSibling
                        oldChildren._bottomChild = oldAboveSibling
                if valChildren
                    unless @_aboveSibling
                        valChildren._topChild = @
                    unless @_belowSibling
                        valChildren._bottomChild = @

                # parent
                @_parent = val
                insertItemInImpl @

                `//<development>`
                assert.is @nextSibling, null
                if val
                    assert.is val.children.lastChild, @
                    assert.isDefined val.children.firstChild
                    assert.isDefined val.children.lastChild
                    assert.isDefined val.children.topChild
                    assert.isDefined val.children.bottomChild
                if old and old.children.length is 0
                    assert.isNotDefined old.children.firstChild
                    assert.isNotDefined old.children.lastChild
                    assert.isNotDefined old.children.topChild
                    assert.isNotDefined old.children.bottomChild
                `//</development>`

                # signals
                if old isnt null
                    emitSignal old, 'onChildrenChange', null, @
                if val isnt null
                    emitSignal val, 'onChildrenChange', @, null

                emitSignal @, 'onParentChange', old

                if oldPreviousSibling isnt null
                    emitSignal oldPreviousSibling, 'onNextSiblingChange', @
                if oldNextSibling isnt null
                    emitSignal oldNextSibling, 'onPreviousSiblingChange', @

                if val isnt null or oldPreviousSibling isnt null
                    if previousSibling
                        emitSignal previousSibling, 'onNextSiblingChange', null
                    emitSignal @, 'onPreviousSiblingChange', oldPreviousSibling
                if oldNextSibling isnt null
                    emitSignal @, 'onNextSiblingChange', oldNextSibling

                return

## *Item* Item::previousSibling

        utils.defineProperty @::, 'previousSibling', null, ->
            @_previousSibling
        , (val = null) ->
            assert.isNot @, val, """
                Item.previousSibling cannot be set with context Item, #{val} given
            """

            if val is @_previousSibling
                return

            if val
                assert.instanceOf val, Item, """
                    Item.previousSibling must be an Item or null, but #{val} given
                """
                nextSibling = val._nextSibling
                if not nextSibling and val._parent isnt @_parent
                    @parent = val._parent
                else
                    @nextSibling = nextSibling
            else
                assert.isDefined @_parent, """
                    Cannot null Item.previousSibling when Item has no parent
                """
                @nextSibling = @_parent.children.firstChild

            assert.is @_previousSibling, val
            return

## *Signal* Item::onPreviousSiblingChange(*Item* oldValue)

        signal.Emitter.createSignal @, 'onPreviousSiblingChange'

## *Item* Item::nextSibling

        isNextSibling = (item, sibling) ->
            while item
                nextItem = item._nextSibling
                if nextItem is sibling
                    return true
                item = nextItem
            return false

        isPreviousSibling = (item, sibling) ->
            while item
                prevItem = item._previousSibling
                if prevItem is sibling
                    return true
                item = prevItem
            return false

        updateZSiblingsForInsertedItem = (item, nextSibling, z, newChildren) ->
            if nextSibling._z is z
                # simple case - the same z-index as in nextSibling
                if item._belowSibling = nextSibling._belowSibling
                    item._belowSibling._aboveSibling = item
                item._aboveSibling = nextSibling
                nextSibling._belowSibling = item
            else
                # hard case - different z-indexes
                nextChild = newChildren._bottomChild
                while child = nextChild
                    nextChild = child._aboveSibling
                    if child._z > z or (child._z is z and isNextSibling(item, child))
                        item._aboveSibling = child
                        if item._belowSibling = child._belowSibling
                            item._belowSibling._aboveSibling = item
                        child._belowSibling = item
                        break
                    unless nextChild
                        item._aboveSibling = null
                        item._belowSibling = child
                        child._aboveSibling = item
            return

        utils.defineProperty @::, 'nextSibling', null, ->
            @_nextSibling
        , (val = null) ->
            assert.isNot @, val, """
                Item.nextSibling cannot be set with context Item, #{val} given
            """
            if val
                assert.instanceOf val, Item, """
                    Item.nextSibling needs to be an Item or null, but #{val} given
                """
                assert.isDefined val._parent, """
                    Item.nextSibling value needs to have a parent, given #{val} has no parent
                """
            else
                assert.isDefined @_parent, """
                    Cannot null Item.nextSibling when Item has no parent
                """

            if val is @_nextSibling
                return

            oldParent = @_parent
            oldChildren = oldParent?._children
            oldPreviousSibling = @_previousSibling
            oldNextSibling = @_nextSibling

            if val
                newParent = val._parent
                newChildren = newParent._children
            else
                newParent = oldParent
                newChildren = oldChildren

            # new parent
            @_parent = newParent

            # current siblings
            oldPreviousSibling?._nextSibling = oldNextSibling
            oldNextSibling?._previousSibling = oldPreviousSibling

            # new siblings
            previousSibling = previousSiblingOldNextSibling = null
            nextSibling = nextSiblingOldPreviousSibling = null
            if val
                if previousSibling = val._previousSibling
                    previousSiblingOldNextSibling = previousSibling._nextSibling
                    previousSibling._nextSibling = @

                nextSibling = val
                nextSiblingOldPreviousSibling = nextSibling._previousSibling
                nextSibling._previousSibling = @
            else
                if previousSibling = newChildren.lastChild
                    previousSibling._nextSibling = @

            @_previousSibling = previousSibling
            @_nextSibling = nextSibling

            # children
            if oldChildren
                oldChildren._length -= 1
                unless oldPreviousSibling
                    oldChildren._firstChild = oldNextSibling
                unless oldNextSibling
                    oldChildren._lastChild = oldPreviousSibling
            newChildren._length += 1
            if newChildren.firstChild is val
                newChildren._firstChild = @
            unless val
                newChildren._lastChild = @

            # old z-index siblings
            oldBelowSibling = @_belowSibling
            oldAboveSibling = @_aboveSibling
            if oldBelowSibling isnt null
                oldBelowSibling._aboveSibling = oldAboveSibling
            if oldAboveSibling isnt null
                oldAboveSibling._belowSibling = oldBelowSibling

            # new z-index siblings
            @_belowSibling = @_aboveSibling = null
            if nextSibling
                updateZSiblingsForInsertedItem @, nextSibling, @_z, newChildren
            else
                updateZSiblingsForAppendedItem @, @_z, newChildren

            # z-index children
            if oldChildren
                unless oldAboveSibling
                    oldChildren._topChild = oldBelowSibling
                unless oldBelowSibling
                    oldChildren._bottomChild = oldAboveSibling
            unless @_aboveSibling
                newChildren._topChild = @
            unless @_belowSibling
                newChildren._bottomChild = @

            # implementation
            insertItemInImpl @

            `//<development>`
            assert.is @_nextSibling, val
            assert.is @_parent, newParent
            if val
                assert.is @_parent, val._parent
            if @_previousSibling
                assert.is @_previousSibling._nextSibling, @
            if @_nextSibling
                assert.is @_nextSibling._previousSibling, @
            if oldPreviousSibling
                assert.is oldPreviousSibling._nextSibling, oldNextSibling
            if oldNextSibling
                assert.is oldNextSibling._previousSibling, oldPreviousSibling
            `//</development>`

            # children signal
            if oldParent isnt newParent
                if oldParent
                    emitSignal oldParent, 'onChildrenChange', null, @
                emitSignal newParent, 'onChildrenChange', @, null
                emitSignal @, 'onParentChange', oldParent
            else
                emitSignal newParent, 'onChildrenChange', null, null

            # current siblings signals
            if oldPreviousSibling
                emitSignal oldPreviousSibling, 'onNextSiblingChange', @
            if oldNextSibling
                emitSignal oldNextSibling, 'onPreviousSiblingChange', @

            # new siblings signals
            emitSignal @, 'onPreviousSiblingChange', oldPreviousSibling
            if previousSibling
                emitSignal previousSibling, 'onNextSiblingChange', previousSiblingOldNextSibling
            emitSignal @, 'onNextSiblingChange', oldNextSibling
            if nextSibling
                emitSignal nextSibling, 'onPreviousSiblingChange', nextSiblingOldPreviousSibling

            return

## *Signal* Item::onNextSiblingChange(*Item* oldValue)

        signal.Emitter.createSignal @, 'onNextSiblingChange'

## ReadOnly *Item* Item::belowSibling

        utils.defineProperty @::, 'belowSibling', null, ->
            @_belowSibling
        , null

## ReadOnly *Item* Item::aboveSibling

        utils.defineProperty @::, 'aboveSibling', null, ->
            @_aboveSibling
        , null

## *Integer* Item::index

        utils.defineProperty @::, 'index', null, ->
            index = 0
            sibling = @
            while sibling = sibling.previousSibling
                index++
            index
        , (val) ->
            assert.isInteger val, "Item.index needs to be a integer, but #{val} given"
            assert.isDefined @_parent, """
                When setting Item.index, item needs to have a parent, #{@} has no parent
            """
            assert.operator val, '>=', 0, "Item.index needs to greater than zero, #{val} given"
            assert.operator val, '<=', @_parent._children.length, """
                Item.index needs to be lower than parent.children.length, #{val} given
            """

            {children} = @parent
            if val >= children.length
                @nextSibling = null
            else if (valItem = children.get(val)) isnt @
                @nextSibling = valItem

            return

## *Boolean* Item::visible = `true`

Determines whether an item is visible or not.

```nml
Item {
    width: 100
    height: 100
    pointer.onClick: function(){
        rect.visible = !rect.visible;
        text.text = rect.visible ? "Click to hide" : "Click to show";
    }
    Rectangle {
        id: rect
        anchors.fill: parent
        color: 'blue'
    }
    Text {
        id: text
        text: "Click to hide"
        anchors.centerIn: parent
    }
}
```

## *Signal* Item::onVisibleChange(*Boolean* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'visible'
            defaultValue: true
            implementation: Impl.setItemVisible
            developmentSetter: (val) ->
                assert.isBoolean val, "Item.visible needs to be a boolean, but #{val} given"

## *Boolean* Item::clip = `false`

## *Signal* Item::onClipChange(*Boolean* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'clip'
            defaultValue: false
            implementation: Impl.setItemClip
            developmentSetter: (val) ->
                assert.isBoolean val, "Item.clip needs to be a boolean, but #{val} given"

## *Float* Item::width = `0`

## *Signal* Item::onWidthChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'width'
            defaultValue: 0
            implementation: Impl.setItemWidth
            developmentSetter: (val) ->
                assert.isFloat val, "Item.width needs to be a float, but #{val} given"

## *Float* Item::height = `0`

## *Signal* Item::onHeightChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'height'
            defaultValue: 0
            implementation: Impl.setItemHeight
            developmentSetter: (val) ->
                assert.isFloat val, "Item.height needs to be a float, but #{val} given"

## *Float* Item::x = `0`

## *Signal* Item::onXChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'x'
            defaultValue: 0
            implementation: Impl.setItemX
            developmentSetter: (val) ->
                assert.isFloat val, "Item.x needs to be a float, but #{val} given"

## *Float* Item::y = `0`

## *Signal* Item::onYChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'y'
            defaultValue: 0
            implementation: Impl.setItemY
            developmentSetter: (val) ->
                assert.isFloat val, "Item.y needs to be a float, but #{val} given"

## *Float* Item::z = `0`

## *Signal* Item::onZChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'z'
            defaultValue: 0
            developmentSetter: (val) ->
                assert.isFloat val, "Item.z needs to be a float, but #{val} given"
            setter: (_super) -> (val) ->
                oldVal = @_z
                if oldVal is val
                    return

                _super.call @, val

                unless parent = @_parent
                    return
                children = parent._children
                oldAboveSibling = @_aboveSibling
                oldBelowSibling = @_belowSibling

                # new siblings
                if val > oldVal
                    nextChild = @_aboveSibling
                    while child = nextChild
                        nextChild = child._aboveSibling
                        if child._z > val or (child._z is val and isNextSibling(@, child))
                            if oldAboveSibling is child
                                break
                            @_aboveSibling = child
                            if @_belowSibling = child._belowSibling
                                @_belowSibling._aboveSibling = @
                            child._belowSibling = @
                            break
                        unless nextChild
                            @_aboveSibling = null
                            @_belowSibling = child
                            child._aboveSibling = @

                if val < oldVal
                    prevChild = @_belowSibling
                    while child = prevChild
                        prevChild = child._belowSibling
                        if child._z < val or (child._z is val and isPreviousSibling(@, child))
                            if oldBelowSibling is child
                                break
                            @_belowSibling = child
                            aboveSibling = child._aboveSibling
                            if @_aboveSibling = child._aboveSibling
                                @_aboveSibling._belowSibling = @
                            child._aboveSibling = @
                            break
                        unless prevChild
                            @_belowSibling = null
                            @_aboveSibling = child
                            child._belowSibling = @

                # clean old siblings
                if oldBelowSibling and oldBelowSibling isnt @_belowSibling
                    oldBelowSibling._aboveSibling = oldAboveSibling
                if oldAboveSibling and oldAboveSibling isnt @_aboveSibling
                    oldAboveSibling._belowSibling = oldBelowSibling

                # new children
                if @_belowSibling
                    if children._bottomChild is @
                        children._bottomChild = oldAboveSibling
                else
                    children._bottomChild = @
                if @_aboveSibling
                    if children._topChild is @
                        children._topChild = oldBelowSibling
                else
                    children._topChild = @

                # implementation
                if oldAboveSibling isnt @_aboveSibling
                    insertItemInImpl @

                `//<development>`
                assert.isNot @_belowSibling, @
                assert.isNot @_belowSibling?._belowSibling, @
                assert.isNot @_aboveSibling, @
                assert.isNot @_aboveSibling?._aboveSibling, @
                if @_belowSibling
                    assert.is @_belowSibling._aboveSibling, @
                if @_aboveSibling
                    assert.is @_aboveSibling._belowSibling, @
                `//</development>`
                return

## *Float* Item::scale = `1`

## *Signal* Item::onScaleChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'scale'
            defaultValue: 1
            implementation: Impl.setItemScale
            developmentSetter: (val) ->
                assert.isFloat val, "Item.scale needs to be a float, but #{val} given"

## *Float* Item::rotation = `0`

```nml
Rectangle {
    width: 100
    height: 100
    color: 'red'
    rotation: Math.PI / 4
}
```

## *Signal* Item::onRotationChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'rotation'
            defaultValue: 0
            implementation: Impl.setItemRotation
            developmentSetter: (val) ->
                assert.isFloat val, "Item.rotation needs to be a float, but #{val} given"

## *Float* Item::opacity = `1`

## *Signal* Item::onOpacityChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'opacity'
            defaultValue: 1
            implementation: Impl.setItemOpacity
            developmentSetter: (val) ->
                assert.isFloat val, "Item.opacity needs to be a float, but #{val} given"

## *String* Item::linkUri = `''`

Points to the URI which will be used when user clicks on this item.

## *Signal* Item::onLinkUriChange(*String* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'linkUri'
            defaultValue: ''
            implementation: Impl.setItemLinkUri
            developmentSetter: (val) ->
                assert.isString val, "Item.linkUri needs to be a string, but #{val} given"

## Item::scaleInPoint(*Float* scale, *Float* pointX, *Float* pointY)

        scaleInPoint: (scale, pointX, pointY) ->
            oldScale = @scale

            # scale
            @scale = scale

            # move to point horizontal
            {width} = @
            widthChange = (width * scale - width * oldScale) / 2
            xOriginToChange = -2 * (pointX / width) + 1
            @x += xOriginToChange * widthChange

            # move to point vertical
            {height} = @
            heightChange = (height * scale - height * oldScale) / 2
            yOriginToChange = -2 * (pointY / height) + 1
            @y += yOriginToChange * heightChange

            return

## *Object* Item::getGlobalComputes()

Returns globally computed x, y, scale, rotation, visible and opacity.

        getGlobalComputes: ->
            m = new Matrix()
            {visible, opacity} = @

            chain = []
            item = @
            while item
                chain.push(item)

                visible and= item.visible
                opacity *= item.opacity
                item = item.parent

            for item in chain by -1
                originX = item.width / 2
                originY = item.height / 2

                m.translate(item.x + originX, item.y + originY)
                m.scale(item.scale)
                m.rotate(item.rotation)
                m.translate(-originX, -originY)

            mScale = m.getScale()
            mRotation = m.getRotation()

            m2 = new Matrix()
            m2.translate(-@width / 2, -@height / 2)
            m2.rotate(mRotation)
            m2.translate(@width * mScale / 2, @height * mScale / 2)

            mTranslate = m.getTranslate()
            m2Translate = m2.getTranslate()

            x: mTranslate.x + m2Translate.x
            y: mTranslate.y + m2Translate.y
            scale: mScale
            rotation: mRotation

        @createSpacing = require('./item/spacing') Renderer, Impl, itemUtils, Item
        @createAlignment = require('./item/alignment') Renderer, Impl, itemUtils, Item
        @createAnchors = require('./item/anchors') Renderer, Impl, itemUtils, Item
        @createLayout = require('./item/layout') Renderer, Impl, itemUtils, Item
        @createMargin = require('./item/margin') Renderer, Impl, itemUtils, Item
        @createPointer = require('./item/pointer') Renderer, Impl, itemUtils, Item
        @createKeys = require('./item/keys') Renderer, Impl, itemUtils, Item

## *Item.Anchors* Item::anchors

## *Signal* Item::onAnchorsChange(*String* property, *Array* oldValue)

        @createAnchors @

## *Item.Layout* Item::layout

## *Signal* Item::onLayoutChange(*String* property, *Any* oldValue)

        @createLayout @

## *Item.Pointer* Item::pointer

        @Pointer = @createPointer @

## *Item.Margin* Item::margin

## *Signal* Item::onMarginChange(*String* property, *Any* oldValue)

        @createMargin @

## *Item.Keys* Item::keys

        @Keys = @createKeys @

        Item

# Item

    'use strict'

    assert = require 'src/assert'
    utils = require 'src/utils'
    signal = require 'src/signal'
    List = require 'src/list'
    Matrix = require 'src/renderer/utils/Matrix'

    {isArray} = Array
    {emitSignal} = signal.Emitter

    assert = assert.scope 'Renderer.Item'

    module.exports = (Renderer, Impl, itemUtils) -> class Item extends itemUtils.Object
        @__name__ = 'Item'
        @__path__ = 'Renderer.Item'

        Document = require 'src/document'
        DocElement = Document.Element

## *Item* Item.New([*Object* options])

        @New = (opts) ->
            item = new Item
            itemUtils.Object.initialize item, opts
            item

## *Item* Item::constructor()

This is a base class for everything which is visible.

        constructor: ->
            assert.instanceOf @, Item

            super()
            @_parent = null
            @_children = null
            @_previousSibling = null
            @_nextSibling = null
            @_belowSibling = null
            @_aboveSibling = null
            @_width = 0
            @_height = 0
            @_x = 0
            @_y = 0
            @_z = 0
            @_visible = true
            @_clip = false
            @_scale = 1
            @_rotation = 0
            @_opacity = 1
            @_linkUri = ''
            @_anchors = null
            @_layout = null
            @_keys = null
            @_pointer = null
            @_margin = null
            @_classes = null
            @_query = ''
            @_node = null

### Custom properties

```nml
Item {
    id: main
    property currentLife: 0.8
    Text {
        text: "Life: " + main.currentLife
    }
}
```

### Custom signals

```nml
Item {
    signal onPlayerCollision
    onPlayerCollision(){
        // boom!
    }
}
```

## ReadOnly *String* Item::query

        utils.defineProperty @::, 'query', null, ->
            @_query
        , (val) ->
            if @_query is ''
                @_query = val
            return

## ReadOnly *Document.Element* Item::node

## *Signal* Item::onNodeChange(*Document.Element* oldValue)

```javascript
Text {
    text: this.node.props.value
}
```

```javascript
Text {
    onNodeChange: function(){
        var inputs = this.node.queryAll('input[type=string]');
    }
}
```

        itemUtils.defineProperty
            constructor: @
            name: 'node'
            defaultValue: null
            developmentSetter: (val) ->
                if val?
                    assert.instanceOf val, DocElement

## *Signal* Item::ready()

Called when the Item is ready, that is, all
properties have been set and it's ready to use.

```nml
Rectangle {
    width: 200
    height: 50
    color: 'green'
    Rectangle {
        width: parent.width / 2
        height: parent.height / 2
        color: 'yellow'
        onReady: function(){
            console.log(this.width, this.height);
            // 100, 25
        }
    }
}
```

        signal.Emitter.createSignal @, 'onReady'

## *Signal* Item::onAnimationFrame(*Integer* miliseconds)

        signal.Emitter.createSignal @, 'onAnimationFrame', do ->
            now = Date.now()
            items = []

            frame = ->
                oldNow = now
                now = Date.now()
                ms = now - oldNow

                for item in items
                    emitSignal item, 'onAnimationFrame', ms
                requestAnimationFrame frame

            requestAnimationFrame? frame

            (item) ->
                items.push item

## ReadOnly *String* Item::id

## *Object* Item::children

        utils.defineProperty @::, 'children', null, ->
            @_children ||= new ChildrenObject(@)
        , (val) ->
            assert.isArray val, "Item.children needs to be an array, but #{val} given"
            @clear()
            for item in val
                val.parent = @
            return

## *Signal* Item::onChildrenChange(*Item* added, *Item* removed)

        signal.Emitter.createSignal @, 'onChildrenChange'

        class ChildrenObject extends itemUtils.MutableDeepObject
            constructor: (ref) ->
                @_layout = null
                @_target = null
                @_firstChild = null
                @_lastChild = null
                @_bottomChild = null
                @_topChild = null
                @_length = 0
                super ref

### ReadOnly *Item* Item::children.firstChild

            utils.defineProperty @::, 'firstChild', null, ->
                @_firstChild
            , null

### ReadOnly *Item* Item::children.lastChild

            utils.defineProperty @::, 'lastChild', null, ->
                @_lastChild
            , null

### ReadOnly *Item* Item::children.bottomChild

            utils.defineProperty @::, 'bottomChild', null, ->
                @_bottomChild
            , null

### ReadOnly *Item* Item::children.topChild

            utils.defineProperty @::, 'topChild', null, ->
                @_topChild
            , null

### ReadOnly *Integer* Item::children.length

            utils.defineProperty @::, 'length', null, ->
                @_length
            , null

### *Item* Item::children.layout

Item used to position children items.
Can be e.g. *Flow*, *Grid* etc.

### *Signal* Item::children.onLayoutChange(*Item* oldValue)

            itemUtils.defineProperty
                constructor: @
                name: 'layout'
                defaultValue: null
                developmentSetter: (val) ->
                    if val?
                        assert.instanceOf val, Item, """
                            Item.children.layout needs to be an Item, but #{val} given
                        """
                setter: (_super) -> (val) ->
                    if @_layout?.effectItem
                        @_layout.parent = null
                        @_layout.effectItem = @_layout

                    _super.call @, val

                    if '_effectItem' of @_ref
                        @_ref.effectItem = if val then null else @_ref

                    if val?
                        ref = @_ref
                        setFakeParent val, ref, 0
                        if val.effectItem
                            val.effectItem = ref

                    return

### *Item* Item::children.target

A new child trying to be added into the item with the `children.target` defined
will be added into the `target` item.

### *Signal* Item::children.onTargetChange(*Item* oldValue)

            itemUtils.defineProperty
                constructor: @
                name: 'target'
                defaultValue: null
                developmentSetter: (val) ->
                    if val?
                        assert.instanceOf val, Item, """
                            Item.children.target needs to be an Item, but #{val} given
                        """

### *Item* Item::children.get(*Integer* index)

Returns an item with the given index.

            get: (val) ->
                assert.operator val, '>=', 0, """
                    Item.children.get index cannot be lower than zero, #{val} given
                """
                assert.operator val, '<', @length, """
                    Item.children.get index must be lower than children.length, \
                    #{val} given
                """

                if val < @length / 2
                    sibling = @firstChild
                    while val > 0
                        sibling = sibling.nextSibling
                        val--
                else
                    sibling = @lastChild
                    while val > 0
                        sibling = sibling.previousSibling
                        val--

                sibling

### *Integer* Item::children.index(*Item* value)

Returns an index of the given child in the children array.

            index: (val) ->
                if @has(val)
                    val.index
                else
                    -1

### *Boolean* Item::children.has(*Item* value)

Returns `true` if the given item is an item child.

            has: (val) ->
                @_ref is val._parent

### Item::children.clear()

Removes all children from the item.

            clear: ->
                while last = @last
                    last.parent = null
                return

## *Item* Item::parent = `null`

## *Signal* Item::onParentChange(*Item* oldParent)

        setFakeParent = (child, parent, index=-1) ->
            child.parent = null

            if index >= 0 and parent.children._length < index
                Impl.insertItemBefore.call child, parent.children[index]
            else
                Impl.setItemParent.call child, parent

            child._parent = parent
            emitSignal child, 'onParentChange', null
            return

        updateZSiblingsForAppendedItem = (item, z, newChildren) ->
            child = newChildren._topChild
            while child
                if child._z <= z
                    if item._aboveSibling = child._aboveSibling
                        item._aboveSibling._belowSibling = item
                    item._belowSibling = child
                    child._aboveSibling = item
                    return
                unless nextChild = child._belowSibling
                    item._aboveSibling = child
                    child._belowSibling = item
                    item._belowSibling = null
                    return
                child = nextChild
            return

        insertItemInImpl = (item) ->
            if aboveSibling = item._aboveSibling
                Impl.insertItemBefore.call item, aboveSibling
            else
                Impl.setItemParent.call item, item._parent
            return

        itemUtils.defineProperty
            constructor: @
            name: 'parent'
            defaultValue: null
            setter: (_super) -> (val = null) ->
                old = @_parent
                oldChildren = old?.children
                valChildren = val?.children

                if valChildren?._target
                    # detect whether target is a child of this item
                    containsItem = false
                    tmpItem = valChildren._target
                    while tmpItem
                        if tmpItem is @
                            containsItem = true
                            break
                        tmpItem = tmpItem._parent

                    unless containsItem
                        val = valChildren._target
                        valChildren = val.children

                if old is val
                    return

                assert.isNot @, val, "Item.parent cannot be set with context item, #{val} given"

                if pointer = @_pointer
                    pointer.hover = pointer.pressed = false

                if val isnt null
                    assert.instanceOf val, Item, """
                        Item.parent needs to be an Item or null, but #{val} given
                    """

                # old siblings
                oldPreviousSibling = @_previousSibling
                oldNextSibling = @_nextSibling
                if oldPreviousSibling isnt null
                    oldPreviousSibling._nextSibling = oldNextSibling
                if oldNextSibling isnt null
                    oldNextSibling._previousSibling = oldPreviousSibling

                # new siblings
                if val isnt null
                    if previousSibling = @_previousSibling = valChildren.lastChild
                        previousSibling._nextSibling = @
                else
                    @_previousSibling = null
                if oldNextSibling isnt null
                    @_nextSibling = null

                # children
                if oldChildren
                    oldChildren._length -= 1
                    if oldChildren.firstChild is @
                        oldChildren._firstChild = oldNextSibling
                    if oldChildren.lastChild is @
                        oldChildren._lastChild = oldPreviousSibling
                if valChildren
                    if ++valChildren._length is 1
                        valChildren._firstChild = @
                    valChildren._lastChild = @

                # old z-index siblings
                oldBelowSibling = @_belowSibling
                oldAboveSibling = @_aboveSibling
                if oldBelowSibling isnt null
                    oldBelowSibling._aboveSibling = oldAboveSibling
                if oldAboveSibling isnt null
                    oldAboveSibling._belowSibling = oldBelowSibling

                # new z-index siblings
                @_belowSibling = @_aboveSibling = null
                if valChildren
                    updateZSiblingsForAppendedItem @, @_z, valChildren

                # z-index children
                if oldChildren
                    unless oldAboveSibling
                        oldChildren._topChild = oldBelowSibling
                    unless oldBelowSibling
                        oldChildren._bottomChild = oldAboveSibling
                if valChildren
                    unless @_aboveSibling
                        valChildren._topChild = @
                    unless @_belowSibling
                        valChildren._bottomChild = @

                # parent
                @_parent = val
                insertItemInImpl @

                `//<development>`
                assert.is @nextSibling, null
                if val
                    assert.is val.children.lastChild, @
                    assert.isDefined val.children.firstChild
                    assert.isDefined val.children.lastChild
                    assert.isDefined val.children.topChild
                    assert.isDefined val.children.bottomChild
                if old and old.children.length is 0
                    assert.isNotDefined old.children.firstChild
                    assert.isNotDefined old.children.lastChild
                    assert.isNotDefined old.children.topChild
                    assert.isNotDefined old.children.bottomChild
                `//</development>`

                # signals
                if old isnt null
                    emitSignal old, 'onChildrenChange', null, @
                if val isnt null
                    emitSignal val, 'onChildrenChange', @, null

                emitSignal @, 'onParentChange', old

                if oldPreviousSibling isnt null
                    emitSignal oldPreviousSibling, 'onNextSiblingChange', @
                if oldNextSibling isnt null
                    emitSignal oldNextSibling, 'onPreviousSiblingChange', @

                if val isnt null or oldPreviousSibling isnt null
                    if previousSibling
                        emitSignal previousSibling, 'onNextSiblingChange', null
                    emitSignal @, 'onPreviousSiblingChange', oldPreviousSibling
                if oldNextSibling isnt null
                    emitSignal @, 'onNextSiblingChange', oldNextSibling

                return

## *Item* Item::previousSibling

        utils.defineProperty @::, 'previousSibling', null, ->
            @_previousSibling
        , (val = null) ->
            assert.isNot @, val, """
                Item.previousSibling cannot be set with context Item, #{val} given
            """

            if val is @_previousSibling
                return

            if val
                assert.instanceOf val, Item, """
                    Item.previousSibling must be an Item or null, but #{val} given
                """
                nextSibling = val._nextSibling
                if not nextSibling and val._parent isnt @_parent
                    @parent = val._parent
                else
                    @nextSibling = nextSibling
            else
                assert.isDefined @_parent, """
                    Cannot null Item.previousSibling when Item has no parent
                """
                @nextSibling = @_parent.children.firstChild

            assert.is @_previousSibling, val
            return

## *Signal* Item::onPreviousSiblingChange(*Item* oldValue)

        signal.Emitter.createSignal @, 'onPreviousSiblingChange'

## *Item* Item::nextSibling

        isNextSibling = (item, sibling) ->
            while item
                nextItem = item._nextSibling
                if nextItem is sibling
                    return true
                item = nextItem
            return false

        isPreviousSibling = (item, sibling) ->
            while item
                prevItem = item._previousSibling
                if prevItem is sibling
                    return true
                item = prevItem
            return false

        updateZSiblingsForInsertedItem = (item, nextSibling, z, newChildren) ->
            if nextSibling._z is z
                # simple case - the same z-index as in nextSibling
                if item._belowSibling = nextSibling._belowSibling
                    item._belowSibling._aboveSibling = item
                item._aboveSibling = nextSibling
                nextSibling._belowSibling = item
            else
                # hard case - different z-indexes
                nextChild = newChildren._bottomChild
                while child = nextChild
                    nextChild = child._aboveSibling
                    if child._z > z or (child._z is z and isNextSibling(item, child))
                        item._aboveSibling = child
                        if item._belowSibling = child._belowSibling
                            item._belowSibling._aboveSibling = item
                        child._belowSibling = item
                        break
                    unless nextChild
                        item._aboveSibling = null
                        item._belowSibling = child
                        child._aboveSibling = item
            return

        utils.defineProperty @::, 'nextSibling', null, ->
            @_nextSibling
        , (val = null) ->
            assert.isNot @, val, """
                Item.nextSibling cannot be set with context Item, #{val} given
            """
            if val
                assert.instanceOf val, Item, """
                    Item.nextSibling needs to be an Item or null, but #{val} given
                """
                assert.isDefined val._parent, """
                    Item.nextSibling value needs to have a parent, given #{val} has no parent
                """
            else
                assert.isDefined @_parent, """
                    Cannot null Item.nextSibling when Item has no parent
                """

            if val is @_nextSibling
                return

            oldParent = @_parent
            oldChildren = oldParent?._children
            oldPreviousSibling = @_previousSibling
            oldNextSibling = @_nextSibling

            if val
                newParent = val._parent
                newChildren = newParent._children
            else
                newParent = oldParent
                newChildren = oldChildren

            # new parent
            @_parent = newParent

            # current siblings
            oldPreviousSibling?._nextSibling = oldNextSibling
            oldNextSibling?._previousSibling = oldPreviousSibling

            # new siblings
            previousSibling = previousSiblingOldNextSibling = null
            nextSibling = nextSiblingOldPreviousSibling = null
            if val
                if previousSibling = val._previousSibling
                    previousSiblingOldNextSibling = previousSibling._nextSibling
                    previousSibling._nextSibling = @

                nextSibling = val
                nextSiblingOldPreviousSibling = nextSibling._previousSibling
                nextSibling._previousSibling = @
            else
                if previousSibling = newChildren.lastChild
                    previousSibling._nextSibling = @

            @_previousSibling = previousSibling
            @_nextSibling = nextSibling

            # children
            if oldChildren
                oldChildren._length -= 1
                unless oldPreviousSibling
                    oldChildren._firstChild = oldNextSibling
                unless oldNextSibling
                    oldChildren._lastChild = oldPreviousSibling
            newChildren._length += 1
            if newChildren.firstChild is val
                newChildren._firstChild = @
            unless val
                newChildren._lastChild = @

            # old z-index siblings
            oldBelowSibling = @_belowSibling
            oldAboveSibling = @_aboveSibling
            if oldBelowSibling isnt null
                oldBelowSibling._aboveSibling = oldAboveSibling
            if oldAboveSibling isnt null
                oldAboveSibling._belowSibling = oldBelowSibling

            # new z-index siblings
            @_belowSibling = @_aboveSibling = null
            if nextSibling
                updateZSiblingsForInsertedItem @, nextSibling, @_z, newChildren
            else
                updateZSiblingsForAppendedItem @, @_z, newChildren

            # z-index children
            if oldChildren
                unless oldAboveSibling
                    oldChildren._topChild = oldBelowSibling
                unless oldBelowSibling
                    oldChildren._bottomChild = oldAboveSibling
            unless @_aboveSibling
                newChildren._topChild = @
            unless @_belowSibling
                newChildren._bottomChild = @

            # implementation
            insertItemInImpl @

            `//<development>`
            assert.is @_nextSibling, val
            assert.is @_parent, newParent
            if val
                assert.is @_parent, val._parent
            if @_previousSibling
                assert.is @_previousSibling._nextSibling, @
            if @_nextSibling
                assert.is @_nextSibling._previousSibling, @
            if oldPreviousSibling
                assert.is oldPreviousSibling._nextSibling, oldNextSibling
            if oldNextSibling
                assert.is oldNextSibling._previousSibling, oldPreviousSibling
            `//</development>`

            # children signal
            if oldParent isnt newParent
                if oldParent
                    emitSignal oldParent, 'onChildrenChange', null, @
                emitSignal newParent, 'onChildrenChange', @, null
                emitSignal @, 'onParentChange', oldParent
            else
                emitSignal newParent, 'onChildrenChange', null, null

            # current siblings signals
            if oldPreviousSibling
                emitSignal oldPreviousSibling, 'onNextSiblingChange', @
            if oldNextSibling
                emitSignal oldNextSibling, 'onPreviousSiblingChange', @

            # new siblings signals
            emitSignal @, 'onPreviousSiblingChange', oldPreviousSibling
            if previousSibling
                emitSignal previousSibling, 'onNextSiblingChange', previousSiblingOldNextSibling
            emitSignal @, 'onNextSiblingChange', oldNextSibling
            if nextSibling
                emitSignal nextSibling, 'onPreviousSiblingChange', nextSiblingOldPreviousSibling

            return

## *Signal* Item::onNextSiblingChange(*Item* oldValue)

        signal.Emitter.createSignal @, 'onNextSiblingChange'

## ReadOnly *Item* Item::belowSibling

        utils.defineProperty @::, 'belowSibling', null, ->
            @_belowSibling
        , null

## ReadOnly *Item* Item::aboveSibling

        utils.defineProperty @::, 'aboveSibling', null, ->
            @_aboveSibling
        , null

## *Integer* Item::index

        utils.defineProperty @::, 'index', null, ->
            index = 0
            sibling = @
            while sibling = sibling.previousSibling
                index++
            index
        , (val) ->
            assert.isInteger val, "Item.index needs to be a integer, but #{val} given"
            assert.isDefined @_parent, """
                When setting Item.index, item needs to have a parent, #{@} has no parent
            """
            assert.operator val, '>=', 0, "Item.index needs to greater than zero, #{val} given"
            assert.operator val, '<=', @_parent._children.length, """
                Item.index needs to be lower than parent.children.length, #{val} given
            """

            {children} = @parent
            if val >= children.length
                @nextSibling = null
            else if (valItem = children.get(val)) isnt @
                @nextSibling = valItem

            return

## *Boolean* Item::visible = `true`

Determines whether an item is visible or not.

```nml
Item {
    width: 100
    height: 100
    pointer.onClick: function(){
        rect.visible = !rect.visible;
        text.text = rect.visible ? "Click to hide" : "Click to show";
    }
    Rectangle {
        id: rect
        anchors.fill: parent
        color: 'blue'
    }
    Text {
        id: text
        text: "Click to hide"
        anchors.centerIn: parent
    }
}
```

## *Signal* Item::onVisibleChange(*Boolean* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'visible'
            defaultValue: true
            implementation: Impl.setItemVisible
            developmentSetter: (val) ->
                assert.isBoolean val, "Item.visible needs to be a boolean, but #{val} given"

## *Boolean* Item::clip = `false`

## *Signal* Item::onClipChange(*Boolean* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'clip'
            defaultValue: false
            implementation: Impl.setItemClip
            developmentSetter: (val) ->
                assert.isBoolean val, "Item.clip needs to be a boolean, but #{val} given"

## *Float* Item::width = `0`

## *Signal* Item::onWidthChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'width'
            defaultValue: 0
            implementation: Impl.setItemWidth
            developmentSetter: (val) ->
                assert.isFloat val, "Item.width needs to be a float, but #{val} given"

## *Float* Item::height = `0`

## *Signal* Item::onHeightChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'height'
            defaultValue: 0
            implementation: Impl.setItemHeight
            developmentSetter: (val) ->
                assert.isFloat val, "Item.height needs to be a float, but #{val} given"

## *Float* Item::x = `0`

## *Signal* Item::onXChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'x'
            defaultValue: 0
            implementation: Impl.setItemX
            developmentSetter: (val) ->
                assert.isFloat val, "Item.x needs to be a float, but #{val} given"

## *Float* Item::y = `0`

## *Signal* Item::onYChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'y'
            defaultValue: 0
            implementation: Impl.setItemY
            developmentSetter: (val) ->
                assert.isFloat val, "Item.y needs to be a float, but #{val} given"

## *Float* Item::z = `0`

## *Signal* Item::onZChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'z'
            defaultValue: 0
            developmentSetter: (val) ->
                assert.isFloat val, "Item.z needs to be a float, but #{val} given"
            setter: (_super) -> (val) ->
                oldVal = @_z
                if oldVal is val
                    return

                _super.call @, val

                unless parent = @_parent
                    return
                children = parent._children
                oldAboveSibling = @_aboveSibling
                oldBelowSibling = @_belowSibling

                # new siblings
                if val > oldVal
                    nextChild = @_aboveSibling
                    while child = nextChild
                        nextChild = child._aboveSibling
                        if child._z > val or (child._z is val and isNextSibling(@, child))
                            if oldAboveSibling is child
                                break
                            @_aboveSibling = child
                            if @_belowSibling = child._belowSibling
                                @_belowSibling._aboveSibling = @
                            child._belowSibling = @
                            break
                        unless nextChild
                            @_aboveSibling = null
                            @_belowSibling = child
                            child._aboveSibling = @

                if val < oldVal
                    prevChild = @_belowSibling
                    while child = prevChild
                        prevChild = child._belowSibling
                        if child._z < val or (child._z is val and isPreviousSibling(@, child))
                            if oldBelowSibling is child
                                break
                            @_belowSibling = child
                            aboveSibling = child._aboveSibling
                            if @_aboveSibling = child._aboveSibling
                                @_aboveSibling._belowSibling = @
                            child._aboveSibling = @
                            break
                        unless prevChild
                            @_belowSibling = null
                            @_aboveSibling = child
                            child._belowSibling = @

                # clean old siblings
                if oldBelowSibling and oldBelowSibling isnt @_belowSibling
                    oldBelowSibling._aboveSibling = oldAboveSibling
                if oldAboveSibling and oldAboveSibling isnt @_aboveSibling
                    oldAboveSibling._belowSibling = oldBelowSibling

                # new children
                if @_belowSibling
                    if children._bottomChild is @
                        children._bottomChild = oldAboveSibling
                else
                    children._bottomChild = @
                if @_aboveSibling
                    if children._topChild is @
                        children._topChild = oldBelowSibling
                else
                    children._topChild = @

                # implementation
                if oldAboveSibling isnt @_aboveSibling
                    insertItemInImpl @

                `//<development>`
                assert.isNot @_belowSibling, @
                assert.isNot @_belowSibling?._belowSibling, @
                assert.isNot @_aboveSibling, @
                assert.isNot @_aboveSibling?._aboveSibling, @
                if @_belowSibling
                    assert.is @_belowSibling._aboveSibling, @
                if @_aboveSibling
                    assert.is @_aboveSibling._belowSibling, @
                `//</development>`
                return

## *Float* Item::scale = `1`

## *Signal* Item::onScaleChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'scale'
            defaultValue: 1
            implementation: Impl.setItemScale
            developmentSetter: (val) ->
                assert.isFloat val, "Item.scale needs to be a float, but #{val} given"

## *Float* Item::rotation = `0`

```nml
Rectangle {
    width: 100
    height: 100
    color: 'red'
    rotation: Math.PI / 4
}
```

## *Signal* Item::onRotationChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'rotation'
            defaultValue: 0
            implementation: Impl.setItemRotation
            developmentSetter: (val) ->
                assert.isFloat val, "Item.rotation needs to be a float, but #{val} given"

## *Float* Item::opacity = `1`

## *Signal* Item::onOpacityChange(*Float* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'opacity'
            defaultValue: 1
            implementation: Impl.setItemOpacity
            developmentSetter: (val) ->
                assert.isFloat val, "Item.opacity needs to be a float, but #{val} given"

## *String* Item::linkUri = `''`

Points to the URI which will be used when user clicks on this item.

## *Signal* Item::onLinkUriChange(*String* oldValue)

        itemUtils.defineProperty
            constructor: @
            name: 'linkUri'
            defaultValue: ''
            implementation: Impl.setItemLinkUri
            developmentSetter: (val) ->
                assert.isString val, "Item.linkUri needs to be a string, but #{val} given"

## Item::scaleInPoint(*Float* scale, *Float* pointX, *Float* pointY)

        scaleInPoint: (scale, pointX, pointY) ->
            oldScale = @scale

            # scale
            @scale *= scale

            # move to point horizontal
            {width} = @
            widthChange = (width * @scale - width * oldScale) / 2
            xOriginToChange = -2 * (pointX / width) + 1
            @x += xOriginToChange * widthChange

            # move to point vertical
            {height} = @
            heightChange = (height * @scale - height * oldScale) / 2
            yOriginToChange = -2 * (pointY / height) + 1
            @y += yOriginToChange * heightChange

            return

## *Object* Item::getGlobalComputes()

Returns globally computed x, y, scale, rotation, visible and opacity.

        getGlobalComputes: ->
            m = new Matrix()
            {visible, opacity} = @

            chain = []
            item = @
            while item
                chain.push(item)

                visible and= item.visible
                opacity *= item.opacity
                item = item.parent

            for item in chain by -1
                originX = item.width / 2
                originY = item.height / 2

                m.translate(item.x + originX, item.y + originY)
                m.scale(item.scale)
                m.rotate(item.rotation)
                m.translate(-originX, -originY)

            mScale = m.getScale()
            mRotation = m.getRotation()

            m2 = new Matrix()
            m2.translate(-@width / 2, -@height / 2)
            m2.rotate(mRotation)
            m2.translate(@width * mScale / 2, @height * mScale / 2)

            mTranslate = m.getTranslate()
            m2Translate = m2.getTranslate()

            x: mTranslate.x + m2Translate.x
            y: mTranslate.y + m2Translate.y
            scale: mScale
            rotation: mRotation

        @createSpacing = require('./item/spacing') Renderer, Impl, itemUtils, Item
        @createAlignment = require('./item/alignment') Renderer, Impl, itemUtils, Item
        @createAnchors = require('./item/anchors') Renderer, Impl, itemUtils, Item
        @createLayout = require('./item/layout') Renderer, Impl, itemUtils, Item
        @createMargin = require('./item/margin') Renderer, Impl, itemUtils, Item
        @createPointer = require('./item/pointer') Renderer, Impl, itemUtils, Item
        @createKeys = require('./item/keys') Renderer, Impl, itemUtils, Item

## *Item.Anchors* Item::anchors

## *Signal* Item::onAnchorsChange(*String* property, *Array* oldValue)

        @createAnchors @

## *Item.Layout* Item::layout

## *Signal* Item::onLayoutChange(*String* property, *Any* oldValue)

        @createLayout @

## *Item.Pointer* Item::pointer

        @Pointer = @createPointer @

## *Item.Margin* Item::margin

## *Signal* Item::onMarginChange(*String* property, *Any* oldValue)

        @createMargin @

## *Item.Keys* Item::keys

        @Keys = @createKeys @

        Item


adds note for refresh

adds note for refresh

# /api/Data Structures/Batman.Event/Batman.Property

`Batman.Property` extends `Batman.PropertyEvent` (which extends `Batman.Event`). `Batman.Property` is home to batman.js's powerful source tracking capabilities.

## Source Tracking by Batman.Property

When you define an `@accessor` on a `Batman.Object`, the accessor's `get` function is actually wrapped in source tracking by `Batman.Property`. Source tracking is implemented by a global source tracker stack, `SOURCE_TRACKER_STACK`, which is inside `Batman.Property`'s closure scope. The source tracker stack's members are arrays of source objects. For example:

```coffeescript
## SOURCE_TRACKER_STACK
[
  [<Batman.Property 1>, <Batman.Property 2>], # a set of sources
  [<Batman.Property 3>, <Batman.Property 4>], # another set of sources
  [ < ... > ]
]
```

Calling `get` signals to batman.js that a new source set may be added (via a variable inside `Batman.Property`'s closure scope, `SOURCE_TRACKER_STACK_VALID`). At the onset of a subsequent `get`:

- a new, empty source set is pushed to the global tracker if needed
- the property pushes itself to the current set of sources
- the `get` signals that a new source set may be added.

At the completion of each `get`:

- the last item of the global source tracker is popped off and stored as the `Property`'s `@sources`.

So, the global source tracker stack grows until a `get` doesn't depend on any other `Batman.Property` objects, then it starts to shrink. As it shrinks, each set of sources is attached to the `Property` which put it on the stack.

## ::constructor(base, key: String) : Property

Returns a new `Property` on `base` named `key`.

## ::.base

Returns `base` specified in the constructor. Represents the object the `Property` belongs to.

## ::.key

Returns the `key` specified in the constructor. Represents the name of property.

## @.defaultAccessor : Object

A JavaScript object implementing the [`Batman.Object.accessor`](/docs/api/batman.object_accessors.html) pattern by storing the value on the `Property` directly.

## @defaultAccessorForBase(base) : Object

Returns the `base`s `'defualtAccessor'` if present, otherwise returns `Batman.Property.defaultAccessor`.

## @accessorForBaseAndKey(base, key: String) :

Checks `base` and its ancestors for an accessor for `string` and returns it if found, otherwise returns `Batman.Property.defaultAccessor`.

## @forBaseAndKey(base, key: String) : Property

If `base.isObservable`, delegates to the object's `property` function to return a `Property` for key, otherwise returns a new `Batman.Keypath` for `base` and `key`.

## @wrapTrackingPrevention(block: Function) : Function

Creates a new function by wrapping `block` in _tracking prevention_ and returns it. When changes are wrapped in tracking prevention, they won't cause updates to other properties.

## @withoutTracking(block: Function)

Wraps `block` in tracking prevention and calls it.

## @registerSource(object)

If `object` is a `Batman.EventEmitter` or a `Batman.Property`, registers `object` in the current set in the global source tracker. Otherwise, it does nothing.

## @pushSourceTracker()

Adds a new set to the global source tracker.

## @popSourceTracker()

Gets the last set from the global source tracker.

## @pushDummySourceTracker()

Adds a dummy set to the global source tracker. Used for preventing source tracking.

## ::.cached[=false] : Boolean

Returns `true` if the value was retrieved from the accessor and the cache hasn't been busted.

## ::.value

Returns the value last retrieved from the accessor.

## ::.sources : Array

Returns the dependencies of the `Property`, set automatically by `updateSourcesFromTracker`. Each source maybe a `Batman.EventEmitter` (which responds to `on`/`off`), or a function (which is managed with `addHandler`/`removeHandler`).

## ::.isProperty[=true] : Boolean

Returns `true`.

## ::.isDead[=false] : Boolean

Returns `false` unless `die` was called on the `Property`.

## ::.isBatchingChanges[=false] : Boolean

If set to `true`, source changes won't cause the `Property` to `refresh` itself.

## ::registerAsMutableSource()

Registers the property as a source with `Batman.Property.registerSource`.

## ::isEqual(other: Property) : Boolean

Returns `true` if `other`'s `constructor`, `base`, and `key` match the `Property`'s `constructor`, `base`, and `key`.

## ::hashKey() : String

Returns a string representation of the `Property`.

## ::accessor() : Object

Returns the accessor object for the `Property` by using `Batman.Property.accessorForBaseAndKey` for the `Property`'s `base` and `key`.

## ::eachObserver(iterator: Function)

Calls `iterator(handler)` for each handler on the `Property` and each of its `Observable` ancestors.

## ::observers() : Array

Returns handlers from the `Property` and each of its `Observable` ancestors.

## ::hasObservers() : Boolean

Returns `true` if it has any observers.

## ::updateSourcesFromTracker()

Pops sources off the global tracker and replaces the `Property`'s current sources with the new ones, using `off`/`on` or `removeHandler`/`addHandler` as appropriate.

## ::getValue()

Registers itself as a mutable source, and if isn't cached,retrieves the value form the accessor and keeps other properties updated. Returns the retrieved value.

## ::isCachable() : Boolean

Returns `true` if the `Property.isFinal()` or if the `Property`'s accessor doesn't specify `cache: false`.

## ::isCached() : Boolean

Returns `true` if `isCachable()` and `cached` are `true`.

## ::isFinal() : Boolean

Returns `true` if the accessor specifies `final: true`.

## ::refresh()

Reloads the value from the accessor and, if the value has changed, fires itself with `value`, `previousValue`, `@key`. If the new value isn't undefined and `isFinal()` is true, it locks the value with `lockValue`.

_Note:_ For a `Batman.Keypath`, these two are not equivalent:

```
someObject.property('nestedObject.someNestedProperty').refresh()        # refreshes the Keypath on someObject
someObject.get('nestedObject').property('someNestedProperty').refresh() # refreshes the Property on nestedObject
```

## ::sourceChangeHandler() : Function

Returns the function to be called when any of the `Property`'s sources change. By default, this function implements several of `Batman.Property`'s features:

- the `Property` is refreshed when its sources change
- If `@isBatchingChanges`, the `Property` isn't refreshed
- If the `Property` `isIsolated`, it isn't refreshed
- Dead properties aren't updated

## ::valueFromAccessor()

Calls the accessor's `get` function with `base` and `key`, returning the result.

## ::setValue(value)

If the `Property`'s accessor has a `set` function, calls that function on `base` with `key` and `value`. This update is wrapped in source tracking, so other properties will be updated.

## ::unsetValue()

If the `Property`'s accessor has a `unset` function, calls that function on `base` with `key`. This update is wrapped in source tracking, so other properties will be updated.

## ::forget([handler: Function])

If `handler` is passed, removes `handler` from the `Property`'s handlers, otherwise removes all handlers from the `Property`.

## ::observeAndFire(handler: Function)

Adds `handler` to the `Property`'s handlers and fires it once. The handler will be called with `oldValue`, `newValue`, but for the first firing, `oldValue` and `newValue` are both the `Property`'s current value.

## ::observe(handler: Function) : Property

Adds `handler` to the `Property`'s handlers. The handler will be called with `oldValue`, `newValue`.

## ::observeOnce(handler: Function) : Property

Adds the `handler` to the `Property`'s handlers, but removes it after being fired once. The handler will be called with `oldValue`, `newValue`.

## ::lockValue()

Prevents changes to the `Property` by:
- removing handlers on the `Property`
- overriding `@getValue` to return the current value
- overriding `@setValue`, `@unsetValue`, `@refresh`, and `@observe` to be no-ops.

## ::die()

Kills the `Property` by removing handlers, unsetting itself, forgetting its `base` and setting `isDead = true`.

## ::isolate()

Isolates the `Property` from other properties. If the property is changed, it won't update its dependents until it's exposed. If its sources change, it won't refresh itself until it's exposed. `expose` must be called once for each time `isolate` is called, so if `isolate` is called twice, `expose` must be called twice.

## ::expose()

Exposes the `Property` to its dependents. If its sources have changed since it was isolated, it refreshes itself. Then, if its own value changed since it was isolated, it updates its dependents.

## ::isIsolated() : Boolean

Returns `true` if the `Property` if `isolate` has been called more times than `expose`.

# /api/Data Structures/Batman.Event/Batman.Property

`Batman.Property` extends `Batman.PropertyEvent` (which extends `Batman.Event`). `Batman.Property` is home to batman.js's powerful source tracking capabilities.

## Source Tracking by Batman.Property

When you define an `@accessor` on a `Batman.Object`, the accessor's `get` function is actually wrapped in source tracking by `Batman.Property`. Source tracking is implemented by a global source tracker stack, `SOURCE_TRACKER_STACK`, which is inside `Batman.Property`'s closure scope. The source tracker stack's members are arrays of source objects. For example:

```coffeescript
## SOURCE_TRACKER_STACK
[
  [<Batman.Property 1>, <Batman.Property 2>], # a set of sources
  [<Batman.Property 3>, <Batman.Property 4>], # another set of sources
  [ < ... > ]
]
```

Calling `get` signals to batman.js that a new source set may be added (via a variable inside `Batman.Property`'s closure scope, `SOURCE_TRACKER_STACK_VALID`). At the onset of a subsequent `get`:

- a new, empty source set is pushed to the global tracker if needed
- the property pushes itself to the current set of sources
- the `get` signals that a new source set may be added.

At the completion of each `get`:

- the last item of the global source tracker is popped off and stored as the `Property`'s `@sources`.

So, the global source tracker stack grows until a `get` doesn't depend on any other `Batman.Property` objects, then it starts to shrink. As it shrinks, each set of sources is attached to the `Property` which put it on the stack.

## ::constructor(base, key: String) : Property

Returns a new `Property` on `base` named `key`.

## ::.base

Returns `base` specified in the constructor. Represents the object the `Property` belongs to.

## ::.key

Returns the `key` specified in the constructor. Represents the name of property.

## @.defaultAccessor : Object

A JavaScript object implementing the [`Batman.Object.accessor`](/docs/api/batman.object_accessors.html) pattern by storing the value on the `Property` directly.

## @defaultAccessorForBase(base) : Object

Returns the `base`s `'defualtAccessor'` if present, otherwise returns `Batman.Property.defaultAccessor`.

## @accessorForBaseAndKey(base, key: String) :

Checks `base` and its ancestors for an accessor for `string` and returns it if found, otherwise returns `Batman.Property.defaultAccessor`.

## @forBaseAndKey(base, key: String) : Property

If `base.isObservable`, delegates to the object's `property` function to return a `Property` for key, otherwise returns a new `Batman.Keypath` for `base` and `key`.

## @wrapTrackingPrevention(block: Function) : Function

Creates a new function by wrapping `block` in _tracking prevention_ and returns it. When changes are wrapped in tracking prevention, they won't cause updates to other properties.

## @withoutTracking(block: Function)

Wraps `block` in tracking prevention and calls it.

## @registerSource(object)

If `object` is a `Batman.EventEmitter` or a `Batman.Property`, registers `object` in the current set in the global source tracker. Otherwise, it does nothing.

## @pushSourceTracker()

Adds a new set to the global source tracker.

## @popSourceTracker()

Gets the last set from the global source tracker.

## @pushDummySourceTracker()

Adds a dummy set to the global source tracker. Used for preventing source tracking.

## ::.cached[=false] : Boolean

Returns `true` if the value was retrieved from the accessor and the cache hasn't been busted.

## ::.value

Returns the value last retrieved from the accessor.

## ::.sources : Array

Returns the dependencies of the `Property`, set automatically by `updateSourcesFromTracker`. Each source maybe a `Batman.EventEmitter` (which responds to `on`/`off`), or a function (which is managed with `addHandler`/`removeHandler`).

## ::.isProperty[=true] : Boolean

Returns `true`.

## ::.isDead[=false] : Boolean

Returns `false` unless `die` was called on the `Property`.

## ::.isBatchingChanges[=false] : Boolean

If set to `true`, source changes won't cause the `Property` to `refresh` itself.

## ::registerAsMutableSource()

Registers the property as a source with `Batman.Property.registerSource`.

## ::isEqual(other: Property) : Boolean

Returns `true` if `other`'s `constructor`, `base`, and `key` match the `Property`'s `constructor`, `base`, and `key`.

## ::hashKey() : String

Returns a string representation of the `Property`.

## ::accessor() : Object

Returns the accessor object for the `Property` by using `Batman.Property.accessorForBaseAndKey` for the `Property`'s `base` and `key`.

## ::eachObserver(iterator: Function)

Calls `iterator(handler)` for each handler on the `Property` and each of its `Observable` ancestors.

## ::observers() : Array

Returns handlers from the `Property` and each of its `Observable` ancestors.

## ::hasObservers() : Boolean

Returns `true` if it has any observers.

## ::updateSourcesFromTracker()

Pops sources off the global tracker and replaces the `Property`'s current sources with the new ones, using `off`/`on` or `removeHandler`/`addHandler` as appropriate.

## ::getValue()

Registers itself as a mutable source, and if isn't cached,retrieves the value form the accessor and keeps other properties updated. Returns the retrieved value.

## ::isCachable() : Boolean

Returns `true` if the `Property.isFinal()` or if the `Property`'s accessor doesn't specify `cache: false`.

## ::isCached() : Boolean

Returns `true` if `isCachable()` and `cached` are `true`.

## ::isFinal() : Boolean

Returns `true` if the accessor specifies `final: true`.

## ::refresh()

Reloads the value from the accessor and, if the value has changed, fires itself with `value`, `previousValue`, `@key`. If the new value isn't undefined and `isFinal()` is true, it locks the value with `lockValue`.

## ::sourceChangeHandler() : Function

Returns the function to be called when any of the `Property`'s sources change. By default, this function implements several of `Batman.Property`'s features:

- the `Property` is refreshed when its sources change
- If `@isBatchingChanges`, the `Property` isn't refreshed
- If the `Property` `isIsolated`, it isn't refreshed
- Dead properties aren't updated

## ::valueFromAccessor()

Calls the accessor's `get` function with `base` and `key`, returning the result.

## ::setValue(value)

If the `Property`'s accessor has a `set` function, calls that function on `base` with `key` and `value`. This update is wrapped in source tracking, so other properties will be updated.

## ::unsetValue()

If the `Property`'s accessor has a `unset` function, calls that function on `base` with `key`. This update is wrapped in source tracking, so other properties will be updated.

## ::forget([handler: Function])

If `handler` is passed, removes `handler` from the `Property`'s handlers, otherwise removes all handlers from the `Property`.

## ::observeAndFire(handler: Function)

Adds `handler` to the `Property`'s handlers and fires it once. The handler will be called with `oldValue`, `newValue`, but for the first firing, `oldValue` and `newValue` are both the `Property`'s current value.

## ::observe(handler: Function) : Property

Adds `handler` to the `Property`'s handlers. The handler will be called with `oldValue`, `newValue`.

## ::observeOnce(handler: Function) : Property

Adds the `handler` to the `Property`'s handlers, but removes it after being fired once. The handler will be called with `oldValue`, `newValue`.

## ::lockValue()

Prevents changes to the `Property` by:
- removing handlers on the `Property`
- overriding `@getValue` to return the current value
- overriding `@setValue`, `@unsetValue`, `@refresh`, and `@observe` to be no-ops.

## ::die()

Kills the `Property` by removing handlers, unsetting itself, forgetting its `base` and setting `isDead = true`.

## ::isolate()

Isolates the `Property` from other properties. If the property is changed, it won't update its dependents until it's exposed. If its sources change, it won't refresh itself until it's exposed. `expose` must be called once for each time `isolate` is called, so if `isolate` is called twice, `expose` must be called twice.

## ::expose()

Exposes the `Property` to its dependents. If its sources have changed since it was isolated, it refreshes itself. Then, if its own value changed since it was isolated, it updates its dependents.

## ::isIsolated() : Boolean

Returns `true` if the `Property` if `isolate` has been called more times than `expose`.