/*

* Copyright (c) 1999 - 2003 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:

*

*/

#ifndef LCDUI_H

#define LCDUI_H

/**

 * @file

 * @publishedPartner

 * @released

 *

 * This header defines the interfaces that must be implemented for LCDUI.

 * It should be read in conjunction with the MIDP 2.0 specification which

 * will contain more information about the enumerations, for example.

 *

 * The MMIDComponentFactory interface, defined at the end of this file, is

 * the logical starting point to read this file.

 *

 * Most methods can be assumed to be invoked in the "server thread" where a

 * UI environment and its active scheduler will be present. Any method

 * marked as "client side" may also be invoked from a thread that does not have

 * a UI environment or activescheduler. These methods should ensure any shared

 * data strucutures that could be accessed by both the server thread and client

 * thread(s) are protected by suitable locking or atomic update strategies.

 *

 * "Framework" refers to the underlying Java Runtime Environment which invokes

 * the methods defined in these interfaces at the appropriate time and which the

 * the implementor of these interfaces need have no knowledge of.

 * "Implementation" refers to the implementation of these interfaces in the client DLL.

 */

#include <e32def.h>

#include <badesca.h>

#include <gdi.h>

#include <w32std.h>

#ifdef RD_JAVA_NGA_ENABLED

#include <EGL/egltypes.h>

#include "monitor.h"

#endif // RD_JAVA_NGA_ENABLED

class MMIDDisplayable;

class MMIDAlert;

class MMIDForm;

class MMIDList;

class MMIDTextBox;

class MMIDItem;

class MMIDImageItem;

class MMIDStringItem;

class MMIDDateField;

class MMIDGauge;

class MMIDTextField;

class MMIDChoiceGroup;

class MMIDTicker;

class MMIDCommand;

class MMIDUtils;

class MMIDEnv;

class MMIDBufferProcessor;

class MMIDFont;

class MMIDImage;

class CFont;

class CCoeControl;

class MMIDToLcduiObserver;

class MDirectContainer;

class MUiEventConsumer;

class MMIDTextEditor;

class MMIDCanvasGraphicsItem;

class MMIDCanvasGraphicsItemPainter;

class MMIDLcduiEventConsumer;

/**

 * @internalComponent

 */

typedef TAny* TJavaPeer;

/**

 * Namespaces including constant definitions for MIDlet suite attribute names and attributes values.

 */

namespace LcduiMidletAttributes

{

_LIT(KAttribMIDletName,                      "MIDlet-Name");

_LIT(KAttribMIDletVersion,                   "MIDlet-Version");

_LIT(KAttribMIDletVendor,                    "MIDlet-Vendor");

_LIT(KAttribUIEnhancement,                   "Nokia-UI-Enhancement");

_LIT(KAttribOrigDisplaySize,                 "Nokia-MIDlet-Original-Display-Size");

_LIT(KAttribTargetDisplaySize,               "Nokia-MIDlet-Target-Display-Size");

_LIT(KAttribNoExitKey,                       "Nokia-MIDlet-No-Exit");

_LIT(KAttribFlipClose,                       "Nokia-MIDlet-Flip-Close");

_LIT(KAttribBackgroundEvent,                 "Nokia-MIDlet-Background-Event");

_LIT(KAttribAllowScalingOnOrientationSwitch, "Nokia-MIDlet-Canvas-Scaling-Orientation-Switch");

_LIT(KAttribS60SelectionKeyCompatibility,    "Nokia-MIDlet-S60-Selection-Key-Compatibility");

_LIT(KAttribAppOrientation,                  "Nokia-MIDlet-App-Orientation");

_LIT(KAttribPointerEventSuppressorValues,    "Nokia-MIDlet-Tap-Detection-Options");

_LIT(KAttribOskSoftkeysInQwerty,             "Nokia-MIDlet-On-Screen-Softkeys-Position");

}

namespace LcduiMidletAttributeValues

{

_LIT(KUIEnhMediaKeys,          "musickeyssupported");

_LIT(KUIEnhCanvasBackground,   "canvashasbackground");

_LIT(KUIEnhPopUpTextBox,       "popuptextbox");

_LIT(KUIEnhFullScreenTextBox,  "fullscreentextbox");

_LIT(KTrueValue,               "true");

_LIT(KPauseValue,              "pause");

_LIT(KRunValue,                "run");

_LIT(KPortraitValue,           "portrait");

_LIT(KLandscapeValue,          "landscape");

_LIT(KPositionBottom,          "bottom");

_LIT(KPositionRight,           "right");

}

/**

 *

 * Base class of all LCDUI objects. Concrete classes always implement a

 * subclass of this interface.

 *

 */

class MMIDComponent

{

    friend class CMIDToolkit;

public:

    /**

     * Enumeration of the component type

     */

    enum TType

    {

        EUnknown,

        EImageItem,

        EStringItem,

        EGauge,

        ETextField,

        EChoiceGroup,

        EDateField,

        ECustomItem,

