/*

* 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(__EIKSBFRM_H__)

#define __EIKSBFRM_H__

#include <lafpublc.h>

#if !defined(__AKNSCRLB_H__)

#include <aknscrlb.h>

#endif

class CEikCba;

/**

 * Enables setting of the frame layout for a scroll bar.

 */

class TEikScrollBarFrameLayout

    {

public:

    /** 

     * Determines whether the client rectangle or the inclusive rectangle

     * remains constant.

     */

    enum TTilingMode

        {

        /** The client rectangle remains constant. */

        EClientRectConstant,

        /** The inclusive rectangle remains constant. */

        EInclusiveRectConstant

        };

public:

    /**

     * C++ default constructor.

     */

    IMPORT_C TEikScrollBarFrameLayout();

    /**

     * Sets all inclusive margins.

     *

     * @param aMargin The value to use for all inclusive margins.

     */

    IMPORT_C void SetInclusiveMargin(TInt aMargin);

    /**

     * Sets all client margins. These surround the client rectangle which is

     * the client area viewport onto the larger canvas to be scrolled.

     *

     * @param aMargin The value to use for all client margins.

     */

    IMPORT_C void SetClientMargin(TInt aMargin);

public:

    /** The inclusive margin (in twips or pixels). */

    TMargins iInclusiveMargin;

    /** 

     * The amount of screen movement performed when the nudge button is 

     * pressed.

     */

    TMargins iClientMargin;

    /** 

     * The amount of screen movement performed when the nudge button is

     * pressed.

     */

    TSize iClientAreaGranularity;

    /** 

     * Determines whether the client rectangle, or the inclusive rectangle,

     * remains constant.

     */

    TTilingMode iTilingMode;

    };

class CEikCornerWindow;

class CEikScrollBarFrameExtension;

/**

 * The scroll bar frame is a control assemblage manager that relates a control,

 * or control body, to two scroll bars and a corner window. A corner window is

 * that part of the screen that is common to both the horizontal, and the 

 * vertical elements of a scroll bar.

 *

 * This class helps with access to, and set up of, scroll bars and also with 

 * the layout of the scrolled control or control body. A scroll bar frame is 

 * not a control, but it does implement the standard control composite pattern

 * to manage the assemblage.

 */

