/*
The following examples explain the common design pattern for OxJS UI widgets: an
inheritance model that is neither classical nor prototypal, but "parasitical" (a
term coined by <a
href="http://www.crockford.com/javascript/inheritance.html">Douglas
Crockford</a>). In a nutshell, "instances" are created by augmenting other
instances, but in addition to private members (`var foo`) and public members
(`that.bar`), they can have shared private members (`self.baz`). `self` cannot
be accessed from outside, but since `self` itself is an argument of the
"constructor", an instance can inherit its parent's `self` by passing its own
`self`.
*/
'use strict';


/*
Create our own namespace. Not required, but if you wanted to create a
module named `My`, this is how you would do it.
*/
Ox.My = {};

/*
<hr>
First, lets build the most basic Box widget. A widget is a "constructor"
function that takes two (optional) arguments, `options` and `self`, and returns
a widget object. It's not a constructor in JavaScript terms though: It doesn't
have to be called with `new`, and doesn't return an `instanceof` anything. It
just enhances another widget object and returns it.
*/
Ox.My.Box = function(options, self) {

    /*
    This is how every widget "constructor" begins. `self` is the widget's shared
    private object.
    */
    self = self || {};
    /*
    `that` is the widget itself, its public object, or, in JavaScript terms, its
    `this`. Every widget "inherits" from another widget by simple assignment.
    All public properties of the "super" widget, i.e. all properties of its
    `that`, will be present on our own `that`. In this case, we use Ox.Element,
    the "root" widget at the end of the inheritance chain, and pass an empty
    options object. But we always pass our own `self`, which means that any
    property that Ox.Element (or any other widget in the inheritance chain) adds
    to `self` will be present on our own `self`.
    */
    var that = Ox.Element({}, self)
        /*
        Then we call the public `defaults`, `options` and `update` methods of
        Ox.Element. `defaults` assigns the defaults object to `self.defaults`
        and copies it to `self.options`, `options` extends `self.options` with
        the options object, and `update` adds one or more callbacks that are
        invoked whenever, by way of calling the `options` method, a property of
        `self.options` is modified or added.
        */
        .defaults({
            color: [128, 128, 128],
            size: [128, 128]
        })
        .options(options || {})
        .update({
            color: setColor,
            size: setSize
        })
        /*
        `addClass` is a jQuery method. In fact, Ox.Element (and any widget
        derived from it) provides, on its prototype, all methods of a jQuery
        `$('<div>')`. Chaining works too: If you have `var $d = $('<div>'), $e =
        Ox.Element();`, then `$d.appendTo($e)` returns `$d`, and `$e.append($d)`
        returns `$e`. If you type Ox.Element() in the console, you will get
        something like `[<div class="OxElement"></div>]`. Any widget's `0`
        property is an actual DOM element, and in case you ever need the
        jQuery-wrapped element &mdash; that's the widget's `$element` property.

        The purpose of the `OxMyBox` class is just to allow us to add CSS
        declarations in an external style sheet. In this case, `.css({float:
        'left'})` would do the same thing.
        */
        .addClass('OxMyBox');

    /*
    The second part of the "constructor" function can be thought of as the
    "initializer", and contains everything needed to set up the "instance". In
    this case, we just define a minimum and maximum size and then set the
    widget's color and size.
    
    We could have used `var minSize` and `var maxSize` here, but by using `self`
    for private variables that we want to be accessible across all the widget's
    methods, we can be sure that inside such methods, any local `var` is
    actually local to the method.
    */
    self.minSize = 1;
    self.maxSize = 256;

    setColor();
    setSize();

    /*
    Third, we declare the widget's private methods. These are just function
    declarations, hoisted to the top of the "constructor".
    */
    function setColor() {
        that.css({
            backgroundColor: 'rgb(' + self.options.color.join(', ') + ')',
        });
    }

    function setSize() {
        /*
        Before setting the size, we make sure the value is between `minSize` and
        `maxSize`.
        */
        self.options.size = self.options.size.map(function(value) {
            return Ox.limit(value, self.minSize, self.maxSize);
        });
        that.css({
            width: self.options.size[0] + 'px',
            height: self.options.size[1] + 'px'
        });
    }

    /*
    Next, we define the widgets public methods, as properties of `that`. (Note
    that unlike private methods, they are not hoisted.)
    */
    that.displayText = function(text) {
        /*
        As there isn't much to do yet, this method just displays some text.
        Here, `.addClass('OxMyText')` is equivalent to `.css({padding: '4px'})`.
        */
        that.empty();
        text && that.append($('<div>').addClass('OxMyText').html(text));
        /*
        Public methods should return `that`, for chaining.
        */
        return that;
    };

    /*
    And finally, at the very end of the "constructor", we return `that`. And
    that's it.
    */
    return that;
    
};

