eventregistry.js

javascript 很酷的类库

	for (var i = 0, length = list.length; keepGoing && (i < length); i++) {
		var item = list[i];
        // Note: this array may be sparse - just skip empty entries
		if (!item) continue;

		// if an item is set to only fire once, remove it from the list.
        // NOTE: we want to do this immediately, that way if there's an error during processing of
        // the event, at least it will only happen once!
		if (item.fireStyle == isc.Page.FIRE_ONCE) list[i] = null;

        //>DEBUG
        if (this.logIsDebugEnabled()) {
            this.logDebug("handleEvent(" + eventType + "): firing action => " +
                                    isc.Func.getShortBody(item.action));
        }
        //<DEBUG 
    
        // fire the action
        if (isc.isA.Function(item.action)) {
            // function / expression style
		    keepGoing = (item.action(target,eventInfo) != false);
        } else {
            // object style: item.action is an Object (eg a Canvas), which should have either
            // "page"[eventName] invoked on it, or a custom function specified at registration
            // time and stored as item.functionName
            var object = item.action;

            if (object.destroyed) {
                // if the item has been destroyed, remove the registration and continue
                list[i] = null;
                continue;
            }

            var functionName = item.functionName || pageEventName;
            if (isc.isA.Function(object[functionName])) {
                keepGoing = (object[functionName](target,eventInfo) != false);
            }           
        }
	}
    this._processingEvent = null;

	// collapse the list of handlers to get rid of any that have been cleared
    // (including those set to fire once).
    
	this._eventRegistry[eventType].removeEmpty();
		
	// return whether or not other event handlers should be fired
	return keepGoing;
},

//>	@classMethod	Page.actionsArePendingForEvent()	(A)
//		Return whether any actions are currently pending for a specific event.
//		@group	EventRegistry
//
//		@param	eventType	(string) 	name of this event
//
//		@return			(boolean)	true == at least one event is pending
//									false == no events pending
//<
actionsArePendingForEvent : function (eventType) {
	return (this._eventRegistry[eventType] && this._eventRegistry[eventType].length != 0);
},



//
//	KeyRegistry -- global eventType for keyboard events
//



//>	@classMethod	Page.registerKey()
// Fire some action when the Page recieves a keyPress event from a certain key.<br>
// Note that if a widget has keyboard focus, this action will fire only after any widget-level
// keyPress handlers have fired and bubbled the event up to the top of their ancestor chain.<br>
// Multiple actions can be registered to fire on a single keyPress using this method, and can
// be associated with different <code>target</code> objects (which will then be available as
// a parameter when the action is fired).<br>
// This differs from calling +link{Page.setEvent()} with the <code>"keyPress"</code>
// events registered via <code>setEvent()</code> will fire <i>before</i> widget level handlers 
// respond to the event, and will fire for every <code>keyPress</code> event, not just those
// triggerred by some specific key or key-combination.
// 
// 
// @group	KeyRegistry
//		@param	key		(KeyIdentifier) key name or identifier object.
//		@param	action	(string)		Action to fire when key is pressed.
//              This can be a string of script to evaluate or a javascript function.<br>
//              This action will be passed 2 parameters: The name of the key pressed will be 
//              available as the first parameter or <code>key</code> keyword. The target 
//              passed into this method will be available as the second parameter or 
//             <code>target</code> keyword.
//      @param  [target]    (any)   If specified this object will be made available to the
//                                  action fired as a parameter.
// @see Canvas.keyPress()
// @see Page.setEvent()
// @see Page.unregisterKey()
// @visibility external
//<

