/*
* Copyright (c) 2007 Nokia Corporation and/or its subsidiary(-ies). 
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:  An interface for querying and setting attributes.
*
*/


#ifndef I_ALFATTRIBUTEOWNER_H
#define I_ALFATTRIBUTEOWNER_H

#include <alf/ialfinterfacebase.h>
#include <alf/alftypes.h>

namespace osncore
    {
class UString;
    }

using namespace osncore;

namespace Alf
    {

class AlfAttribute;
class AlfAttributeValueType;
class AlfAttributeContainer;

namespace alfattributeowner
    {
static const IfId ident =
    {
    0, "alfattributeowner"
    };
    }

/**
 *  An interface for querying and setting attributes.
 *  The interface defines a generic functionality for setting
 *  any attributes of the implementing class. It can be used
 *  also to query the available set of attributes.
 *
 *  The interface should by implemented by all widget classes.
 *  It can be also used by element classes.
 *  Widget attributes have often corresponding data fields in the
 *  model. In this case, setting new values should also update
 *  the model. If an attribute is related to the presentation of
 *  the widget, the presentation is updated when a new value is set
 *  for the attribute.
 *
 *  @lib alfwidgetmodel.lib
 *  @since S60 ?S60_version
 *  @status Draft
 */
class IAlfAttributeOwner : public IAlfInterfaceBase
    {
public:
    /**
     * Virtual destructor.
     */
    virtual ~IAlfAttributeOwner() {}

    /**
     * Get the number of available attributes.
     *
     * @return The number of attributes.
     */
    virtual int attributeCount() const = 0;

    /**
     * Gets the attribute with the given name.
     * The returned attribute instance is owned by the widget and
     * should not be deleted.
     * Also the returned attribute instance should not be modified.
     * Use SetAttribute for that.
     *
     * @param aAttribName The name of the attribute.
     * @return The attribute, or 0 if the attribute was not found.
     */
    virtual const AlfAttribute* getAttribute( const UString& aAttribName ) const = 0;

    /**
     * Set a value of an attribute.
     *
     * If no value is present in passed attribute parameter,
     * an AlfAttributeException-exception
     * is thrown with EInvalidAttribute error code.
     *
     * @param aAttribute Reference attribute, the data is copied from it.
     * The ownership is not transferred.
     * @return True if the attribute was supported, false if not.
     *         Attribute is added to container even if it not supported.
     */
    virtual bool setAttribute( const AlfAttribute& aAttribute ) = 0; 

    /**
     * Set a value of an attribute.
     * This SetAttribute variant is for simple non animated attributes 
     * that only have name and value.
     *
     * If no value is present in passed attributevalue parameter,
     * an AlfAttributeException-exception
     * is thrown with EInvalidAttribute error code.
     *
     * @param aAttribName Name of the attribute.
     * @param aValue Value of the attribute. Ownership is transferred 
     * @return True if the attribute was supported, false if not.
     *         Attribute is added to container even if it not supported.
     */    
    virtual bool setAttribute( const UString& aAttribName, 
        AlfAttributeValueType* aValue ) = 0; 
    /**
     * Sets values of each attribute in given container 
     *
     * If no value is present in an attribute in the container,
     * an AlfAttributeException-exception
     * is thrown with EInvalidAttribute error code.
     *
     * @param aAttributeContainer Reference attributeContainer, All attributes
     *        in the container are handled. The ownership is not transferred.
     * @return True if all attributes were supported, false if at least 1 attribute was not supported
     */    
    virtual bool setAttributeContainer( AlfAttributeContainer& aAttributeContainer ) = 0; 

   /**
     * Sets a value of an attribute to a specific target. 
     * The target is identified by using aTargetId parameter.
     *
     * If no value is present in passed attribute parameter,
     * an AlfAttributeException-exception
     * is thrown with EInvalidAttribute error code.
     *
     * @param aTargetId  Name of the target widget part, e.g element class tag.
     * @param aAttribute Reference attribute, the data is copied from it.
     *                   The ownership is not transferred.
     * @return True if the attribute was supported, false if not.
     */    
    virtual bool setAttribute( const UString& aTargetId , 
                               AlfAttribute& aAttribute ) = 0; 


 
  /**
     * Sets a value of an static attribute.
     * This SetAttribute variant is for simple non animated attributes 
     * that only have name and value.
     *
     * If no value is present in passed attributevalue parameter,
     * an AlfAttributeException-exception
     * is thrown with EInvalidAttribute error code.
     *
     * @param aTargetId   The name of the target widget part, e.g. element class
     * @param aAttribName Name of the attribute.
     * @param aValue      Value of the attribute. Ownership is transferred
     * @return True if the attribute was supported, false if not.
     */
    virtual bool setAttribute( const UString& aTargetId, 
                               const UString& aAttribName, 
                               AlfAttributeValueType* aValue ) = 0;
 
   /**
     * Sets values of each attribute in given container to a specific target. 
     * The target is identified by using aTargetId parameter.
     *
     * If no value is present in an attribute in the container,
     * an AlfAttributeException-exception
     * is thrown with EInvalidAttribute error code.
     *
     * @param aTargetId  Name of the target widget part, e.g element class tag.
     * @param aAttributeContainer Reference attributeContainer, All attributes
     *        in the container are handled. The ownership is not transferred.
     * @return True if all attributes were supported, false if at least 1 attribute was not supported
     */    
    virtual bool setAttributeContainer( const UString& aTargetId , 
                               AlfAttributeContainer& aAttributeContainer ) = 0; 

		/**
     * Gets the attribute with the given name from specific target.
     * The returned attribute instance is owned by the widget and
     * should not be deleted.
     * Also the returned attribute instance should not be modified.
     * Use SetAttribute for that.
     *
     * @param aTargetId   The name of the target widget part, e.g. element class
     * @param aAttribName The name of the attribute.
     * @return A pointer to the attribute, or 0 if the attribute was not found.
     */
    virtual const AlfAttribute* getAttribute( const UString& aTargetId ,
                                              const UString& aAttribName ) const = 0;



    /**
     * Getter for the type identifier of this interface.
     *
     * @since S60 ?S60_versio
     * @return Identifier of this interface.
     */
    static inline const IfId& type()
        {
        return alfattributeowner::ident;
        }
    };

    } // namespace Alf

#endif // I_ALFATTRIBUTEOWNER_H