/*!
  @header ECXMLControlReferenceRule
  @abstract Module of Encore
 
  @availability OS X, GNUstep
  @copyright 2004, 2005, 2006 Oliver Langer

  Author: Oliver Langer

  This library is free software; you can redistribute it and/or
  modify it under the terms of the GNU Lesser General Public
  License as published by the Free Software Foundation; either
  version 2.1 of the License, or (at your option) any later version.

  This library 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
  Lesser General Public License for more details.

  You should have received a copy of the GNU Lesser General Public
  License along with this library; if not, write to the Free Software
  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301 USA

  <pre>
  -------------------------------------------------------------------------
  Modification history

  10.02.06 ola     initial version
  22.08.06 ola     license changed
  -------------------------------------------------------------------------
  </pre>
*/

#if !defined(__ECXMLControlReferenceRule_H)
#define __ECXMLControlReferenceRule_H

#include <Foundation/Foundation.h>
#include <Encore/ECObject.h>
#include <Encore/ECXMLControlDefaultRule.h>

/*!
  @class ECXMLControlReferenceRule
  @abstract This rule allows the definition of anchors and their
    corresponding references.
  @discussion Through this rule it is possible to set an anchor and by doing
  so, to refer to the corresponding object later in the xml parsing step. The
  reference results in a corresponding setter call. Example: <p>
 &lthouse id="house-id"/&gt;
 
 &lt;Contract price="128.231,75" object-idref="house-id"/&gt;
 </pre>
  In this example the object allocated by &lt;Contracr&gt; will be hand-off
  the previously allocate instance related to &lt;house&gt; by calling the
  related setter method setObject or addObject.<p/>
  The underlying rules are as follows:
 <ul>
    <li><b>id</b>-attribute: This attribute specifies the name under which the
      object, which is currently on top of the stack, has to be registered.
      The identifier behind has to be unique wrt. the whole file.</li>
   <li><b>&lt;attributename&gt;-idref</b>-attribute: Looks for an object 
     which has been registered with the value specified by this attribute.
     The registration must habe been done before! If the registired object
     is found then the underlying setting method is called using
     &lt;attributename&gt; as the base name.
 </ul>
 Regarding the lookup for the corresponding setting method please refer
 to ECXMLControlSetterLookupUtil.
 */
@interface ECXMLControlReferenceRule : ECObject <ECXMLControlRule> {
  @private
    ECXMLControlSetterLookupUtil *setterLookupUtil;
}


- init;
- (void) dealloc;


/*!
 * @method addObject 
 * @abstract Internal method used to register an object which may be
 *   references.
 * @param anObject related object
 * @param aRefId underlying reference identifier
 * @param aDictionary dictionary used to store the new identifier and the
 *   corresponding object
 * @result self
 */
- addObject: (id) anObject withRefId: (NSString *) aRefId
  usingDictionary: (NSMutableDictionary *) aDicitonary;
  
  
/*!
 * @method respondsToContext
 * @param aContext current context to evaluate
 * @result YES if the receiver should be valuated according to the given 
 *   context
 */
- (BOOL) mayActOn: (ECXMLControlContext *) aContext;


/*!
 * @method actOn
 * @param aContext current context to evaluate
 * @result YES if no more rules should be evaluated
 */
- (BOOL) actOn: (ECXMLControlContext *) aContext;


/*!
 * @method setReferenceToObject
 * @abstract Hands-off a referenced object to the object currently being on top
 *   of the stack
 * @param idName identifier string which references the object to hand-off
 * @param anObject object to which the referenced object has to be hand-off
 * @param methodName method to call
 * @param aDicitonary global rule dictionary where the references are managed.
 * @result self
 */
- setReferenceToObject: (id) anObject 
  objectIdReference: (NSString *) idName
  usingMethod: (NSString *) methodName
  usingDictionary: (NSMutableDictionary *) aDictionary;
@end
#endif