/*

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

*

*/

#if !defined(__EIKMENUP_H__)

#define __EIKMENUP_H__

#if !defined(__EIKBCTRL_H__)

#include <eikbctrl.h>

#endif

#if !defined(__EIKDEF_H__)

#include <eikdef.h>

#endif

#if !defined(__EIKSBOBS_H__)

#include <eiksbobs.h> // for TEikScrollEvent

#endif

#include <bidi.h>

// FORWARD DECLARATIONS

class MEikMenuObserver;

class CEikHotKeyTable;

class CEikMenuPaneTitle;

class CEikButtonBase;

class CEikScrollBarFrame;

class CEikScrollBar;

class TEikScrollBarModel;

class CGulIcon;

class CEikMenuPaneExtension ;

class CEikCba;

class CAknItemActionMenuData;

// CONSTANTS

const TInt KScaleableTextSeparator = 0x0001;

/**

  * A helper class for extending CEikMenuPaneItem without breaking binary 

  * compability.

  */

class CExtendedItemData : public CBase

    {

public:

    /**

     * Destructor.

     */

    ~CExtendedItemData();

public:

    /** Two packaked bitmaps: bitmap icon and mask for it. */

    CGulIcon* iIcon;

    /** Scalable text buffer. */

    HBufC* iScaleableText;    

    };

/**

 * The @c CEikMenuPaneItem class encapsulates the data needed to define a menu

 * pane item and provides some of the functionality required to display the 

 * item.

 *

 * @since ER5U

 */

class CEikMenuPaneItem : public CBase

    {

public:

    /** Struct to menu pane item. */

    struct SData

        {

        /** Nominal text length.*/

        enum { ENominalTextLength=40 };

        /** 

         * ID of the command to issue when the menu item using this @c SData is 

         * selected.

         */

        TInt iCommandId;

        /** Resource ID of a menu pane to cascade from this item. */

        TInt iCascadeId;

        /** 

         * Flags used internally by @c CEikMenuPane and accessible through 

         * functions such as @c CEikMenuPane::SetItemDimmed().

         */

        TInt iFlags;

        /** The text buffer displayed in the main area of the menu item. */

        TBuf<ENominalTextLength> iText; // less than this actually stored

        /** 

         * Additional descriptive text about the item. This is used by @c 

         * CEikMenuPane to display hotkey names.

         */

        TBuf<1> iExtraText;

        };

public:

    /**

     * C++ default constructor.

     */

    IMPORT_C CEikMenuPaneItem();

    /**

     * Destructor.

     */

    IMPORT_C ~CEikMenuPaneItem();

    /**

     * Sets a menu item icon. This replaces any icon already set for the menu

     * item.

     *

     * @param aIcon Menu item icon consisting of a picture bitmap and a mask 

     *        bitmap.

     */

    IMPORT_C void SetIcon(CGulIcon* aIcon);

    /**

     * Draws the menu item icon.

     * 

     * @param aGc Graphics context to which the icon is drawn.

     * @param aRect Rectangle in which the icon is drawn. 

     * @param aDimmed If @c ETrue the icon is drawn dimmed. 

     * @param aBitmapSpaceRequired Length of one side of the square required to 

     *        contain the bitmap.

     */

    IMPORT_C void DrawItemIcon(CWindowGc& aGc, 

                               TRect aRect, 

                               TBool aDimmed, 

                               TInt aBitmapSpaceRequired) const;

    /**

     * Construct an icon from bitmaps. 

     * 

     * Constructs a new icon for the menu item, taking ownership of the picture

     * bitmap aBitmap and the mask bitmap aMask unless the bitmaps are 

     * externally owned.

     * 

     * @param aBitmap Picture bitmap.

     * @param aMask Mask bitmap.

     */

    IMPORT_C void CreateIconL(CFbsBitmap* aBitmap, 

                              CFbsBitmap* aMask);

    /**

     * Gets a pointer to the menu item's icon picture bitmap. This does not 

     * imply transfer of ownership.

     * 

     * @return Picture bitmap.

     */

    IMPORT_C CFbsBitmap* IconBitmap() const;

    /**

     * Gets a pointer to the menu item's icon mask bitmap. This does not imply

     * transfer of ownership.

     * 

     * @return Mask bitmap.

     */

    IMPORT_C CFbsBitmap* IconMask() const;

    /**

     * Sets icon bitmap ownership.

     * Sets the menu item's icon bitmaps as externally owned if @c 

     * aOwnedExternally is @c ETrue.

     * 

     * @param aOwnedExternally If @c ETrue bitmaps are set as externally owned. 

     *        @c If EFalse bitmaps are set as not being externally owned. 

     */

    IMPORT_C void SetBitmapsOwnedExternally(TBool aOwnedExternally);

    /**

     * Sets the picture bitmap. Transfers ownership unless the bitmaps are 

     * already owned externally.

     * 

     * @param aBitmap Picture bitmap.

     */

    IMPORT_C void SetIconBitmapL(CFbsBitmap* aBitmap);

    /**

     * Sets the mask bitmap. Transfers ownership unless the bitmaps are already

     * owned externally.

     * 

     * @param aMask Mask bitmap.

     */

    IMPORT_C void SetIconMaskL(CFbsBitmap* aMask);

    /**

     * Returns scaleable text. If there isn't scaleable text available then

     * this method returns @c iData.iText.

     * 

     * @return Pointer to TPtrC object that contains scaleable text.

     */

    IMPORT_C TPtrC ScaleableText() const;

    /**

     * Sets scaleable text. @c iData.iText is set to first text version.

     * 

     * @param aText Scalable text.

     */

    IMPORT_C void SetScaleableTextL(const TDesC& aText);

private:

    inline void CreateExtendedDataBlock();

    inline TBool IsScaleableText(const TDesC& aText) const;

    TPtrC GetNominalText(const TDesC& aText);

public:

    /** The y position of the menu pane item. */

    TInt iPos;

    /** The menu pane item's hotkey text. */

    TInt iHotKeyCode;

    /** Information from an SData struct. */

    SData  iData;

private:

    CExtendedItemData* iExtendedData;

    };