registerKey : function (key, action, target) {

    if (key == null || action == null) return;

    // If passed an object for key, get keyName and any modifiers from it!
    var keyName = key,
        ctrlKey, shiftKey, altKey, metaKey;
    
    if (isc.isAn.Object(key)) {
        keyName = key.keyName;
        ctrlKey = key.ctrlKey;
        shiftKey = key.shiftKey;
        altKey = key.altKey;
        // Not doc'ing Meta- we don't reliably get meta+key events cross platform.
        metaKey = key.metaKey;
    }

    // allow passing either "a" or "A".  Note toUpperCase() will simply no-op on numbers and
    // punctuation.
    if (keyName.length == 1) keyName = keyName.toUpperCase();

    // if we don't recognize the keyName, log a warning and bail
    // A definitive list of keyNames is in the '_virtualKeyMap' on EventHandler
    var isKeyName = false;
    for (var i in isc.EH._virtualKeyMap) {
        if (isc.EH._virtualKeyMap[i] == keyName) {
            isKeyName = true;
            break;
        }
    }

    if (!isKeyName) {
        this.logWarn(
            "Page.registerKey() passed unrecognized key name '" + key +"'. Not registering",
            "events"
        );
        return;
    }
    

    var keyRegistry = this._keyRegistry;
	// create an array under that key if necessary
	if (!keyRegistry[keyName]) keyRegistry[keyName] = [];
	
	// add the item to the key registry
	keyRegistry[keyName].add({target:target, action:action, 
                              ctrlKey:ctrlKey, shiftKey:shiftKey,
                              altKey:altKey, metaKey:metaKey});
},

//>	@classMethod	Page.unregisterKey()
// Clears an action registered to fire on a specific a keyPress event via the +link{Page.registerKey()}
// method. 
//		@group	KeyRegistry
//		@see	Page.registerKey()
//
//		@param	actionID (KeyName) Name of key to clear registry enties for.
//		@param	[target] (object) target specified when the action was registered for the key.
//
// @visibility external
//<
unregisterKey : function (key, target) {

	// if the registry item under that key doesn't exist, bail
	if (!this._keyRegistry[key]) {
        isc.Log.logInfo("Page.unregisterKey(): No events registered for key " + isc.Log.echo(key) + ".", "events");
        return false;
    }
	// remove the item
	this._keyRegistry[key].removeWhere("target", target)
},


//>	@classMethod	Page.handleKeyPress()	(A)
//			Handle a key press by firing messages to all listeners of that key 
//			registered with the Key Registry.
//		@group	KeyRegistry
//
//		@param	event	(DOM event) DOM event object (as passed by isc.EventHandler)
//		@return			(boolean)	false == stop further event processing	
//
//<
handleKeyPress : function () {
    // Get the name for the key
    var EH = isc.EH,
        key = EH.getKey(),
        keyRegistry = this._keyRegistry;
    
    //this.logInfo("keyName is " + key + 
    //             ", handlers are registered for: " + getKeys(Page._keyRegistry));

	// no one has registered an action for this key
    if (!keyRegistry[key]) return true;

	// get the list of actions from the registry
    
    var actionsInReg = keyRegistry[key],
        actions = actionsInReg.duplicate(),
        length = actions.length,
        returnVal = true;

    // Pick up each action to fire from the registry
    
	for (var i = 0; i < length; i++) {
        var item = actions[i];
        // The item may have been unregistered by another item's action.
        // If so skip it.
        if (!actionsInReg.contains(item)) continue;

        // if passed an explicit preference on modifier keys, respect it (if not specified,
        // fire regardless of modifiers!).  NOTE we support eg ctrlKey:false as a way of *not*
        // firing if the ctrlKey is down.
        if (item.ctrlKey != null && item.ctrlKey != EH.ctrlKeyDown()) continue;
        if (item.altKey != null && item.altKey != EH.altKeyDown()) continue; 
        if (item.shiftKey != null && item.shiftKey != EH.shiftKeyDown()) continue;
        if (item.metaKey != null && item.metaKey != EH.metaKeyDown()) continue;        

		// CALLBACK API:  available variables:  "key,target"
		// Convert a string callback to a function
		if (item.action != null && !isc.isA.Function(item.action)) {
			isc.Func.replaceWithMethod(item, "action", "key,target");
		}
		returnVal = ((item.action(key, item.target) != false) && returnVal);
	}
	return returnVal;
}

});	// END isc.Page.addMethods