sideshow 0.4.1

data/src/general/polling.js

@@ -0,0 +1,151 @@
+    /**
+    Controls the polling functions needed by Sideshow
+
+    @class Polling
+    @static
+    **/
+    var Polling = {};
+
+    /**
+    The polling functions queue
+
+    @@field queue
+    @type Object
+    @static
+    **/
+    Polling.queue = [];
+
+    /**
+    A flag that controls if the polling is locked
+
+    @@field lock
+    @type boolean
+    @static
+    **/
+    Polling.lock = false;
+
+    /**
+    Pushes a polling function in the queue
+
+    @method enqueue
+    @static
+    **/
+    Polling.enqueue = function() {
+        var firstArg = arguments[0];
+        var fn;
+        var name = "";
+
+        if(typeof firstArg == "function")
+            fn = firstArg;
+        else{
+            name = arguments[0];
+            fn = arguments[1];
+        } 
+
+        if (this.getFunctionIndex(fn) < 0
+            && (name === "" || this.getFunctionIndex(name) < 0)) {
+            this.queue.push({ name: name, fn: fn, enabled: true });
+        } else
+            throw new SSException("301", "The function is already in the polling queue.");
+    };
+
+    /**
+    Removes a polling function from the queue
+
+    @method dequeue
+    @static
+    **/
+    Polling.dequeue = function() {
+        this.queue.splice(this.getFunctionIndex(arguments[0]), 1);
+    };
+
+    /**
+    Enables an specific polling function
+
+    @method enable
+    @static
+    **/
+    Polling.enable = function(){
+        this.queue[this.getFunctionIndex(arguments[0])].enabled = true;
+    }
+
+    /**
+    Disables an specific polling function, but preserving it in the polling queue 
+
+    @method disable
+    @static
+    **/
+    Polling.disable = function(){
+        this.queue[this.getFunctionIndex(arguments[0])].enabled = false;
+    }
+
+    /**
+    Gets the position of a polling function in the queue based on its name or the function itself
+
+    @method getFunctionIndex
+    @static
+    **/
+    Polling.getFunctionIndex = function(){
+        var firstArg = arguments[0];
+
+        if(typeof firstArg == "function")
+            return this.queue.map(function(p){ return p.fn; }).indexOf(firstArg);
+        else if(typeof firstArg == "string")
+            return this.queue.map(function(p){ return p.name; }).indexOf(firstArg);
+
+        throw new SSException("302", "Invalid argument for getFunctionIndex method. Expected a string (the polling function name) or a function (the polling function itself).");
+    }
+
+    /**
+    Unlocks the polling and starts the checking process
+
+    @method start
+    @static
+    **/
+    Polling.start = function() {
+        this.lock = false;
+        this.doPolling();
+    };
+
+    /**
+    Stops the polling process
+
+    @method stop
+    @static
+    **/
+    Polling.stop = function() {
+        this.lock = true;
+    };
+
+    /**
+    Clear the polling queue
+
+    @method clear
+    @static
+    **/
+    Polling.clear = function() {
+        var lock = this.lock;
+
+        this.lock = true;
+        this.queue = [];
+        this.lock = lock;
+    };
+
+    /**
+    Starts the polling process  
+
+    @method doPolling
+    @static
+    **/
+    Polling.doPolling = function() {
+        if (!this.lock) {
+            //Using timeout to avoid the queue to not complete in a cycle
+            setTimeout(function() {
+                for (var fn = 0; fn < Polling.queue.length; fn++) {
+                    var pollingFunction = Polling.queue[fn];
+                    pollingFunction.enabled && pollingFunction.fn();
+                }
+                Polling.doPolling();
+            }, pollingDuration);
+        }
+    };

data/src/general/screen.js

