/*

* 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:  Visual class for alfred widget model.

      This class queries the visual by name and ID.

*

*/

#ifndef ALFREFERENCETOVISUAL_H

#define ALFREFERENCETOVISUAL_H

//INCLUDES

#include <osn/osndefines.h>

#include <osn/ustring.h>

// FORWARD DECLARATIONS

class CAlfControl;

class CAlfVisual;

using namespace osncore;

namespace Alf

    {

class CAlfWidgetControl;

/** @class AlfReferenceToVisual alfreferencetovisual.h "alf/alfreferencetovisual.h"

 * A class for finding a specific visual according to

 * the name of the visual, name of the parent element,

 * and the associated data ID. The number of visual

 * trees created by an element may depend on the data.

 * Therefore, the visual structure is not always known

 * beforehand. CAlfControl::FindElement() and MAlfElement::FindVisual

 * can be used to find elements and visuals even in dynamic

 * conditions.

 *

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 *  @status Draft

 */

class AlfReferenceToVisual

    {

public:

    /**

     * constructor.

     *

	 * @exception std::bad_alloc     

     * @since S60 ?S60_version

     * @param aElementName The name of the element that is responsible

    *      for creating the visual.

     * @param aVisualName The name of the visual.

     * @param aUseDataID Deprecated and not used. The given data ID is always

     * used when resolving the visual. Only if the visual is not found with

     * the given data ID, then the data ID zero is tested for global visuals.

     * @return New object.

     */

    OSN_IMPORT static AlfReferenceToVisual* create(

        const char* aElementName,const char* aVisualName, bool aUseDataID);

    /** Destructor. No derived classes, therefore not virtual. */

    OSN_IMPORT ~AlfReferenceToVisual();

    /**

     * Find the referenced visual according to the given data ID.

     *

     * @exception osncore::AlfVisualException Thrown with the error code osncore::ECommonError\n 

     *										  when some operation performed on visual fails.

     * @since S60 ?S60_version

     * @param aControl  The control containing the associated element.

     * @param aDataID  The data ID used to create the visual. The caller

     *      is responsible for determining what data ID

     *      is related to this reference. If the visual is not found with

     * the given data ID, then the data ID zero is tried for global visuals.

     * @return The resolved visual.

     */

    OSN_IMPORT CAlfVisual* resolve(CAlfWidgetControl& aControl, unsigned int aDataID);

    /**

     * Finds the referenced visual according to given pointer to visual

     *

        * @since S60 ?S60_version

        * @param aControl      The control containing the associated element.

        * @param aSourceVisual  Pointer to visual that needs to be queried.

        */

    OSN_IMPORT CAlfVisual* resolve(CAlfWidgetControl &aControl, CAlfVisual* aSourceVisual);

private:

    /**

     * constructor

     */

    AlfReferenceToVisual(const char* aElementName,const char* aVisualName, bool aUseDataID);

private:

    // The element name. Owned.

    UString mElementName;

    // The visual name. Owned.

    UString mVisualName;

    // The associated data ID.

    bool mUseDataID;

    };

    } // namespace Alf

#endif //ALFREFERENCETOVISUAL_H