/*

* 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 used by design tools to get a description of the control.

*

*/

#ifndef I_ALFWIDGETCONTROLDESCRIPTOR_H

#define I_ALFWIDGETCONTROLDESCRIPTOR_H

#include <e32base.h>

#include <alf/ialfinterfacebase.h>

namespace Alf

    {

/**

 *  An interface used by design tools to get a description of the control.

 *  The description may include a generic description of the control, and

 *  descriptions of the event handlers and elements used by the control.

 *

 *  @lib alfwidgetmodel.lib

 *  @since S60 ?S60_version

 *  @status Draft

 */

class IAlfWidgetControlDescription : public IAlfInterfaceBase

    {

public:

    /**

     * Get the description of the control.

     *

     * @since S60 ?S60_version

     * @return The description of the control.

     */

    virtual const TDesC8& controlDescription() const = 0;

    /**

     * Get the number of required elements in the control.

     *

     * @since S60 ?S60_version

     * @return The number of required elements.

     */

    virtual int numRequiredElements() const = 0;

    /**

     * Get the name of a required element by index.

     *

     * @since S60 ?S60_version

     * @param aIndex The index of the element.

     * @return The name of the element at the given index.

     */

    virtual const TDesC8& elementName(int aIndex) const = 0;

    /**

     * Get the description of a required element by index.

     *

     * @since S60 ?S60_version

     * @param aIndex The index of the element.

     * @return The description of the element at the given index.

     */

    virtual const TDesC8& elementDescription(int aIndex) const = 0;

    /**

     * Get the number of required event handlers in the control.

     *

     * @since S60 ?S60_version

     * @return The number of required event handlers.

     */

    virtual int numRequiredEventHandlers() const = 0;

    /**

     * Get the event id of a required event handler by index.

     * The event id may be a custaom event id or a key event id.

     *

     * @since S60 ?S60_version

     * @param aIndex The index of the event handler.

     * @return The name of the event handler at the given index.

     */

    virtual uint eventHandlerId(int aIndex) const = 0;

    /**

     * Determine the type of a required event handler by index.

     * The event type may be a custom event or a key event.

     *

     * @note Pointer event handlers cannot be identified without

     * an associated custom event id. Therefore, pointer event handlers

     * are visible as custom event handlers.

     *

     * @since S60 ?S60_version

     * @param aIndex The index of the event handler.

     * @return <code>ETrue</code> if the event handler is a key event handler.

     *         <code>EFalse</code> if the event handler is a custom event handler.

     */

    virtual bool keyEventHandler(int aIndex) const = 0;

    /**

     * Get the name of a required event handler by index.

     *

     * @since S60 ?S60_version

     * @param aIndex The index of the event handler.

     * @return The name of the event handler at the given index.

     */

    virtual const TDesC8& eventHandlerName(int aIndex) const = 0;

    /**

     * Get the description of a required event handler by index.

     *

     * @since S60 ?S60_version

     * @param aIndex The index of the event handler.

     * @return The description of the event handler at the given index.

     */

    virtual const TDesC8& eventHandlerDescription(int aIndex) const = 0;

    };

    } // namespace Alf

#endif // I_ALFWIDGETCONTROLDESCRIPTOR_H

// End of File