class CEikScrollBarFrame : public CBase

    {

public:	// enums 

    DECLARE_TYPE_ID(0x101F8672)   

    /** Defines the scroll bar’s visibility.*/

    enum TScrollBarVisibility

        {

        /** Scroll bar not visible.*/

        EOff,

        /** Scroll bar visible.*/

        EOn,

        /** Scroll bar visible if required.*/

        EAuto

        };

    /** Defines the type of scroll bar.*/	

    enum TScrollBarType

        {

        /** Scroll bar complete with shaft. Not used.*/

        ENormalScrollBar =0x0,

        /** Floating arrow head scroll bar, without shaft. Legacy type. */

        EArrowHead =0x200,

        /** Spanned scroll bar. */

        EDoubleSpan =0x400

        };

    /** Defines where the scroll bar is located. */		

    enum TScrollBarSide

        {

        /** 

         * Scroll bar located at the bottom, or to the right of the scroll bar

         * frame.

         */

        EBottomOrRight =0x0,

        /** 

         * Scroll bar located at the top, or to the left of the scroll bar

         * frame.

         */

        ETopOrLeft =0x800

        };

    /** Determines how the scroll bar frame manages scroll bars.*/

    enum TScrollBarManagement 

        {

        /** 

         * The scroll bar frame creates, destroys and recreates, scroll bars

         * according to the visibility mode. The scroll bar frame also acts as

         * an intermediary with its owning control so that the scroll bars can

         * be treated as component controls.

         */

        EComponent                  ,//=SLafScrollBarFrame::EComponent,

        /** 

         * The scroll bar frame creates, destroys and recreates, scroll bars 

         * according to the visibility mode. In this case, the scroll bars are

         * not treated as component controls. Instead, the scroll bars are 

         * geometry managed in windows floating above the control window and

         * their position is determined in relation to the frame’s position on

         * the screen.

         */

        EFloating                   ,//=SLafScrollBarFrame::EFloating,

        /** 

         * The scroll bar frame uses the central application scroll bar as held

         * in the environment. This scroll bar is neither owned by the frame 

         * nor treated as a component control of the frame’s owner.

         */

        EApplicationScrollBar       //=SLafScrollBarFrame::EApplicationScrollBar

        };

    /**

     * Defines that is the horizontal or the vertical (spanned) scroll bar

     * visible. Applicaple  only for spanned scroll bars.

     */

    enum TScrollBarFrameFlags

        {

        /** Horizontal spanned scroll bar visible. */

        EHVisible           =0x01,

        /** Vertical spanned scroll bar visible. */

        EVVisible           =0x02,

        /** 

         * Enables nudge buttons in touch devices. This flag MUST

         * be set before the creation of the doublespan scrollbar.

         */

        EEnableNudgeButtons = 0x04,

        /** 

         * Disables expanded touch area, which is on by default

         * in touch devices. This flag MUST be set before the

         * creation of the doublespan scrollbar.

         */

        EDisableExpandedTouchArea = 0x08      

        };

private:

    enum TMarginsAdjustmentMode

        {

        EGrow,

        EShrink

        };

public:	// specific

    /**

     * C++ default constructor.

     */

    CEikScrollBarFrame(){}

    /**

     * Constructor. Constructs a scroll bar frame object.

     *

     * @param aParentWindow The scroll bar’s parent control.

     * @param aObserver The scroll bar observer.

     * @param aPreAlloc Not used.

     */  	

    IMPORT_C CEikScrollBarFrame(CCoeControl* aParentWindow, 

                                MEikScrollBarObserver* aObserver, 

                                TBool aPreAlloc=EFalse);

    /**

     * Destructor.

     */  

    IMPORT_C ~CEikScrollBarFrame();

    /**

     * Constructor. Internal only to Eikcoctl.lib use. Parameter @c aDoubleSpan

     * offers possibility to optimize scroll bar loading (if @c ETrue,

     * arrowhead scroll bar will never be loaded).

     *

     * @since S60 3.0

     * @param aParentWindow The scroll bar’s parent control.

     * @param aObserver The scroll bar observer.

     * @param aPreAlloc Not used.

     * @param aDoubleSpan If @c ETrue, spanned scroll bar is created.

     */     

    CEikScrollBarFrame(CCoeControl* aParentWindow, 

                       MEikScrollBarObserver* aObserver, 

                       TBool aPreAlloc, 

                       TBool aDoubleSpan);

    /**

     * Initializes a new @c CEikScrollBarFrameExtension object.

     *

     * @since S60 3.0

     * @param aParentWindow The scroll bar’s parent control.

     * @param aObserver The scroll bar observer.

     */

    void InitExtension(CCoeControl* aParentWindow, 

                       MEikScrollBarObserver* aObserver);

    /**

     * Forces any scroll bars and the corner window if it is visible to be 

     * redrawn.

     */     

    IMPORT_C void DrawScrollBarsNow() const;

	/**

     * Tell scroll bars and the corner window to redraw if it is visible

     */     

    void DrawScrollBarsDeferred() const;

    /**

     * Sets the visibility state for both the horizontal and the vertical scroll

     * bars. This is used when tiling.

     *

     * @param aHVisibility Horizontal scroll bar visibility.

     * @param aVVisibility Vertical scroll bar visibility.

     */     

    IMPORT_C void SetScrollBarVisibilityL(TScrollBarVisibility aHVisibility, 

                                          TScrollBarVisibility aVVisibility);

    /**

     * Determines the vertical scroll bar’s visibility. @c 

     * CEikScrollBarFrame::ScrollBarVisibility @c 

     * (CEikScrollBar::TOrientation aOrientation) can be used instead of this

     * method.

     * 

     * @return Visibility for vertical scroll bar.

     */     

    inline TScrollBarVisibility VScrollBarVisibility() const;

    /**

     * Sets scrollbar observers.

     *

     * @param aObserver The scroll bar observer. 

     */     

    IMPORT_C void SetScrollBarFrameObserver(MEikScrollBarObserver* aObserver);

    // Model setting. 

    /**

     * Sets the vertical scrollbar mode. Does not actually draw anything until 

     * the thumb or focus setting functions are called.

     *

     * @param aVModel Model for the vertical scrollbar.

     * @return @c EFalse.

     */     

    IMPORT_C TBool Tile(TEikScrollBarModel* aVModel);

    /**

     * Tiles the client area and the scroll bars managed by the frame. The 

     * scroll bars are set up according to the scroll bar models; @c aHModel and

     * @c aVModel. Ownership is not transferred as a result of passing these

     * parameters as pointers. The result of tiling geometry management is 

     * observable through the two rectangles @c aClientRect and @c 

     * aInclusiveRect. Depending on the tiling layout @c aLayout and the scroll 

     * bar visibility settings, either of these rectangles can be made constant

     * and the other rectangle adjusted accordingly.

     *

     * For @c EArrowhead type scrollbar the layout is always fixed, it cannot be

     * altered by using this method.

     *

     * For @c EDoublespan type scrollbar the layout can be set also with two 

     * helper methods from the @c AknLayoutUtils class:

     *

     * @code

     * AknLayoutUtils::LayoutVerticalScrollBar(

     *           CEikScrollBarFrame* aScrollBarFrame, 

     *           const TRect& aControlParent, 

     *           const TAknWindowLineLayout& aLayout);

     * AknLayoutUtils::LayoutHorizontalScrollBar(

     *           CEikScrollBarFrame* aScrollBarFrame, 

     *           const TRect& aControlParent, 

     *           const TAknWindowLineLayout& aLayout);

     * @endcode

     *   

     * @param aHModel Horizontal scroll bar model.

     * @param aVModel Vertical scroll bar model.

     * @param aClientRect Client rectangle.

     * @param aInclusiveRect A rectangle that includes the area to be scrolled 

     *        and the scroll bars themselves.

     * @param aLayout Tiling layout.

     * 

     * @return @c ETrue if the non-constant rectangle is adjusted, otherwise @c 

     *         EFalse.

     */     

    IMPORT_C TBool TileL(TEikScrollBarModel* aHModel, 

                         TEikScrollBarModel* aVModel,

                         TRect& aClientRect,

                         TRect& aInclusiveRect,

                         const TEikScrollBarFrameLayout& aLayout);

    /**

     * Moves the scroll bar thumbs by the specified amounts. This updates the 

     * scroll bars after an external scroll. The values of the parameters should

     * be supplied in terms of the horizontal and vertical scrolling models 

     * respectively. The scrolling models are presumed not to have changed 

     * spans.

     *

     * @param aDeltaX The amount to move the horizontal scroll bar.

     * @param aDeltaY The amount to move the vertical scroll bar.

     */     

    IMPORT_C void MoveThumbsBy(TInt aDeltaX, TInt aDeltaY);

    /**

     * Moves the horizontal scroll bar thumb to the position @c aHorizThumbPos.

     * This function is used to update the scroll bar after an external scroll.

     * The value of @c aThumbPos should be supplied in terms of the scrolling

     * model, which is presumed not to have changed spans.

     * 

     * @param aHorizThumbPos The required thumb position.

     */     

    IMPORT_C void MoveHorizThumbTo(TInt aHorizThumbPos);

    /**

     * Moves the vertical scroll bar thumb to the position @c aVertThumbPos. 

     * This function is used to update the scroll bar after an external scroll.

     * The value of aThumbPos should be supplied in terms of the scrolling 

     * model, which is presumed not to have changed spans.

     * 

     * @param aVertThumbPos The required thumb position.

     */     

    IMPORT_C void MoveVertThumbTo(TInt aVertThumbPos);

    /**

     * Moves the vertical scroll bar thumb to the position @c aFocusPosition. 

     * This function is used to update the scroll bar after an external scroll. 

     * The value of @c aFocusPosition should be supplied in terms of the 

     * scrolling model, which is presumed not to have changed spans.

     * 

     * @param aFocusPosition The required thumb position.

     */     

    IMPORT_C void SetVFocusPosToThumbPos(TInt aFocusPosition);

    /**

     * Returns the breadth of the scroll bar idenitified by @c aOrientation, or

     * zero if none exists.

     *

     * @param  aOrientation The orientation of the scroll bar for which you wish

     *         to obtain the breadth.

     *

     * @return The specified scroll bar's breadth. This is zero if none exists.

     */     

    IMPORT_C TInt ScrollBarBreadth(

        CEikScrollBar::TOrientation aOrientation) const;

    // scroll bar frame behavior functions

    /**

     * Not implemented.

     *

     * @param aAdjusts Not used. 

     */     

    IMPORT_C void SetAdjustsHorizontalModel(TBool aAdjusts); 

    /**

     * Not implemented.

     *

     * @param aAdjusts Not used. 

     */      

    IMPORT_C void SetAdjustsVerticalModel(TBool aAdjusts);

    /**

     * Sets scrollbar frame flags. 

     *

     * @param aMask Bitmask of the bits that are to be set.

     */     

    inline void SetScrollBarFrameFlags(TInt aMask);

    /**

     * Determines whether the scroll bar specified by aOrientation exists

     * 

     * @param aOrientation The scroll bar’s orientation.

     * @return @c ETrue if the specified scroll bar exists otherwise @c EFalse.

     */     

    IMPORT_C TBool ScrollBarExists(

        CEikScrollBar::TOrientation aOrientation) const;

    /**

     * From @c CCoeControl

     *

     * Gets the number of controls contained in a compound control.

     * 

     * @return The number of component controls contained in this control.

     */     

    IMPORT_C TInt CountComponentControls() const;

    /**

     * From @c CCoeControl

     *

     * Gets the component specified by index. Within a compound control, each

     * component control is identified by an index, where the index depends on

     * the order the controls were added: the first is given an index of 0, the

     * next an index of 1, and so on.

     * 

     * @return The component control with an index of aIndex

     */         

    IMPORT_C CCoeControl* ComponentControl(TInt aIndex) const;

    /**

     * Returns a pointer to the scroll bar identified by orientation @c 

     * aOrientation.

     * 

     * @param aOrientation The orientation of the scroll bar for which you wish

     *        to obtain a pointer.

     * @return A pointer to the scroll bar with orientation @c aOrientation if 

     *         the scrollbar is visible.

     */         

    IMPORT_C CEikScrollBar* GetScrollBarHandle(

        CEikScrollBar::TOrientation aOrientation) const;

    /**

     * Returns a pointer to the vertical scroll bar.

     * 

     * @return A pointer to the vertical scroll bar.

     */         

    IMPORT_C CEikScrollBar* VerticalScrollBar() const;

    /**

     * Sets the type of horizontal scroll bar. Possible values are @c EArrowHead

     * and @c EDoubleSpan.

     *

     * @param aType Type of the scrollbar. 

     */         

    IMPORT_C void SetTypeOfHScrollBar(TScrollBarType aType);

    /**

     * Sets the type of vertical scroll bar. Possible values are @c EArrowHead

     * and @c EDoubleSpan.

     *

     * @param aType Type of the scrollbar. 

     */         

    IMPORT_C void SetTypeOfVScrollBar(TScrollBarType aType);

    /**

     * Returns the control type of the horizontal scroll bar 

     * 

     * @return Type of the scrollbar.

     */         

    IMPORT_C TScrollBarType TypeOfHScrollBar() const;

    /**

     * Returns the control type of the vertical scroll bar 

     * 

     * @return Type of the scrollbar.

     */         

    IMPORT_C TScrollBarType TypeOfVScrollBar() const;

    /**

     * Checks if the vertical scrollbar type is @c EArrowHead.

     *

     * @param aFlag Not used.

     * @return @c ETrue if the type of the scrollbar is @c EArrowHead.

     */         

    IMPORT_C TBool IsArrowHeadScrollBar(TInt aFlag) const;

    // application scroll bar utilities