@@ -0,0 +1,39 @@
+	/**
+	Represents the current available area in the browser
+
+	@class Screen
+	@static
+	**/
+	var Screen = {};
+
+	/**
+	Object holding dimension information for the screen
+
+	@@field
+	@static
+	@type Object
+	**/
+	Screen.dimension = {};
+
+	/**
+	Checks if the screen dimension information has changed
+
+	@method hasChanged
+	@static
+	@return boolean
+	**/
+	Screen.hasChanged = function() {
+	    return ($window.width() !== this.dimension.width) ||
+	        ($window.height() !== this.dimension.height);
+	};
+
+	/**
+	Updates the dimension information for the screen 
+
+	@method updateInfo
+	@static
+	**/
+	Screen.updateInfo = function() {
+	    this.dimension.width = $window.width();
+	    this.dimension.height = $window.height();
+	};  

data/src/general/utility_functions.js

@@ -0,0 +1,88 @@
+    /**
+    Shows a warning  in a pre-defined format
+
+    @@function showWarning
+    @param {String} code                                  The warning code
+    @param {String} message                               The warning message
+    **/
+    function showWarning(code, message) {
+        console.warn("[SIDESHOW_W#" + ("00000000" + code).substr(-8) + "] " + message);
+    }
+
+    /**
+    Parses a string in the format "#px" in a number
+
+    @@function parsePxValue
+    @param {String} value                                 A value with/without a px unit
+    @return Number                                        The number value without unit 
+    **/
+    function parsePxValue(value) {
+        if (value.constructor !== String) return value;
+        var br = value === "" ? "0" : value;
+        return +br.replace("px", "");
+    }
+
+    /**
+    Gets a string from the dictionary in the current language
+
+    @@function getString
+    @param {Object} stringKeyValuePair                    A string key-value pair in dictionary
+    @return String                                        The string value in the current language
+    **/
+    function getString(stringKeyValuePair) {
+        if (!(SS.config.language in stringKeyValuePair)) {
+            showWarning("2001", "String not found for the selected language, getting the first available.");
+            return stringKeyValuePair[Object.keys(stringKeyValuePair)[0]];
+        }
+
+        return stringKeyValuePair[SS.config.language];
+    }
+
+    /**
+    Registers hotkeys to be used when running Sideshow
+
+    @@function registerInnerHotkeys
+    **/
+    function registerInnerHotkeys() {
+        $document.keyup(innerHotkeysListener);
+    }
+
+    /**
+    Unregisters hotkeys used when running Sideshow
+
+    @@function Unregisters
+    **/
+    function unregisterInnerHotkeys() {
+        $document.unbind("keyup", innerHotkeysListener);
+    }
+
+    function innerHotkeysListener(e) {
+        //Esc or F1
+        if (e.keyCode == 27 || e.keyCode == 112) SS.close();
+    }
+
+    /**
+    Registers global hotkeys
+
+    @@function registerGlobalHotkeys
+    **/
+    function registerGlobalHotkeys() {
+        $document.keyup(function(e) {
+            //F2
+            if (e.keyCode == 113) {
+                if (e.shiftKey) SS.start({
+                    listAll: true
+                });
+                else SS.start();
+            }
+        });
+    }
+
+    /**
+    Removes nodes created by Sideshow (except mask, which remains due to performance reasons when recalling Sideshow)
+
+    @@function removeDOMGarbage
+    **/
+    function removeDOMGarbage() {
+        $("[class*=\"sideshow\"]").not(".sideshow-mask-part, .sideshow-mask-corner-part, .sideshow-subject-mask").remove();
+    }

data/src/general/variables.js

@@ -0,0 +1,42 @@
+    var globalObjectName = "Sideshow",
+        $window,
+        $body,
+        $document,
+        pollingDuration = 150,
+        longAnimationDuration = 600,
+
+        /** 
+        The main class for Sideshow
+
+        @class SS 
+        @static
+        **/
+        SS = {
+            /**
+            The current Sideshow version
+
+            @property VERSION
+            @type String
+            **/
+            get VERSION() {
+                return "0.4.1";
+            }
+        },
+
+        controlVariables = [],
+        flags = {
+            lockMaskUpdate: false,
+            changingStep: false,
+            skippingStep: false,
+            running: false
+        },
+        wizards = [],
+        currentWizard,
+
+        /**
+        Possible statuses for an animation
+
+        @@enum AnimationStatus
+        **/
+        AnimationStatus = jazz.Enum("VISIBLE", "FADING_IN", "FADING_OUT", "NOT_DISPLAYED", "NOT_RENDERED", "TRANSPARENT");
+

