eventhandler.js

javascript 很酷的类库

/*
 * Isomorphic SmartClient
 * Version 6.5 (2008-04-30)
 * Copyright(c) 1998-2007 Isomorphic Software, Inc. All rights reserved.
 * "SmartClient" is a trademark of Isomorphic Software, Inc.
 *
 * [e-mail]
 *
 * http://smartclient.com/license
 */

 

//>	@class	EventHandler
//
// The ISC system provides a predictable cross-browser event-handling mechanism for ISC
// widgets. Events can be handled both at the page level (i.e., globally), and at the level of
// individual widgets.
// <p>
// With the exception of a few page-specific events ('load', 'unload', 'idle' and 'resize'),
// events are processed in the following sequence:
// <p>
// 1. The event is sent to any global (page-level) event handlers. These handlers can cancel
// further propagation of the event by returning false.  You can register to listen for any of the
// events linked in the seeAlso section (below) by calling +link{classMethod:Page.setEvent()}
// method.
// <p>
// 2. If the event occurred on a form element or a link, it is passed on to the browser so that
// the element will perform its default action. No widget receives the event.
// <p>
// 3. If the event occurred on an enabled widget (but not on a form element or link inside
// the widget), it is sent to that widget's event handler, if any. This handler can cancel
// further propagation of the event by returning false.  An "enabled" widget is any widget that
// defines an event handler for one of the supported events.  Interceptable events are defined in
// the +link{class:Canvas#methods#events, "widgetEvents" section of Canvas}.
// <p>
// 4. The event is "bubbled" up to the widget's parent in the containment hierarchy, if any.
// Again, the parent's handler for the event can cancel further propagation by returning
// false. This step is repeated, with the event "bubbling" up through the containment
// hierarchy, until a top-level widget is reached or the event is explicitly canceled.
// In brief, the ISC event model offers the best features of browser event models:
// <ul>
// <li> Page-first event handling allows you to reliably process or cancel any event before it
//      affects the objects on the page.
// <li> Event "bubbling" ensures that parent widgets receive events sent to their children,
//      and allows you to create generalized parent-level handlers rather than duplicating
//      code in each child.
// </ul>
// Note: Canceling propagation of an event may cancel its side effects as well, including the
// generation of other (synthetic) events. For example, if a global mouseDown handler returns
// false, drag-and-drop events will not be generated. Specific effects are discussed in the
// descriptions of the various events in the following sections.
// <p>
// SmartClient libraries will not interfere with native event handling when events occur
// outside of a target widget. You can therefore have HTML that is not ISC-based on the same
// page as widget objects that will react to native events as you would expect.
// <p>
// You can use isc.Event as an alias for isc.EventHandler.
// 
// @see type:PageEvent    
// @see classMethod:Page.setEvent()
// @see classMethod:Page.clearEvent()
// @see class:Canvas#methods#widgetEvents
//
// @treeLocation   Client Reference/System
// @visibility external
//<