/*
<hr>
Now we can "subclass" our Box. Let's build one that can have its color inverted.
*/
Ox.My.InvertibleBox = function(options, self) { 

    self = self || {};
    /*
    We no longer inherit from Ox.Element, but from `Ox.My.Box`.
    We could have written
    <pre>
    var that = Ox.My.Box({}, self)
        .defaults({
            color: [128, 128, 128],
            inverted: false,
            size: [128, 128]
        })
        .options(options || ())
        .update({
            ...
        })
    </pre>
    &mdash; but why repeat the defaults of `Ox.My.Box` if we can simply extend
    them. (Just like `options()` returns all options of a widget, `defaults()`
    returns all its defaults.)
    */
    var that = Ox.My.Box({}, self);
    that.defaults(Ox.extend(that.defaults(), {
            inverted: false
        }))
        .options(options || {})
        /*
        Again, we add handlers that run when the widget's options are updated.
        The original handlers of `Ox.My.Box` will run next, so we just add the
        ones we need. We leave out `size`, so when the `size` option changes,
        we'll get the original behavior.
        */
        .update({
            color: setColor,
            inverted: setColor
        })
        /*
        The same as `.css({cursor: 'pointer'})`.
        */
        .addClass('OxMyInvertibleBox')
        /*
        Ox.Element and its descendants provide a number of public methods
        (`bindEvent`, `bindEventOnce`, `triggerEvent` and `unbindEvent`) that
        allow widgets to communicate via custom events. Here, we add a handler
        for Ox.Element's `doubleclick` event. If we just wanted to handle a
        `click` event, we could also use jQuery here:
        <pre>
        .on({
            click: function() {
                that.invert();
            }
        })
        </pre>
        */
        .bindEvent({
            doubleclick: function() {
                that.invert();
            }
        });

    /*
    The idea is that our widget's inverted state is separate from its color. If
    the inverted option is set, then the color option stays the same, but has
    the inverse effect. This means that when initializing the widget, we have
    to call our custom `setColor` method if `self.options.inverted` is `true`.
    */
    self.options.inverted && setColor();

    /*
    When `setColor` is invoked as an update handler, returning `false` signals
    that no other handler should run. Otherwise, the original handler of
    `Ox.My.Box` would run next, and revert any inversion we might have done
    here.
    */
    function setColor() {
        that.css({backgroundColor: 'rgb(' + (
            self.options.inverted ? self.options.color.map(function(value) {
                return 255 - value;
            }) : self.options.color
        ).join(', ') + ')'});
        return false;
    }

    /*
    The public `invert` method is added as a convenience for the users of our
    widget, so that when they want to toggle its inverted state, they don't have
    to write
    <pre>
    $widget.options({
        inverted: !$widget.options('inverted')
    });
    </pre>
    all the time.
    
    Also, we trigger an `invert` event, that anyone can bind to via
    <pre>
    $widget.bindEvent({
        invert: function() { ... }
    });
    </pre>
    */
    that.invert = function() {
        that.options({inverted: !self.options.inverted});
        that.triggerEvent('invert');
        return that;
    };

    /*
    And again, we return `that`.
    */
    return that;

};

