<?php
/*
    File: xajaxEvent.inc.php

    Definition of the xajax Event object.

    Title: xajaxEvent

    Please see <copyright.inc.php> for a detailed description, copyright
    and license information.
*/

/*
    @package xajax
    @version $Id: xajaxEvent.inc.php 362 2007-05-29 15:32:24Z calltoconstruct $
    @copyright Copyright (c) 2005-2007 by Jared White & J. Max Wilson
    @copyright Copyright (c) 2008-2010 by Joseph Woolley, Steffen Konerow, Jared White  & J. Max Wilson
    @license http://www.xajaxproject.org/bsd_license.txt BSD License
*/

// require_once is necessary here as the function plugin also includes this
//SkipAIO
require_once __DIR__ . '/xajaxUserFunction.inc.php';
//EndSkipAIO

/*
    Class: xajaxEvent

    A container class which holds a reference to handler functions and configuration
    options associated with a registered event.
*/
final class xajaxEvent
{
    /*
        String: sName

        The name of the event.
    */
    private $sName;
    
    /*
        Array: aConfiguration

        Configuration / call options to be used when initiating a xajax request
        to trigger this event.
    */
    private $aConfiguration;
    
    /*
        Array: aHandlers

        A list of <xajaxUserFunction> objects associated with this registered
        event.  Each of these functions will be called when the event is triggered.
    */
    private $aHandlers;
    
    /*
        Function: xajaxEvent

        Construct and initialize this <xajaxEvent> object.
    */
    public function __construct($sName)
    {
        $this->sName = $sName;
        $this->aConfiguration = array();
        $this->aHandlers = array();
    }
    
    /*
        Function: getName

        Returns the name of the event.

        Returns:

        string - the name of the event.
    */
    public function getName()
    {
        return $this->sName;
    }
    
    /*
        Function: configure

        Sets/stores configuration options that will be used when generating
        the client script that is sent to the browser.
    */
    public function configure($sName, $mValue)
    {
        $this->aConfiguration[$sName] = $mValue;
    }
    
    /*
        Function: addHandler

        Adds a <xajaxUserFunction> object to the list of handlers that will
        be fired when the event is triggered.
    */
    public function addHandler($xuf)
    {
        $this->aHandlers[] = $xuf;
    }
    
    /*
        Function: generateRequest

        Generates a <xajaxRequest> object that corresponds to the
        event so that the client script can easily invoke this event.

        sXajaxPrefix - (string):  The prefix that will be prepended to
            the client script stub function associated with this event.

        sEventPrefix - (string):  The prefix prepended to the client script
            function stub and <xajaxRequest> script.
    */
    public function generateRequest($sXajaxPrefix, $sEventPrefix)
    {
        $sEvent = $this->sName;
        return new xajaxRequest("{$sXajaxPrefix}{$sEventPrefix}{$sEvent}");
    }



    /*
        Function: generateClientScript

        Generates a block of javascript code that declares a stub function
        that can be used to easily trigger the event from the browser.
    */
    public function generateClientScript($sXajaxPrefix, $sEventPrefix)
    {
        $sMode = '';
        $sMethod = '';
        
        if (isset($this->aConfiguration['mode'])) {
            $sMode = $this->aConfiguration['mode'];
        }
            
        if (isset($this->aConfiguration['method'])) {
            $sMethod = $this->aConfiguration['method'];
        }
            
        if (0 < strlen($sMode)) {
            $sMode = ", mode: '{$sMode}'";
        }
        
        if (0 < strlen($sMethod)) {
            $sMethod = ", method: '{$sMethod}'";
        }
        
        $sEvent = $this->sName;
        echo "{$sXajaxPrefix}{$sEventPrefix}{$sEvent} = function() { return xajax.request( { xjxevt: '{$sEvent}' }, { parameters: arguments{$sMode}{$sMethod} } ); };\n";
    }
    
    /*
        Function: fire

        Called by the <xajaxEventPlugin> when the event has been triggered.
    */
    public function fire($aArgs)
    {
        $objResponseManager = xajaxResponseManager::getInstance();
        
        foreach (array_keys($this->aHandlers) as $sKey) {
            $this->aHandlers[$sKey]->call($aArgs);
        }
    }
}
