source: gs3-extensions/seaweed-debug/trunk/src/events/Mouse.js@ 25160

/*
 * file: Mouse.js
 *
 * @BEGINLICENSE
 * Copyright 2010 Brook Novak  (email : [email protected]) 
 * This program is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or
 * (at your option) any later version.
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 * You should have received a copy of the GNU General Public License
 * along with this program; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
 * @ENDLICENSE
 */
bootstrap.provides("events.Mouse");

(function() {

    var LEFT_BUTTON = "1",
        RIGHT_BUTTON = "2",
        toNormalizedIDMap, // Platform dependant map for transating to platform independant values
        draggingScrollBars = false,
        // The keys are button values in dom mouse event objects.
        // The values are booleans, where true means they are down
        mouseStateMap = {};
    
    $enqueueInit("events.Mouse", function(){
        
        // Ensure that the document always captures mouse events to track mouse state
        //_addHandler(document, "mousedown", function() {}); // DEPRECIATED: Selection will always have these events
      //  _addHandler(document, "mouseup", function() {});
        
        // Setup mouse-button map for translating button/which values into a normalized/agreed value for all platforms
        if (_browser == _Platform.IE) {
            toNormalizedIDMap = {
                "1": LEFT_BUTTON,
                "2": RIGHT_BUTTON
            };
        } else {// DOM Complient
            // DOM have screwed up their specification. There is no way to tell
            // reliably whether a left click is down since their button value
            toNormalizedIDMap = {
                "0": LEFT_BUTTON,
                "2": RIGHT_BUTTON
            };
        }
        
        mouseStateMap[LEFT_BUTTON] =  mouseStateMap[RIGHT_BUTTON] = false;

    });

    /**
     * @class A singleton that provides cross-browser/platform mouse-state facilties.
     * @author Brook Jesse Novak
     */
    de.events.Mouse = {
    
        sniffMouseDownEvent : function(e) {
            
            // Update mouse button state
            var normalizedClickID = toNormalizedIDMap[e.button];

            if (normalizedClickID) {
                // Left click + ctrl = right click on macs
                if (_os == _Platform.MAC && normalizedClickID == LEFT_BUTTON && e.ctrlKey) 
                    normalizedClickID = RIGHT_CLICK;
                mouseStateMap[normalizedClickID] = true;
            }
            
            // Filter out mouse events on the document when the mouse is on the scroll bars
            if (isOnScrollBars(e)) {
                draggingScrollBars = this.isLeftDown();
                return false;
            }
            
            return true;
        },
        
        sniffMouseUpEvent: function(e){
        
            // Update mouse button state
            var normalizedClickID = toNormalizedIDMap[e.button];
  
            if (normalizedClickID) {
                // Left click + ctrl = right click on macs. However- the user may have depressed the ctrl key before the
                // key up event. Therefore, if this is a mac, and if this button up event is a left button, then set both left and right
                // states to no longer being down. 
                if (_os == _Platform.MAC && normalizedClickID == LEFT_BUTTON) 
                    // Sure this isn't perfect but there is no way to tell - and its not the end of the world,
                    // I don't think the use of two buttons at the same time is very useful for text-editors anyway!
                    this.clearDownStates();
                else 
                    mouseStateMap[normalizedClickID] = false;
            }
            
            draggingScrollBars = this.isLeftDown();
            
            // Filter out mouse events on the document when the mouse is on the scroll bars
            return !isOnScrollBars(e);
        },
        
        sniffMouseMoveEvent: function(e){
            // Filter out mouse move events within the document (including the actual document)
            // if the user is scrolling.
            return !(this.isLeftDown() && draggingScrollBars);
        },        
        
        /**
         * @return {Boolean} True if the left mouse button is currently down.
         *
         * <br>
         * <b>Note</b>: On a mac, if the user left-clicks while ctrl is down, this seen a right click
         * gesture for their single button mouse design - but also does the same thing for mouses
         * with multiple buttons.
         *
         */
        isLeftDown: function(){
            return mouseStateMap[LEFT_BUTTON];
        },
        
        /**
         * @return {Boolean} True if the right mouse button is currently down.
         */
        isRightDown: function(){
            return mouseStateMap[RIGHT_BUTTON];
        },
        
        /**
         * Clears the button down states.
         * Useful if mouse module is unable to capture/sniff mouse up events in a particulat environment ...
         * this provides a way to manually clear mousedown states.
         */
        clearDownStates : function() {
            mouseStateMap[LEFT_BUTTON] = false;
            mouseStateMap[RIGHT_BUTTON] = false;
        }
        
    }; // End mouse singleton

    /**
     * Determines whether mouse event targetted at the document is over scroll bars
     * @param {Object} e
     * @return {Boolean} Evaluate true if mouse event was on scrollbars
     */
    function isOnScrollBars(e) {
        
        var target = de.events.getEventTarget(e);

        if (target == window || target == document || target == document.documentElement) {
            
            // Opera never raises events on document scrollbars
            if (_engine == _Platform.PRESTO) 
                return;
            
            var pos = de.events.getXYInWindowFromEvent(e),
                viewportSize = _getViewPortSize();
            if (pos.x >= viewportSize.width) 
                return 1;
                
            return pos.y >= viewportSize.height; 
        }
        
    }
    
})();