        ESpacer,

        ECanvas,

        EGameCanvas,

        EGraphics,

        EAlert,

        EForm,

        EList,

        ETextBox,

        ETicker,

        EFont,

        ECmd,

        EDisplayableContainer,

        EImage,

        ESprite,

        ETiledLayer,

        EDefaultBackground,

        ECanvasTextEditor,

        ECanvasGraphicsItem,

        ECanvasGraphicsItemPainter,

        ENumTypes   // Add types before ENumTypes

    };

public:

    /**

     * Invoked by the framework to clean up any  resources used by the

     * implementation. Typically, the implementation will do "delete this"

     * but is clearly not restricted to this.

     */

    virtual void Dispose() = 0;

    /**

     * This is an aid to the implementation - it is not used by the framework.

     * Not particularly good O-O, but the example implementation makes

     * considerable use of this method to good simplification.

     */

    virtual TType Type() const

    {

        return EUnknown;

    }

    /**

     * Returns buffer processor associated with this component (if any).

     */

    virtual MMIDBufferProcessor* Processor()

    {

        return NULL;

    }

private:

    /**

     * Inaccessible to the implementation, used by the framework for keeping

     * track of the associated Java object.

     */

    TJavaPeer iPeer;

};

#ifdef RD_JAVA_NGA_ENABLED

/**

 * NGA tension to the Component interface

 * @since S60 9.2

 */

class MMIDComponentNgaExtension : public MMIDComponent

{

public:

    /**

     * Update EGL content. Called by M3G to request LCDUI canvas to update

     * EGL surface with 2D content.

     * @since S60 9.2

     */

    virtual void UpdateEglContent() = 0;

    /**

     * Checks if EGL is available.

     * @return <code>ETrue</code> if EGL exists.

     * @since S60 9.2

     */

    virtual TBool IsEglAvailable() const = 0;

    /**

     * Gets and binds EGL surface.

     * @return surface handle. <code>EGL_NO_SURFACE</code> is

     * returned if binding is not possible.

     * @since S60 9.2

     * @see MMIDComponentNga#ReleaseEglSurface

     */

    virtual EGLSurface BindEglSurface() = 0;

    /**

     * Release EGL surface

     * @since S60 9.2

     */

    virtual void ReleaseEglSurface() = 0;

    /**

     * Update offscreen bitmap i.e. canvas frame buffer

     * @param aForced   If true, off-screen bitmap is updated without

     *                  checking Canvas type (Canvas/GameCanvas)

     * @since S60 9.2

     */

    virtual void UpdateOffScreenBitmapL(TBool aForced) = 0;

    /**

     * Fills EGL surface

     * @param aRect The area to be filled

     * @param aColor The fill color

     * @since S60 9.2

     */

    virtual TBool FillEglSurface(const TRect& aRect, const TRgb& aColor) = 0;

};

#endif // RD_JAVA_NGA_ENABLED

/**

 *

 * Interface to Command

 *

 */

class MMIDCommand : public MMIDComponent

{

public:

    /**

     * This is the type passed into the plugin factory CreateCommand method

     */

    enum TCommandType

    {

        EScreen=1,

        EBack,

        ECancel,

        EOk,

        EHelp,

        EStop,

        EExit,

        EItem

    };

    /**

     * Native command peer identifiers.

     */

    enum TCommandID

    {

        ENullCommand=0,             // null

        EAlertDismissCommand=1,     // Alert.DISMISS_COMMAND

        EListSelectCommand=2,       // List.SELECT_COMMAND

        EUserCommandBase=4          // Base id for application commands.

    };

public:

    /**

     * Returns the human readable displayable text associated with the command.

     * @return  A descriptor containing the text.

     */

    virtual const TDesC& Label() const = 0;

    virtual TCommandType CommandType() const = 0;

    virtual TInt Priority() const = 0;

    virtual TInt Id() const = 0;

public:

    /**

     * Returns the component type.

     * @return  The component type as a MMIDComponent::TType enum.

     */

    TType Type() const

    {

        return ECmd;

    }

};

/**

 *

 * Base class of all Items.

 *

 * MMIDForm::RefreshItemL() is generally called following any method calls

 * which result in the item changing its appearance, e.g. size, label, layout or

 * content changed which may mean that the Item's min size has changed. Hence

 * the concrete implementation of Item does not need to refresh the Form's

 * appearance itself.

 *

 */

class MMIDItem : public MMIDComponent

{

public:

    /**

     * Used to describe the positioning of Item within the form.

     * Used by the form layout.

     */

    enum TLayout

    {

        EDefault = 0,

        ELeft,

        ERight,

        ECenter,

        //

        ETop = 0x10,

        EBottom = 0x20,

        EVerticalCenter = 0x30,

        //

        ENewLineBefore = 0x100,

        ENewLineAfter = 0x200,

        //

        EShrink = 0x400,

        EExpand = 0x800,

        EVerticalShrink = 0x1000,