data/src/interface_itens/fadable_item.js

@@ -0,0 +1,55 @@
+    /**
+    A visual item which holds fading in and out capabilities
+
+    @class FadableItem
+    @@abstract
+    @extends HidableItem
+    **/
+    var FadableItem = jazz.Class().extending(HidableItem).abstract;
+
+    /**
+    Does a fade in transition for the visual item
+
+    @method fadeIn
+    **/
+    FadableItem.method("fadeIn", function(callback, linearTimingFunction) {
+        var item = this;
+        item.status = AnimationStatus.FADING_IN;
+
+        if (!item.$el) this.render();
+        if (linearTimingFunction) item.$el.css("animation-timing-function", "linear");
+        item.$el.removeClass("sideshow-hidden");
+
+        //Needed hack to get CSS transition to work properly
+        setTimeout(function() {
+            item.$el.removeClass("sideshow-invisible");
+
+            setTimeout(function() {
+                item.status = AnimationStatus.VISIBLE;
+                if (linearTimingFunction) item.$el.css("animation-timing-function", "ease");
+                if (callback) callback();
+            }, longAnimationDuration);
+        }, 20); //<-- Yeap, I'm really scheduling a timeout for 20 milliseconds... this is a dirty trick =)
+    });
+
+    /**
+    Does a fade out transition for the visual item
+
+    @method fadeOut
+    **/
+    FadableItem.method("fadeOut", function(callback, linearTimingFunction) {
+        var item = this;
+        if (item.status != AnimationStatus.NOT_RENDERED) {
+            item.status = AnimationStatus.FADING_OUT;
+
+            if (linearTimingFunction) item.$el.css("animation-timing-function", "linear");
+            item.$el.addClass("sideshow-invisible");
+
+            setTimeout(function() {
+                item.$el.addClass("sideshow-hidden");
+                item.status = AnimationStatus.NOT_DISPLAYED;
+                if (linearTimingFunction) item.$el.css("animation-timing-function", "ease");
+                if (callback) callback();
+            }, longAnimationDuration);
+        }
+    });

data/src/interface_itens/hidable_item.js

@@ -0,0 +1,32 @@
+	/**
+	A visual item which can be shown and hidden
+
+	@class HidableItem
+	@@abstract
+	@extends VisualItem
+	**/
+	var HidableItem = jazz.Class().extending(VisualItem).abstract;
+
+	/**
+	Shows the visual item
+
+	@method show
+	@param {boolean} displayButKeepTransparent            The item will hold space but keep invisible
+	**/
+	HidableItem.method("show", function(displayButKeepTransparent) {
+	    if (!this.$el) this.render();
+	    if (!displayButKeepTransparent) this.$el.removeClass("sideshow-invisible");
+	    this.$el.removeClass("sideshow-hidden");
+	    this.status = AnimationStatus.VISIBLE;
+	});
+
+	/**
+	Hides the visual item
+
+	@method hide
+	**/
+	HidableItem.method("hide", function(keepHoldingSpace) {
+	    if (!keepHoldingSpace) this.$el.addClass("sideshow-hidden");
+	    this.$el.addClass("sideshow-invisible");
+	    this.status = AnimationStatus.NOT_DISPLAYED;
+	});

data/src/interface_itens/visual_item.js

@@ -0,0 +1,42 @@
+	/**
+	A visual item 
+
+	@class VisualItem
+	@@abstract
+	**/
+	var VisualItem = jazz.Class().abstract;
+
+	/**
+	The jQuery wrapped DOM element for the visual item
+
+	@@field $el
+	@type Object 
+	**/
+	VisualItem.field("$el");
+
+	/**
+	The jQuery wrapped DOM element for the visual item
+
+	@@field $el
+	@type AnimationStatus 
+	**/
+	VisualItem.field("status", AnimationStatus.NOT_RENDERED);
+
+	/**
+	Renders the item's DOM object
+
+	@method render
+	**/
+	VisualItem.method("render", function($parent) {
+	    ($parent || $body).append(this.$el);
+	    this.status = AnimationStatus.NOT_DISPLAYED;
+	});
+
+	/**
+	Destroys the item's DOM object
+
+	@method destroy
+	**/
+	VisualItem.method("destroy", function() {
+	    this.$el.remove();
+	});