/*
<hr>
Now it's time for something more funky: A MetaBox &mdash; that is, a box of
boxes.
*/
Ox.My.MetaBox = function(options, self) {

    /*
    This time, we inherit from `Ox.My.InvertibleBox`. The one thing that's
    different though is the `color` option: It is no longer a single value, but
    an array of array of values. That's how the boxes inside out meta-box are
    specified. The following would create a grid of boxes with two rows and
    three columns:
    <pre>
    Ox.My.MetaBox({
        color: [
            [[255, 0, 0], [255, 255, 0], [0, 255, 0]],
            [[0, 255, 255], [0, 255, 0], [255, 0, 255]]
        ]
    });
    </pre>
    */
    self = self || {};
    var that = Ox.My.InvertibleBox({}, self)
        .options(options || {})
        .update({color: setColor});

    /*
    But we keep the default color of `Ox.My.InvertibleBox` (`[128, 128, 128]`)
    as our own default color, and only here check if the color option is a
    single value. In that case, we convert it to an array of one row and one
    column. This way, whenever someone accidentally passes a single color value,
    our MetaBox can handle it.
    */
    if (Ox.isNumber(self.options.color[0])) {
        self.options.color = [[self.options.color]];
    }

    /*
    `self.sizes` holds the width of each column and the height of each row.
    `self.options.color.length` is the number of rows,
    `self.options.color[0].length` the number of columns, and Ox.splitInt(a, b)
    "splits" an integer `a` into an array of `b` integers that sum up to `a`.
    (We don't want fractional pixel sizes.)
    */
    self.sizes = [
        Ox.splitInt(self.options.size[0], self.options.color[0].length),
        Ox.splitInt(self.options.size[1], self.options.color.length)
    ];

    /*
    `self.$boxes` are the actual boxes. We use `Ox.My.InvertibleBox`, but
    remove their `doubleclick` handlers, since our meta-box already has one. 
    (`unbindEvent(event)` removes all handlers, `unbindEvent(event, handler)`
    removes a specific one.) Then we simply append each box to the meta-box.
    */
    self.$boxes = self.options.color.map(function(array, y) {
        return array.map(function(color, x) {
            return Ox.My.InvertibleBox({
                    color: color,
                    size: [self.sizes[0][x], self.sizes[1][y]]
                })
                .unbindEvent('doubleclick')
                .appendTo(that);
        });
    });

    /*
    To set the color of a meta-box means to set the color of each box.
    */
    function setColor() {
        self.$boxes.forEach(function(array, y) {
            array.forEach(function($box, x) {
                $box.options({color: self.options.color[y][x]});
            });
        });
    }

    /*
    This is the rare case of a shared private method. Its purpose will become
    apparent a bit later. Otherwise, we could just have made a private function,
    or an anonymous function in the loop below.
    */
    self.invertBox = function($box) {
        $box.invert();
    };

    /*
    Here, we override the public `invert` method of `Ox.My.InvertibleBox`. When
    inverting an `Ox.My.MetaBox`, we have to invert each of its boxes. (If we
    wanted to keep the original method around, we could store it as
    `that.superInvert` before.)
    */
    that.invert = function() {
        self.$boxes.forEach(function(array) {
            array.forEach(self.invertBox);
        });
        that.triggerEvent('invert');
        return that;
    };

    /*
    And that's all it takes to make a meta-box.
    */
    return that;

};

/*
<hr>
The next widget is a peculiar type of meta-box. A PixelBox has only one color,
but this color will be split into a red box, a green box and a blue box.
*/
Ox.My.PixelBox = function(options, self) {

    self = self || {};
    /*
    ...
    */
    self.options = Ox.extend(Ox.My.Box().defaults(), options || {});
    var that = Ox.My.MetaBox(Ox.extend(self.options, {
            color: getColor()
        }), self)
        .update({
            color: setColor
        });

    /*
    This is how the color gets split up into a red box, a green box and a blue
    box.
    */
    function getColor() {
        return [[
            [self.options.color[0], 0, 0],
            [0, self.options.color[1], 0],
            [0, 0, self.options.color[2]]
        ]];
    }

    /*
    ...
    */
    function setColor() {
        if (Ox.isNumber(self.options.color[0])) {
            that.options({color: getColor()});
            return false;
        }
    }

    /*
    Inverting a PixelBox is different from inverting a MetaBox, since we only
    want to invert one color channel per box. This is where the shared private
    `invertBox` method of `Ox.My.MetaBox` comes into play. Since we share the
    same `self`, we can simply override it. (Alternatively, we could have added
    an `invertBox` option to `Ox.My.MetaBox`, but overriding a shared private
    method is much more elegant than cluttering the public API of
    `Ox.My.MetaBox` with such an option.)
    */
    self.invertBox = function($box, x) {
        $box.options({
            color: $box.options('color').map(function(value, i) {
                return i == x ? 255 - value : value
            })
        });
    };

    return that;

};