        EVerticalExpand = 0x2000,

        ELayout2 = 0x4000

    };

    /**

     * Used only in StringItem & ImageItem

     */

    enum TAppearance

    {

        EPlain,     /** Item has normal appearance */

        EHyperLink, /** Item appears as a hyperlink */

        EButton     /** Item appears as a button */

    };

public:

    /**

     * Since the following methods are followed by MMIDForm::RefreshItemL(),

     * a reasonable implementation strategy could be to just cache the values

     * and calculate/redisplay on the refresh. These methods are invoked server

     * side, nonetheless, so the alternative strategy can be followed.

     */

    /**

     * Sets the Item's label.

     * @param   aLabel

     *          A descriptor containing the label text.

     */

    virtual void SetLabelL(const TDesC& aLabel) = 0;

    /**

     * Sets the Item's layout.

     * @param   aLayout

     *          A TLayout enumeration describing the desired layout.

     */

    virtual void SetLayoutL(TLayout aLayout) = 0;

    /**

     * Commands are always referred to by their index. This is their position in

     * an array where 0 is the first command added and (number of commands -1)

     * is the last added. Removing commands has the obvious re-numbering of commands

     * which follow in order. In effect, the implementation should store them in a

     * similar structure regardless of how they are ordered on the display.

     *

     * If the item is actually visible on the display (e.g. CBA button), and

     * this call affects the set of visible commands, the implementation

     * should update the display as soon as it is feasible to do so.

     */

    /**

     * Adds a command to the list at the specified index. If aIndex is zero,

     * the command is added at the head of the list.

     * @param   aIndex

     *          The position at which to insert the command.

     * @param   aCommand

     *          The command to add.

     */

    virtual void AddCommandL(MMIDCommand* aCommand) = 0;

    /**

     * Removes the command specified by the given index.

     * @param   aIndex

     *          The position from which to remove the command.

     */

    virtual void RemoveCommand(MMIDCommand* aCommand) = 0;

    /**

     * Sets the default command to be aIndex, where aIndex is the index of a command

     * which has already been added via AddCommandL(). If aIndex = -1, then

     * there should be no default command set.

     * @param   aIndex

     *          The index of the command to set.

     */

    virtual void SetDefaultCommand(MMIDCommand*) = 0;

    /**

     * aSize could have either/both iWidth and iHeight = -1.

     * This means that the width/height should be computed based

     * on the item's contents .

     * @param   aSize

     *          Structure representing the preferred size.

     */

    virtual void SetPreferredSizeL(const TSize& aSize) = 0;

    /*

     * Return the sizes as per MIDP 2.0 spec

     */

    /**

     * Returns the Item's preferred size.

     * @return  The preferred size.

     */

    virtual TSize PreferredSize() const = 0;

    /**

     * Returns the Item's minimum size.

     * @return  The minimum size.

     */

    virtual TSize MinimumSize() const = 0;

};

/**

 * Displayable container window created before the actual content (e.g. List/Canvas etc)

 * is called before CreateListL() in the factory).

 *

 * It is envisioned that the concrete implementation of MMIDDisplayable

 * is a container for the actual Displayable in which to hang commands, title bar

 * etc.

 *

 * Do not subclass from both MMIDDisplayable and one of the content types (e.g. MMIDList, MMIDForm)

 * in the same implementation class.

 *

 */

class MMIDDisplayable : public MMIDComponent

{

public:

    /**

     * Sets the Displayable's title.

     * @param   aTitle

     *          A descriptor containing the title text, may be NULL indicating

     *          that the displayable should hide the titlebar.

     */

    virtual void SetTitleL(const TDesC* aTitle) = 0;

    /**

     * Sets the Displayable's ticker, replacing any previous ticker.

     * The Ticker could be null, in which case no ticker is displayed.

     * @param   aTicker

     *          The ticker to associate with the Displayable.

     */

    virtual void SetTickerL(MMIDTicker* aTicker) = 0;

    /**

     * Returns the current ticker, or null if there is none set

     * @return  The ticker.

     */

    virtual MMIDTicker* Ticker() const = 0;

    /*

     * Commands are always referred to by their index. This is their position in

     * an array. The Commands will be inserted into the array in order of priority.

     * Removing commands has the obvious re-numbering of commands which follow in

     * order. In effect, the implementation should store them in a similar structure.

     *

     * If the item is actually visible on the display (e.g. CBA button), and

     * this call affects the set of visible commands, the implementation

     * should update the display as soon as it is feasible to do so.

     *

     * Adds a command to the list at the specified index. If aIndex is zero,

     * the command is added at the head of the list.

     * @param   aIndex

     *          The position at which to insert the command.

     * @param   aCommand

     *          The command to add.

     */

    virtual void AddCommandL(MMIDCommand* aCommand) = 0;

    /**

     * Removes the command specified by the given index.

     * @param   aIndex

     *          The position from which to remove the command.

     */

    virtual void RemoveCommand(MMIDCommand* aCommand) = 0;