// create the isc.EventHandler object
isc.ClassFactory.defineClass("EventHandler");
// nicknames - isc.Event is publicly documented as an alias
isc.EH = isc.Event = isc.EventHandler;
// add class properties and constants
isc.EventHandler.addClassProperties(
{ 	
    //>	@classAttr	isc.EventHandler.lastEvent		(object : {} : IRWA)
	//		Last event that was processed by our event system.  We store the properties
	//		 of the event in a separate object so we can access them uniformly on both
	//		 platforms and so we can remember characteristics of the last event we've
	//		 seen even when we're not in the script context of this event.<br><br>
	//		
	//		To access properties of the last event, use:<ul>
	//			<li>isc.EventHandler.getLastEvent()
	//			<li>isc.EventHandler.getX()
	//			<li>isc.EventHandler.getY()
	//			<li>isc.EventHandler.getScreenX()
	//			<li>isc.EventHandler.getScreenY()
	//			<li>isc.EventHandler.getButtonNum()
	//			<li>isc.EventHandler.leftButtonDown()
	//			<li>isc.EventHandler.rightButtonDown()
	//			<li>isc.EventHandler.getKey()
    //          <li>isc.EventHandler.getKeyEventCharacterValue()
    //          <li>isc.EventHandler.getKeyEventCharacter()
	//			<li>isc.EventHandler.shiftKeyDown()
	//			<li>isc.EventHandler.ctrlKeyDown()
	//			<li>isc.EventHandler.altKeyDown()
	//			<li>isc.EventHandler.metaKeyDown()
    //      </ul>
	//
	//		@group events
	//		@see	isc.EventHandler.getMouseEventProperties()
    //      @see    isc.EventHandler.getKeyEventProperties()
    //  @visibility eventhandler
	//<
	lastEvent : {},						
	
    //>	@classAttr	isc.EventHandler._dropRegistry		(array : [] : IRWA)
	//		Registry of canvases that are interested in receiving drop events.
	//		@group dragdrop
	//		@see	isc.EventHandler.eventHandledNatively()
    //  @visibility internal
	//<
    _dropRegistry : [],			        

	//>	@classAttr	isc.EventHandler._maskRegistry		(array : [] : IA)
	//		Registry of canvases that have their own _eventMask peers to block mouse
	//		events. Implemented so that canvases with contentsURL (iframe contents)
	//		won't swallow events during drag & drop. When a drag operation begins,
	//		we show the masks for all canvases in this registry.
    // @visibility internal
	//<
	_maskRegistry : [],
	
	//>	@classAttr	isc.EventHandler.passThroughEvents		(boolean : true : IRWA)
	//			if true, we pass events to anchors and form elements automatically.
	//			false == trap these events
	//		@see	isc.EventHandler.eventHandledNatively()
    // @visibility internal
	//<
	passThroughEvents:true,

	//>	@classAttr	isc.EventHandler.maskNativeEvents (boolean : true : IRWA)
	//      Whether the clickmask should mask events on non ISC-elements as well.  
    // @visibility internal
	//<
    maskNativeTargets:true,
						
	//=	@const	isc.EventHandler.STILL_DOWN_DELAY	amount of time between mouseStillDown messages (msec)
	STILL_DOWN_DELAY 	: 100,
	//=	@const	isc.EventHandler.DOUBLE_CLICK_DELAY	amount of time between doubleClicks (msec)
    
	DOUBLE_CLICK_DELAY  : 500,
    //=	@const	isc.EventHandler.IDLE_DELAY			amount of time between idle messages (msec)
	IDLE_DELAY 			: 10,

    //=	@const	isc.EventHandler.STOP_BUBBLING		return this from a child event to stop the event propagating to its parent
	STOP_BUBBLING : "***STOP***",		


	//=	@const	isc.EventHandler.ALL_EDGES	default set of edges to resize from (all)
	ALL_EDGES : ["T","L","B","R","TL","TR","BL","BR"],

    eventTypes :	{	
        // Events are documented on Canvas as methods since that's how we expect users to register
        // them on widgets.  Some are also documented here for reference by Page.setEvent()

        //> @type PageEvent
        //
        // Events registerable via +link{classMethod:Page.setEvent()}
        //
        // 
        // @value "idle" 
        //        Fires repeatedly (every 10 ms by default) when the system is idle (i.e.,
        //        not busy running other scripts) after the page is loaded.
        // @value "load" 
        //        Fires when the page has finished loading. It corresponds to the
        //        browser 'load' event normally handled by window.onload.
        // @value "unload" 
        //        Fires when the page is exited or unloaded. It corresponds to the
        //        browser 'unload' event normally handled by window.onunload.
        // @value "resize" 
        //        Fires when the browser window is resized by the user. It corresponds
        //        to the browser 'resize' event normally handled by window.onresize.    
        //
        //
        // @value "mouseDown"
        //        Fires when the left mouse button is pressed on the Page.
        // @value "rightMouseDown"
        //        Fires when the right mouse button is pressed on the Page.
        // @value "mouseMove"
        //        Fires when the mouse moves on the Page.
        // @value "mouseUp"
        //        Fires when the left mouse button released on the Page.
        // @value "cick"
        //        Fires when the user clicks the mouse on the Page.
        // @value "doubleClick"
        //        Fires when the uesr double-clicks on the Page.
        //
        // @value "showContextMenu"
        //        Fires when the right mouse button is clicked on the page.  If your event handler
        //        for this event returns false, the native browser context menu will be suppressed.<br>
        //        Note: On the Macintosh platform, <code>Command+Click</code> may be used instead
        //        of right-button click to trigger a context menu event.<br>
        //        On the Opera browser, <code>Ctrl+Shift+Click</code> should be used instead of
        //        right-button click.
        //
        // @value "keyPress" Fires when a user presses a key on the keyboard. 
        //
        // see classMethod:Page.setEvent()
        // see classMethod:Page.clearEvent()
        // @visibility external
        //<
        
    	MOUSE_DOWN : "mouseDown",
    	RIGHT_MOUSE_DOWN : "rightMouseDown",
    	MOUSE_MOVE : "mouseMove",			
    	MOUSE_UP : "mouseUp",				    
    	SHOW_CONTEXT_MENU : "showContextMenu",	

        CLICK : "click",		
    	DOUBLE_CLICK : "doubleClick",		
    	// the following mouse events are not available on Page 
    	MOUSE_OUT : "mouseOut",				
    	MOUSE_STILL_DOWN : "mouseStillDown",
    	MOUSE_OVER : "mouseOver",


        // XXX classify
    	SET_DRAG_TRACKER : "setDragTracker",
        GET_DRAG_DATA : "getDragData",      
        RELEASE_DRAG_DATA : "releaseDragData", 
        

        DRAG_START:"dragStart",
        DRAG_STOP:"dragStop",  
    	DRAG_MOVE : "dragMove",
    	DRAG_OUT : "dragOut",	
        DRAG_REPOSITION_START : "dragRepositionStart",
        DRAG_REPOSITION_MOVE : "dragRepositionMove",
        DRAG_REPOSITION_STOP : "dragRepositionStop",
        DRAG_RESIZE_START : "dragResizeStart",
        DRAG_RESIZE_MOVE : "dragResizeMove",
        DRAG_RESIZE_STOP : "dragResizeStop",

    	DROP_OVER : "dropOver",
    	DROP_MOVE : "dropMove",
    	DROP_OUT : "dropOut",
    	DROP : "drop",			
    
    	KEY_DOWN : "keyDown",	
    	KEY_UP : "keyUp",		
    	KEY_PRESS : "keyPress",	
        MOUSE_WHEEL : "mouseWheel",
    	
    	SELECT_START : "selectStart",
        SELECTION_CHANGE : "selectionChange",
        FOCUS_IN : "focusIn",
        FOCUS_OUT : "focusOut",

    	IDLE : "idle",				
    	LOAD : "load",						
    	UNLOAD : "unload",					
    	RESIZE : "resize"
    },
    
    // Map used by getMouseEventProperties to convert from native mouse event names to 
    // canonicalized versions (available as constants on the EH class).
    _nativeMouseEventMap : {
        // By default all browsers give lowercase event names for the following events*
        //  *Verified on IE6, Windows; Moz 1.73, Windows; Safari 2, Mac; Moz 1.6, Unix;
        mousemove:"mouseMove",
        mousedown:"mouseDown",
        mouseup:"mouseUp",

        // Proprietary to IE6
        mousewheel:"mouseWheel",
        selectionchange:"selectionChange",
        // Proprietary to Moz
        DOMMouseScroll:"mouseWheel",

        
        // Also handle being passed an already canonicalized version - may happen if the 
        // event passed to getMouseEventProperrties was an ISC event rather than a native event
        mouseMove:"mouseMove",
        mouseDown:"mouseDown",
        mouseUp:"mouseUp",
        mouseWheel:"mouseWheel",
        
        selectionstart:"selectionStart",
        selectionStart:"selectionStart",
        selectionchange:"selectionChange",
        selectionChange:"selectionChange"
        
    },

    //> @const isc.EventHandler._eventHandlerArgString    
    // Argument string for event handler stringMethods
    // @visibility internal
    //<
    _eventHandlerArgString:"event,eventInfo",   

	//>	@type	DragOperation
	// Builtin types of drag and drop interactions
	//		@group	dragdrop
    //	@value	isc.EventHandler.DRAG_RESIZE			Resizing by dragging
	DRAG_RESIZE : "dragResize",			
    //	@value	isc.EventHandler.DRAG_REPOSITION		Repositioning by dragging
	DRAG_REPOSITION : "dragReposition",	
    //	@value	isc.EventHandler.DRAG			General drag (custom implementation)
	DRAG : "drag",
	//<										

    //>	@type	DragAppearance
    // 		Different types of effects for showing dragging behavior.
    //	@group	dragdrop
	//	@visibility external
    //
    //	@value	"none"
    //      No default drag appearance is indicated. Your custom dragging routines should
    //      implement some behavior that indicates that the user is in a dragging situation,
    //      and where the mouse is.
	NONE : "none",
    //	@value	"tracker"
    //      A "drag tracker" object is automatically shown and moved around with the
    //      mouse. This is generally set to an icon that represents what is being dragged. The
    //      default tracker is a 10 pixel black square, but you can customize this icon. This
    //      dragAppearance is not recommended for use with drag resizing or drag moving.
	TRACKER : "tracker",
    //	@value	"target"
    //      The target object is actually moved, resized, etc. in real time. This is
    //      recommended for drag repositioning, but not for drag resizing of complex objects.
	TARGET : "target",
    //	@value	"outline"
    //      An outline the size of the target object is moved, resized, etc. with the
    //      mouse. This is recommended for drag resizing, especially for objects that take a
    //      significant amount of time to draw.
	OUTLINE : "outline",
    //<	

    //>	@type	DragIntersectStyle
    //      Different styles of determining intersection: with mouse or entire rect of target
    //		@group	dragdrop
    //
	//	@visibility eventhandler
    //	@value	isc.EventHandler.INTERSECT_WITH_MOUSE
    //      Look for drop targets that are under the current mouse cursor position.
	INTERSECT_WITH_MOUSE : "mouse",
    //	@value	isc.EventHandler.INTERSECT_WITH_RECT
    //      Look for drop targets by intersection of the entire rect of the drag target with the
    //      droppable target.
	INTERSECT_WITH_RECT : "rect",
    //<

    
    //>	@classAttr  dragTargetShadowDepth   (number : 10 : IRWA);
    //  If we are showing a shadow for some widget on drag, how deep should the shadow be.
    //  @group  dragdrop
    //<
    dragTargetShadowDepth : 10,



	_anchorTags : {
        A : true,
        AREA : true
    },
	_formTags : {
        INPUT : true,
        TEXTAREA : true,
        SELECT : true,
        OPTION : true
    },