data/src/main.js

@@ -0,0 +1,52 @@
+;(function(global, $, jazz, markdown){
+  (function(name, module){
+    var ss = module();
+   
+    if (typeof define === 'function' && define.amd){ 
+      define(module);
+    } else { 
+      global[name] = ss;
+    }
+  })('sideshow', function(){
+      //jQuery is needed
+      if ($ === undefined) throw new SSException("2", "jQuery is required for Sideshow to work.");
+
+      //Jazz is needed
+      if (jazz === undefined) throw new SSException("3", "Jazz is required for Sideshow to work.");
+
+      //Pagedown (the Markdown parser used by Sideshow) is needed
+      if (markdown === undefined) throw new SSException("4", "Pagedown (the Markdown parser used by Sideshow) is required for Sideshow to work.");
+
+      //=include general/variables.js
+      //=include general/exception.js
+      //=include general/utility_functions.js
+      //=include general/dictionary.js
+      //=include general/config.js
+      //=include wizard/wizard_control_variables.js
+      //=include interface_itens/visual_item.js
+      //=include interface_itens/hidable_item.js
+      //=include interface_itens/fadable_item.js
+      //=include wizard/wizard.js
+      //=include step/step_details_panel.js
+      //=include step/arrows.js
+      //=include step/arrow.js
+      //=include step/step_description.js
+      //=include step/step_description_next_button.js
+      //=include general/screen.js
+      //=include step/subject.js
+      //=include mask/mask.js
+      //=include mask/subject_mask.js
+      //=include mask/composite_mask.js
+      //=include mask/composite_mask_part.js
+      //=include mask/composite_mask_corner_part.js
+      //=include general/polling.js
+      //=include wizard/wizard_menu.js
+      //=include general/global_object.js
+
+      //Tries to register the Global Access Point
+      if (global[globalObjectName] === undefined) {
+        global[globalObjectName] = SS;
+      } else
+        throw new SSException("1", "The global access point \"Sideshow\" is already being used.");
+  });
+})(this, jQuery, Jazz, Markdown);

data/src/mask/composite_mask.js