inline void CEikMenuPaneItem::CreateExtendedDataBlock()

    {

    if (!iExtendedData)

        {

        TRAPD(err, ( iExtendedData = new (ELeave) CExtendedItemData() ) );

        }

    }

inline TBool CEikMenuPaneItem::IsScaleableText(const TDesC& aText) const

    {

    return aText.Locate( TChar( KScaleableTextSeparator ) ) != KErrNotFound;

    }

/**

 * Menu panes are opened by activating the menu title 

 * @c (CEikMenuPaneTitle / MENU_TITLE) which is displayed in the menu bar @c 

 * (CEikMenuBar / MENU_BAR). They can also be cascaded from a menu item @c

 * (CEikMenuPaneItem / MENU_ITEM) or launched by a menu button @c 

 * (CEikMenuButton). 

 *

 * Menu panes may be defined using a @c MENU_PANE resource.

 */

class CEikMenuPane : public CEikBorderedControl

    {

private:

    enum {ENothingSelected=-1};

    class CMenuScroller;

    friend class CMenuScroller;

    friend class CEikMenuPaneExtension;

public:

    /** The text to be displayed for a hotkey. */

    typedef TBuf<20> THotKeyDisplayText;

public:

    /**

     * This class provides a constructor to create an array of menu pane items

     * and a destructor to destroy an array of menu pane items.

     */

    class CItemArray:public CArrayPtrFlat<CEikMenuPaneItem>

        {

    public:

        /**

         * C++ default constructor that creates a flat array of menu pane 

         * items.

         */

        IMPORT_C CItemArray();

        /**

         * Destructor.

         */

        IMPORT_C ~CItemArray();

        /**

         * Appends @c CEikMenuPaneItem class object to array.

         *

         * @param aMenuItem The menu item to add.

         */        

        IMPORT_C void AddItemL(CEikMenuPaneItem* aMenuItem);

        };

public:

    /**

     * Destructor.

     */

    IMPORT_C ~CEikMenuPane();

    /**

     * C++ default constructor. Constructs a menu pane object with the 

     * specified observer.

     * 

     * @param aMenuObserver Menu observer.

     */

    IMPORT_C CEikMenuPane(MEikMenuObserver* aMenuObserver);

    /**

     * Handles 2nd base construction. Completes construction of a menu pane object. 

     * 

     * @param aOwner Menu pane owner ( for cascade menu ).

     * @param aEditMenuObserver Observer for the edit menu. In default this is 

     *        @c NULL.

     */

    IMPORT_C void ConstructL(CEikMenuPane* aOwner, 

                             MEikMenuObserver* aEditMenuObserver = NULL);

    /**

     * Destroys the menu pane's item array.

     */

    IMPORT_C void Reset();

public: // framework

    /**

     * From @c CcoeControl.

     *

     * Handles key events offered to the menu by the control environment and 

     * provides an appropriate implementation of @c 

     * CCoeControl::OfferKeyEventL(). 

     * 

     * @param aKeyEvent The key event. 

     * @param aType The type of key event: @c EEventKey, @c EEventKeyUp or @c 

     *        EEventKeyDown.

     */

    IMPORT_C TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,

                                         TEventCode aType);

    /**

     * From @c CcoeControl.

     *

     * Handles a pointer event on the menu.

     * 

     * @param aPointerEvent The pointer event to handle.

     */

    IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);

    /**

     * From @c CcoeControl.

     *

     * Gets the list of logical colours employed in the drawing of the control, 

     * paired with an explanation of how they are used. Appends the list into 

     * @c aColorUseList.

     * 

     * @since 005u

     * @param aColorUseList The list of colours paired with explanations.

     */

    IMPORT_C virtual void GetColorUseListL(

        CArrayFix<TCoeColorUse>& aColorUseList) const; 

    /**

     * From @c CcoeControl.

     *

     * Handles a change to the menu's resources which are shared across the

     * environment. For example, colours or fonts.

     * 

     * @since 005u

     * @param aType The type of resource that has changed.

     */

    IMPORT_C virtual void HandleResourceChange(TInt aType);         // not available before Release 005u