/*
<hr>
And finally &mdash; a meta-meta-box! An ImageBox takes an image and, for each
pixel, displays a PixelBox.
*/
Ox.My.ImageBox = function(options, self) {

    self = self || {};
    /*
    Loading the image is asynchronous, but we want to display a box immediately.
    So we just subclass `Ox.My.Box`. Also, this seems to be a good use case for
    its `displayText` method.
    */
    var that = Ox.My.Box({}, self).displayText('Loading...');
    that.defaults(Ox.extend(that.defaults(), {
            image: null
        }))
        .options(options || {});

    /*
    Ox.Image takes a URI and passes an image object to its callback function.
    */
    self.options.image && Ox.Image(self.options.image, function(image) {
        var size = image.getSize();
        size = [size.width, size.height];
        /*
        Again, we have to compute the width of each column and the height of
        each row.
        */
        self.sizes = size.map(function(value, index) {
            return Ox.splitInt(self.options.size[index], value);
        });
        /*
        Remove the 'Loading...' message.
        */
        that.displayText();
        /*
        For each pixel ...
        */
        self.$boxes = Ox.range(size[1]).map(function(y) {
            return Ox.range(size[0]).map(function(x) {
                /*
                ... create a PixelBox ...
                */
                return Ox.My.PixelBox({
                        /*
                        (`image.pixel` returns RGBA, so discard alpha)
                        */
                        color: image.pixel(x, y).slice(0, 3),
                        size: [self.sizes[0][x], self.sizes[1][y]]
                    })
                    /*
                    ... remove its `doubleclick` handler ...
                    */
                    .unbindEvent('doubleclick')
                    /*
                    ... and append it to the ImageBox.
                    */
                    .appendTo(that);
            });
        });
    });

    /*
    We've inherited from `Ox.My.Box`, so we don't have an `invert` method yet.
    This is how we can borrow the one from `Ox.My.MetaBox`. We're passing our
    own `self`, so the `self.$boxes` that the `invert` method of `Ox.My.MetaBox`
    operates on will be the PixelBoxes that we are assinging in the asynchronous
    callback above.

    This is somewhat analogous to the
    <pre>
    someOtherObject.method.apply(this, args)
    </pre>
    pattern that is common in JavaScript.

    Note that we have to pass `self.options` too, otherwise our own size would
    get overwritten by the MetaBox default size.
    */
    that.invert = Ox.My.MetaBox(self.options, self).invert;

    /*
    But wait &mdash; where's our `doubleclick` handler?
    */
    return that;

};

/*
<hr>
This one is left as an exercise to the reader ;)
*/
Ox.My.VideoBox = function(options, self) {
    
};

/*
<hr>
Load the UI and Image modules.
*/
Ox.load(['Image', 'UI'], function() {
    var h = Ox.random(360), s = 1, l = 0.5;
    window.My = {};
    My.$backgroundBox = Ox.My.Box({
            size: [256, 256]
        })
        .append(
            My.$box = Ox.My.Box({
                color: Ox.rgb(h, s, l)
            }),
            My.$invertibleBox = Ox.My.InvertibleBox({
                color: Ox.rgb(h + 120, s, l)
            }),
            My.$metaBox = Ox.My.MetaBox({
                color: Ox.range(2).map(function(y) {
                    return Ox.range(3).map(function(x) {
                        return Ox.rgb(h + x * 60 + y * 180, s, l);
                    });
                })
            }),
            My.$pixelBox = Ox.My.PixelBox({
                color: Ox.rgb(h + 120, s, l)
            })
        )
        .appendTo(Ox.$body);
    My.$imageBox = Ox.My.ImageBox({
            image: 'png/pandora32.png',
            size: [256, 256]
        })
        .appendTo(Ox.$body);
    Ox.forEach(My, function($element, name) {
        $element.bindEvent({
            invert: function() {
                My.$box.displayText(name[1].toUpperCase() + name.slice(2));
            }
        })
    });
});