@@ -0,0 +1,193 @@
+    /**
+    Controls the mask surrounds the subject (the step focussed area)
+
+    @class CompositeMask
+    @@singleton
+    **/
+    Mask.CompositeMask = jazz.Class().extending(FadableItem).singleton;
+
+    /**
+    Initializes the composite mask
+
+    @method init
+    **/
+    Mask.CompositeMask.method("init", function() {
+        var mask = this;
+        ["top", "left", "right", "bottom"].forEach(function(d) {
+            mask.parts[d] = Mask.CompositeMask.Part.build();
+        });
+        ["leftTop", "rightTop", "leftBottom", "rightBottom"].forEach(function(d) {
+            mask.parts[d] = Mask.CompositeMask.CornerPart.build();
+        });
+    });
+
+    /**
+    The parts composing the mask
+
+    @@field parts
+    @type Object
+    **/
+    Mask.CompositeMask.field("parts", {});
+
+    /**
+    Renders the composite mask 
+
+    @method render
+    **/
+    Mask.CompositeMask.method("render", function() {
+        var mask = this;
+        for (var p in this.parts) {
+            var part = this.parts[p];
+            if (part.render) part.render();
+        }
+        this.$el = $(".sideshow-mask-part, .sideshow-mask-corner-part");
+        // if(!this.$el || this.$el.length === 0) this.$el = $(".sideshow-mask-part, .sideshow-mask-corner-part");
+        Mask.SubjectMask.singleInstance.render();
+        ["leftTop", "rightTop", "leftBottom", "rightBottom"].forEach(function(d) {
+            mask.parts[d].$el.addClass(d);
+        });
+        this.status = AnimationStatus.NOT_DISPLAYED;
+    });
+
+    /**
+    Checks if the subject is fully visible, if not, scrolls 'til it became fully visible
+
+    @method scrollIfNecessary
+    @param {Object} position                              An object representing the positioning info for the mask
+    @param {Object} dimension                             An object representing the dimension info for the mask
+    **/
+    Mask.CompositeMask.method("scrollIfNecessary", function(position, dimension) {
+        function doSmoothScroll(scrollTop, callback){
+            $("body,html").animate({
+                scrollTop: scrollTop
+            }, 300, callback);
+        }
+
+        if(!Subject.isSubjectVisible(position, dimension)) {
+            var description = StepDescription.singleInstance;
+            var y = dimension.height > ($window.height() - 50) ? position.y : position.y - 25;
+            y += $window.scrollTop();
+            
+            doSmoothScroll(y, function(){
+                setTimeout(function(){
+                    DetailsPanel.singleInstance.positionate();
+                    description.positionate();
+                    description.fadeIn();
+                }, 300);
+            });
+            
+            return true;
+        }
+        return false;
+    });
+
+    /**
+    Updates the positioning and dimension of each part composing the whole mask, according to the subject coordinates
+
+    @method update
+    @param {Object} position                              An object representing the positioning info for the mask
+    @param {Object} dimension                             An object representing the dimension info for the mask
+    @param {Object} borderRadius                          An object representing the borderRadius info for the mask
+    **/
+    Mask.CompositeMask.method("update", function(position, dimension, borderRadius) {
+        Mask.SubjectMask.singleInstance.update(position, dimension, borderRadius);
+        //Aliases
+        var left = position.x,
+            top = position.y,
+            width = dimension.width,
+            height = dimension.height,
+            br = borderRadius;
+
+        //Updates the divs surrounding the subject
+        this.parts.top.update({
+            x: 0,
+            y: 0
+        }, {
+            width: $window.width(),
+            height: top
+        });
+        this.parts.left.update({
+            x: 0,
+            y: top
+        }, {
+            width: left,
+            height: height
+        });
+        this.parts.right.update({
+            x: left + width,
+            y: top
+        }, {
+            width: $window.width() - (left + width),
+            height: height
+        });
+        this.parts.bottom.update({
+            x: 0,
+            y: top + height
+        }, {
+            width: $window.width(),
+            height: $window.height() - (top + height)
+        });
+
+        //Updates the Rounded corners
+        this.parts.leftTop.update({
+            x: left,
+            y: top
+        }, br.leftTop);
+        this.parts.rightTop.update({
+            x: left + width - br.rightTop,
+            y: top
+        }, br.rightTop);
+        this.parts.leftBottom.update({
+            x: left,
+            y: top + height - br.leftBottom
+        }, br.leftBottom);
+        this.parts.rightBottom.update({
+            x: left + width - br.rightBottom,
+            y: top + height - br.rightBottom
+        }, br.rightBottom);
+    });
+
+    /**
+    A Polling function to check if subject coordinates has changed
+
+    @method pollForSubjectChanges
+    **/
+    Mask.CompositeMask.method("pollForSubjectChanges", function() {
+        if (!flags.lockMaskUpdate) {
+            if (currentWizard && currentWizard.currentStep.subject) {
+                var subject = $(currentWizard.currentStep.subject);
+                if (Subject.obj[0] !== subject[0]) SS.setSubject(subject, true);
+            }
+
+            if (Subject.hasChanged()) {
+                Subject.updateInfo();
+                this.update(Subject.position, Subject.dimension, Subject.borderRadius);
+            }
+        }
+    });
+
+    /**
+    A Polling function to check if screen dimension has changed
+
+    @method pollForScreenChanges
+    **/
+    Mask.CompositeMask.method("pollForScreenChanges", function() {
+        if (Screen.hasChanged()) {
+            Screen.updateInfo();
+            this.update(Subject.position, Subject.dimension, Subject.borderRadius);
+        }
+    });
+
+    /**
+    A part composing the mask
+
+    @class Part
+    @@initializer 
+    @param {Object} position                              The positioning information 
+    @param {Object} dimension                             The dimension information 
+    **/
+    Mask.CompositeMask.Part = jazz.Class(function(position, dimension) {
+        this.position = position;
+        this.dimension = dimension;
+    }).extending(VisualItem);
+