EIKLBX.H

00001 /*
00002 * ============================================================================
00003 *  Name        : EIKLBX.H
00004 *  Part of     : UI Framework Core / EIKON Concrete Controls
00005 *  Description : Base class for an on-screen list box control from
00006 *                which one or more items can be selected.
00007 *  Version     : %version: 12.1.6.1.1 %
00008 *
00009 *  Copyright © 2002-2009 Nokia.  All rights reserved.
00010 *  This material, including documentation and any related computer
00011 *  programs, is protected by copyright controlled by Nokia.  All
00012 *  rights are reserved.  Copying, including reproducing, storing,
00013 *  adapting or translating, any or all of this material requires the
00014 *  prior written consent of Nokia.  This material also contains
00015 *  confidential information which may not be disclosed to others
00016 *  without the prior written consent of Nokia.
00017 * ============================================================================
00018 */
00020 #ifndef __EIKLBX_H__
00021 #define __EIKLBX_H__
00022 
00023 //  INCLUDES 
00024 #include <gdi.h>
00025 #include <eikbctrl.h>
00026 #include <eiklbo.h>
00027 #include <eiksbfrm.h>
00028 #include <eiklbm.h>
00029 #include <eiklbv.h>
00030 #include <gulbordr.h>
00031 #include <eiklbed.h>
00032 #include <gulutil.h>
00033 #include <lafpublc.h>
00035 //  FORWARD DECLARATIONS
00036 enum TKeyCode;
00037 class RIncrMatcherBase;
00038 class CListItemDrawer;
00039 class CEikScrollBarFrame;
00040 class CEikButtonBase;
00041 class CMatchBuffer;
00042 class CListBoxExt;
00043 class CEikListBox;
00045 //  CLASS DECLARATION
00055 class MListBoxItemChangeObserver
00056     {
00057     public:
00063         virtual void ListBoxItemsChanged(CEikListBox* aListBox) = 0;
00064     };
00075 class MListBoxSelectionObserver
00076     {
00077     public:
00085         virtual void SelectionModeChanged(CEikListBox* aListBox, TBool aSelectionModeEnabled) = 0;
00086     };
00089 // CLASS DECLARATION
00110 class CEikListBox : public CEikBorderedControl, public MEikScrollBarObserver
00111     {
00113 public:
00115     friend class CListBoxExt;
00117 public:
00122     enum TFlags
00123         {
EMultipleSelection          = SLafListBox::EMultipleSelection,
ENoExtendedSelection        = SLafListBox::ENoExtendedSelection,
EIncrementalMatching        = SLafListBox::EIncrementalMatching,
EPopout                     = SLafListBox::EPopout,
ELeftDownInViewRect         = SLafListBox::ELeftDownInViewRect,
EItemDoubleClicked          = SLafListBox::EItemDoubleClicked,
EKeepModel                  = SLafListBox::EKeepModel,
EScrollBarSizeExcluded      = SLafListBox::EScrollBarSizeExcluded,
EStateChanged               = SLafListBox::EStateChanged,
ECreateOwnWindow            = SLafListBox::ECreateOwnWindow,
ENoFirstLetterMatching      = SLafListBox::ENoFirstLetterMatching,
EPaintedSelection           = SLafListBox::EPaintedSelection ,
ELoopScrolling = 0x1000,
EEnterMarks = 0x2000,       // Avkon multiselection list
EShiftEnterMarks = 0x4000,  // Avkon markable list
EViewerFlag = 0x8000,       // combined the two flags to fit to WORD.
EPageAtOnceScrolling = 0x8000, // Avkon viewers
EDisableHighlight = 0x8000,  // Avkon viewers       
ES60StyleMultiselection     = SLafListBox::ES60StyleMultiselection,   
ES60StyleMarkable           = SLafListBox::ES60StyleMarkable
00241         };
00242     enum {KEikMaxMatchingBufferLength = 2};
00247     enum TScrollBarOwnerShip
00248         {
ENotOwnedExternally=0x0000,
EOwnedExternally   =0x0001
00257         };
00259 protected:
00264     enum TReasonForFocusLost
00265         { 
EFocusLostToExternalControl, 
EFocusLostToInternalEditor 
00274         };
00276 public:
00280     IMPORT_C ~CEikListBox();
00285     IMPORT_C CEikListBox();
00298     IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,
CListItemDrawer* aListItemDrawer,
00300                              const CCoeControl* aParent,
00301                              TInt aFlags = 0);
00318     IMPORT_C void ConstructL(MListBoxModel* aListBoxModel,
CListItemDrawer* aListItemDrawer,
00320                              const CCoeControl* aParent, 
00321                              TGulBorder aBorder, 
00322                              TInt aFlags = 0);
00332     IMPORT_C virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,
00333                                                  TEventCode aType);
00341     IMPORT_C virtual void HandlePointerEventL(
00342                             const TPointerEvent& aPointerEvent);
00350     IMPORT_C virtual void SetContainerWindowL(const CCoeControl& aContainer);
00357     IMPORT_C virtual TSize MinimumSize();
00365     IMPORT_C virtual void SetDimmed(TBool aDimmed);
00373     IMPORT_C virtual void HandleScrollEventL(CEikScrollBar* aScrollBar, 
TEikScrollEvent aEventType);
00376     // model/view access functions 
00382     IMPORT_C MListBoxModel* Model() const;
00389     IMPORT_C CListBoxView* View() const;
00391     // functions for accessing top/current/bottom item index
00397     IMPORT_C TInt TopItemIndex() const;
00404     IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
00411     IMPORT_C TInt BottomItemIndex() const;
00418     IMPORT_C TInt CurrentItemIndex() const;   
00427     IMPORT_C void SetCurrentItemIndex(TInt aItemIndex) const;
00435     IMPORT_C void SetCurrentItemIndexAndDraw(TInt aItemIndex) const;
00437     // functions for dealing with the selection state
00443     IMPORT_C const CListBoxView::CSelectionIndexArray* SelectionIndexes() const;
00451     IMPORT_C void SetSelectionIndexesL(
CListBoxView::CSelectionIndexArray* aArrayOfSelectionIndexes);
00457     IMPORT_C void ClearSelection(); 
00459     // Functions for updating a list box's internal state after its model has
00460     // been updated, all of them will emit item change event to item change
00461     // observers.
00465     IMPORT_C void HandleItemAdditionL();
00470     IMPORT_C void HandleItemRemovalL();
00481     IMPORT_C void HandleItemAdditionL(
00482                     CArrayFix<TInt> &aArrayOfNewIndexesAfterAddition);
00493     IMPORT_C void HandleItemRemovalL(
00494                     CArrayFix<TInt> &aArrayOfOldIndexesBeforeRemoval);
00499     IMPORT_C void Reset();
00508     IMPORT_C void AddItemChangeObserverL( MListBoxItemChangeObserver* aObserver );
00517     IMPORT_C TBool RemoveItemChangeObserver( MListBoxItemChangeObserver* aObserver );
00519     // functions for accessing the item height
00525     IMPORT_C virtual void SetItemHeightL(TInt aHeight);
00532     IMPORT_C TInt ItemHeight() const;
00534     // functions for scrollbars
00542     IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc=EFalse);
00551     IMPORT_C void SetScrollBarFrame(CEikScrollBarFrame* aScrollBarFrame, TScrollBarOwnerShip aOwnerShip);
00558     IMPORT_C CEikScrollBarFrame* const ScrollBarFrame();
00563     IMPORT_C virtual void UpdateScrollBarsL();
00565     // construction support functions
00575     IMPORT_C void CalculatePopoutRect( TInt aTargetItemIndex,
00576                                        TInt aTargetYPos,
00577                                        TRect& aListBoxRect,
00578                                        TInt aMinHeightInNumOfItems = 1 );
00592     IMPORT_C TSize CalcSizeInPixels(TInt aWidthAsNumOfChars, 
00593                                     TInt aHeightAsNumOfItems) const;
00605     IMPORT_C TInt CalcWidthBasedOnNumOfChars(TInt aNumOfChars) const;
00616     IMPORT_C TInt CalcHeightBasedOnNumOfItems(TInt aNumOfItems) const;
00629     IMPORT_C TInt CalcWidthBasedOnRequiredItemWidth(
00630                                 TInt aTextWidthInPixels) const;
00632     // drawing/scrolling functions
00640     IMPORT_C void DrawItem(TInt aItemIndex) const;
00647     IMPORT_C void ScrollToMakeItemVisible(TInt aItemIndex) const;
00654     IMPORT_C void RedrawItem( TInt aItemIndex );
00656     // observer support
00662     IMPORT_C void SetListBoxObserver(MEikListBoxObserver* aObserver);
00671     IMPORT_C TInt VerticalInterItemGap() const;
00673     // popouts only
00680     IMPORT_C void SetLaunchingButton(CEikButtonBase* aButton);
00682     // Editing support
00688     IMPORT_C void SetItemEditor(MEikListBoxEditor* aEditor);
00693     IMPORT_C void ResetItemEditor();
00699     IMPORT_C MEikListBoxEditor* ItemEditor();
00712     IMPORT_C virtual void EditItemL(TInt aMaxLength);
00722     IMPORT_C void StopEditingL(TBool aUpdateModel);
00724     // functions needed for Avkon shortcuts, 
00725     // passing information from one list to another
00732     IMPORT_C virtual TInt ShortcutValueForNextList();
00739     IMPORT_C virtual void SetShortcutValueFromPrevList(TInt aValue);
00741     // pop-up positioning support
00748     IMPORT_C TRect HighlightRect() const;
00753      IMPORT_C TBool BackgroundDrawingSuppressed() const;
00755 public: // from CCoeControl
00766     IMPORT_C virtual void GetColorUseListL(
00767                         CArrayFix<TCoeColorUse>& aColorUseList) const; 
00768                         // not available before Release 005u
00778     IMPORT_C virtual void HandleResourceChange(TInt aType);         
00779                 // not available before Release 005u
00818     IMPORT_C virtual void ActivateL();
00827     IMPORT_C TCoeInputCapabilities InputCapabilities() const;
00829 private:
00833     IMPORT_C void* ExtensionInterface( TUid aInterface );
00835 protected:
00836     // Shortcuts need access to Incremental matching
00837     // The shortcuts will be used inside OfferkeyEventL().
00838     friend class AknListBoxShortCutsImplementation;
00839     // Avkon layout uses SetVerticalMargin, which is protected.
00840     friend class AknListBoxLayouts;
00856     IMPORT_C virtual void FocusChanged(TDrawNow aDrawNow);
00876     IMPORT_C virtual void SizeChanged();
00882     IMPORT_C virtual void HandleViewRectSizeChangeL();
00893     IMPORT_C virtual TInt CountComponentControls() const;
00910     IMPORT_C virtual CCoeControl* ComponentControl(TInt aIndex) const;
00912     // functions that implement first letter and incremental matching
00916     IMPORT_C void CreateMatchBufferL();  
00921     IMPORT_C void ClearMatchBuffer() const;
00928     IMPORT_C void MatchTypedCharL(TUint aCode);
00934     IMPORT_C void UndoLastChar();
00940     IMPORT_C TBool LastCharMatched() const;
00942     // functions needed for supporting scrollbars
00947     IMPORT_C virtual void UpdateScrollBarThumbs() const;
00956     IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
00966     IMPORT_C virtual TInt HorizontalNudgeValue() const;
00975     IMPORT_C virtual void AdjustTopItemIndex() const;
00977     // navigation support functions
00988     IMPORT_C void SimulateArrowKeyEventL(TKeyCode aKeyCode);
00998     IMPORT_C virtual void HandleLeftArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
01008     IMPORT_C virtual void HandleRightArrowKeyL(CListBoxView::TSelectionMode aSelectionMode);
01010     // construction support functions
01018     IMPORT_C void RestoreCommonListBoxPropertiesL(TResourceReader& aReader); 
01030     IMPORT_C virtual void ConstructL(const CCoeControl* aParent, TInt aFlags = 0);
01039     IMPORT_C virtual void CreateViewL();
01051     IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
01059     IMPORT_C void SetViewRectFromClientRect(const TRect& aClientRect);
01072     IMPORT_C virtual void RestoreClientRectFromViewRect( TRect& aClientRect) const;
01081     IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems( TRect& aRect) const;
01083     // accessor for Laf members
01089     IMPORT_C TMargins8 ListBoxMargins() const;
01091     // various accessors for private data members
01100     IMPORT_C TInt HorizontalMargin() const;
01111     IMPORT_C TInt VerticalMargin() const;
01118     IMPORT_C void SetHorizontalMargin(TInt aMargin);
01125     IMPORT_C void SetVerticalMargin(TInt aMargin);
01133     IMPORT_C RIncrMatcherBase* MatchBuffer() const;
01144     IMPORT_C TInt ViewRectHeightAdjustment() const;
01151     IMPORT_C TRgb BackColor() const;
01158     IMPORT_C void SetViewRectHeightAdjustment(TInt aAdjustment);
01160     // misc functions
01168     IMPORT_C virtual void ReportListBoxEventL( MEikListBoxObserver::TListBoxEvent aEvent );
01176     IMPORT_C virtual void Draw(const TRect& aRect) const;
01182     IMPORT_C void ClearMargins() const;
01191     IMPORT_C virtual void UpdateCurrentItem(TInt aItemIndex) const;
01202     IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
01210     IMPORT_C TBool ItemExists(TInt aItemIndex) const;
01227     IMPORT_C void DrawMatcherCursor() const;
01234     IMPORT_C static TInt InterItemGap();
01240     IMPORT_C void UpdateViewColors();
01246     IMPORT_C void UpdateItemDrawerColors();
01255     IMPORT_C void FireItemChange();
01258 protected:      // functions which deal with extension
01267     IMPORT_C void SetReasonForFocusLostL( TReasonForFocusLost aReasonForFocusLost );
01274     IMPORT_C TReasonForFocusLost ReasonForFocusLostL();
01282     IMPORT_C TBool IsMatchBuffer() const;
01289     void CheckCreateExtensionL();
01300     TBool CheckCreateExtension();
01306     void CheckCreateBufferL();
01313     CMatchBuffer* Buffer() const;
01315 protected:
01321     IMPORT_C void CreateScrollBarFrameLayout(TEikScrollBarFrameLayout& aLayout) const;
01327     void UpdateMarkUnmarkMSKL() const;
01329 public:
01333     IMPORT_C TInt EventModifiers();
01335     /* 
01336     * Returns ETrue if list has ES60StyleMultiselection flag. 
01337     */
01338     IMPORT_C TBool IsMultiselection();
01352     IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote);
01369     IMPORT_C CEikScrollBarFrame* CreateScrollBarFrameL(TBool aPreAlloc, TBool aRemote, TBool aWindowOwning);
01381     IMPORT_C void EnableMSKObserver(TBool aEnable);
01388     void DoShiftMSKMarkingL();
01396     void InformMSKButtonGroupDeletion();
01405     IMPORT_C void AddSelectionObserverL( MListBoxSelectionObserver* aObserver );
01413     IMPORT_C void RemoveSelectionObserver( MListBoxSelectionObserver* aObserver );
01422     void ChangeSelectionMode(TBool aEnable);
01430     IMPORT_C void SetItemsInSingleLine(TInt aItems);
01442     IMPORT_C void SetPointerEventFilterDisabledL( const CArrayFix<TInt>& aItemIndexes );
01454     IMPORT_C void HandlePhysicsScrollEventL( TInt aDeltaPixels );
01464     IMPORT_C void DisableScrolling( TBool aDisabled );
01466 private:
01467     IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
01468     void HorizontalScroll(TInt aScrollAmountInPixels);
01469     void DrawItemInView(TInt aItemIndex) const;
01470     void ClearMargins(CWindowGc& aGc) const;
01471     TKeyResponse DoOfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
01472     void UpdateScrollBarColors(CEikScrollBar* aScrollBar);
01473     void UpdateScrollBarsColors();
01475     void HandleItemRemovalWithoutSelectionsL();
01477 protected:
01479     TInt iListBoxFlags;
01482     CListBoxView* iView;
01485     CListItemDrawer* iItemDrawer;
01488     MListBoxModel* iModel;
01491     TInt iItemHeight;   
01494     CEikScrollBarFrame* iSBFrame;
01497     TScrollBarOwnerShip iSBFrameOwned;
01502     TInt iRequiredHeightInNumOfItems;
01507     CEikButtonBase* iLaunchingButton; // only used by popouts
01510     MEikListBoxObserver* iListBoxObserver;
01512 private:
01514     TRgb iBackColor;
01515 //  TInt iHorizontalMargin;
01516 //  TInt iVerticalMargin;
01517     TMargins8 iMargins ;
CListBoxExt* iListBoxExt;
01519     TInt iViewRectHeightAdjustment;
MEikListBoxEditor* iItemEditor;
01521     TBool* iLbxDestroyed;
01522     TBool iLastCharMatched;
01523     TInt iSpare;
01524     };
01542 class CEikSnakingListBox : public CEikListBox  
01543     {
01544 public:
01548     IMPORT_C CEikSnakingListBox();
01553     IMPORT_C ~CEikSnakingListBox();
01567     IMPORT_C virtual CListBoxView* MakeViewClassInstanceL();
01574     IMPORT_C virtual void SetTopItemIndex(TInt aItemIndex) const;
01581     IMPORT_C TInt ColumnWidth() const;
01588     IMPORT_C void SetColumnWidth(TInt aColumnWidth);
01590 public: //from CCoeControl
01599     IMPORT_C void HandlePointerEventL(const TPointerEvent& aPointerEvent);
01601 protected:
01611     IMPORT_C virtual void HandleViewRectSizeChangeL();
01621     IMPORT_C virtual void HandleLeftArrowKeyL(
CListBoxView::TSelectionMode aSelectionMode);
01632     IMPORT_C virtual void HandleRightArrowKeyL(
CListBoxView::TSelectionMode aSelectionMode);
01644     IMPORT_C virtual TInt HorizontalNudgeValue() const;
01654     IMPORT_C virtual TInt HorizScrollGranularityInPixels() const;
01663     IMPORT_C virtual void AdjustTopItemIndex() const;
01674     IMPORT_C virtual void HandleDragEventL(TPoint aPointerPos);
01687     IMPORT_C virtual void RestoreClientRectFromViewRect(
01688                                                     TRect& aClientRect) const;
01697     IMPORT_C virtual TInt AdjustRectHeightToWholeNumberOfItems(
01698                                                         TRect& aRect) const;
01705     IMPORT_C void MoveToNextOrPreviousItemL(TPoint aPoint);
01707 protected: //from CCoeControl
01715     IMPORT_C virtual void SizeChanged();
01726     IMPORT_C virtual void GetColorUseListL(
01727                     CArrayFix<TCoeColorUse>& aColorUseList) const; 
01728                     // not available before Release 005u
01737     IMPORT_C virtual void HandleResourceChange(TInt aType);         
01738                     // not available before Release 005u
01740 private: // from CCoeControl
01741     IMPORT_C void Reserved_1();
01743     IMPORT_C void Reserved_2();
01745 private:
01749     IMPORT_C void* ExtensionInterface( TUid aInterface );
01751 private:
01752     IMPORT_C virtual void CEikListBox_Reserved(); // listbox use only
01753     };
01755 #endif  // __EIKLBX_H__