private: // from base class

    /**

     * Not implemented.

     * 

     * @param Not used.

     * @return NULL

     */

    IMPORT_C void* ExtensionInterface( TUid aInterface );

public: // from MCoeInputObserver

    /**

     * From @c CCoeControl.

     *

     * Gets the list box’s input capabilities as set through the list box flags.

     *

     * @return List box input capabilities.

     */

    IMPORT_C TCoeInputCapabilities InputCapabilities() const;

protected: // from base class

    /** 

     * From @c CCoeControl

     * 

     * Draw a control called by window server. 

     *

     * All controls, except blank controls, should implement this function. The

     * default implementation draws a blank control. This function is used for

     * window server-initiated redrawing of controls, and for some 

     * application-initiated drawing. It should be implemented by each control,

     * but  is only called from within @c CCoeControl's member functions, and 

     * not from the derived class. For this reason it is a private member 

     * function of @c CCoeControl.

     *

     * The rectangle aRect indicates the region of the control that needs to be

     * redrawn. The implementation of @c Draw() must always draw to every pixel 

     * within this rectangle.

     *

     * @param aRect The region of the control to be redrawn. 

     *        Co-ordinates are relative to the control's origin (top left 

     *        corner). Optional, not used currently.

     */

    IMPORT_C void Draw(const TRect& aRect) const;

    /**

     * From @c CCoeControl.

     *

     * Takes any action required when the menu pane gains or loses focus, 

     * to change its appearance for example.

     * 

     * @param aDrawNow If @c EDrawNow the menu pane is redrawn. If @c 

     *        ENoDrawNow the menu pane is not redrawn.

     */

    IMPORT_C void FocusChanged(TDrawNow aDrawNow);

    /**

     * From @c CCoeControl.

     *

     * Constructs the menu pane using the specified resource reader.

     * Fills the menu item array with the list of menu items provided by the

     * resource file.

     * 

     * @param aReader The resource reader to use.

     * @leave KErrNoMemory Memory allocation failure earlier construction.     

     */

    IMPORT_C void ConstructFromResourceL(TResourceReader& aReader);

public: // new functions

    /**

     * Adds a menu item dynamically by creating a new menu item, setting its 

     * data to @c aMenuItem and appending it to the pane's menu item array. 

     * Updates the menu's scroll bar to take account of the new item.

     * 

     * @param aMenuItem The menu item to add.

     *        NOTICE that @c SData is a structure so all fields in it should be

     *        set to avoid any unexpected behaviour.

     */

    IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem);

    /**

     * Adds a menu item dynamically by creating a new menu item, setting its 

     * data to @c aMenuItem and inserting it into the pane's menu item array. 

     * Updates the menu's scroll bar to take account of the new item.

     * 

     * @param aMenuItem The menu item to add. NOTICE that @c SData is a 

     *        structure so all fields in it should be set to avoid any 

     *        unexpected behaviour.

     * @param aPreviousId The id of the item after which the new item should be

     *        added.

     */

    IMPORT_C void AddMenuItemL(const CEikMenuPaneItem::SData& aMenuItem, 

                               TInt aPreviousId);

    /**

     * Adds menu items dynamically by creating new menu items from resource 

     * and inserts them into the pane's menu item array. 

     * 

     * @param aResourceId The ID of the resource for the menu item.

     * @param aPreviousId The ID of the previous menu item, after which this 

     *        newly created item should be added.

     * @param aAddSeperator Shouldn't be used as separator is not not supported

     *        anymore.

     */

    IMPORT_C void AddMenuItemsL(TInt aResourceId, 

                                TInt aPreviousId = 0,

                                TBool aAddSeperator = EFalse);

    /**

     * Deletes the specified item in the menu pane.

     * 

     * @param aCommandId The ID for the item to be deleted.

     */

    IMPORT_C void DeleteMenuItem(TInt aCommandId);

    /**

     * Deletes the items between specified items.

     * 

     * @param aStartIndex The index of the item after which items should be 

     *        deleted.

     * @param aEndIndex The index of the item up to which items should be 

     *        deleted.

     */

    IMPORT_C void DeleteBetweenMenuItems(TInt aStartIndex, 

                                         TInt aEndIndex);

    /**

     * Gets a reference to the data in the specified menu item.

     * 

     * @param aCommandId The command ID of the menu item for which data is 

     *        obtained.

     * @return Reference to struct that contains command id.

     */

    IMPORT_C CEikMenuPaneItem::SData& ItemData(TInt aCommandId);

    /**