1 /*

     2 * Copyright (c) 2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:     

    15 *

    16 */

    17 

    18 

    19 #ifndef HGSCROLLER_H_

    20 #define HGSCROLLER_H_

    21 

    22 // INCLUDES

    23 #include <coecntrl.h>

    24 #include <coemain.h>

    25 

    26 #include <aknphysicsobserveriface.h>

    27 #include <aknlongtapdetector.h>

    28 #include <akncollection.h>

    29 #include <ganes/HgBufferOwnerIface.h>

    30 #include <ganes/HgScrollbarObserverIface.h>

    31 

    32 // FORWARD DECLARATIONS

    33 class CAknPhysics;

    34 class MHgScrollBufferObserver;

    35 class MHgSelectionObserver;

    36 class MHgMarkingObserver;

    37 class CHgItem;

    38 class CHgScrollbar;

    39 class CGulIcon;

    40 class CHgScrollBufferManager;

    41 class THgPopupDrawer;

    42 class CHgIndicatorManager;

    43 class CHgDrawUtils;

    44 class CHgKeyUtils;

    45 class CHgTextFind;

    46 class CAknItemActionMenu;

    47 

    48 // CLASS DECLARATION

    49 class CHgScroller : 

    50     public CCoeControl, 

    51     public MHgBufferOwner,

    52     public MHgScrollbarObserver,

    53     public MCoeForegroundObserver,

    54     public MAknPhysicsObserver,

    55     public MAknLongTapDetectorCallBack,

    56     public MAknCollection

    57     {

    58 public:

    59     

    60     // Flags that define possible scroller modes

    61     enum THgScrollerMode

    62         {

    63         EHgScrollerSelectionMode = 0x0001,

    64         EHgScrollerSearchWithQWERTY = 0x0002,

    65         EHgScrollerKeyMarkingDisabled = 0x0004,

    66         EHgScrollerScreenFreeze = 0x0008,

    67         EHgScrollerForceDoubleClick = 0x0010,

    68         EHgScrollerFlatStatusPane = 0x0020

    69         };

    70 

    71     // Scrollbar types

    72     enum THgScrollBarType

    73         {

    74         EHgScrollerScrollBar = 0,

    75         EHgScrollerLetterStrip,

    76         EHgScrollerTimeStrip,

    77         EHgScrollerLetterStripLite

    78         };

    79     

    80 public: // Destructor.

    81     IMPORT_C virtual ~CHgScroller();

    82     

    83 public: // CCoeControl

    84     void Draw(const TRect& aRect ) const;

    85     void SizeChanged();

    86     void HandlePointerEventL( const TPointerEvent& aEvent );

    87     TKeyResponse OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType );

    88     virtual TCoeInputCapabilities InputCapabilities() const;

    89     virtual void FocusChanged(TDrawNow aDrawNow);

    90     virtual void HandleResourceChange(TInt aType);

    91 

    92 protected: // MAknPhysicsObserver

    93     void ViewPositionChanged( const TPoint& aNewPosition,

    94                                   TBool aDrawNow,

    95                                   TUint aFlags );

    96     void PhysicEmulationEnded();

    97     TPoint ViewPosition() const;

    98     

    99 private: // MHgBufferOwner

   100     void Release(TInt aReleaseStart, TInt aReleaseEnd);

   101 

   102 private: // MHgScrollbarObserver

   103     void ScrollBarPositionChanged( const TPoint& aNewPosition );

   104     void HandleNaviStripChar( const TChar& aChar );

   105 

   106 protected: // MAknLongTapDetectorCallBack

   107     void HandleLongTapEventL( const TPoint& aPenEventLocation,

   108                             const TPoint& aPenEventScreenLocation);

   109     

   110 protected: // MAknCollection

   111     TUint CollectionState() const;

   112     void ItemActionMenuClosed();

   113     TInt CollectionExtension( TUint aExtensionId, TAny*& a0, TAny* a1 );

   114 

   115 public: // NEW FUNCTIONS

   116     /**

   117      * Re-inits the grid display area. DSA version.

   118      * 

   119      * @param aRect New display rect

   120      * @param aSession Window server session for DSA

   121      */

   122     IMPORT_C void InitScreenL( const TRect& aRect, RWsSession& aSession );

   123     

   124     /**

   125      * Re-inits the grid display area. Non-DSA version.

   126      * 

   127      * @param aRect New display rect

   128      */

   129     IMPORT_C void InitScreenL( const TRect& aRect );

   130     

   131     /**

   132      * Refreshes screen.

   133      * @param aIndex Index that was modified.

   134      */

   135     IMPORT_C void RefreshScreen( TInt aIndex );

   136 

   137     /**

   138      * Gives the first index on the screen.

   139      * 

   140      * Note: The index is not guaranteed to be in the range of the scroller items.

   141      * Index can be negative if the scroller is scrolled to the way up or 

   142      * over the count - 1 if scrolled way down.   

   143      * 

   144      * @return The index of the first item on the screen. 

   145      */

   146     IMPORT_C TInt FirstIndexOnScreen();

   147     

   148     /**

   149      * How many items fit on one screen. 

   150      * @return Item count.

   151      */

   152     IMPORT_C TInt ItemsOnScreen();

   153     

   154     /**

   155      * Get item at specified index.

   156      * 

   157      * @param aIndex Index of the item that is returned

   158      * @return Reference to item.

   159      */

   160     IMPORT_C CHgItem& ItemL( TInt aIndex );

   161     

   162     /**

   163      * Resets item at the index position. Old item is deleted.

   164      * 

   165      * @param aItem New item. Ownership transferred.

   166      * @param aIndex The index of the item.

   167      */

   168     IMPORT_C void SetItem(CHgItem* aItem, TInt aIndex);

   169 

   170     /**

   171      * Adds Item.

   172      * 

   173      * @param aItem New item. Ownership transferred.

   174      */

   175     IMPORT_C void AddItem(CHgItem* aItem);

   176 

   177     /**

   178      * Inserts item at index postion.

   179      * 

   180      * @param aItem New item. Ownership transferred.

   181      * @param aIndex The index of the item.

   182      */

   183     IMPORT_C void InsertItem(CHgItem* aItem, TInt aIndex);

   184 

   185     /**

   186      * Removes item at index position. Removed item is deleted.

   187      * 

   188      * @param aIndex The index of the item.

   189      */

   190     IMPORT_C void RemoveItem(TInt aIndex);

   191 

   192     /**

   193      * @return Selected index (KErrNotFound if nothing is selected)

   194      */

   195     IMPORT_C TInt SelectedIndex();

   196 

   197     /**

   198      * Sets selected index.

   199      * @param aIndex new selected index. Selection is also made visible.

   200      */

   201     IMPORT_C void SetSelectedIndex( TInt aIndex );

   202     

   203     /**

   204      * Marks item at index position.

   205      * @param aIndex Index of the item that is marked.

   206      */

   207     IMPORT_C void Mark( TInt aIndex );

   208 

   209     /**

   210      * Unmarks item at index position.

   211      * @param aIndex Index of the item that is unmarked.

   212      */

   213     IMPORT_C void UnMark( TInt aIndex );

   214     

   215     /**

   216      * Marks all items.

   217      */

   218     IMPORT_C void MarkAll();

   219 

   220     /**

   221      * Unmarks all items.

   222      */

   223     IMPORT_C void UnMarkAll();

   224     

   225     /**

   226      * Gets all marked item indexes.

   227      * @param aIndexes On return contains the indexes of marked items.

   228      */

   229     IMPORT_C void GetMarkedItemsL( RArray<TInt>& aIndexes );

   230     

   231     /**

   232      * Enables Buffering.

   233      * @param aObserver Buffer change observer.

   234      * @param aBufferSize The size of the buffer.

   235      * @param aBufferTreshold The minimum change needed for buffer to be modified.

   236      */

   237     IMPORT_C void EnableScrollBufferL( MHgScrollBufferObserver& aObserver, 

   238             TInt aBufferSize,

   239             TInt aBufferTreshold );

   240     

   241     /**

   242      * Sets selection observer.

   243      * @param aObserver Selection observer.

   244      */

   245     IMPORT_C void SetSelectionObserver( MHgSelectionObserver& aObserver );

   246 

   247     /**

   248      * Sets marking observer.

   249      * @param aObserver marking observer.

   250      */

   251     IMPORT_C void SetMarkingObserver( MHgMarkingObserver& aObserver );

   252     

   253     /**

   254      * Removes all items and presents empty text

   255      * */

   256     IMPORT_C void Reset();

   257     

   258     /**

   259      * Resizes Grid/List.

   260      * @param aItemCount New Count of items.

   261      */

   262     IMPORT_C void ResizeL( TInt aItemCount );

   263 

   264     /**

   265      * Set text that is displayed when there are no items in the view.

   266      * @param aEmptyText Empty text.

   267      */

   268     IMPORT_C void SetEmptyTextL( const TDesC& aEmptyText );

   269     

   270     /**

   271      * Fetch item count.

   272      * @return Total number of items.

   273      */

   274     IMPORT_C TInt ItemCount() const;

   275     

   276     /**

   277      * Set scrollbar type.

   278      * @param aType ScrollBar type

   279      */

   280     IMPORT_C void SetScrollBarTypeL( THgScrollBarType aType );

   281     

   282     /**

   283      * Set mode flags. Possible values are defined in THgScrollerMode.

   284      * @param aFlags flags to bet set.

   285      */

   286     IMPORT_C void SetFlags( TInt aFlags );

   287     

   288     /**

   289      * Clear mode flags. Possible values are defined in THgScrollerMode.

   290      * @param aFlags flags to be cleared.

   291      */

   292     IMPORT_C void ClearFlags( TInt aFlags );

   293     

   294     /**

   295      * Get flags. Possible values are defined in THgScrollerMode.

   296      * @return Current flags.

   297      */

   298     IMPORT_C TInt Flags();

   299     

   300     /**

   301      * Highlights item based on the descriptor given.

   302      * @param aHighlightText Text to be searched.

   303      * @return Was aHighlightText found.

   304      */

   305     IMPORT_C TBool HightlightItem( const TDesC& aHighlightText );

   306     

   307     /**

   308      * Sets new default icon.

   309      * @param aDefaultIcon New default icon to be used in scroller.

   310      */

   311     IMPORT_C void SetDefaultIconL( CGulIcon* aDefaultIcon );

   312     

   313     /**

   314      * Disables Scrollbuffer.

   315      */

   316     IMPORT_C void DisableScrollBuffer();

   317 

   318     // Selection modes. Used in internal key marking implemention.

   319     enum TSelectionMode

   320         {

   321         ENoSelection = 0,

   322         ESelectionPossible,

   323         ESelectionMark,

   324         ESelectionUnMark

   325         };

   326     

   327     /**

   328      * Set selection mode. Used in internal key marking implemention.

   329      * @param aMode New selection mode.

   330      */

   331     void SetSelectionMode( TSelectionMode aMode );

   332     

   333     /**

   334      * Get current selection mode. Used in internal key marking implemention.

   335      * @return Current selection mode.

   336      */

   337     TSelectionMode SelectionMode() const;

   338     

   339 protected: // Pure Virtual Functions

   340     virtual TInt GetSelected( TPoint aPosition ) const = 0;

   341     virtual void HandleSizeChanged() = 0;

   342     virtual void InitItemsL() = 0;

   343     virtual TSize TotalSize() const = 0;

   344     virtual void DoDraw( const TRect& aRect ) const = 0;

   345     virtual TBool DoHandleKeyEvent( const TKeyEvent& aKeyEvent ) = 0;

   346     virtual void FitSelectionToView() = 0;

   347     virtual TInt CurrentIndex() = 0;

   348     virtual TBool IsDisplayed( TInt aIndex ) = 0;

   349     virtual void FitTopItemToView( TInt aIndex ) = 0;

   350     

   351 protected: // Constructors

   352     CHgScroller( TInt aItemCount, 

   353             CGulIcon* aDefaultIcon );

   354 

   355     void ConstructL (const TRect& aRect, RWsSession* aSession );

   356     

   357 protected:

   358     void InitPhysicsL();

   359     virtual void HandleViewPositionChanged( TBool aUpdateScrollbar = ETrue );

   360     void InitDrawBuffer() const;

   361     void SelectionChanged();

   362     void FitRowToView( TInt aRow );

   363     TBool HasHighlight() const;

   364     static TInt MarqueeCallback( TAny* aSelf );

   365 

   366 private:

   367     TKeyResponse HandleKeyEvent(const TKeyEvent& aKeyEvent);

   368     

   369     void HandleItemCountChanged();

   370     void HandleSelectionL();

   371 

   372     TBool HandleScrollbarEventL( const TPointerEvent& aEvent );

   373     void HandleDownEventL( const TPointerEvent& aEvent );

   374     void HandleDragEventL( const TPointerEvent& aEvent );

   375     void HandleUpEventL( const TPointerEvent& aEvent );

   376     

   377     void KeyEventDown();

   378     void KeyEventUp();

   379     

   380     void InitGraphicsL();

   381     void InitScrollbarL();

   382 

   383     void HandleGainingForeground();

   384     void HandleLosingForeground();

   385     

   386     /**

   387      * Launches the highlight timer.

   388      */

   389     void LaunchHighlightTimer();

   390 

   391     /**

   392      * Callback method for highlight timer.

   393      *

   394      * @param aPtr Pointer to an instance of CHgScroller class.

   395      *

   396      * @return System wide error code.

   397      */

   398     static TInt HighlightTimerCallback( TAny* aPtr );

   399         

   400     /**

   401      * Sets highlight to focused item.

   402      */

   403     void SetHighlightL();

   404 

   405     /**

   406      * Callback method for key scrolling timer.

   407      *

   408      * @param aPtr Pointer to an instance of CHgScroller class.

   409      *

   410      * @return System wide error code.

   411      */

   412     static TInt KeyScrollingTimerCallback( TAny* aPtr );

   413         

   414     /**

   415      * Move view based on key scolling mode.

   416      */

   417     void DoKeyScrolling();

   418     

   419     /**

   420      * Sets item highlight and stops the scrolling timer.

   421      */

   422     void StopKeyScrolling();

   423     

   424 protected:

   425     CAknPhysics* iPhysics; // Physics engine. Own

   426     CHgScrollBufferManager* iManager; // Own

   427     CHgScrollbar* iScrollbar; // Scrollbar. Own

   428     CHgIndicatorManager* iIndicatorManager; // Utility for drawing indicators. Own

   429     CHgDrawUtils* iDrawUtils; // Drawing utility. Own

   430     CHgTextFind* iTextFind; // Text find utility to communicate with FEP. Own

   431     CAknLongTapDetector* iDetector; // Longtap detector for single click. Own

   432     CAknItemActionMenu* iActionMenu; // Item action menu for single click. Not Own

   433     

   434     // Observers

   435     MHgSelectionObserver* iSelectionObserver; // Not Own

   436     MHgMarkingObserver* iMarkingObserver; // Not Own

   437     

   438     // Arrays

   439     RPointerArray<CHgItem> iItems; // Items

   440 

   441     // For dragging

   442     TPoint iStart; // Drag start position

   443     TTime iStartTime; // Drag start time

   444     TPoint iPrev; // Previous pointer event position.

   445 

   446     // The Rest.

   447     CGulIcon* iDefaultIcon; // Default item icon

   448         

   449     TPoint iViewPosition; // Current view position

   450     

   451     TBool iLandscapeScrolling; // Scrolling landscape?

   452     

   453     TInt iWidth; // The width of the view

   454     TInt iHeight; // The height of the view

   455     TInt iRowHeight; // Row height (square images)

   456     TInt iItemCount; // Total number of items

   457     TInt iItemsOnScreen;

   458     

   459     TInt iCurrentRow; // The number of the first row that is drawn

   460     TInt iSelectedIndex; // The index of the selected item

   461 

   462     TInt iKeyRepeats; // How many key repeasts have been received

   463     

   464     TSize iImageSize; // Image Size

   465     TSize iIndicatorSize; // Size of the indicator in list or grid

   466     

   467     enum TKeyScrollingState

   468         {

   469         ENoKeyScrolling = 0,

   470         EKeyScrollingUp,

   471         EKeyScrollingDown,

   472         EKeyScrollingLeft,

   473         EKeyScrollingRight

   474         } iKeyScrollingState; // State of the key scrolling

   475 

   476     TInt iFlags; // Possible mode flags

   477     

   478     HBufC* iEmptyText; // text for empty list or grid.

   479 

   480     THgPopupDrawer* iPopupDrawer;

   481     TBool iPanning;

   482     TBool iShowHighlight;

   483     

   484     THgScrollBarType iScrollBarType; // Scrollbar type

   485     

   486     RBuf iUpperCaseTitle; // Used in search for uppercase conversion

   487     RBuf iPopupText1;

   488     RBuf iPopupText2;

   489     

   490     TBool iFirstTime; // Flag to indicating first time run.

   491     TBool iPointerDown;

   492 

   493     CPeriodic* iHighlightTimer; // Higlight timer, own.

   494     TBool iSelectionToFocusedItem; // Is focused item clicked

   495     TInt iFocusedIndex; // highlight timer updates this value

   496     

   497     CHgKeyUtils* iKeyUtils; // MSK key handler, own

   498     

   499     TSelectionMode iSelectionMode;

   500     

   501     CPeriodic* iKeyScrollingTimer; // Timer for key scrolling, own.

   502     };

   503 

   504 #endif /*HGSCROLLER_H_*/